@rubytech/create-maxy-code 0.1.60 → 0.1.62

package/payload/platform/plugins/epc/mcp/src/lib/key-store.ts

@@ -0,0 +1,172 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { homedir } from "node:os";
+import { getSession } from "./neo4j.js";
+import { encrypt, decrypt } from "./crypto.js";
+import { encryptWith, decryptWith } from "./file-crypto.js";
+
+// Storage abstraction so the same MCP body runs against Neo4j (platform mode)
+// or an on-disk encrypted file (standalone mode, e.g. spawned by Claude Code
+// from ~/.claude/). Selected by the EPC_STANDALONE env flag at boot. Mirrors
+// the property-data key-store with one node per account: EPC keys are
+// account-scoped and the gov.uk EPC API has no team concept.
+
+export interface StoredKey {
+  apiKey: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface KeyStore {
+  readonly backendName: string;
+  readonly backendPath: string;
+  load(accountId: string): Promise<StoredKey | null>;
+  save(accountId: string, apiKey: string): Promise<void>;
+  delete(accountId: string): Promise<boolean>;
+}
+
+class Neo4jKeyStore implements KeyStore {
+  readonly backendName = "neo4j";
+  readonly backendPath = process.env.NEO4J_URI ?? "<unset>";
+
+  async load(accountId: string): Promise<StoredKey | null> {
+    const session = getSession();
+    try {
+      const result = await session.run(
+        `MATCH (k:EpcApiKey {accountId: $accountId})
+         RETURN k.encryptedKey AS encryptedKey,
+                k.createdAt AS createdAt,
+                k.updatedAt AS updatedAt`,
+        { accountId },
+      );
+      if (result.records.length === 0) return null;
+      const r = result.records[0];
+      return {
+        apiKey: decrypt(r.get("encryptedKey")),
+        createdAt: r.get("createdAt") ?? "",
+        updatedAt: r.get("updatedAt") ?? "",
+      };
+    } finally {
+      await session.close();
+    }
+  }
+
+  async save(accountId: string, apiKey: string): Promise<void> {
+    const encryptedKey = encrypt(apiKey);
+    const now = new Date().toISOString();
+    const session = getSession();
+    try {
+      await session.run(
+        `CREATE INDEX epc_api_key_account IF NOT EXISTS
+         FOR (k:EpcApiKey) ON (k.accountId)`,
+        {},
+      );
+      await session.run(
+        `MERGE (k:EpcApiKey {accountId: $accountId})
+         ON CREATE SET k.encryptedKey = $encryptedKey, k.createdAt = $now, k.updatedAt = $now
+         ON MATCH  SET k.encryptedKey = $encryptedKey, k.updatedAt = $now`,
+        { accountId, encryptedKey, now },
+      );
+    } finally {
+      await session.close();
+    }
+  }
+
+  async delete(accountId: string): Promise<boolean> {
+    const session = getSession();
+    try {
+      const result = await session.run(
+        `MATCH (k:EpcApiKey {accountId: $accountId})
+         DELETE k
+         RETURN count(k) AS deleted`,
+        { accountId },
+      );
+      const deleted = result.records[0]?.get("deleted")?.toNumber?.() ?? 0;
+      return deleted > 0;
+    } finally {
+      await session.close();
+    }
+  }
+}
+
+interface FileEnvelope {
+  [accountId: string]: { encryptedKey: string; createdAt: string; updatedAt: string };
+}
+
+const LABEL = "epc";
+
+class FileKeyStore implements KeyStore {
+  readonly backendName = "file";
+  readonly backendPath: string;
+  private readonly storePath: string;
+  private readonly keyFilePath: string;
+
+  constructor() {
+    const home = homedir();
+    this.storePath = resolve(home, ".claude/.realagent-epc-key.enc");
+    this.keyFilePath = resolve(home, ".claude/.realagent-epc-encryption-key");
+    this.backendPath = this.storePath;
+  }
+
+  private ensureDir(): void {
+    mkdirSync(dirname(this.storePath), { recursive: true });
+  }
+
+  private readAll(): FileEnvelope {
+    if (!existsSync(this.storePath)) return {};
+    const blob = readFileSync(this.storePath, "utf-8").trim();
+    if (!blob) return {};
+    const json = decryptWith(blob, this.keyFilePath, LABEL);
+    return JSON.parse(json) as FileEnvelope;
+  }
+
+  private writeAll(env: FileEnvelope): void {
+    this.ensureDir();
+    const blob = encryptWith(JSON.stringify(env), this.keyFilePath, LABEL);
+    writeFileSync(this.storePath, blob, { mode: 0o600 });
+  }
+
+  async load(accountId: string): Promise<StoredKey | null> {
+    const env = this.readAll();
+    const entry = env[accountId];
+    if (!entry) return null;
+    return {
+      apiKey: decryptWith(entry.encryptedKey, this.keyFilePath, LABEL),
+      createdAt: entry.createdAt,
+      updatedAt: entry.updatedAt,
+    };
+  }
+
+  async save(accountId: string, apiKey: string): Promise<void> {
+    const env = this.readAll();
+    const now = new Date().toISOString();
+    const encryptedKey = encryptWith(apiKey, this.keyFilePath, LABEL);
+    const prev = env[accountId];
+    env[accountId] = {
+      encryptedKey,
+      createdAt: prev?.createdAt ?? now,
+      updatedAt: now,
+    };
+    this.writeAll(env);
+  }
+
+  async delete(accountId: string): Promise<boolean> {
+    const env = this.readAll();
+    if (!(accountId in env)) return false;
+    delete env[accountId];
+    this.writeAll(env);
+    return true;
+  }
+}
+
+let cached: KeyStore | null = null;
+
+export function selectKeyStore(): KeyStore {
+  if (cached) return cached;
+  cached = process.env.EPC_STANDALONE === "1" ? new FileKeyStore() : new Neo4jKeyStore();
+  return cached;
+}
+
+export function _resetKeyStoreForTests(): void {
+  cached = null;
+}

package/payload/platform/plugins/epc/mcp/src/lib/neo4j.ts

@@ -0,0 +1,47 @@
+import neo4j, { Driver, Session } from "neo4j-driver";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+let driver: Driver | null = null;
+
+function readPassword(): string {
+  if (process.env.NEO4J_PASSWORD) return process.env.NEO4J_PASSWORD;
+  const passwordFile = resolve(
+    process.env.PLATFORM_ROOT ?? resolve(import.meta.dirname, "../../../.."),
+    "config/.neo4j-password",
+  );
+  try {
+    return readFileSync(passwordFile, "utf-8").trim();
+  } catch {
+    throw new Error(
+      `Neo4j password not found. Expected at ${passwordFile} or in NEO4J_PASSWORD env var.`,
+    );
+  }
+}
+
+export function getDriver(): Driver {
+  if (!driver) {
+    const uri = process.env.NEO4J_URI;
+    if (!uri) {
+      throw new Error(
+        "[epc] NEO4J_URI unset — refusing to default to bolt://localhost:7687",
+      );
+    }
+    const user = process.env.NEO4J_USER ?? "neo4j";
+    const password = readPassword();
+    console.error(`[epc] resolved neo4j_uri=${uri}`);
+    driver = neo4j.driver(uri, neo4j.auth.basic(user, password));
+  }
+  return driver;
+}
+
+export function getSession(): Session {
+  return getDriver().session();
+}
+
+export async function closeDriver(): Promise<void> {
+  if (driver) {
+    await driver.close();
+    driver = null;
+  }
+}

package/payload/platform/plugins/epc/mcp/src/tools/key-deregister.ts

@@ -0,0 +1,9 @@
+import { selectKeyStore } from "../lib/key-store.js";
+
+export async function keyDeregister(params: { accountId: string }): Promise<void> {
+  const deleted = await selectKeyStore().delete(params.accountId);
+  if (!deleted) {
+    throw new Error("No EPC API key is registered for this account.");
+  }
+  console.error(`[epc] key-op op=deregister account=${params.accountId}`);
+}

package/payload/platform/plugins/epc/mcp/src/tools/key-list.ts

@@ -0,0 +1,10 @@
+import { loadAccountKey } from "../lib/epc-api.js";
+
+export async function keyList(params: { accountId: string }): Promise<string> {
+  const key = await loadAccountKey(params.accountId);
+  console.error(`[epc] key-op op=list account=${params.accountId}`);
+  if (!key) {
+    return "No EPC API key registered. Use epc-key-register to add one.";
+  }
+  return `EPC API key registered (created: ${key.createdAt}, updated: ${key.updatedAt}). Key value is encrypted and cannot be retrieved.`;
+}

package/payload/platform/plugins/epc/mcp/src/tools/key-register.ts

@@ -0,0 +1,44 @@
+import { selectKeyStore } from "../lib/key-store.js";
+import { BASE_URL, REQUEST_TIMEOUT_MS, EpcError } from "../lib/epc-api.js";
+
+// Probe the EPC register with the supplied credential against
+// /domestic/search constrained to a tiny page so we do not pull a real
+// payload. A valid credential returns HTTP 200 (rows may be empty for a
+// nonsense postcode, which is fine — authentication is what we test).
+// An invalid credential returns HTTP 401 Unauthorized.
+
+async function validateApiKey(credential: string): Promise<void> {
+  const url = `${BASE_URL}/domestic/search?postcode=SW1A1AA&size=1`;
+  const response = await fetch(url, {
+    headers: {
+      Accept: "application/json",
+      Authorization: `Basic ${Buffer.from(credential, "utf-8").toString("base64")}`,
+    },
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  });
+  if (response.status === 401 || response.status === 403) {
+    throw new Error(
+      `EPC register rejected the credential (HTTP ${response.status}). Expected format is email:api-key.`,
+    );
+  }
+  // 200, 404 (no rows for that postcode), and 200-with-rows all prove the
+  // credential was accepted. Anything else surfaces as the upstream code.
+  if (response.status === 200 || response.status === 404) return;
+  const body = await response.text().catch(() => "");
+  throw new EpcError(response.status, "domestic/search", body.slice(0, 200));
+}
+
+export async function keyRegister(params: {
+  apiKey: string;
+  accountId: string;
+}): Promise<void> {
+  const { apiKey, accountId } = params;
+  if (!apiKey.includes(":")) {
+    throw new Error(
+      "EPC credential must be in the form email:api-key (email of the account that generated the key, then a colon, then the API key).",
+    );
+  }
+  await validateApiKey(apiKey);
+  await selectKeyStore().save(accountId, apiKey);
+  console.error(`[epc] key-op op=register account=${accountId}`);
+}

package/payload/platform/plugins/epc/mcp/src/tools/lookup.ts

@@ -0,0 +1,43 @@
+import { epcSearch, groupAndPickMostRecent, EpcMatch } from "../lib/epc-api.js";
+
+interface LookupResult {
+  status: "ok";
+  matches: EpcMatch[];
+}
+
+export async function epcLookupByAddress(args: {
+  accountId: string;
+  address: string;
+  postcode?: string;
+}): Promise<string> {
+  const { accountId, address, postcode } = args;
+  const { rows } = await epcSearch({
+    toolName: "epc-lookup-by-address",
+    accountId,
+    identifier: address,
+    params: { address, postcode, size: 25 },
+  });
+  const result: LookupResult = {
+    status: "ok",
+    matches: groupAndPickMostRecent(rows),
+  };
+  return JSON.stringify(result, null, 2);
+}
+
+export async function epcLookupByUprn(args: {
+  accountId: string;
+  uprn: string;
+}): Promise<string> {
+  const { accountId, uprn } = args;
+  const { rows } = await epcSearch({
+    toolName: "epc-lookup-by-uprn",
+    accountId,
+    identifier: uprn,
+    params: { uprn, size: 25 },
+  });
+  const result: LookupResult = {
+    status: "ok",
+    matches: groupAndPickMostRecent(rows),
+  };
+  return JSON.stringify(result, null, 2);
+}

package/payload/platform/plugins/epc/mcp/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src"],
+  "exclude": ["src/**/__tests__/**", "src/**/*.test.ts"]
+}

package/payload/platform/plugins/epc/mcp/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/**/__tests__/**/*.test.ts"],
+    environment: "node",
+  },
+});

package/payload/platform/plugins/preval/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "real-agent-preval",
-  "description": "Single-address pre-valuation pack. One full UK address in, 4-page A4 PDF out (cover · valuation · area · demand+trend+sources). Consumes the real-agent-property-data MCP — no MCP tools of its own.",
+  "description": "Single-address pre-valuation pitch pack. One full UK address in, 5-page A4 PDF out (cover · subject valuation · market context · comparables · recently with <brand>). Consumes the real-agent-property-data and real-agent-epc MCPs — no MCP tools of its own.",
   "version": "0.1.0",
   "author": {
     "name": "Rubytech LLC"

package/payload/platform/plugins/preval/PLUGIN.md

@@ -1,6 +1,6 @@
 ---
 name: real-agent-preval
-description: "Single-address pre-valuation pack. One full UK address in, 4-page A4 PDF out (cover · valuation · area · demand+trend+sources). Consumes the real-agent-property-data MCP — no MCP tools of its own."
+description: "Single-address pre-valuation pitch pack. One full UK address in, 5-page A4 PDF out (cover · subject valuation · market context · comparables · recently with <brand>). Consumes the real-agent-property-data and real-agent-epc MCPs — no MCP tools of its own."
 skills:
   - skills/property-preval/SKILL.md
 always: false
@@ -9,31 +9,39 @@ metadata: {"platform":{"optional":true,"embed":["admin"]}}
 
 # Real Agent — Preval
 
-Consumer sub-plugin. No MCP server, no new tools — only a skill (`property-preval`) that takes one full UK address and renders a 4-page A4 pre-valuation PDF by fanning out to 12 of the 22 `real-agent-property-data` MCP tools.
+Consumer sub-plugin. No MCP server, no new tools — only a skill (`property-preval`) that takes one full UK address plus operator-supplied brand tokens, subject details, agent listings, and a market summary, and renders a **5-page A4 pre-valuation PDF** designed as a sales pitch for the listing.
 
 ## What it produces
 
-A 4-page A4 PDF and the source HTML, written to `~/Documents/Maxy/preval/<postcode>-<YYYY-MM-DD>/`:
+A 5-page A4 PDF and the source HTML, written to `~/Documents/Maxy/preval/<postcode-compact>-<YYYY-MM-DD>/`:
 
-- **Page 1 — Cover.** Full address, postcode chip, generated-date meta strip.
-- **Page 2 — Valuation.** Average asking £, asking £/sqft, sold avg £, sold £/sqft. Nearest-sold comps table. Live asking comps grid.
-- **Page 3 — Area.** Crime rating, flood risk, council-tax band D cost, local area population. Crime breakdown panel + council-tax band table. Headline read.
-- **Page 4 — Demand, trend, sources.** Demand rating, days-on-market, turnover, for-sale count. 7y growth sparkline (£ and £/sqft). Rental-side mini-panel. Property-types doughnut. Sources/methodology block.
+- **Page 1 — Cover.** Full-bleed subject hero photo with gradient scrim. Light brand wordmark top-left. Address in display-italic. Postcode chip. Four-up meta strip (Report · Address · Postcode · Generated). Lifted from the `property-market-report` cover contract.
+- **Page 2 — Subject valuation.** KPI strip (floor area, bedrooms, EPC rating, type). Valuation panel: headline range = `subject.sqft × sold £/sqft 70pc band` (Land Registry), asking £/sqft cross-check, operator adjustments (`subject.adjustments[]`) shown as a stacked list with colour-coded percentages, final indicative range pill. `subject.sqft` is required — a null value aborts the run.
+- **Page 3 — Market context.** Market summary headline + paragraphs with drop cap. KPI strip (avg asking £, avg sold £, £/sqft). Price-growth panel (YoY) + demand pill with gauge. 7-year sparkline of £ and £/sqft. Same patterns as `property-market-report`.
+- **Page 4 — Comparables.** Full-width Land Registry sold-transactions table (≤ 6 rows), stacked above a full-width live-asking-comparables tile grid (≤ 4 tiles). Never side-by-side — corrects the cramped two-column layout in v1 preval.
+- **Page 5 — Recently with `<brand>` + sources.** Operator-curated `agent_listings[]` rendered as a clickable tile grid with status badges (Sold / Under offer / For sale), then the sources & methodology block. The vendor reads this page and knows who to call.
 
-## How the address routes
+## Tool dependencies
 
-The skill derives the postcode from the address (UK-postcode regex on the final token group), then fans out to **12** `real-agent-property-data` MCP tools in fixed call order:
+The skill fans out to **13** MCP calls in parallel:
 
-`prices`, `prices-per-sqf`, `sold-prices`, `sold-prices-per-sqf`, `growth`, `growth-psf`, `demand`, `demand-rent`, `property-types`, `crime`, `flood-risk`, `council-tax`.
+- **12 PropertyData** tools (postcode-keyed): `prices`, `prices-per-sqf`, `sold-prices`, `sold-prices-per-sqf`, `growth`, `growth-psf`, `demand`, `demand-rent`, `property-types`, `crime`, `flood-risk`, `council-tax`.
+- **1 EPC** tool (address-keyed): `epc-lookup-by-address` for subject floor area + energy rating + lodgement date.
 
-Two tools from the same MCP are **deliberately not called** by this skill:
+`property-data-address-match-uprn` and `property-data-planning-applications` are deliberately not called (CRM hygiene and dev-precedent reports, respectively).
 
-- `property-data-address-match-uprn` — UPRN is CRM hygiene, not preval data.
-- `property-data-planning-applications` — planning is a separate dev-precedent report.
+## Failure handling
 
-Operators can still reach those tools via the underlying `property-data` skill or directly through the MCP.
+Every failure is fail-loud. The skill emits `[preval] aborted reason=<cause> …` and exits 2; no partial `index.html` or PDF is left on disk.
 
-## Dependencies
+- **PropertyData `key-not-registered`** → abort `reason=property-data-key-not-registered` with the `property-data-key-register` remediation hint.
+- **PropertyData `http-429`** → back off and retry the single throttled tool once. A second `http-429` aborts `reason=property-data-rate-limited`.
+- **PropertyData `http-5xx` / network failure** → abort `reason=property-data-unavailable`.
+- **EPC failure of any kind** — `key-not-registered`, `http-404 (no record)`, `http-429`, `http-5xx`, network failure, EPC MCP not configured — aborts the run. There is no in-band prompt and no benchmark-only mode. The operator's options before re-running are (a) run Task 155 to deploy / register the EPC MCP, or (b) paste `subject.sqft` and `subject.sqft_m2` into the inputs as a deliberate operator override.
+- See `skills/property-preval/SKILL.md` § Hard breakpoints for the full table of abort causes.
 
-- Requires `real-agent-property-data` enabled on the account with a registered PropertyData API key (`property-data-key-register`). Without a key every fan-out call returns `Error: key-not-registered` and the renderer raises before producing a PDF.
-- Requires Google Chrome at `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome` (mac, headless `--print-to-pdf`). Same Chrome dependency as `property-market-report`.
+## External dependencies
+
+- Requires `real-agent-property-data` enabled on the account with a registered PropertyData API key (`property-data-key-register`).
+- Requires `real-agent-epc` enabled with a registered EPC API key (`epc-key-register`), **or** an operator-supplied `subject.sqft` + `subject.sqft_m2` override pre-baked into the inputs. EPC failures are not silently absorbed.
+- Requires Google Chrome at `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome` for headless `--print-to-pdf`. Same Chrome dependency as `property-market-report`.

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

@@ -1,78 +1,146 @@
 ---
 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`. Both are required. If EPC has no record (pre-2008 property never sold or let; Scotland/NI; unmatched), the operator pastes `subject.sqft` directly **before invocation** as a deliberate override. There is no mid-run paste prompt and no benchmark-only render — a null `sqft` aborts the run with `reason=subject-sqft-missing`.
+- **`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. One paragraph of `subject.narrative` under the panel. `sqft` is required — a null value aborts the run, never renders a benchmark-only 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. Every failure is fail-loud — no mid-run paste prompts, no benchmark-only render, no degraded pack on disk:
+   - **PropertyData `key-not-registered`** → abort `reason=property-data-key-not-registered` with the `property-data-key-register` remediation hint.
+   - **PropertyData `http-429`** → back off and retry the single throttled tool **once**. A second `http-429` aborts `reason=property-data-rate-limited`.
+   - **PropertyData `http-5xx` / network failure** → abort `reason=property-data-unavailable`.
+   - **EPC failure of any kind** — `key-not-registered`, `http-404 (no record on file)`, `http-429`, `http-5xx`, network failure, or MCP not configured on the account — aborts the run. The operator's options before re-running are (a) run Task 155 to deploy / register the EPC MCP, or (b) paste `subject.sqft` (plus `subject.sqft_m2`) into the inputs as a deliberate operator override. There is no in-band prompt and no benchmark-only mode.
+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.
+
+## Adjustments — linear vs compound
+
+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
 
-Emit at start: `[preval] start address="<addr>" postcode=<pc>`.
-Emit at done:  `[preval] done pdf=<path> pages=<n> ms=<n>`.
+- `[preval] start address="<addr>" postcode=<pc>` at run start.
+- `[preval] done pdf=<path> pages=<n> ms=<n>` at run end.
+- `[preval] aborted reason=<cause> address="<addr>" postcode=<pc> ms=<n>` on any abort (one line, then exit 2; no `done`).
+- 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).
+
+## Hard breakpoints
+
+Each row aborts the run with the named cause. No PDF or `index.html` is left on disk. Operator sees a single-line cause + one-line remediation hint, nothing else.
+
+| Forbidden state | `reason=` cause |
+|---|---|
+| EPC MCP not configured / `key-not-registered` / `http-5xx` / network error | `epc-mcp-unavailable` (operator must run Task 155 or paste `subject.sqft` before invocation) |
+| `subject.sqft` null after EPC lookup | `subject-sqft-missing` |
+| `subject.sqft_m2` null | `subject-sqft-m2-missing` |
+| `subject.cover_hero` missing, unreachable, below 1200×800, or symlinked into another property's folder | `subject-cover-hero-missing` / `subject-cover-hero-unreadable` / `subject-cover-hero-too-small` / `subject-cover-hero-symlinked-foreign` |
+| `brand` not resolved from an on-disk `DESIGN.md` (required token missing) | `brand-unresolved` |
+| `agent_listings` empty | `agent-listings-empty` |
+| `market_summary.paragraphs` < 2 entries | `market-summary-too-thin` |
+| PropertyData any-call `http-429` after 1 retry | `property-data-rate-limited` |
+| PropertyData any-call `key-not-registered` | `property-data-key-not-registered` (operator runs `property-data-key-register`) |
+| EPC lookup returns `http-404` (no record on file) | `epc-no-record` (operator pastes `subject.sqft` as override and re-runs, or accepts that this address can't be preval'd until lodged) |
+
+## Forbidden behaviours
+
+The skill is the contract; if any of these slip through, the pack must not render:
 
-Each of the 12 fan-out calls produces its own `[property-data] tool=<name>` line in `server.log` (inherited contract — no new instrumentation).
+- Silent fallback selection — switching to a benchmark-only / "Estimate requires floor area" panel when an input is missing.
+- Inventing inputs — fabricating `brand`, `subject.cover_hero`, `market_summary.paragraphs`, `agent_listings`, or any field the operator did not supply.
+- Reusing a hero photo from a different property as a placeholder.
+- Defaulting `agent_listings[].status` to `"For sale"` when the source is null.
+- Mid-run prompts for a paste-in (EPC retries, sqft, etc). Overrides are operator-supplied **before** invocation.
+- Omitting the `[preval]` start / done / aborted log emissions.
+- Leaving partial output (`index.html`, `<stem>.pdf`) on disk after an abort.
 
-## Failure signatures
+## Failure diagnostics
 
-- `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.
-- `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`).
+- `pages=6` (or ≠ 5) in the `done` line → template overflow on one page. Diagnose with `pdftoppm -png -f <n> -l <n> <pdf>`, then trim that panel's padding only.
+- `start` with no matching `done` or `aborted` within 60s → renderer crashed mid-run. Inspect with `grep -B2 -A20 '\[preval\] start address="<echoed>"' server.log`.
+- `[preval] aborted reason=<cause>` → look up `<cause>` in the **Hard breakpoints** table for the remediation hint.
 
 ## 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.