@rubytech/create-maxy-code 0.1.68 → 0.1.70

package/payload/premium-plugins/real-agent/plugins/brochures/skills/property-brochure/references/build.md

@@ -4,17 +4,19 @@
 
 1. Copy template to property directory, populate with content
 2. Stage `output/images/` per `images.md → Image renaming and optimisation`
-3. Serve locally: `python3 -m http.server <port>` from the project root
-4. Navigate Playwright to the brochure URL
-5. Present to user in browser for review
-6. User requests changes — iterate on content, image sizing, page balance
-7. Verify every page fits A4: measure `scrollHeight` for all `.page` elements
-8. Verify no 404s in the browser console
-9. Repeat 5–8 until user approves the final copy
-10. **Only after user approval**: render snapshots (two passes — 300 dpi to `output/`, 192 dpi to `output/.snapshots-web/`) per **Print snapshot capture** below
-11. Build both PDFs (img2pdf + qpdf) per **PDF deliverable** below
-12. Build the web bundle (96 dpi JPGs + bundled web PDF + zip) per **Web bundle** below
-13. User downloads the web PDF via brochure.html's Download button or receives the print master separately for press/print runs
+3. **If branded register and `<brand_dir>/DESIGN.md` contains a `## Type roles` block** — emit the role overlay into both `brochure.html` and `page.html`/`index.html` per **Type-role overlay generation** below. Run this **before** any snapshot capture; the overlay is part of what the user reviews in the browser, not a post-process applied to PDFs.
+4. Serve locally: `python3 -m http.server <port>` from the project root
+5. Navigate Playwright to the brochure URL
+6. Present to user in browser for review
+7. User requests changes — iterate on content, image sizing, page balance
+8. Verify every page fits A4: measure `scrollHeight` for all `.page` elements
+9. Verify no 404s in the browser console
+10. Repeat 6–9 until user approves the final copy
+11. **Preview manifest gate** — render `<property_dir>/output/.review/` thumbnails (per-page PNGs at 1× DPR) plus `<property_dir>/output/.review/manifest.json` capturing the active register, computed `--paper-25 / --serif / --gold-700 / --ink` token values, risk probes for `.mi-row .v` / `.folio em` / `.opener-title`, and which always-emit blocks were emitted (`DARK_SURFACE_PROTECTION`, `LIGHT_SURFACE_DATA_PROTECTION`, `STRUCTURAL_CLAMP_LOOSEN`). Halt and wait until the operator writes `<property_dir>/output/.review/approved`. The interactive form of the same gate is the browser-review loop in steps 6–10; this file-based halt is the structural form that scripted or autonomous runs cannot bypass — the build refuses to advance until `approved` exists.
+12. **Only after `approved` exists**: render snapshots (two passes — 300 dpi to `output/`, 192 dpi to `output/.snapshots-web/`) per **Print snapshot capture** below
+13. Build both PDFs (img2pdf + qpdf) per **PDF deliverable** below
+14. Build the web bundle (96 dpi JPGs + bundled web PDF + zip) per **Web bundle** below
+15. User downloads the web PDF via brochure.html's Download button or receives the print master separately for press/print runs
 
 Do not capture snapshots during the editing cycle — they are expensive and invalidated by every change.
 
@@ -268,3 +270,274 @@ The brochure should render the same as the canonical preview, just lighter on th
 | `.snapshots-web/*-print.png` | ✓ intermediate (192 dpi PNGs used by the web-PDF build; deletable after) | — |
 
 The convention: `output/` is the canonical archive for the property's lifetime. `output/web/` is a derived bundle, regenerable any time from the canonical artefacts.
+
+## Type-role overlay generation
+
+If the brand pack's `DESIGN.md` contains a `## Type roles` block (declared per `references/registers.md → Type-role overrides`), parse it and emit a single `<style id="brand-type-roles">…</style>` block at the `<!-- BRAND_TYPE_ROLES_OVERRIDE_SLOT -->` sentinel immediately before the closing `</style>` of the template's main stylesheet. The override CSS is generated **mechanically** from the recipe map below — the build does not invent selectors, it emits the documented ones using values from the DESIGN doc.
+
+Two agents running this build on different days for the same brand pack produce byte-identical overlays. That is the contract.
+
+The role-overlay step runs **before** snapshot capture (step 10 in the live-editing workflow), not after. The overlay is part of the rendered HTML the user reviews, not a post-process applied to PDFs.
+
+### Recipe map — reference implementation
+
+```python
+ROLE_RECIPES = {
+    'display-headline-style': {
+        'normal': [
+            '.cover-title, .opener-title, .ed-headline, .chapter-head h3, '
+            '.feature-page h3, .gallery-head h3, .siteplan-page h3, .toc-title, '
+            '.back-headline, .mi-head h2, .mi-head h3 '
+            '{ font-style: normal !important; }',
+        ],
+    },
+    'display-em-style': {
+        'weight-shift': [
+            '.cover-title em, .opener-title em, .ed-headline em, .toc-title em, '
+            '.back-headline em, .mi-head em '
+            '{ font-style: normal !important; font-weight: 500 !important; }',
+        ],
+        'normal': [
+            '.cover-title em, .opener-title em, .ed-headline em, .toc-title em, '
+            '.back-headline em, .mi-head em '
+            '{ font-style: normal !important; }',
+        ],
+    },
+    'display-letterspacing': {
+        # tuned to family: Cormorant=wide (0.18em), humanist sans=medium (0.10em),
+        # geometric sans=tight (0.04em). Applies only to the two largest display lines.
+        'medium': [
+            '.cover-title { letter-spacing: 0.10em !important; text-indent: 0.10em !important; }',
+            '.opener-title { letter-spacing: -0.012em !important; }',
+        ],
+        'tight': [
+            '.cover-title { letter-spacing: 0.04em !important; text-indent: 0.04em !important; }',
+            '.opener-title { letter-spacing: -0.02em !important; }',
+        ],
+    },
+    'deck-family': {
+        'sans': [
+            '.ed-deck, .ed-deck em, .feature-deck, .gallery-deck, .siteplan-deck '
+            '{ font-family: var(--sans) !important; font-style: normal !important; }',
+        ],
+    },
+    'deck-case': {
+        'sentence': [
+            '.ed-deck, .feature-deck, .gallery-deck, .siteplan-deck '
+            '{ letter-spacing: 0.02em !important; text-transform: none !important; }',
+            '.ed-deck em { font-weight: 500 !important; }',
+        ],
+    },
+    'subtitle-family': {
+        'sans-tracked-caps': [
+            '.opener-title em, .cover-subtitle, .opener-spec '
+            '{ font-family: var(--sans) !important; font-style: normal !important; }',
+            '.opener-spec em { font-style: normal !important; font-weight: 500 !important; }',
+        ],
+        'sans': [
+            '.opener-title em, .cover-subtitle, .opener-spec '
+            '{ font-family: var(--sans) !important; font-style: normal !important; '
+            'letter-spacing: 0.04em !important; text-transform: none !important; }',
+        ],
+    },
+    'caption-family': {
+        'sans': [
+            '.ed-caption, .ed-caption strong, .caption, .caption-pill, .caption-text, '
+            '.img-caption, .photo-caption, .intermission .caption-pill '
+            '{ font-family: var(--sans) !important; font-style: normal !important; }',
+        ],
+    },
+    'caption-em-style': {
+        'weight-shift': [
+            '.ed-caption em, .caption em, .caption-text em, .img-caption em, '
+            '.photo-caption em, .intermission .caption-pill em '
+            '{ font-style: normal !important; font-weight: 500 !important; }',
+        ],
+    },
+    'dropcap': {
+        'ink': [
+            '.ed-body.dropcap::first-letter { color: var(--ink) !important; }',
+        ],
+        'ink-bold-sans': [
+            '.ed-body.dropcap::first-letter { '
+            'font-family: var(--sans) !important; font-style: normal !important; '
+            'font-weight: 700 !important; color: var(--ink) !important; }',
+        ],
+        'hidden': [
+            '.ed-body.dropcap::first-letter { '
+            'font-family: var(--sans) !important; font-style: normal !important; '
+            'font-size: inherit !important; font-weight: 400 !important; '
+            'line-height: inherit !important; color: inherit !important; '
+            'float: none !important; padding: 0 !important; }',
+        ],
+    },
+    'hairline-rules': {
+        'eyebrow-only': [
+            '.opener .ed-rule, .opener-text .ed-rule, .opener-body .ed-rule, '
+            '.feature-page .ed-rule, .gallery-head .ed-rule, .siteplan-page .ed-rule, '
+            '.chapter-head .ed-rule { display: none !important; }',
+        ],
+        'hidden': [
+            '.ed-rule, .toc-rule { display: none !important; }',
+        ],
+    },
+    'body-em-style': {
+        'weight-shift': [
+            '.ed-body em, .opener-body em, .opener-text em, .gallery-cell em, '
+            '.siteplan-panel em, .spec-list li em, .mi-row em, .floorplan-lead em, '
+            '.floorplan-sub em, .epc-caption em '
+            '{ font-style: normal !important; font-weight: 500 !important; }',
+        ],
+    },
+    'folio-em-style': {
+        'weight-shift': [
+            '.folio em, .folio .folio-mid em '
+            '{ font-style: normal !important; font-weight: 500 !important; '
+            'font-family: var(--sans) !important; }',
+        ],
+    },
+    'backpage-em-style': {
+        'weight-shift': [
+            '.back-headline em, .back-tagline em, .back-foot em, .back-contact-grid em, '
+            '.back-rule em { font-style: normal !important; font-weight: 500 !important; }',
+        ],
+    },
+}
+
+
+def emit_overlay(role_values: dict[str, str]) -> str:
+    """Compose the <style id='brand-type-roles'> block from a {role: value} dict.
+
+    role_values is parsed from the DESIGN.md `## Type roles` block — either a
+    role/value table or a flat `role: value` line list. Missing roles inherit
+    the template default (no CSS emitted). Unknown roles raise ValueError so
+    they surface during the build, not silently in the rendered brochure.
+
+    DARK_SURFACE_PROTECTION and STRUCTURAL_CLAMP_LOOSEN are emitted FIRST and
+    UNCONDITIONALLY whenever any role values are declared. They are the
+    foundation of any branded re-skin; see "Always-emit recipes" above.
+    """
+    if not role_values:
+        return ""  # No role block declared — emit nothing.
+    lines = ["<style id=\"brand-type-roles\">"]
+    lines.append("  /* === DARK SURFACE PROTECTION === */")
+    lines.extend(DARK_SURFACE_PROTECTION)
+    lines.append("  /* === STRUCTURAL CLAMP LOOSEN === */")
+    lines.extend(STRUCTURAL_CLAMP_LOOSEN)
+    for role, value in role_values.items():
+        if role not in ROLE_RECIPES:
+            raise ValueError(f"Unknown type role: {role}")
+        if value not in ROLE_RECIPES[role]:
+            raise ValueError(f"Unknown value '{value}' for role '{role}'")
+        lines.append(f"  /* === ROLE: {role}: {value} === */")
+        lines.extend(ROLE_RECIPES[role][value])
+    lines.append("</style>")
+    return "\n".join(lines)
+```
+
+
+### Always-emit recipes — dark-surface protection, light-surface data protection, structural clamps
+
+Three sections of the overlay are emitted **whenever the brand pack's `## Type roles` block is present**, regardless of which roles the operator declared. They are the foundation of any branded re-skin — without them the role API's targeted overrides can blow up adjacent template assumptions.
+
+#### Dark-surface protection (fixed exclusion list)
+
+The role API's color rules deliberately stop short of selectors that sit on dark surfaces — the toc-image caption pill, intermission caption pills, the spread-6 chapter-head overlay on a dark photo, the back-page masthead and tagline, and the back-page contact-grid name lines. The brand-token swap will have remapped `--gold-700` (the template's italic-emphasis color) to the brand's accent — typically navy or a deep brand colour. On a light surface, that's correct. On a dark surface, navy on dark is unreadable.
+
+The recipe is a **fixed exclusion list**, not a heuristic. Ship it as part of the overlay:
+
+```python
+DARK_SURFACE_PROTECTION = [
+    # Body text on dark surfaces — keep paper-light regardless of brand-token swap.
+    '.toc-image .caption, .toc-image .caption *, '
+    '.intermission .caption-pill, .intermission .caption-pill *, '
+    '.spread-6 .top-image .overlay, .spread-6 .top-image .overlay *, '
+    '.back-headline, .back-tagline, .back-foot, .back-contact-grid, .back-rule '
+    '{ color: var(--paper-25) !important; }',
+    # Emphasis on dark surfaces — use the brand accent (--gold-300) which the
+    # brand-tokens block typically maps to the brand's bright/highlight colour.
+    '.toc-image .caption em, '
+    '.intermission .caption-pill em, '
+    '.spread-6 .top-image .overlay em, '
+    '.spread-6 .top-image .overlay .ed-headline em, '
+    '.back-headline em, '
+    '.back-tagline em, '
+    '.back-contact-grid .cell .name em, '
+    '.back-foot em '
+    '{ color: var(--gold-300) !important; }',
+]
+```
+
+The selector list is closed. Two agents producing brochures for the same brand pack emit byte-identical dark-surface blocks. If the template adds a new dark-surface region in a future revision, this list (in `build.md`) is the authoritative update site.
+
+#### Light-surface data protection (fixed selector list)
+
+The template uses `var(--gold-700)` both for genuine accents (em emphasis, eyebrow rules, particulars numbering) **and** for data-value treatment in the Material Information rows, opener meta row, EPC chart rows, floorplan caption, and the spec list. Premium binds `--gold-700` to a muted bronze (`#7A6235`) so the data cells read as subtle accents on cream. Branded binds `--gold-700` to whatever the brand's primary accent is — for some brands a saturated green or red — and every data cell turns into a hyperlink-looking blob.
+
+The light-surface twin of dark-surface protection forces data-cell text back to `var(--ink)` (and the folio strip to `var(--slate-600)`), regardless of which brand token swap happens.
+
+```python
+LIGHT_SURFACE_DATA_PROTECTION = [
+    # Material info, opener meta, EPC data values, floorplan caption, spec list —
+    # always read as ink, never brand-accent.
+    '.mi-row .v, .mi-row .v em, '
+    '.opener-meta-row .v, .opener-meta-row .v em, '
+    '.epc-row .v, .epc-row .v em, '
+    '.spec-list li, .spec-list li em, .spec-list li strong, '
+    '.floorplan-sub, .floorplan-sub em '
+    '{ color: var(--ink) !important; }',
+    # Folio strip — muted slate, never full brand colour.
+    '.folio, .folio em, .folio-mid, .folio-mid em '
+    '{ color: var(--slate-600) !important; }',
+    # Particulars numbering keeps the brand accent intentionally; the existing
+    # `.spec-list li .num` rule already scopes that to the number span only —
+    # no override needed here.
+]
+```
+
+Same closed-list contract as the dark-surface block: two agents emit byte-identical output for the same brand. If a future template revision adds a new data-cell region, the entry is added here. A cleaner long-term fix is to split `--gold-700` into `--accent-strong` (em, eyebrow rules, `.num`) and `--data-text` (the selectors above, defaulting to `--ink`) so Branded only swaps `--accent-strong`; until that token split lands, this override block is structurally mandatory in Branded runs, not optional polish.
+
+#### Structural clamp loosen
+
+The template's chapter-heading grid rows are sized for the Cormorant Garamond display setup (italic, weight 400, letter-spacing tuned for didone). When the role overlay swaps display family, weight, or letter-spacing, headings can grow a few millimetres beyond what the fixed-height rows accommodate — and the template's `overflow: hidden` on those rows clips the descenders. The proposal author's term for this is "structural-element clamps that need to be loosened together with the type-role overlay."
+
+The recipe is bounded: only the known fixed-height heading rows in spreads 2 and 3 are loosened, and only to `minmax(<original>, max-content)`. A heading that already fits the original budget renders identically; a heading that needs a few extra mm no longer clips.
+
+```python
+STRUCTURAL_CLAMP_LOOSEN = [
+    # spread-3: chapter heading row fixed at 60mm in the template.
+    # Loosen to "60mm but grow if needed" — image cells in the second row
+    # absorb the shrinkage when the heading takes extra height.
+    '.spread-3 { grid-template-rows: minmax(60mm, max-content) 1fr !important; }',
+    '.spread-3 .head { overflow: visible !important; }',
+    # spread-2: bottom strip fixed at 56mm. Same treatment.
+    '.spread-2 { grid-template-rows: 1fr minmax(56mm, max-content) !important; }',
+    # Other spreads use auto 1fr or auto auto already — no loosening needed.
+]
+```
+
+If a future template revision adds another fixed-height heading row, the entry is added here. The substitute step's `emit_overlay()` always emits these three sections first, then the per-role recipes.
+
+
+### Where the overlay lands
+
+The template's main `<style>` ends with the sentinel line:
+
+```html
+/* BRAND_TYPE_ROLES_OVERRIDE_SLOT — branded register may inject role overrides here */
+</style>
+```
+
+The build replaces that sentinel comment with the emitted `<style id="brand-type-roles">…</style>` block (or with nothing if no role values are declared). The original `<style>` continues to its closing `</style>` immediately after. Both `brochure.html` and the landing page (`page.html` / `index.html`) carry the sentinel and receive the same overlay — the role API is global to the property's output.
+
+### Verification
+
+After the overlay is emitted, run a quick check:
+
+```bash
+grep -c 'id="brand-type-roles"' output/brochure.html output/web/page.html
+# both must return 1 if the brand pack declared roles, 0 otherwise.
+```
+
+A branded run whose DESIGN.md declares `## Type roles` but whose rendered HTML lacks `id="brand-type-roles"` is **shipped broken** — the overlay step was skipped or failed silently.
+

package/payload/premium-plugins/real-agent/plugins/brochures/skills/property-brochure/references/index.html

@@ -834,6 +834,7 @@
     .key-facts .grid { grid-template-columns: 1fr; }
     .subnav .left .price { display: none; }
   }
+  /* BRAND_TYPE_ROLES_OVERRIDE_SLOT — branded register may inject role overrides here */
 </style>
 </head>
 <body>

package/payload/premium-plugins/real-agent/plugins/brochures/skills/property-brochure/references/registers.md

@@ -13,17 +13,75 @@ The skill template ships with a default super-premium visual scheme. Two registe
 
 | Register | What you change |
 |---|---|
-| **Premium** (template scheme retained) | Keep all super-premium tokens (palette, type, layout) verbatim. Swap **only** the agent's logo (back-page masthead + TOC credit) and the agent's contact details. Make subtle consistency adjustments — e.g. the accent dot in "Brand · Town" can pick up the brand's primary colour if doing so doesn't disrupt the ivory/ink/bronze relationship. **Do not apply the brand's palette or type tokens.** |
-| **Branded** (full DESIGN.md re-skin) | Swap font names at the `--serif` / `--body-serif` / `--sans` custom properties; replace palette tokens (`--paper-25`, `--ink`, `--gold-500`, `--gold-700`, `--gold-300`, `--rule` etc.) with the DESIGN doc's values; adjust copy register to match the brand's voice; substitute the brand's logo PNGs at the back-page masthead and TOC credit. The chapter structure (sixteen pages, Roman-numeral chapters, italic headlines, editorial decks, intermissions, gallery, site plan) stays. |
+| **Branded** (default — full DESIGN.md re-skin) | Swap font names at the `--serif` / `--body-serif` / `--sans` custom properties; replace palette tokens (`--paper-25`, `--ink`, `--gold-500`, `--gold-700`, `--gold-300`, `--rule` etc.) with the DESIGN doc's values; **apply role-level type overrides from the DESIGN doc's `## Type roles` block** (see *Type-role overrides* below); substitute the brand's logo PNGs at the back-page masthead and TOC credit. The chapter structure (sixteen pages, Roman-numeral chapters, intermissions, gallery, site plan) stays — *layout, image slots, page geometry and folio chrome positions remain identical, only the styling of named type roles changes*. |
+| **Premium** (opt-in only — template scheme retained) | Keep all super-premium tokens (palette, type, layout) verbatim. Swap **only** the agent's logo (back-page masthead + TOC credit) and the agent's contact details. Make subtle consistency adjustments — e.g. the accent dot in "Brand · Town" can pick up the brand's primary colour if doing so doesn't disrupt the ivory/ink/bronze relationship. **Do not apply the brand's palette or type tokens.** |
 
 ## Selecting the register — decide in this order
 
-1. **The user said "premium" or "super-premium"** in the request → **Premium**, regardless of whether a DESIGN.md exists.
-2. **A DESIGN.md is provided** and the user did *not* say "premium" → **Branded**.
-3. **Neither a DESIGN.md nor the word "premium"** → **Premium** (the template ships with super-premium defaults already in place).
+1. **The user explicitly said "premium" or "super-premium"** in the request → **Premium**, regardless of whether a DESIGN.md exists.
+2. **Otherwise → Branded.** If no DESIGN.md exists for the brand, **run `brand-design` first** to produce one — do not fall back to Premium just because the brand pack is missing. Premium is opt-in; "missing brand pack" is a setup step, not a register decision.
 
 The signal is the user's wording, not the property. Don't infer premium from a high guide price or a country-house name when the user has handed over a DESIGN.md without qualifying language — the agent may want their brand on every brochure regardless of property tier. Conversely, when the user says "premium" but the property is plainly mid-market (a £450k semi, a city flat), surface the mismatch in one line ("Going premium register — confirm you want the country-folio look on this listing?") before generating, so the user can correct the wording rather than discover the mismatch in the rendered output.
 
+## Type-role overrides
+
+The branded register's font-family and palette swap alone produces a folio painted in the brand's colours but still wearing the template's editorial conventions — italic display, small-caps decks, gold hairlines under every heading, dropcap, italic emphasis on `<em>`. For brands whose live identity does not use those conventions (Cooper Adams' upright TrajanPro, eXp UK's Montserrat, Knight-Frank-adjacent vs corporate-residential), that's a mismatch. The brochure reads as a country-house folio with brand paint, not as a brand document.
+
+To close the gap without leaving branded territory, the brand pack's `DESIGN.md` may declare a `## Type roles` block. Each row maps a named brochure type-role to a brand styling decision. The build pipeline reads these and emits a single override CSS block — see `build.md → Type-role overlay generation` for the recipe map.
+
+The role API is **fixed and bounded**. Only the roles below may be overridden; the build does not invent selectors. Anything else stays at template defaults.
+
+| Role | Targets (CSS selectors) | Allowed values |
+|---|---|---|
+| `display-headline-style` | `.cover-title`, `.opener-title`, `.ed-headline`, `.chapter-head h3`, `.feature-page h3`, `.gallery-head h3`, `.siteplan-page h3`, `.toc-title`, `.back-headline`, `.mi-head h2`, `.mi-head h3` | `italic` (default) / `normal` |
+| `display-em-style` | `<em>` inside the headline selectors above | `italic` (default) / `weight-shift` / `normal` |
+| `display-letterspacing` | `.cover-title`, `.opener-title` | `wide` (default, ≈0.18em — tuned for Cormorant/didone) / `medium` (≈0.10em — humanist sans) / `tight` (≈0.04em — geometric sans) |
+| `deck-family` | `.ed-deck`, `.feature-deck`, `.gallery-deck`, `.siteplan-deck` | `serif` (default) / `sans` |
+| `deck-case` | same as `deck-family` | `caps-tracked` (default) / `sentence` |
+| `eyebrow-family` | `.ed-eyebrow`, `.toc-eyebrow`, `.chapter-eyebrow`, `.ed-eyebrow-light` | `sans` (default — documented for explicitness) |
+| `subtitle-family` | `.opener-title em`, `.cover-subtitle`, `.opener-spec` | `serif-smallcaps` (default) / `sans-tracked-caps` / `sans` |
+| `caption-family` | `.ed-caption`, `.caption-pill`, `.caption-text`, `.img-caption`, `.photo-caption`, `.intermission .caption-pill` | `serif` (default) / `sans` |
+| `caption-em-style` | `<em>` inside any caption selector | `italic` (default) / `weight-shift` / `normal` |
+| `dropcap` | `.ed-body.dropcap::first-letter` | `gold` (default — italic serif in `--gold-700`) / `ink` (italic serif in `--ink`) / `ink-bold-sans` (bold sans in `--ink`, no italic) / `hidden` (neutralised — first letter inline at body size) |
+| `hairline-rules` | `.ed-rule`, `.toc-rule` | `visible` (default) / `eyebrow-only` (rules beside eyebrows only, not under chapter heads) / `hidden` |
+| `body-em-style` | `.ed-body em`, `.opener-body em`, `.opener-text em`, `.gallery-cell em`, `.siteplan-panel em`, `.spec-list li em`, `.mi-row em`, `.floorplan-lead em`, `.floorplan-sub em`, `.epc-caption em` | `italic` (default) / `weight-shift` / `normal` |
+| `folio-em-style` | `.folio em`, `.folio .folio-mid em` | `italic` (default) / `weight-shift` / `normal` |
+| `backpage-em-style` | `.back-headline em`, `.back-tagline em`, `.back-foot em`, `.back-contact-grid em`, `.back-rule em` | `italic-gold` (default) / `weight-shift` / `normal` |
+
+### What the role API permits
+
+Each `value` maps to a deterministic, named CSS recipe (the full map lives in `build.md → Type-role overlay generation`). For example:
+
+- `display-em-style: weight-shift` → emits `{ font-style: normal !important; font-weight: 500 !important; }`
+- `deck-family: sans` + `deck-case: sentence` → emits `{ font-family: var(--sans) !important; font-style: normal !important; letter-spacing: 0.02em !important; text-transform: none !important; }`
+- `dropcap: hidden` → emits a `::first-letter` override that neutralises the float, size, color and font-family overrides from the template
+
+### What the role API does NOT permit
+
+- Changing page layout, grid structure, image slot positions, page count, folio position
+- Adding new CSS classes or DOM elements
+- Changing colour assignments (those belong to the palette tokens, not the role API)
+- Restyling the back page's QR strip or contact grid layout
+- Restyling the MI three-column grid layout
+- Defining new roles ad hoc — the role list above is the complete API
+
+A branded brochure must remain layout-identical to the premium brochure; only the *styling of named type roles* may differ.
+
+### Backward compatibility
+
+Existing brand packs whose `DESIGN.md` files do not contain a `## Type roles` block are **unaffected**. Omitted roles inherit template defaults — which match the template's current behaviour exactly. Two agents producing brochures for the same brand on different days produce identical results because the role list is fixed and the recipe per value is fixed.
+
+
+### Foundation: always-emit recipes
+
+Two sections of the role overlay are emitted **whenever the brand pack declares any `## Type roles`**, regardless of which specific roles the operator chose. They are the foundation of any branded re-skin:
+
+1. **Dark-surface protection.** A fixed exclusion list of selectors that sit on dark surfaces — the TOC hero caption pill, intermission caption pills, the spread-6 chapter-head overlay on its dark photo, the back-page masthead and tagline, and the back-page contact-grid name lines. The brand-token swap remaps `--gold-700` (the template's italic-emphasis colour) to the brand's accent. On a light surface that's correct. On a dark surface, a brand-accent like navy or maroon on dark photographic background is unreadable. The dark-surface protection forces text on these selectors to `var(--paper-25)` and emphasis to `var(--gold-300)` (the brand's accent / highlight). This is **not** a per-implementer concern — the exclusion list is fixed in `build.md → Always-emit recipes`.
+2. **Light-surface data protection.** The template uses `--gold-700` for two semantically different things — genuine accents (em emphasis, eyebrow rules, particulars numbering) and data-value treatment in `.mi-row .v`, `.opener-meta-row .v`, `.epc-row .v`, `.spec-list li`, and `.floorplan-sub`. In Premium that's invisible because `--gold-700` is a muted bronze on cream. In Branded, where `--gold-700` is rebound to whatever the brand's primary accent is (often a saturated green, red, or navy), every data cell turns into a hyperlink-looking blob. The light-surface twin of dark-surface protection forces those data cells to `var(--ink)` and the folio strip to `var(--slate-600)` regardless of the brand token swap. The fixed selector list lives in `build.md → Always-emit recipes` as `LIGHT_SURFACE_DATA_PROTECTION`. This is structurally mandatory in Branded runs, not optional polish — the long-term cleanup is to split `--gold-700` into `--accent-strong` and `--data-text` tokens so Branded only swaps the accent.
+3. **Structural clamp loosen.** The template's chapter-heading rows in `.spread-2` and `.spread-3` are sized for the Cormorant Garamond display setup (italic, weight 400, didone-tuned letter-spacing). When the role overlay changes display family, weight, or letter-spacing, headings can grow a few millimetres beyond what those fixed-height rows accommodate, and the template's `overflow: hidden` clips the descenders. The clamp-loosen recipe converts the affected rows to `minmax(<original>, max-content)` and lifts the heading-row `overflow` from `hidden` to `visible`. A heading that already fits renders identically; a heading that needs a few extra mm no longer clips. If a future template revision adds another fixed-height heading row, the entry is added in `build.md` — not handwritten per property.
+
+A branded brochure built with the role overlay must show all three blocks in the emitted `<style id="brand-type-roles">`. Their absence is a build-time defect, not a stylistic choice.
+
 ## Forbidden template sources
 
 **Do not** start from any of the following, even when they exist in the same brand workspace and look "more on-brand" than the skill template:
@@ -31,9 +89,9 @@ The signal is the user's wording, not the property. Don't infer premium from a h
 - `<brand>/properties/<other-listing>/output/brochure.html` — a sibling property's rendered brochure
 - A previous brochure that was hand-edited after the last template release
 - A "brand brochure" or "marketing PDF" supplied by the agency
-- An older version of `template.html` cached anywhere outside `~/.claude/plugins/brochures/skills/property-brochure/references/`
+- An older version of `template.html` cached anywhere outside `~/.claude/plugins/property-brochure/skills/property-brochure/references/`
 
-Sibling brochures contain property-specific copy edits, hand-tuned image positions, ad-hoc CSS overrides, and drift from the canonical layout. Starting from one bakes that drift into the new brochure and silently diverges every property's structure over time. The DESIGN doc supplies design **tokens** (fonts, palette, voice) — it does not authorise reaching for an existing brochure as a starting point.
+Sibling brochures contain property-specific copy edits, hand-tuned image positions, ad-hoc CSS overrides, and drift from the canonical layout. Starting from one bakes that drift into the new brochure and silently diverges every property's structure over time. The DESIGN doc supplies design **tokens** (fonts, palette, voice) and **role declarations** — it does not authorise reaching for an existing brochure as a starting point.
 
 If the canonical `references/template.html` looks wrong for the brand, the right action is to **patch the template** (open a discussion with the user about what to change), not to substitute a different starting point for one run.
 
@@ -44,4 +102,4 @@ If the canonical `references/template.html` looks wrong for the brand, the right
 - Adding new pages, removing pages, or merging spreads to "look more like" the brand's website
 - Importing CSS from the brand's website into the brochure to "match the live experience"
 
-If a branded re-skin is genuinely incompatible with the sixteen-page editorial folio (rare — most brands sit happily in this structure with token swaps), surface that to the user before generating anything. Don't unilaterally substitute structure. Any alternative count must still be **even** — see `a4-print-documents` → Even-page count for duplex printing.
+If a branded re-skin is genuinely incompatible with the sixteen-page editorial folio (rare — most brands sit happily in this structure with token swaps plus role overrides), surface that to the user before generating anything. Don't unilaterally substitute structure. Any alternative count must still be **even** — see `a4-print-documents` → Even-page count for duplex printing.

package/payload/premium-plugins/real-agent/plugins/brochures/skills/property-brochure/references/template.html

@@ -208,6 +208,7 @@
     text-transform: uppercase;
     color: var(--ink);
     white-space: nowrap;
+    white-space: nowrap;
   }
 
   .cover-subtitle {
@@ -514,6 +515,7 @@
     font-weight: 400;
     color: var(--gold-700);
     font-size: 0.36em;
+    white-space: nowrap;
     line-height: 1.2;
     margin-top: 8px;
     letter-spacing: 0.18em;
@@ -1121,7 +1123,7 @@
     color: var(--paper-0);
     margin-bottom: 12px;
   }
-  .back-headline em { font-style: italic; color: var(--gold-300); }
+  .back-headline em { font-style: italic; color: var(--gold-300); white-space: nowrap; }
 
   .back-tagline {
     font-family: var(--serif);
@@ -1360,6 +1362,7 @@
 
     * { -webkit-print-color-adjust: exact !important; print-color-adjust: exact !important; }
   }
+  /* BRAND_TYPE_ROLES_OVERRIDE_SLOT — branded register may inject role overrides here */
 </style>
 </head>
 <body>