diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8f0027cd..ccc60184 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -299,7 +299,7 @@ v1.6.1 stays on JitPack as a maintenance release.
 The "expressive" release. Closes the remaining canonical-vs-legacy
 parity gaps for advanced authoring without architectural rollback.
 Every new primitive ships through `DocumentNode + NodeDefinition +
-render handler`. See [`docs/v1.6-roadmap.md`](docs/v1.6-roadmap.md)
+render handler`. See [`docs/roadmaps/v1.6-roadmap.md`](docs/roadmaps/v1.6-roadmap.md)
 for the phased plan, verification gates, and ADRs.
 
 ### Headline — "expressive"
@@ -336,7 +336,7 @@ The architecture lane closes the highest-severity findings from the
 post-1.5 audit. None of these change author-facing behaviour for
 unmodified v1.5 code; they sharpen the public-vs-internal boundary,
 open extension points, and split the load-bearing files. See
-[`docs/migration-v1-5-to-v1-6.md`](docs/migration-v1-5-to-v1-6.md)
+[`docs/roadmaps/migration-v1-5-to-v1-6.md`](docs/roadmaps/migration-v1-5-to-v1-6.md)
 for the user-facing summary.
 
 - **`@Internal` API stability marker.** New
@@ -774,7 +774,7 @@ streaming, snapshot, CV-render, and Transformable-leaf-builder surfaces.
 v1.5 is **fully source-compatible with v1.4**. Every public record
 that grew a new field ships back-compat constructors that default the
 new value, so v1.4 callers compile and behave unchanged. See
-[`docs/migration-v1-4-to-v1-5.md`](docs/migration-v1-4-to-v1-5.md).
+[`docs/roadmaps/migration-v1-4-to-v1-5.md`](docs/roadmaps/migration-v1-4-to-v1-5.md).
 
 ### Public API — visual primitives
 
@@ -1024,7 +1024,7 @@ The runnable `examples/` module gains six new showcases hooked into
   [`assets/readme/examples/`](assets/readme/examples/) (whitelisted in
   `.gitignore`) so users can browse renders straight from GitHub
   without running anything.
-- New [`docs/template-authoring.md`](docs/template-authoring.md) (~620
+- New [`docs/templates/v1-classic/authoring.md`](docs/templates/v1-classic/authoring.md) (~620
   lines) — the canonical cheatsheet covering builder hierarchy, a
   per-builder one-liner cheatsheet, a style-types reference, the
   theme system in 60 seconds, six golden patterns, ten anti-patterns,
@@ -1041,10 +1041,10 @@ The runnable `examples/` module gains six new showcases hooked into
 - [`docs/recipes.md`](docs/recipes.md) is now a pure index linking
   every topic-focused recipe page plus four 5-line "common DSL
   primitives" starter snippets.
-- [`docs/canonical-legacy-parity.md`](docs/canonical-legacy-parity.md)
+- [`docs/architecture/canonical-legacy-parity.md`](docs/architecture/canonical-legacy-parity.md)
   gains a "Shape-as-container (clipped)" row recording the DOCX
   fallback rule.
-- New [`docs/migration-v1-4-to-v1-5.md`](docs/migration-v1-4-to-v1-5.md)
+- New [`docs/roadmaps/migration-v1-4-to-v1-5.md`](docs/roadmaps/migration-v1-4-to-v1-5.md)
   — fresh migration guide for v1.4 consumers.
 
 ### Performance — v1.5 baseline
@@ -1128,7 +1128,7 @@ baseline and the next snapshot.
   `ProposalTemplateV1` ship side-by-side with the V2 templates;
   callers who want the cinematic look opt in by switching the type.
 
-See [`docs/migration-v1-4-to-v1-5.md`](docs/migration-v1-4-to-v1-5.md)
+See [`docs/roadmaps/migration-v1-4-to-v1-5.md`](docs/roadmaps/migration-v1-4-to-v1-5.md)
 for the full guide.
 
 ---
@@ -1232,8 +1232,8 @@ v1.4 closes the visual-design gap that the previous releases left open. Tables c
 
 ### Documentation
 
-- `docs/canonical-legacy-parity.md` is updated to reflect the v1.3 capabilities (rows, per-side borders, auto-size text, DOCX export)
-- `docs/benchmarks.md` documents the new smoke profile defaults, the GC stabilization point, the linear-interpolation percentile rule, and the stage-breakdown table
+- `docs/architecture/canonical-legacy-parity.md` is updated to reflect the v1.3 capabilities (rows, per-side borders, auto-size text, DOCX export)
+- `docs/operations/benchmarks.md` documents the new smoke profile defaults, the GC stabilization point, the linear-interpolation percentile rule, and the stage-breakdown table
 - `CONTRIBUTING.md` repository map and package list now describe the canonical functional layout (`document.layout`, `document.backend`, `document.output`) alongside the legacy ECS engine
 
 ---
@@ -1272,7 +1272,7 @@ v1.4 closes the visual-design gap that the previous releases left open. Tables c
 
 - new `docs/migration-v1-1-to-v1-2.md` outlines the move from older v1.1 usage patterns to the canonical session-first API
 - new `docs/v1.2-roadmap.md` tracks the remaining stabilization work for the v1.2 release polish window
-- `docs/release-process.md` now describes the current JitPack-first 1.x release flow and runnable examples verification
+- `docs/contributing/release-process.md` now describes the current JitPack-first 1.x release flow and runnable examples verification
 - user-facing docs now describe debug guide-line overlays through `GraphCompose.document(...).guideLines(true)` / `DocumentSession.guideLines(true)` and call out JitPack tag-cache handling during release verification
 
 ---
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3a063b56..98203607 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -7,9 +7,9 @@ Thanks for helping improve GraphCompose.
 Read these files first:
 
 - [README.md](./README.md)
-- [docs/architecture.md](./docs/architecture.md)
-- [docs/implementation-guide.md](./docs/implementation-guide.md)
-- [docs/benchmarks.md](./docs/benchmarks.md) when you touch benchmark tooling, render hot paths, layout hot paths, or performance-facing docs
+- [docs/architecture/overview.md](./docs/architecture/overview.md)
+- [docs/contributing/implementation-guide.md](./docs/contributing/implementation-guide.md)
+- [docs/operations/benchmarks.md](./docs/operations/benchmarks.md) when you touch benchmark tooling, render hot paths, layout hot paths, or performance-facing docs
 
 They explain the current public surface, the engine/template split, and the recommended extension points.
 
@@ -81,7 +81,7 @@ GraphCompose follows a fork → feature branch → pull request flow. Exte
 3. **JitPack** picks up the new tag automatically. After JitPack reports `BUILD SUCCESS`, a separate post-release commit on `develop` flips the README install snippets to the new version.
 4. **GitHub Release** is created with notes from the matching `CHANGELOG.md` section.
 
-See [docs/release-process.md](./docs/release-process.md) for the full checklist (audit gates, hotfix protocol, lessons learned).
+See [docs/contributing/release-process.md](./docs/contributing/release-process.md) for the full checklist (audit gates, hotfix protocol, lessons learned).
 
 ## Repository map
 
@@ -251,15 +251,37 @@ Reference templates to copy:
 
 ### New built-in template
 
+GraphCompose supports two template authoring patterns. Pick based
+on whether you're extending an existing template family or building
+a new one.
+
+**For a NEW template family from scratch** (invoice-v2,
+cover-letter-v2, report-v2, anything not yet in `cv/v2/`) — follow
+the canonical layered architecture documented in
+[**docs/templates/v2-layered/contributor-guide.md**](./docs/templates/v2-layered/contributor-guide.md).
+Five sub-packages (`data/` / `theme/` / `components/` / `widgets/`
+/ `presets/`), each with a clear contract. CV v2
+(`com.demcha.compose.document.templates.cv.v2`) is the reference
+implementation; read it before starting yours.
+
+**For a new preset inside an existing v1-classic family** (a new CV
+variant alongside `ModernProfessional`, a new invoice preset
+alongside `InvoiceTemplateV2`):
+
 - Constructor takes a `BusinessTheme` (or `CvTheme` for CV
   templates). Provide a no-arg overload that picks a default theme.
 - Compose against `DocumentDsl` — no PDF-specific imports.
 - Route every visible token through `theme.palette()` /
   `theme.text()` / `theme.spacing()` / `theme.table()`.
 - Reference: `InvoiceTemplateV2`, `ProposalTemplateV2`. Read
-  [docs/template-authoring.md](./docs/template-authoring.md) before
+  [docs/templates/v1-classic/authoring.md](./docs/templates/v1-classic/authoring.md) before
   starting.
 
+> 📚 **Map of template docs**:
+> [docs/README.md](./docs/README.md#templates) lists every template
+> guide with a one-line description so you can pick the right one
+> fast.
+
 ### New engine internal primitive
 
 If you are extending the engine foundation itself (a new render
@@ -281,8 +303,8 @@ marker, a new layout system, a new render-pass session):
 For text-heavy primitives, also read:
 
 - [TextMeasurementSystem.java](./src/main/java/com/demcha/compose/engine/measurement/TextMeasurementSystem.java)
-- [docs/architecture.md](./docs/architecture.md)
-- [docs/implementation-guide.md](./docs/implementation-guide.md)
+- [docs/architecture/overview.md](./docs/architecture/overview.md)
+- [docs/contributing/implementation-guide.md](./docs/contributing/implementation-guide.md)
 
 If the primitive should be available to application developers,
 expose it through `DocumentDsl` and a public `DocumentNode`, not a
@@ -328,8 +350,8 @@ If a change affects resolved geometry, pagination, or ordering, prefer adding or
 - Keep [README.md](./README.md) aligned with the tested examples.
 - Keep benchmark values clearly dated when they are refreshed.
 - Keep `assets/readme/*` screenshots consistent with the current render outputs.
-- If you add a new extension point or contribution pattern, update [README.md](./README.md), [docs/architecture.md](./docs/architecture.md), and [docs/implementation-guide.md](./docs/implementation-guide.md) as part of the same change.
-- If you change benchmark flow, benchmark artifact layout, or diff selection rules, update [README.md](./README.md) and [docs/benchmarks.md](./docs/benchmarks.md) in the same change.
+- If you add a new extension point or contribution pattern, update [README.md](./README.md), [docs/architecture/overview.md](./docs/architecture/overview.md), and [docs/contributing/implementation-guide.md](./docs/contributing/implementation-guide.md) as part of the same change.
+- If you change benchmark flow, benchmark artifact layout, or diff selection rules, update [README.md](./README.md) and [docs/operations/benchmarks.md](./docs/operations/benchmarks.md) in the same change.
 - Visual PDF artifacts are grouped under `target/visual-tests/clean/*` and `target/visual-tests/guides/*` so guide-line renders are easy to find separately from clean outputs.
 
 ## Package naming
diff --git a/README.md b/README.md
index 120c9eb0..b52bd7dd 100644
--- a/README.md
+++ b/README.md
@@ -81,9 +81,9 @@ GraphCompose uses PDFBox under the hood as the rendering backend — the com
 | You want to… | Surface | Entry point |
 |---|---|---|
 | Generate a one-off PDF programmatically | DSL | `GraphCompose.document(...).pageFlow(...)` — see [Hello world](#hello-world) below |
-| Generate a CV / cover letter / invoice / proposal from data | Templates v2 | `ModernProfessional.create(BusinessTheme.modern()).compose(session, spec)` — see [templates v2](./docs/templates-v2.md) |
-| Add a custom visual primitive | Engine extension | `NodeDefinition` + `PdfFragmentRenderHandler` — see [extension guide](./docs/extension-guide.md) |
-| Regression-test generated layouts | Layout snapshots | `DocumentSession#layoutSnapshot()` — see [snapshot testing](./docs/layout-snapshot-testing.md) |
+| Generate a CV / cover letter / invoice / proposal from data | Templates v2 | `ModernProfessional.create(BusinessTheme.modern()).compose(session, spec)` — see [templates v2](./docs/templates/v1-classic/README.md) |
+| Add a custom visual primitive | Engine extension | `NodeDefinition` + `PdfFragmentRenderHandler` — see [extension guide](./docs/contributing/extension-guide.md) |
+| Regression-test generated layouts | Layout snapshots | `DocumentSession#layoutSnapshot()` — see [snapshot testing](./docs/operations/layout-snapshot-testing.md) |
 
 ## Installation
 
@@ -106,7 +106,7 @@ dependencies { implementation("com.github.demchaav:GraphCompose:v1.6.4") }
 
 > **Distribution status** — currently **JitPack**. Maven Central is planned for v1.7 ([tracking issue](https://github.com/DemchaAV/GraphCompose/issues/7)).
 
-> **Upgrading from v1.5?** Core document authoring stays source-compatible — engine, DSL, themes, and backend-neutral records carry v1.5 callers unchanged. **Templates v2** replaces the legacy CV / cover-letter template classes; legacy classes were **deleted**, not deprecated. Read the [migration guide](./docs/migration-v1-5-to-v1-6.md) before upgrading template-heavy code.
+> **Upgrading from v1.5?** Core document authoring stays source-compatible — engine, DSL, themes, and backend-neutral records carry v1.5 callers unchanged. **Templates v2** replaces the legacy CV / cover-letter template classes; legacy classes were **deleted**, not deprecated. Read the [migration guide](./docs/roadmaps/migration-v1-5-to-v1-6.md) before upgrading template-heavy code.
 
 ## Hello world
 
@@ -146,11 +146,11 @@ For a Spring Boot `@RestController` streaming the PDF straight to the response,
 
 ## What's in v1.6 — "expressive"
 
-- **Templates v2** — 14 CV and 14 paired cover-letter presets, theme-driven via `BusinessTheme`, one-liner `create(theme)` factories. Inline markdown, slot-based multi-column layouts. See [`docs/templates-v2.md`](./docs/templates-v2.md).
+- **Templates v2** — 14 CV and 14 paired cover-letter presets, theme-driven via `BusinessTheme`, one-liner `create(theme)` factories. Inline markdown, slot-based multi-column layouts. See [`docs/templates/v1-classic/README.md`](./docs/templates/v1-classic/README.md).
 - **Composed primitives** — `ListBuilder.addItem(label, Consumer)` (nested lists), `DocumentTableCell.node(...)` (any node inside a cell), `CanvasLayerNode` (pixel-precise free-canvas placement).
 - **Architecture hardening** — `@Internal` API stability marker, public `PdfFragmentRenderHandler` SPI, `DocumentRenderingException` on the convenience render path, documented thread-safety contract.
 
-Full notes in [`CHANGELOG.md`](./CHANGELOG.md). Upgrade guide: [`docs/migration-v1-5-to-v1-6.md`](./docs/migration-v1-5-to-v1-6.md).
+Full notes in [`CHANGELOG.md`](./CHANGELOG.md). Upgrade guide: [`docs/roadmaps/migration-v1-5-to-v1-6.md`](./docs/roadmaps/migration-v1-5-to-v1-6.md).
 
 ## v1.6 primitives in 30 lines
 
@@ -189,13 +189,21 @@ document.pageFlow().addCanvas(523, 360, canvas -> canvas
 
 ## Documentation
 
-- 🆕 [**Templates — layered architecture**](./docs/templates-layered/README.md) — the canonical going-forward pattern for new template families (CV v2 is the reference implementation). Personas: [quickstart](./docs/templates-layered/quickstart.md) · [using templates](./docs/templates-layered/using-templates.md) · [authoring presets](./docs/templates-layered/authoring-presets.md) · [contributing a new family](./docs/templates-layered/contributor-guide.md).
-- [Template authoring cheatsheet](./docs/template-authoring.md) — read this once before writing your own template (covers v1 template surface)
-- [Templates v2 landing](./docs/templates-v2.md) — CV / cover-letter / invoice / proposal preset library (v1 surface, still shipped)
+📚 **[Full docs index](./docs/README.md)** — categorised map of every doc, ADR, and recipe. Start there to navigate the documentation.
+
+### Templates
+- 🆕 [**Templates — v2 layered architecture**](./docs/templates/v2-layered/README.md) — the canonical going-forward pattern for new template families (CV v2 is the reference implementation). Personas: [quickstart](./docs/templates/v2-layered/quickstart.md) · [using templates](./docs/templates/v2-layered/using-templates.md) · [authoring presets](./docs/templates/v2-layered/authoring-presets.md) · [contributing a new family](./docs/templates/v2-layered/contributor-guide.md).
+- [Templates v1-classic landing](./docs/templates/v1-classic/README.md) — CV / cover-letter / invoice / proposal preset library (v1.6 surface, still shipped). Cheat sheet: [authoring](./docs/templates/v1-classic/authoring.md).
+
+### Architecture & operations
+- [Architecture overview](./docs/architecture/overview.md) · [Lifecycle](./docs/architecture/lifecycle.md) · [Production rendering](./docs/operations/production-rendering.md) · [Layout snapshot testing](./docs/operations/layout-snapshot-testing.md)
+
+### Recipes & examples
+- [Recipes index](./docs/recipes.md) — [shape-as-container](./docs/recipes/shape-as-container.md) · [shapes](./docs/recipes/shapes.md) · [transforms](./docs/recipes/transforms.md) · [tables](./docs/recipes/tables.md) · [themes](./docs/recipes/themes.md) · [streaming](./docs/recipes/streaming.md) · [extending](./docs/recipes/extending.md)
 - [Examples gallery](./examples/README.md) — every runnable example with PDF preview
-- [Architecture](./docs/architecture.md) · [Lifecycle](./docs/lifecycle.md) · [Production rendering](./docs/production-rendering.md)
-- Recipes: [shape-as-container](./docs/recipes/shape-as-container.md) · [transforms](./docs/recipes/transforms.md) · [tables](./docs/recipes/tables.md) · [themes](./docs/recipes/themes.md) · [streaming](./docs/recipes/streaming.md) · [extending](./docs/recipes/extending.md)
-- [Migration v1.5 → v1.6](./docs/migration-v1-5-to-v1-6.md) · [Release process](./docs/release-process.md) · [Contributing](./CONTRIBUTING.md)
+
+### Contributing & releases
+- [Migration v1.5 → v1.6](./docs/roadmaps/migration-v1-5-to-v1-6.md) · [Release process](./docs/contributing/release-process.md) · [Contributing](./CONTRIBUTING.md)
 
 ## Companion projects
 
diff --git a/ROADMAP.md b/ROADMAP.md
index e58d2dea..8ef2b59d 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -1,6 +1,6 @@
 # Roadmap
 
-GraphCompose is solo-maintained. This roadmap is a direction, not a contract. Dates are intentionally omitted. Concrete work is tracked in [issues](https://github.com/DemchaAV/GraphCompose/issues) and shipped work is recorded in [CHANGELOG.md](CHANGELOG.md). For v1.6 phase-level detail, see [docs/v1.6-roadmap.md](docs/v1.6-roadmap.md).
+GraphCompose is solo-maintained. This roadmap is a direction, not a contract. Dates are intentionally omitted. Concrete work is tracked in [issues](https://github.com/DemchaAV/GraphCompose/issues) and shipped work is recorded in [CHANGELOG.md](CHANGELOG.md). For v1.6 phase-level detail, see [docs/roadmaps/v1.6-roadmap.md](docs/roadmaps/v1.6-roadmap.md).
 
 ## Now (v1.6.x)
 
diff --git a/SECURITY.md b/SECURITY.md
index 4bc5a332..58644155 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -9,7 +9,7 @@ Security fixes are issued for the latest minor release. Older minors do not rece
 | Version | Supported |
 |---------|-----------|
 | 1.6.x   | Yes — actively patched |
-| < 1.6   | No — upgrade required (see [migration guide](docs/migration-v1-5-to-v1-6.md)) |
+| < 1.6   | No — upgrade required (see [migration guide](docs/roadmaps/migration-v1-5-to-v1-6.md)) |
 
 ## Reporting a vulnerability
 
@@ -58,5 +58,5 @@ Out of scope:
 ## Hardening notes for consumers
 
 - Treat user-supplied input as untrusted before injecting it into the DSL. Long strings, control characters, oversize tables, and pathological pagination inputs can affect render time and memory.
-- For server-side rendering, scope `DocumentSession` to a single request and close it via try-with-resources. See [docs/lifecycle.md](docs/lifecycle.md).
-- Production rendering guidance: [docs/production-rendering.md](docs/production-rendering.md).
+- For server-side rendering, scope `DocumentSession` to a single request and close it via try-with-resources. See [docs/architecture/lifecycle.md](docs/architecture/lifecycle.md).
+- Production rendering guidance: [docs/operations/production-rendering.md](docs/operations/production-rendering.md).
diff --git a/SUPPORT.md b/SUPPORT.md
index 38801c73..46512f4e 100644
--- a/SUPPORT.md
+++ b/SUPPORT.md
@@ -20,8 +20,8 @@ Self-serve, ordered by likelihood of containing the answer:
 2. [docs/getting-started.md](docs/getting-started.md) — first runnable example.
 3. [examples/README.md](examples/README.md) — runnable examples with PDF previews.
 4. [docs/recipes.md](docs/recipes.md) — patterns for common layouts.
-5. [docs/architecture.md](docs/architecture.md) and [docs/package-map.md](docs/package-map.md) — when extending the engine.
-6. [docs/migration-v1-5-to-v1-6.md](docs/migration-v1-5-to-v1-6.md) — upgrades from previous minor.
+5. [docs/architecture/overview.md](docs/architecture/overview.md) and [docs/architecture/package-map.md](docs/architecture/package-map.md) — when extending the engine.
+6. [docs/roadmaps/migration-v1-5-to-v1-6.md](docs/roadmaps/migration-v1-5-to-v1-6.md) — upgrades from previous minor.
 
 ## Response expectations
 
@@ -36,4 +36,4 @@ Best-effort. Triage typically within a week. Reports with minimal reproductions
 
 ## Contributing
 
-If you want to contribute rather than ask for help, see [CONTRIBUTING.md](CONTRIBUTING.md). Lane structure and architecture rules: [docs/architecture.md](docs/architecture.md).
+If you want to contribute rather than ask for help, see [CONTRIBUTING.md](CONTRIBUTING.md). Lane structure and architecture rules: [docs/architecture/overview.md](docs/architecture/overview.md).
diff --git a/docs/README.md b/docs/README.md
index c0a12903..539c3e0e 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,51 +1,104 @@
-# GraphCompose GitHub Pages Showcase
+# GraphCompose Documentation
 
-This folder contains the lightweight static showcase site for GraphCompose. It is intentionally plain HTML, CSS, JavaScript, and JSON so GitHub Pages can publish it directly from the main repository without a build step.
+Comprehensive docs for the engine, the templates, and the
+contribution workflow. Below is the map — pick your path.
 
-## Files
+If you're new to GraphCompose entirely, start at the
+[**root README**](../README.md) for the project overview, then come
+back here.
 
-- `index.html` is the single-page showcase.
-- `styles.css` contains the visual system and responsive layout.
-- `examples.json` is the gallery data source.
-- `assets/logo/` contains the showcase logo asset.
-- `assets/screenshots/` contains PNG previews for generated PDFs.
-- `assets/pdf/` contains the generated PDF examples linked from the gallery.
+---
 
-## Add A New Showcase Item
+## 🧭 By persona — start here
 
-1. Generate the PDF from the examples module.
-2. Copy the PDF into `docs/assets/pdf/`.
-3. Add a PNG screenshot into `docs/assets/screenshots/`.
-4. Add a new object to `docs/examples.json`.
-5. Commit and push.
+| You are… | Read |
+|---|---|
+| **New to GraphCompose** — what is it, how do I render my first PDF | [Getting started](getting-started.md) → [Hello world in root README](../README.md#hello-world) |
+| **Author rendering a CV** with your own data | [Templates v2 (layered) — quickstart](templates/v2-layered/quickstart.md) |
+| **Designer / author** wanting a custom visual style for CVs | [Templates v2 (layered) — authoring presets](templates/v2-layered/authoring-presets.md) |
+| **Author using legacy v1.6 templates** (CV / cover-letter / invoice / proposal still using `*Spec` + builders) | [Templates v1-classic — landing](templates/v1-classic/README.md) |
+| **Contributor adding a new template family** to the library | [Templates v2 (layered) — contributor guide](templates/v2-layered/contributor-guide.md) |
+| **Contributor extending the engine** (new node type, new backend handler) | [Extension guide](contributing/extension-guide.md) → [Implementation guide](contributing/implementation-guide.md) |
+| **Operator** running GraphCompose in production | [Production rendering](operations/production-rendering.md) → [Performance](operations/performance.md) → [Logging](operations/logging.md) |
 
-Each `examples.json` object uses this shape:
+---
 
-```json
-{
-  "title": "Cinematic Invoice",
-  "description": "A short description of the generated document.",
-  "tags": ["Template", "Tables", "Theme"],
-  "image": "assets/screenshots/invoice-v2.png",
-  "pdf": "assets/pdf/invoice-v2.pdf",
-  "code": "https://github.com/DemchaAV/GraphCompose/blob/main/examples/src/main/java/com/demcha/examples/InvoiceCinematicFileExample.java"
-}
-```
+## 📁 By category
 
-## Local Preview
+### Getting started
+- **[getting-started.md](getting-started.md)** — DSL vs templates, first-render walk-through, decision tree.
 
-Open `docs/index.html` directly in a browser for a quick visual check. If your browser blocks `fetch("examples.json")` for local `file://` pages, run any tiny static server from the repository root and open the `/docs/` path. No build step is required.
+### Templates
+- **[templates/v2-layered/](templates/v2-layered/)** — 🆕 canonical going-forward pattern (CV is the reference implementation): `data` / `theme` / `components` / `widgets` / `presets`.
+- **[templates/v1-classic/](templates/v1-classic/)** — the spec/builder/presets surface used by v1.6 CV, cover-letter, invoice, proposal templates. Still ships, still supported.
 
-## GitHub Pages
+### Architecture
+- **[architecture/overview.md](architecture/overview.md)** — high-level system architecture (engine + DSL + templates + backends).
+- **[architecture/lifecycle.md](architecture/lifecycle.md)** — the document lifecycle from `GraphCompose.document(...)` through `buildPdf()`.
+- **[architecture/pagination-ordering.md](architecture/pagination-ordering.md)** — how nodes are paginated and ordered.
+- **[architecture/package-map.md](architecture/package-map.md)** — what's in which package.
+- **[architecture/canonical-legacy-parity.md](architecture/canonical-legacy-parity.md)** — canonical (v1.5+) vs legacy compatibility matrix.
 
-To publish this site with GitHub Pages:
+### Operations
+- **[operations/production-rendering.md](operations/production-rendering.md)** — server-side rendering, streaming, thread safety.
+- **[operations/performance.md](operations/performance.md)** — perf characteristics + tuning.
+- **[operations/benchmarks.md](operations/benchmarks.md)** — how to run benchmarks; reference numbers.
+- **[operations/logging.md](operations/logging.md)** — logger configuration, what each logger emits.
+- **[operations/layout-snapshot-testing.md](operations/layout-snapshot-testing.md)** — snapshot-based layout regression testing.
 
-1. Open repository Settings.
-2. Go to Pages.
-3. Set Source to "Deploy from a branch".
-4. Select the main branch and `/docs` folder.
-5. Save.
+### Contributing
+- **[contributing/extension-guide.md](contributing/extension-guide.md)** — add a new node type, backend handler, or theme primitive.
+- **[contributing/implementation-guide.md](contributing/implementation-guide.md)** — internal engine notes for contributors hacking on layout / measurement / pagination.
+- **[contributing/release-process.md](contributing/release-process.md)** — versioning, tag procedure, JitPack publication.
 
-The site should become available at:
+### Roadmaps & migrations
+- **[roadmaps/v1.6-roadmap.md](roadmaps/v1.6-roadmap.md)** — current development roadmap.
+- **[roadmaps/migration-v1-5-to-v1-6.md](roadmaps/migration-v1-5-to-v1-6.md)** — upgrade guide for v1.5 → v1.6.
+- **[roadmaps/migration-v1-4-to-v1-5.md](roadmaps/migration-v1-4-to-v1-5.md)** — upgrade guide for v1.4 → v1.5.
 
-https://demchaav.github.io/GraphCompose/
+### Recipes (cookbook-style howtos)
+- **[recipes.md](recipes.md)** — index of all recipes.
+- **[recipes/shape-as-container.md](recipes/shape-as-container.md)** — shapes that hold child content.
+- **[recipes/transforms.md](recipes/transforms.md)** — rotation, scaling, skewing.
+- **[recipes/tables.md](recipes/tables.md)** — tabular layouts.
+- **[recipes/themes.md](recipes/themes.md)** — custom themes.
+- **[recipes/streaming.md](recipes/streaming.md)** — streaming PDFs to HTTP responses.
+- **[recipes/extending.md](recipes/extending.md)** — extension patterns by example.
+
+### Architecture Decision Records (ADRs)
+Numbered, dated decisions about non-trivial design choices. Read these
+when you need to understand *why* a piece of the system looks the way
+it does.
+
+- **[adr/0001-shape-as-container.md](adr/0001-shape-as-container.md)** — shape nodes as content containers.
+- **[adr/0002-theme-unification.md](adr/0002-theme-unification.md)** — single canonical theme model.
+- **[adr/0003-api-stability-and-internal-marker.md](adr/0003-api-stability-and-internal-marker.md)** — public-API guarantees + `@Internal` marker.
+- **[adr/0004-pdf-handler-spi-extension.md](adr/0004-pdf-handler-spi-extension.md)** — PDF render handler SPI.
+- **[adr/0011-templates-v2-architecture.md](adr/0011-templates-v2-architecture.md)** — the v1.6 templates restructure (spec/builder/presets/themes).
+- **[adr/0012-nested-list-evolution.md](adr/0012-nested-list-evolution.md)** — nested list rendering evolution.
+- **[adr/0013-composed-table-cell.md](adr/0013-composed-table-cell.md)** — composed table cell model.
+- **[adr/0014-controlled-absolute-placement.md](adr/0014-controlled-absolute-placement.md)** — controlled absolute placement strategy.
+
+> **ADR numbering gap (0005–0010)** is intentional — those numbers
+> were reserved during a v1.5 restructure that landed under ADR 0011
+> instead of multiple smaller records. No deleted ADRs.
+
+### Showcase site
+- **[SHOWCASE.md](SHOWCASE.md)** — how the GitHub Pages showcase is
+  built and how to add new examples to it. (Not documentation about
+  GraphCompose itself — this is meta-doc about the website at
+  https://demchaav.github.io/GraphCompose/.)
+
+### Archive
+- **[archive/](archive/)** — old migration guides and roadmaps kept
+  for historical reference. Not part of the live doc set.
+
+---
+
+## 🔗 Quick links
+
+- [Project root README](../README.md)
+- [CONTRIBUTING.md](../CONTRIBUTING.md)
+- [CHANGELOG.md](../CHANGELOG.md)
+- [Examples gallery](../examples/README.md)
+- [Live showcase site](https://demchaav.github.io/GraphCompose/)
diff --git a/docs/SHOWCASE.md b/docs/SHOWCASE.md
new file mode 100644
index 00000000..c0a12903
--- /dev/null
+++ b/docs/SHOWCASE.md
@@ -0,0 +1,51 @@
+# GraphCompose GitHub Pages Showcase
+
+This folder contains the lightweight static showcase site for GraphCompose. It is intentionally plain HTML, CSS, JavaScript, and JSON so GitHub Pages can publish it directly from the main repository without a build step.
+
+## Files
+
+- `index.html` is the single-page showcase.
+- `styles.css` contains the visual system and responsive layout.
+- `examples.json` is the gallery data source.
+- `assets/logo/` contains the showcase logo asset.
+- `assets/screenshots/` contains PNG previews for generated PDFs.
+- `assets/pdf/` contains the generated PDF examples linked from the gallery.
+
+## Add A New Showcase Item
+
+1. Generate the PDF from the examples module.
+2. Copy the PDF into `docs/assets/pdf/`.
+3. Add a PNG screenshot into `docs/assets/screenshots/`.
+4. Add a new object to `docs/examples.json`.
+5. Commit and push.
+
+Each `examples.json` object uses this shape:
+
+```json
+{
+  "title": "Cinematic Invoice",
+  "description": "A short description of the generated document.",
+  "tags": ["Template", "Tables", "Theme"],
+  "image": "assets/screenshots/invoice-v2.png",
+  "pdf": "assets/pdf/invoice-v2.pdf",
+  "code": "https://github.com/DemchaAV/GraphCompose/blob/main/examples/src/main/java/com/demcha/examples/InvoiceCinematicFileExample.java"
+}
+```
+
+## Local Preview
+
+Open `docs/index.html` directly in a browser for a quick visual check. If your browser blocks `fetch("examples.json")` for local `file://` pages, run any tiny static server from the repository root and open the `/docs/` path. No build step is required.
+
+## GitHub Pages
+
+To publish this site with GitHub Pages:
+
+1. Open repository Settings.
+2. Go to Pages.
+3. Set Source to "Deploy from a branch".
+4. Select the main branch and `/docs` folder.
+5. Save.
+
+The site should become available at:
+
+https://demchaav.github.io/GraphCompose/
diff --git a/docs/adr/0001-shape-as-container.md b/docs/adr/0001-shape-as-container.md
index 00f928ec..4f9ada54 100644
--- a/docs/adr/0001-shape-as-container.md
+++ b/docs/adr/0001-shape-as-container.md
@@ -123,7 +123,7 @@ We considered two alternatives.
   must continue to show empty allowlists. The pre-pass that resolves the
   outline geometry lives in `LayoutCompiler`, not in the public surface.
 - The DOCX backend gains documented limitations around `CLIP_PATH`. They are
-  recorded in `docs/canonical-legacy-parity.md` as part of B.6.
+  recorded in `docs/architecture/canonical-legacy-parity.md` as part of B.6.
 
 ## Implementation order (executed in B.2 → B.10)
 
diff --git a/docs/adr/0003-api-stability-and-internal-marker.md b/docs/adr/0003-api-stability-and-internal-marker.md
index 5f4a7198..4d2bcc03 100644
--- a/docs/adr/0003-api-stability-and-internal-marker.md
+++ b/docs/adr/0003-api-stability-and-internal-marker.md
@@ -85,7 +85,7 @@ right next to `DocumentSession`, so it is discoverable.
   in quick-doc and Javadoc). Existing call sites continue to compile
   and run; the annotation is a documentation signal, not a hard break.
   Migration guidance is published in
-  [`docs/migration-v1-5-to-v1-6.md`](../migration-v1-5-to-v1-6.md).
+  [`docs/roadmaps/migration-v1-5-to-v1-6.md`](../roadmaps/migration-v1-5-to-v1-6.md).
 - **For us:** Phase E.1 / E.2 (split `BuiltInNodeDefinitions`,
   relocate payload records) and Phase E.4 (extract `PlacementContext`)
   can now ship as internal refactors without semver implications. If a
diff --git a/docs/adr/0011-templates-v2-architecture.md b/docs/adr/0011-templates-v2-architecture.md
index 0c3fc07f..90ba8a34 100644
--- a/docs/adr/0011-templates-v2-architecture.md
+++ b/docs/adr/0011-templates-v2-architecture.md
@@ -124,7 +124,7 @@ Key design contracts:
    templates), `templates/support/cv` (15 composers),
    `templates/theme/CvTheme`, the `CvTemplate` interface — all
    removed. Migration table in `CHANGELOG.md` and
-   `docs/migration-v1-5-to-v1-6.md`. Cinematic V2 templates
+   `docs/roadmaps/migration-v1-5-to-v1-6.md`. Cinematic V2 templates
    (`InvoiceTemplateV2` / `ProposalTemplateV2`) are kept until the
    minimal v2 surface (`ModernInvoice` / `ModernProposal`) closes
    feature parity in a follow-up release.
@@ -204,7 +204,7 @@ references. The reopen made an explicit trade-off:
 - **Migration is breaking.** Anyone on
   `new CvTemplateV1()` / `new NordicCleanCvTemplate()` etc. must
   switch to the new factory (see migration table in `CHANGELOG.md`
-  and `docs/migration-v1-5-to-v1-6.md`).
+  and `docs/roadmaps/migration-v1-5-to-v1-6.md`).
 - **Cinematic V2 templates remain.** `InvoiceTemplateV2` /
   `ProposalTemplateV2` / `WeeklyScheduleTemplateV1` /
   `BuiltInCvTemplateSupport` stay in `templates/builtins/`. The
diff --git a/docs/adr/0012-nested-list-evolution.md b/docs/adr/0012-nested-list-evolution.md
index 876e2722..51339198 100644
--- a/docs/adr/0012-nested-list-evolution.md
+++ b/docs/adr/0012-nested-list-evolution.md
@@ -13,7 +13,7 @@ semantics (no per-depth bullet glyph), break pagination on
 splitting, and force the caller to re-implement a depth indent
 that any reasonable list primitive should provide.
 
-The v1.6 roadmap (`docs/v1.6-roadmap.md` Phase A) lands real
+The v1.6 roadmap (`docs/roadmaps/v1.6-roadmap.md` Phase A) lands real
 nested-list authoring with the public API:
 
 - `ListBuilder.addItem(String label, Consumer<ListBuilder> body)`
@@ -169,7 +169,7 @@ across mixed flat / nested entries.
 ## References
 
 - v1.6 roadmap, Phase A:
-  [`docs/v1.6-roadmap.md`](../v1.6-roadmap.md).
+  [`docs/roadmaps/v1.6-roadmap.md`](../roadmaps/v1.6-roadmap.md).
 - ADR 0003 — API stability and `@Internal` marker:
   [`0003-api-stability-and-internal-marker.md`](0003-api-stability-and-internal-marker.md)
   (gate that allows new components on existing records).
diff --git a/docs/adr/0013-composed-table-cell.md b/docs/adr/0013-composed-table-cell.md
index a220042f..1646055c 100644
--- a/docs/adr/0013-composed-table-cell.md
+++ b/docs/adr/0013-composed-table-cell.md
@@ -19,7 +19,7 @@ Authors who needed that today either:
 2. Composed the table fragment manually with the engine API
    (which v1.5 retired from the public surface).
 
-The v1.6 roadmap (`docs/v1.6-roadmap.md` Phase B) opens the cell
+The v1.6 roadmap (`docs/roadmaps/v1.6-roadmap.md` Phase B) opens the cell
 to any composable `DocumentNode`, with two-pass cell measurement
 and pagination preserving row-by-row behaviour.
 
@@ -190,7 +190,7 @@ etc.).
 ## References
 
 - v1.6 roadmap, Phase B:
-  [`docs/v1.6-roadmap.md`](../v1.6-roadmap.md).
+  [`docs/roadmaps/v1.6-roadmap.md`](../roadmaps/v1.6-roadmap.md).
 - ADR 0011 — Templates v2 architecture (consumer of composed
   cells in v1.7+):
   [`0011-templates-v2-architecture.md`](0011-templates-v2-architecture.md).
diff --git a/docs/adr/0014-controlled-absolute-placement.md b/docs/adr/0014-controlled-absolute-placement.md
index 365e1a11..a2630522 100644
--- a/docs/adr/0014-controlled-absolute-placement.md
+++ b/docs/adr/0014-controlled-absolute-placement.md
@@ -30,7 +30,7 @@ specific coordinates — currently reach for either:
 - The retired low-level `EntityManager` engine API that v1.5
   removed from the public surface.
 
-The v1.6 roadmap (`docs/v1.6-roadmap.md` Phase C) lands an
+The v1.6 roadmap (`docs/roadmaps/v1.6-roadmap.md` Phase C) lands an
 explicit "I want absolute placement" opt-in that is still a
 canonical node — not an engine bypass.
 
@@ -204,7 +204,7 @@ diagram authors who want overflow can opt into
 ## References
 
 - v1.6 roadmap, Phase C:
-  [`docs/v1.6-roadmap.md`](../v1.6-roadmap.md).
+  [`docs/roadmaps/v1.6-roadmap.md`](../roadmaps/v1.6-roadmap.md).
 - ADR 0001 — Shape-as-container (consumer of the same
   `ClipPolicy`):
   [`0001-shape-as-container.md`](0001-shape-as-container.md).
diff --git a/docs/canonical-legacy-parity.md b/docs/architecture/canonical-legacy-parity.md
similarity index 97%
rename from docs/canonical-legacy-parity.md
rename to docs/architecture/canonical-legacy-parity.md
index de637b28..0db4fdfc 100644
--- a/docs/canonical-legacy-parity.md
+++ b/docs/architecture/canonical-legacy-parity.md
@@ -33,7 +33,7 @@ compatibility concerns. New authoring features should be added through
 | Child horizontal alignment | Done via `LayerStack` / `ShapeContainer` | Use `LayerStackBuilder.topLeft(...)` … `bottomRight(...)` (nine alignment shortcuts) or `ShapeContainerBuilder` with the same vocabulary; v1.5 also exposes `position(node, offsetX, offsetY, anchor)` for screen-space nudges from an anchor. |
 | Child vertical alignment | Done via `LayerStack` / `ShapeContainer` | Same nine alignment anchors cover top, centre, bottom edges. |
 | Absolute placement | Rejected for normal authoring | Keep coordinates inside layout and backend internals. Use `LayerStack.position(...)` if you need anchor-plus-offset placement. |
-| Controlled free canvas (`CanvasLayerNode`) | Planned for v1.6 (stretch) | New atomic semantic node accepting children at explicit `(x, y)` coordinates. Separate from `LayerStackNode` and `ShapeContainerNode` so absolute placement stays an opt-in primitive, not a global policy. See [v1.6 roadmap, Phase C](./v1.6-roadmap.md). |
+| Controlled free canvas (`CanvasLayerNode`) | Planned for v1.6 (stretch) | New atomic semantic node accepting children at explicit `(x, y)` coordinates. Separate from `LayerStackNode` and `ShapeContainerNode` so absolute placement stays an opt-in primitive, not a global policy. See [v1.6 roadmap, Phase C](../roadmaps/v1.6-roadmap.md). |
 
 ## Visual Primitives
 
@@ -56,7 +56,7 @@ compatibility concerns. New authoring features should be added through
 | Paragraph wrapping | Done | Keep wrapping in paragraph layout preparation. |
 | Inline text/link runs | Done | Keep as paragraph-level semantic content. |
 | Lists | Done | Existing marker and indentation APIs remain canonical. |
-| Nested list ergonomics | Planned for v1.6 (committed) | `ListBuilder.addItem(label, Consumer<ListBuilder>)` plus a new `ListItem` value type and a `ListNode` record extension with back-compat constructor. See [v1.6 roadmap, Phase A](./v1.6-roadmap.md). |
+| Nested list ergonomics | Planned for v1.6 (committed) | `ListBuilder.addItem(label, Consumer<ListBuilder>)` plus a new `ListItem` value type and a `ListNode` record extension with back-compat constructor. See [v1.6 roadmap, Phase A](../roadmaps/v1.6-roadmap.md). |
 | Auto-size text | Done | Use `ParagraphBuilder.autoSize(maxSize, minSize)` to fit single-line headlines into the resolved inner width. |
 
 ## Images
@@ -80,7 +80,7 @@ compatibility concerns. New authoring features should be added through
 | Zebra rows | Done | `TableBuilder.zebra(odd, even)` (style or colour overload) alternates row fills. Applied lazily at `build()`; explicit `rowStyle(idx, ...)` always wins. |
 | Totals row | Done | `TableBuilder.totalRow(values)` appends a row with a default bold + subtle-fill style. `totalRow(style, values)` for a custom look. |
 | Repeated header on page break | Done | `TableBuilder.repeatHeader()` repeats the first row at the top of every continuation page; `repeatHeader(int n)` for multi-row headers. |
-| Complex cell composition | Planned for v1.6 (committed) | New `TableCellContent.NodeContent(DocumentNode child)` variant + `DocumentTableCell.node(DocumentNode)` factory. Two-pass cell measurement preserves row pagination behaviour. See [v1.6 roadmap, Phase B](./v1.6-roadmap.md). |
+| Complex cell composition | Planned for v1.6 (committed) | New `TableCellContent.NodeContent(DocumentNode child)` variant + `DocumentTableCell.node(DocumentNode)` factory. Two-pass cell measurement preserves row pagination behaviour. See [v1.6 roadmap, Phase B](../roadmaps/v1.6-roadmap.md). |
 
 ## PDF Output
 
@@ -92,7 +92,7 @@ compatibility concerns. New authoring features should be added through
 | Guide lines | Done | `guideLines(true)` is available on document builder and session. |
 | Metadata/protection/watermark/header/footer | Done | Configure on `DocumentSession` (e.g. `metadata(...)`, `watermark(...)`, `protect(...)`, `header(...)`, `footer(...)`); convenience PDF entrypoints (`buildPdf`, `writePdf`, `toPdfBytes`) honour these options without an explicit backend builder. `PdfFixedLayoutBackend.builder()` remains for advanced cases. |
 | DOCX semantic export | Done | Use `session.export(new DocxSemanticBackend())` for paragraph/table/image-aware Word output. Requires `org.apache.poi:poi-ooxml` on the consumer classpath. |
-| PPTX semantic export | Planned for v1.6 (stretch) | Build out `PptxSemanticBackend` from the existing manifest skeleton to a working POI-based exporter — paragraphs as text boxes, tables as PowerPoint tables, sections as slides. See [v1.6 roadmap, Phase D](./v1.6-roadmap.md). |
+| PPTX semantic export | Planned for v1.6 (stretch) | Build out `PptxSemanticBackend` from the existing manifest skeleton to a working POI-based exporter — paragraphs as text boxes, tables as PowerPoint tables, sections as slides. See [v1.6 roadmap, Phase D](../roadmaps/v1.6-roadmap.md). |
 | PDFBox types in session API | Rejected | Keep PDFBox behind the fixed PDF backend. |
 
 ## Diagnostics
diff --git a/docs/lifecycle.md b/docs/architecture/lifecycle.md
similarity index 97%
rename from docs/lifecycle.md
rename to docs/architecture/lifecycle.md
index 5ee376f9..b864ed60 100644
--- a/docs/lifecycle.md
+++ b/docs/architecture/lifecycle.md
@@ -98,4 +98,4 @@ The canonical PDF backend:
 
 Always close the session, normally with try-with-resources. Closing releases measurement resources and clears request-local text measurement caches. It does not require consumers to manage PDFBox objects directly.
 
-For production server guidance, see [Production Rendering](./production-rendering.md).
+For production server guidance, see [Production Rendering](../operations/production-rendering.md).
diff --git a/docs/architecture.md b/docs/architecture/overview.md
similarity index 98%
rename from docs/architecture.md
rename to docs/architecture/overview.md
index a48374a7..01676f5d 100644
--- a/docs/architecture.md
+++ b/docs/architecture/overview.md
@@ -299,7 +299,7 @@ GraphCompose uses a practical three-layer regression strategy:
 3. PDF render tests for visual smoke coverage and artifact
    inspection (`PdfVisualRegression`, `target/visual-tests/`)
 
-See [layout-snapshot-testing.md](./layout-snapshot-testing.md) for the
+See [layout-snapshot-testing.md](../operations/layout-snapshot-testing.md) for the
 snapshot workflow and developer conventions.
 
 ## Maintenance references
@@ -308,7 +308,7 @@ snapshot workflow and developer conventions.
   package ownership and extension rules.
 - [lifecycle.md](./lifecycle.md) describes the document session,
   layout, pagination, and render lifecycle.
-- [logging.md](./logging.md) documents the quiet-by-default lifecycle
+- [logging.md](../operations/logging.md) documents the quiet-by-default lifecycle
   logger categories.
 - [canonical-legacy-parity.md](./canonical-legacy-parity.md) tracks
   feature parity between the canonical authoring surface and older
diff --git a/docs/package-map.md b/docs/architecture/package-map.md
similarity index 100%
rename from docs/package-map.md
rename to docs/architecture/package-map.md
diff --git a/docs/pagination-ordering.md b/docs/architecture/pagination-ordering.md
similarity index 100%
rename from docs/pagination-ordering.md
rename to docs/architecture/pagination-ordering.md
diff --git a/docs/archive/README.md b/docs/archive/README.md
index 9c72f822..b3da7048 100644
--- a/docs/archive/README.md
+++ b/docs/archive/README.md
@@ -11,11 +11,11 @@ The current docs live under [`docs/`](../) at the repository root:
 - [`docs/recipes.md`](../recipes.md) and the
   [`docs/recipes/`](../recipes/) folder — copy-paste catalogues per
   feature area.
-- [`docs/canonical-legacy-parity.md`](../canonical-legacy-parity.md) —
+- [`docs/architecture/canonical-legacy-parity.md`](../architecture/canonical-legacy-parity.md) —
   living parity matrix.
-- [`docs/architecture.md`](../architecture.md),
-  [`docs/lifecycle.md`](../lifecycle.md),
-  [`docs/package-map.md`](../package-map.md) — internal architecture
+- [`docs/architecture/overview.md`](../architecture/overview.md),
+  [`docs/architecture/lifecycle.md`](../architecture/lifecycle.md),
+  [`docs/architecture/package-map.md`](../architecture/package-map.md) — internal architecture
   references.
 
 ## What's archived
@@ -23,4 +23,4 @@ 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/migration-v1-4-to-v1-5.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`. |
diff --git a/docs/archive/migration-v1-1-to-v1-2.md b/docs/archive/migration-v1-1-to-v1-2.md
index 749e1e20..590b941d 100644
--- a/docs/archive/migration-v1-1-to-v1-2.md
+++ b/docs/archive/migration-v1-1-to-v1-2.md
@@ -115,7 +115,7 @@ After switching, run:
 
 ## Where to go next
 
-- [Getting Started](./getting-started.md)
-- [Recipes](./recipes.md)
-- [Lifecycle](./lifecycle.md)
+- [Getting Started](../getting-started.md)
+- [Recipes](../recipes.md)
+- [Lifecycle](../architecture/lifecycle.md)
 - [v1.2 Roadmap](./v1.2-roadmap.md)
diff --git a/docs/archive/v1.2-roadmap.md b/docs/archive/v1.2-roadmap.md
index d13b6b56..fb934414 100644
--- a/docs/archive/v1.2-roadmap.md
+++ b/docs/archive/v1.2-roadmap.md
@@ -139,7 +139,7 @@ Current conversions are centralized in `document.layout.DocumentNodeAdapters`. T
 ## Phase 8 - Documentation polish - Partially complete
 
 - [x] README is short and focused on value, installation, quick start, concepts, and docs.
-- [x] `docs/getting-started.md`, `docs/recipes.md`, `docs/architecture.md`, `docs/package-map.md`, `docs/lifecycle.md`, `docs/production-rendering.md`, `docs/layout-snapshot-testing.md`, `docs/benchmarks.md`, and `docs/release-process.md` exist.
+- [x] `docs/getting-started.md`, `docs/recipes.md`, `docs/architecture/overview.md`, `docs/architecture/package-map.md`, `docs/architecture/lifecycle.md`, `docs/operations/production-rendering.md`, `docs/operations/layout-snapshot-testing.md`, `docs/operations/benchmarks.md`, and `docs/contributing/release-process.md` exist.
 - [x] Migration docs now target v1.1 to v1.2 canonical API adoption.
 - [ ] Keep examples checked against documentation tests as new snippets are added.
 
@@ -148,7 +148,7 @@ Current conversions are centralized in `document.layout.DocumentNodeAdapters`. T
 - [x] groupId `io.github.demchaav`
 - [x] artifactId `graphcompose`
 - [x] version `1.2.0`
-- [x] JitPack-first release checklist in `docs/release-process.md`
+- [x] JitPack-first release checklist in `docs/contributing/release-process.md`
 - [x] Runnable examples module builds separately through `examples/pom.xml`
 - [x] Create local release tag `v1.2.0` after final verification.
 - [x] GitHub draft release targets the current `v1.2.0` tag / commit.
diff --git a/docs/extension-guide.md b/docs/contributing/extension-guide.md
similarity index 97%
rename from docs/extension-guide.md
rename to docs/contributing/extension-guide.md
index 425e924e..2af90eb1 100644
--- a/docs/extension-guide.md
+++ b/docs/contributing/extension-guide.md
@@ -230,16 +230,16 @@ locate the responsible file:
 | Engine ECS internals | `com.demcha.compose.engine.*` (don't reach in from canonical code) |
 
 Detailed ownership lives in
-[`docs/package-map.md`](package-map.md).
+[`docs/architecture/package-map.md`](package-map.md).
 
 ## See also
 
-- [`docs/architecture.md`](architecture.md) — high-level architecture
+- [`docs/architecture/overview.md`](architecture.md) — high-level architecture
   and the canonical-vs-engine boundary.
-- [`docs/implementation-guide.md`](implementation-guide.md) —
+- [`docs/contributing/implementation-guide.md`](implementation-guide.md) —
   engine-side ECS extension patterns (component records, system
   registration, low-level harness builders).
-- [`docs/lifecycle.md`](lifecycle.md) — the session, layout, and
+- [`docs/architecture/lifecycle.md`](lifecycle.md) — the session, layout, and
   render flow end-to-end.
 - [ADR 0001 — Shape-as-container](adr/0001-shape-as-container.md) —
   the design rationale that shaped the v1.5 `ShapeContainerNode`,
diff --git a/docs/implementation-guide.md b/docs/contributing/implementation-guide.md
similarity index 98%
rename from docs/implementation-guide.md
rename to docs/contributing/implementation-guide.md
index ee554201..340ef547 100644
--- a/docs/implementation-guide.md
+++ b/docs/contributing/implementation-guide.md
@@ -371,7 +371,7 @@ Recommended rule:
 
 Prefer pairing a snapshot assertion with an existing render test when the document is complex or business-critical.
 
-See [layout-snapshot-testing.md](./layout-snapshot-testing.md) for the baseline locations, update flow, and concrete examples.
+See [layout-snapshot-testing.md](../operations/layout-snapshot-testing.md) for the baseline locations, update flow, and concrete examples.
 
 So if your new object needs custom drawing, it is not enough to add a builder. You also need a renderable component with the correct renderer implementation.
 
@@ -402,7 +402,7 @@ Use the helpers directly when that intent is what you need:
 - read bounds and edges through `EntityBounds` instead of adding more bound helpers to `Entity`
 - update parent container size or shifted positions through `ParentContainerUpdater` instead of growing the `Entity` API further
 
-See [pagination-ordering.md](./pagination-ordering.md) for a focused explanation of this rule, including why a `Circle` case can fail while an `Image` case appears to work.
+See [pagination-ordering.md](../architecture/pagination-ordering.md) for a focused explanation of this rule, including why a `Circle` case can fail while an `Image` case appears to work.
 
 If those components are missing or inconsistent, the renderer cannot save you later.
 
diff --git a/docs/release-process.md b/docs/contributing/release-process.md
similarity index 100%
rename from docs/release-process.md
rename to docs/contributing/release-process.md
diff --git a/docs/getting-started.md b/docs/getting-started.md
index f8eed055..66b39dc9 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -201,10 +201,10 @@ try (DocumentSession document = GraphCompose.document(Path.of("invoice.pdf")).cr
   per-layer z-index for overlays.
 - [Advanced tables](./recipes/tables.md) — row span, zebra rows,
   totals row, repeating header on page break.
-- [Canonical Legacy-Parity Matrix](./canonical-legacy-parity.md) — what
+- [Canonical Legacy-Parity Matrix](./architecture/canonical-legacy-parity.md) — what
   works today, what is `Partial`, what is `Planned`.
-- [Lifecycle](./lifecycle.md) — the session, layout, and render flow.
-- [Production Rendering](./production-rendering.md) — server-side
+- [Lifecycle](./architecture/lifecycle.md) — the session, layout, and render flow.
+- [Production Rendering](./operations/production-rendering.md) — server-side
   lifecycle, privacy, and load guidance.
-- [Package Map](./package-map.md) — read this before adding new public
+- [Package Map](./architecture/package-map.md) — read this before adding new public
   APIs or engine internals.
diff --git a/docs/benchmarks.md b/docs/operations/benchmarks.md
similarity index 98%
rename from docs/benchmarks.md
rename to docs/operations/benchmarks.md
index fef678d3..f946ad64 100644
--- a/docs/benchmarks.md
+++ b/docs/operations/benchmarks.md
@@ -9,7 +9,7 @@ The short version is:
 - current-speed diffs are only valid between reports from the same profile
 - repeated local runs should be compared via median aggregation, not by eyeballing one lucky run
 
-If you are changing layout, pagination, render ordering, PDF session lifetime, or benchmark tooling, read this file together with [README.md](./../README.md), [architecture.md](./architecture.md), and [CONTRIBUTING.md](./../CONTRIBUTING.md).
+If you are changing layout, pagination, render ordering, PDF session lifetime, or benchmark tooling, read this file together with [README.md](../../README.md), [architecture.md](../architecture/overview.md), and [CONTRIBUTING.md](../../CONTRIBUTING.md).
 
 ## Core terms
 
diff --git a/docs/layout-snapshot-testing.md b/docs/operations/layout-snapshot-testing.md
similarity index 100%
rename from docs/layout-snapshot-testing.md
rename to docs/operations/layout-snapshot-testing.md
diff --git a/docs/logging.md b/docs/operations/logging.md
similarity index 100%
rename from docs/logging.md
rename to docs/operations/logging.md
diff --git a/docs/performance.md b/docs/operations/performance.md
similarity index 98%
rename from docs/performance.md
rename to docs/operations/performance.md
index ebb385d0..ecf02c5b 100644
--- a/docs/performance.md
+++ b/docs/operations/performance.md
@@ -7,7 +7,7 @@ and `stress` suites in sequence. They were captured on a developer
 laptop; CI machines are typically 1.5–2× slower. The benchmark
 methodology, profiles, GC stabilisation, percentile rule, and how to
 compare two runs locally are documented in
-[docs/benchmarks.md](./benchmarks.md).
+[docs/operations/benchmarks.md](./benchmarks.md).
 
 ## End-to-end latency
 
diff --git a/docs/production-rendering.md b/docs/operations/production-rendering.md
similarity index 100%
rename from docs/production-rendering.md
rename to docs/operations/production-rendering.md
diff --git a/docs/recipes/extending.md b/docs/recipes/extending.md
index 022f50b9..fa55afb5 100644
--- a/docs/recipes/extending.md
+++ b/docs/recipes/extending.md
@@ -2,15 +2,15 @@
 
 Short cheatsheets for the four most common extension paths. Each
 section gives you a 30-second mental model plus a pointer to the deep
-walkthrough in [`docs/extension-guide.md`](../extension-guide.md),
+walkthrough in [`docs/contributing/extension-guide.md`](../contributing/extension-guide.md),
 which uses the v1.5 `ShapeContainerNode` work as a worked example.
 
 | You want to... | Touch | Read |
 | --- | --- | --- |
-| Add a new semantic node | `DocumentNode` record + `NodeDefinition` + render handler | [Extension guide § 1](../extension-guide.md#1-add-a-semantic-node) |
-| Add a fluent setter | One `*Builder` only | [Extension guide § 2](../extension-guide.md#2-add-a-fluent-setter-to-a-builder) |
-| Add a render backend | Implement `FixedLayoutBackend` or `SemanticBackend` | [Extension guide § 3](../extension-guide.md#3-add-a-render-backend) |
-| Pin layout in a snapshot test | Use `LayoutSnapshotAssertions.assertMatches` | [Extension guide § 4](../extension-guide.md#4-validate-a-custom-nodes-layout-via-snapshots) |
+| Add a new semantic node | `DocumentNode` record + `NodeDefinition` + render handler | [Extension guide § 1](../contributing/extension-guide.md#1-add-a-semantic-node) |
+| Add a fluent setter | One `*Builder` only | [Extension guide § 2](../contributing/extension-guide.md#2-add-a-fluent-setter-to-a-builder) |
+| Add a render backend | Implement `FixedLayoutBackend` or `SemanticBackend` | [Extension guide § 3](../contributing/extension-guide.md#3-add-a-render-backend) |
+| Pin layout in a snapshot test | Use `LayoutSnapshotAssertions.assertMatches` | [Extension guide § 4](../contributing/extension-guide.md#4-validate-a-custom-nodes-layout-via-snapshots) |
 
 ## 1. Add a semantic node — five-step skeleton
 
@@ -25,7 +25,7 @@ which uses the v1.5 `ShapeContainerNode` work as a worked example.
 The Phase B `ShapeContainerNode`, `ShapeContainerDefinition`,
 `ShapeFragmentPayload`, and `PdfShape*RenderHandler` files are the
 canonical worked example. Walk
-[`docs/extension-guide.md`](../extension-guide.md) for the full
+[`docs/contributing/extension-guide.md`](../contributing/extension-guide.md) for the full
 narrative.
 
 ## 2. Add a fluent setter — single-builder change
@@ -94,7 +94,7 @@ for a runnable end-to-end demonstration.
 
 ## See also
 
-- [Extension guide](../extension-guide.md) — long-form walkthrough
+- [Extension guide](../contributing/extension-guide.md) — long-form walkthrough
   with the `ShapeContainerNode` worked example.
 - [Streaming and output](streaming.md) — how custom backends slot
   into the existing `writePdf` / `toPdfBytes` / `export(...)` paths.
diff --git a/docs/recipes/shape-as-container.md b/docs/recipes/shape-as-container.md
index fd77a39b..2c0d5cb8 100644
--- a/docs/recipes/shape-as-container.md
+++ b/docs/recipes/shape-as-container.md
@@ -133,7 +133,7 @@ outline frame and without clipping, and logs a one-time
 `docx.export.shape-container-fallback` capability warning per export
 pass. Authors who need the outline must export to PDF.
 
-This is documented in [canonical-legacy-parity.md](../canonical-legacy-parity.md)
+This is documented in [canonical-legacy-parity.md](../architecture/canonical-legacy-parity.md)
 under the "Surfaces and structure" section.
 
 ## How the rendering pipeline emits a clipped container
diff --git a/docs/recipes/streaming.md b/docs/recipes/streaming.md
index 14fc5d5c..3c962938 100644
--- a/docs/recipes/streaming.md
+++ b/docs/recipes/streaming.md
@@ -95,7 +95,7 @@ try (DocumentSession document = GraphCompose.document().create()) {
 The DOCX path is semantic — it preserves paragraphs, tables, images,
 and module structure but ignores fixed-layout concerns (page
 backgrounds, exact placement, graphics-state clip paths). See the
-[parity matrix](../canonical-legacy-parity.md) for the per-feature
+[parity matrix](../architecture/canonical-legacy-parity.md) for the per-feature
 mapping.
 
 ## Header / footer chrome
@@ -142,9 +142,9 @@ try (DocumentSession document = GraphCompose.document(Path.of("debug.pdf"))
 
 - [`docs/getting-started.md`](../getting-started.md) — covers the
   three convenience output flows in the quick-start section.
-- [`docs/production-rendering.md`](../production-rendering.md) —
+- [`docs/operations/production-rendering.md`](../operations/production-rendering.md) —
   server-side lifecycle, privacy, and load guidance for production
   HTTP / queue paths.
-- [`docs/canonical-legacy-parity.md`](../canonical-legacy-parity.md) —
+- [`docs/architecture/canonical-legacy-parity.md`](../architecture/canonical-legacy-parity.md) —
   PDF Output section lists every chrome / metadata / protection /
   watermark / header / footer option.
diff --git a/docs/recipes/themes.md b/docs/recipes/themes.md
index 585bb2ee..35e8a236 100644
--- a/docs/recipes/themes.md
+++ b/docs/recipes/themes.md
@@ -132,6 +132,6 @@ for the mapping table and the rationale.
 - [Tables](tables.md) — the table style overrides used by
   `headerStyle(...)`, `totalRow(...)`, and `zebra(...)` accept full
   `DocumentTableStyle` values, so they pick up theme palettes.
-- [`docs/canonical-legacy-parity.md`](../canonical-legacy-parity.md) —
+- [`docs/architecture/canonical-legacy-parity.md`](../architecture/canonical-legacy-parity.md) —
   the parity matrix lists every theme-aware style override that
   v1.5 supports.
diff --git a/docs/migration-v1-4-to-v1-5.md b/docs/roadmaps/migration-v1-4-to-v1-5.md
similarity index 100%
rename from docs/migration-v1-4-to-v1-5.md
rename to docs/roadmaps/migration-v1-4-to-v1-5.md
diff --git a/docs/migration-v1-5-to-v1-6.md b/docs/roadmaps/migration-v1-5-to-v1-6.md
similarity index 99%
rename from docs/migration-v1-5-to-v1-6.md
rename to docs/roadmaps/migration-v1-5-to-v1-6.md
index 6052e213..f2974e52 100644
--- a/docs/migration-v1-5-to-v1-6.md
+++ b/docs/roadmaps/migration-v1-5-to-v1-6.md
@@ -332,7 +332,7 @@ try (DocumentSession session = GraphCompose.document(out).create()) {
 ```
 
 The full builder fluent surface and module / block taxonomy are
-documented in [`docs/template-authoring.md`](template-authoring.md).
+documented in [`docs/templates/v1-classic/authoring.md`](template-authoring.md).
 The full gallery of v2 CV / cover-letter renders lives under
 [`assets/readme/examples/`](../assets/readme/examples/) and is
 regenerable via
diff --git a/docs/v1.6-roadmap.md b/docs/roadmaps/v1.6-roadmap.md
similarity index 95%
rename from docs/v1.6-roadmap.md
rename to docs/roadmaps/v1.6-roadmap.md
index f8817df7..8477ba48 100644
--- a/docs/v1.6-roadmap.md
+++ b/docs/roadmaps/v1.6-roadmap.md
@@ -308,7 +308,7 @@ Every phase ships only when:
 - the matching `docs/recipes/*.md` and a runnable example under
   `examples/src/main/java/com/demcha/examples/` exist
 - the matching ADR is committed to `docs/adr/`
-- `docs/canonical-legacy-parity.md` is updated to reflect the new
+- `docs/architecture/canonical-legacy-parity.md` is updated to reflect the new
   feature's parity status (Partial → Done where applicable)
 
 ## Out-of-scope but tracked
@@ -329,11 +329,11 @@ roadmap:
 - Maven coordinates `io.github.demchaav:graphcompose:1.6.0`
 - JitPack coordinates `com.github.demchaav:GraphCompose:v1.6.0`
 - Tag `v1.6.0` on `main` after develop merge
-- Migration guide at `docs/migration-v1-5-to-v1-6.md`
+- Migration guide at `docs/roadmaps/migration-v1-5-to-v1-6.md`
 
 ## References
 
-- [docs/canonical-legacy-parity.md](./canonical-legacy-parity.md) — feature parity matrix
-- [docs/template-authoring.md](./template-authoring.md) — current authoring cheatsheet
-- [docs/release-process.md](./release-process.md) — release checklist
-- [CHANGELOG.md](../CHANGELOG.md) — `## v1.6.0 — Planned` section mirrors this roadmap's committed scope
+- [docs/architecture/canonical-legacy-parity.md](../architecture/canonical-legacy-parity.md) — feature parity matrix
+- [docs/templates/v1-classic/authoring.md](../templates/v1-classic/authoring.md) — current authoring cheatsheet
+- [docs/contributing/release-process.md](../contributing/release-process.md) — release checklist
+- [CHANGELOG.md](../../CHANGELOG.md) — `## v1.6.0 — Planned` section mirrors this roadmap's committed scope
diff --git a/docs/templates-v2.md b/docs/templates/v1-classic/README.md
similarity index 86%
rename from docs/templates-v2.md
rename to docs/templates/v1-classic/README.md
index a7a39cd7..f1ee9bce 100644
--- a/docs/templates-v2.md
+++ b/docs/templates/v1-classic/README.md
@@ -1,4 +1,18 @@
-# Templates v2 &mdash; CV, cover letter, invoice, proposal
+# Templates v1-classic &mdash; CV, cover letter, invoice, proposal
+
+> ⚠️ **Naming clarification.** This page describes the **v1.6
+> "Templates v2"** surface — the rebuilt canonical templates that
+> shipped in v1.6 with `*Spec` records + `*Builder` + presets. The
+> codebase still calls this layer "Templates v2" internally (see
+> [ADR 0011](../../adr/0011-templates-v2-architecture.md)).
+>
+> The **newer layered architecture** for v2 templates (data /
+> theme / components / widgets / presets, with `CvDocument` rather
+> than `CvSpec`) lives at
+> **[templates/v2-layered/](../v2-layered/README.md)** and is the
+> recommended path for new template families going forward.
+>
+> Both surfaces coexist today; neither is deprecated yet.
 
 GraphCompose v1.6 ships a rebuilt canonical template surface for the four
 business document shapes: **CV, cover letter, invoice, proposal**. Every
@@ -9,9 +23,9 @@ caller learns it once and reuses it everywhere.
 This page is a landing reference. For a full conceptual walk-through
 (four-layer architecture, when to extend a preset vs. write your own,
 how rendering decisions cascade through theme tokens), read
-[`docs/template-authoring.md`](./template-authoring.md). For the v1 → v2
-upgrade table (every old class → its v2 replacement, with before/after
-code), read [`docs/migration-v1-5-to-v1-6.md`](./migration-v1-5-to-v1-6.md).
+[`./authoring.md`](./authoring.md). For the v1 → v2 upgrade table
+(every old class → its v2 replacement, with before/after code), read
+[`../../roadmaps/migration-v1-5-to-v1-6.md`](../../roadmaps/migration-v1-5-to-v1-6.md).
 
 ---
 
@@ -130,4 +144,4 @@ Legacy CV / cover-letter classes (`CvTemplateV1`, `NordicCleanCvTemplate`,
 v1.6. Any code constructing those classes must switch to the matching v2
 preset's `create(BusinessTheme)` factory. The full mapping (every old
 class → its v2 replacement, with side-by-side code) is documented in
-[`docs/migration-v1-5-to-v1-6.md`](./migration-v1-5-to-v1-6.md).
+[`docs/roadmaps/migration-v1-5-to-v1-6.md`](../../roadmaps/migration-v1-5-to-v1-6.md).
diff --git a/docs/template-authoring.md b/docs/templates/v1-classic/authoring.md
similarity index 96%
rename from docs/template-authoring.md
rename to docs/templates/v1-classic/authoring.md
index 8dfc3f9c..3780229d 100644
--- a/docs/template-authoring.md
+++ b/docs/templates/v1-classic/authoring.md
@@ -1,14 +1,25 @@
-# Template authoring — canonical cheatsheet
+# Template authoring — v1-classic cheatsheet
+
+> ⚠️ **For the v1.6 "Templates v2" surface** (`CvSpec`, `CvBuilder`,
+> `*Presets` with `BusinessTheme`). Still shipped and maintained.
+>
+> **Writing a new template family from scratch?** The newer layered
+> architecture is the canonical going-forward path —
+> [templates/v2-layered/authoring-presets.md](../v2-layered/authoring-presets.md)
+> shows the widget-composition pattern (much shorter presets, fewer
+> classes to maintain).
+>
+> **Authoring against existing v1-classic templates?** Keep reading.
 
 This page is the single reference for writing new templates and DSL
 code without boilerplate. Read it once before starting a template;
 keep it open while you're writing one.
 
 The companion long-form docs are
-[`getting-started.md`](getting-started.md) (concepts) and
-[`extension-guide.md`](extension-guide.md) (engine internals). When
-the cheatsheet says "see X recipe", the file lives under
-[`recipes/`](recipes/).
+[`../../getting-started.md`](../../getting-started.md) (concepts) and
+[`../../contributing/extension-guide.md`](../../contributing/extension-guide.md)
+(engine internals). When the cheatsheet says "see X recipe", the
+file lives under [`../../recipes/`](../../recipes/).
 
 ---
 
diff --git a/docs/templates-layered/README.md b/docs/templates/v2-layered/README.md
similarity index 85%
rename from docs/templates-layered/README.md
rename to docs/templates/v2-layered/README.md
index e6894904..d9f484f4 100644
--- a/docs/templates-layered/README.md
+++ b/docs/templates/v2-layered/README.md
@@ -1,5 +1,15 @@
 # Templates — Layered Architecture
 
+> ⚠️ **Naming clarification.** This is the **layered** template
+> architecture (data / theme / components / widgets / presets), the
+> going-forward canonical pattern. Package:
+> `com.demcha.compose.document.templates.cv.v2`.
+>
+> **Not to be confused with** the older v1.6 "Templates v2" surface
+> (`CvSpec`, `CvBuilder`, presets with `BusinessTheme`) — that lives
+> in [templates/v1-classic/](../v1-classic/README.md) and still ships
+> alongside this one.
+
 The **canonical going-forward pattern** for building business documents
 on GraphCompose. CV is the reference implementation today
 (`com.demcha.compose.document.templates.cv.v2`); invoice, cover-letter,
@@ -103,16 +113,16 @@ The detailed contract for each layer is in
 ## See also
 
 - **Per-package JavaDocs**:
-  [`cv/v2/package-info.java`](../../src/main/java/com/demcha/compose/document/templates/cv/v2/package-info.java)
+  [`cv/v2/package-info.java`](../../../src/main/java/com/demcha/compose/document/templates/cv/v2/package-info.java)
   has the ASCII diagram and 4-step author walkthrough.
 - **AUTHORS.md**:
-  [`cv/v2/AUTHORS.md`](../../src/main/java/com/demcha/compose/document/templates/cv/v2/AUTHORS.md)
+  [`cv/v2/AUTHORS.md`](../../../src/main/java/com/demcha/compose/document/templates/cv/v2/AUTHORS.md)
   is the recipe cookbook — 7 hands-on recipes from "change a bullet
   glyph" to "add a new section subtype".
 - **Examples**:
   [`examples/cv/v2/`](../../examples/src/main/java/com/demcha/examples/templates/cv/v2)
   has three runnable rendering examples — one per shipped preset.
 - **Legacy v1 surface**:
-  [`docs/templates-v2.md`](../templates-v2.md) describes the older
+  [`docs/templates/v1-classic/README.md`](../v1-classic/README.md) describes the older
   spec / preset / theme split used by the v1 templates. Still valid
   for the v1 packages; superseded by this guide for v2 work.
diff --git a/docs/templates-layered/authoring-presets.md b/docs/templates/v2-layered/authoring-presets.md
similarity index 99%
rename from docs/templates-layered/authoring-presets.md
rename to docs/templates/v2-layered/authoring-presets.md
index a5b013f2..385e7328 100644
--- a/docs/templates-layered/authoring-presets.md
+++ b/docs/templates/v2-layered/authoring-presets.md
@@ -347,4 +347,4 @@ cover-letter-v2) following the same layered shape?
 
 → The full recipe cookbook (with code for every customisation
 combo):
-[`cv/v2/AUTHORS.md`](../../src/main/java/com/demcha/compose/document/templates/cv/v2/AUTHORS.md)
+[`cv/v2/AUTHORS.md`](../../../src/main/java/com/demcha/compose/document/templates/cv/v2/AUTHORS.md)
diff --git a/docs/templates-layered/contributor-guide.md b/docs/templates/v2-layered/contributor-guide.md
similarity index 99%
rename from docs/templates-layered/contributor-guide.md
rename to docs/templates/v2-layered/contributor-guide.md
index b5565eaf..9942a89b 100644
--- a/docs/templates-layered/contributor-guide.md
+++ b/docs/templates/v2-layered/contributor-guide.md
@@ -291,7 +291,7 @@ a reference render) is encouraged but optional today.
       conditional sections.
 - [ ] `<family>/v2/<sub-package>/package-info.java` — each
       sub-package gets a paragraph explaining its role.
-- [ ] **Update [`docs/templates-layered/README.md`](README.md)** to
+- [ ] **Update [`docs/templates/v2-layered/README.md`](README.md)** to
       list the new family in the "implementations" section.
 
 ---
diff --git a/docs/templates-layered/quickstart.md b/docs/templates/v2-layered/quickstart.md
similarity index 98%
rename from docs/templates-layered/quickstart.md
rename to docs/templates/v2-layered/quickstart.md
index f7e4e0bb..8d7de664 100644
--- a/docs/templates-layered/quickstart.md
+++ b/docs/templates/v2-layered/quickstart.md
@@ -138,5 +138,5 @@ touch a renderer. A new widget doesn't touch the data model.
 | Render your own CV with your data | [using-templates.md](using-templates.md) |
 | Make a new visual style | [authoring-presets.md](authoring-presets.md) |
 | Add a new template family to the library (invoice, cover-letter) | [contributor-guide.md](contributor-guide.md) |
-| See hands-on recipes (change a bullet, swap colours, …) | [`cv/v2/AUTHORS.md`](../../src/main/java/com/demcha/compose/document/templates/cv/v2/AUTHORS.md) |
+| See hands-on recipes (change a bullet, swap colours, …) | [`cv/v2/AUTHORS.md`](../../../src/main/java/com/demcha/compose/document/templates/cv/v2/AUTHORS.md) |
 | Run the shipped examples | [`examples/cv/v2/`](../../examples/src/main/java/com/demcha/examples/templates/cv/v2) |
diff --git a/docs/templates-layered/using-templates.md b/docs/templates/v2-layered/using-templates.md
similarity index 98%
rename from docs/templates-layered/using-templates.md
rename to docs/templates/v2-layered/using-templates.md
index 49c40aec..94b499a9 100644
--- a/docs/templates-layered/using-templates.md
+++ b/docs/templates/v2-layered/using-templates.md
@@ -247,7 +247,7 @@ CvTheme theme = new CvTheme(
 ```
 
 For more recipes (compact spacing, alternative typography scales,
-etc.) see [`cv/v2/AUTHORS.md`](../../src/main/java/com/demcha/compose/document/templates/cv/v2/AUTHORS.md).
+etc.) see [`cv/v2/AUTHORS.md`](../../../src/main/java/com/demcha/compose/document/templates/cv/v2/AUTHORS.md).
 
 ---
 
@@ -347,4 +347,4 @@ No GitHub, no Projects, no Tech Skills — and the API doesn't notice.
 [**authoring-presets.md**](authoring-presets.md)
 
 → Reference for every recipe (change bullet, swap colours, …)
-[`cv/v2/AUTHORS.md`](../../src/main/java/com/demcha/compose/document/templates/cv/v2/AUTHORS.md)
+[`cv/v2/AUTHORS.md`](../../../src/main/java/com/demcha/compose/document/templates/cv/v2/AUTHORS.md)
diff --git a/examples/README.md b/examples/README.md
index 4b54d059..86d8e536 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -653,7 +653,7 @@ same bytes (verified by `LayoutSnapshotRegressionExample`).
 For the canonical authoring patterns — builder hierarchy, theme
 tokens, table presets, golden / anti-patterns, and a 40-line skeleton
 for new templates — read
-[**`docs/template-authoring.md`**](../docs/template-authoring.md)
+[**`docs/templates/v1-classic/authoring.md`**](../docs/templates/v1-classic/authoring.md)
 once before writing your own.
 
 ## Where things live
@@ -664,5 +664,5 @@ once before writing your own.
 | `examples/src/main/java/com/demcha/examples/support/` | Reusable helpers (`ExampleOutputPaths`, `WeeklyScheduleRenderer`) |
 | `examples/target/generated-pdfs/` | Output of running the examples (gitignored) |
 | `assets/readme/examples/` | Committed PDF previews linked from this gallery |
-| `docs/template-authoring.md` | Template authoring cheatsheet |
+| `docs/templates/v1-classic/authoring.md` | Template authoring cheatsheet |
 | `CHANGELOG.md` | Per-version surface changes (every example link is current to v1.6) |
diff --git a/src/test/java/com/demcha/documentation/CanonicalSurfaceGuardTest.java b/src/test/java/com/demcha/documentation/CanonicalSurfaceGuardTest.java
index 33f6c8de..20c9c6d9 100644
--- a/src/test/java/com/demcha/documentation/CanonicalSurfaceGuardTest.java
+++ b/src/test/java/com/demcha/documentation/CanonicalSurfaceGuardTest.java
@@ -47,7 +47,7 @@ class CanonicalSurfaceGuardTest {
             // Lists every retired V1 CV / cover-letter class so callers
             // can find the v2 replacement. Naming the legacy surface is
             // the explicit purpose of a migration log.
-            "docs/migration-v1-5-to-v1-6.md");
+            "docs/roadmaps/migration-v1-5-to-v1-6.md");
     private static final List<String> FORBIDDEN_PUBLIC_AUTHORING_IMPORTS = List.of(
             "import com.demcha.compose.engine.");
 
@@ -110,7 +110,7 @@ void publicAuthoringDocsAndExamplesShouldNotImportEngineInternals() throws IOExc
                         PROJECT_ROOT.resolve("README.md"),
                         PROJECT_ROOT.resolve("docs/getting-started.md"),
                         PROJECT_ROOT.resolve("docs/recipes.md"),
-                        PROJECT_ROOT.resolve("docs/layout-snapshot-testing.md"),
+                        PROJECT_ROOT.resolve("docs/operations/layout-snapshot-testing.md"),
                         PROJECT_ROOT.resolve("examples/src/main/java/com/demcha/examples"),
                         PROJECT_ROOT.resolve("src/test/java/com/demcha/documentation/DocumentationExamplesTest.java")));
     }