DemchaAV · DemchaAV · Aug 3, 2026 · Aug 3, 2026
@@ -201,6 +201,26 @@ follow semantic versioning; release dates are ISO 8601.
 
 ### Documentation
 
+- **One recipe catalogue instead of two.** The cookbook page and the folder index each
+  carried a hand-maintained table of all twenty-two recipe pages. They happened to agree
+  on which pages exist and disagreed on ten of the descriptions — the folder index named
+  PDF417 and DataMatrix among the barcode symbologies, the cookbook did not; the cookbook
+  was fuller on themes, transforms and page backgrounds. Merged into the page both the
+  README and the documentation index point at, taking the better description of each
+  pair, so nothing is lost. The folder file keeps the one job GitHub gives it — being
+  what you see when you open the directory — and now says where the catalogue is instead
+  of holding a copy that drifts.
+- **Documents nobody could reach are reachable.** The archive index named its three
+  files in code spans rather than links, so the folder's own table of contents did not
+  actually lead anywhere, and one of the three was not listed at all. The two benchmark
+  notes sitting beside the committed baseline had no inbound link from anywhere; the
+  benchmark guide names them now, and says what they are — an April 2026 capture and the
+  before/after of the optimization round it belonged to, six weeks older than the
+  baseline file and unrelated to it.
+- **The starting-point table has an answer for the ordinary document.** Its three rows
+  each asked a "yes" question — a known template family, pixel-level control, a re-usable
+  new type — and a reader generating an ordinary report from data matched none of them
+  and fell off the end. The DSL is the default, not the fallback, and the table says so.
 - **The example catalogue stops calling current code legacy.** Two examples sat under
   a heading reading "🗄️ Legacy — pre-rebuild examples kept for downstream callers still
   on V1; do not start new code here", pointing at a V1 → V2 migration guide. There is no

@@ -79,7 +79,7 @@ Kept for anyone stepping through the 1.x line one minor at a time. Nothing here
 </details>
 
 ### Recipes (cookbook-style howtos)
-- **[recipes.md](recipes.md)** — index of all recipes (coverage map in [recipes/README.md](recipes/README.md)).
+- **[recipes.md](recipes.md)** — the catalogue: every recipe page and what it covers.
 - **[recipes/charts.md](recipes/charts.md)** — native vector bar/line/area/pie charts.
 - **[recipes/keep-together.md](recipes/keep-together.md)** — blocks that never split at a page break.
 - **[recipes/shapes.md](recipes/shapes.md)** — cards, dividers, lines, ellipses, images.

@@ -22,5 +22,6 @@ The current docs live under [`docs/`](../) at the repository root:
 
 | File | Why archived |
 | --- | --- |
-| `v1.2-roadmap.md` | Roadmap planning notes for the v1.2 release. Superseded by `CHANGELOG.md` for shipped features and by the Phase A–F execution plan for in-flight work. |
-| `migration-v1-1-to-v1-2.md` | Migration guide from v1.1 to v1.2. Both versions are out of support; v1.4 → v1.5 callers should follow the migration doc at `docs/roadmaps/migration-v1-4-to-v1-5.md`. |
+| [`v1.2-roadmap.md`](v1.2-roadmap.md) | Roadmap planning notes for the v1.2 release. Superseded by `CHANGELOG.md` for shipped features and by the Phase A–F execution plan for in-flight work. |
+| [`migration-v1-1-to-v1-2.md`](migration-v1-1-to-v1-2.md) | Migration guide from v1.1 to v1.2. Both versions are out of support; v1.4 → v1.5 callers should follow the migration doc at `docs/roadmaps/migration-v1-4-to-v1-5.md`. |
+| [`implementation-guide.md`](implementation-guide.md) | Implementation notes for an engine model 2.0 removed. The current route for adding a node, a handler or a backend is [`docs/contributing/extension-guide.md`](../contributing/extension-guide.md), with [`docs/architecture/package-map.md`](../architecture/package-map.md) for where things live. |
@@ -19,6 +19,7 @@ tree to choose the right one for the document you're rendering.
 | Is your document one of the template families (CV, cover letter, invoice, proposal)? | Yes | **Layered template preset.** Skip ahead to "Templates". |
 | Do you need pixel-level control over a one-off PDF? | Yes | **Raw DSL** (`DocumentSession.pageFlow(...)`). |
 | Do you need a re-usable scene for a *new* business document type? | Yes | **Custom template that wraps the DSL.** Implement `DocumentTemplate<S>` and take a `BrandTheme` for visual coherence. |
+| Anything else — a report, a statement, a brochure, one-off or generated from data | — | **Raw DSL.** This is the default answer, not a fallback: the DSL is the authoring surface, and templates are presets built on it. Continue with "Quick start" below. |
 
 The DSL and the templates compose against the SAME `DocumentSession`
 — a template can also live alongside hand-written DSL inside one

@@ -284,7 +284,9 @@ cleanest numbers.
 
 `baselines/current-speed-full.json` is a committed median `current-speed` report
 that `11-verdict-current-speed` judges new runs against (hard gate: average
-latency ±10%; peak heap is advisory, GC-timing noisy). Refresh it **only** for an
+latency ±10%; peak heap is advisory, GC-timing noisy).
+
+Refresh it **only** for an
 intended, verified improvement so the gate ratchets down — never to turn a red
 gate green. Capture a median of **≥5** runs on the branch that defines the new
 reference, with the IDE closed:
@@ -312,8 +314,17 @@ java -cp "$cp" com.demcha.compose.BenchmarkMedianTool current-speed $runs
 cp -f target/benchmarks/aggregates/current-speed/full/latest.json baselines/current-speed-full.json
 ```
 
-The baseline is machine-class-specific; the JSON records provenance
-(`timestamp`, `profile`, `sourceRuns`). Validate the refresh against a *fresh*
+The baseline is machine-class-specific; the JSON records its own provenance
+(`timestamp`, `profile`, `sourceRuns`) — read those rather than inferring where the
+numbers came from. Two older notes share the folder and are **historical context
+only**: [`baselines/BASELINE_SUMMARY.md`](../../baselines/BASELINE_SUMMARY.md) is a
+smoke-profile capture from April 2026, taken before a round of engine optimization,
+and [`baselines/COMPARISON.md`](../../baselines/COMPARISON.md) is that round's
+before/after. Neither produced this baseline and neither tracks it: the JSON was first
+cut six weeks later as a separate full-profile median when the verdict gate landed, and
+has been re-measured independently since.
+
+Validate the refresh against a *fresh*
 run — not one of the five that built the median — on that branch; it should
 score NEUTRAL and exit `0`:
 

@@ -16,19 +16,19 @@ authoring API; public application code should not import
 | [Shape-as-container](recipes/shape-as-container.md) | `addCircle` / `addEllipse` / `addContainer` with `ClipPolicy` (clipped layered children) |
 | [Transforms and z-index](recipes/transforms.md) | `rotate` / `scale` mixin, per-layer `zIndex` for overlays |
 | [Page backgrounds](recipes/page-backgrounds.md) | `pageBackground` / `pageBackgrounds`, `PageBackgroundFill` columns, bands, point-based fills, layering |
-| [Layered page design](recipes/layered-page-design.md) | Choosing between page backgrounds, rows, layer stacks, and canvases |
+| [Layered page design](recipes/layered-page-design.md) | Page background vs. row vs. layer stack vs. canvas — choosing the layer |
 | [Absolute placement](recipes/absolute-placement.md) | `addCanvas` + `position(x, y)` for pixel-precise certificates and badges |
 | [Tables](recipes/tables.md) | Row span, zebra rows, totals row, repeated header on page break |
-| [Rich text](recipes/rich-text.md) | `RichText` mixed-style runs, inline links/images/shapes, SVG icons, emoji shortcodes, checkboxes |
-| [Lists](recipes/lists.md) | `addList`, marker customisation, nested lists with per-depth markers |
-| [Timelines](recipes/timelines.md) | `addTimeline`: markers on a connector rail, geometry and text-style controls |
-| [Barcodes](recipes/barcodes.md) | QR / Code 128 / EAN / UPC and friends, tinting, quiet zone |
-| [Images](recipes/images.md) | Sources, sizing precedence, fit modes, images in rows and cards |
-| [PDF chrome](recipes/pdf-chrome.md) | Metadata, watermarks, running header/footer placeholders, protection, links, bookmarks |
-| [In-PDF navigation](recipes/in-pdf-navigation.md) | Anchors + internal `linkTo` links: clickable contents, heading jumps, bidirectional footnotes, inline-graphic links |
-| [Translucency](recipes/translucency.md) | `DocumentColor.rgba` / `withOpacity`, alpha coverage, layered tints |
-| [DOCX export](recipes/docx-export.md) | Semantic export, node mapping, fallbacks and skipped kinds |
-| [Snapshot testing](recipes/snapshot-testing.md) | Layout-snapshot regression testing in consumer projects |
+| [Rich text](recipes/rich-text.md) | `RichText` mixed-style runs in one paragraph: bold/accent/styled segments, inline links, inline images, inline SVG icons, emoji shortcodes, inline shapes and checkboxes |
+| [Lists](recipes/lists.md) | `addList`: quick bulleted lists, marker customisation, nested lists with per-depth markers, spacing and styled items |
+| [Timelines](recipes/timelines.md) | `addTimeline`: markers (dot / circle / numbered / square) on a connector rail, geometry and text-style controls, pagination opt-ins |
+| [Barcodes](recipes/barcodes.md) | QR / Code 128 / Code 39 / EAN / UPC / PDF417 / DataMatrix, tinting, quiet zone, card centring |
+| [Images](recipes/images.md) | Sources (bytes/path), sizing precedence, STRETCH/CONTAIN/COVER fit modes, images in rows and cards |
+| [PDF chrome](recipes/pdf-chrome.md) | Metadata, watermarks, running header/footer with `{page}/{pages}/{date}`, protection, links and outline bookmarks |
+| [In-PDF navigation](recipes/in-pdf-navigation.md) | Named `anchor(...)` destinations + internal `linkTo(...)` links: clickable tables of contents, `#heading`-style jumps, bidirectional footnotes, inline-graphic links — native PDF GoTo actions |
+| [Translucency](recipes/translucency.md) | `DocumentColor.rgba` / `withOpacity`: which primitives honour alpha, byte-identity for opaque colours, layered tints |
+| [DOCX export](recipes/docx-export.md) | Semantic DOCX export: 1:1 node mapping, chart/shape-container fallbacks, skipped kinds |
+| [Snapshot testing](recipes/snapshot-testing.md) | Layout-snapshot regression testing in consumer projects, baseline update flow |
 | [Streaming and output](recipes/streaming.md) | `buildPdf` / `writePdf` / `toPdfBytes`, DOCX export, layout snapshots, header / footer chrome, guide lines |
 | [Extending GraphCompose](recipes/extending.md) | New semantic node, fluent setter, render backend, snapshot-based regression tests |
 

@@ -1,34 +1,10 @@
 # Recipes
 
-Task-oriented guides: each page shows how to use one slice of the canonical
-API, with copy-pasteable snippets verified against the current release.
-
-## Available recipes
-
-| Recipe | Covers |
-|---|---|
-| [charts.md](charts.md) | Native vector bar / line / area / pie-donut charts: data–spec–style layers, axis & grid toggles, point markers, value-label halos, legend placement, translucent area fills |
-| [rich-text.md](rich-text.md) | `RichText` mixed-style runs in one paragraph: bold/accent/styled segments, inline links, inline images, inline SVG icons, emoji shortcodes, inline shapes and checkboxes |
-| [lists.md](lists.md) | `addList`: quick bulleted lists, marker customisation, nested lists with per-depth markers, spacing and styled items |
-| [timelines.md](timelines.md) | `addTimeline`: markers (dot / circle / numbered / square) on a connector rail, geometry and text-style controls, pagination opt-ins |
-| [keep-together.md](keep-together.md) | `keepTogether()` / `keepEntriesTogether()` — blocks that relocate whole instead of orphaning a heading at a page break |
-| [shapes.md](shapes.md) | Filled cards, dividers, accent bars, lines, spacers, ellipses, images |
-| [shape-as-container.md](shape-as-container.md) | Circles/ellipses/rounded cards holding clipped children, `ClipPolicy` |
-| [absolute-placement.md](absolute-placement.md) | `CanvasLayerNode` — children at explicit (x, y) |
-| [layered-page-design.md](layered-page-design.md) | Page background vs. row vs. layer stack vs. canvas — choosing the layer |
-| [page-backgrounds.md](page-backgrounds.md) | Per-page fills: sidebars, bands, layered tints |
-| [transforms.md](transforms.md) | Rotation, scaling, skewing |
-| [tables.md](tables.md) | Tabular layouts: columns, headers, zebra rows, composed cells |
-| [themes.md](themes.md) | `BrandTheme` factories and custom token bundles |
-| [barcodes.md](barcodes.md) | QR / Code 128 / Code 39 / EAN / UPC / PDF417 / DataMatrix, tinting, quiet zone, card centring |
-| [images.md](images.md) | Sources (bytes/path), sizing precedence, STRETCH/CONTAIN/COVER fit modes, images in rows and cards |
-| [pdf-chrome.md](pdf-chrome.md) | Metadata, watermarks, running header/footer with `{page}/{pages}/{date}`, protection, links and outline bookmarks |
-| [in-pdf-navigation.md](in-pdf-navigation.md) | Named `anchor(...)` destinations + internal `linkTo(...)` links: clickable tables of contents, `#heading`-style jumps, bidirectional footnotes, inline-graphic links — native PDF GoTo actions |
-| [translucency.md](translucency.md) | `DocumentColor.rgba` / `withOpacity`: which primitives honour alpha, byte-identity for opaque colours, layered tints |
-| [docx-export.md](docx-export.md) | Semantic DOCX export: 1:1 node mapping, chart/shape-container fallbacks, skipped kinds |
-| [snapshot-testing.md](snapshot-testing.md) | Layout-snapshot regression testing in consumer projects, baseline update flow |
-| [streaming.md](streaming.md) | Streaming PDFs to HTTP responses |
-| [extending.md](extending.md) | Extension patterns: custom nodes via the `NodeDefinition` SPI |
-
-Every shipped feature now has a recipe; the runnable
-[examples](../../examples/README.md) remain the end-to-end references.
+Task-oriented guides: each page shows how to use one slice of the canonical API, with
+copy-pasteable snippets verified against the current release.
+
+The catalogue — every page in this folder and what it covers — lives one level up, in
+**[`docs/recipes.md`](../recipes.md)**. That is the page the root README and the
+documentation index point at, so it is the one kept current; this file used to carry a
+second copy of the same table, and two hand-maintained copies of one list only ever
+agree until they don't.