npm - @rubytech/create-maxy-code - Versions diffs - 0.1.111 → 0.1.113 - Mend

@rubytech/create-maxy-code 0.1.111 → 0.1.113

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (54) hide show

package/payload/platform/plugins/venture-studio/skills/prototype-host/references/scaffold-frameworks.md ADDED Viewed

@@ -0,0 +1,60 @@
+# Framework scaffolders, dev-server commands, and port overrides
+Five frameworks supported. Each row gives the exact command set the prototype-host skill runs in phases 2 and 5.
+## Selection defaults
+| Surface intent | Default framework | Reason |
+|---|---|---|
+| `landing` | `static` | One HTML file rendered from `01-narrative/LANDING.md` is faster to ship and faster to load than a Vite bundle. Lighthouse-clean by construction. |
+| `prototype` | `vite` | Vue/React/Svelte all supported; HMR is the founder's iteration loop. |
+If the operator names a framework explicitly, use that. Otherwise these defaults stand.
+## `static`
+No scaffolder. The skill writes a single `index.html` directly into `<surface-dir>/` from `01-narrative/LANDING.md`, with brand tokens inlined into `<style>` in the `<head>`.
+- **Build:** none (raw HTML); for a `dist/` build (if the operator adds Tailwind etc later) the skill respects `<surface-dir>/dist/` if present.
+- **Serve:** `cloudflared file-server --port <port> <surface-dir>` (or `<surface-dir>/dist` if a build directory exists).
+- **Port override:** `--port <port>` on `cloudflared file-server`.
+## `vite`
+- **Scaffold:** `cd <surface-dir-parent> && npm create vite@latest <surface-name> -- --template vanilla-ts -- --yes`. The agent prompts the operator before this if they want a non-vanilla template (`react-ts`, `svelte-ts`, `vue-ts`); otherwise `vanilla-ts` is the default — the founder can rewrite `index.html` + `src/main.ts` to anything from there.
+- **Install:** `cd <surface-dir> && npm install`
+- **Build:** `npm run build` (outputs to `<surface-dir>/dist/`)
+- **Dev server:** `npm run dev -- --port <port> --host 127.0.0.1`
+- **Port override:** `--port <port>` (Vite respects the flag; `PORT=` is ignored).
+## `next`
+- **Scaffold:** `cd <surface-dir-parent> && npx -y create-next-app@latest <surface-name> --typescript --app --tailwind --eslint --src-dir --import-alias "@/*" --use-npm --yes`
+- **Install:** scaffolder runs `npm install` automatically.
+- **Build:** `npm run build`
+- **Dev server:** `npm run dev -- -p <port> -H 127.0.0.1`
+- **Port override:** `-p <port>` (Next.js dev/start respect the flag; `PORT=` also works but `-p` is explicit).
+## `sveltekit`
+- **Scaffold:** `cd <surface-dir-parent> && npx -y sv create <surface-name> --template minimal --types ts --no-add-ons --install npm`
+- **Install:** scaffolder runs `npm install` automatically when `--install npm` is passed.
+- **Build:** `npm run build`
+- **Dev server:** `npm run dev -- --port <port> --host 127.0.0.1`
+- **Port override:** `--port <port>`.
+## `astro`
+- **Scaffold:** `cd <surface-dir-parent> && npm create astro@latest <surface-name> -- --template minimal --typescript strict --install --no-git --yes`
+- **Install:** scaffolder runs `npm install` when `--install` is passed.
+- **Build:** `npm run build` (outputs to `<surface-dir>/dist/`)
+- **Dev server:** `npm run dev -- --port <port> --host 127.0.0.1`
+- **Port override:** `--port <port>`.
+## Why `--host 127.0.0.1`
+Every dev server above binds to `127.0.0.1`, not `0.0.0.0`. Cloudflared connects to the loopback address; binding to `0.0.0.0` would expose the dev server on the install device's LAN address, which is unwanted (LAN clients should reach the prototype through the tunnel, not directly).
+## Why no `--yes` on `create-next-app` interactive prompts in older versions
+`create-next-app@latest` (≥14.2) treats all listed flags as the answer set and runs non-interactively. If a flag is omitted it falls back to a TTY prompt — fatal under the agent's non-TTY Bash invocation. Always pass every flag the table lists.

package/payload/platform/plugins/venture-studio/skills/prototype-host/references/systemd-user-service.md ADDED Viewed

@@ -0,0 +1,104 @@
+# Systemd user unit template for a hosted prototype surface
+One unit per hosted surface: `${HOME}/.config/systemd/user/${BRAND}-prototype-<surface>.service`.
+Two flavours: dev-server mode (frameworks with hot-reload) and static file-server mode (raw HTML or built `dist/`).
+## Dev-server mode (vite, next, sveltekit, astro)
+```ini
+[Unit]
+Description=${BRAND} prototype surface <surface> — <framework> dev server
+After=network.target
+[Service]
+Type=simple
+WorkingDirectory=<surface-dir>
+Environment="PORT=<port>"
+Environment="NODE_ENV=development"
+ExecStart=/usr/bin/env npm run dev -- <framework-port-flag> <port> --host 127.0.0.1
+Restart=on-failure
+RestartSec=3
+StandardOutput=journal
+StandardError=journal
+[Install]
+WantedBy=default.target
+```
+`<framework-port-flag>` is the per-framework override from [`scaffold-frameworks.md`](scaffold-frameworks.md): `--port` for Vite/SvelteKit/Astro, `-p` for Next.
+## Static file-server mode
+For the `static` framework (raw HTML rendered from `LANDING.md`):
+```ini
+[Unit]
+Description=${BRAND} prototype surface <surface> — static file server
+After=network.target
+[Service]
+Type=simple
+WorkingDirectory=<surface-dir>
+ExecStart=/usr/local/bin/cloudflared file-server --port <port> --address 127.0.0.1 <surface-dir>
+Restart=on-failure
+RestartSec=3
+StandardOutput=journal
+StandardError=journal
+[Install]
+WantedBy=default.target
+```
+If `<surface-dir>/dist/` exists (the founder added a build step later), point `ExecStart`'s last arg at `<surface-dir>/dist` instead of `<surface-dir>`. The skill detects this automatically with `[ -d <surface-dir>/dist ] && SERVE_DIR=<surface-dir>/dist || SERVE_DIR=<surface-dir>`.
+## Why a user unit, not a root unit
+The brand cloudflared connector already runs as a `systemctl --user` unit ([`platform/plugins/cloudflare/references/reset-guide.md`](../../../../../platform/plugins/cloudflare/references/reset-guide.md)). Keeping prototype units in the same scope means:
+- Same `journalctl --user` namespace — the operator reads one log namespace, not two.
+- No `sudo` required to install, enable, or restart.
+- `loginctl enable-linger <user>` (already set by the installer) survives reboot — units come back without an SSH session.
+Root units would also work, but split the operator's mental model and require `sudo` for every restart. Not worth the tradeoff for a per-prototype surface.
+## Enabling and starting
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now "${BRAND}-prototype-<surface>.service"
+# Verify it stayed up.
+systemctl --user is-active "${BRAND}-prototype-<surface>.service"
+# If not active, dump the journal and surface verbatim.
+if [ "$(systemctl --user is-active "${BRAND}-prototype-<surface>.service")" != "active" ]; then
+  journalctl --user -u "${BRAND}-prototype-<surface>.service" -n 50 --no-pager >&2
+  exit 1
+fi
+```
+## Re-run after edit
+If the skill regenerates the unit file (e.g. the port changed, or the static surface gained a `dist/` directory), the sequence is:
+```bash
+systemctl --user daemon-reload
+systemctl --user restart "${BRAND}-prototype-<surface>.service"
+```
+`daemon-reload` is required after any unit-file edit; `restart` picks up the new `ExecStart`.
+## Why `Restart=on-failure`, not `always`
+Dev servers exit 0 in legitimate cases (the operator killed `npm run dev` from another shell to apply a config edit). `on-failure` respects those exits; `always` would fight them.
+## Logging
+All output (stdout + stderr from the dev server / file server) goes to the user journal. Read with:
+```bash
+journalctl --user -u "${BRAND}-prototype-<surface>.service" -f
+```
+No file-based log rotation needed — systemd handles journal rotation.

package/payload/platform/plugins/venture-studio/skills/zero-to-prototype/SKILL.md CHANGED Viewed

@@ -284,6 +284,10 @@ For go-to-market planning:
 4. **Progress over perfection** — Ship, measure, iterate
 5. **Synthesis over summary** — Connect dots, don't just list facts
+## Research routing
+Customer-discovery prior-art lookups, prospect-finding (`references/boolean-search.md` invocations, Earlyvangelist identification), citation-backed claims (PMF benchmarks, market signal precedents), and academic-grade evidence all route through the `research-assistant` specialist with the `deep-research`, `data-research`, and `academic-verify` skills. Dispatch the specialist; do not call `WebSearch` or `WebFetch` directly from this skill. The specialist returns structured findings with citations the PMF, Landing, and PRD artefacts can quote.
 ## Framework Reference Files
 All frameworks are in `references/` directory:

package/payload/platform/templates/agents/public/IDENTITY.md CHANGED Viewed

@@ -31,7 +31,17 @@ A landfill graph defeats EVIDENCE-BASED: search returns noise, the agent re-writ
 ## Visual content
-Images may be available at `/brand/` — these are visual assets the business has prepared. When your knowledge lists an image and a visitor's question is relevant to it, embed it inline using standard markdown: `![description](/brand/filename)`. The visitor sees the image directly in the conversation. Only reference images explicitly listed in your knowledge — never guess or fabricate filenames. When a relevant image exists, show it rather than describing what you could show.
+Two sources of inline images are permitted, and only these two:
+1. **Brand images at `/brand/`** — visual assets the business has prepared. When your knowledge lists an image and a visitor's question is relevant to it, embed it inline using standard markdown: `![description](/brand/filename)`. Only reference images explicitly listed in your knowledge — never guess or fabricate filenames.
+2. **`:ImageObject` URLs returned by `memory-search`** — when a memory-search result includes `:ImageObject` neighbours on its `related` set (e.g. a `:Listing` returned with its `:DEPICTS`-linked images), the `url` field of those neighbours is permitted as an inline image source: `![<ImageObject.description>](<ImageObject.url>)`. Use the ImageObject's own `description` as the alt text; never substitute placeholder alt text. Only embed URLs returned by memory-search in this turn — do not cache, reuse across turns from memory, or compose URLs from slugs.
+No other external image embedding is permitted. The visitor sees the image directly in the conversation. When a relevant image exists, show it rather than describing what you could show.
+### No fabrication on graph-backed content
+When you relay graph-backed entities to a visitor — listings, prices, addresses, image content, anything sourced from `memory-search` — every field in the reply must trace to a property on a node the search just returned. If memory-search returns zero matches for the visitor's intent, say so plainly in one sentence. Never invent a listing, a price, a room photo, or a feature to fill the gap. Run the same intent three times and the no-match reply must stay consistent in meaning — the visitor's experience is the audit.
 ## Boundaries

package/payload/premium-plugins/real-agent/BUNDLE.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: real-agent
-description: "UK estate agency skills + Loop CRM + PropertyData market analytics + single-address preval — 12 sub-plugins covering sales, listings, vendor management, buyer management, lead generation, coaching, business operations, teaching, Loop CRM, PropertyData, property brochures, and preval. 3 specialist roles (negotiator, valuer, compliance). 34 skills + 45 MCP tools."
+description: "UK estate agency skills + Loop CRM + PropertyData market analytics + single-address preval — 12 sub-plugins covering sales, listings, vendor management, buyer management, lead generation, coaching, business operations, teaching, Loop CRM, PropertyData, property brochures, and preval. 4 specialist roles (negotiator, valuer, compliance, listing-curator). 34 skills + 45 MCP tools."
 plugins:
   - estate-sales
   - listings
@@ -18,7 +18,7 @@ plugins:
 # Real Agent
-Premium plugin bundle for UK estate agency professionals. Shipped on every non-Maxy brand install (today: Real Agent); Maxy installs do not receive it. All 12 sub-plugins ship as a set, each independently activatable via `enabledPlugins`. Every admin boot walks every bundle under `premium-plugins/` (brand-gated — Maxy short-circuits) and reconciles `account.json` `enabledPlugins` against on-disk presence: any sub-plugin from the `plugins:` list above whose `platform/plugins/<sub>/PLUGIN.md` exists gets stamped via an idempotent set-union, so `mcp__loop__*` tools and the other sub-plugin surfaces are visible to the admin agent from the first turn after install — and on first boot post-deploy for accounts that already had the bundle on disk from a prior install. Disable individual sub-plugins with `plugin-toggle-enabled`. The bundle also delivers three specialist roles (negotiator, valuer, and compliance) that embed domain knowledge from the sub-plugins and operate autonomously with Loop CRM tools.
+Premium plugin bundle for UK estate agency professionals. Shipped on every non-Maxy brand install (today: Real Agent); Maxy installs do not receive it. All 12 sub-plugins ship as a set, each independently activatable via `enabledPlugins`. Every admin boot walks every bundle under `premium-plugins/` (brand-gated — Maxy short-circuits) and reconciles `account.json` `enabledPlugins` against on-disk presence: any sub-plugin from the `plugins:` list above whose `platform/plugins/<sub>/PLUGIN.md` exists gets stamped via an idempotent set-union, so `mcp__loop__*` tools and the other sub-plugin surfaces are visible to the admin agent from the first turn after install — and on first boot post-deploy for accounts that already had the bundle on disk from a prior install. Disable individual sub-plugins with `plugin-toggle-enabled`. The bundle also delivers four specialist roles (negotiator, valuer, compliance, listing-curator) that embed domain knowledge from the sub-plugins and operate autonomously with Loop CRM and memory tools.
 ## Specialist Roles
@@ -27,6 +27,7 @@ Premium plugin bundle for UK estate agency professionals. Shipped on every non-M
 | Negotiator | `agents/negotiator.md` | All Loop CRM tools + memory-search | Buyer pipeline, viewings, feedback, offers, deal progression |
 | Valuer | `agents/valuer.md` | Loop property/people tools + memory-search | Market appraisal preparation, comparable evidence analysis |
 | Compliance | `agents/compliance.md` | All Loop CRM tools + memory-search + perplexity-search | UK estate agency law, listing audit, AML/KYC, regulatory compliance |
+| Listing Curator | `agents/listing-curator.md` | memory-search + memory-write + memory-update + memory-image-fetch + Loop property/team tools | Ingestion of property listings into typed `:Listing` nodes — maps Loop CRM records, published zip-site directories, and manual operator dumps to renderable graph entities so the public agent can surface them as property cards. Also writes one `:ImageObject` per Listing image (vision-LLM description + closed-set tags) so the public-side recommender can pick contextually rather than always emitting the hero. |
 ## Sub-Plugins

package/payload/premium-plugins/real-agent/agents/listing-curator.md ADDED Viewed

@@ -0,0 +1,152 @@
+---
+name: listing-curator
+description: "Property listing ingestion. Maps any property-shaped input — a Loop CRM record, a published zip-site directory, or a manual operator dump — to one typed :Listing node that the public agent's memory-search can return as a renderable property card. Delegate when a property listing needs to enter the graph, when an existing Listing's status drifts (for-sale → under-offer → sold), or when a hosted property site has been published and the graph has no record of it yet."
+summary: "Your listing curator — maps property inputs to typed :Listing nodes that visitor-facing chat can render."
+model: claude-sonnet-4-6
+tools: mcp__memory__memory-search, mcp__memory__memory-write, mcp__memory__memory-update, mcp__memory__image-fetch, mcp__loop__loop-property-search, mcp__loop__loop-property-detail, mcp__loop__loop-property-listed, mcp__loop__loop-property-sold, mcp__loop__loop-key-list, mcp__loop__loop-team-info
+---
+# Listing Curator
+You are the listing curator. You own one outcome: any property-shaped input that crosses the realagent boundary leaves the graph as a `:Listing` node carrying the renderable contract from `schema-estate-agent.md`. Generic ingestion specialists (`database-operator`) and hosting flows are not allowed to mint property data — that work routes here so the doctrine is enforced in one place.
+You receive a brief from the admin agent. You read the source, map it field-by-field, and write the Listing. You return the new `:Listing`'s `slug` and the action you took (`create` / `update` / `no-op`).
+## Outcome contract
+For every property-shaped input the curator returns one `:Listing` node satisfying `schema-estate-agent.md`'s required-property set, idempotent on `(accountId, sourceSystem, sourceId)`. The Listing always carries the parent edge `(:Listing)-[:LISTED_BY]->(:LocalBusiness)` naming the estate agency; when a structural `:Property` node is known, additionally `(:Listing)-[:FOR_PROPERTY]->(:Property)`.
+Three legal action outcomes:
+- **`create`** — no Listing existed at `(accountId, sourceSystem, sourceId)`; one was written.
+- **`update`** — a Listing existed; its mutable fields were refreshed (status, price, blurb, images, lastVerifiedAt). The `slug`, `sourceSystem`, and `sourceId` are immutable on update.
+- **`no-op`** — the source record could not be mapped to a complete Listing (see "Source rejection" below). No write occurred. The brief is returned to the admin agent with an explanation.
+Anything else — emitting a `:KnowledgeDocument` instead of a `:Listing`, leaving renderable fields null on a `for-sale` listing, creating a second Listing for a re-ingested source record — is a defect.
+## Source mapping
+### Loop CRM record → Listing
+The Loop CRM record format you receive (either piped in by the brief or fetched via `mcp__loop__loop-property-detail`) carries a flat `body` text plus structured `loopPropertyId`. Parse with these rules:
+| Listing field | Source |
+|---|---|
+| `accountId` | inherited from the curator's session env |
+| `slug` | derived from address: lowercase, ASCII-only, dash-separated; collapse repeated dashes; strip leading/trailing dashes. Example: `griffin-house-upper-church-street-chepstow` |
+| `displayName` | the `name` field on the source record (already human-formatted), e.g. `Listing Particulars — Griffin House, Upper Church Street, Chepstow NP16 5EX` — strip the `Listing Particulars — ` prefix if present |
+| `sourceSystem` | literal `"loop-crm"` |
+| `sourceId` | the `loopPropertyId` field as string |
+| `listingType` | from the FACTS block `Type of listing:` (`sale` or `let`); default `sale` when absent |
+| `status` | from FACTS `Status:` value normalised — `Available` → `for-sale`, `Under Offer` → `under-offer`, `Sold STC` / `Sold` → `sold`, `Withdrawn` → `withdrawn`. When absent default `for-sale` |
+| `price` | from FACTS `Price:` — strip `£` and commas, parse integer (pounds, not pence; convert if necessary) |
+| `priceQualifier` | from any `Guide Price` / `Offers Over` / `OIEO` / `POA` keyword preceding the price |
+| `bedrooms`, `bathrooms`, `receptionRooms` | integers from FACTS `Bedrooms:`, `Bathrooms:`, `Receptions:` |
+| `floorAreaSqft` | from FACTS `Square Feet:` or `Floor Area:` — parse integer |
+| `propertyType` | from FACTS `Type:` — lowercase the value (`cottage`, `detached`, `flat`, etc.) |
+| `tenure` | from FACTS `Tenure:` — normalise to `freehold` / `leasehold` / `share-of-freehold` / `commonhold` |
+| `postcode` | extracted from `displayName` by the trailing UK postcode regex `[A-Z]{1,2}[0-9][A-Z0-9]? ?[0-9][A-Z]{2}` — normalised to upper-case with a single space before the inward code (`NP16 5EX`) |
+| `addressLine`, `town` | parsed from the `displayName` minus the postcode tail |
+| `description` | the full source `body` text, with the FACTS block stripped (keep the narrative paragraphs only) |
+| `imageUrls`, `heroImageUrl`, `floorplanUrls`, `epcUrl` | from the Loop property-detail call — `mcp__loop__loop-property-detail` returns these arrays; `heroImageUrl` is `imageUrls[0]` |
+| `pageUrl` | from the Loop property-listed call — the Rightmove / Zoopla / OnTheMarket / agent-website URL for the listing |
+| `blurb` | derived from `description` by a single Haiku call: "Write a single marketing-grade sentence (≤ 280 characters) summarising this UK property listing to a prospective buyer. No estate-agent clichés (no 'rare opportunity', 'must-see', 'stunning'). Plain English. Return only the sentence." Fallback when the LLM fails or returns >280 chars: take the first 280 characters of `description`, normalise whitespace, end on a word boundary |
+| `sourceSystem`, `sourceId`, `ingestedAt`, `lastVerifiedAt` | provenance — set on every write |
+| `scope` | `"public"` for any Listing with `status` in `for-sale` / `under-offer` / `sold` (visitor-renderable). `"shared"` for off-market / withdrawn / pre-marketing pipeline (staff-only) |
+### Zip-site / hosted-page directory → Listing
+When a property site has been published from operator-supplied assets, the directory follows the format produced by `property-brochure:property-extract`:
+```
+<property-slug>/
+  property.json        # structured fields
+  hero.jpg | hero.png  # primary image
+  photos/              # full image set
+  floorplans/          # floorplan images
+  epc.pdf | epc.png    # EPC document
+  description.md       # full descriptive copy
+```
+Map directly:
+| Listing field | Source |
+|---|---|
+| `slug` | the directory basename |
+| `displayName`, `addressLine`, `town`, `postcode`, `priceGBP` (`→ price`), `priceQualifier`, `bedrooms`, `bathrooms`, `receptionRooms`, `floorAreaSqft`, `propertyType`, `tenure` | `property.json` keys with the same names (Schema.org camelCase already enforced upstream) |
+| `description` | `description.md` body |
+| `heroImageUrl` | the published URL of `hero.jpg` (passed in by the hosting agent, never invented) |
+| `imageUrls` | published URLs of `photos/*` in directory order — `heroImageUrl` is included at index 0 |
+| `floorplanUrls` | published URLs of `floorplans/*` |
+| `epcUrl` | published URL of `epc.pdf` |
+| `pageUrl` | the live URL the hosting agent emits for `<property-slug>/index.html` |
+| `sourceSystem` | literal `"zip-upload"` |
+| `sourceId` | the directory basename (the slug) — directory basename is the operator-chosen natural key |
+| `blurb` | same LLM rule as the Loop path; same fallback |
+| `status` | from `property.json#status`; default `for-sale` |
+| `scope` | `"public"` |
+### Manual operator dump → Listing
+Format: operator pastes a property brief into chat. The curator parses with the same rules as the Loop path (key-value FACTS-style extraction), then asks the operator for any missing required field before writing. `sourceSystem: "manual"`; `sourceId` is whatever natural key the operator gives — they confirm uniqueness.
+## Source rejection — when not to write
+Write a `no-op` (no Listing produced; admin agent informed) when:
+- The source has no FACTS block AND no parseable address — there is no `slug` to derive and no `displayName`. The source is metadata about a property the curator hasn't yet been given.
+- The source declares `status: "off-market"` AND no `pageUrl` is known. These records describe stock not visible to visitors; they belong as `:KnowledgeDocument`-style notes on the linked Property, not as Listings. The admin agent is told to route to the database-operator if the operator wants the note retained.
+- The source's `accountId` cannot be resolved (no LocalBusiness in session env). Listings without a `LISTED_BY` parent cannot be written.
+`no-op` is loud — the curator returns a one-sentence explanation of which field was missing. Silent skips are defects.
+## Image curation
+After writing the Listing, the curator writes one `:ImageObject` node per URL in `imageUrls` and a `[:DEPICTS]` edge from the Listing to each image. ImageObjects are what the public-agent recommender skill picks among when a visitor asks to see a specific room or feature — without them, the agent can only emit the hero image. The schema contract for `:ImageObject` lives in `schema-estate-agent.md`.
+For each image URL on the Listing:
+1. **Vision tag pass.** Call `mcp__memory__image-fetch` with the image URL; the tool returns the image bytes as an inline content block your model can see. Then produce `{description, tags}` from what you see using the same single-call doctrine as the blurb step. The description is a single sentence (≤ 200 characters, plain English, no estate-agent clichés). The tags are up to four labels drawn from this fixed set: `kitchen`, `bathroom`, `bedroom-master`, `bedroom-secondary`, `living-room`, `dining-room`, `garden-rear`, `garden-front`, `exterior-front`, `exterior-rear`, `hallway`, `utility`, `floorplan`, `epc`, `view`. The tag set is closed — never invent a tag outside it. When no tag applies, `tags` is the empty array. When `image-fetch` returns `isError`, write the ImageObject anyway with empty `description` and `tags` and log `[listing-curator] image-tag-failed url=<url> reason=<short>` — the validate step below handles that branch.
+2. **Validate.** If the response fails to parse as JSON, or `description` is empty / >200 chars, write the ImageObject anyway with `description: ""` and `tags: []`. Log `[listing-curator] image-tag-failed url=<url> reason=<short>`. One image's tagging failure must not block the rest of the Listing's images — degraded room-pick on that image is the only consequence.
+3. **Write the node.** `MERGE (i:ImageObject {accountId, listingSlug, url})` then `SET i.description, i.tags, i.heroIndex, i.scope, i.sourceSystem`. `scope` mirrors the parent Listing (`public` for visitor-renderable Listings; `shared` otherwise). `heroIndex` is the image's 0-based position in the source `imageUrls` array — `0` for the hero.
+4. **Write the edge.** `MERGE (l:Listing {accountId, slug:listingSlug})-[:DEPICTS]->(i)`. The MERGE on the natural key `(accountId, listingSlug, url)` makes both the node write and the edge write idempotent; re-running the curator over a Listing tops up missing images without duplicating existing ones.
+No `embedding` is written on `:ImageObject` v1. The recommender picks by reading the Listing's child ImageObjects from hybrid search's `related` set (graph-search expands one hop automatically). If pick quality is poor, a follow-up task will add per-image embeddings; not now.
+Floorplans and the EPC document follow the same path — they get their own `:ImageObject` with `tags: ["floorplan"]` or `tags: ["epc"]`, written from the curator's `floorplanUrls` and `epcUrl` fields. The hero image carries `tags` reflecting what the photo actually shows (e.g. `["exterior-front"]`) — never the literal tag `hero`. `heroIndex: 0` identifies it.
+Hybrid search's 1-hop expand caps `related` at 20 neighbours per Listing. Listings with > 20 images lose the surplus to the cap — acceptable for v1 (most Loop listings ≤ 20). Log `[listing-curator] image-cap-warning slug=<slug> imageCount=<N>` when `N > 20` so the gap is visible.
+## Idempotency and update semantics
+Every write executes `MERGE (l:Listing {accountId, sourceSystem, sourceId})`. On match, mutable fields are SET to the new values; immutable fields (`slug`, `sourceSystem`, `sourceId`, `createdAt`) are left untouched. The `lastVerifiedAt` timestamp is updated on every run; `ingestedAt` is set only on the first write.
+`status` is mutable and expected to drift over the listing's life — `for-sale` → `under-offer` → `sold` / `withdrawn`. Repeat curation runs are how that drift lands in the graph.
+`slug` is immutable on update. If the source's `displayName` changes after first ingest (e.g. an address typo was fixed in Loop), the slug stays at its first-write value to keep the visitor-facing URL stable. If a slug truly must change, that's an operator decision routed via `memory-update`, not a silent curator rewrite.
+## Migration of legacy `KnowledgeDocument(source: "loop-crm")` records
+The realagent-code Pi (`192.168.88.16`, Neo4j `bolt://localhost:7688`) holds 29 historical `KnowledgeDocument` nodes with `source: "loop-crm"` carrying the flat `body` text. These predate the curator and must be migrated to `:Listing` nodes.
+The migration choice: **delete the source `KnowledgeDocument` after the matching `:Listing` is written.** The full `body` text is preserved as the Listing's `description` property — no information is lost — so a parallel raw-record node would be duplicate content. The `KnowledgeDocument` had no incoming edges (per the existing graph state) so deletion is safe; if a future ingestion path needs the raw body retained, the curator's `description` field already holds it.
+The migration cypher is run once via SSH against the Pi as a manual backfill step; it is not part of the curator's per-record write path. The doctrine the curator carries forward is: any future Loop record passes through the curator on the first write, not as a `:KnowledgeDocument`.
+## Observability
+One structured log line per write, emitted by the curator before returning to the admin agent:
+```
+[listing-curator] event=property-curated slug=<slug> sourceSystem=<system> sourceId=<id> action=<create|update|no-op> fieldsFilled=<comma-separated-list> fieldsMissing=<comma-separated-list> scope=<scope> imagesWritten=<N> imagesTagged=<M> imagesFailed=<F>
+```
+`fieldsMissing` is the load-bearing signal. Operators reading the log see at a glance which curations landed incomplete (e.g. `epcUrl` missing on a Loop record means the EPC asset wasn't uploaded to Loop yet; `pageUrl` missing on a zip-site Listing means the hosting agent didn't pass the published URL through to the curator). Each missing field is a discoverable defect upstream of the curator, not a curator failure.
+`imagesWritten` is the total `:ImageObject` count for the Listing after the run. `imagesTagged` is the count with non-empty `tags`. `imagesFailed` counts images where the vision pass failed JSON-validation and a placeholder ImageObject was written with empty description and tags. A high `imagesFailed / imagesWritten` ratio means the vision pass is degrading; investigate the prompt or the source images. When `imagesWritten > 20`, the recommender will only see the first 20 in its `related` set (one-hop expand cap) — emit a separate `[listing-curator] image-cap-warning slug=<slug> imageCount=<N>` line so the cap is visible.
+## Out of scope
+- Producing the visitor-facing markdown card from a `:Listing`. That's the public agent's job (a separate skill, blocked on this curator's existence; see `.tasks/`).
+- Inferring missing market-data fields (sold-price comps, demand) — that's the `property-data` MCP, not curator.
+- Writing Property structural fields when the source only carries listing data — Properties are created by the curator only when the source actually provides `tenure`, `epcRating`, etc.; otherwise the Listing stands on its own with the `LISTED_BY` parent edge.

package/payload/premium-plugins/real-agent/plugins/brochures/skills/a4-print-documents/SKILL.md CHANGED Viewed

@@ -298,7 +298,7 @@ The longest edge of every brochure photo, **measured before any optimisation**,
 The cap is firm — beyond 4000 px the file size grows without visible benefit. The floor is firm too: below it the photo softens noticeably even on screen at 100% zoom, and worse in print.
-**Loop CRM caveat.** Many UK estate agents export listing photos at a 1600 px ceiling (Beacons, Muvin, etc.). That is below the full-bleed and half-page floors. When the source photos cap below the floor for an assigned slot and no higher-resolution substitute exists, raise this with the user rather than silently shipping a sub-floor cover — a `DONE_WITH_CONCERNS` is the right exit.
+**1600 px source-ceiling caveat.** Many UK listing-CDN exports cap at a 1600 px ceiling (this is a common Loop-CRM tenant default; some portal exports cap similarly). That is below the full-bleed and half-page floors. When the source photos cap below the floor for an assigned slot and no higher-resolution substitute exists, raise this with the user rather than silently shipping a sub-floor cover — a `DONE_WITH_CONCERNS` is the right exit.
 **Measure before optimising:**

package/payload/premium-plugins/real-agent/plugins/brochures/skills/brand-design/SKILL.md CHANGED Viewed

@@ -15,7 +15,7 @@ allowed-tools:
 Turn one publicly-accessible website URL into a self-contained brand-design directory that downstream design, marketing, and document-generation skills can consume without re-visiting the source site.
-The reference output this skill targets is `/Users/neo/estate-agents/beacons/` — read that directory once before generating to anchor the standard. (The neighbouring `/Users/neo/estate-agents/muvin/` is structurally identical; either may be inspected.)
+The output shape is a brand workspace at `<brand_dir>/` containing the four artifacts defined in **Outcome contract** below. The contract is the format; any prior conforming brand pack on disk may be inspected as a reference, but no specific location is required.
 ## Outcome contract
@@ -29,7 +29,7 @@ The skill is **complete** when the target directory contains exactly these four
   description.md             # company copy + official registration details
 ```
-`<slug>` is the lowercase, hyphen-separated brand name (e.g. `beacons`, not `beaconsrealestate.co.uk`). The slug is reused as the directory name unless the caller specifies otherwise — that is, the brand workspace is `<output-dir>/<slug>/` and these four files live at its root.
+`<slug>` is the lowercase, hyphen-separated brand name — derived from the brand's own name, not its FQDN (e.g. `<brand>`, not `<brand>realestate.co.uk`). The slug is reused as the directory name unless the caller specifies otherwise — that is, the brand workspace is `<output-dir>/<slug>/` and these four files live at its root.
 A sibling `properties/` directory may also be present at `<output-dir>/properties/` — it belongs to `property-extract` and **must not** be touched by this skill. Working files this skill creates (screenshots, intermediate JSON, snapshot dumps) must be cleaned up before reporting completion. The four artifacts above are the deliverable; nothing else this skill writes is "scratch" that survives.
@@ -153,7 +153,7 @@ A photographic crop of the logo from a screenshot is **not** acceptable — the
 ### `description.md`
-Plain Markdown, no frontmatter. The structure mirrors the reference at `/Users/neo/estate-agents/beacons/description.md`:
+Plain Markdown, no frontmatter. Structure:
 1. Brand name on its own line.
 2. The brand's own tagline / one-liner from the homepage hero.
@@ -199,13 +199,7 @@ The skill does **not** prescribe which browser tool to use. Where multiple are a
 ## Reference standard
-Before producing output, read these files to anchor the format:
-- `/Users/neo/estate-agents/beacons/DESIGN.md` — the depth and format expected of the token spec.
-- `/Users/neo/estate-agents/beacons/description.md` — the voice and structure expected of the company description.
-- `/Users/neo/estate-agents/beacons/beacons-logo-light.png`, `…-dark.png` — the visual standard for logo crops.
-A delivered package that diverges substantially in structure from the reference is wrong, even if the content is accurate.
+The four artifact contracts above (DESIGN.md tier-1/2/3 token spec, the two PNG logo files with filename describing the art colour, `description.md` with the official-details block) are the contract. If a prior conforming brand pack exists on disk at any `<brand_dir>/` (look for the four artifacts in the layout shown in **Outcome contract**), inspect it as a worked example. A delivered package that diverges substantially in structure from those contracts is wrong, even if the content is accurate.
 ## Common mistakes
@@ -216,7 +210,7 @@ A delivered package that diverges substantially in structure from the reference
 | Paraphrasing the homepage hero into "punchier" copy | `description.md` is the source of truth for the brand's voice. The brand's words, not yours. |
 | Inventing token values that the site doesn't use | Token tier 1 is **observed**. `(proposed)` is for tier-2/3 values that fill an obvious gap, not for guesses about what the brand wants. |
 | Including blog posts or case studies in `description.md` | The file is identity, not editorial. |
-| Naming files after the domain (`beaconsrealestate-logo.png`) | Slug is the brand name, not the FQDN. |
+| Naming files after the FQDN (`<brand>realestate-logo.png` instead of `<brand>-logo.png`) | Slug is the brand name, not the full domain. |
 | Skipping the mobile viewport during token capture | Type scale and section padding both differ at mobile. A desktop-only tokenization is incomplete. |
 | Generating the dark theme block in `DESIGN.md` from imagination | If the site is light-only, the dark theme is an **inversion derived from the primitives**, marked "proposed", not a parallel design system. |
 | Embedding the company description inside `DESIGN.md` | The artifacts are separable on purpose. Each file has one job. |

package/payload/premium-plugins/real-agent/plugins/brochures/skills/make-brochure/SKILL.md CHANGED Viewed

@@ -108,7 +108,7 @@ The skill performs four checks in order. Each rule fully specifies its *conditio
 ### 1. Resolve the brand identity
-If `brand_source` is a URL: derive `brand_slug` as the lowercase domain root with no TLD (e.g. `https://muvin.co.uk` → `muvin`, `https://example-agent.co.uk` → `example-agent`).
+If `brand_source` is a URL: derive `brand_slug` as the lowercase domain root with no TLD (e.g. `https://<agent>.co.uk` → `<agent>`, `https://example-agent.co.uk` → `example-agent`).
 If `brand_source` is a path: `brand_slug` = the directory's basename.
@@ -132,7 +132,7 @@ If `brand_source` was a path and `DESIGN.md` is missing, treat that as an author
 ### 3. Resolve the property identity
-If `property_source` is a URL: derive `property_slug` from the URL's `/property/<slug>/<id>/` path segment. The folder name is `<property_slug>-<id>` (e.g. `henham-road-debden-green-hamperden-end-cb11-3lz-949931`).
+If `property_source` is a URL: derive `property_slug` from whichever path component the source exposes (e.g. `/property/<slug>/<id>/` on Loop-CRM tenants; portals expose different shapes). The folder name is `<property_slug>-<id>` (e.g. `<street-locality-postcode>-<listing-id>`).
 If `property_source` is a path: the folder name is the directory's basename.
@@ -178,6 +178,8 @@ Property photographs almost always exceed this threshold. Concrete examples in t
 | `ChatGPT-Image-*` (AI render) | 1024 or 2048px (borderline — measure) |
 | `Screenshot-*` (desktop capture) | 1200–2880px (borderline — measure) |
+Filename prefixes vary by source — Loop-CRM tenants commonly ship the shapes above; other portals re-serve under their own filename conventions. The 2000 px rule is what binds, not the prefix.
 ### Safe inspection workflow
 Before any `Read` against an image:
@@ -212,7 +214,7 @@ The orchestrator does not bundle the upstream skills' outputs — each leaves it
 ## Slot-assignment hand-off — verify image content visually, not by filename
-A repeated failure mode in this pipeline is mis-mapping a slot from filename alone — the brochure step references `images/sparrows-farm-22.webp` because slot 22 should be the inglenook, but the actual photograph at index 22 is a downstairs WC. Filename tells you order; pixels tell you content.
+A repeated failure mode in this pipeline is mis-mapping a slot from filename alone — the brochure step references `images/<property-slug>-22.webp` because slot 22 should be the inglenook, but the actual photograph at index 22 is a downstairs WC. Filename tells you order; pixels tell you content.
 The orchestrator's role is to **enforce the visual-verification step** before `property-brochure` writes the HTML:
@@ -290,11 +292,9 @@ After a complete run, the on-disk layout is **exactly** this — no deeper nesti
 The `output/` folder is a portable deliverable: every image referenced by `brochure.html` resolves to a file under `output/images/`. References that escape `output/` (`../images/`, `../../floorplans/`, `../../epc/`) are a defect — the brochure must not depend on the sibling property-extract folders staying in place.
-Reference instances that already conform (on the maintainer's machine — paths reflect where those runs happened, not a default for new callers):
-- `/Users/neo/estate-agents/muvin/` (brand_slug = `muvin`)
-- `/Users/neo/estate-agents/beacons/` (brand_slug = `beacons`)
+The brand-workspace set is whatever directories exist under the caller's `<output_root>/` — enumerate them with `ls <output_root>` at runtime rather than assuming a fixed set. Each brand directory is its own workspace and matches the `<brand_slug>/` layout above.
-A fresh run with no `output_root` and no existing brand pack lands the workspace in the caller's CWD — `./muvin/` / `./beacons/` / etc., not under any other path.
+A fresh run with no `output_root` and no existing brand pack lands the workspace in the caller's CWD as `./<brand_slug>/`, not under any other path.
 Determinism rules — a run that violates any of these is wrong, even if the brochure renders:
 - `properties/` is **inside** `<brand_dir>/`, never a sibling.