@rubytech/create-realagent-code 0.1.24 → 0.1.27

package/payload/platform/plugins/brochures/skills/property-brochure/references/placeholders.md

@@ -0,0 +1,250 @@
+# 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/platform/plugins/brochures/skills/property-brochure/references/registers.md

@@ -0,0 +1,47 @@
+# 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 |
+|---|---|
+| **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. |
+
+## 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).
+
+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.
+
+## 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/real-estate-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.
+
+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), 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/platform/plugins/brochures/skills/property-brochure/references/seller-brief.md

@@ -0,0 +1,56 @@
+# 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.

package/payload/platform/plugins/brochures/skills/property-brochure/references/structure.md

@@ -0,0 +1,249 @@
+# Brochure structure — orientation, 16-page layout, cover, floorplan, features, MI, QR, map
+
+## Orientation
+
+Brochures ship in either **landscape** (297×210mm A4, default — the editorial folio is designed for it) or portrait (210×297mm A4). The choice changes page geometry, render-slot dimensions, print snapshot pixel sizes, the PDF call, and which page layouts make visual sense — it is **not a cosmetic flag**. Every downstream measurement has a landscape value and a portrait value.
+
+### When to ask
+
+Default to landscape unless the user says otherwise. The folio's editorial layouts (split heros, wide caption strips, full-bleed feature spreads, three-column plan + particulars + EPC pages) are tuned for landscape proportions; portrait works but compresses the spreads. If the user explicitly asks for portrait, fine — re-test every page's `scrollHeight` against the new fit budget before generating snapshots. If a prior brochure for this property exists at `<property_dir>/output/brochure.html`, inherit its orientation by reading the CSS (`@page { size: A4 landscape | portrait }`) rather than asking again.
+
+### Dimensional contract
+
+| Quantity | Landscape (default) | Portrait |
+|---|---|---|
+| `.page` width × height | 297mm × 210mm | 210mm × 297mm |
+| Page fit budget (px @ 96dpi) | 1123 × **794** | 794 × **1123** |
+| Print snapshot pixel dimensions | 1123×794 | 794×1123 |
+| `@page` rule | `size: A4 landscape` | `size: A4 portrait` |
+| Playwright `page.pdf()` | `landscape: true` | (default; portrait) |
+| "Safe to read" snapshot ceiling | longest-edge 1123px | longest-edge 1123px |
+
+The 1600px image-source ceiling from `images.md` is unchanged — it provides 2× retina headroom for full-bleed images at either orientation.
+
+### Reference template orientation swap
+
+`references/template.html` ships **landscape** (`width: 297mm; min-height: 210mm` across `.page`, `.cover`, `.backpage`, plus `@page { size: A4 landscape }` in the print CSS). For portrait, swap every `297mm` ↔ `210mm` in those rules and change `@page { size: A4 landscape }` to `@page { size: A4 portrait }`. The page-internal flex/grid layouts then redistribute against the new aspect — re-test every page's `scrollHeight` against the new fit budget (1123 instead of 794) before generating snapshots, and expect the editorial feel to compress: the wide caption strips and side-by-side spread layouts will need to stack rather than sit alongside.
+
+## 16-page structure
+
+Each page is a `<section class="page">` (or `.cover` / `.backpage`) sized to the chosen orientation: `width: 297mm; min-height: 210mm` (landscape) or `width: 210mm; min-height: 297mm` (portrait). Every page must fit within the orientation's short-edge budget (794px landscape, 1123px portrait — both at 96dpi). Measure with `element.scrollHeight` during development against that budget and adjust image heights with inline styles if content overflows.
+
+The page count is **sixteen** so the brochure prints cleanly on duplex (16 is even) and binds cleanly as a saddle-stitched booklet (16 ÷ 4 = 4 folded sheets). See `a4-print-documents` → **Even-page count for duplex printing**.
+
+| Page | Class | Chapter | Key content |
+|------|-------|---------|-------------|
+| 1 | `.cover` | Cover | Split layout — paper title block on top with property name + address subtitle, full-bleed hero photo below |
+| 2 | `.page` | Contents (TOC) | Editorial image with caption, eight-chapter table of contents (Roman i–viii), credit line, folio strip |
+| 3 | `.page` | I · Of place & pedigree | Opener — property name with county sub-line, street + postcode + price spec, 5-stat row, two-paragraph editorial intro with dropcap, principal elevation image with caption |
+| 4 | `.page` | II · A house at ease | Hero open-plan image, text column, three-image caption strip |
+| 5 | `.page intermission` | (no chapter — visual breath) | Full-bleed image-only spread between chapters; no editorial copy |
+| 6 | `.page` | III · Hall, hearth & sun | Split header, large left image, two stacked right images |
+| 7 | `.page intermission` | (no chapter — visual breath) | Full-bleed image-only spread between chapters |
+| 8 | `.page` | IV · Bedrooms & baths | Text column with 3-stat row, 5-cell gallery (one tall feature) |
+| 9 | `.page gallery-page` | Image-led additional internal | Full-page asymmetric photo grid (no body copy), gallery head with eyebrow + title, captions per cell |
+| 10 | `.page` | V · Pool, outdoor kitchen & summerhouse | Full-bleed feature image, narrow text panel with attribute grid (repurpose if no leisure block — annexe / studio / outbuilding) |
+| 11 | `.page intermission` | (no chapter — visual breath) | Full-bleed outdoor image-only spread |
+| 12 | `.page folio-dark` | VI · Garden & ground | Full-bleed aerial with overlaid title, four short-text panels, dark-pill folio chrome |
+| 13 | `.page siteplan-page` | (extension of VI) | Dedicated site-plan page — large plot plan on one side, plot/grounds text panel on the other |
+| 14 | `.page` | VII · Plan & particulars | Wide chapter header, large floor plan + meta, 8-9 item particulars list, EPC bar chart |
+| 15 | `.page` | VIII · Material information | Three-section disclosure grid (Parts A/B/C), boilerplate footer |
+| 16 | `.backpage` | Back page | Atmospheric background, brand masthead, CTA headline, tagline, two-cell contact grid (agent + office), QR strip (video tour + listing), folio footer, disclaimer |
+
+**Page-type classes.** The default folio uses three structural extensions to the base `.page`:
+
+- `.intermission` — full-bleed photo spread with no editorial copy. Three intermissions sit between chapters (after II, IV/gallery, V) to give the eye a beat. If the property doesn't have enough strong landscape/atmospheric photos to fill all three, drop the weakest intermission rather than reusing an image.
+- `.gallery-page` — asymmetric grid of property photos (typically 4–5 cells with one tall feature) with a small head block and per-cell captions. Used for "rooms in passing" — supplementary internal shots that don't anchor a chapter.
+- `.siteplan-page` — dedicated plot-plan page with a large plan image and a text-side panel describing acreage, paddocks, drives, outlook. Pairs with the **Garden & ground** chapter — both pages share Roman numeral VI.
+- `.folio-dark` — applied to dark/photo-heavy pages so the folio chrome swaps to light-on-dark.
+
+## Cover layout — title block above, photo below
+
+The cover is the property's name plate, not its full pitch. The reference register (Knight Frank country houses, Strutt & Parker folios, Sotheby's International Realty) uses a **split layout**:
+
+1. Top ~85mm of paper, ivory background, with the property name in serif caps with heavy letter-spacing, flanked by hairline gold rules, with one tracked-caps subtitle below (full address)
+2. Bottom ~125mm full-bleed photographic image — the strongest single hero shot, no overlays
+
+**Do not** place price, edition number, folio number, masthead with brand logo, tagline paragraph, or location eyebrow over the cover photo. Each of those is a contrast-fight against the photo and a magnet for the panel-treatment work-around. The cover reads as confident only when the image is unblemished.
+
+Where do those data points go instead?
+
+| Data point | Lives on |
+|---|---|
+| Property name + full address | Cover title block (the only thing on the cover) |
+| Price | Page 3 opener, beneath the property name in italic, *and* in Material Information |
+| Folio / reference number | Back page, foot-left in tracked caps, *and* implicitly in the URL |
+| Edition / season | Optional, back page foot-right; usually omitted for evergreen brochures |
+| Brand masthead / agency name | Back page top, as a logo (light/white variant on the dark back-page hero) |
+| Tagline | Page 3 opener body or back-page tagline |
+
+The Knight Frank pattern: **the property speaks first**. The agency surfaces on the back where the buyer reads contact details. The price surfaces on the second spread, after the buyer has seen the photo.
+
+## Floorplan sizing (page 10)
+
+Floorplans are the most information-dense images in the brochure. The plan area on page 10 is the largest rectangle that does not push the particulars list, EPC bar, or chapter header off A4. Use `object-fit: contain; width: 100%; height: 100%` so the image fills the slot without distortion. Wide-aspect floorplans leave vertical headroom; tall ones leave horizontal headroom — that's expected and fine. After any change, measure both `scrollHeight` against the orientation's page-fit budget (794px landscape / 1123px portrait) **and** the spec-side column's `scrollHeight` against `clientHeight` — text overflow is the silent failure that a screenshot can hide.
+
+If a brochure has multiple floor plans (per-floor breakdowns), tune the layout to the images' aspect ratios rather than splitting evenly. A 2:1 wide-aspect plan needs less vertical room than a 1.16:1 nearly-square one.
+
+## Distinguishing features clearly — "outdoor kitchen" ≠ "summerhouse" ≠ "orangery"
+
+Property listings in this register often have several distinct outdoor or auxiliary buildings, each photographed separately. The brochure must keep them distinct in copy *and* match each photo to the right structure. The recurring failure mode is collapsing them into a single noun ("the cedar pavilion", "the garden complex") that means different things on different pages.
+
+For Henham/Sparrows-Farm-style country homes the typical glossary is:
+
+| Feature | Description | Photo cue |
+|---|---|---|
+| **Outdoor kitchen** | Cedar-clad cooking pavilion with sloped tile roof, sink, grill, often a wood-fired oven, bench or table seating | Wood/cedar walls dominate; no glass walls; cooking equipment visible |
+| **Summerhouse** | Detached glass-walled structure on a raised stone plinth, accessed by steps, often houses a gym or studio | Glass walls dominate; not for cooking; raised on plinth |
+| **Orangery** | Internal-to-the-home glass-roofed reception room, opens onto patio, used as a third living room | Inside the home's footprint; vaulted glass roof; furnished with sofas |
+| **Garden room** | A room within the home or a detached pavilion overlooking the garden, less glass-heavy than the orangery | Often has corner glazing but solid walls behind |
+
+Use the precise noun in copy and the precise photo per chapter. Do **not**:
+
+- Call the outdoor kitchen "the summerhouse" because both are outdoor structures
+- Call the summerhouse "the cedar pavilion" because cedar is the cladding material of the *outdoor kitchen*; the summerhouse is glass-walled
+- Use "garden complex" as a chapter title — it's vague; use the actual feature names
+- Conflate the orangery (interior reception) with the garden room (different room entirely)
+
+Verify each feature has its own photograph and its own paragraph. If the property has a feature that isn't photographed prominently (e.g. the summerhouse only appears in a wide drone shot), surface that as `DONE_WITH_CONCERNS` so the user can decide whether to commission a shot or downplay the feature in the copy.
+
+## Material Information (UK regulatory compliance)
+
+Three tiers per National Trading Standards and DMCCA 2024. Populate all known fields; mark unknowns as "TBC":
+
+- **Part A** (all transactions): price, tenure, council tax, property type, rooms, floor area, utilities (electricity, water, sewerage, heating), broadband, mobile, parking, EPC
+- **Part B** (where applicable): building safety, covenants, rights of way, easements, listed status, conservation area, TPOs, accessibility
+- **Part C** (additional facts): flood risk, coastal erosion, planning, construction type, structural issues, subsidence, damp, asbestos, knotweed, mining
+
+### Floor area — exclude detached outbuildings
+
+Total internal floor area is the sum of the principal home's floors. **Do not include detached outbuildings** (gymnasium-summerhouses, garages, plant rooms, garden offices) in the principal floor figure even when they sit at the same level on the floor plan or share a footprint reference. List them separately:
+
+> Floor 1 · 2,573 sq ft · Floor 2 · 1,948 sq ft · Gymnasium (summerhouse) · 495 sq ft · Garage · 338 sq ft
+
+A first-floor figure that secretly includes a detached gymnasium is a misrepresentation — even by a small amount it changes the £/sq ft and the comparable. Keep the principal home's floors honest, and disclose ancillary footprints alongside.
+
+### Pulling material data from a third-party report
+
+For UK listings, a Sprift, Propalt or PropertyData report can supply many Part A and Part B/C values that are not on the public listing page. When the user supplies a Sprift report URL or invokes one of the API endpoints below, navigate the page in a browser (not `WebFetch` — Sprift dynamically loads its sections) and extract:
+
+| Source | What it adds |
+|---|---|
+| [Sprift KFB report](https://reports.sprift.com/...) | Tenure, title number, council tax band + £, EPC current/potential, broadband (FTTP/FTTC/ADSL speeds), mobile signal coverage, flood risk, conservation area, restrictive covenants, UPRN, local authority, plot acreage |
+| [Sprift API](https://sprift.com/data-and-api) | Same fields programmatically |
+| [Propalt API](https://propalt.co.uk/product/api) | Material info bundled |
+| [PropertyData / Land Registry API](https://propertydata.co.uk/api/land-registry) | Title number, sold-history, deed restrictions |
+
+Sprift's KFB report is the most useful free-form source — it's a single URL the user pastes, contains nearly everything needed for Part A, and is current. Treat the listing page as authoritative for marketing copy (price, photos, key features) and the Sprift KFB report as authoritative for compliance data (tenure, broadband, flood risk).
+
+## Back-page QR codes — clickable, with visible URL
+
+The back page includes two QR codes, one for the video tour and one for the listing URL. The QR images alone are sufficient for a printed brochure (a viewer scans with their phone), but the brochure is *also* read as a digital PDF and as a hosted web page, where a QR code is unscannable from the same screen. Each QR must therefore have:
+
+1. The QR image itself (for print scanning).
+2. A short label above describing what it links to ("Watch the *video tour*", "View the *full listing*").
+3. **A visible, underlined URL beneath the label** — short and human-readable (e.g. `youtu.be/8V7jjS5ZyeI`, `muvin.co.uk · listing 949931`).
+4. **The whole stack wrapped in an `<a>` tag with `target="_blank" rel="noopener"`** so the QR image, label and URL are all clickable in the digital PDF and on the web.
+
+Markup:
+
+```html
+<div class="back-qr-strip">
+  <a class="qr" href="https://youtu.be/<videoId>" target="_blank" rel="noopener">
+    <img src="images/qr-video.png" alt="Scan or click to view the property video tour">
+    <div class="qr-label">Watch the <em>video tour</em></div>
+    <div class="qr-link">youtu.be/<videoId></div>
+  </a>
+  <a class="qr" href="https://<agent>.co.uk/property/<slug>/<id>/" target="_blank" rel="noopener">
+    <img src="images/qr-listing.png" alt="Scan or click to view the full property listing">
+    <div class="qr-label">View the <em>full listing</em></div>
+    <div class="qr-link"><agent>.co.uk &middot; listing <id></div>
+  </a>
+</div>
+```
+
+The `.qr-link` is **always present** — never empty. A printed brochure shows it as a typeset URL; a digital reader hovers and clicks it. Don't let the URL wrap awkwardly: keep it short (path stripped), use `&middot;` to separate domain and identifier, and apply `font-variant-numeric: tabular-nums` to the digits so they kern cleanly in the underlined treatment.
+
+Default styling:
+
+```css
+.back-qr-strip a.qr {
+  display: flex; flex-direction: column; align-items: center; gap: 6px;
+  text-decoration: none; color: inherit;
+  transition: opacity 200ms ease;
+}
+.back-qr-strip a.qr:hover { opacity: 0.85; }
+.back-qr-strip .qr-link {
+  font-family: var(--sans);
+  font-size: 9px; font-weight: 400;
+  text-decoration: underline;
+  text-decoration-color: rgba(201,176,122,0.45);
+  text-underline-offset: 3px;
+  color: var(--gold-300);
+  text-align: center;
+  font-variant-numeric: tabular-nums;
+  margin-top: 4px;
+}
+```
+
+A common mistake is to ship QR codes without the visible URL — it makes the digital experience worse than the print one. The visible URL is mandatory.
+
+## Location map — extract or omit
+
+The brochure includes a location map **only when the source listing supplies one**. When the listing has no map, the brochure ships without a map slot. The pipeline never synthesises a map from a postcode, an OSM static-tile call, or AI-generated artwork — postcode centroids can mislead about exact location, and the brochure should reflect what the agent actually publishes, not what the pipeline could imagine. **Extract or omit.**
+
+### How the conditional works
+
+`property-extract` screenshots whatever map element exists on the listing — provider-agnostic by design. Google Maps iframes (Loop CRM / Muvin), Mapbox or Leaflet div+canvas builds, static-map `<img>` tags from Rightmove-style backends, Apple/Bing embeds — they all land as `<property_dir>/images/map.webp` and `media.map: "map.webp"` in `property.json`. When no map element is detected on the listing, both `media.map` and (typically) `address.geo` are `null`. See **Map — extract or omit** in the property-extract SKILL for the heuristic detector and the screenshot contract.
+
+The template ships with a marker-bounded conditional block on page 10 (Plan & particulars), in the `.spec-side` column above the EPC bars:
+
+```html
+<!-- BROCHURE_MAP_SLOT_START
+     CONDITIONAL: render only when property.json -> media.map is non-null.
+     If media.map is null, DELETE everything between BROCHURE_MAP_SLOT_START
+     and BROCHURE_MAP_SLOT_END (inclusive of both marker comments). -->
+<figure class="location-map">
+  <img src="images/map.webp" alt="Location of Property Name — Town, Postcode">
+  <figcaption>Source: Google Maps &copy; YYYY Google</figcaption>
+</figure>
+<!-- BROCHURE_MAP_SLOT_END -->
+```
+
+The agent's job at brochure-assembly time:
+
+| `property.json -> media.map` | Action |
+|---|---|
+| Filename string (e.g. `"map.webp"`) | Leave the block in place. Copy `<property_dir>/images/map.webp` into `<output>/images/map.webp` (re-encode at 1500px / q86 if not already optimised). Substitute the filename, alt text (property name + town/postcode), and the year in the figcaption. |
+| `null` | **Delete** every line between `<!-- BROCHURE_MAP_SLOT_START` and `<!-- BROCHURE_MAP_SLOT_END -->` **inclusive of both marker comments**. The page-10 layout reflows; no placeholder, no broken image, no empty box. |
+
+The marker pattern is the same in both the template HTML and this SKILL — grep `BROCHURE_MAP_SLOT_START` across the plugin to see every place it's referenced.
+
+### Attribution
+
+When the slot is rendered, the figcaption must credit the provider whose tiles are visible in the screenshot. Read `property.json -> address.geo.source` and choose the right line:
+
+| `source` value | Figcaption text |
+|---|---|
+| `google_maps_iframe` | `Source: Google Maps © {year} Google` |
+| `mapbox_iframe` | `Source: © Mapbox © OpenStreetMap` |
+| `apple_maps_iframe` | `Source: Apple Maps` |
+| `static_map_image` | Use the attribution shown on the source listing if visible; otherwise the provider name as a generic noun (e.g. `Source: location map © OpenStreetMap contributors`) |
+| `unknown` (screenshot only) | `Source: location map as shown on the agent's listing` |
+
+Don't strip the attribution — it's a licence requirement on most providers' tiles, not a stylistic flourish. Google's brand guidelines additionally forbid recolouring the word "Google", so when that's the source keep "Google" in `var(--ink)`, not the gold accent. The italic figcaption styling lives in the template under `.location-map figcaption`.
+
+### Forbidden patterns
+
+The user has explicitly rejected synthesised maps. **None of these are allowed when `media.map` is `null`**:
+
+- Geocoding the postcode via postcodes.io (or any other geocoder) and rendering a centroid-pinned static map
+- OSM static-tile calls as a fallback ("just any map is better than no map")
+- AI-generated map artwork (DALL-E / Imagen / Midjourney prompts that produce map-like images)
+- Re-using a screenshot from a different listing or a stock map asset
+
+If `media.map` is `null` and the user asks for a map anyway, the correct answer is to send them back to the source listing — either the agent enables the map block on their CRM, or the brochure ships without one. **Extract or omit.**
+
+### Cross-reference
+
+The render-slot table in `images.md` lists "Map / screenshot" with a 1500 px digital floor and q86 WebP — those values apply **only** when a map has been captured. When `media.map` is `null`, there is no map asset to optimise and the row is moot.