basaltbytes · PhilDL · Aug 23, 2026 · Aug 23, 2026
diff --git a/.changeset/plain-diagnostics.md b/.changeset/plain-diagnostics.md
@@ -0,0 +1,5 @@
+---
+"balade": patch
+---
+
+Reword `balade check` diagnostics in plain language. Messages now say what is wrong directly ("`matrix` contains no table", "Text outside a section is ignored", "Lines 3-9 are out of range: `f` has 5 lines") instead of describing the compiler's internals. Diagnostic codes are unchanged.
diff --git a/src/server/api.ts b/src/server/api.ts
@@ -300,7 +300,7 @@ export function apiErrorResponse(error: ApiError): ApiErrorResponse {
     }),
     ApiReviewStateMismatch: ({ statePath, requestPath }): ApiErrorResponse => ({
       status: 400,
-      message: `The body names \`${statePath}\`, but the request names \`${requestPath}\`.`,
+      message: `The body is for \`${statePath}\`, but the request is for \`${requestPath}\`.`,
     }),
     ApiTargetNotServed: ({ path }): ApiErrorResponse => ({
       status: 404,
@@ -312,7 +312,7 @@ export function apiErrorResponse(error: ApiError): ApiErrorResponse {
     }),
     ApiStampUnreadable: ({ path }): ApiErrorResponse => ({
       status: 404,
-      message: `\`${path}\` carries no readable stamp.`,
+      message: `\`${path}\` has no readable stamp.`,
     }),
     ApiStampUnresolvable: ({ pin }): ApiErrorResponse => ({
       status: 404,

diff --git a/src/walkthrough/blocks.ts b/src/walkthrough/blocks.ts
@@ -115,7 +115,7 @@ export function compileBlocks(
         level: "warning",
         file: env.file,
         line: lineOf(fence),
-        message: "A fenced code block reaches the payload only at a section's top level.",
+        message: "Fenced code blocks are only supported at the top level of a section.",
         hint: "Move the fence out of the blockquote or list. A ```mermaid fence renders as a diagram; any other fence renders as read-only text.",
       });
     }
@@ -177,8 +177,8 @@ function compileTag(node: Node, env: CompileEnv, sectionId: string): Block[] {
       level: "error",
       file: env.file,
       line: lineOf(node),
-      message: `The tag \`${tag}\` cannot stand on its own.`,
-      hint: `Put it inside its parent tag, as \`field\` goes inside \`fields\`.`,
+      message: `The tag \`${tag}\` must be inside a parent tag.`,
+      hint: `Put it inside its parent tag (for example \`field\` inside \`fields\`).`,
     });
     return [];
   }
@@ -278,7 +278,7 @@ function childTags(node: Node, family: string, env: CompileEnv): Node[] {
       level: "error",
       file: env.file,
       line: lineOf(child),
-      message: `\`${family}\` cannot hold a \`${tag}\` tag.`,
+      message: `\`${tag}\` is not allowed inside \`${family}\`.`,
       hint: `Use ${allowed.map((name) => `\`${name}\``).join(" or ")} inside \`${family}\`.`,
     });
   }
@@ -417,7 +417,7 @@ function matrixBlock(node: Node, env: CompileEnv): Block {
       level: "error",
       file: env.file,
       line: lineOf(node),
-      message: "`matrix` holds no table.",
+      message: "`matrix` contains no table.",
       hint: "Put a markdown table inside `matrix` — the first column is the row label.",
     });
     return { b: "matrix", head: [], rows: [] };
@@ -486,8 +486,8 @@ function filesBlock(node: Node, env: CompileEnv, sectionId: string): Block {
         level: "warning",
         file: env.file,
         line: lineOf(child),
-        message: `The \`filegroup\` \`${label}\` claims no file this list still holds.`,
-        hint: `Check the filter: ${childFilter.text}. Earlier groups claim first; statuses are ${FILE_STATUSES.join(", ")}.`,
+        message: `The \`filegroup\` \`${label}\` matches no file.`,
+        hint: `Check the filter: ${childFilter.text}. Files already taken by an earlier \`filegroup\` are not available again. Statuses are ${FILE_STATUSES.join(", ")}.`,
       });
     }
   }
@@ -510,8 +510,8 @@ function filesBlock(node: Node, env: CompileEnv, sectionId: string): Block {
         level: "error",
         file: env.file,
         line: lineOf(node),
-        message: `\`why\` names \`${path}\`, which this file list does not hold.`,
-        hint: "Name a path the PR changed, and keep it inside the `only`/`status` filter.",
+        message: `\`why\` references \`${path}\`, which is not in this file list.`,
+        hint: "Use a path the PR changed that also matches the `only`/`status` filter.",
       });
       continue;
     }
@@ -577,7 +577,7 @@ function codeBlock(node: Node, env: CompileEnv, sectionId: string): Block[] {
       file: env.file,
       line,
       message: `\`${file}\` does not exist at the stamped commit ${short(env.ctx.pin)}.`,
-      hint: "Check the path — it is relative to the repository root — or re-stamp the walkthrough against a commit that holds the file.",
+      hint: "Check the path (relative to the repository root), or re-stamp the walkthrough against a commit that contains the file.",
     });
     env.card({
       code: "file-unresolvable",
@@ -601,12 +601,12 @@ function codeBlock(node: Node, env: CompileEnv, sectionId: string): Block[] {
       level: "error",
       file: env.file,
       line,
-      message: `Lines ${from}-${to} fall outside \`${file}\`, which holds ${blob.value.length} lines at ${short(env.ctx.pin)}.`,
+      message: `Lines ${from}-${to} are out of range: \`${file}\` has ${blob.value.length} lines at ${short(env.ctx.pin)}.`,
       hint: `Use a range inside 1-${blob.value.length}.`,
     });
     env.card({
       code: "range-unresolvable",
-      message: `Lines ${from}-${to} fall outside \`${file}\` (${blob.value.length} lines).`,
+      message: `Lines ${from}-${to} are out of range: \`${file}\` has ${blob.value.length} lines.`,
       reference,
       sectionId,
       line,
@@ -635,7 +635,7 @@ function codeBlock(node: Node, env: CompileEnv, sectionId: string): Block[] {
       level: "warning",
       file: env.file,
       line,
-      message: `\`mark\` names ${outside.join(", ")}, outside the range ${from}-${to}.`,
+      message: `\`mark\` lists ${outside.join(", ")}, outside the range ${from}-${to}.`,
       hint: `Mark lines are absolute file line numbers; keep them inside ${from}-${to}.`,
     });
   }
@@ -650,8 +650,8 @@ function codeBlock(node: Node, env: CompileEnv, sectionId: string): Block[] {
       level: "warning",
       file: env.file,
       line,
-      message: `The code reference \`${reference}\` carries no \`expect\`.`,
-      hint: `Add expect="${quoteFragment(first)}" — a literal fragment of line ${from}, so a miscounted range fails loudly.`,
+      message: `The code reference \`${reference}\` has no \`expect\` attribute.`,
+      hint: `Add expect="${quoteFragment(first)}", a literal fragment of line ${from}, so a wrong range is reported as an error.`,
     });
   } else if (first.includes(expected)) {
     expect = { value: expected, status: "ok" };
@@ -662,7 +662,7 @@ function codeBlock(node: Node, env: CompileEnv, sectionId: string): Block[] {
       level: "error",
       file: env.file,
       line,
-      message: `Line ${from} of \`${file}\` does not hold the expected fragment.`,
+      message: `Line ${from} of \`${file}\` does not contain the expected fragment.`,
       hint: "Recount the range, then quote a fragment of its first line.",
       expected,
       actual: first,

diff --git a/src/walkthrough/compiler.ts b/src/walkthrough/compiler.ts
@@ -125,7 +125,7 @@ export function compileDocument(input: CompileInput): CompileResult {
         file: sourcePath,
         line,
         message: `The section id \`${id}\` is already used on line ${first}.`,
-        hint: "Section ids key the review state; give this one its own kebab-case id.",
+        hint: "Section ids identify the review state; give this one a unique kebab-case id.",
       });
     }
     seen.set(id, line);
@@ -150,7 +150,7 @@ export function compileDocument(input: CompileInput): CompileResult {
           file: sourcePath,
           line,
           message: `The section file \`${filePath}\` does not exist at ${short(ctx.pin)}.`,
-          hint: "Use a path relative to the repository root, as git spells it.",
+          hint: "Use a path relative to the repository root, as git reports it.",
         });
         sectionEnv.card({
           code: "file-unresolvable",
@@ -166,7 +166,7 @@ export function compileDocument(input: CompileInput): CompileResult {
           file: sourcePath,
           line,
           message: `The section file \`${filePath}\` is not part of this PR.`,
-          hint: "A file-section marks a changed file; use a plain section for context files.",
+          hint: "A file section is for a changed file; use a plain section for context files.",
         });
       }
     }
@@ -244,8 +244,8 @@ export function compileDocument(input: CompileInput): CompileResult {
           level: "error",
           file: sourcePath,
           line: lineOf(node),
-          message: `The tag \`${node.tag ?? ""}\` sits outside a section.`,
-          hint: "The document body holds sections and groups only; move the tag inside a `section`.",
+          message: `The tag \`${node.tag ?? ""}\` is outside a section.`,
+          hint: "Only sections and groups are allowed at the top level; move the tag inside a `section`.",
         });
         continue;
       }
@@ -255,8 +255,8 @@ export function compileDocument(input: CompileInput): CompileResult {
           level: "warning",
           file: sourcePath,
           line: lineOf(node),
-          message: "Prose outside a section does not reach the payload.",
-          hint: "Move it into a `section`; the document body holds sections and groups only.",
+          message: "Text outside a section is ignored.",
+          hint: "Move it into a `section`; only sections and groups are allowed at the top level.",
         });
       }
     }
@@ -292,7 +292,7 @@ export function compileDocument(input: CompileInput): CompileResult {
       file: sourcePath,
       line: lineOf(openingSection),
       message: 'The first section must be the overview, with `id="overview"`.',
-      hint: "Open the walkthrough with the section that frames the change for the reviewer.",
+      hint: "The first section introduces the change to the reviewer.",
     });
   }
 
@@ -313,8 +313,8 @@ export function compileDocument(input: CompileInput): CompileResult {
       level: "error",
       file: sourcePath,
       line: lineOf(openingSection),
-      message: "The walkthrough must open with a group holding only the overview section.",
-      hint: "Wrap the overview in its own opening group; the thematic groups start after it.",
+      message: "The walkthrough must start with a group containing only the overview section.",
+      hint: "Wrap the overview in its own group; the thematic groups come after it.",
     });
   }
 
@@ -326,7 +326,7 @@ export function compileDocument(input: CompileInput): CompileResult {
           level: "error",
           file: sourcePath,
           line: pending.line,
-          message: `\`related\` names \`${id}\`, which no section in this file defines.`,
+          message: `\`related\` references \`${id}\`, but no section in this file has that id.`,
           hint: "Each `related` entry is a section id; its chip jumps to that section.",
         });
       }
@@ -342,7 +342,7 @@ export function compileDocument(input: CompileInput): CompileResult {
         level: "error",
         file: sourcePath,
         line,
-        message: `The PR head moved ${ctx.headDistance} commit${ctx.headDistance === 1 ? "" : "s"} past the stamp, and it touches ${overlap.join(", ")}.`,
+        message: `The PR head is ${ctx.headDistance} commit${ctx.headDistance === 1 ? "" : "s"} ahead of the stamped commit and changes ${overlap.join(", ")}.`,
         hint: `Re-read the changed files, update the ranges, then re-stamp: commit: ${short(ctx.headSha)}.`,
       });
     } else {
@@ -351,7 +351,7 @@ export function compileDocument(input: CompileInput): CompileResult {
         level: "warning",
         file: sourcePath,
         line,
-        message: `The PR head moved ${ctx.headDistance} commit${ctx.headDistance === 1 ? "" : "s"} past the stamp, but touches no file this walkthrough shows.`,
+        message: `The PR head is ${ctx.headDistance} commit${ctx.headDistance === 1 ? "" : "s"} ahead of the stamped commit, but changes no file shown in this walkthrough.`,
         hint: `Re-stamp when convenient: commit: ${short(ctx.headSha)}.`,
       });
     }

diff --git a/src/walkthrough/document.ts b/src/walkthrough/document.ts
@@ -67,7 +67,7 @@ export function parseDocument(source: string, file: string): ParsedDocument {
         file,
         line: frontmatterLine(raw, "preset"),
         message: `Unknown preset \`${frontmatter.preset}\`.`,
-        hint: `This build ships: ${presetNames().join(", ")}. Remove the key to stay on the core catalog.`,
+        hint: `Available presets: ${presetNames().join(", ")}. Remove the key to use the core catalog only.`,
       });
     }
   }

diff --git a/src/walkthrough/frontmatter.ts b/src/walkthrough/frontmatter.ts
@@ -29,7 +29,7 @@ const INVALID_FIELDS = [
   {
     key: "walkthrough",
     message: (value: string) => `Unsupported schema version \`${value}\`.`,
-    hint: `This build reads schema version ${SCHEMA_VERSION}. Write \`walkthrough: ${SCHEMA_VERSION}\`, or run a newer balade.`,
+    hint: `This version of balade supports schema version ${SCHEMA_VERSION}. Write \`walkthrough: ${SCHEMA_VERSION}\`, or upgrade balade.`,
   },
   {
     key: "title",
@@ -115,7 +115,7 @@ export function parseFrontmatter(raw: string, file: string): FrontmatterResult {
       file,
       line: 1,
       message: "The walkthrough file has no frontmatter.",
-      hint: "Start the file with a `---` block that holds walkthrough: 1, title, pr and commit.",
+      hint: "Start the file with a `---` block containing walkthrough: 1, title, pr and commit.",
     });
     return { frontmatter: null, diagnostics };
   }
@@ -130,7 +130,7 @@ export function parseFrontmatter(raw: string, file: string): FrontmatterResult {
       file,
       line: 1,
       message: `The frontmatter is not valid YAML: ${error instanceof Error ? error.message : String(error)}`,
-      hint: "Quote values that hold a colon, and keep the indentation consistent.",
+      hint: "Quote values that contain a colon, and keep the indentation consistent.",
     });
     return { frontmatter: null, diagnostics };
   }

diff --git a/src/walkthrough/pipeline.ts b/src/walkthrough/pipeline.ts
@@ -120,7 +120,7 @@ export function loadErrorDiagnostic(error: LoadError): CheckDiagnostic {
       level: "error",
       file: cwd,
       message: "This directory is not inside a git repository.",
-      hint: "Run balade from the repository that holds the walkthrough.",
+      hint: "Run balade from the repository that contains the walkthrough.",
     }),
     CommitUnresolvable: ({ commit, file }): CheckDiagnostic => ({
       code: "commit-unresolvable",

diff --git a/test/check.test.ts b/test/check.test.ts
@@ -361,7 +361,7 @@ The narrative.
       expect(find(rejected, "overview-section-missing")).toMatchObject({
         level: "error",
         message: expect.stringContaining("first section"),
-        hint: expect.stringContaining("frames the change"),
+        hint: expect.stringContaining("introduces the change"),
       });
       expect(codes(valid.diagnostics)).not.toContain("overview-section-missing");
     }),