@rubytech/create-maxy-code 0.1.24 → 0.1.27

package/payload/platform/plugins/brochures/skills/make-brochure/references/seller-brief-template.md

@@ -0,0 +1,115 @@
+# Seller's Brief — <Property Name>
+
+The answers below are interview answers from the seller. They source the brochure's editorial voice — chapter decks, body paragraphs, captions, taglines, and buyer-avatar tone. The brochure agent reads this file before generating any copy and uses it to anchor every section.
+
+This template ships with the `make-brochure` skill at `references/seller-brief-template.md`. To use:
+
+1. Copy this file to `<property_dir>/seller-brief.md`.
+2. Fill in every answer. Empty answers are not acceptable; the orchestrator will refuse to invoke `property-brochure` until each question has at least a few sentences.
+3. Save and re-run the orchestrator (or `property-brochure` directly).
+
+Answers are not quoted verbatim in the brochure — the agent distils them into the editorial register. If a phrase is so apt the seller wants it preserved word-for-word, mark it `[VERBATIM]` at the start of the answer.
+
+---
+
+## Story & Motivation
+
+**1. Why did you first buy this home when you bought it?**
+
+<!-- Answer here. The home's first chapter starts with what drew the current owner. -->
+
+**2. How long have you owned this property, and what made you decide it was the right time to sell?**
+
+<!-- Answer here. -->
+
+**3. What do you love most about this property?**
+
+<!-- Answer here. -->
+
+**4. What will you miss most when it's sold?**
+
+<!-- Answer here. -->
+
+---
+
+## Layout & Lifestyle
+
+**5. If a buyer walked through the door for the first time, what feeling do you want them to get?**
+
+<!-- Answer here. This sets the *deck* of the opening chapter — the single italic sentence at the top of page 3. -->
+
+**6. Which room or feature is your personal favourite, and why?**
+
+<!-- Answer here. This room gets the strongest photographic treatment in its chapter — the hero cell, not a strip-cell. -->
+
+**7. What kind of lifestyle does this home support best (family, professional couple, entertainer, quiet retreat, etc.)?**
+
+<!-- Answer here. This shapes the buyer-avatar tone of every body paragraph. -->
+
+---
+
+## Improvements & Upgrades
+
+**8. Have you done any renovations, upgrades, or improvements since moving in?**
+
+<!-- Answer here. -->
+
+**9. If so, what did you change and why? (Style, functionality, energy efficiency, etc.)**
+
+<!-- Answer here. These become the highlighted items in the particulars list on the Plan & Particulars page. -->
+
+**10. Are there any design details or features people often notice or comment on?**
+
+<!-- Answer here. These become the strip-cell captions and attr-grid features. -->
+
+---
+
+## Local Area & Community
+
+**11. What do you love about the local area?**
+
+<!-- Answer here. -->
+
+**12. Are there any hidden gems — cafés, parks, walks, schools, neighbours — that stand out?**
+
+<!-- Answer here. -->
+
+**13. What's the commute or transport like for work or weekends away?**
+
+<!-- Answer here. -->
+
+**14. How would you describe the community vibe to someone who's never been here?**
+
+<!-- Answer here. -->
+
+---
+
+## Practical & Buyer Avatar
+
+**15. Who do you think this home would suit best — and why?**
+
+<!-- Answer here. -->
+
+**16. What type of buyer do you hope moves in next?**
+
+<!-- Answer here. -->
+
+**17. Is there anything about the home you feel needs context or explanation before viewings? (e.g., heating, electrics, layout quirks)**
+
+<!-- Answer here. Items raised here are flagged as "context" in the Material Information page or footnoted in the Particulars list — they are not omitted from the brochure. -->
+
+**18. What do you think buyers might overlook that deserves more attention?**
+
+<!-- Answer here. These are the "moments" the brochure deliberately surfaces — sometimes promoting a slot from a strip-cell to a hero. -->
+
+**19. If you could describe your home in three words, what would they be?**
+
+<!-- Answer here. These three words anchor the cover sub-line OR the opening chapter deck. The brochure uses the seller's words; it does not rephrase them. -->
+
+**20. Is there a particular feeling, story, or phrase you'd love buyers to connect with when they see your home online?**
+
+<!-- Answer here. This phrase becomes the cover tagline, the opener pull-quote, OR the back-page tagline — wherever it best fits. The brochure carries the seller's exact phrase if marked [VERBATIM]. -->
+
+---
+
+*All answers above are confidential to the brochure assembly process. Sensitive personal information will not be reproduced verbatim in the published brochure unless explicitly marked [VERBATIM].*

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

@@ -0,0 +1,119 @@
+---
+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 a 16-page super-premium editorial **folio** in landscape A4. The brochure renders in-browser for live editing and exports to two image-only PDFs (web and print master) plus a self-contained web bundle including a companion landing page.
+
+## Output location
+
+By default the brochure is written to the **caller's current working directory**. The skill creates `./output/brochure.html`, `./output/web/index.html`, the print PNGs, and the two PDFs underneath `pwd` — no inference, no nesting under a brand workspace.
+
+If you want the output elsewhere, pass `output_dir` explicitly (an absolute path or a relative path resolved against CWD). Common overrides:
+
+| Scenario | `output_dir` |
+|---|---|
+| No override (the default) | `./output/` under the caller's CWD |
+| Brochure should live next to an existing brand pack | `<brand_dir>/properties/<property_slug>-<id>/output/` |
+| Brochure should land somewhere specific (a delivery folder, a customer's repo) | the supplied absolute path |
+
+Do not silently nest the output under a brand workspace just because one is present. The `make-brochure` orchestrator may pass `output_dir` to align with its own routing; this skill on its own runs in the caller's CWD unless told otherwise.
+
+## Step 1 — copy the canonical templates (do this first)
+
+`references/template.html` and `references/index.html` are the **only** acceptable starting points. They are placeholder-only — every property value is a `{{ token }}`. Copy them before doing anything else. **Do not write brochure HTML or page HTML from scratch. Do not start from a sibling property's output. Do not improvise structure from prose.**
+
+```bash
+mkdir -p <output_dir>/web
+cp ~/.claude/plugins/real-estate-brochure/skills/property-brochure/references/template.html <output_dir>/brochure.html
+cp ~/.claude/plugins/real-estate-brochure/skills/property-brochure/references/index.html      <output_dir>/web/index.html
+```
+
+`<output_dir>` is whatever the **Output location** section above resolves to — typically `./output/` in the caller's CWD.
+
+If the canonical template looks wrong for the brand, **patch the template** (open a discussion with the user about what to change). Don't substitute a different starting point for one run — that bakes drift into every brochure.
+
+Full register/structure rules: [references/registers.md](references/registers.md). Forbidden starting points are listed there.
+
+## Step 2 — verify the copy worked
+
+Both files must contain canonical sentinels (proves they came from `references/`, not hand-written or hand-edited):
+
+```bash
+grep -q '{{ property_name }}'  <output_dir>/brochure.html  || echo "FAIL: brochure not from template"
+grep -q 'hero-stage'           <output_dir>/web/index.html  || echo "FAIL: index.html not from references"
+```
+
+Both greps must succeed before populating content. If either fails, recopy.
+
+## Step 3 — choose the visual register
+
+| Register | What you change |
+|---|---|
+| **Premium** (template scheme retained) | Keep all super-premium tokens (palette, type, layout) verbatim. Swap **only** the agent's logo and contact details. Do not apply the brand's palette or type tokens. |
+| **Branded** (DESIGN.md re-skin) | Swap font names at `--serif` / `--body-serif` / `--sans`; replace palette tokens with the DESIGN doc's values; substitute logo PNGs. Sixteen-page structure stays. |
+
+Decision order:
+1. User said **"premium" / "super-premium"** → Premium (regardless of DESIGN.md).
+2. **DESIGN.md provided** and user did *not* say premium → Branded.
+3. Neither → Premium (template defaults).
+
+Detail and forbidden patterns: [references/registers.md](references/registers.md).
+
+## Step 4 — populate, render, deliver
+
+Read the seller brief once before writing any copy. Then walk the `{{ placeholder }}` tokens in both files top-to-bottom, substituting from the brief and `property.json`. The complete substitution contract — every token, its source field, its expected format and voice — lives in [references/placeholders.md](references/placeholders.md). Each token also has an inline `<!-- REPLACE: ... -->` comment in the template giving the short version.
+
+| Concern | Reference |
+|---|---|
+| **Placeholders — the substitution contract** (every `{{ token }}`, what fills it, what format) | [references/placeholders.md](references/placeholders.md) |
+| Seller brief — per-question → brochure mapping, [VERBATIM] contract | [references/seller-brief.md](references/seller-brief.md) |
+| Image preview safety, slot verification, requirements, optimisation, brand logo | [references/images.md](references/images.md) |
+| Editorial copy register, em-dash policy, "home" vs "house", text-on-images, typography, stats rows, AI hero prompt, **per-section composition guide** | [references/copy.md](references/copy.md) |
+| Orientation, 16-page layout, cover, floorplan, distinguishing features, Material Information, QR codes, location map | [references/structure.md](references/structure.md) |
+| Live editing, snapshot capture, PDF deliverable, web bundle | [references/build.md](references/build.md) |
+| `index.html` landing page — sections, hero rotator, mobile/drawer | [references/index-landing.md](references/index-landing.md) |
+
+### Substitution completion gate
+
+A brochure with any `{{ x }}` still in the rendered HTML is **shipped broken**. Before any snapshot capture or PDF build, run:
+
+```bash
+unsubstituted=$(grep -c '{{' "$output_dir/brochure.html" "$output_dir/web/index.html" 2>/dev/null | awk -F: '{s+=$2} END {print s}')
+[ "$unsubstituted" -eq 0 ] || { echo "DEFECT: $unsubstituted unsubstituted {{ tokens }} remain"; exit 1; }
+```
+
+`grep '{{ ' brochure.html` is the canonical bug-detector — any match is a defect.
+
+## Required inputs
+
+- **Property photographs** — minimum 16, ideally 25+
+- **Property name and address** (see `property-extract → Property name vs address`)
+- **Floor plan image**, **EPC rating**
+- **Property walkthrough transcript or written description**
+- **Seller brief** at `<property_dir>/seller-brief.md` — non-empty answers to all 20 questions in `make-brochure/references/seller-brief-template.md`. Stop and ask if missing; do not synthesise from the listing description.
+- **Agent details** — from `property.json -> agent` (no built-in default). Logos follow the colour-of-the-art naming convention: `<brand>-logo-light.png` (for dark surfaces — cover/back) and `<brand>-logo-dark.png` (for light surfaces — TOC).
+- **Page orientation** — `landscape` (default) or `portrait`
+- **DESIGN doc** (optional) — controls register choice; never replaces the template structure
+
+## Hard rules (load-bearing — do not violate)
+
+- **Never `Read` an image whose longest edge exceeds 2000px** — it can drop the session. Measure with `sips -g pixelWidth -g pixelHeight <file>` first.
+- **Never assign an image to a slot from filename alone.** Verify by pixel content via a contact-sheet montage.
+- **Never synthesise a location map** from postcode, OSM call, or AI artwork. Extract the agent's screenshot or omit. ([references/structure.md → Location map](references/structure.md))
+- **Page count must be even** (16 default; 12 if the property is too small). 14 is forbidden.
+- **Image-only PDFs** — no fonts embedded, no Ghostscript anywhere in the chain.
+- **Self-contained `output/`** — never reference `../` paths. Every asset the HTML uses must live under `output/images/`.
+- **Web bundle must include `index.html`** — a bundle without it is incomplete.
+- **Suppress screen-only chrome before snapshotting** — the template's `.download-bar` is hidden under `@media print` but Playwright's `element.screenshot()` captures the screen render, where the bar IS visible. The render script in `build.md` injects a style tag (`.download-bar { display: none !important; }`) before capture. Any custom render script must do the same.
+- **No `{{ token }}` may remain in rendered output** — `grep '{{' output/brochure.html` must return zero matches before PDFs are built.
+
+## Scope
+
+**Included**: HTML brochure + companion landing page, image organisation and per-slot optimisation, AI hero prompt, all print snapshots at 300 dpi, two image-only PDF deliverables (print master + web), a self-contained web bundle (`output/web/` + `<slug>-web.zip`), 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, selectable / searchable text in the PDFs (deliberate trade-off; see `a4-print-documents → Why image-only`).
+
+**Depends on**: Playwright (Node `playwright` package), local HTTP server for browser preview, `a4-print-documents` skill, `cwebp` (libwebp), `img2pdf`, `qpdf`, ImageMagick (`magick`).

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

@@ -0,0 +1,270 @@
+# Build pipeline — live editing, snapshots, PDFs, web bundle
+
+## Live editing workflow
+
+1. Copy template to property directory, populate with content
+2. Stage `output/images/` per `images.md → Image renaming and optimisation`
+3. Serve locally: `python3 -m http.server <port>` from the project root
+4. Navigate Playwright to the brochure URL
+5. Present to user in browser for review
+6. User requests changes — iterate on content, image sizing, page balance
+7. Verify every page fits A4: measure `scrollHeight` for all `.page` elements
+8. Verify no 404s in the browser console
+9. Repeat 5–8 until user approves the final copy
+10. **Only after user approval**: render snapshots (two passes — 300 dpi to `output/`, 192 dpi to `output/.snapshots-web/`) per **Print snapshot capture** below
+11. Build both PDFs (img2pdf + qpdf) per **PDF deliverable** below
+12. Build the web bundle (96 dpi JPGs + bundled web PDF + zip) per **Web bundle** below
+13. User downloads the web PDF via brochure.html's Download button or receives the print master separately for press/print runs
+
+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. The PNGs are used both as the print-stylesheet replacement (so the live brochure prints to a clean PDF when a user hits Cmd+P) **and** as the source images bound into the two PDF deliverables. **Run this only once, after the user approves the final version.**
+
+**Two render passes, two DPI tiers:**
+
+| Snapshot set | DPR | Size per page (landscape A4) | Used for |
+|---|---|---|---|
+| `<property_dir>/output/*-print.png` | 3.125× (300 dpi) | 3509×2481 px | print-master PDF + the print stylesheet's `.print-img` swap |
+| `<property_dir>/output/.snapshots-web/*-print.png` | 2× (192 dpi) | 2246×1588 px | web PDF |
+
+The print-tier PNGs (300 dpi) are the canonical archived snapshots — they live at the top of `output/` next to the HTML and the PDFs. The web-tier PNGs (192 dpi) are an intermediate render step and live in `output/.snapshots-web/`; they're consumed by the web-PDF build and can be deleted afterwards.
+
+**Render via Playwright** (one script, run twice with different `SCALE`):
+
+```javascript
+const { chromium } = require('playwright');
+const path = require('path');
+
+const HTML = process.argv[2];        // path to brochure.html
+const OUT_DIR = process.argv[3];     // output directory for PNGs
+const SCALE = parseFloat(process.argv[4] || '3.125');  // 2 for web, 3.125 for print
+
+(async () => {
+  const browser = await chromium.launch();
+  const context = await browser.newContext({
+    viewport: { width: 1123, height: 794 },          // 794 × 1123 if portrait
+    deviceScaleFactor: SCALE,
+  });
+  const page = await context.newPage();
+  await page.goto(`file://${HTML}`, { waitUntil: 'networkidle' });
+
+  // Suppress screen-only chrome before snapshotting.
+  // The template has @media print { .download-bar { display: none } } so the
+  // bar disappears under Cmd+P, but Playwright's element.screenshot() captures
+  // the SCREEN render — @media print does not fire. Without this style-tag
+  // injection, the floating "Download PDF" button (and any future screen-only
+  // overlay) leaks into every per-page snapshot and into both PDFs.
+  // KEEP this in any custom render script — it is load-bearing.
+  await page.addStyleTag({ content: `
+    .download-bar { display: none !important; }
+  ` });
+
+  await page.evaluate(() =>
+    Promise.all(Array.from(document.images, img =>
+      img.complete ? null : new Promise(r => { img.onload = img.onerror = r; }))));
+
+  const pages = await page.$$('section.page');
+  for (let i = 0; i < pages.length; i++) {
+    const label = await pages[i].getAttribute('data-screen-label');
+    const filename = i === 0
+      ? 'cover-print.png'
+      : /back/i.test(label || '') ? 'backpage-print.png' : `page${i+1}-print.png`;
+    await pages[i].scrollIntoViewIfNeeded();
+    await pages[i].screenshot({ path: path.join(OUT_DIR, filename), type: 'png' });
+  }
+  await browser.close();
+})();
+```
+
+Run it once for each tier:
+
+```bash
+node render-snapshots.js <property_dir>/output/brochure.html <property_dir>/output/                    3.125
+node render-snapshots.js <property_dir>/output/brochure.html <property_dir>/output/.snapshots-web/    2
+```
+
+For a 16-page folio, each pass produces `cover-print.png`, `page2-print.png` through `page15-print.png`, and `backpage-print.png` — sixteen files in each directory.
+
+**Print CSS**: `@page { size: A4 landscape; margin: 0 }` (or `portrait` if overridden). The print stylesheet has two paths, both still needed:
+
+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`. The 300 dpi snapshots are referenced by `.print-img src=""` so the live DOM print path also gets full-quality output if the user hits Cmd+P.
+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 ships as `brochure.html` plus **two PDFs**, both in `<property_dir>/output/`:
+
+- `<property_slug>-brochure-print.pdf` — **print master** (300 dpi, ~65–100 MB for a 16-page folio). Canonical archive artefact, suitable for sending to commercial print houses.
+- `<property_slug>-brochure-web.pdf` — **web/digital deliverable** (192 dpi, ~20–35 MB). What gets emailed, attached, and downloaded from the web bundle.
+
+Both are image-only — no fonts embedded, no Ghostscript anywhere in the chain. See **a4-print-documents → PDF deliverables** for the full rationale on why image-only is the right answer.
+
+### Build steps
+
+For each grade, bind the per-page PNG snapshots into a PDF via img2pdf, then linearize via qpdf:
+
+```bash
+# Print master from 300 dpi PNGs (in output/)
+cd <property_dir>/output/
+img2pdf --pagesize 297mmx210mm \
+        --title "<Property Name> · <address line 1>" \
+        --author "<Agent Name>" \
+        --output /tmp/pre-linearize.pdf \
+        cover-print.png page2-print.png page3-print.png page4-print.png \
+        page5-print.png page6-print.png page7-print.png page8-print.png \
+        page9-print.png page10-print.png page11-print.png page12-print.png \
+        page13-print.png page14-print.png page15-print.png backpage-print.png
+qpdf --linearize --object-streams=disable \
+     /tmp/pre-linearize.pdf \
+     <property_slug>-brochure-print.pdf
+
+# Web PDF from 192 dpi PNGs (in output/.snapshots-web/)
+cd <property_dir>/output/.snapshots-web/
+img2pdf --pagesize 297mmx210mm \
+        --title "<Property Name> · <address line 1>" \
+        --author "<Agent Name>" \
+        --output /tmp/pre-linearize.pdf \
+        cover-print.png page2-print.png … backpage-print.png
+qpdf --linearize --object-streams=disable \
+     /tmp/pre-linearize.pdf \
+     <property_dir>/output/<property_slug>-brochure-web.pdf
+
+rm /tmp/pre-linearize.pdf
+rm -rf <property_dir>/output/.snapshots-web/   # optional cleanup
+```
+
+`297mmx210mm` is **landscape** A4. For portrait flip to `210mmx297mm`. img2pdf preserves the embedded PNG bytes verbatim — no re-encode, no quality loss. qpdf's `--object-streams=disable` is required because the PDF 1.4 linearization profile (which we want for maximum viewer compatibility) is incompatible with object streams.
+
+### Verification — three commands, all must pass for both files
+
+```bash
+qpdf --check <output>.pdf      # → "No syntax or stream encoding errors found"
+pdfinfo  <output>.pdf | grep Optimized   # → "Optimized: yes"
+pdffonts <output>.pdf | wc -l            # → 2 (header rows only; no font entries)
+```
+
+A typical 16-page folio ships with the print master at **65–100 MB** and the web PDF at **25–45 MB**. If the print master lands under ~40 MB, the snapshot DPR is wrong (likely rendered at 2× instead of 3.125×). If the web PDF exceeds ~55 MB, source photos may be over-floor (see **Image resolution floor** in a4-print-documents) or the snapshot DPR drifted to 3.125× by accident.
+
+If the web PDF runs into a transport limit (some webmail systems cap at 25 MB), substitute JPEG-encoded snapshots: `magick page-print.png -quality 88 -strip -interlace none -colorspace sRGB page-print.jpg`, then bind `.jpg` files instead of `.png`. Expect 30–40% size reduction with no visible quality loss at 192 dpi.
+
+### When to (re)generate
+
+Generate the PDF after every approved layout change. Do not let the PDF drift behind the HTML.
+
+## Web bundle — self-contained zip for hosting
+
+In addition to the print-quality artefacts in `output/`, the brochure ships a separate **self-contained web bundle** under `output/web/`, then zipped to `output/<slug>-web.zip`. This is what a property micro-site or marketing portal hosts publicly. It is intentionally smaller — the canonical `output/` photos and snapshots are sized for archival print quality, which is wasteful when the brochure is being delivered as a one-time HTML page on a web page.
+
+The web bundle is a parallel directory with the same on-disk shape as `output/` but with smaller assets:
+
+```
+output/web/
+  brochure.html                      # identical content; only print-img references switched .png → .jpg
+  index.html                          # companion landing page (mandatory in bundle)
+  cover-print.jpg, page2-print.jpg … backpage-print.jpg   # 96 dpi JPEG snapshots (q=88)
+  <slug>-brochure.pdf                # identical bytes to <slug>-brochure-web.pdf at the property level — simpler name inside the bundle since there's only one PDF here
+  images/
+    <slug>-NN.webp                   # web-tier per-slot encodings (see table below)
+    qr-video.png, qr-listing.png
+    <brand>-logo-light.png
+```
+
+### Web-tier image encoding
+
+The same per-slot tier idea as the digital floor in `images.md`, but with smaller widths and slightly lower quality — sized for screen viewing at 100% zoom, not for print sharpness.
+
+| Slot type | Web tier (long edge / quality) | Typical file size |
+|---|---|---|
+| Hero / cover / banner / feature / drone aerial / front elevation / outdoor full-bleed | **1300 px @ q82** | 80–300 KB |
+| Story photo (in-spread half-page) | **1100 px @ q80** | 60–250 KB |
+| Gallery thumb / strip / image-led grid cell | **800 px @ q76** | 25–80 KB |
+| **Floor plan** (PNG, line art) | **source file copied unchanged** — `cp <slug>-floorplan.png web/images/` | matches source (often 500 KB – 1 MB) |
+| Site plan (raster line art) | **1100 px @ q80** WebP if not already PNG; if PNG, copy unchanged | 30–60 KB or source size |
+
+A 27-image folio typically lands at **~2.5 MB** of web photographs, with the floor plan adding **0.5–1.0 MB** on top because line art is preserved at source resolution. Total web image weight is typically 3.0–3.5 MB.
+
+**Floor-plan rule, repeated for emphasis.** Line-art PNG floor plans are **never re-encoded** for the web bundle — copy the source file as-is. Browsers render PNG line art crisply at any zoom level; converting to WebP introduces visible artefacts on text and rules even at q90+. The bundle gains a few hundred KB but the trade-off is on the right side.
+
+### Print snapshots — JPEG at 96 dpi for the web bundle
+
+The canonical snapshots in `output/` are 300 dpi PNG (~4–7 MB each, ~65 MB total) — far too heavy for the web bundle's `.print-img` swap layer. For the web bundle, derive 96 dpi JPEG copies directly from the canonical 300 dpi PNGs (no PDF round-trip):
+
+```bash
+cd output/web
+for png in ../*-print.png; do
+  base=$(basename "$png" .png)
+  magick "$png" -resize 1123x794^ -quality 88 -strip -interlace none -colorspace sRGB "$base.jpg"
+done
+```
+
+`-resize 1123x794^` downsamples to A4-landscape at 96 dpi (use `794x1123^` for portrait). `-strip` removes embedded metadata (EXIF, ICC) so the bundle stays minimal. `-interlace none` produces baseline JPEG which decodes faster in mobile previewers than progressive.
+
+JPEG at 88% quality is roughly 5× smaller than the PNG equivalent for photographic content. A 16-page folio's web-bundle snapshots total ~3 MB. The brochure HTML's `print-img` references must be updated from `.png` to `.jpg` on the web copy:
+
+```python
+# Edit the web copy of brochure.html only — leave the canonical output/brochure.html unchanged
+import re
+with open("output/web/brochure.html") as f:
+    s = f.read()
+s = re.sub(r'(cover-print|page\d+-print|backpage-print)\.png',
+           lambda m: m.group(1) + '.jpg', s)
+with open("output/web/brochure.html", "w") as f:
+    f.write(s)
+```
+
+A 16-page folio's web-bundle snapshots total ~3 MB (vs ~85 MB for the canonical print PNGs), with no perceptual difference at typical Cmd+P quality.
+
+### Copy the web PDF into the bundle
+
+The web PDF (`<slug>-brochure-web.pdf` at the property level) is also placed inside the bundle, named simply `<slug>-brochure.pdf` to match `index.html` and `brochure.html` link conventions (where there's only one PDF in scope, no `-web` suffix is needed):
+
+```bash
+cp output/<slug>-brochure-web.pdf output/web/<slug>-brochure.pdf
+```
+
+### Bundling
+
+After populating `output/web/`, zip it with `-X` (strip extra attributes) and exclude any `.DS_Store` / AppleDouble files:
+
+```bash
+cd output && rm -f <slug>-web.zip
+( cd web && zip -r -X "../<slug>-web.zip" . -x "*.DS_Store" "._*" )
+```
+
+A typical 16-page folio web zip is **30–50 MB**, dominated by the embedded web PDF. The `output/web/` directory remains on disk alongside the zip — it's the unzipped form of the same bundle, useful for direct upload to a static-site host.
+
+### Smoke-test before declaring done
+
+Serve the unzipped bundle from an isolated temp directory and verify every referenced asset returns 200:
+
+```bash
+TMP=/tmp/web-test && rm -rf $TMP && mkdir -p $TMP
+cd $TMP && unzip -q /path/to/<slug>-web.zip
+python3 -m http.server 8765 &
+for f in brochure.html index.html cover-print.jpg images/<slug>-01.webp images/<brand>-logo-light.png <slug>-brochure.pdf; do
+  echo "$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8765/$f) $f"
+done
+```
+
+The brochure should render the same as the canonical preview, just lighter on the wire. If any 404 appears, the web copy is missing a referenced file — fix and re-zip.
+
+### What stays in `output/` vs. what moves to `output/web/`
+
+| File | `output/` (canonical archive) | `output/web/` (web bundle) |
+|---|---|---|
+| `brochure.html` | full-resolution images, `.png` snapshot refs | identical structure, `.jpg` snapshot refs, smaller image refs |
+| `index.html` | — | ✓ companion landing page; see `index-landing.md` |
+| `<slug>-brochure-print.pdf` | ✓ canonical print master (50–80 MB, 300 dpi) | — (too large to bundle) |
+| `<slug>-brochure-web.pdf` | ✓ web/digital deliverable (20–35 MB, 192 dpi) | — copied into bundle as `<slug>-brochure.pdf` |
+| `<slug>-brochure.pdf` | — | ✓ identical bytes to `-web.pdf`; matches index.html / brochure.html link |
+| `cover-print.png … backpage-print.png` | ✓ 300 dpi PNG (~4–7 MB each) — canonical snapshots | — replaced by 96 dpi `.jpg` versions |
+| `cover-print.jpg … backpage-print.jpg` | — | ✓ 96 dpi JPEG (~150 KB each, derived from the 300 dpi PNGs) |
+| `images/<slug>-NN.webp` | full-quality per Render-slot table | web-tier per the web table above |
+| `images/qr-*.png`, `images/<brand>-logo-*.png` | ✓ | ✓ (copied unchanged — already small) |
+| `.snapshots-web/*-print.png` | ✓ intermediate (192 dpi PNGs used by the web-PDF build; deletable after) | — |
+
+The convention: `output/` is the canonical archive for the property's lifetime. `output/web/` is a derived bundle, regenerable any time from the canonical artefacts.