@rubytech/create-realagent-code 0.1.24 → 0.1.27

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

@@ -0,0 +1,211 @@
+# Editorial copy register, typography, on-image text
+
+The brochure templates are placeholder-only — every body string is a `{{ token }}` (see `placeholders.md`). This file owns the **register and composition rules** for the copy that fills those tokens: voice, length, sentence count, and the per-section structural expectations.
+
+When in doubt about what "good" reads like, open 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`. It is the canonical worked example for every register rule below. The rules — not the example — are the contract; the example shows what those rules produce.
+
+## Editorial copy register — what super-premium reads like
+
+The brochure is editorial print, not a property listing description. Body copy is read aloud, in full sentences, with restraint. A handful of rules separate luxury copy from middle-market or AI-tell copy.
+
+### Reduce em-dash usage
+
+" — " (em-dash with spaces) used as a connector between phrases is **a hallmark of AI-generated copy** and undermines the luxury feel. The pattern looks like: *"The home pairs period and craft — original beams, Italian Mandarin stone — with twenty-first-century comforts."* On every read, replace each instance with one of:
+
+| Pattern | Replacement |
+|---|---|
+| Parenthetical aside (" — A — B — C — ") | Comma list, or a colon followed by a clause, or split into two sentences |
+| Connector between two clauses | Comma, or full stop and new sentence |
+| Emphasis dash | Restructure so the emphasis sits in a strong noun or `<strong>` tag instead |
+
+A single em-dash per page is fine. Two or more in the same paragraph reads as machine cadence.
+
+### "Home" not "house"
+
+At the super-premium register, "home" is warmer, more personal, and more aspirational. Replace "house" with "home" globally in body copy, decks, taglines and chapter titles, *unless* the word appears in a literal grammatical context that requires it (e.g. "principal house" as a property classification). The chapter "A house at ease" becomes "A home at ease".
+
+This is a register choice, not a grammatical one. Use the word the buyer will use: *the home* they are touring, not *the house* they are inspecting.
+
+### Reflow text to avoid orphan words
+
+A single word stranded on its own line in a short caption or tagline reads as a layout failure. After populating any caption, deck, or tagline that wraps to multiple lines, scan for orphans (one word on the last line) and either tighten the copy or insert a manual `<br>` so the lines balance. Particularly in cover taglines, TOC captions, and back-page CTAs.
+
+### Verify on every body-heavy page
+
+After populating copy, scan the body of every chapter for em-dashes (count them — under three across the whole brochure is a good target), for any remaining "house" references, and for orphan-word line breaks.
+
+## Text on images — use a translucent panel, not a gradient
+
+When body or caption text is placed over a photographic background, **the only reliable legibility technique is a translucent dark panel directly behind the text**, with the text in `var(--paper-0)` (pure white). Gradients on the underlying image and `text-shadow` on the text are *not sufficient* — they look fine on the average pixel and fail on every busy-pattern pixel (stone tile floors, golden-hour skies, leaf canopies, bright pool reflections).
+
+The contract for any text-on-image element is:
+
+```css
+.caption-on-image {
+  position: absolute;
+  /* anchor at one corner */
+  padding: 12px 16px 14px;
+  background: rgba(14, 20, 24, 0.78);   /* translucent ink panel */
+  border-left: 1px solid var(--gold-300); /* OR border-right, matching caption alignment */
+  color: var(--paper-0);
+  font-family: var(--body-serif);       /* italic at the chosen size */
+  font-style: italic;
+  font-size: 14–16px;
+  line-height: 1.45–1.55;
+}
+```
+
+Notes:
+
+- Opacity in the 0.72–0.82 range allows the photo to show through subtly while keeping the type fully legible. Solid black panels look grafted-on; transparent gradients look broken.
+- The 1px gold border on the leading edge gives the panel a deliberate editorial note — it reads as a "credit slip" or "name plate", not a UI overlay.
+- Text shadow can be added as belt-and-braces but is not load-bearing. The panel is.
+- The panel applies to **every** text-on-image element: TOC caption, opener image caption, feature-page photo caption, intermission caption-pills, and the spread-6 chapter overlay (which uses the same pattern with `background: rgba(14,20,24,0.78)` plus `color: var(--paper-0)` and `border-left: 1px solid var(--gold-300)`).
+
+Variants for left-aligned vs right-aligned captions: use `border-left` for left-anchored panels, `border-right` for right-anchored. Don't centre-align panel text — editorial captions are flush-left.
+
+### Why a gradient is insufficient
+
+A `linear-gradient(180deg, transparent 60%, rgba(0,0,0,0.45) 100%)` darkens the bottom 40% of the image evenly. But the pixels directly behind the text vary photo-by-photo: a beige stone-tile floor at the bottom of a kitchen photo gives a 0.45-darkened beige pixel that is *still* close to white at small italic point sizes; a golden-hour cloud has a similar problem. The panel removes the variability — it presents one consistent dark surface behind the text regardless of what the photo is doing in that region.
+
+This rule applies consistently across all on-image text, including the cover. If the cover has overlay text (price, folio number, edition), it must use the panel treatment — or, preferably (per the *Cover layout* note in `structure.md`), drop the overlay text entirely and use the split-paper-above / photo-below cover layout where overlays don't arise.
+
+## Body typography — ragged-right only
+
+Paragraph body copy in property brochures uses `text-align: left; hyphens: none` (ragged-right). Justified body copy is **forbidden**: at the body sizes used in print marketing (~10–11pt), justification produces either visible rivers or hyphenated word breaks (e.g. "de- / signed", "thresh- / olds"). Both look cheap. Drop justification, accept the ragged right edge — it is the correct choice for editorial print.
+
+```css
+.ed-body, .ed-deck, .opener-body p, .feature-page .panel p {
+  text-align: left;
+  hyphens: none;
+  -webkit-hyphens: none;
+  word-break: normal;
+  overflow-wrap: normal;
+}
+```
+
+Headings and display type are exempt — they don't trigger hyphenation at large sizes anyway, and a centred or balanced heading is fine.
+
+**Verification.** After capturing print snapshots, scan a body-heavy page (typically the opener, the feature page, or any `.ed-body` paragraph that exceeds ~5 lines) for trailing hyphens at line-ends. If any appear, the rule above isn't applied to that paragraph's class. Common omissions: `.opener-body .ed-body` (different selector specificity), `.feature-page .panel p` (uses a custom paragraph class).
+
+## Stats / facts rows must never wrap a value
+
+Every numeric or short-label cell in a stats row (the 5-stat strip on the opener, the 3-stat block in `.ed-stat`, the meta-row above any photo, the EPC quick-facts band) must be single-line. The row layout shrinks before any cell wraps. Wrapping "1,821 sq ft" across two lines because the row is one cell too wide is an editorial failure — the row reads as a broken table, not a confident summary.
+
+```css
+.opener-meta-row {
+  display: flex; flex-wrap: nowrap; gap: 14px;
+  font-variant-numeric: tabular-nums;
+}
+.opener-meta-row .item { flex: 0 1 auto; min-width: 0; white-space: nowrap; }
+.opener-meta-row .item .k,
+.opener-meta-row .item .v,
+.opener-meta-row .item .v em { white-space: nowrap; }
+```
+
+If five cells at the chosen font size do not fit the available row width, **shrink the font-size or padding** until they do — do **not** drop `flex-wrap: nowrap`, do **not** widen the page, do **not** wrap a value. `font-variant-numeric: tabular-nums` is recommended for the digits — it gives the row consistent column widths and looks more like print typography than the default proportional figures.
+
+**Verification.** After capturing print snapshots, scan the opener (page 3) and the bedrooms-and-baths page (page 6, with `.ed-stat`) for any value that wraps to a second line. If any cell wraps, either the font-size is too large for the row width or the row is missing `flex-wrap: nowrap`.
+
+## Per-section composition guide
+
+This section is the writing brief for each placeholder block in `template.html` and `index.html`. The token names map 1:1 to entries in `placeholders.md`; this file says **how the copy should read** for each one.
+
+### Cover & subtitle (page 1)
+
+- `{{ property_name }}` — Title Case proper noun. Distinct house name preferred ("Sparrows Farm", "Agincourt House"); fall back to the street as proper noun when the property has no separate name. Keep it short — CSS renders it ALL-CAPS with heavy tracking, capped at ~28 source characters between the gold flank rules.
+- `{{ address_subtitle }}` — postal address in four parts joined by ` <em>·</em> `. Single line; do not wrap.
+- The cover carries NO price, NO edition number, NO masthead text over the photo. Those data points live elsewhere (see structure.md "Cover layout").
+
+### TOC (page 2)
+
+- `{{ toc_caption }}` — ONE italic sentence, 15-30 words. The property's elevator pitch. Distil from seller brief Q5 ("the feeling on entry") + Q19 ("three words to describe the home"). It sits on a translucent dark panel over the TOC hero — no gradient fallback (see "Text on images" below).
+- `{{ toc_chapter_N_title }}` — chapter names in Title Case, short. Adapt to the property: if there's no pool, the chapter is not "Pool, outdoor kitchen & summerhouse" — it's "Terrace & outdoor kitchen" or "The annexe & studio". Never use vague nouns ("garden complex") that hide which feature you mean.
+- `{{ toc_chapter_N_sub }}` — sentence case, 6-12 words. The "what's in this chapter" line.
+- `{{ toc_chapter_N_page }}` — MUST match the rendered page index. Default 16-page folio: 03, 04, 06, 08, 10, 12, 14, 15.
+
+### Opener (page 3 — Chapter I)
+
+- `{{ opener_title_main }}` — the property name as an h2 glyph. CSS italicises.
+- `{{ opener_title_sub }}` — `<locality>, <county>`. Tracked caps via CSS.
+- `{{ opener_spec_line }}` — `<strong>{{ address_line_1 }}</strong> · {{ postcode }} &nbsp;·&nbsp; <em>{{ price_line }}</em>`. The strong/em formatting holds the eye on street + price.
+- `{{ opener_meta_N_value }}` × 5 — five short single-line values. Drop a cell (don't fill with TBC) if a value is genuinely missing.
+- `{{ opener_para_1 }}` — 4-6 sentences carrying the dropcap. Set place + age + tenure context. Open with the home in its setting; close with a hook that earns the page-turn. Distil seller brief Q1, Q3, Q11.
+- `{{ opener_para_2 }}` — 3-4 sentences. Pairs character with comfort (period + modern; craft + convenience). End on a one-sentence italic phrase wrapped in `<em>` — the brochure's "voice signature" closer.
+
+### Chapter II — A home at ease (page 4) + intermission (page 5)
+
+- `{{ chapter2_heading }}` — h3 with italic close. Use `<em>` on the last 1-2 words. Avoid "house" — use "home" (see "Home not house" below).
+- `{{ chapter2_deck }}` — ONE italic sentence, 12-25 words.
+- `{{ chapter2_para_1 }}` — 4-6 sentences. Walk the reader from the entrance through the principal reception(s) to the central living space (kitchen-dining-living). Lean on light, beam, stone, glazing.
+- `{{ chapter2_para_2 }}` — 3-5 sentences. Kitchen specifics (cabinetry, worksurfaces, appliances by brand if distinctive) + how the rooms connect to utility and outdoor.
+- `{{ chapter2_strip_N_caption_label }}` + `{{ chapter2_strip_N_caption_text }}` — bold lead-in (e.g. `"The kitchen."`, `"Wolf & Sub-Zero."`) followed by ONE descriptive sentence.
+- `{{ intermission_05_caption }}` — italic anchor sentence, 10-20 words. Starts with `<em>The [room]</em>,` to match the photo.
+
+### Chapter III — Hearth & hall (page 6) + intermission (page 7)
+
+- `{{ chapter3_heading }}` — two-line h3 with italic close.
+- `{{ chapter3_deck }}` — italic sentence.
+- `{{ chapter3_para }}` — one longer body paragraph, 6-9 sentences. Walks the secondary reception rooms (hearth, hallway, drawing room, orangery/conservatory, fifth ground-floor bedroom if present). Each named room earns a clause that says what it is + what it does.
+- `{{ intermission_07_caption }}` — same shape as page 5.
+
+### Chapter IV — Bedrooms & baths (page 8)
+
+- `{{ chapter4_deck }}` — italic, 15-25 words. Lead with the count ("X bedrooms across Y floors") and the principal-suite signature.
+- `{{ chapter4_para_1 }}` — 3-5 sentences walking the sleeping floor — staircase, landing, second/third/fourth bedrooms in order.
+- 3× `.ed-stat` blocks — big number (.v) with optional unit in `<em>`, then an all-caps slate label (.l). Typical content: bedroom count + character, bathroom count + en-suite split, upper-floor sq ft. Drop the third stat if the property is small.
+- `{{ chapter4_para_2 }}` — 2-3 sentence closer focused on the principal suite (dressing room, en-suite, view).
+- Gallery: 5 cells (1 tall feature). The TALL cell is the principal bedroom — verify by **pixel content**, not filename.
+
+### Page 9 — Image-led gallery ("Rooms in passing")
+
+- `{{ gallery_heading }}` — short h3, italic close.
+- `{{ gallery_deck }}` — single sentence.
+- 5× `figcaption` — SHORT italic — `<em>The [room].</em>` plus an optional trailing clause. Do not repeat captions from Chapter II's strip cells.
+
+### Chapter V — Feature page (page 10) + intermission (page 11)
+
+- `{{ chapter5_eyebrow }}` — match the TOC entry verbatim. If you adapted the chapter title for the property (e.g. "Terrace & outdoor kitchen"), use that here too.
+- `{{ chapter5_heading }}` — two-line italic editorial headline.
+- `{{ chapter5_deck }}` — italic, 18-30 words.
+- `{{ chapter5_para }}` — one body paragraph, 5-7 sentences. **Name each feature exactly** — "outdoor kitchen", "summerhouse", "orangery" are not interchangeable (see structure.md "Distinguishing features clearly"). Verify each photographed feature has its own clause.
+- 4× attribute blocks (k/v). Crisp facts — plot, signature feature, count, material.
+
+### Chapter VI — Garden & ground (page 12) + site plan (page 13)
+
+- `{{ chapter6_heading }}` — two-line italic with `<br>`.
+- 4× bottom panels (`<h4>` + body). Italic h4 label (one word + optional italic close) + 2-3 sentence body. Typical four: rear garden, paddocks/plot, front/approach, ancillary outbuildings. Re-title per property — never "ancillary" as a noun if you can say "garage & sun room".
+- Site plan page: `{{ siteplan_heading }}` is the headline plot fact (acreage if known, "The plot & outlook" otherwise). 3× h4 + body panels: plot, boundary, garden complex / outbuildings.
+
+### Chapter VII — Plan & particulars (page 14)
+
+- `{{ floorplan_lead }}` — italic — "Total internal area · <em>X sq ft</em> · Y m²". Convert one to the other.
+- `{{ floorplan_sub }}` — floor-by-floor breakdown joined by &nbsp;·&nbsp;. **Detached outbuildings are listed separately** — never silently rolled into the principal home's sq ft. See structure.md "Floor area".
+- `{{ particular_N }}` × 9 — each is a single short sentence, with `<strong>` on the named element. Sequence: top-line architectural fact → character feature → kitchen specifics → heating/services → signature internal feature → signature outdoor feature → ancillary buildings → plot → outlook. Drop unused slots; never exceed 9.
+- EPC: exactly one of `{{ epc_current_a..g }}` is ` current` (leading space → CSS class); all others empty string. `{{ epc_caption }}` is 1-2 sentences on the heating system and what the band reflects.
+
+### Chapter VIII — Material information (page 15)
+
+- Every `{{ mi_* }}` row carries the property.json value verbatim. Unknowns are "TBC" — never invent.
+- `{{ mi_part_b_extra_label }}` / `{{ mi_part_b_extra_value }}` is the per-property distinctive Part B slot — "Pool" for a property with one, "Annexe" / "Outdoor" / etc.
+- Drop a row only if the field is genuinely not applicable (e.g. "Coastal Erosion" for an inland home).
+
+### Back page (page 16)
+
+- `{{ backpage_headline }}` — canonical phrasing "Arrange a viewing of <em>{{ property_name }}</em>". Do not paraphrase.
+- `{{ backpage_tagline }}` — single sentence, 25-45 words. Mirrors the cover/opener without duplicating phrases. Close with "Best understood in person." or an equivalent property-specific clincher.
+
+### Landing page (index.html)
+
+The landing-page tokens (`{{ landing_* }}`) source the same brief but render in continuous-scroll form rather than a 16-page folio. Each `{{ landing_*_para_N }}` follows the same length/voice rules as the equivalent brochure paragraph — see placeholders.md → "Category 9 — index.html editorial copy" for the per-section breakdown.
+
+## AI hero image prompt
+
+The cover and back page benefit from a golden-hour version of the front and rear exteriors. The prompt must:
+- Reference the floor plan and aerial image to determine compass orientation
+- Position the setting sun on the correct side of the frame relative to the front elevation
+- Specify warm amber directional light on the facade from the sun side
+- Sky gradient from deep amber at sun to pale peach opposite
+- Keep the house structure sharp and unmodified
+- Professional UK estate agent photography style
+- Output the prompt text for the user to execute in their image tool of choice

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

@@ -0,0 +1,166 @@
+# Images — preview safety, slot verification, optimisation, brand logo
+
+## Image preview safety — never `Read` an image >2000px
+
+**Hard rule: never `Read` an image whose longest edge exceeds 2000px.** The harness loads images into context as multimodal inputs and large ones break the session — the encoding budget overruns and the conversation can drop. Property photographs from DSLRs (`DSC*`, 6000–8000px) and drones (`DJI_*`, 4000–8000px) routinely exceed the limit; AI renders (`ChatGPT-Image-*`, 1024 or 2048px) and screenshots are borderline.
+
+Before any `Read` against an image:
+
+1. **Measure first.** `sips -g pixelWidth -g pixelHeight <file>` (macOS) or `identify -format "%wx%h\n" <file>` (ImageMagick).
+2. If the longest edge ≤ 2000px, reading the original is safe.
+3. If it exceeds 2000px, generate a downscaled preview into `/tmp/`, read the preview, then delete it: `sips -Z 2000 "<src>" --out "/tmp/preview-$(basename "<src>")"`.
+4. Often you don't need pixels at all — filename, byte-size, dimensions, and EXIF answer most layout-decision questions ("is this the kitchen wide shot?", "landscape or portrait?") without a multimodal read.
+
+Generated brochure print snapshots (`cover-print.png`, `pageN-print.png`) are A4 @ 96dpi — 1123×794px in landscape, 794×1123px in portrait. Either way they are safe to read directly.
+
+The constraint is non-negotiable; the failure mode is loss of the entire session, not a graceful error.
+
+## Image content verification — never assign a slot from filename alone
+
+A filename like `Sparrows Farm 22.jpg` or `DSC01525_1727361503...jpg` tells you the index and the timestamp. It does not tell you whether the photo is the inglenook, a vanity bathroom, or the principal bedroom. Slot assignment from filename alone routinely puts a downstairs WC where the inglenook should be, or a family bathroom in the principal-bedroom hero cell. The error is silent — the brochure still renders, but the editorial reads as broken because every chapter title misaligns with its image.
+
+Before referencing any image in the HTML by slot, **verify by reading the actual pixels** (subject to the 2000px safety rule above). Build a labelled montage of all 49 images at thumbnail size and read it once, or read each candidate slot directly. Trust the photo, not the filename.
+
+A useful contact-sheet recipe (49 thumbnails, 4 sheets):
+
+```bash
+mkdir -p /tmp/thumbs
+for n in $(seq 1 49); do
+  src="<property_dir>/images/<Property> $n.jpg"
+  printf -v idx "%02d" "$n"
+  magick "$src" -resize 500x375^ -gravity center -extent 500x375 \
+    -fill yellow -gravity north -pointsize 28 -annotate +0+8 "$idx" \
+    "/tmp/thumbs/${idx}.png"
+done
+montage /tmp/thumbs/*.png -tile 4x4 -geometry 500x375+4+4 \
+  -background '#1a2426' /tmp/sheet1.jpg  # repeat for sheets 2–4
+sips -Z 2000 /tmp/sheet1.jpg --out /tmp/sheet1.jpg
+```
+
+Each sheet is 2000×1500px (safe to read), with each thumb labelled by its source index. Read the sheet, write down the slot map, then assign in the HTML.
+
+Particularly easy mis-assignments to watch for:
+
+| Looks similar at thumb size | Different in reality |
+|---|---|
+| Outdoor kitchen, summerhouse, orangery | Three distinct buildings with three distinct uses |
+| Principal bedroom vs guest bedroom | Principal usually has dressing area + chapel windows |
+| Walk-in wardrobe vs bathroom | Both white-cabinetry; check for plumbing |
+| Family bathroom vs en-suite | En-suite is typically attached to a bedroom shot pair |
+
+## Image requirements — slot map
+
+Rename all photos to `{property-slug}-NN.webp` in an `images/` subfolder. The folio template references images by index, not by descriptive name — index 01 is the cover hero, index 02 is the principal elevation, etc. Slot up to 17 distinct images; missing slots can be replaced by re-using a strong photo from elsewhere, or the spread can be reflowed to omit the cell.
+
+| Index | Page | Role |
+|------|------|------|
+| 01 | Cover | Hero — golden-hour exterior or atmospheric front shot |
+| 02 | Opener (p3) | Principal front elevation |
+| 04 | Contents (p2), House at ease (p4) | Wide open-plan reception or kitchen-dining hero |
+| 05 | Hall, hearth & sun (p5) | Open reception or hero room |
+| 06 | House at ease (p4) — strip | Kitchen / breakfast room |
+| 07 | House at ease (p4) — strip | Kitchen wide or patio doors |
+| 08 | House at ease (p4) — strip | Separate living / sitting room |
+| 09 | Hall, hearth & sun (p5) | Entrance hallway |
+| 10 | Hall, hearth & sun (p5) | Garden room / sun room / second reception |
+| 13 | Bedrooms & baths (p6) | Principal bedroom (tall feature cell) |
+| 14 | Bedrooms & baths (p6) | Shower room or secondary bathroom |
+| 15 | Bedrooms & baths (p6), Annexe (p7) | Bedroom two — and the feature page if the feature is annexe-like |
+| 18 | Bedrooms & baths (p6) | Bedroom three |
+| 19 | Bedrooms & baths (p6) | Family bathroom |
+| 24 | Garden & ground (p8) | Aerial / drone / wide garden hero |
+| 27 | Lifestyle break (p9) | Full-bleed wide-aspect aerial / twilight exterior with single-line italic caption |
+| 25 | Plan & particulars (p10) | Composite floor plan |
+| 26 | Back page | Atmospheric rear or aerial at golden hour |
+
+Indexes 03, 11–12, 16–17, 20–23, 28+ are intentionally unused — leaving gaps means a property with more rooms can use them without renumbering. Adapt the page layout when images are missing — remove the slot, don't leave a placeholder.
+
+## Output folder structure
+
+All final artefacts go in **exactly one** location: `<property_dir>/output/`, where `<property_dir>` is `<brand_dir>/properties/<property_slug>-<id>/`. The folder is the deliverable; no nested `brochure/` wrapper between `<property_dir>/` and `output/`, no flat HTML/PDF at the `<property_dir>/` level.
+
+```
+<brand_dir>/properties/<property_slug>-<id>/output/
+  brochure.html                              # literal filename — NOT <property_slug>-brochure.html
+  <property_slug>-brochure-print.pdf         # print master (300 dpi, ~65–100 MB) — canonical archive artefact
+  <property_slug>-brochure-web.pdf           # web/digital deliverable (192 dpi, ~25–45 MB) — emailed/attached
+  cover-print.png                            # canonical 300 dpi snapshot (used for print PDF + .print-img swap)
+  page2-print.png … page15-print.png         # 14 inner-page snapshots
+  backpage-print.png
+  .snapshots-web/                            # intermediate 192 dpi PNGs for the web-PDF build (deletable after)
+    cover-print.png … backpage-print.png
+  images/
+    <property_slug>-01.webp                  # cover hero (optimised)
+    <property_slug>-02.webp                  # front elevation
+    <property_slug>-NN.webp …                # remaining photos by index
+  web/                                       # self-contained web bundle — see references/build.md
+```
+
+The brochure folder is **self-contained**: every image the HTML references must live under `output/images/`. Never reference `../images/`, `../../floorplans/`, `../../epc/`, or any other path that escapes `output/`. Those upstream `property-extract` directories are inputs to the brochure, not dependencies of the deliverable. A brochure that breaks if its source property assets move is wrong.
+
+If any prior run left a flat brochure or stray PDF at `<property_dir>/` (e.g. from the legacy `brochure/output/` layout), move it to `<property_dir>/_archive/` before writing the canonical layout — never overwrite, never leave it adjacent to `output/`.
+
+## Image renaming and optimisation
+
+Source photos are oversized for the brochure's render slots. Optimise as you copy.
+
+Rename **and re-encode** every photo to `{property-slug}-NN.webp` per the index table above. Use zero-padded two-digit numbers. The brochure HTML must reference `images/{property-slug}-NN.webp` — not the original camera/WhatsApp filenames, not the source path under `<property_dir>/images/`, not a path that escapes `output/`.
+
+### Render-slot sizing
+
+The brochure is a **print-first deliverable**. Source images target the print-master floors below; the digital PDF that gets emailed/embedded is generated by **downsampling the print PDF** (see `build.md → PDF deliverable`), not by re-encoding a smaller WebP. There is therefore no separate "digital-grade source" target — every WebP is encoded once, at print resolution.
+
+| Slot type | Folio positions | Source-px floor | Output long edge | WebP quality |
+|---|---|---|---|---|
+| **Cover hero** | page 01 cover, full-bleed | **2800 px** | 2800–4000 | 90 |
+| **Page banner** | aerial garden hero (p8), lifestyle break (p9), feature image (p7), back-page bg | **2800 px** | 2800–4000 | 90 |
+| **Story photo** | hero spread images (p4 main, p5 main) | **2200 px** | 2200–3200 | 88 |
+| **Gallery thumb** | strip cells (p4), gallery cells (p6), stacked images (p5) | **1600 px** | 1024–1600 | 84 |
+| **Floor plan** | page 10 — line/text content, q80 produces visible mosquito noise on rules | **2000 px** | source size, no resize | 92 |
+| **Map / screenshot** | screenshot with text labels | **2000 px** | source size, no resize | 88 |
+| **EPC chart** | small, already <100KB — copy through unchanged | n/a | as-is | as-is |
+
+**Floor plan exception — keep the source file as-is.** When the seller (or the agency's floor-plan provider) supplies a high-resolution PNG, **use it directly** — do not convert to WebP, do not downscale, do not re-encode. Floor plans are line art with thin strokes and crisp text where any quality loss is visibly worse than the same quality loss on photographic content. The same file (`<slug>-floorplan.png`) is referenced in the canonical brochure HTML, in the index.html landing page, and copied verbatim into `output/web/images/`. Because the new PDF pipeline rasterises whole pages from the rendered HTML (rather than passing the floor plan through a separate compression stage), the floor plan's quality at the PDF stage is determined by the snapshot DPI — 300 dpi for the print master, 192 dpi for the web PDF. A typical 2000 px floor plan slotted into a ~150 mm-wide brochure cell renders crisply at 300 dpi without any per-image processing. The **web bundle** also references the same `.png` (not a `.webp` substitute) — line art doesn't compress well as WebP and the file size is already modest.
+
+The **source-px floor** is the floor on the input photo's longest edge **before optimisation** — see the `Image resolution floor` section in the **a4-print-documents** SKILL for the rationale and full thresholds.
+
+**File-size targets.** The digital PDF derivative ships at ~2–5 MB (because users care about email/embed size). The print master ships at ~5–10 MB. Both are produced from the same source WebPs; the size split happens at the PDF stage.
+
+**Loop CRM caveat.** Many UK estate agents export listing photos at a 1600 px ceiling (Beacons, Muvin, etc.). That sits below the cover, page-banner, and story-photo floors. When the source photos cap below the floor for an assigned slot and no higher-resolution substitute exists, raise this with the user — `DONE_WITH_CONCERNS` per the a4-print-documents rule.
+
+**Do not upscale.** `cwebp -resize 3200 0 <1600px-src>` and `sips -Z 3200` produce a larger file with no extra detail — Lanczos-upscaled blur encoded into a heavier payload.
+
+The print snapshot pipeline renders at 2× DPI (192 dpi → 2247×1588px landscape, 1588×2247px portrait) — see `build.md → Print snapshot capture`. 2× DPI is plenty for the screen-side reviewer to judge quality; on-page print quality is verified from the PDF directly, not from the review snapshots.
+
+### Encoder
+
+Use `cwebp -q <quality> -m 6 -mt -resize <width> 0 <src> -o <dst>` with the print-master widths from the table above (2800 / 2200 / 1600 px) and the matching qualities (90 / 88 / 84). Floor plans and maps use `-q 92` and `-q 88` respectively, no resize. For source images already encoded at the same quality and dimensions (a previously-optimised WebP), re-encoding rarely saves more than 1–2% — verify by comparing output size to source size, and if it grew or stayed flat, copy the source through instead.
+
+### What to optimise
+
+Optimise every image referenced by the HTML, including those that started as `.png` or `.jpeg`. PNG photography is the highest-leverage target. Discard the originals from `output/images/` after the WebP is in place; the source images under `<property_dir>/images/`, `<property_dir>/floorplans/`, and `<property_dir>/epc/` remain as the canonical untouched copies.
+
+After optimisation, sanity-check: open the brochure in a browser, watch for 404s in the console, visually inspect cover and floorplan pages at 1× zoom. A typical 17-photo folio lands in the 3–6 MB range total; anything over 10 MB suggests an over-sized slot.
+
+## Brand logo
+
+The cover masthead, back-page masthead, and TOC credit line use the brand's logo image — never a text-only "BRAND · Property Folio" string. Two variants are required, named by the **colour of the art itself, not the surface where it goes** (matching `brand-design`'s convention):
+
+| Filename | Art colour | Place it on |
+|---|---|---|
+| `<brand>-logo-light.png` | light/white pixels on transparent | Cover masthead, back-page masthead — both sit over dark golden-hour photography |
+| `<brand>-logo-dark.png` | dark/brand-colour pixels on transparent | TOC credit line — sits on warm paper background |
+
+Copy both into `output/images/` alongside the property photos. Reference them in the template at:
+
+- `.cover-mast img` — `<img src="images/{brand}-logo-light.png" alt="{Brand}">`
+- `.back-mast img` — same as cover
+- `.toc-credit img` — `<img src="images/{brand}-logo-dark.png" alt="{Brand}">`
+
+**Sanity-check before referencing.** Open the file in your IDE preview. `<brand>-logo-light.png` should look almost invisible against a white background (it's light-coloured art designed to disappear without a dark surface behind it); if you can read it crisply against white, the file is misnamed and should be `-logo-dark.png` instead. The reverse for `-logo-dark.png`. A run that wires a misnamed file into the template ships a brochure with an invisible masthead.
+
+The masthead lockup is `[logo] | [PROPERTY FOLIO]` — the `<span class="pipe">` is a hairline divider; the `<span class="label">` is the small-caps "Property Folio" tag. Don't drop either; the lockup gives the logo air and signals what the document is.
+
+If only **one** logo variant exists (e.g. a white-on-transparent only), use it everywhere — but on the warm-paper TOC background, either wrap it in a dark-teal pill or skip the TOC instance rather than ship an invisible logo. If **no** logo asset exists, fall back to the original text masthead (`<div class="cover-mast">BRAND · Property Folio</div>`) and remove the `<img>` and `<span>` children.
+
+Logo height: 26px (cover), 28px (back page), 22px (TOC credit). Don't let it exceed 30px — the masthead is a piece of trim, not a billboard.