docs(templates): point template docs at the extracted templates.core (#252)

Update the current template docs to the post-extraction names: the CV
theme is BrandTheme in templates.core.theme, and the markdown/text
helpers, header widgets, and shared widgets live under templates.core.*.

- package-map: add core.theme/text/identity/widgets rows, fold the old
  widgets+decorations entries into one core.widgets row, note MarkdownText
  moved to core.text.
- v2-layered guides, AUTHORS, which-template-system, api-stability,
  recipes, overview, CONTRIBUTING: CvTheme to BrandTheme,
  cv.v2.theme to core.theme, and corrected widget package homes.
- coverletter package-info: the reused renderer is
  core.text.RichParagraphRenderer.

Historical records (ADRs, CHANGELOG, migration guides) are left as
point-in-time records.

Author: DemchaAV

CONTRIBUTING.md

@@ -272,7 +272,7 @@ implementation; read it before starting yours.
 variant alongside `ModernProfessional`, a new invoice preset
 alongside `InvoiceTemplateV2`):
 
-- Constructor takes a `BusinessTheme` (or `CvTheme` for CV
+- Constructor takes a `BusinessTheme` (or `BrandTheme` 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()` /

docs/api-stability.md

@@ -28,7 +28,7 @@ matrix.
 
 | Tier | Marker | Used for | Breaking changes allowed in |
 |---|---|---|---|
-| **Stable** | _(default — no annotation)_ | The canonical authoring surface that user code is meant to call: `GraphCompose.document(...)`, `DocumentSession`, `DocumentDsl`, `RowBuilder` / `SectionBuilder` / `ParagraphBuilder` and friends, `DocumentInsets` / `DocumentColor` / `DocumentTextStyle`, the `BusinessTheme` and `CvTheme` factories, the recommended template presets in `cv.v2.*` and `coverletter.v2.*`. | **Major releases only.** |
+| **Stable** | _(default — no annotation)_ | The canonical authoring surface that user code is meant to call: `GraphCompose.document(...)`, `DocumentSession`, `DocumentDsl`, `RowBuilder` / `SectionBuilder` / `ParagraphBuilder` and friends, `DocumentInsets` / `DocumentColor` / `DocumentTextStyle`, the `BusinessTheme` and `BrandTheme` factories, the recommended template presets in `cv.v2.*` and `coverletter.v2.*`. | **Major releases only.** |
 | **Supported** | _(no annotation; called out in the page's Javadoc)_ | A canonical surface that ships through 1.x but won't be in 2.0 — its replacement is already the Stable path. The `cv.presets.*` "classic" CV preset surface is the only Supported tier in 1.x today (replaced by `cv.v2.*` per [`which-template-system.md`](templates/which-template-system.md)). Bug fixes + behaviour-preserving refactors only. | **Minor releases for behaviour-preserving refactors; removed wholesale in 2.0.** |
 | **Extension SPI** | [`@Beta`](../src/main/java/com/demcha/compose/document/api/Beta.java) | Public extension points that authors are expected to **implement**, not only call: render-handler interfaces, [`NodeDefinition`](../src/main/java/com/demcha/compose/document/layout/NodeDefinition.java), custom `Theme` subtype contracts, fragment payload interfaces designed for extension. | Minor releases, with a one-minor deprecation window where possible. |
 | **Experimental** | [`@Beta`](../src/main/java/com/demcha/compose/document/api/Beta.java) _(same annotation as Extension SPI; the distinction lives in the docstring on the annotated element)_ | A brand-new public type shipping in its first minor release before its contract has stabilised. The contract is in active flux. | Any minor release, including removal. No deprecation window. |
@@ -178,7 +178,7 @@ window starts, and its `Status` flips to `deprecated 1.x`.
 |---|---|---|---|---|---|---|
 | `DocumentSession.pageMargins(List<PageMarginRule>)` / `PageMarginRule` | Stable | planned | Per-page margins resolve a block's content width by the page it *begins* on (the engine measures each block once, before pagination). A margin that changes the content width therefore does not re-wrap a block mid-flow across a page boundary. | Revisit a page-aware per-line/per-fragment width model so a block can re-wrap when it crosses a margin boundary, if demand warrants. | — | — |
 | `templates.api.CoverLetterTemplate` | Stable | deprecated 1.9 | Orphan interface — nothing implements it; cover-letter presets implement the generic `DocumentTemplate<CoverLetterDocumentSpec>` seam. | Remove; callers implement `DocumentTemplate<CoverLetterDocumentSpec>`. | — | — |
-| `templates.cv.v2.components.HeadlineRenderer` / `ContactRenderer` / `BannerRenderer` | Stable | deprecated 1.9 | Pre-widgets delegating shims superseded by the `cv.v2.widgets` `Headline` / `ContactLine` / `SectionHeader` widgets; no callers. | Remove; use the widgets. | — | — |
+| `templates.cv.v2.components.HeadlineRenderer` / `ContactRenderer` / `BannerRenderer` | Stable | deprecated 1.9 | Pre-widgets delegating shims superseded by the `Headline` / `ContactLine` / `SectionHeader` widgets; no callers. | Remove; use the widgets. | — | — |
 
 ---
 
@@ -194,7 +194,7 @@ Javadoc per element.
 | `com.demcha.compose.document.dsl` | **Stable** | All builder types (`RowBuilder`, `SectionBuilder`, `ParagraphBuilder`, etc.). |
 | `com.demcha.compose.document.node` | **Stable** | Node records (`RowNode`, `SectionNode`, `ParagraphNode`, ...). Sealed where relevant — see § 2. |
 | `com.demcha.compose.document.style` | **Stable** | `DocumentColor`, `DocumentInsets`, `DocumentTextStyle`, `DocumentTransform`, ... |
-| `com.demcha.compose.document.templates.cv.v2.*` | **Stable** | Layered CV presets, `CvDocument`, `CvTheme`. Recommended template surface. |
+| `com.demcha.compose.document.templates.cv.v2.*` | **Stable** | Layered CV presets, `CvDocument`, `BrandTheme`. Recommended template surface. |
 | `com.demcha.compose.document.templates.coverletter.v2.*` | **Stable** | Layered cover-letter presets. |
 | `com.demcha.compose.document.templates.builtins` | **Stable** | `InvoiceTemplateV2`, `ProposalTemplateV2`, `BusinessTheme`. |
 | `com.demcha.compose.document.templates.cv.presets.*` | **Stable but Supported** | The "classic" v1.6 rebuild surface. See [`which-template-system.md`](templates/which-template-system.md). Supported through 1.x; removed in 2.0. |

docs/architecture/overview.md

@@ -93,8 +93,8 @@ need to reach below it.
   (`DocumentImageData`, `DocumentImageFitMode`).
 - **`document.theme`** — `BusinessTheme` design tokens
   (`DocumentPalette`, `SpacingScale`, `TextScale`, `TablePreset`). The
-  layered CV theme `CvTheme` lives separately under
-  `…templates.cv.v2.theme`.
+  layered CV theme `BrandTheme` lives separately under
+  `…templates.core.theme`.
 - **`document.output`** — backend-neutral output options
   (`DocumentMetadata`, `DocumentWatermark`, `DocumentProtection`,
   `DocumentHeaderFooter`).
@@ -128,7 +128,7 @@ the same `DocumentDsl` an application would use directly.
 - **`...templates.builtins`** — concrete built-ins
   (`InvoiceTemplateV1`, `InvoiceTemplateV2`, `ProposalTemplateV1`,
   `ProposalTemplateV2`, `CvTemplateV1`, plus a CV gallery that takes a
-  `BusinessTheme` or `CvTheme` in their constructor).
+  `BusinessTheme` or `BrandTheme` in their constructor).
 - **`...templates.support`** — backend-neutral scene composers per
   domain (`...support.cv`, `...support.business`, `...support.schedule`)
   plus shared composition primitives in `...support.common`.

docs/architecture/package-map.md

@@ -68,10 +68,12 @@ intended.
 | `com.demcha.compose.document.templates.support.schedule` | Schedule-specific scene composer. | Keep schedule-specific table/rhythm decisions isolated here. |
 | `com.demcha.compose.document.templates.theme` | Older shared theme *objects* for built-ins (e.g. `WeeklyScheduleTheme`). Distinct from `…templates.themes` (plural) below. | Themes carry styling decisions, not document content. New v2 token work goes in `themes`, not here. |
 | `com.demcha.compose.document.templates.themes` | Templates-v2 theme *token records* — `Spacing`, `Typography` (future `Palette`). Pure value types, no engine / session dependencies. | One source of truth per token group; keep it dependency-free. |
-| `com.demcha.compose.document.templates.components` | Templates-v2 reusable composition components shared across families — `Header`, `Module`, `MarkdownText`. | Stateless after construction; produce `DocumentNode`s. Family-specific components go in `<family>.v2.components`. |
+| `com.demcha.compose.document.templates.components` | Gen-2 composition components — `Header`, `Module` (`MarkdownText` moved to `core.text`). | Stateless after construction; produce `DocumentNode`s. |
 | `com.demcha.compose.document.templates.blocks` | Templates-v2 module-body block kinds — `ParagraphBlock`, `BulletListBlock`, `NumberedListBlock`, `IndentedBlock`, `KeyValueBlock`, `MultiParagraphBlock`, `EducationBlock`, `WorkHistoryBlock`. | A block declares *what* content appears; the renderer expands it per active theme / tokens. |
-| `com.demcha.compose.document.templates.decorations` | Templates-v2 decoration library — `Divider`, `AccentStrip`, `Spacer` (Panel / Banner / Ornament reserved). | First-class artefacts any preset can attach; not baked into composer logic. |
-| `com.demcha.compose.document.templates.widgets` | Shared visual widgets usable by every family — `CardWidget`, `TableWidget`, `TimelineAxisWidget`. | Keep generic (no CV-only assumptions) so invoice / proposal / cover-letter can reuse them. |
+| `com.demcha.compose.document.templates.core.theme` | Family-neutral theme tokens — `BrandTheme` + `Palette` / `Typography` / `Spacing` / `Decoration`. | The single token source every family's presets read. |
+| `com.demcha.compose.document.templates.core.text` | Family-neutral text rendering — `MarkdownText`, `MarkdownInline`, `RichParagraphRenderer`, `TextStyles`, `TextOrnaments`. | Markdown → DSL nodes; no family data model. |
+| `com.demcha.compose.document.templates.core.identity` | Family-neutral identity — `PartyIdentity` contract + header widgets (`Headline`, `ContactLine`, `Masthead`, `Subheadline`, `SvgGlyph`) + `Contact` / `Link`. | A masthead is the same shape in every family. |
+| `com.demcha.compose.document.templates.core.widgets` | Family-neutral shared widgets + decoration primitives — `CardWidget`, `TableWidget`, `TimelineAxisWidget`, `Divider`, `AccentStrip`, `Spacer`. | Keep generic (no CV-only assumptions) so any family can reuse them. |
 
 > **Preset families.** Concrete document families live under `…templates.<family>` — `cv`, `coverletter`, `invoice`, `proposal`, `schedule`. CV and cover letter additionally ship a layered v2 surface (`…cv.v2.*` / `…coverletter.v2.*`: `data` / `theme` / `components` / `widgets` / `presets`). These per-family packages are documented by the template guides rather than enumerated here — see [which-template-system.md](../templates/which-template-system.md) for the status matrix and [templates/v2-layered/](../templates/v2-layered/README.md) for the layered architecture.
 

docs/recipes.md

@@ -11,7 +11,7 @@ authoring API; public application code should not import
 | --- | --- |
 | [Charts](recipes/charts.md) | Native vector bar / line / area / pie-donut charts: data–spec–style layers, axis & grid toggles, point markers, value-label halos, legend placement, translucent area fills |
 | [Keep-together pagination](recipes/keep-together.md) | `keepTogether()` / `keepEntriesTogether()` — blocks that relocate whole instead of orphaning a heading at a page break |
-| [Themes](recipes/themes.md) | `BusinessTheme.classic / modern / executive`, page background, palette slots, text scale, the `CvTheme` ↔ `BusinessTheme` bridge |
+| [Themes](recipes/themes.md) | `BusinessTheme.classic / modern / executive`, page background, palette slots, text scale, the `BrandTheme` ↔ `BusinessTheme` bridge |
 | [Shapes and visual primitives](recipes/shapes.md) | Filled cards, dividers, spacers, lines, ellipses, image fit modes, soft panels |
 | [Shape-as-container](recipes/shape-as-container.md) | `addCircle` / `addEllipse` / `addContainer` with `ClipPolicy` (clipped layered children) |
 | [Transforms and z-index](recipes/transforms.md) | `rotate` / `scale` mixin, per-layer `zIndex` for overlays |

docs/recipes/themes.md

@@ -103,8 +103,8 @@ side; V2 is the cinematic theme-driven path.
 ## CV themes
 
 CV templates are themed independently of `BusinessTheme`. The layered
-CV presets (`cv.v2.presets.*`) carry their own theme type, `CvTheme`
-(in `com.demcha.compose.document.templates.cv.v2.theme`), so CV tokens
+CV presets (`cv.v2.presets.*`) carry their own theme type, `BrandTheme`
+(in `com.demcha.compose.document.templates.core.theme`), so CV tokens
 stay separate from invoice / proposal vocabulary. Each preset ships a
 default theme; render one against a `CvDocument` with its `create()`
 factory:
@@ -118,7 +118,7 @@ DocumentTemplate<CvDocument> cv = ModernProfessional.create();
 cv.compose(session, cvDocument);
 ```
 
-To restyle, pass a custom `CvTheme` to the preset's `create(...)`
+To restyle, pass a custom `BrandTheme` to the preset's `create(...)`
 overload, or use its `Options` builder where one is provided (for
 example `MintEditorial.Options.builder().headerBandColor(...).build()`
 → `MintEditorial.create(options)`). See

docs/templates/v1-classic/README.md

@@ -121,7 +121,7 @@ copy-and-tweak entry point for callers extending their own branding.
 
 ## Authoring features built into every preset
 
-- **Inline markdown** — body strings carrying `**bold**` and `*italic*` markers render with proper `DocumentTextDecoration` via `templates.components.MarkdownText`.
+- **Inline markdown** — body strings carrying `**bold**` and `*italic*` markers render with proper `DocumentTextDecoration` via `templates.core.text.MarkdownText`.
 - **Active hyperlinks** — header email + LinkedIn / GitHub labels become clickable `mailto:` / `https:` runs via `DocumentLinkOptions`.
 - **Slot-based layouts** — multi-column presets (`Panel`, `SidebarPortrait`, `MonogramSidebar`) declare named slots (`MAIN`, `SIDEBAR`); custom presets rearrange modules via `.place(slot, "Module Name", ...)`.
 - **Adaptive sidebar fill** — sidebar layouts size the trailing spacer dynamically from `canvas().innerHeight()` so background panels reach the page bottom on A4 / Letter / smaller fixtures without overflow.

docs/templates/v2-layered/authoring-presets.md

@@ -60,11 +60,15 @@ visual decision you can read like a recipe.
 <a id="the-widget-catalog"></a>
 ## The widget catalog
 
-The CV widget classes live in
-`com.demcha.compose.document.templates.cv.v2.widgets`. Each has a
-small set of named variants. Generic widgets that can be reused by
-CVs, proposals, invoices, and cover letters live one package higher
-in `com.demcha.compose.document.templates.widgets`.
+The neutral header widgets — `Headline`, `Subheadline`, `ContactLine`,
+`Masthead`, `SvgGlyph` — live in
+`com.demcha.compose.document.templates.core.identity`. The CV-specific
+section widgets (`SectionHeader` and friends) stay in
+`com.demcha.compose.document.templates.cv.v2.widgets`. The generic
+`CardWidget` / `TableWidget` / `TimelineAxisWidget` reusable by CVs,
+proposals, invoices, and cover letters live in
+`com.demcha.compose.document.templates.core.widgets`. Each has a small
+set of named variants.
 
 ### `Headline` — top-of-document name
 
@@ -143,14 +147,14 @@ Used for the icon-led contact and social rows in sidebar CV layouts
 
 The separator glyph used by `ContactLine`, the bullet glyph used by
 `RowRenderer`, and other character-level choices come from
-`theme.decoration()` — swap a `CvDecoration` to change them
+`theme.decoration()` — swap a `Decoration` to change them
 globally.
 
 Some presets also expose narrow preset-specific options when the
 visual decision is structural rather than a reusable widget. Example:
 `NordicClean.Options` lets authors move the skills rail to the right
 and override the accent colour, rail fill, or profile-band fill
-without mutating shared `CvTheme` defaults or changing other presets.
+without mutating shared `BrandTheme` defaults or changing other presets.
 
 ---
 
@@ -169,17 +173,17 @@ public final class MyPreset {
     private MyPreset() { }
 
     public static DocumentTemplate<CvDocument> create() {
-        return create(CvTheme.boxedClassic());
+        return create(BrandTheme.boxedClassic());
     }
 
-    public static DocumentTemplate<CvDocument> create(CvTheme theme) {
+    public static DocumentTemplate<CvDocument> create(BrandTheme theme) {
         Objects.requireNonNull(theme, "theme");
         return new Template(theme);
     }
 
     private static final class Template implements DocumentTemplate<CvDocument> {
-        private final CvTheme theme;
-        Template(CvTheme theme) { this.theme = theme; }
+        private final BrandTheme theme;
+        Template(BrandTheme theme) { this.theme = theme; }
 
         @Override public String id()          { return ID; }
         @Override public String displayName() { return DISPLAY_NAME; }
@@ -192,7 +196,7 @@ public final class MyPreset {
 }
 ```
 
-Two factories (`create()` and `create(CvTheme)`), three constants
+Two factories (`create()` and `create(BrandTheme)`), three constants
 (`ID`, `DISPLAY_NAME`, `RECOMMENDED_MARGIN`), one inner `Template`
 class implementing `DocumentTemplate<CvDocument>`. Stable.
 
@@ -216,18 +220,18 @@ public final class CardStyle {
     private CardStyle() { }
 
     public static DocumentTemplate<CvDocument> create() {
-        return create(CvTheme.boxedClassic());
+        return create(BrandTheme.boxedClassic());
     }
 
-    public static DocumentTemplate<CvDocument> create(CvTheme theme) {
+    public static DocumentTemplate<CvDocument> create(BrandTheme theme) {
         Objects.requireNonNull(theme, "theme");
         return new Template(theme);
     }
 
     private static final class Template implements DocumentTemplate<CvDocument> {
 
-        private final CvTheme theme;
-        Template(CvTheme theme) { this.theme = theme; }
+        private final BrandTheme theme;
+        Template(BrandTheme theme) { this.theme = theme; }
 
         @Override public String id()          { return ID; }
         @Override public String displayName() { return DISPLAY_NAME; }
@@ -365,7 +369,7 @@ When you do add a new widget:
 2. **`public final class`** with a private constructor.
 3. **1-3 named factories** + a lower-level `.render(...)` when useful.
 4. **First parameter is always `SectionBuilder host`**.
-5. **Pass `CvTheme theme` when the widget reads shared tokens**;
+5. **Pass `BrandTheme theme` when the widget reads shared tokens**;
    pass an explicit style only when the preset owns that unique style.
 6. **No instance state** — all static, all stateless.
 7. **JavaDoc the visual** — what does this look like? Who uses it?

docs/templates/v2-layered/contributor-guide.md

@@ -115,7 +115,7 @@ differ.
 ## Naming rules
 
 - **Family prefix** on top-level records to avoid name collisions.
-  CV uses `CvName`, `CvContact`, `CvTheme`. Invoice should use
+  CV uses `CvName`, `CvIdentity`, `CvSection`. Invoice should use
   `InvoiceParty`, `InvoiceLine`, `InvoiceTheme`. Cover letter:
   `CoverLetterRecipient`, `CoverLetterTheme`. Etc.
 - **`<Family>Document`** for the root record. (`CvDocument`,

docs/templates/v2-layered/quickstart.md

@@ -11,7 +11,7 @@ GraphCompose's templates v2 (layered) gives you:
 
 - **Records describing content** — `CvDocument`, `CvIdentity`,
   `CvSection`. No styling, no rendering, just structured data.
-- **Themes describing visuals** — `CvTheme` (palette + typography +
+- **Themes describing visuals** — `BrandTheme` (palette + typography +
   spacing + decoration). Swap a theme to change colours, fonts,
   bullet glyphs without touching renderers.
 - **Widgets as visual LEGO bricks** — `Headline`, `Subheadline`,
@@ -105,11 +105,11 @@ Same data, different visual. That's the layering.
         ▼                  ▼
 ┌─────────────────────┐  ┌──────────────────────────────────┐
 │  components/         │  │  theme/                          │
-│    SectionDispatcher │  │    CvPalette  (colours)          │
-│    EntryRenderer     │  │    CvTypography (fonts + sizes)  │
-│    RowRenderer       │  │    CvSpacing  (margins + gaps)   │
-│    ParagraphRenderer │  │    CvDecoration (bullet, sep)    │
-│    + primitives      │  │    CvTheme (bundle + factories)  │
+│    SectionDispatcher │  │    Palette  (colours)          │
+│    EntryRenderer     │  │    Typography (fonts + sizes)  │
+│    RowRenderer       │  │    Spacing  (margins + gaps)   │
+│    ParagraphRenderer │  │    Decoration (bullet, sep)    │
+│    + primitives      │  │    BrandTheme (bundle + factories)  │
 └─────────────────────┘  └──────────────────────────────────┘
         │ renders into DSL
         ▼