@rubytech/create-maxy-code 0.1.59 → 0.1.61

package/payload/platform/plugins/preval/skills/property-preval/SKILL.md

@@ -1,78 +1,118 @@
 ---
 name: property-preval
-description: Use when an operator asks for a pre-valuation pack for a single UK property — input is one full UK address, output is a 4-page A4 PDF covering valuation, area, and demand/trend. Triggers include "preval <address>", "pre-valuation for <address>", "what's <address> worth", "valuation pack for <address>", "market and area report for <address>".
+description: Use when an operator wants a pre-valuation pack to pitch for a UK property listing — a 5-page A4 PDF that combines a market-data report for the postcode with the subject property's own valuation range, full-width sold + asking comparables, and the agent's recent successes as the sales close. Triggers include "preval <address>", "pre-valuation for <address>", "valuation pitch for <address>", "what's <address> worth and pitch us to list it", "pre-appraisal pack for <address>".
 ---
 
 # Property Preval
 
-Outcome: turn **one full UK address** into a 4-page A4 pre-valuation PDF the operator can send to a vendor before the appraisal visit. The skill owns the fan-out and the render; the operator supplies only the address.
+A 5-page A4 PDF that pitches the agent for the listing: cover (full-bleed subject hero), subject valuation (sqft × £/sqft band with operator adjustments), market context, full-width comparables (sold + asking stacked), and the agent's recent successes + disclaimer. **Preval is a sales pitch, not just a data sheet** — every page either tells the vendor what the property is worth or what the agent has recently delivered nearby.
 
-## Input
+## Typography is fixed; only colours and logos come from the agent
 
-A single string — the full UK address, ending in a valid UK postcode. Examples:
+Same typographic lock as `property-market-report`:
 
-- `47 Phoenix Drive, Bishop's Stortford, CM23 2UJ`
-- `Flat 3, 122 Kensington High Street, London, W8 4SG`
+- **Display** — Cormorant Garamond (italic for headlines, KPI values, prices, addresses)
+- **Body** — Lora
+- **Sans / labels** — Inter (eyebrows, KPI labels, chips, footer meta)
 
-The skill derives the postcode by matching the UK postcode regex on the final token group. If no postcode is matched, the skill stops and asks the operator for one.
+Never substitute the agent's body or display fonts even if their `DESIGN.md` specifies different families. The pack reads as an editorial / luxury document across every brand. The agent's identity comes through the **palette and logo only**.
 
-## Output
-
-A directory under `~/Documents/Maxy/preval/<postcode-compact>-<YYYY-MM-DD>/` containing:
+## Inputs (never invented)
 
-- `index.html` — single self-contained file.
-- `<slug>-<date>.pdf` — exactly 4 A4 pages. If `mdls -name kMDItemNumberOfPages` returns ≠ 4, the renderer raises rather than ship an overflowing report.
-
-Return the PDF path to the operator.
+- **`address`** — full UK address ending in a valid postcode (e.g. `9 Phoenix Drive, Bishop's Stortford, CM23 2UJ`). Skill derives the postcode by matching the UK postcode regex on the final token group; stops if no match.
+- **`brand`** — agent design tokens, same shape as property-market-report: `name`, `tagline`, hex tokens `primary` / `primary_dark` / `accent` / `paper` / `paper_banded` / `rule`. Optional `logo_light` / `logo_dark` filesystem paths. Resolved from the agent's `DESIGN.md` (e.g. `/estate-agents/muvin/DESIGN.md`); read the canonical hex values directly, never substitute "close" colours. Only colour tokens are consumed; typography/spacing/radius tokens in the agent's `DESIGN.md` are ignored by design.
+- **`subject`** — paste-in details about the property being valued:
+  - `cover_hero` (filesystem path or URL to a photo of the subject — required for the cover).
+  - Optional `beds`, `type`, `tenure`, `condition` (well / average / needs work).
+  - `adjustments[]` — operator-curated array of `{label, delta_pct}` covering esoteric factors that shift the headline range (e.g. `{"label":"South-facing garden","delta_pct":3}`, `{"label":"Needs full reno","delta_pct":-8}`). Deltas sum linearly into the final range.
+  - `narrative` — one short paragraph the operator writes about the property.
+  - **Floor area is auto-pulled from the EPC register** via `real-agent-epc` (`epc-lookup-by-address`) and surfaced as `sqft_m2` + derived `sqft`. If EPC has no record (pre-2008 property never sold or let; Scotland/NI; unmatched), operator pastes `subject.sqft` directly. Without a floor area the renderer prints "Estimate requires floor area" and shows only the £/sqft benchmark — never invents a number.
+- **`agent_listings`** — the agent's recent sold / under-offer / live listings to feature on the closing page. Up to 6 entries of `{url, address, price, beds, type, image, status, slug}` where `status ∈ {"Sold","Under offer","For sale"}`. Operator picks the comps that make the strongest pitch; this is *not* the PropertyData sample.
+- **`market_summary`** — `headline` (one display-italic line), `paragraphs[]` (2–3 short paragraphs), `demand_gauge_position` (percentage string like `"62%"`), `price_growth_note`, `demand_note`. The operator drafts or accepts an LLM stub.
 
-## Tools the skill calls (in order)
+## Tools the skill calls
 
-Fan-out is fixed at **12** `real-agent-property-data` MCP tools, keyed on the derived postcode (and address attributes where the tool needs them):
+Parallel fan-out keyed on the derived postcode + the subject address:
 
+**PropertyData (12 calls — credit cost 12):**
 1. `property-data-prices` — asking £ distribution + raw asking comps.
 2. `property-data-prices-per-sqf` — asking £/sqft.
 3. `property-data-sold-prices` — Land Registry sold transactions + raw sold comps.
-4. `property-data-sold-prices-per-sqf` — achieved £/sqft.
+4. `property-data-sold-prices-per-sqf` — achieved £/sqft (plus 70pc band used for the valuation range).
 5. `property-data-growth` — 7y price series.
 6. `property-data-growth-psf` — 7y £/sqft series.
 7. `property-data-demand` — for-sale, sales/mo, turnover, MoI, DoM, demand rating.
 8. `property-data-demand-rent` — rental-side demand pillar.
-9. `property-data-property-types` — mix doughnut (detached / semi / terraced / flat).
+9. `property-data-property-types` — mix (detached / semi / terraced / flat).
 10. `property-data-crime` — area crime rating + breakdown.
 11. `property-data-flood-risk` — area flood risk (full postcode only).
-12. `property-data-council-tax` — band D cost + per-property bands (full postcode only).
+12. `property-data-council-tax` — band D + per-property bands (full postcode only).
 
-## Tools the skill deliberately does NOT call
+**EPC (1 call — free, rate-limited):**
 
-- `property-data-address-match-uprn` — UPRN is CRM hygiene, not preval data.
-- `property-data-planning-applications` — planning is a separate dev-precedent report.
+13. `epc-lookup-by-address(address, postcode)` — subject floor area + energy ratings + lodgement date.
 
-Both remain available via the underlying `property-data` skill; preval omits them to keep the output focused and the credit cost at 12 per pack.
+`address-match-uprn` and `planning-applications` are deliberately omitted (CRM hygiene and dev-precedent reports respectively).
+
+## Output
+
+Directory under `~/Documents/Maxy/preval/<postcode-compact>-<YYYY-MM-DD>/` containing:
+
+- `index.html` — single self-contained file.
+- `img/` — copied logos and the subject hero image.
+- `<slug>-<date>.pdf` — exactly **5** A4 pages. Renderer asserts via `pdfinfo` and raises if ≠ 5.
+
+Return the PDF path to the operator.
+
+## Pages
+
+1. **Cover** — full-bleed `subject.cover_hero` with vertical gradient scrim; light logo top-left; eyebrow "`<brand.name>` · Pre-valuation"; address in display-italic; postcode chip; four-up meta strip (Report · Address · Postcode · Generated). Lifted from property-market-report's cover contract.
+2. **Subject valuation** — KPI strip (sqft, beds, EPC rating, type). Centre panel: headline range = `sqft × sold_psf_low–high` (Land Registry 70pc band) with `sqft × asking_psf` shown as a cross-check. Operator `adjustments[]` displayed as a stacked list (label · delta% · running £). Final range pill at the foot. If `sqft` missing the panel switches to the "requires floor area" mode (£/sqft benchmark only). One paragraph of `subject.narrative` under the panel.
+3. **Market context** — KPI cube (avg asking, avg sold, £/sqft, YoY); pill + gauge for demand; 7y growth sparkline (£ solid + £/sqft dashed); summary paragraphs. Same patterns as property-market-report's page 2.
+4. **Comparables (full-width, stacked)** — Nearest sold table (top 6) full-width across the page; Live asking tile grid (top 4) full-width below. Vertically stacked, never side-by-side — corrects the cramped two-column layout in the v1 preval where the asking tiles got pushed to ~40mm columns of italic addresses.
+5. **Recently with `<brand.name>` + sources** — agent's own listings as a clickable tile grid (`<a>` per card, status badge: Sold / Under offer / For sale), then the sources / methodology / accuracy / investment block. Closes with `Real Agent · Generated <date> · <postcode>` in the footer.
 
 ## How to execute
 
-1. Match the postcode out of the address (`/[A-Z]{1,2}[0-9][A-Z0-9]?\s?[0-9][A-Z]{2}/i`). Stop and ask if no match.
-2. Run the 12 fan-out tools in the order above. Any `Error: key-not-registered` aborts the run — surface the registration prompt and stop.
-3. Assemble the `inputs.json` shape per `references/template-inputs.schema.json`.
-4. Run `python3 references/render.py inputs.json`. The renderer fills the template, writes the HTML, drives Chrome `--print-to-pdf`, and asserts page count = 4.
-5. Return the PDF path.
+1. Match the postcode out of the address (`/[A-Z]{1,2}[0-9][A-Z0-9]?\s?[0-9][A-Z]{2}/i`). Stop if no match.
+2. Run the 13 fan-out tools (12 PropertyData + 1 EPC) in parallel. Failure handling differs by source:
+   - **PropertyData `key-not-registered`** → abort with the `property-data-key-register` prompt. The pack cannot render without market data.
+   - **PropertyData `http-429`** → back off, retry only the throttled tool. Do not re-run the whole fan-out.
+   - **EPC failure of any kind** — `key-not-registered`, `http-404 (no record on file)`, `http-429`, `http-500`, network failure, or MCP not configured on the account — is treated as a single class: **prompt the operator** with the relevant cause (e.g. "EPC API key not registered — register with `epc-key-register`, or paste subject.sqft to continue"; "No EPC on file for this address — paste subject.sqft to continue"; "EPC API unavailable — paste subject.sqft to continue"). If the operator pastes `subject.sqft`, the pack renders normally with the EPC-derived KPI cells switching to "—" + "No EPC on file" / "EPC API unavailable" sub-labels. If the operator declines to paste, the valuation panel switches to the "Estimate requires floor area" benchmark-only mode and the pack still renders the other four pages.
+3. Compute valuation range:
+   - `sold_psf_low` = `sold-prices-per-sqf` `70pc_range[0]`
+   - `sold_psf_high` = `sold-prices-per-sqf` `70pc_range[1]`
+   - `low = sqft × sold_psf_low`, `mid = sqft × sold_psf`, `high = sqft × sold_psf_high`
+   - Apply `adjustments` linearly: `factor = 1 + Σ delta_pct / 100`. Final range = `[low × factor, high × factor]`, midpoint = `mid × factor`.
+4. Assemble the `inputs.json` shape per `references/template-inputs.schema.json`.
+5. `python3 references/render.py inputs.json`. Renderer fills the template, copies logos + hero into `img/`, drives Chrome `--print-to-pdf`, asserts page count == 5.
+6. Return the PDF path.
 
-## Observability
+## Adjustments — linear vs compound
 
-Emit at start: `[preval] start address="<addr>" postcode=<pc>`.
-Emit at done:  `[preval] done pdf=<path> pages=<n> ms=<n>`.
+Deltas sum linearly (`-8 + 3 = -5%`, applied as `× 0.95`). Compound interpretation (`× 0.92 × 1.03`) would give a slightly different number (-5.24%) but the operator presents the figures verbally as a sum, so the displayed maths must match the verbal claim. If a future operator wants compound adjustments, this is a deliberate skill-level rewrite, not a config switch.
+
+## Observability
 
-Each of the 12 fan-out calls produces its own `[property-data] tool=<name>` line in `server.log` (inherited contract — no new instrumentation).
+- `[preval] start address="<addr>" postcode=<pc>` at run start.
+- `[preval] done pdf=<path> pages=<n> ms=<n>` at run end.
+- Each fan-out call emits its own `[property-data] tool=<name>` or `[epc] tool=<name>` line in `server.log` (inherited contracts; no new instrumentation here).
 
 ## Failure signatures
 
-- `pages=5` (or anything ≠ 4) in the `done` line → template overflow on one page. Diagnose with `pdftoppm -png -f 5 -l 5 <pdf>` to see which content bled, then trim that panel's padding.
+- `pages=6` (or ≠ 5) in the `done` line → template overflow on one page. Diagnose with `pdftoppm -png -f <n> -l <n> <pdf>` to see which page bled, then trim that panel's padding only.
 - `start` with no matching `done` within 60s → renderer crashed. Inspect with `grep -B2 -A20 '\[preval\] start address="<echoed>"' server.log`.
-- Wrong postcode derivation → check `grep '\[preval\] start' server.log | awk -F'postcode=' '{print $2}' | sort -u`; the regex must keep the inward part of the postcode (e.g. `CM23 2UJ`, not `CM23`).
+- `[epc] … status=http-404` → property has no EPC; prompt "no EPC on file for this address — paste subject.sqft to continue".
+- `[epc] … status=key-not-registered` → prompt "EPC API key not registered — run `epc-key-register`, or paste subject.sqft to continue".
+- `[epc] … status=http-429` | `http-5xx` | `bad-response` | `network-error` → prompt "EPC API unavailable — paste subject.sqft to continue". The MCP-not-installed case (no `[epc] …` line at all and the tool call surfaces as "tool not found") is the same prompt with cause "EPC MCP not configured on this account".
+- `[property-data] … status=http-429` → 4-calls-in-10-seconds throttle. Retry only the throttled tool after the back-off; do not re-run the whole fan-out.
 
 ## Out of scope
 
-- Multi-address batch preval (CSV in → many PDFs out) — separate skill if needed.
-- Loop CRM auto-publish of the PDF onto a contact's record — separate skill.
-- A hero image on the cover via `property-socials` — preval cover is text-only by design.
-- Caching of MCP responses — 12 credits per pack is acceptable; cost optimisation is a Task 144B concern.
+- Multi-address batch preval (CSV in → many PDFs out).
+- Loop CRM auto-publish of the PDF onto a contact's record.
+- Pulling `agent_listings` from Loop CRM automatically — operator paste-in for now; CRM wire-up is a separate task.
+- Caching of MCP responses (13 credits per pack is acceptable).
+- A separate cover letter / pitch letter — the cover page *is* the pitch.
+- Compound adjustments (linear sum is the contract; see above).
+- Subject sqft from sources other than EPC and the operator paste-in fallback (e.g. Loop CRM floor plans, Rightmove sqft scrape) — separate task if pursued.

package/payload/platform/plugins/preval/skills/property-preval/references/render.py

@@ -2,7 +2,7 @@
 
 Substitutes <!-- REPLACE: <slot> --> placeholders in template.html with values
 derived from one inputs.json (shape: template-inputs.schema.json), drives
-Chrome headless to produce a 4-page A4 PDF, and asserts page count == 4.
+Chrome headless to produce a 5-page A4 PDF, and asserts page count == 5.
 
 Usage:
     python3 render.py inputs.json
@@ -12,10 +12,25 @@ import html, json, re, shutil, subprocess, sys
 from pathlib import Path
 
 
+M2_TO_SQFT = 10.7639
+
+
 def _money(n: int) -> str:
     return f"£{int(n):,}"
 
 
+def _range_money(low: int, high: int) -> str:
+    return f"£{int(low):,} – £{int(high):,}"
+
+
+# ---------------- helpers ----------------
+
+def _short_address(address: str) -> str:
+    """First two address tokens for the cover meta strip."""
+    parts = [p.strip() for p in address.split(",")]
+    return ", ".join(parts[:2]) if len(parts) >= 2 else address
+
+
 def _sold_comps_rows(rows: list[dict]) -> str:
     if not rows:
         return '<tr><td colspan="4" class="muted">No sold transactions in the sample.</td></tr>'
@@ -49,31 +64,6 @@ def _asking_comps_tiles(rows: list[dict]) -> str:
     return "".join(out)
 
 
-def _crime_rows(rows: list[dict]) -> str:
-    if not rows:
-        return '<div class="muted">No crime data.</div>'
-    top = sorted(rows, key=lambda r: r["count"], reverse=True)[:6]
-    cap = max((r["count"] for r in top), default=1) or 1
-    return "".join(
-        f'<div class="dist-row">'
-        f'<div class="name">{html.escape(r["category"])}</div>'
-        f'<div class="bar"><span{" class=gold" if i == 0 else ""} style="width:{int(100 * r["count"] / cap)}%"></span></div>'
-        f'<div class="pct">{r["count"]}</div>'
-        f"</div>"
-        for i, r in enumerate(top)
-    )
-
-
-def _band_rows(rows: list[dict]) -> str:
-    if not rows:
-        return '<tr><td colspan="2" class="muted">No banding data.</td></tr>'
-    return "".join(
-        f"<tr><td>Band {html.escape(r['band'])}</td>"
-        f"<td class=\"num\">{_money(r['amount'])}</td></tr>"
-        for r in rows
-    )
-
-
 def _type_dist_rows(rows: list[dict]) -> str:
     if not rows:
         return '<div class="muted">No property-type mix data.</div>'
@@ -89,7 +79,7 @@ def _type_dist_rows(rows: list[dict]) -> str:
 
 
 def _spark_svg(price_series: list[dict], psf_series: list[dict]) -> str:
-    """Two-line sparkline in a 1000x380 viewBox SVG, no external dependencies."""
+    """Two-line sparkline in a 1000x380 viewBox SVG, no external deps."""
     W, H = 1000, 380
     pad_l, pad_r, pad_t, pad_b = 70, 30, 30, 50
     iw, ih = W - pad_l - pad_r, H - pad_t - pad_b
@@ -102,9 +92,7 @@ def _spark_svg(price_series: list[dict], psf_series: list[dict]) -> str:
         if ymax == ymin:
             ymax = ymin + 1
         n = len(series)
-        pts = []
-        circles = []
-        labels = []
+        pts, circles, labels = [], [], []
         for i, p in enumerate(series):
             x = pad_l + (i * iw / max(1, n - 1))
             y = pad_t + ih - ((float(p[key]) - ymin) / (ymax - ymin)) * ih
@@ -115,8 +103,7 @@ def _spark_svg(price_series: list[dict], psf_series: list[dict]) -> str:
             )
         return (
             f'<polyline class="{css_pl}" points="{" ".join(pts)}"/>'
-            + "".join(circles)
-            + "".join(labels)
+            + "".join(circles) + "".join(labels)
         )
 
     axis = (
@@ -128,54 +115,283 @@ def _spark_svg(price_series: list[dict], psf_series: list[dict]) -> str:
     )
 
 
+def _summary_paragraphs(paras: list[str]) -> str:
+    if not paras:
+        return ""
+    out = [f'<p class="dropcap">{html.escape(paras[0])}</p>']
+    for p in paras[1:]:
+        out.append(f"<p>{html.escape(p)}</p>")
+    return "".join(out)
+
+
+def _wordmark(brand: dict, variant: str, out_dir: Path) -> str:
+    """variant ∈ {'light', 'dark'}. Mirrors property-market-report's wordmark."""
+    key = "logo_light" if variant == "light" else "logo_dark"
+    logo_path = brand.get(key)
+    if logo_path:
+        src = Path(logo_path).expanduser()
+        dest_dir = out_dir / "img"
+        dest_dir.mkdir(parents=True, exist_ok=True)
+        dest = dest_dir / src.name
+        if src.resolve() != dest.resolve():
+            shutil.copy2(src, dest)
+        rel = f"img/{src.name}"
+        height = "14mm" if variant == "light" else "9mm"
+        return f'<img src="{html.escape(rel)}" alt="{html.escape(brand["name"])}" style="height:{height};width:auto;display:block">'
+    cls = "wm light" if variant == "light" else "wm small"
+    return (
+        f'<div class="{cls}">'
+        f'<span class="wm-name">{html.escape(brand["name"])}</span>'
+        f'<span class="wm-sub">{html.escape(brand["tagline"])}</span>'
+        f"</div>"
+    )
+
+
+def _hero_asset(subject: dict, out_dir: Path) -> str:
+    """Copy subject.cover_hero into img/ and return the relative path. URLs pass through."""
+    hero = subject["cover_hero"]
+    if hero.startswith(("http://", "https://", "data:")):
+        return hero
+    src = Path(hero).expanduser()
+    if not src.exists():
+        raise FileNotFoundError(f"subject.cover_hero not found: {src}")
+    dest_dir = out_dir / "img"
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest = dest_dir / f"hero{src.suffix.lower()}"
+    if src.resolve() != dest.resolve():
+        shutil.copy2(src, dest)
+    return f"img/{dest.name}"
+
+
+def _listing_card(p: dict, index: int, out_dir: Path) -> str:
+    addr_parts = [x.strip() for x in p["address"].split(",")]
+    addr = html.escape(addr_parts[0])
+    chips = []
+    if p.get("beds"):  chips.append(f"{p['beds']} bed")
+    if p.get("type"):  chips.append(html.escape(p["type"]))
+    chips_html = "".join(f"<span>{c}</span>" for c in chips)
+    img_src = ""
+    if p.get("image"):
+        src = Path(p["image"]).expanduser() if not str(p["image"]).startswith(("http://", "https://", "data:")) else None
+        if src and src.exists():
+            dest_dir = out_dir / "img"
+            dest_dir.mkdir(parents=True, exist_ok=True)
+            dest = dest_dir / f"agent-{index:02d}-{p['slug']}{src.suffix.lower()}"
+            if src.resolve() != dest.resolve():
+                shutil.copy2(src, dest)
+            img_src = f"img/{dest.name}"
+        elif src is None:
+            img_src = str(p["image"])
+    status = p.get("status", "")
+    badge_cls = {"Sold": "sold", "Under offer": "under"}.get(status, "")
+    photo = (
+        f'<div class="photo">'
+        f'{f"<img src=\"{html.escape(img_src)}\" alt=\"{addr}\">" if img_src else ""}'
+        f'<div class="badge {badge_cls}">{html.escape(status)}</div>'
+        f"</div>"
+    )
+    meta = (
+        f'<div class="meta">'
+        f'<div class="addr">{addr}</div>'
+        f'<div class="price">{_money(p["price"])}</div>'
+        f'<div class="kfs">{chips_html}</div>'
+        f"</div>"
+    )
+    inner = photo + meta
+    if p.get("url"):
+        return f'<a class="listing" href="{html.escape(p["url"])}" target="_blank" rel="noopener">{inner}</a>'
+    return f'<div class="listing">{inner}</div>'
+
+
+def _agent_listings_cards(rows: list[dict], out_dir: Path) -> str:
+    if not rows:
+        return '<div class="muted" style="margin-top:5mm">No recent listings supplied.</div>'
+    return "".join(_listing_card(p, i, out_dir) for i, p in enumerate(rows[:6]))
+
+
+# ---------------- valuation maths ----------------
+
+def _valuation_block(subject: dict, valuation: dict) -> str:
+    """Build the page-2 valuation panel: headline range, adjustments, final range.
+
+    Falls back to the 'requires floor area' state when subject.sqft is missing.
+    """
+    sqft = subject.get("sqft")
+    if not sqft:
+        return (
+            '<div class="val-panel"><div class="val-empty">'
+            "Estimate requires floor area.<br>"
+            "<span style=\"font-size:10pt;color:var(--text-muted)\">"
+            f"Benchmark: sold £/sqft = {_money(valuation['sold_psf'])}, "
+            f"asking £/sqft = {_money(valuation['asking_psf'])}. "
+            "Paste subject.sqft to compute the range."
+            "</span></div></div>"
+        )
+
+    low_psf  = valuation["sold_psf_low"]
+    mid_psf  = valuation["sold_psf"]
+    high_psf = valuation["sold_psf_high"]
+    ask_psf  = valuation["asking_psf"]
+
+    low_raw  = int(sqft * low_psf)
+    mid_raw  = int(sqft * mid_psf)
+    high_raw = int(sqft * high_psf)
+    ask_raw  = int(sqft * ask_psf)
+
+    rows = [
+        ('<div class="val-row headline">'
+         f'<div class="lbl">Headline range<small>{sqft:,} sqft × £{low_psf}–£{high_psf} sold £/sqft (Land Registry 70pc band)</small></div>'
+         f'<div class="num">{_range_money(low_raw, high_raw)}</div></div>'),
+        ('<div class="val-row">'
+         f'<div class="lbl">Cross-check · asking £/sqft<small>{sqft:,} sqft × £{ask_psf} mean asking £/sqft</small></div>'
+         f'<div class="num">{_money(ask_raw)}</div></div>'),
+    ]
+
+    adjustments = subject.get("adjustments") or []
+    if adjustments:
+        rows.append('<div class="val-row"><div class="lbl" style="font-family:var(--sans);font-weight:600;font-size:8pt;letter-spacing:2pt;text-transform:uppercase;color:var(--text-accent)">Adjustments</div><div class="num">&nbsp;</div></div>')
+        for adj in adjustments:
+            delta = float(adj["delta_pct"])
+            cls = "pos" if delta > 0 else ("neg" if delta < 0 else "")
+            sign = "+" if delta >= 0 else ""
+            rows.append(
+                '<div class="val-row adj">'
+                f'<div class="lbl">{html.escape(adj["label"])}</div>'
+                f'<div class="num {cls}">{sign}{delta:.1f}%</div>'
+                "</div>"
+            )
+
+    delta_sum = sum(float(a["delta_pct"]) for a in adjustments)
+    factor = 1.0 + delta_sum / 100.0
+    low_final  = int(low_raw  * factor)
+    high_final = int(high_raw * factor)
+
+    final = (
+        '<div class="val-final">'
+        f'<div class="lbl">Final indicative range</div>'
+        f'<div class="num">{_range_money(low_final, high_final)}</div>'
+        "</div>"
+    )
+
+    return '<div class="val-panel">' + "".join(rows) + "</div>" + final
+
+
+def _kpi_subject_sqft(subject: dict) -> tuple[str, str]:
+    sqft = subject.get("sqft")
+    m2 = subject.get("sqft_m2")
+    if sqft:
+        sub = f"≈ {m2:.0f} m² · from EPC register" if m2 else "Square feet (operator)"
+        return f"{int(sqft):,}", sub
+    return "—", "No EPC on file"
+
+
+def _kpi_subject_epc(subject: dict) -> tuple[str, str]:
+    current  = subject.get("epc_current")
+    potential = subject.get("epc_potential")
+    lodgement = subject.get("epc_lodgement")
+    if not current:
+        return "—", "No EPC on file"
+    sub_bits = []
+    if potential:
+        sub_bits.append(f"potential {potential}")
+    if lodgement:
+        sub_bits.append(f"lodged {lodgement}")
+    return current, " · ".join(sub_bits) or "EPC register"
+
+
+# ---------------- render ----------------
+
 def render(inputs: dict, out_dir: Path, template_path: Path | None = None) -> Path:
     template_path = template_path or (Path(__file__).parent / "template.html")
     tmpl = template_path.read_text()
 
-    v = inputs["valuation"]
-    a = inputs["area"]
-    d = inputs["demand_trend"]
-    r = d["rental"]
+    brand   = inputs["brand"]
+    subject = inputs["subject"]
+    v       = inputs["valuation"]
+    a       = inputs["area"]
+    d       = inputs["demand_trend"]
+    ms      = inputs["market_summary"]
+    r       = d["rental"]
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    subject_sqft, subject_sqft_sub = _kpi_subject_sqft(subject)
+    subject_epc,  subject_epc_sub  = _kpi_subject_epc(subject)
+
+    yoy = d.get("yoy_growth_pct")
+    if yoy is None and len(d.get("growth_series", [])) >= 2:
+        last, prev = d["growth_series"][-1]["price"], d["growth_series"][-2]["price"]
+        yoy = (last - prev) / prev * 100.0
+    yoy_str = f"{yoy:+.1f}%" if yoy is not None else "—"
+
+    psf = d.get("sales_per_month")
+    if psf is None:
+        psf = max(1, round(d["for_sale"] / 7))  # crude fallback only when not provided
 
     slots = {
+        # branding
+        "brand_name":         brand["name"],
+        "brand_tagline":      brand["tagline"],
+        "brand_primary":      brand["primary"],
+        "brand_primary_dark": brand["primary_dark"],
+        "brand_accent":       brand["accent"],
+        "brand_paper":        brand["paper"],
+        "brand_paper_banded": brand["paper_banded"],
+        "brand_rule":         brand["rule"],
+        "wordmark_light":     _wordmark(brand, "light", out_dir),
+        "wordmark_dark":      _wordmark(brand, "dark",  out_dir),
+
+        # cover + header
+        "subject_hero_path":  _hero_asset(subject, out_dir),
         "address":            inputs["address"],
+        "address_short":      _short_address(inputs["address"]),
         "postcode":           inputs["postcode"],
         "generated":          inputs["generated"],
 
-        "kpi_avg_asking":     _money(v["avg_asking"]),
-        "kpi_asking_psf":     _money(v["asking_psf"]),
-        "kpi_avg_sold":       _money(v["avg_sold"]),
-        "kpi_sold_psf":       _money(v["sold_psf"]),
-        "sold_comps_rows":    _sold_comps_rows(v.get("sold_comps", [])),
-        "asking_comps_tiles": _asking_comps_tiles(v.get("asking_comps", [])),
-
-        "area_headline":      a["headline"],
-        "kpi_crime":          a["crime_rating"],
-        "kpi_flood":          a["flood_risk"],
-        "kpi_band_d":         _money(a["council_tax_band_d"]),
-        "kpi_population":     f"{int(a['population']):,}",
-        "crime_rows":         _crime_rows(a.get("crime_breakdown", [])),
-        "band_rows":          _band_rows(a.get("council_tax_bands", [])),
-
-        "kpi_demand_rating":  d["demand_rating"],
-        "kpi_dom":            str(d["dom"]),
-        "kpi_turnover":       f"{int(d['turnover_pct'])}%",
-        "kpi_for_sale":       str(d["for_sale"]),
-        "spark_svg":          _spark_svg(d.get("growth_series", []), d.get("growth_psf_series", [])),
-
-        "rental_rating":      r["demand_rating"],
-        "rental_dom":         str(r["dom"]),
-        "rental_turnover":    f"{int(r['turnover_pct'])}%",
-        "rental_for_rent":    str(r["for_rent"]),
-
-        "type_dist_rows":     _type_dist_rows(d.get("type_dist", [])),
+        # page 2 — subject valuation
+        "kpi_subject_sqft":     subject_sqft,
+        "kpi_subject_sqft_sub": subject_sqft_sub,
+        "kpi_subject_beds":     str(subject.get("beds") or "—"),
+        "kpi_subject_epc":      subject_epc,
+        "kpi_subject_epc_sub":  subject_epc_sub,
+        "kpi_subject_type":     subject.get("type") or "—",
+        "kpi_subject_tenure":   subject.get("tenure") or "Tenure unknown",
+        "valuation_block":      _valuation_block(subject, v),
+        "subject_narrative":    subject.get("narrative") or "",
+
+        # page 3 — market context
+        "summary_headline":     ms["headline"],
+        "summary_paragraphs":   _summary_paragraphs(ms["paragraphs"]),
+        "kpi_avg_asking":       _money(v["avg_asking"]),
+        "kpi_avg_sold":         _money(v["avg_sold"]),
+        "kpi_psf":              _money(v["asking_psf"]),
+        "kpi_yoy":              yoy_str,
+        "demand_rating":        d["demand_rating"],
+        "gauge_position":       ms["demand_gauge_position"],
+        "price_growth_note":    ms["price_growth_note"],
+        "demand_note":          ms["demand_note"],
+        "spark_svg":            _spark_svg(d.get("growth_series", []), d.get("growth_psf_series", [])),
+
+        # page 4 — comparables
+        "sold_comps_rows":      _sold_comps_rows(v.get("sold_comps", [])),
+        "asking_comps_tiles":   _asking_comps_tiles(v.get("asking_comps", [])),
+
+        # page 5 — agent listings + sources
+        "agent_listings_cards": _agent_listings_cards(inputs["agent_listings"], out_dir),
     }
 
-    # Escape free-form text slots that aren't already HTML fragments.
-    text_slots = {"address", "postcode", "generated", "area_headline", "kpi_crime", "kpi_flood",
-                  "kpi_demand_rating", "rental_rating"}
+    # Escape only the plain-text slots; HTML fragments pass through untouched.
+    text_slots = {
+        "address", "address_short", "postcode", "generated",
+        "brand_name", "brand_tagline",
+        "kpi_subject_beds", "kpi_subject_epc", "kpi_subject_epc_sub",
+        "kpi_subject_sqft", "kpi_subject_sqft_sub",
+        "kpi_subject_type", "kpi_subject_tenure",
+        "summary_headline", "demand_rating",
+        "price_growth_note", "demand_note", "subject_narrative",
+    }
     for k in text_slots:
-        slots[k] = html.escape(slots[k])
+        slots[k] = html.escape(str(slots[k]))
 
     out = tmpl
     for k, val in slots.items():
@@ -187,7 +403,6 @@ def render(inputs: dict, out_dir: Path, template_path: Path | None = None) -> Pa
             "template has unfilled placeholders: " + ", ".join(sorted(set(leftovers)))
         )
 
-    out_dir.mkdir(parents=True, exist_ok=True)
     out_path = out_dir / "index.html"
     out_path.write_text(out)
     return out_path
@@ -212,11 +427,10 @@ _PAGE_OBJ_RE = re.compile(rb"/Type\s*/Page(?![sA-Za-z])")
 
 
 def _count_pages(pdf_path: Path) -> int:
-    """Prefer pdfinfo (handles compressed object streams); fall back to a
-    raw `/Type /Page` byte scan when pdfinfo is not installed. The fallback
-    is correct for current Chrome `--print-to-pdf` output (no `/ObjStm`)
-    but would silently undercount if a future Chrome switches to compressed
-    page-object streams — hence pdfinfo first when available.
+    """pdfinfo first (handles /ObjStm-compressed page-object streams), with a
+    raw /Type /Page byte scan as fallback. The fallback is correct for current
+    Chrome --print-to-pdf output but would undercount if Chrome ever switches
+    to compressed page-object streams — hence pdfinfo first when present.
     """
     pdfinfo = shutil.which("pdfinfo")
     if pdfinfo:
@@ -231,13 +445,6 @@ def _count_pages(pdf_path: Path) -> int:
 
 
 def assert_page_count(pdf_path: Path, expected: int) -> int:
-    """Assert PDF page count == expected; raise RuntimeError otherwise.
-
-    Synchronous and reliable — does not depend on Spotlight (`mdls` returns
-    `(null)` until indexing finishes, which is async). Operators can still
-    verify externally with `mdls -name kMDItemNumberOfPages <pdf>` once
-    Spotlight catches up.
-    """
     n = _count_pages(pdf_path)
     if n != expected:
         raise RuntimeError(
@@ -256,7 +463,7 @@ def main():
     base = inputs["filename_stem"]
     render(inputs, out_dir)
     pdf = render_pdf(out_dir, f"{base}.pdf")
-    pages = assert_page_count(pdf, 4)
+    pages = assert_page_count(pdf, 5)
     print(f"HTML  → {out_dir/'index.html'}")
     print(f"PDF   → {pdf} ({pages} pages)")