Merge PR #536: docs(extract): make worked examples runnable and outputs verbatim

Author: merge-queue-bot

PLAN.md

@@ -170,5 +170,10 @@ footer: |
 | 240 | 🔲     | sonnet | [cuelite phase 4 — drop cuelang.org and enable tinygo](plan/240_cuelite-drop-cue.md)                                                    |
 | 241 | 🔲     | opus   | [Schema-per-file config under `.mdsmith/schemas/`](plan/241_schema-files.md)                                                            |
 | 242 | 🔲     | sonnet | [Recover from panics in the LSP lint pipeline](plan/242_lsp-panic-recovery.md)                                                          |
+| 242 | 🔲     | opus   | [proto.md schemas declare content entries via `<?content?>`](plan/242_proto-content-entries.md)                                         |
+| 243 | 🔲     | sonnet | [`mdsmith extract` projects the document H1 as `title`](plan/243_extract-h1-title.md)                                                   |
 | 243 | 🔲     | sonnet | [Security hardening batch — 2026-06-09 audit](plan/243_secreview-2026-06-09-hardening.md)                                               |
+| 244 | 🔲     | opus   | [Structured list projection; fix nested-item text corruption](plan/244_structured-list-projection.md)                                   |
+| 245 | 🔲     | sonnet | [Table projection modes: `records` and `rows`](plan/245_table-projection-modes.md)                                                      |
+| 246 | 🔲     | opus   | [Typed block projection and full-document extract](plan/246_block-projection-full-extract.md)                                           |
 <?/catalog?>

docs/guides/extract-markdown-as-data.md

@@ -38,14 +38,16 @@ YAML scalar.
 The trap is to reach for frontmatter for everything
 because it's structured. A 60-character `tagline` in
 frontmatter and the same 60 characters in a
-`## Tagline` body section produce identical JSON;
-the body version is shorter to edit, diffs cleanly
-when wrapped, and is lintable as Markdown.
+`## Tagline` body section project the same string;
+only the key moves, from `frontmatter.tagline` to
+`tagline.text`. The body version is shorter to edit,
+diffs cleanly when wrapped, and is lintable as
+Markdown.
 
 ## Worked example
 
-A product-copy file with a tagline, a lead, and one
-per-surface description.
+A product-copy file at `docs/copy/product.md` with a
+tagline, a lead, and one per-surface description.
 
 ### Frontmatter-heavy (the trap)
 
@@ -101,33 +103,58 @@ Inline diagnostics, fix-on-save, and instant
 navigation for Markdown in VS Code.
 ```
 
-With a matching schema in `.mdsmith.yml`:
+With a matching schema and kind assignment in
+`.mdsmith.yml`:
 
 ```yaml
 kinds:
   product-copy:
     schema:
       sections:
         - heading: { regex: '^Tagline$' }
+          content:
+            - { kind: paragraph }
         - heading: { regex: '^Lead$' }
+          content:
+            - { kind: paragraph }
         - heading: { regex: '^VS Code$' }
           bind: vscode-description
+          content:
+            - { kind: paragraph }
+kind-assignment:
+  - glob: ["docs/copy/product.md"]
+    kinds: [product-copy]
 ```
 
-`mdsmith extract product-copy --format json` emits
-the same shape both encodings would produce:
+Each `content:` entry declares the paragraph its
+section projects. A section without one projects as
+an empty object — the schema, not the body, decides
+what `extract` emits.
+
+`mdsmith extract product-copy --format json docs/copy/product.md`
+emits:
 
 ```json
 {
-  "frontmatter": { "title": "Product copy" },
-  "tagline": { "text": "Mark down your ideas; smith them into shipping docs." },
-  "lead": { "text": "A lint-and-fix tool that keeps your Markdown consistent across every surface — READMEs, docs site, editor extensions." },
-  "vscode-description": { "text": "Inline diagnostics, fix-on-save, and instant navigation for Markdown in VS Code." }
+  "frontmatter": {
+    "title": "Product copy"
+  },
+  "lead": {
+    "text": "A lint-and-fix tool that keeps your Markdown consistent across every surface — READMEs, docs site, editor extensions."
+  },
+  "tagline": {
+    "text": "Mark down your ideas; smith them into shipping docs."
+  },
+  "vscode-description": {
+    "text": "Inline diagnostics, fix-on-save, and instant navigation for Markdown in VS Code."
+  }
 }
 ```
 
-The body version costs nothing at the projection
-layer and is the editable artifact.
+Keys come out sorted, not in document order. The
+consumer reads the same strings the frontmatter
+version held, and the body version is the editable
+artifact.
 
 ## Projecting inline structure
 
@@ -165,21 +192,36 @@ kinds:
             - { kind: paragraph, projection: inline, required: true }
 ```
 
-`mdsmith extract product-copy --format json` emits the
-headline as a span list — text, then the level-1
-emphasis span with its own `children`, then the
-trailing text:
+`mdsmith extract product-copy --format json docs/copy/product.md`
+emits the headline as a span list: text, then the
+level-1 emphasis span with its own `children`, then
+the trailing text:
 
 ```json
 {
-  "frontmatter": { "title": "Product copy" },
+  "frontmatter": {
+    "title": "Product copy"
+  },
   "headline": {
     "inline": [
-      { "span": "text", "value": "Mark" },
-      { "span": "emphasis", "level": 1, "children": [
-        { "span": "text", "value": "down" }
-      ]},
-      { "span": "text", "value": ", smithed." }
+      {
+        "span": "text",
+        "value": "Mark"
+      },
+      {
+        "children": [
+          {
+            "span": "text",
+            "value": "down"
+          }
+        ],
+        "level": 1,
+        "span": "emphasis"
+      },
+      {
+        "span": "text",
+        "value": ", smithed."
+      }
     ]
   }
 }
@@ -194,9 +236,11 @@ recursive mode switch:
 ```json
 "inline": [
   { "span": "text", "value": "run " },
-  { "span": "strong", "level": 2, "children": [
-    { "span": "code", "value": "mdsmith fix" }
-  ]},
+  {
+    "children": [{ "span": "code", "value": "mdsmith fix" }],
+    "level": 2,
+    "span": "strong"
+  },
   { "span": "text", "value": " daily" }
 ]
 ```
@@ -237,6 +281,81 @@ than one line, and anything that benefits from
 Markdown formatting (code, emphasis, links) all
 belong in the body.
 
+## Frontmatter `title` and the H1
+
+The worked example carries the same string twice:
+`title: Product copy` in frontmatter and
+`# Product copy` as the H1. Nothing checks the two
+against each other by default, so they can drift
+apart edit by edit.
+
+The test from the previous section decides it. When
+no catalog row, site template, or release script
+reads `frontmatter.title`, delete the field; the H1
+alone is the title. When a tool does read the
+field, keep it and let MDS020 enforce the match.
+
+Enforcement needs a file-based schema. An inline
+`schema:` starts matching at H2 — the H1 belongs to
+[first-line-heading][mds004] — so the kind switches
+to a `proto.md` whose first row is the `{title}`
+placeholder:
+
+```markdown
+# {title}
+
+## ...
+```
+
+```yaml
+kinds:
+  product-copy:
+    rules:
+      required-structure:
+        schema: copy-proto.md
+```
+
+The `{title}` row requires the frontmatter field
+and checks the H1 text against its value. A drifted
+H1 fails `mdsmith check`:
+
+```text
+docs/copy/product.md:4:1 MDS020 heading does not match frontmatter: expected "Product copy" (from title), got "Product page copy"
+```
+
+The synced H1 also becomes data. `mdsmith extract`
+projects the H1 scope under a `title` key, with the
+captured heading text inside:
+
+```json
+{
+  "frontmatter": {
+    "title": "Product copy"
+  },
+  "title": {
+    "title": "Product copy"
+  }
+}
+```
+
+Weigh two limits before switching. Every schema
+source on a file must declare the same root level,
+so an H1-rooted `proto.md` cannot compose with an
+H2-rooted inline schema on the same file. And a
+`proto.md` declares heading rows only, not
+`content:` entries, so the worked example's
+paragraph projections (`tagline.text`, …) drop out
+of the tree.
+
+When the kind's main job is extraction, keep the
+inline schema and delete the frontmatter field
+instead. mdsmith cannot project the H1 text without
+a frontmatter field behind it: a `{title}` row with
+no `title` field matches any heading, and `extract`
+skips wildcard scopes.
+
+[mds004]: ../../internal/rules/MDS004-first-line-heading/README.md
+
 ## `bind:` patterns
 
 `bind:` renames the JSON key that a heading or
@@ -281,13 +400,14 @@ embed reads the tagline directly:
 file: docs/copy/product.md
 extract: tagline.text
 ?>
-Mark down your ideas; smith them into shipping
-docs.
+Mark down your ideas; smith them into shipping docs.
 <?/include?>
 ```
 
-The directive runs the included file through the
-same projection rules `mdsmith extract` produces,
+The spliced text lands on one line: a `text`
+projection joins a soft-wrapped paragraph with
+spaces. The directive runs the included file through
+the same projection rules `mdsmith extract` uses,
 walks the dotted path, and splices the leaf. There
 is no intermediate "fragment" file to keep in sync —
 the README reads the source of truth on every lint.

docs/reference/cli/extract.md

@@ -59,8 +59,9 @@ Content entries project under default keys:
 - `paragraph` → `text` (plain text), or `inline` when
   the entry sets `projection: inline` (see below).
 
-Two sibling projections that resolve to the same key
-are a schema error. It is reported at extract time.
+Sibling keys are emitted in sorted order, not document
+order. Two sibling projections that resolve to the same
+key are a schema error. It is reported at extract time.
 Optional sections that did not match are omitted, not
 emitted as null.
 
@@ -110,9 +111,11 @@ For the headline `Mark*down*, smithed.`:
 "headline": {
   "inline": [
     { "span": "text", "value": "Mark" },
-    { "span": "emphasis", "level": 1, "children": [
-      { "span": "text", "value": "down" }
-    ]},
+    {
+      "children": [{ "span": "text", "value": "down" }],
+      "level": 1,
+      "span": "emphasis"
+    },
     { "span": "text", "value": ", smithed." }
   ]
 }
@@ -122,9 +125,11 @@ A nested example — a strong span wrapping a code span,
 ``**`mdsmith fix`**`` — projects with no mode switch:
 
 ```json
-{ "span": "strong", "level": 2, "children": [
-    { "span": "code", "value": "mdsmith fix" }
-] }
+{
+  "children": [{ "span": "code", "value": "mdsmith fix" }],
+  "level": 2,
+  "span": "strong"
+}
 ```
 
 Each content kind constrains its projection at schema-
@@ -175,7 +180,10 @@ mdsmith extract plan --format msgpack plan/166_x.md > plan.mp
 
 ### Worked example
 
-A two-section kind schema and a conformant file:
+A two-section kind schema, a kind assignment, and a
+conformant file. Each section declares a `content:`
+entry. A section without one projects as an empty
+object:
 
 ```yaml
 # .mdsmith.yml
@@ -184,8 +192,15 @@ kinds:
     schema:
       sections:
         - heading: { regex: '^Tagline$' }
+          content:
+            - { kind: paragraph }
         - heading: { regex: '^VS Code$' }
           bind: vscode-description
+          content:
+            - { kind: paragraph }
+kind-assignment:
+  - glob: ["docs/copy.md"]
+    kinds: [product-copy]
 ```
 
 ```markdown
@@ -210,9 +225,15 @@ emits:
 
 ```json
 {
-  "frontmatter": { "title": "Product copy" },
-  "tagline": { "text": "Mark down your ideas; smith them into shipping docs." },
-  "vscode-description": { "text": "Inline diagnostics, fix-on-save, and instant navigation for Markdown in VS Code." }
+  "frontmatter": {
+    "title": "Product copy"
+  },
+  "tagline": {
+    "text": "Mark down your ideas; smith them into shipping docs."
+  },
+  "vscode-description": {
+    "text": "Inline diagnostics, fix-on-save, and instant navigation for Markdown in VS Code."
+  }
 }
 ```