@rubytech/create-maxy-code 0.1.113 → 0.1.115

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

@@ -1,250 +0,0 @@
-# Placeholders — the substitution contract
-
-`template.html` and `index.html` are pure placeholder templates: every property-specific value is a `{{ token }}` token. There is no exemplar copy left to accidentally inherit. After rendering, `grep "{{" output/brochure.html` (and `output/web/index.html`) MUST return **zero matches**. Any remaining `{{ x }}` is a substitution bug.
-
-This file is the substitution contract — the exhaustive list of every token used across both templates, what fills it, what format it takes, and what voice the copy tokens need. Style and composition guidance lives in `copy.md` (and is referenced inline from each `<!-- REPLACE: ... -->` comment in the templates). The two files are complementary: this one says **what** each token is; `copy.md` says **how** the copy should read.
-
-Worked examples below quote the validated Sparrows Farm reference brochure at `/Users/neo/estate-agents/muvin/properties/henham-road-debden-green-hamperden-end-cb11-3lz-949931/output/brochure.html` — that brochure is the canonical "what good looks like." Read it whenever a placeholder's intent is unclear.
-
-## How to use this file
-
-1. Open the seller brief at `<property_dir>/seller-brief.md` and `<property_dir>/property.json` side-by-side.
-2. Walk the categories below top-to-bottom — common tokens first (identity, brand, agent, listing, specs), then chapter-by-chapter editorial copy.
-3. For each token, write the substitution into a single dict / map keyed by token name. The substitution step at the end of `property-brochure` reads the map and rewrites both files in one pass.
-4. Run the **completion check**: `grep -c "{{" output/brochure.html output/web/index.html`. Both files must return `0`. If any token is unsubstituted, it is a defect — the brochure is not shippable until every `{{ x }}` is gone.
-
-## Category 1 — Property identity
-
-These tokens are used everywhere — cover, opener, folio strips, footer, alt text, image filenames.
-
-| Token | Source | Format / length | Notes |
-|---|---|---|---|
-| `{{ property_name }}` | `property.json -> property_name`, or `address.line_1` if name is null | Title Case, ~10-30 chars | Distinct house name preferred ("Sparrows Farm", "Agincourt House"); falls back to the street ("12 Henham Road") when the property has no separate name. CSS renders it ALL-CAPS on the cover — source is Title Case. |
-| `{{ property_slug }}` | `property.json -> source.url` (slug part) | lowercase-kebab | Used in every image filename pattern: `images/{{ property_slug }}-NN.webp`. Examples: `sparrows-farm`, `agincourt-house`. |
-| `{{ address_line_1 }}` | `property.json -> address.line_1` | Title Case | Street or first address line ("Henham Road", "Llanddewi Rhydderch"). |
-| `{{ locality }}` | `property.json -> address.locality` | Title Case | Village / town district. |
-| `{{ town }}` | `property.json -> address.town` | Title Case | Nearest town. |
-| `{{ county }}` | `property.json -> address.county` | Title Case | County. |
-| `{{ postcode }}` | `property.json -> address.postcode` | UK format, with `&nbsp;` between out-code and in-code on the cover and in the brochure ("NP7&nbsp;9TS"). Plain in flat strings ("NP7 9TS"). | |
-| `{{ address_subtitle }}` | Composed from the above | `<line_1> <em>·</em> <locality> <em>·</em> <county> <em>·</em> <postcode>`, single line | Cover subtitle. The `<em>·</em>` separators are gold-coloured via CSS. |
-| `{{ folio_strip }}` | Composed | `{{ property_name }} · {{ locality }}` | Repeats on every interior page's left folio slot. |
-| `{{ folio_mid_NN }}` | Per-page chapter title | "Contents" / "Of place & pedigree" / "A home at ease" / etc. | Used in `<em>` of folio-mid. Match the chapter the page belongs to (intermissions inherit their parent chapter's mid-label). |
-
-Worked example (Sparrows Farm):
-- `property_name` = "Sparrows Farm"
-- `property_slug` = "sparrows-farm"
-- `address_subtitle` = `Henham Road <em>·</em> Hamperden End <em>·</em> Essex <em>·</em> CB11&nbsp;3LZ`
-- `folio_strip` = "Sparrows Farm · Hamperden End"
-
-## Category 2 — Brand pack
-
-From the brand pack at `<brand_dir>/{description.md, DESIGN.md}` and `property.json -> agent`.
-
-| Token | Source | Format | Notes |
-|---|---|---|---|
-| `{{ brand_slug }}` | `<brand_dir>` basename | lowercase-kebab | Used in logo filenames: `images/{{ brand_slug }}-logo-light.png` (dark surfaces) and `images/{{ brand_slug }}-logo-dark.png` (light surfaces). Naming convention is the **colour of the art**, not the surface — see `images.md` → "Brand logo". |
-| `{{ brand_name }}` | `description.md` first line | Title Case | "Muvin", "Beacons Real Estate". |
-| `{{ brand_town }}` | `description.md` officials block | Title Case | Branch town. |
-| `{{ brand_county }}` | `description.md` officials block | Title Case | |
-| `{{ brand_year }}` | Current year | YYYY | Used in the index.html footer copyright. |
-| `{{ office_address_line_1 }}` | `description.md` registered office line | "25 Bell Street" | Street, first line of the postal address. |
-| `{{ office_address_line_2 }}` | `description.md` registered office line | "Sawbridgeworth, Hertfordshire CM21 9AR" | Locality + county + postcode. |
-| `{{ office_phone }}` | `property.json -> agent.phone` | Display format | "01873 377 575". |
-| `{{ office_phone_tel }}` | Composed | `tel:` link format | "+441873377575" (no spaces, with country code). |
-| `{{ office_email }}` | `property.json -> agent.email` | lowercase | "sales@beaconsrealestate.com". |
-| `{{ email_subject_enquiry }}` | Composed | `{{ property_name }} — enquiry` | Used in mailto: subject param (URL-encode spaces if needed). |
-| `{{ email_subject_viewing }}` | Composed | `{{ property_name }} — viewing request` | Same as above. |
-
-## Category 3 — Named agent
-
-From `property.json -> agent`.
-
-| Token | Source | Format | Notes |
-|---|---|---|---|
-| `{{ agent_first_name }}` | First name | Title Case | Goes in `<em>` on the back page contact cell. |
-| `{{ agent_surname }}` | Last name (possibly hyphenated) | Title Case | Plain weight after the first name. |
-
-Worked example (Sparrows Farm): `{{ agent_first_name }}` = "Adam", `{{ agent_surname }}` = "Mackay".
-
-## Category 4 — Listing references
-
-From `property.json -> source` and `property.json -> media`.
-
-| Token | Source | Format | Notes |
-|---|---|---|---|
-| `{{ listing_url }}` | `source.url` | full URL | Used in QR + listing CTAs. |
-| `{{ listing_id }}` | `source.listing_id` | numeric | |
-| `{{ listing_display }}` | Composed | "{{ brand domain }} &middot; listing {{ listing_id }}" | Short, scannable text for QR caption (e.g. "beaconsrealestate.co.uk · listing 1424919"). |
-| `{{ video_url }}` | `media.video_tours[0]` | full URL | Empty string if no video; in that case drop the video QR per the back-page rules. |
-| `{{ video_short_url }}` | derived | "youtu.be/<id>" or equivalent | Visible URL under the video QR. |
-
-## Category 5 — Price
-
-From `property.json -> price`.
-
-| Token | Source | Format | Notes |
-|---|---|---|---|
-| `{{ price_qualifier }}` | `price.qualifier` | "Offers Over" / "Guide Price" / "Asking Price" / "POA" | Use VERBATIM from property.json — don't paraphrase. |
-| `{{ price_formatted }}` | `price.amount` | "£1,750,000" | UK-formatted with thousands separators. |
-| `{{ price_line }}` | Composed | `{{ price_qualifier }} {{ price_formatted }}` | Used inline in the opener spec line. |
-
-## Category 6 — Specs (visible on opener, hero info-card, particulars)
-
-From `property.json -> specifications`.
-
-| Token | Source | Format | Notes |
-|---|---|---|---|
-| `{{ tenure }}` | `specifications.tenure` | "Freehold" / "Leasehold" / "Share of Freehold" | |
-| `{{ year_built }}` | `specifications.year_built` | YYYY or descriptive | The hero info-card uses "c.&nbsp;YYYY". |
-| `{{ epc_rating }}` | `specifications.epc_rating` | Single letter A-G or "TBC" | |
-| `{{ spec_beds }}` | derived | "5 Bed" / "5 Bedrooms" | Page.html hero info-card uses short form ("5 Bed"). |
-| `{{ spec_baths }}` | derived | "4 Bath" | |
-| `{{ spec_area }}` | derived | "4,521 sq ft" | |
-| `{{ spec_plot }}` | derived | "2.20 acres" or drop the cell if no plot | |
-| `{{ opener_meta_N_label }}` / `{{ opener_meta_N_value }}` | derived | Five fixed cells | Typical labels: Bedrooms, Bathrooms, Receptions, Internal, Plot. Drop a cell (don't fill with TBC) if the value is genuinely unknown. The row MUST NOT wrap — see copy.md "Stats rows". |
-
-## Category 7 — TOC chapter list (page 2)
-
-Eight chapters in the canonical folio. Each entry has three tokens.
-
-| Token group | Format | Notes |
-|---|---|---|
-| `{{ toc_chapter_N_title }}` | Title Case, short | "Of place & pedigree", "A home at ease", "Hearth & hall", "Bedrooms & baths", "Terrace & outdoor kitchen", "Garden & ground", "Plan & particulars", "Material information". Adapt to the property — never use vague nouns ("garden complex"); name the actual features. |
-| `{{ toc_chapter_N_sub }}` | sentence case, ~6-12 words | One-line "what's in this chapter" — appears under the title in tracked-caps small slate. |
-| `{{ toc_chapter_N_page }}` | "03", "04", "06", "08", "10", "12", "14", "15" by default | MUST match the actual rendered pages. Intermissions (pages 5, 7, 11) and the site-plan page (13) are not numbered in the TOC. |
-| `{{ toc_caption }}` | italic sentence, 15-30 words | Elevator pitch, sits over the TOC hero image. Distilled from seller brief Q5 ("the feeling on entry") + Q19 ("three words"). |
-| `{{ toc_credit }}` | two-line block | Italic photography note + "Marketed by {{ brand_name }}, {{ brand_town }}, {{ brand_county }}." See template inline for exact format. |
-
-## Category 8 — Chapter editorial copy
-
-Each chapter's narrative tokens. Length and voice rules below; the full register guidance is in `copy.md`.
-
-### Chapter I — Opener (page 3)
-
-| Token | Length / voice | Source |
-|---|---|---|
-| `{{ chapter1_eyebrow }}` | "Chapter I · <chapter1 title>" | Match the TOC chapter-1 title. |
-| `{{ opener_title_main }}` | The property name as h2 glyph | One word or compound noun. CSS renders italic. |
-| `{{ opener_title_sub }}` | `<locality>, <county>` | Tracked caps via CSS. |
-| `{{ opener_spec_line }}` | `<strong>{{ address_line_1 }}</strong> · {{ postcode }} &nbsp;·&nbsp; <em>{{ price_line }}</em>` | Single line. |
-| `{{ opener_para_1 }}` | 4-6 sentences, dropcap. Place + age + tenure context. | Distil seller brief Q1 + Q3 + Q11. |
-| `{{ opener_para_2 }}` | 3-4 sentences. Period + craft + modern comfort. End on an italic phrase. | Distil seller brief Q3 + Q10. |
-| `{{ opener_image_alt }}` / `{{ opener_image_caption }}` | One factual + one italic sentence | The principal elevation or strong aerial. |
-
-### Chapter II — A home at ease (page 4) + intermission (page 5)
-
-| Token | Length / voice |
-|---|---|
-| `{{ chapter2_eyebrow }}` | "Chapter II" |
-| `{{ chapter2_heading }}` | h3, italic close — "A home <em>at ease</em>" |
-| `{{ chapter2_deck }}` | one italic sentence, 12-25 words |
-| `{{ chapter2_para_1 }}` | 4-6 sentences — entrance through reception to central living |
-| `{{ chapter2_para_2 }}` | 3-5 sentences — kitchen specifics + utility/outdoor connection |
-| `{{ chapter2_strip_N_caption_label }}` | bold lead-in (e.g. `"The kitchen."`) |
-| `{{ chapter2_strip_N_caption_text }}` | one descriptive sentence |
-| `{{ intermission_05_caption }}` | italic anchor sentence, 10-20 words, starts with `<em>The [room]</em>,` |
-
-### Chapter III — Hearth & hall / equivalent (page 6) + intermission (page 7)
-
-Same shape as Chapter II — one eyebrow, one heading, one deck, one body paragraph (longer: 6-9 sentences walking through secondary reception rooms), one big-image alt, two stacked-image alts.
-
-### Chapter IV — Bedrooms & baths (page 8)
-
-| Token | Length / voice |
-|---|---|
-| `{{ chapter4_eyebrow }}` | "Chapter IV" |
-| `{{ chapter4_heading }}` | "Bedrooms<br>&amp; <em>baths</em>" |
-| `{{ chapter4_deck }}` | italic, 15-25 words. Count + principal-suite signature. |
-| `{{ chapter4_para_1 }}` | 3-5 sentences walking the sleeping floor |
-| `{{ chapter4_stat_N_value }}` / `{{ chapter4_stat_N_label }}` | Big number (.v) + all-caps label (.l). Typical: 5 bedrooms / 3 bathrooms / first-floor sq ft. |
-| `{{ chapter4_para_2 }}` | 2-3 sentence closer on the principal suite |
-| 5 gallery cells | Mix principal-bedroom (tall feature cell) + secondary bedrooms + family bathroom. Verify pixel content matches the principal in the tall cell. |
-
-### Chapter V — Feature page (page 10) + intermission (page 11)
-
-For properties with a true garden complex (pool, summerhouse, outdoor kitchen, paddocks) this is the leisure chapter. For others, repurpose to the property's most distinctive outdoor or auxiliary feature (annexe, studio, terrace, pavilion).
-
-| Token | Length / voice |
-|---|---|
-| `{{ chapter5_eyebrow }}` | "Chapter V · <feature title>" |
-| `{{ chapter5_heading }}` | italic editorial headline, two-line |
-| `{{ chapter5_deck }}` | italic, 18-30 words |
-| `{{ chapter5_para }}` | 5-7 sentences. **Name each feature exactly** — outdoor kitchen ≠ summerhouse ≠ orangery; see structure.md "Distinguishing features clearly". |
-| `{{ chapter5_attr_N_label }}` / `{{ chapter5_attr_N_value }}` | Four crisp facts — plot, signature feature, count, material. |
-| `{{ intermission_11_caption }}` | italic anchor sentence |
-
-### Chapter VI — Garden & ground (page 12) + site plan (page 13)
-
-| Token | Length / voice |
-|---|---|
-| `{{ chapter6_eyebrow }}` | "Chapter VI" |
-| `{{ chapter6_heading }}` | italic two-line |
-| `{{ chapter6_panel_N_heading }}` / `{{ chapter6_panel_N_body }}` | Four panels each: italic h4 + 2-3 sentence body. Typical four: rear garden, paddocks/plot, front/approach, ancillary outbuildings. Re-title per property. |
-| `{{ siteplan_eyebrow }}` | "Continued, Chapter VI · The plot" |
-| `{{ siteplan_heading }}` | the plot's headline fact ("In excess of <em>2.20 acres</em>", "The <em>plot &amp; outlook</em>") |
-| `{{ siteplan_panel_N_heading }}` / `{{ siteplan_panel_N_body }}` | Three panels: plot, boundary, garden complex / outbuildings. |
-
-### Chapter VII — Plan & particulars (page 14)
-
-| Token | Length / voice |
-|---|---|
-| `{{ chapter7_eyebrow }}` | "Chapter VII · Plan &amp; particulars" |
-| `{{ chapter7_heading }}` | "All floors <em>at a glance</em>" |
-| `{{ floorplan_lead }}` | italic — "Total internal area · <em>X sq ft</em> · Y m&sup2;" |
-| `{{ floorplan_sub }}` | Floor-by-floor breakdown + ancillary footprints, joined by &nbsp;·&nbsp;. **List outbuildings separately** — never silently roll detached gymnasium / garage / annexe sq ft into the principal home figure. See structure.md "Floor area". |
-| `{{ particular_N }}` × 9 | Numbered particulars — each a single short sentence with `<strong>` on the named element. Sequence: architectural fact → character feature → kitchen specifics → heating/services → signature internal → signature outdoor → ancillary buildings → plot → outlook. Drop unused slots; never go over 9 (column overflows). |
-| `{{ epc_current_a..g }}` | The matching band gets ` current` (leading space → CSS class). All others empty string. Exactly one is non-empty. |
-| `{{ epc_caption }}` | 1-2 sentences on heating + what the band reflects. |
-
-### Chapter VIII — Material information (page 15)
-
-Every `{{ mi_* }}` token corresponds to a Material Information row. Mark unknowns "TBC" verbatim — **never invent**. Drop a row only if the field is genuinely not applicable (e.g. Coastal Erosion for an inland home). `{{ mi_part_b_extra_label }}` / `{{ mi_part_b_extra_value }}` is a per-property slot for a distinctive fact (e.g. "Pool", "Annexe", "Outdoor"). See structure.md "Material Information".
-
-### Back page (page 16)
-
-| Token | Length / voice |
-|---|---|
-| `{{ backpage_bg_src }}` / `{{ backpage_bg_alt }}` | Atmospheric exterior at golden hour (slot 26 or back-equivalent). |
-| `{{ backpage_headline }}` | "Arrange a viewing of <em>{{ property_name }}</em>" — canonical phrasing. |
-| `{{ backpage_tagline }}` | 25-45 words. Mirrors but does not duplicate the cover/opener. Close with "Best understood in person." or equivalent clincher. |
-
-## Category 9 — index.html (landing) editorial copy
-
-The landing page mirrors the brochure's content but in a continuous-scroll form. Tokens are prefixed `landing_*` to avoid name collisions with the brochure tokens. Sections:
-
-| Section | Tokens | Notes |
-|---|---|---|
-| Story | `{{ landing_story_eyebrow }}`, `{{ landing_story_headline }}`, `{{ landing_story_para_1 }}`, `{{ landing_story_para_2 }}` | Same source as Chapter I opener but scaled for screen — para 1 short (3-4 sentences) for dropcap legibility; para 2 longer (4-6). |
-| Home | `{{ landing_home_eyebrow }}`, `{{ landing_home_headline }}`, `{{ landing_home_para_1..3 }}` | Three paragraphs: entrance/flow, kitchen-dining, reception/orangery. |
-| Bedrooms | `{{ landing_bedrooms_eyebrow }}`, `{{ landing_bedrooms_headline }}`, `{{ landing_bedrooms_para_1..2 }}` | Two paragraphs. |
-| Garden | `{{ landing_garden_eyebrow }}`, `{{ landing_garden_headline }}`, `{{ landing_garden_para_1..2 }}` | Two paragraphs. |
-| Area | `{{ landing_area_eyebrow }}`, `{{ landing_area_headline }}`, `{{ landing_area_para_1..2 }}` | Two paragraphs — admin/transport + qualitative setting. |
-| Photo grids 1-6 | `{{ landing_grid_N_src_a..d }}` / `{{ landing_grid_N_alt_a..d }}` | Four cells per grid; image filenames reference the same {{ property_slug }}-NN.webp slots used in the brochure. |
-| Floor plan section | `{{ landing_floorplan_heading }}`, `{{ landing_floorplan_lead }}`, `{{ landing_floorplan_row_N_k }}` / `{{ landing_floorplan_row_N_v }}` × 5 | Up to 5 rows + an EPC row that reuses `{{ epc_rating }}`. Drop a row if the property doesn't have that footprint. |
-| Key facts | reuses `{{ mi_* }}` tokens from the brochure + `{{ landing_flood_summary }}` | The landing-page "Key facts" compresses Part A into 15 rows. |
-| CTA strip | `{{ landing_cta_headline }}` | "Interested? Let's talk." or property-specific. |
-| Nav anchors | `{{ nav_section_1..4 }}` | Defaults: "Story", "The Home", "The Garden", "The Area". Rename only if the property's narrative arc differs. |
-| `{{ hero_tag }}` | "For Sale · New" / "For Sale" | The small tracked-caps tag on the hero info-card. |
-| `{{ hero_N_src }}` / `{{ hero_N_alt }}` × 3 | Three Ken-Burns hero slides. THREE DIFFERENT MOMENTS — not three angles. |
-| `{{ page_title }}` | "<Property name> · <street>, <locality> · For Sale" | Browser tab. |
-| `{{ meta_description }}` | Same single-sentence pitch as `{{ backpage_tagline }}`. |
-
-## Completion check
-
-The substitution step that runs `property-brochure` should end with this verification gate:
-
-```bash
-PROP=<property_dir>
-remaining=$(grep -c '{{' "$PROP/output/brochure.html" "$PROP/output/web/index.html" 2>/dev/null | awk -F: '{s+=$2} END {print s}')
-if [ "$remaining" -gt 0 ]; then
-  echo "DEFECT: $remaining unsubstituted {{ tokens }} remain — see grep '{{' output/"
-  exit 1
-fi
-echo "Substitution clean."
-```
-
-A brochure with any `{{ x }}` remaining in the rendered output is shipped broken — the verification gate is mandatory.
-
-## Adding a new token
-
-If a property has a feature the canonical placeholder set doesn't cover (e.g. an annexe with separate utility, a wine cellar, a moat — they exist), do not invent a new token in the templates without also adding the entry here. The substitution contract is what catches the bug; an unlisted token gets silently ignored by the substitution step and the brochure ships with `{{ wine_cellar }}` literal in the body. Either reuse an existing token, or add the new one to this file AND to template.html/index.html before rendering.

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

@@ -1,105 +0,0 @@
-# Visual register — premium vs branded
-
-The skill template ships with a default super-premium visual scheme. Two registers govern how that scheme interacts with the agent's brand pack.
-
-## Default scheme baked into `references/template.html`
-
-- **Type**: Cormorant Garamond (display, italics for emphasis) + Lora (humanist serif body) + Inter (tabular numerics, particulars labels)
-- **Palette**: ivory paper (`#F8F4ED`), ink (`#0E1418`), bronze (`#7A6235`), antique gold (`#A4884C`), champagne (`#C9B07A`)
-- **Voice**: editorial, considered, country-house tone — chapters numbered in Roman, dropcaps, pull quotes
-- **Layout**: A4 landscape, 16 pages, asymmetric photo grids, full-bleed feature spreads, intermission breaks between chapters, ornamental rules between sections
-
-## The two registers
-
-| Register | What you change |
-|---|---|
-| **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 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` (affirmative — preserve display family's natural italic cut; recipe emits no override) / `weight-shift` (flatten italic to bold sans-like) / `normal` (flatten italic, no weight bump). Default if omitted is the same as `italic`; setting `italic` explicitly is preferred so the choice is recorded affirmatively rather than silently. |
-| `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:
-
-- `<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/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) 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.
-
-## What neither register authorises
-
-- Replacing the skill template with a brand's existing brochure HTML
-- Restructuring the page count, page order, or chapter grid because the brand's other materials look different
-- 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 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/seller-brief.md

@@ -1,56 +0,0 @@
-# Seller brief — the source of editorial voice
-
-The seller brief at `<property_dir>/seller-brief.md` is the single most influential input to the brochure's copy. It is an interview document with 20 questions that the operator collected from the seller (the home's current owner). Read it once, in full, before writing any chapter copy. It does not get quoted verbatim unless an answer is explicitly marked `[VERBATIM]` — it is *distilled* into the editorial register.
-
-A complete brief is a precondition for `property-brochure` (and the orchestrator gates on it — see `make-brochure → Brief routing`). If the brief is missing or incomplete, stop and report the gap; do not synthesise answers from the listing description.
-
-## Per-question mapping — what each answer informs
-
-The 20 questions cluster into four uses: **voice setters** (Q5, Q19, Q20 — set tone of the cover and opener), **body content** (Q1–4, Q6, Q7, Q11–14 — body paragraphs across chapters), **list emphasis** (Q8–10, Q18 — particulars list and feature highlights), and **disclosure** (Q15–17 — buyer avatar and Material Information context).
-
-| Question | What it informs in the brochure |
-|---|---|
-| **Q1.** Why did you first buy this home? | Opener body paragraph 1 (the home's "of place & pedigree" framing) |
-| **Q2.** Length of ownership / why selling now | Not surfaced directly; informs the brochure's tense and time-frame voice |
-| **Q3.** What you love most | Cover sub-line candidate; opener body paragraph 2 (the "what makes this house unusual" hook) |
-| **Q4.** What you'll miss most | Back-page tagline candidate; orangery / sitting-room caption |
-| **Q5.** Feeling on first walking through the door | **The opening chapter deck** — the single italic sentence at the top of page 3. This is the brochure's tone-of-voice contract. |
-| **Q6.** Your favourite room | The room that gets *hero* treatment in its chapter (tall feature cell, full-bleed intermission, or strongest in-spread image). The brochure agent re-orders slot priority around this answer. |
-| **Q7.** Lifestyle the home supports | Buyer-avatar tone of every body paragraph; choice of which chapter gets emphasis (e.g. an entertainer's home leans into pool/kitchen/dining; a quiet retreat leans into garden/orangery) |
-| **Q8.** Renovations done? | Particulars list i–iii items; opener body paragraph 2 |
-| **Q9.** What changed and why | Particulars list item phrasing — *what* the seller did becomes the headline; *why* becomes the qualifying clause |
-| **Q10.** Design details others notice | Strip-cell captions (page 4); attr-grid features (page 7 feature page) |
-| **Q11.** What you love about the local area | Garden & ground page text panels (rear garden, front & approach, ancillary) |
-| **Q12.** Hidden gems nearby | Garden & ground secondary panel; possibly a footnote on the back page |
-| **Q13.** Commute / transport | Opener spec line (e.g. "*Essex · CB11 3LZ · 50 minutes from Liverpool Street*") if commutable |
-| **Q14.** Community vibe | Garden & ground tone; back-page tagline supporting line |
-| **Q15.** Who this home suits best | Buyer-avatar tone (reinforces Q7) |
-| **Q16.** Hoped-for next buyer | Tone of the back-page CTA ("Arrange a viewing of …") |
-| **Q17.** Anything that needs context before viewings | Material Information page note (page 11) — the "context" line above the disclosure grid, or a footnote on a specific MI row |
-| **Q18.** What buyers might overlook | Promotes a slot from strip-cell to hero, or surfaces a particular in the list that wouldn't otherwise be there |
-| **Q19.** Three words to describe the home | **Cover sub-line OR opening chapter deck.** The seller's three words appear unrephrased — they are the home's tagline. If the cover already uses Q5 for the deck, Q19 lands on the cover sub-line in tracked-caps small. |
-| **Q20.** Feeling, story, or phrase for buyers to connect with | **Cover tagline OR back-page tagline.** This is the single phrase the brochure carries. If marked `[VERBATIM]`, it is preserved word-for-word. Otherwise it is gently distilled into the editorial register. |
-
-## Distil, don't quote — except [VERBATIM]
-
-Sellers' answers are conversational. The brochure's register is editorial. Most answers are *distilled* — the seller's "we love how the morning light comes through the chapel windows of the principal bedroom" becomes a deck like *"the morning light through chapel-style windows."* The seller's **information** survives; the seller's **conversational cadence** does not, except where they tag an answer `[VERBATIM]`.
-
-`[VERBATIM]` is a contract: the answer is preserved exactly, in italic, as a pull-quote on a chapter page or as the back-page tagline. Use it sparingly — at most one or two per brochure. The Q20 answer is the most common candidate; Q4 and Q5 occasionally.
-
-## Worked example — Sparrows Farm
-
-(Hypothetical — Sparrows Farm shipped without a brief; a real example would source from the seller.)
-
-> **Q5.** A buyer should feel that the home is *settled*. Six hundred years of beam and stone with a kitchen that wants to be cooked in.
->
-> **Q19.** *Settled. Restored. Loved.*
->
-> **Q20.** [VERBATIM] *A timeless home, lived in well.*
-
-Becomes:
-
-- Opening chapter deck (page 3): "A home built to be settled in — six hundred years of beam and stone, with a kitchen that wants to be cooked in."
-- Cover sub-line (page 1): "SETTLED · RESTORED · LOVED" (tracked caps, beneath the title)
-- Back-page tagline (page 16): *"A timeless home, lived in well."* — preserved verbatim, in italic, beneath "Arrange a viewing of …"
-
-The brochure agent records which question informed which copy element in a one-line internal log so a reviewer can check that every brief answer found a place in the brochure.