@rubytech/create-maxy-code 0.1.68 → 0.1.69

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.68",
+  "version": "0.1.69",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/platform/plugins/admin/PLUGIN.md

@@ -129,7 +129,7 @@ Tools are available via the `admin` MCP server.
 - `hooks/pre-tool-use.sh` — enforces admin agent write boundaries
 - `hooks/playwright-file-guard.sh` — rewrites file:// URLs to a backgrounded loopback http.server before Playwright sees them
 - `hooks/webfetch-preflight.mjs` — short-circuits WebFetch on JS-SPA shells with a structured `WEBFETCH_CANNOT_READ_JS_SPA` error so the agent surfaces a loud failure to the owner instead of paying the 60s extraction timeout. Fail-open on any internal error.
-- `hooks/turn-completed-graph-write.sh` — Stop hook fired once per completed admin-agent turn. Gates on `MAXY_SESSION_ROLE=admin` + `MAXY_SPECIALIST!=database-operator` so it never recurses into the recorder PTY or fires on public sessions. **Task 147** — the recorder is spawned via the same route Sidebar uses. ONE POST to `POST /api/admin/claude-sessions`, body carries `{specialist:'database-operator', model:'haiku', initialMessage:<json-envelope>, adminSessionId:<op>}` — no synthetic `senderId: 'turn-recorder'` marker. The Hono wrapper bypasses cookie auth on this exact method+path when the request originates from `127.0.0.1` (same trust boundary the claude-session-manager itself relies on), looks up the operator's senderId from the manager's `/<adminSessionId>/meta`, and forwards a Sidebar-shape spawn body. The `/recorder-spawn` sibling route is gone. The hook reads its UI port from `MAXY_UI_INTERNAL_PORT` (stamped on the manager systemd unit) — no fallback; absence emits `[turn-recorder] spawn-failed reason=missing-env env=MAXY_UI_INTERNAL_PORT` to stderr instead of silently 19199-ing. **Task 177** — `initialMessage` is a JSON-stringified envelope conforming to the database-operator agent file's `## Input shape`. Top-level keys exactly: `turns`, `conversationId`, `accountId`, `occurredAt`. `turns` is the full conversation transcript, oldest first, newest last, with each entry `{ role: "user"|"assistant", text, ts, toolCalls? }`. No windowing, no truncation. Multi-record assistant messages collapse on `message.id`. `tool_use` and matching `tool_result` blocks attach as a single `toolCalls` entry on the owning assistant turn; the user record carrying only the `tool_result` does not create a separate user turn. No leading instruction prose. `toolCalls[].input` and `toolCalls[].output` are native JSON values, never re-stringified. (Replaces Task 175's `(operatorMessage, assistantReply)` pair, which asserted a temporal Q→A relationship the walker never enforced.) One observability line `[turn-recorder] envelope sessionId=<op> turnsCount=<n> userTurns=<n> assistantTurns=<n> toolCallTurns=<n>` precedes `spawn-request`. The envelope rides on the `/spawn` body as a trailing positional argv to `claude`, so the database-operator session's JSONL first `role=user` line is the JSON object verbatim. No separate `POST /:id/input` call, no bracketed-paste, no keystroke injection. The recorder-auto-archive subscriber stops the recorder PTY as soon as its JSONL contains an assistant message with `stop_reason === "end_turn"`. **Task 129** — every emit goes through `POST /api/admin/log-ingest` so the lines land in `server.log` keyed by the operator session id. The chain is `trigger` → `spawn-request` → `spawn-success` → `input-delivered` → `tool-call` × N → `tool-result` × N → `write-complete` → `auto-archive`; each gated-off path emits one `trigger-skipped reason=<role-not-admin|is-recorder|empty-stdin|missing-transcript|conversation-empty>` line. Failure modes — `spawn-failed`, `tool-surface-missing`, `input-failed`, `write-empty`, `auto-archive reason=stale-recorder` — each emit one named line; absence is itself a defect.
+- `hooks/turn-completed-graph-write.sh` — Stop hook fired once per completed admin-agent turn. Gates on `MAXY_SESSION_ROLE=admin` + `MAXY_SPECIALIST!=database-operator` so it never recurses into the recorder PTY or fires on public sessions. **Task 147** — the recorder is spawned via the same route Sidebar uses. ONE POST to `POST /api/admin/claude-sessions`, body carries `{specialist:'database-operator', model:'haiku', initialMessage:<json-envelope>, adminSessionId:<op>}` — no synthetic `senderId: 'turn-recorder'` marker. The Hono wrapper bypasses cookie auth on this exact method+path when the request originates from `127.0.0.1` (same trust boundary the claude-session-manager itself relies on), looks up the operator's senderId from the manager's `/<adminSessionId>/meta`, and forwards a Sidebar-shape spawn body. The `/recorder-spawn` sibling route is gone. The hook reads its UI port from `MAXY_UI_INTERNAL_PORT` (stamped on the manager systemd unit) — no fallback; absence emits `[turn-recorder] spawn-failed reason=missing-env env=MAXY_UI_INTERNAL_PORT` to stderr instead of silently 19199-ing. **Task 177** — `initialMessage` is a JSON-stringified envelope; the schema lives in [`platform/plugins/docs/references/admin-session.md`](../docs/references/admin-session.md) under "`initialMessage` JSON envelope (Task 177)". Top-level keys exactly: `turns`, `conversationId`, `accountId`, `occurredAt`. `turns` is the full conversation transcript, oldest first, newest last, with each entry `{ role: "user"|"assistant", text, ts, toolCalls? }`. No windowing, no truncation. Multi-record assistant messages collapse on `message.id`. `tool_use` and matching `tool_result` blocks attach as a single `toolCalls` entry on the owning assistant turn; the user record carrying only the `tool_result` does not create a separate user turn. No leading instruction prose. `toolCalls[].input` and `toolCalls[].output` are native JSON values, never re-stringified. (Replaces Task 175's `(operatorMessage, assistantReply)` pair, which asserted a temporal Q→A relationship the walker never enforced.) One observability line `[turn-recorder] envelope sessionId=<op> turnsCount=<n> userTurns=<n> assistantTurns=<n> toolCallTurns=<n>` precedes `spawn-request`. The envelope rides on the `/spawn` body as a trailing positional argv to `claude`, so the database-operator session's JSONL first `role=user` line is the JSON object verbatim. No separate `POST /:id/input` call, no bracketed-paste, no keystroke injection. The recorder-auto-archive subscriber stops the recorder PTY as soon as its JSONL contains an assistant message with `stop_reason === "end_turn"`. **Task 129** — every emit goes through `POST /api/admin/log-ingest` so the lines land in `server.log` keyed by the operator session id. The chain is `trigger` → `spawn-request` → `spawn-success` → `input-delivered` → `tool-call` × N → `tool-result` × N → `write-complete` → `auto-archive`; each gated-off path emits one `trigger-skipped reason=<role-not-admin|is-recorder|empty-stdin|missing-transcript|conversation-empty>` line. Failure modes — `spawn-failed`, `tool-surface-missing`, `input-failed`, `write-empty`, `auto-archive reason=stale-recorder` — each emit one named line; absence is itself a defect.
 
 ## Session identifiers (Task 135)
 

package/payload/platform/plugins/docs/references/admin-session.md

@@ -96,7 +96,7 @@ Body overrides relative to a plain Sidebar click:
 
 **Spawn body.** The hook POSTs `{adminSessionId, channel: 'browser', specialist: 'database-operator', model: 'haiku', initialMessage}` to `POST /api/admin/claude-sessions`. `adminSessionId` is the loopback-bypass key — the wrapper resolves the operator's real `senderId` from `GET <managerBase>/<adminSessionId>/meta` and forwards a Sidebar-shape body to the manager.
 
-**`initialMessage` JSON envelope (Task 177).** A single JSON object stringified to a string. Top-level keys exactly match the database-operator agent file `## Input shape`:
+**`initialMessage` JSON envelope (Task 177).** A single JSON object stringified to a string. The schema below is the authoritative contract — the database-operator agent file no longer carries it, so any change here is the only place the envelope shape moves:
 
 ```
 {

package/payload/platform/templates/specialists/agents/database-operator.md

@@ -8,68 +8,28 @@ tools: mcp__memory__memory-write, mcp__memory__memory-update, mcp__memory__memor
 
 # Database Operator
 
-You are the background recorder for this account's memory graph. Every admin-agent turn that completes fires you as a hidden PTY with the operator's full conversation transcript as stdin. You read what was said, decide what is worth recording from the most recent operator turn, and write through the wrapped writers. You never interact with the operator.
-
-## Input shape
-
-Stdin is one JSON object carrying the chronologically-ordered conversation:
-
-```
-{
-  "turns": [
-    { "role": "user",      "text": "<what the owner said>",   "ts": "<ISO-8601>" },
-    { "role": "assistant", "text": "<what the agent said>",   "ts": "<ISO-8601>",
-      "toolCalls": [ { "tool": "...", "input": {...}, "output": ... } ] },
-    ...
-  ],
-  "conversationId": "<intrinsic claude session id>",
-  "accountId":      "<account id>",
-  "occurredAt":     "<ISO-8601 timestamp of the recorder fire>"
-}
-```
-
-The array is oldest first, newest last — every user / assistant turn in the operator's transcript from session start to the moment the recorder fired. No windowing, no truncation. The **most recent operator turn** (the last `role == "user"` entry) is the trigger; everything before it is conversational context that disambiguates what the operator means.
-
-`toolCalls` appears on assistant turns that called tools. `input` and `output` are native JSON, not strings. `toolCalls` is omitted on turns that called no tools.
-
-A worked example. Four turns ending in a name-and-business statement:
-
-```
-{
-  "turns": [
-    { "role": "assistant", "text": "Session noted. What would you like to work on?", "ts": "2026-05-19T21:27:45.158Z" },
-    { "role": "user",      "text": "you tell me",                "ts": "2026-05-19T21:27:57.314Z" },
-    { "role": "assistant", "text": "What is your name and the agency you operate under?", "ts": "2026-05-19T21:28:00.847Z" },
-    { "role": "user",      "text": "Smalleys. I am Joel Smalley", "ts": "2026-05-19T21:28:12.248Z" }
-  ],
-  "conversationId": "bf704cba-eaba-4d9b-b606-7f4b8b84c011",
-  "accountId":      "be23f93a-1e51-4586-b37c-c0e86d1614c9",
-  "occurredAt":     "2026-05-19T21:28:13.000Z"
-}
-```
-
-Read in order, the trigger is the last operator turn (`"Smalleys. I am Joel Smalley"`). The preceding assistant turn names what was asked. The graph write that follows is `LocalBusiness {name:"Smalleys"}` plus the `:Person {givenName:"Joel"}` adjacency.
+You are this account's background recorder for the memory graph. You receive the operator's full conversation transcript and you decide what the most recent operator turn implies for the graph. You write through the wrapped tools listed in your frontmatter and produce no other output. The operator never sees you.
 
 ## Three rules
 
 These three rules win when anything else in this prompt conflicts with them.
 
-1. **Be precise.** Every write has a source in the most recent operator turn, anchored by the prior turns in the array. No inferred facts. No "likely".
-2. **Be concise.** No prose output. Your job is the write, not the report. If there is nothing to write, exit silently.
-3. **Show your evidence.** Stamp `createdBySource='turn-recorder'` and `createdBySession=<conversationId>` on every node and edge so the audit trail names where the claim came from.
+1. **Be precise.** Every write traces to the most recent operator turn, anchored by the earlier turns in the transcript. No inferred facts. No "likely".
+2. **Be concise.** Your job is the write, not the report. If the latest operator turn implies no write, exit silently. Do not narrate, summarise, or describe the graph.
+3. **Stamp your evidence.** On every node and edge you write, set `createdBySource` to the literal string `turn-recorder` and `createdBySession` to the operator's conversation id so the audit trail names where the claim came from.
 
 ## Outcome contract
 
-Graph writes only, through the wrapped writers in your tool list. No raw cypher. No filesystem reads. No web calls. No tool not in your frontmatter. The most recent operator turn is what you record; earlier turns are context, not separate triggers. If the latest operator turn implies a write the wrapped writers cannot make, the write is out of scope for this run: skip silently and let the graph stay where it is.
+Writes happen through the wrapped tools in your frontmatter. Nothing else. No raw cypher, no filesystem reads, no web calls, no tool outside that list. The most recent operator turn is what you record; earlier turns are context, not separate triggers. If the latest operator turn implies a change the wrapped tools cannot make, that change is out of scope for this run — skip silently and leave the graph where it is.
 
 ## Graph hierarchy
 
-Every node has a parent in the canonical chain `LocalBusiness → Project → Task | Person | Organisation | KnowledgeDocument`. The wrapped writers reject orphans; never try to bypass that by writing the node first and the parent edge "later". If you do not have a parent for the node, do not write the node.
+Every node has a parent in the canonical chain that runs LocalBusiness, then Project, then Task or Person or Organisation or KnowledgeDocument. The wrapped tools reject orphans; do not try to circumvent that by writing a node first and adding the parent edge later. If you do not have a parent for the node, do not write the node.
 
 ## Idempotency
 
-You will be fired many times against the same operator. The wrapped writers MERGE on natural keys; identical inputs produce no new nodes or edges. Do not invent surrogate keys to force a fresh write.
+You will be fired many times against the same operator. The wrapped tools merge on natural keys; identical inputs produce no new nodes or edges. Do not invent surrogate keys to force a fresh write.
 
 ## When a tool returns an error
 
-Acknowledge the error in your log line, do not retry, do not call a different tool to "rescue" the write. The graph stays where it is; the next turn fires you again.
+Acknowledge the error to yourself and stop. Do not retry. Do not call a different tool to rescue the write. The graph stays where it is; the next turn will fire you again.

package/payload/premium-plugins/real-agent/plugins/brochures/skills/brand-design/SKILL.md

@@ -73,6 +73,54 @@ What the file must contain regardless of who generated it:
 
 The naming convention is `--ds-{category}-{property}-{variant}-{state}` unless the site already ships a brand-prefixed convention, in which case adopt the existing prefix and note it.
 
+#### Optional: `## Type roles` block (for branded brochures)
+
+When the brand is the source for a property brochure run, the `property-brochure` skill's branded register applies the DESIGN.md's palette and font tokens automatically. For brands whose live identity diverges from the brochure template's editorial conventions (italic display, small-caps decks, gold hairlines under every heading, dropcaps, italic emphasis on `<em>`), the token-only swap is not enough — the brochure ends up reading as a country-house folio painted in the brand's colours, not as a brand document.
+
+To close that, declare an optional `## Type roles` block in the DESIGN.md. The brochure build reads it and emits a deterministic CSS overlay at the template's `<!-- BRAND_TYPE_ROLES_OVERRIDE_SLOT -->` sentinel. The full role list (fixed, bounded), the allowed values per role, and the recipe map live in `property-brochure/references/registers.md → Type-role overrides` and `property-brochure/references/build.md → Type-role overlay generation`.
+
+Format — one role per line, `role: value`, or a Markdown table:
+
+```markdown
+## Type roles
+
+| Role | Value |
+|---|---|
+| `display-headline-style` | `normal` |
+| `display-em-style` | `weight-shift` |
+| `display-letterspacing` | `medium` |
+| `deck-family` | `sans` |
+| `deck-case` | `sentence` |
+| `subtitle-family` | `sans-tracked-caps` |
+| `caption-family` | `sans` |
+| `caption-em-style` | `weight-shift` |
+| `dropcap` | `hidden` |
+| `hairline-rules` | `eyebrow-only` |
+| `body-em-style` | `weight-shift` |
+| `folio-em-style` | `weight-shift` |
+| `backpage-em-style` | `weight-shift` |
+```
+
+Omitted roles inherit the template default. The block is **optional**; brands whose identity already matches the template's editorial conventions (country-house agents, traditional residential, fine-art galleries) skip the block entirely.
+
+How to decide which values to set, given the brand audit you've already done:
+
+| Observation on the live site | Maps to role |
+|---|---|
+| Display headlines render upright (no `font-style: italic`) | `display-headline-style: normal` |
+| Display family is a humanist sans (Montserrat, Inter, Söhne) | `display-letterspacing: medium` |
+| Display family is a geometric/grotesque sans (Helvetica, Roboto Mono) | `display-letterspacing: tight` |
+| The site never italicises anything | `display-em-style`, `body-em-style`, `caption-em-style`, `folio-em-style`, `backpage-em-style` → `weight-shift` (preferred) or `normal` |
+| All body running text is sans-serif | `deck-family: sans`, `caption-family: sans` |
+| Captions and labels share the body family | `caption-family: sans` |
+| No dropcaps anywhere on the site | `dropcap: hidden` |
+| Site uses bold sans for initial-cap accents (e.g. magazine-style hero pull-letters) | `dropcap: ink-bold-sans` |
+| Decorative gold/accent rules appear only beside small labels, not under headings | `hairline-rules: eyebrow-only` (or `hidden` if no rules at all) |
+| Subtitles use letter-spaced uppercase sans | `subtitle-family: sans-tracked-caps` |
+
+If the brand's identity has no observable signal either way for a role, leave it omitted — the template default applies.
+
+
 ### `<slug>-logo-light.png` and `<slug>-logo-dark.png`
 
 Two PNGs of the wordmark/lockup as the brand uses it. **The filename describes the colour of the logo art itself, not the surface where it will be placed.** This matches the natural reading and the convention used by Google, Bootstrap, Tailwind, and most public design systems:

package/payload/premium-plugins/real-agent/plugins/brochures/skills/make-brochure/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: make-brochure
-description: Use when the user gives both an estate agent's website URL (or existing brand-pack directory) and a property listing URL (or existing property-assets directory) in one request, asking for the brochure as an end-to-end deliverable. Trigger phrases include "build a brochure for <listing> using the agent at <agent-url>", "create a brochure for the property at <X> with the brand at <Y>", "end-to-end brochure for <listing>", "do everything from brand to brochure for <listing>", "make me the brochure for <listing> on <agent-site>", or any request that names both a brand source and a property source in the same turn.
+description: Meta-skill that runs the full brand-design → property-extract → property-brochure pipeline end-to-end, skipping any step whose output already exists on disk. This is the default surface whenever the deliverable is a property brochure — use it whether the user supplies an agent URL plus a listing URL, just a listing URL on a known agent, an existing brand pack plus a listing, or simply asks to "make a brochure for <listing>". The three component skills (brand-design, property-extract, property-brochure) remain individually callable for single-step work, but any request whose outcome is the brochure itself should route here. Trigger phrases include "make me a brochure for <listing>", "build the brochure for <X>", "brochure for <listing>", "do the brochure end-to-end", "everything from brand to brochure for <listing>", "create a brochure for the property at <X> with the brand at <Y>", or any full-pipeline brochure intent.
 allowed-tools:
   - Bash
   - Read

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

@@ -4,17 +4,18 @@
 
 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. **Only after user approval**: render snapshots (two passes — 300 dpi to `output/`, 192 dpi to `output/.snapshots-web/`) per **Print snapshot capture** below
+12. Build both PDFs (img2pdf + qpdf) per **PDF deliverable** below
+13. Build the web bundle (96 dpi JPGs + bundled web PDF + zip) per **Web bundle** below
+14. 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 +269,247 @@ 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 and structural clamps
+
+Two 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.
+
+#### 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 two 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,74 @@ 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. **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 both 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 +88,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 +101,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

@@ -1360,6 +1360,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>