docs: reorganise into categorised folders + real docs index + link audit

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
 
 ---

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

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
 

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)
 

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).