@rubytech/create-maxy-code 0.1.70 → 0.1.71

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.70",
+  "version": "0.1.71",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/platform/templates/specialists/agents/database-operator.md

@@ -2,7 +2,7 @@
 name: database-operator
 description: "Background recorder for the memory graph. Reads the operator's full conversation transcript (ordered turns array with text and tool calls) from stdin and writes whatever the most recent operator turn implies into the graph via the wrapped writers. Fires once per admin turn from a Stop hook; never reachable from the admin agent directly."
 summary: "Watches every completed admin turn and records what it implies into the memory graph."
-model: claude-haiku-4-5
+model: claude-sonnet-4-6
 tools: mcp__memory__memory-write, mcp__memory__memory-update, mcp__memory__memory-search, mcp__memory__profile-update, mcp__memory__profile-read, mcp__contacts__contact-create, mcp__contacts__contact-update, mcp__tasks__task-create, mcp__tasks__task-update, mcp__tasks__project-create, mcp__tasks__project-update
 ---
 

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

@@ -86,12 +86,12 @@ A `[SKIP]` answer is a **valid** answer for the gate. An empty answer is still a
 
 If the operator's request contains "and socials", "+socials", "with socials", "with OG images", or any equivalent, append a socials step after the brochure web bundle is built:
 
-1. Invoke the `property-socials` skill on the same `<property_dir>` (it reads `output/web/page.html` or `output/web/index.html`, `property.json`, and the brand pack).
-2. The OG JPGs (landscape 1200x630, square 1080x1080, portrait 1080x1350) land under `output/web/socials/`.
-3. This skill **additionally** produces a small gallery page at `output/web/socials.html`: the third endpoint in the web bundle, alongside the brochure HTML and the landing page, previewing each tile size with download links and the suggested copy / alt text for each platform. Brand it from the same DESIGN.md tokens used for the brochure.
-4. The bundle's smoke-test extends to `socials.html` and every JPG referenced; all must return 200 from the isolated HTTP server.
+1. Invoke the `property-socials` skill on the same `<property_dir>` (it reads `output/web/index.html`, `property.json`, and the brand pack).
+2. `property-socials` owns the full deliverable: OG JPGs in `output/web/socials/` (landscape 1200×628, square 1200×1200, portrait 1080×1350), the gallery page at `output/web/socials.html`, captions at `output/web/social-posts.md`, and the `og.html` template kept for re-runs. The orchestrator does **not** produce a separate gallery — everything lands when the skill returns, so a direct standalone invocation produces an identical bundle to the orchestrator-invoked one.
+3. After the skill returns, extend the bundle's smoke-test to include `socials.html` and every JPG referenced; all must return 200 from the isolated HTTP server.
+4. Re-zip the web bundle with the socials artefacts included.
 
-The web bundle is then re-zipped with the socials artefacts included. If the operator did **not** request socials, do not run the step; adding 1 to 3 MB of imagery and a third HTML page silently is an over-reach.
+If the operator did **not** request socials, do not run the step; adding 1 to 3 MB of imagery and a third HTML page silently is an over-reach.
 
 ## Step 4 — populate, render, deliver
 
@@ -164,6 +164,12 @@ When any field above is unresolved after consulting its primary source, **stop b
 - **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.
 - **Brand-token overrides MUST land at the `BRAND_TOKENS_OVERRIDE_SLOT` sentinel** — immediately before the closing `}` of the template's `:root` rule. Any earlier insertion site loses the CSS cascade: the template's own `--paper-25 / --serif / --gold-700` declarations win in source order, and the brochure renders in Premium register despite `register=branded`. The substitution gate and snapshot capture both pass — failure is silent until visual review.
 - **Display-headline wrap contract on `{{ property_name }}`** — `.back-headline em`, `.cover-title`, and `.opener-title em` carry `white-space: nowrap` so multi-word property names sit on one line regardless of brand display family. Removing the nowrap rule reintroduces non-deterministic wrap (same name renders correctly in Premium and breaks in Branded when the display family changes). For a property name long enough to overflow at the column width, shrink the headline `font-size` or shorten the name — never delete the nowrap rule.
+- **Web bundle must contain only referenced images.** Before the zip step, walk `output/web/images/` and remove every file not appearing in any of the bundle's HTML surfaces (`brochure.html`, the companion landing page, optional `og.html`). A bundle carrying unreferenced images is a build defect; the 30–50 MB target documented in `build.md → Web bundle` is enforced, not aspirational. See `build.md → Strip unreferenced images` for the recipe.
+- **Web PDF defaults to JPEG-embedded at quality 85.** Snapshot PNGs in `output/.snapshots-web/` are re-encoded to JPEG q=85 before `img2pdf` binds them. PNG-embedded for the web grade is opt-in only (one-pagers / report-style where small-text crispness outweighs wire size). The print master never flips to JPEG — its audience archives for press runs. A web PDF over ~20 MB on a 16-page folio means the re-encode was skipped.
+- **Companion landing page is named `index.html`.** Every reference (template, bundle, smoke-test, docs) uses `index.html` so the static host serves it as the default document without an explicit URL. Do not drift back to `page.html` — that name was deprecated in favour of hosting-platform default-document compatibility.
+- **Floorplan ships as PNG on disk.** The brochure templates reference `images/<slug>-floorplan.png` and the contract is PNG-only on disk regardless of source format. If the operator-supplied source is JPG, convert at build time (`magick <src>.jpg <slug>-floorplan.png`) before substitution. JPEG compression artefacts on thin lines and small text are unacceptable for floorplans.
+- **Brand-token override block must carry both vocabularies and target both templates.** The brochure (`template.html`) and the landing page (`index.html`) declare independent `:root` token vocabularies (`--paper-25 / --gold-700 / …` vs `--paper / --gold / …`). The brand-tokens block must emit **both** sets of token names with the same brand values and substitute at the `BRAND_TOKENS_OVERRIDE_SLOT` sentinel in **both** templates. A block that only carries the brochure's vocabulary leaves the landing page rendering Premium silently — the substitution gate passes and the snapshot capture proceeds. See `references/build.md → Brand-token override emission` for the mapping table and example block. Long-term vocabulary unification is a follow-up; until it lands the dual emission is structurally required.
+- **Doc-comment strip pass runs against BOTH templates.** After substitution, the `<!-- REPLACE … -->` authoring notes must be removed from both `brochure.html` AND `index.html`. A strip pass that covers only the brochure leaves landing-page authoring notes rendering as visible body text whenever a comment delimiter is misplaced. The companion source-side check in `references/build.md → Template authoring hygiene + CI lint` catches the same defect class at template-edit time.
 - **No `{{ token }}` may remain in rendered output** — `grep '{{' output/brochure.html` must return zero matches before PDFs are built.
 
 ## Scope

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

@@ -4,7 +4,8 @@
 
 1. Copy template to property directory, populate with content
 2. Stage `output/images/` per `images.md → Image renaming and optimisation`
-3. **If branded register and `<brand_dir>/DESIGN.md` contains a `## Type roles` block** — emit the role overlay into both `brochure.html` and `page.html`/`index.html` per **Type-role overlay generation** below. Run this **before** any snapshot capture; the overlay is part of what the user reviews in the browser, not a post-process applied to PDFs.
+3. **If branded register and `<brand_dir>/DESIGN.md` contains a `## Type roles` block** — emit the role overlay into both `brochure.html` and `index.html` per **Type-role overlay generation** below. Run this **before** any snapshot capture; the overlay is part of what the user reviews in the browser, not a post-process applied to PDFs.
+3b. **Doc-comment strip — run against BOTH templates.** After substitution and overlay emission, run a regex pass that removes template authoring notes (the `<!-- REPLACE … -->` markers and any demo-placeholder blocks inside comments) from both `brochure.html` and `index.html`. The single regex is `re.compile(r"<!--\s*REPLACE\s+.*?-->", re.DOTALL)`. Run it explicitly against **both** files — a strip pass that covers only the brochure leaves landing-page authoring notes rendering as visible body text whenever a comment delimiter is misplaced (the historical `page.html` template shipped this defect once already). See **Template authoring hygiene + CI lint** below for the source-side check that catches the same class of defect at template-edit time, before a property build is ever started.
 4. Serve locally: `python3 -m http.server <port>` from the project root
 5. Navigate Playwright to the brochure URL
 6. Present to user in browser for review
@@ -107,7 +108,7 @@ Both are image-only — no fonts embedded, no Ghostscript anywhere in the chain.
 
 ### Build steps
 
-For each grade, bind the per-page PNG snapshots into a PDF via img2pdf, then linearize via qpdf:
+Build both grades from the per-page snapshots in `output/` and `output/.snapshots-web/`, then linearize via qpdf. The print master embeds the PNG snapshots verbatim; the web grade re-encodes them as JPEG quality 85 before binding, so the deliverable that goes out to email and CDN hosting is materially smaller:
 
 ```bash
 # Print master from 300 dpi PNGs (in output/)
@@ -124,13 +125,17 @@ qpdf --linearize --object-streams=disable \
      /tmp/pre-linearize.pdf \
      <property_slug>-brochure-print.pdf
 
-# Web PDF from 192 dpi PNGs (in output/.snapshots-web/)
+# Web PDF from 192 dpi PNGs → JPEG q=85 (in output/.snapshots-web/)
+# img2pdf preserves JPEG bytes verbatim, so re-encoding once up front is the only quality step.
 cd <property_dir>/output/.snapshots-web/
+for png in *-print.png; do
+  magick "$png" -quality 85 -strip -interlace none -colorspace sRGB "${png%.png}.jpg"
+done
 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
+        cover-print.jpg page2-print.jpg … backpage-print.jpg
 qpdf --linearize --object-streams=disable \
      /tmp/pre-linearize.pdf \
      <property_dir>/output/<property_slug>-brochure-web.pdf
@@ -149,9 +154,9 @@ 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.
+A typical 16-page folio ships with the print master at **65–100 MB** (PNG-embedded) and the web PDF at **7–15 MB** (JPEG-embedded at q=85). 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 ~20 MB, the JPEG re-encode was skipped (bind step ran against `.png` instead of `.jpg`) 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.
+The web PDF defaults to JPEG-embedded; PNG-embedded for the web grade is **opt-in only**, for one-pagers or report-style brochures where small-text crispness matters more than wire size. For the standard photographic property folio, JPEG q=85 is visually indistinguishable from PNG at typical screen DPRs and is roughly 3–5× smaller. The print master never flips to JPEG — its audience archives for press runs.
 
 ### When to (re)generate
 
@@ -184,7 +189,7 @@ The same per-slot tier idea as the digital floor in `images.md`, but with smalle
 | 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) |
+| **Floor plan** (PNG output, line art) | **PNG source copied unchanged; JPG source converted to PNG at build time** — `magick <slug>-floorplan.jpg <slug>-floorplan.png` then drop the `.jpg`. The brochure templates reference `images/<slug>-floorplan.png` and the contract is PNG-only on disk; JPEG compression artefacts on thin lines and small text are unacceptable for floorplans. | matches PNG output (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.
@@ -228,6 +233,34 @@ The web PDF (`<slug>-brochure-web.pdf` at the property level) is also placed ins
 cp output/<slug>-brochure-web.pdf output/web/<slug>-brochure.pdf
 ```
 
+### Strip unreferenced images
+
+Every image in `output/web/images/` must be reachable from at least one HTML surface in the bundle (`brochure.html`, the companion landing page, and `og.html` if present). The build accumulates working images during editing — operator drops a hero, re-numbers a sequence, swaps an image and forgets to delete the prior version — and without the strip step the bundle ships every accumulated file. Typical bloat on a re-iterated 16-page folio is 20–40 unreferenced `.webp` files at ~500 KB each, which is what pushes a "30–50 MB target" bundle to 80–120 MB.
+
+```bash
+cd output/web
+
+# Collect every image actually referenced by the bundle's HTML surfaces.
+# `cat *.html` catches brochure.html, the companion landing page, and og.html
+# without needing to know the landing-page filename in advance.
+referenced=$(cat *.html 2>/dev/null \
+  | grep -oE 'images/[A-Za-z0-9_.-]+\.(webp|jpg|jpeg|png|svg)' \
+  | sort -u)
+
+# Walk images/ and remove anything not in $referenced. Brand assets
+# (logos, QR PNGs) are referenced by the templates and survive.
+removed=0
+for f in images/*; do
+  if ! echo "$referenced" | grep -qxF "$f"; then
+    rm -f "$f"
+    removed=$((removed + 1))
+  fi
+done
+echo "[strip] removed $removed unreferenced files from output/web/images/"
+```
+
+The strip is a closed-set operation: two agents producing the bundle for the same property emit byte-identical surviving image sets. Run it before the zip step; a bundle carrying unreferenced images is a build defect, not "extra-safe" packaging.
+
 ### Bundling
 
 After populating `output/web/`, zip it with `-X` (strip extra attributes) and exclude any `.DS_Store` / AppleDouble files:
@@ -271,6 +304,117 @@ The brochure should render the same as the canonical preview, just lighter on th
 
 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.
 
+## Brand-token override emission (cascade-safe, two-template, two-vocabulary)
+
+Branded register replaces palette and type tokens in `:root`. The override is emitted as a `<style id="brand-tokens">…</style>` block at the **`BRAND_TOKENS_OVERRIDE_SLOT`** sentinel in **both** the brochure template (`template.html`) and the companion landing page (`index.html`). The sentinel sits immediately before the closing `}` of each `:root` rule — placing the override after the template's own declarations is what keeps the brand values winning the cascade. See SKILL.md hard rule "Brand-token overrides MUST land at the BRAND_TOKENS_OVERRIDE_SLOT sentinel".
+
+### Two vocabularies (today)
+
+The brochure and the landing page use independent token vocabularies. Until vocabulary unification lands (see follow-up below), the brand-tokens block must include **both** sets of token names so that whichever template the block lands in, the right values bind.
+
+| Concept | `template.html` token | `index.html` token |
+|---|---|---|
+| Ivory page background | `--paper-25` | `--paper` |
+| Slightly darker cream surface | `--paper-50` | `--paper-2` |
+| Warm cream / banded surface | `--paper-100` | (no equivalent — omit) |
+| Pure white | `--paper-0` | (no equivalent — omit) |
+| Body ink | `--ink` | `--ink` (shared name) |
+| Secondary ink | (no equivalent — omit) | `--ink-2` |
+| Bronze accent | `--gold-700` | `--gold` |
+| Antique gold rule / softer accent | `--gold-500` | `--gold-soft` |
+| Champagne flourish | `--gold-300` | (no equivalent — omit) |
+| Display serif family | `--serif` | `--serif` (shared name) |
+| Body serif family | `--body-serif` | (no equivalent — omit) |
+| Sans family | `--sans` | (no equivalent — omit) |
+
+Pick one brand-pack value per concept, emit **both** token names in the same block. Example for a brand whose accent is brand-green `#02843E`:
+
+```html
+<style id="brand-tokens">
+:root {
+  /* template.html vocabulary */
+  --paper-25: #FFFFFF;
+  --paper-50: #F4F1EA;
+  --paper-100: #EFE7D8;
+  --gold-700: #02843E;
+  --gold-500: #4FB371;
+  --gold-300: #C9E8D4;
+  --ink: #323636;
+  --serif: 'Lora', 'Cormorant Garamond', serif;
+  --body-serif: 'Lora', serif;
+  --sans: 'Inter', sans-serif;
+
+  /* index.html vocabulary — same colour values, different token names */
+  --paper: #FFFFFF;
+  --paper-2: #F4F1EA;
+  --gold: #02843E;
+  --gold-soft: #4FB371;
+  --ink-2: #2A3036;
+}
+</style>
+```
+
+The same block is substituted at the sentinel in **both** templates. A block that only carries the `template.html` vocabulary leaves the landing page rendering Premium silently — the substitution gate passes and the snapshot capture proceeds. The defect is invisible until visual review.
+
+### Follow-up — vocabulary unification (long-term)
+
+The dual-emission above is a tactical fix for the divergence between the two templates' `:root` vocabularies. The long-term fix is to **unify the landing page on `template.html`'s tiered vocabulary** (`--paper-0 / -25 / -50 / -100`, `--gold-300 / -500 / -700`, `--ink` plus a `--ink-2` if needed) so every brand block is authored once instead of twice. Until that refactor lands, the dual-emission contract above is structurally required.
+
+## Template authoring hygiene + CI lint
+
+The doc-comment strip in step 3b of the workflow above catches template authoring notes **at property-build time** — but a template that ships with a misplaced `<!-- … -->` delimiter is a source-side defect that should be caught at template-edit time, before any property build runs against it. The historical `page.html` template carried a duplicated authoring note where one copy sat inside a proper comment and the other copy sat outside any delimiters; browsers rendered the duplicate as visible body text on every property built from that template.
+
+Add a CI step (or a `make check-templates` recipe at the plugin root) that parses every `references/*.html` and asserts:
+
+```python
+import re
+from pathlib import Path
+
+REFERENCES = Path("references")
+TEMPLATES = list(REFERENCES.glob("*.html"))           # template.html, index.html
+COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
+
+LEAKED_PHRASES = [
+    "terminate this outer comment",
+    "REPLACE markers, use prose",
+    "delimiter pair",
+    "the bug that prompted this note",
+]
+
+defects = []
+
+for tpl in TEMPLATES:
+    text = tpl.read_text()
+
+    # 1. Every <!-- must be closed by --> within the file.
+    if text.count("<!--") != text.count("-->"):
+        defects.append(f"{tpl}: unbalanced HTML comment delimiters")
+
+    # 2. Strip every well-formed comment, then any LEAKED_PHRASES that
+    # remain are authoring notes sitting outside comments — body-text
+    # defects waiting to ship.
+    outside_comments = COMMENT_RE.sub("", text)
+    for phrase in LEAKED_PHRASES:
+        if phrase in outside_comments:
+            defects.append(f"{tpl}: authoring-note phrase {phrase!r} found outside any HTML comment")
+
+    # 3. `{{ token }}` placeholders are fine inside slot positions but
+    # an example placeholder appearing inside a code-block in body text
+    # (e.g. an explanation of how to use the template) is a leak.
+    # Surface as a soft warning — operator decides.
+    leftover_examples = re.findall(r"\{\{\s*example[_a-z]*\s*\}\}", outside_comments)
+    if leftover_examples:
+        defects.append(f"{tpl}: example placeholders leaked outside comments: {leftover_examples}")
+
+if defects:
+    print("Template lint failed:")
+    for d in defects:
+        print(f"  - {d}")
+    raise SystemExit(1)
+```
+
+Either check catches the page.html-class leak at edit time, before it ships to a property build. The lint runs against the source-side `references/*.html` only — the property-build copies under `<property_dir>/output/` are derived artefacts and are protected by step 3b above instead.
+
 ## Type-role overlay generation
 
 If the brand pack's `DESIGN.md` contains a `## Type roles` block (declared per `references/registers.md → Type-role overrides`), parse it and emit a single `<style id="brand-type-roles">…</style>` block at the `<!-- BRAND_TYPE_ROLES_OVERRIDE_SLOT -->` sentinel immediately before the closing `</style>` of the template's main stylesheet. The override CSS is generated **mechanically** from the recipe map below — the build does not invent selectors, it emits the documented ones using values from the DESIGN doc.

package/payload/premium-plugins/real-agent/plugins/brochures/skills/property-extract/SKILL.md

@@ -319,6 +319,7 @@ The skill orchestrates four capabilities, each a **what** not a **how**:
 2. **Extract.** Pull the raw HTML and grep all `b-cdn.net/propertyimages/...` and `b-cdn.net/floorplans/...` URLs. Deduplicate. Also grep PDF URLs containing `epc`. Extract the `<div class="section__description">` block for the description text. (Map detection is provider-agnostic and happens in step 4 below — don't try to parse map markup at this static-HTML stage.)
 3. **Stage.** Create the four-folder structure under `<output-dir>/<slug>-<listing-id>/`. Download images and floorplans in parallel (`xargs -n1 -P8 curl -O -L`) — there are routinely 40–60 images per listing and serial downloads are slow.
 4. **Capture map** (conditional, provider-agnostic). Drive Playwright to the listing URL and apply the heuristic detector under **Map — extract or omit**: try iframe-by-provider, then class/id-by-keyword, then static-map images, then visual fallback. On the first hit, scroll into view, wait for tiles, screenshot the **element** (not the page), convert to `map.webp` at ~1500 px wide. If no heuristic finds a map, skip — **extract or omit**, no fallback synthesis.
+4b. **Traverse tabbed UIs (conditional, provider-agnostic).** Modern listing pages from Loop CRM tenants, Rightmove, Zoopla and others render top-level data in tabs — *Details / Floorplan / EPC / Virtual Tour / Map View / Book Viewing* — and the static HTML returned by `WebFetch` or `curl` often does not include the inactive-tab content. If the probe in step 1 came back with data the listing visibly shows (EPC band, floorplan thumbnail, video URL) but the static-HTML extract in step 2 does not, the data is almost certainly tab-bound. Drive the Playwright session opened in step 4 (or open one if step 4 skipped) and walk the tab list: detect elements with `role="tablist"`, `role="tab"`, or class/id substrings `tab` containing the keywords `EPC`, `Floor plan`, `Map`, `Virtual tour`, `Brochure`. For each tab found, `page.click(<selector>)`, `page.waitForLoadState('networkidle')`, then harvest the panel content. For the EPC tab specifically: scrape the certificate PDF/PNG link and the displayed current/potential scores into `specifications.epc_rating`, `specifications.epc_current_score`, `specifications.epc_potential_score`. For other tabs: extract what each contract field needs and skip the rest. The traversal is principled — never hard-code a single agency's tab markup as the sole detector; the same listing surface ships with different tab implementations across CMS tenants.
 5. **Assemble.** Write `property.json` and `description.md`. Run a final consistency pass: image count in JSON matches files on disk, EPC rating in JSON matches the description.md line, agent contact in JSON matches the description.md header. `media.map` is populated iff a map screenshot landed on disk; `address.geo` is populated iff coordinates were parseable from a recognised URL pattern (and may legitimately be `null` even when `media.map` is set — see the schema notes).
 
 The skill does not prescribe which HTTP tool to use. `curl` is fine for the static HTML pages Muvin serves. If a future agent ships a JS-rendered listing page, switch to Chrome DevTools MCP or Playwright — the contract on the output is unchanged.
@@ -345,6 +346,7 @@ A delivered package that diverges substantially in shape from the reference is w
 | Saving `/tmp/muvin_property.html` or other working files inside the output directory | The directory is the deliverable. Working files get cleaned up. |
 | Hardcoding the tenant UUID | The UUID identifies the agency on Loop CRM. Different Muvin offices can have different tenant IDs. Extract it from the actual URLs on the page. |
 | Treating "EPC: TBC" as a missing field | "TBC" is information — the agent is telling you the assessment hasn't been done. Record it verbatim. |
+| Recording "EPC: TBC" when the listing's EPC tab actually shows a band but the static HTML did not | Modern listings tab-hide data behind a JS tab switcher; `WebFetch` / `curl` see only the active tab. If the listing visibly carries EPC content the static HTML lacks, drive Playwright per step 4b and harvest from the tab panel. "TBC" recorded from a missed-tab extract is a silent data-loss defect, not a faithful record. |
 | Synthesizing a map when the listing has none | The rule is **extract or omit**. Postcode-centroid renders, OSM static maps, and AI-generated map artwork are all forbidden. If the heuristic detector returns nothing, write `media.map: null` and move on. |
 | Hard-coding a single CMS's map markup (`section__property--map`, `<iframe src="google.com/maps">`) as the only detector | Each agent embeds maps differently — Loop CRM uses Google iframes, custom builds use Mapbox-GL canvases, others use static-map `<img>` tags. The detection order is heuristic and provider-agnostic by design. Hard-coding one breaks every other listing. |
 | Trying to render a map provider's tiles ourselves with our own API key | The screenshot approach captures whatever the agency already pays for, with their attribution. Spinning up our own Mapbox/Google account introduces a billing relationship the user didn't ask for, and risks brand-mismatch with what the agency publishes. Screenshot the element; don't reach for an API. |

package/payload/premium-plugins/real-agent/plugins/brochures/skills/property-socials/SKILL.md

@@ -27,23 +27,24 @@ shots — it does not re-design anything.
 
 ## Output contract
 
-Two deliverables every time: image files and the captions that go with them.
+This skill owns the **full** social-collateral deliverable. Whether invoked directly or through `make-brochure`'s `+socials` add-on, the same files land on disk — no orchestrator-side gallery emission, no split contract.
 
-**Image files** are written next to `page.html` so they share the same public
-URL prefix:
+```
+output/web/
+  socials/
+    og-landscape-<hero>.jpg     # 1200×628  Twitter / LinkedIn / Facebook / OG
+    og-square-<hero>.jpg        # 1200×1200 Instagram feed
+    og-portrait-<hero>.jpg      # 1080×1350 Instagram portrait, mobile
+  socials.html                  # gallery page — the third HTML endpoint in the bundle
+  social-posts.md               # paste-ready captions, also linked from socials.html
+  og.html                       # template that renders the tiles, kept for re-runs
+```
 
-| File | Dimensions | Use |
-|------|------------|-----|
-| `og-landscape-<hero>.jpg` | 1200×628  | Twitter / LinkedIn / Facebook / OG |
-| `og-square-<hero>.jpg`    | 1200×1200 | Instagram feed |
-| `og-portrait-<hero>.jpg`  | 1080×1350 | Instagram portrait, mobile |
+`<hero>` is `main`, `kitchen`, or `garden`. At minimum produce `og-landscape-main.jpg`; offer the full nine-variant set (landscape + square + portrait × main/kitchen/garden) when the user wants social collateral, not just a meta image.
 
-`<hero>` is `main`, `kitchen`, or `garden`. At minimum produce
-`og-landscape-main.jpg`; offer the full five-variant set (landscape + square +
-three portraits) when the user wants social collateral, not just a meta image.
+**Gallery page (`socials.html`)** sits at the root of the web bundle, alongside `brochure.html` and `index.html`. It previews each tile at its actual dimensions with download links, the suggested copy from `social-posts.md` inline next to each tile, and the platform's `<meta>` snippet ready to paste into a page `<head>`. Brand it from the same DESIGN.md tokens used for the brochure — same `:root` palette, same display family, same accent.
 
-**Captions** are written into `output/web/social-posts.md`, one section per
-image, ready to paste. Every caption is generated through the `plainly` skill's
+**Captions (`social-posts.md`)** are written one section per image, ready to paste. Every caption is generated through the `plainly` skill's
 register: no em-dashes, no inflation vocabulary (*discover*, *unlock*,
 *nestled*, *stunning*, *boasts*, *bespoke* where it isn't literally bespoke),
 no antithetical "it's not X, it's Y", no rhetorical openers (*Imagine…*,