@rubytech/create-maxy 1.0.879 → 1.0.881

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

@@ -0,0 +1,239 @@
+---
+name: make-brochure
+description: Use when the user gives both an estate agent's website URL (or existing brand-pack directory) and a property listing URL (or existing property-assets directory) in one request, asking for the brochure as an end-to-end deliverable. Trigger phrases include "build a brochure for <listing> using the agent at <agent-url>", "create a brochure for the property at <X> with the brand at <Y>", "end-to-end brochure for <listing>", "do everything from brand to brochure for <listing>", "make me the brochure for <listing> on <agent-site>", or any request that names both a brand source and a property source in the same turn.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - WebFetch
+---
+
+# make-brochure
+
+Single-entry orchestrator for the `brand-design` → `property-extract` → `property-brochure` pipeline. Routes inputs to the right skill in the right order, **skipping any upstream step whose output already exists on disk for the requested source URL**.
+
+This skill is a playbook, not a programmatic dispatcher. It tells you (the agent) the routing rules; you execute each step using the underlying skills' own contracts.
+
+## Outcome contract
+
+The deliverable is identical to `property-brochure`'s outcome — a print-ready `output/brochure.html` plus per-page print PNGs, written into `<property-dir>/brochure/`. The orchestrator's value is in what it does **not** redo:
+
+- If the brand pack for the agent already exists and matches the requested agent URL, `brand-design` is **skipped**.
+- If the property assets for the listing already exist and match the requested listing URL, `property-extract` is **skipped**.
+- `property-brochure` always runs (the brochure itself is the deliverable; re-running it is the point).
+
+A run that re-tokenises a brand pack already on disk for the same URL is a **defect**, not an extra-careful pass. Re-tokenisation burns tokens, can mutate logo PNGs that downstream brochures already reference, and risks divergence between the brand pack and the brochures that consumed it earlier.
+
+## Inputs
+
+Required, in either form for each:
+
+| Input | URL form | Path form |
+|---|---|---|
+| **brand source** | `https://<agent>.co.uk` | `<dir-with-DESIGN.md>` |
+| **property source** | `https://<agent>.co.uk/property/<slug>/<id>/` | `<dir-with-property.json>` |
+| **orientation** | `portrait` or `landscape` (A4) — see **Orientation routing** below |
+
+Optional:
+
+- `force` — one of `brand`, `property`, `all`, or absent. When set, the named upstream step runs even if its output already exists.
+- `output_root` — defaults to the parent of the existing brand pack if one is given, otherwise `./` in the caller's working directory.
+
+If only one input is supplied, **decline and ask for the other** — the orchestrator's reason for being is having both. Route a single-input request to the appropriate sub-skill directly.
+
+## Orientation routing
+
+The brochure ships in either portrait (210×297mm) or landscape (297×210mm) A4. The two are not visually interchangeable — page geometry, render-slot dimensions, print-snapshot pixel sizes, and the PDF call all change with the choice. See `property-brochure`'s **Orientation** section for the full dimensional contract.
+
+Apply this rule **before** running any of the upstream steps:
+
+| Did the user state orientation? | Action |
+|---|---|
+| Yes — explicit `portrait` / `landscape`, or named A4 dimensions in one of the two orders | Use the stated value. Pass it through to `property-brochure`. |
+| No — but a prior brochure exists at `<property_dir>/brochure/output/brochure.html` | Read the existing `@page { size: A4 portrait \| landscape }` rule and confirm with the user in one line ("Keeping existing landscape — OK?"). Default to the inherited value if they don't object. |
+| No — and there's no prior brochure | **Stop and ask.** One-line prompt: "Portrait or landscape A4?" Do not silently default to portrait. |
+
+The reason orientation is hoisted to the orchestrator (not deferred to `property-brochure`) is the same as for missing brand/property sources: the question costs one round-trip; rebuilding a wrong-orientation brochure costs a full pipeline run plus user re-review. Always pay the cheap cost.
+
+When the user answers, pass the orientation through to `property-brochure` as an explicit parameter. Do not re-ask in the downstream skill — the contract is "asked once at the orchestrator level".
+
+## Routing rules
+
+The skill performs four checks in order. Each rule fully specifies its *condition* and its *action*; do not improvise extra branches.
+
+### 1. Resolve the brand identity
+
+If `brand_source` is a URL: derive `brand_slug` as the lowercase domain root with no TLD (e.g. `https://muvin.co.uk` → `muvin`, `https://example-agent.co.uk` → `example-agent`).
+
+If `brand_source` is a path: `brand_slug` = the directory's basename.
+
+Resolve `brand_dir` as:
+- `<output_root>/<brand_slug>/` when `brand_source` was a URL.
+- the supplied path when `brand_source` was a path.
+
+### 2. Decide whether to run `brand-design`
+
+Read `<brand_dir>/DESIGN.md` if it exists. The first paragraph should record the source URL (per the `brand-design` artefact contract).
+
+| `<brand_dir>/DESIGN.md` exists? | Recorded source URL matches request? | `force` value | Action |
+|---|---|---|---|
+| No | — | any | Run `brand-design` against the URL |
+| Yes | Yes | absent | **Skip**. Reuse the existing brand pack. |
+| Yes | Yes | `brand` or `all` | Run `brand-design` (overwrites existing pack) |
+| Yes | No | absent | **Stop and ask the user** — the directory belongs to a different brand. Do not silently overwrite. |
+| Yes | No | `brand` or `all` | Run `brand-design` (overwrites — user opted in) |
+
+If `brand_source` was a path and `DESIGN.md` is missing, treat that as an authoring error — the user pointed at a directory that isn't a brand pack. Stop and ask for the actual brand-pack directory or a URL.
+
+### 3. Resolve the property identity
+
+If `property_source` is a URL: derive `property_slug` from the URL's `/property/<slug>/<id>/` path segment. The folder name is `<property_slug>-<id>` (e.g. `henham-road-debden-green-hamperden-end-cb11-3lz-949931`).
+
+If `property_source` is a path: the folder name is the directory's basename.
+
+Resolve `property_dir` as:
+- `<brand_dir>/properties/<property_slug>-<id>/` when `property_source` was a URL. The property directory always lives **inside** the brand workspace, never as a sibling of it. This is non-negotiable — `property-extract`, `property-brochure`, and the brand pack all assume this nesting.
+- the supplied path when `property_source` was a path. If the supplied path is not under `<brand_dir>/properties/`, stop and ask — silently re-rooting the property would orphan it from its brand pack.
+
+### 4. Decide whether to run `property-extract`
+
+Read `<property_dir>/property.json` if it exists.
+
+| `<property_dir>/property.json` exists? | `source.url` matches request? | `force` value | Action |
+|---|---|---|---|
+| No | — | any | Run `property-extract` against the URL |
+| Yes | Yes | absent | **Skip**. Reuse the existing property assets. |
+| Yes | Yes | `property` or `all` | Run `property-extract` (overwrites existing) |
+| Yes | No | absent | **Stop and ask the user** — the directory holds a different listing. |
+| Yes | No | `property` or `all` | Run `property-extract` (overwrites — user opted in) |
+
+### 5. Always run `property-brochure`
+
+Once steps 2 and 4 have either completed or been skipped, invoke `property-brochure` with both directories as inputs. The brochure HTML and print PNGs land in `<property_dir>/brochure/output/` — that exact path, with the exact filenames listed in the Reference standard. No alternate names, no flat layout under `brochure/`.
+
+If `<property_dir>/brochure/output/brochure.html` already exists from a prior run and the user has **not** asked to re-render, ask before overwriting. Re-rendering the brochure is cheap, but it invalidates whatever review state the user had on the previous version.
+
+## Image preview safety
+
+**Hard rule: never `Read` an image file whose longest edge exceeds 2000px.** The harness loads images into context as multimodal inputs and large ones break the session — the encoding budget overruns, the conversation can drop, and recovery is expensive.
+
+Property photographs almost always exceed this threshold. Concrete examples in the validated reference directory:
+
+| Filename pattern | Typical longest-edge |
+|---|---|
+| `DSC*` (DSLR) | 6000–8000px |
+| `IMG*` (iPhone wide) | 4000–5000px |
+| `DJI_*` (drone) | 4000–8000px |
+| `ChatGPT-Image-*` (AI render) | 1024 or 2048px (borderline — measure) |
+| `Screenshot-*` (desktop capture) | 1200–2880px (borderline — measure) |
+
+### Safe inspection workflow
+
+Before any `Read` against an image:
+
+1. **Measure first.** On macOS: `sips -g pixelWidth -g pixelHeight <file>`. With ImageMagick: `identify -format "%wx%h\n" <file>`. Both are fast and require no decode.
+2. **If the longest edge ≤ 2000px**, reading the original is safe.
+3. **If the longest edge > 2000px**, generate a downscaled preview into `/tmp/`, read the preview, then delete it:
+   ```bash
+   sips -Z 2000 "<src>" --out "/tmp/preview-$(basename "<src>")"
+   # ...Read the preview...
+   rm "/tmp/preview-$(basename "<src>")"
+   ```
+   Or with ImageMagick: `magick "<src>" -resize '2000x2000>' "/tmp/preview-..."`.
+4. **Often you don't need the pixels at all** — filename, byte-size, dimensions, and EXIF tags answer most QA questions ("is this the kitchen wide shot?", "is this in landscape?") without a multimodal read.
+
+The constraint applies to **every** image-reading touchpoint in the pipeline: shortlisting cover candidates, picking the kitchen hero, sanity-checking floorplans, verifying a downloaded asset, eyeballing AI-render quality. Treat the rule as non-negotiable; the failure mode is loss of the entire session, not a graceful error.
+
+Generated brochure print snapshots (`cover-print.png`, `pageN-print.png`) are produced at A4 @ 96dpi which is **794×1123px** — those are safe to read directly.
+
+## Process — high level
+
+1. **Parse and validate inputs.** Confirm both sources are present; pick form (URL or path) per source; bail early with a clear question if either is missing or ambiguous. Apply the **Orientation routing** table — if orientation is not stated and not inheritable, stop and ask before doing any other work.
+2. **Apply Routing rule 1–4.** For each upstream skill, determine `run` / `skip` / `ask` based on the table; record the decision in a one-line log so the user can see what was reused.
+3. **Run the upstream skills in sequence**, brand first then property. Each runs under its own SKILL.md contract — do not adapt or shortcut their completion criteria. If either reports `DONE_WITH_CONCERNS` or `STATUS: BLOCKED`, surface that to the user and stop before invoking `property-brochure`.
+4. **Run `property-brochure`** pointing at both directories. Confirm the brochure landed in `<property_dir>/brochure/output/` and that all per-page print PNGs are present.
+5. **Report.** Tell the user, in order: which steps ran fresh, which were reused, the final brochure path, and any `DONE_WITH_CONCERNS` items from the upstream steps.
+
+The orchestrator does not bundle the upstream skills' outputs — each leaves its artefacts where its own SKILL.md says to. The brochure is the only thing this skill is responsible for delivering.
+
+## Reference standard
+
+After a complete run, the on-disk layout is **exactly** this — no deeper nesting, no extra wrappers, no sibling `properties/`:
+
+```
+<output_root>/
+  <brand_slug>/                           # = brand workspace = <brand_dir>
+    DESIGN.md                             # produced by brand-design
+    description.md                        # produced by brand-design
+    <brand_slug>-logo-light.png           # produced by brand-design
+    <brand_slug>-logo-dark.png            # produced by brand-design
+    properties/                           # nested INSIDE the brand workspace
+      <property_slug>-<id>/               # = <property_dir>
+        property.json                     # produced by property-extract
+        description.md                    # produced by property-extract
+        images/                           # produced by property-extract — original photo filenames preserved
+        floorplans/                       # produced by property-extract
+        epc/                              # produced by property-extract (may be empty)
+        brochure/                         # owned by property-brochure
+          output/                         # the only child of brochure/ — final deliverables; self-contained
+            brochure.html
+            cover-print.png
+            page2-print.png … page9-print.png
+            backpage-print.png
+            images/                       # renamed + per-slot-optimised brochure photos: <property_slug>-NN.webp
+            <brand_slug>-light.png        # brand logo for dark surfaces
+            <brand_slug>-dark.png         # brand logo for light surfaces (when used)
+            <property_slug>-logo-light.svg  # property line-drawing logo
+            <property_slug>-logo-dark.svg
+```
+
+The `output/` folder is a portable deliverable: every image referenced by `brochure.html` resolves to a file under `output/images/`. References that escape `output/` (`../images/`, `../../floorplans/`, `../../epc/`) are a defect — the brochure must not depend on the sibling property-extract folders staying in place.
+
+Reference instances that already conform:
+- `/Users/neo/estate-agents/muvin/` (brand_slug = `muvin`)
+- `/Users/neo/estate-agents/beacons/` (brand_slug = `beacons`)
+
+Determinism rules — a run that violates any of these is wrong, even if the brochure renders:
+- `properties/` is **inside** `<brand_dir>/`, never a sibling.
+- `brochure/` contains exactly one child: `output/`. No `<name>-brochure-brand.html`, no flat HTML/PDF at the `brochure/` level.
+- The brochure's HTML lives at `<property_dir>/brochure/output/brochure.html`. The filename is literal `brochure.html` — not `<property_slug>-brochure.html`.
+- Print snapshots are named `cover-print.png`, `page2-print.png` … `page9-print.png`, `backpage-print.png` — never `cover-print-brand.png` or other variants.
+- Anything that would otherwise pollute `brochure/` (legacy versions, scratch HTML, branding experiments) is moved out of `brochure/` entirely. `_archive/` at the property root is acceptable; extra files inside `brochure/` are not.
+
+## Common mistakes
+
+| Mistake | Why it's wrong |
+|---|---|
+| Running `brand-design` when `DESIGN.md` already exists for the same URL | Wastes tokens and risks regenerating logo PNGs that earlier brochures point at. |
+| Treating "directory exists" as enough for skip-check | The directory may exist with a different brand's content. The check is **content match** (recorded source URL), not filesystem presence. |
+| Silently overwriting a brand pack whose recorded URL differs from the request | The user almost certainly meant a sibling directory or a typo. Asking takes one turn; an overwrite costs them work. |
+| Reading a 6000px DSLR photo with `Read` to "have a look" | Breaks the session. Always measure first; downscale if needed. |
+| Skipping `property-brochure` because the brochure already exists from a prior run | The user asked for the end-to-end deliverable. If they want to keep the existing brochure, they will say so — confirm before overwriting, but don't unilaterally skip. |
+| Bundling `brand-design`'s outputs into the property directory | The artefacts are separable on purpose. The brand pack is reused across listings; collapsing it into a single property's folder defeats reuse. |
+| Inferring `force` from the user's tone ("redo it properly") | `force` is an explicit lever. If the user's intent is unclear, ask — don't assume `force=all`. |
+| Silently defaulting to portrait when the user did not specify orientation | The brochure's geometry, render slots, and PDF call all change with orientation. A wrong choice means a full rebuild. One-line ask is cheaper than a wasted run. |
+| Asking for orientation again in `property-brochure` after the orchestrator already collected it | The contract is "asked once". Re-asking annoys the user and risks a divergent answer mid-pipeline. Pass the value through. |
+
+## Completion criteria
+
+Report `DONE` only after:
+
+- Both upstream artefact contracts are satisfied at their expected paths (`<brand_dir>/DESIGN.md`, `<property_dir>/property.json`).
+- Orientation was explicit before any layout work began — either stated by the user, inherited from a prior brochure with confirmation, or asked-and-answered.
+- The brochure HTML exists at `<property_dir>/brochure/output/brochure.html` and its `@page { size: A4 portrait | landscape }` matches the chosen orientation.
+- The PDF deliverable exists alongside `brochure.html` (typically `<property_slug>-brochure.pdf`) and was emitted with the matching `landscape: true` flag (or omitted for portrait).
+- All per-page print snapshots referenced by the HTML's print CSS exist at expected names and at the orientation-correct pixel dimensions (794×1123 portrait / 1123×794 landscape).
+- The user-facing report names which steps ran and which were reused, **and the chosen orientation**.
+- No image was read in violation of the 2000px rule (verifiable: every image read should have been preceded by a `sips`/`identify` measurement, and any over-threshold image was previewed via `/tmp/`).
+
+If any condition is unmet, report `DONE_WITH_CONCERNS` and list the gap.
+
+## When NOT to use this skill
+
+- The user supplies only a brand URL (no property) → route directly to `brand-design`.
+- The user supplies only a property URL (no brand context) → ask which agent's brand to use; if they say "use the existing one in `<dir>`", route to `property-extract` and then `property-brochure` with that brand directory.
+- The user supplies pre-staged photos and asks for the brochure → route directly to `property-brochure`. There's nothing to orchestrate.
+- The user wants to refresh a single piece (e.g. just regenerate the dark logo, just re-download images) → call the underlying skill directly with whatever scope they specified. The orchestrator is for end-to-end runs, not à la carte fixes.

package/payload/premium-plugins/real-agency/plugins/brochures/skills/property-brochure/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: property-brochure
+description: Create A4 property brochures (landscape default, portrait optional) from raw photos, transcripts, and floorplans. Produces print-ready HTML and a recompressed PDF deliverable. The skill ships an editorial "folio" template by default; if the property has a DESIGN doc that specifies its own visual scheme, follow that instead. Use when asked to create an estate agent brochure, property marketing material, or property listing document.
+---
+
+# Property Brochure
+
+Produce an A4 property brochure from raw assets. The default deliverable is an 11-page editorial **folio** in landscape A4 — magazine-style chapters with Cormorant Garamond display type, Poppins body, drop caps, pull quotes, and asymmetric photo grids. The brochure renders in-browser for live editing and exports to pixel-perfect PDF via page-level image snapshots and a Ghostscript recompression pass.
+
+## Reference template
+
+See `references/template.html` — the canonical HTML template for the editorial folio (landscape by default; see the **Orientation** section for the portrait adaptation). Read it, copy to `output/brochure.html` in the property's project directory, and populate all `<!-- REPLACE: -->` placeholders with real content. The CSS is final; do not modify it except for the orientation swap documented under **Orientation**.
+
+The folio comprises eleven pages: cover, contents, opening chapter, three editorial room spreads (house at ease / hall, hearth & sun / bedrooms & baths), a flexible feature page (annexe / studio / outbuilding — repurpose if the property has none), garden & ground, plan & particulars, material information, and a back page. Every chapter carries a Roman-numeral eyebrow, an italic-emphasised headline, an editorial deck, and folio numbers in the footer.
+
+## Default visual scheme — and when to override it
+
+If the property does not come with a DESIGN doc, **default to the scheme baked into `references/template.html`**:
+
+- **Type**: Cormorant Garamond (display, italics for emphasis) + Poppins (body)
+- **Palette**: warm paper (`#f6f1ea`), deep teal (`#0f4f5a`), gold (`#b8945c`), ink (`#1a2426`)
+- **Voice**: editorial, considered, country-house tone — chapters numbered in Roman, dropcaps, pull quotes
+- **Layout**: A4 landscape, 11 pages, asymmetric photo grids, full-bleed feature spreads, ornamental rules between sections
+
+If a DESIGN doc *is* provided, **follow it**. Do not impose the default scheme over a brand's stated tokens, fonts, or layout system. The DESIGN doc's font stack, palette, and tone-of-voice take precedence over everything in this section. Adapt the structure (still 11 pages, still landscape by default) but re-skin: swap fonts at the `--display` / `--body` custom properties, replace palette tokens, adjust the editorial voice to match the brand's register.
+
+## Required inputs
+
+- **Property photographs** — minimum 16, ideally 25+. See image requirements below.
+- **Property name and address**
+- **Floor plan image** — used for room dimensions, total area, and compass orientation
+- **EPC rating** — set the `current` class on the correct A-G band on page 9
+- **Property walkthrough transcript or written description** — source for room descriptions, features, renovation history
+- **Agent details** — read from the brand pack at `<brand_dir>/description.md` (registered office, phone, email, agency name). Logos: `<brand>-light.png` (logo for warm/light backgrounds) and `<brand>-dark.png` (logo for dark/photo backgrounds) as documented under **Brand logo** below. The cover and back page use the dark-background variant; the TOC credit line uses the light-background variant.
+- **Page orientation** — `landscape` (297×210mm, default) or `portrait` (210×297mm). See the **Orientation** section.
+- **DESIGN doc** (optional) — if present, overrides the default visual scheme.
+
+## 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 in this SKILL 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>/brochure/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 the **Image renaming and optimisation** section is unchanged — it provides 2× retina headroom for full-bleed images at either orientation.
+
+### Reference template
+
+`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.
+
+## Image preview safety
+
+**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 requirements
+
+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 |
+| 25 | Plan & particulars (p9) | Composite floor plan |
+| 26 | Back page | Atmospheric rear or aerial at golden hour |
+
+Indexes 03, 11–12, 16–17, 20–23, 27+ 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>/brochure/output/`, where `<property_dir>` is `<brand_dir>/properties/<property_slug>-<id>/`. The folder is the deliverable; no other path under `brochure/` is acceptable.
+
+```
+<brand_dir>/properties/<property_slug>-<id>/brochure/output/
+  brochure.html                    # literal filename — NOT <property_slug>-brochure.html
+  cover-print.png                  # cover snapshot
+  page2-print.png … page10-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
+```
+
+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 under `brochure/`, 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
+
+| Slot type | Folio positions | Max long edge | WebP quality |
+|---|---|---|---|
+| **Cover hero** | page 01 cover, full-bleed | 1600px | 85 |
+| **Page banner** | aerial garden hero (p8), feature image (p7), back-page bg | 1600px | 82 |
+| **Story photo** | hero spread images (p4 main, p5 main) | 1280px | 82 |
+| **Gallery thumb** | strip cells (p4), gallery cells (p6), stacked images (p5) | 1024px | 80 |
+| **Floor plan** | page 9 — line/text content, q80 produces visible mosquito noise on rules | 1600px | 90 |
+| **Map / screenshot** | screenshot with text labels | 1600px | 85 |
+| **EPC chart** | small, already <100KB — copy through unchanged | as-is | as-is |
+
+The numbers are calibrated against the print snapshot pipeline (A4 @ 96dpi → 1123×794px landscape or 794×1123px portrait) at 2× retina headroom. Going beyond 1600px on the long edge buys nothing the print snapshot can use; going below 1024px on a gallery thumb produces softening that's visible at print scale. The slot-type table is orientation-agnostic; what changes is *which slots a given page uses*, not the long-edge ceilings.
+
+### Encoder
+
+Use `cwebp -q <quality> -m 6 -mt -resize <width> 0 <src> -o <dst>`. 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:
+
+| Variant | Use on | Filename pattern |
+|---|---|---|
+| **Light/white logo** (white pixels on transparent) | Cover masthead, back-page masthead — both sit over dark golden-hour photography | `<brand>-light.png` or `<brand>-on-dark.png` |
+| **Dark/coloured logo** (brand colour on transparent) | TOC credit line — sits on warm paper background | `<brand>-dark.png` or `<brand>-on-light.png` |
+
+Copy both into `output/images/` alongside the property photos. Reference them in the template at:
+
+- `.cover-mast img` — `<img src="images/{brand}-light.png" alt="{Brand}">`
+- `.back-mast img` — same as cover
+- `.toc-credit img` — `<img src="images/{brand}-dark.png" alt="{Brand}">`
+
+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.
+
+## 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
+
+## 11-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.
+
+| Page | Class | Chapter | Key content |
+|------|-------|---------|-------------|
+| 1 | `.cover` | Cover | Full-bleed hero, masthead, edition line, location eyebrow, property title, tagline, guide price, folio number |
+| 2 | `.page` | Contents (TOC) | Editorial image with caption, eight-chapter table of contents (Roman i–viii), credit line |
+| 3 | `.page` | I · Of place & pedigree | Opener — property name, county/postcode, 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` | III · Hall, hearth & sun | Split header, large left image, two stacked right images |
+| 6 | `.page` | IV · Bedrooms & baths | Text column with 3-stat row, 5-cell gallery (one tall feature) |
+| 7 | `.page` | V · Feature page | Full-bleed feature image (annexe/studio/outbuilding), narrow text panel with attribute grid |
+| 8 | `.page` | VI · Garden & ground | Full-bleed aerial with overlaid title, four short-text panels |
+| 9 | `.page` | VII · Plan & particulars | Wide chapter header, large floor plan + meta, 8-9 item particulars list, EPC bar chart |
+| 10 | `.page` | VIII · Material information | Three-section disclosure grid (Parts A/B/C), boilerplate footer |
+| 11 | `.backpage` | Back page | Atmospheric background, masthead, CTA headline, two-cell contact grid (agent + office), folio footer, disclaimer |
+
+## 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
+
+## Floorplan sizing (page 9)
+
+Floorplans are the most information-dense images in the brochure. The plan area on page 9 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.
+
+## Live editing workflow
+
+1. Copy template to property directory, populate with content
+2. Stage `output/images/` per the **Image renaming and optimisation** section
+3. Serve locally: `python3 -m http.server <port>` from the project root
+4. Navigate Playwright to the brochure URL
+5. Present to user in browser for review
+6. User requests changes — iterate on content, image sizing, page balance
+7. Verify every page fits A4: measure `scrollHeight` for all `.page` elements
+8. Verify no 404s in the browser console
+9. Repeat 5–8 until user approves the final copy
+10. **Only after user approval**: capture all print snapshots
+11. User downloads PDF via the Download button
+
+Do not capture snapshots during the editing cycle — they are expensive and invalidated by every change.
+
+## Print snapshot capture
+
+Every page is pre-captured as a PNG that swaps in during print. **Run this only once, after the user approves the final version.**
+
+Capture all pages in one pass via Playwright `browser_run_code`:
+
+```javascript
+async (page) => {
+  await page.evaluate(() => {
+    document.querySelector('.download-bar').style.display = 'none';
+    document.body.style.overflow = 'hidden';
+  });
+  const base = '/path/to/property/';
+  const cover = page.locator('.cover');
+  await cover.scrollIntoViewIfNeeded();
+  await cover.screenshot({ path: base + 'cover-print.png', type: 'png' });
+  // .page selector includes .cover and .backpage in this template; filter to the middle nine.
+  const pages = page.locator('.page:not(.cover):not(.backpage)');
+  for (let i = 0; i < await pages.count(); i++) {
+    await pages.nth(i).scrollIntoViewIfNeeded();
+    await pages.nth(i).screenshot({ path: base + `page${i+2}-print.png`, type: 'png' });
+  }
+  const back = page.locator('.backpage');
+  await back.scrollIntoViewIfNeeded();
+  await back.screenshot({ path: base + 'backpage-print.png', type: 'png' });
+  await page.evaluate(() => {
+    document.querySelector('.download-bar').style.display = '';
+    document.body.style.overflow = '';
+  });
+}
+```
+
+**Print CSS**: `@page { size: A4 landscape; margin: 0 }` (or `portrait` if overridden). The print stylesheet has two paths:
+
+1. **Snapshot path (primary)** — when a `.print-img` has a non-empty `src`, the rule `.page:has(.print-img[src]:not([src=""])) > *:not(.print-img) { display: none }` hides everything else and the snapshot fills the page at `z-index: 9999`. Folios are baked into the snapshot.
+2. **Live-DOM fallback** — if a snapshot is missing or empty, the page prints the live DOM. The folio is forced visible by overriding `.folio` with `z-index: 100`, `bottom: 6mm`, and **dropping `backdrop-filter`** (Chromium's PDF engine strips it, making the pill effectively invisible against dark imagery). The pill background falls back to a solid `rgba(252, 251, 248, 0.95)` for light pages and `rgba(6, 68, 68, 0.78)` for `.folio-dark` pages. The same `z-index` lift is applied to `.back-foot`.
+
+**Why both paths matter**: users sometimes hit Cmd+P before snapshots are captured, or the snapshot pipeline fails silently. The fallback guarantees the folio still prints. The `.print-img` elements use `opacity: 0; width: 1px; height: 1px` on screen (not `display: none` — that prevents image loading in some browsers).
+
+## PDF deliverable
+
+The brochure is shipped as both `brochure.html` and `<property_slug>-brochure.pdf`. The PDF lives alongside `brochure.html` in `<property_dir>/brochure/output/`.
+
+### Two-stage generation
+
+Browser print-to-PDF is the source of truth, but Chromium re-rasterises CSS background-images at print DPI, producing 30–70 MB outputs. A second pass through Ghostscript at 300dpi recompresses without visible loss.
+
+1. **Stage 1 — Chromium print-to-PDF** via Playwright `browser_run_code`:
+   - Wait for `networkidle` so all images have loaded
+   - Hide `.download-bar`
+   - Call `page.emulateMedia({ media: 'print' })`
+   - `page.pdf({ path, format: 'A4', landscape: true, printBackground: true, preferCSSPageSize: true, margin: 0 })` for the default landscape folio. Drop `landscape: true` if the brochure has been swapped to portrait.
+2. **Stage 2 — Ghostscript recompression**:
+   ```
+   gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.5 -dPDFSETTINGS=/printer \
+      -dNOPAUSE -dQUIET -dBATCH -dDetectDuplicateImages=true \
+      -sOutputFile=<final>.pdf <stage1>.pdf
+   ```
+3. Discard the stage-1 PDF.
+
+A typical folio ships at 3–6 MB after recompression. Anything over 10 MB suggests an over-sized image source slipped through optimisation.
+
+### When to (re)generate
+
+Generate the PDF after every approved layout change. Do not let the PDF drift behind the HTML.
+
+## Scope
+
+**Included**: HTML brochure, image organisation **and per-slot optimisation**, AI hero prompt, all print snapshots, **PDF deliverable** (Chromium print-to-PDF + Ghostscript recompression), Material Information compliance, EPC chart, disclaimers.
+
+**Not included**: Professional photography, actual EPC assessment, legal verification of Material Information values, agent CRM integration, print shop preparation (CMYK, bleed marks), executing the AI hero image prompt.
+
+**Depends on**: Playwright MCP for screenshots and PDF emit, local HTTP server for browser preview, A4 print skill for print constraints, `cwebp` (libwebp) for image encoding, `gs` (Ghostscript) for PDF recompression.