@rubytech/create-maxy-code 0.1.112 → 0.1.113

package/payload/platform/plugins/venture-studio/skills/prototype-host/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: prototype-host
+description: Use when the operator asks to "host the landing", "host the prototype", "deploy this", "give me a public URL", or any variant that means "make the landing page or wedge prototype reachable on a real URL the founder can send to a customer". Scaffolds a source tree, allocates a local port, edits the brand's cloudflared ingress, creates a DNS row, runs the dev server (or static file-server) under a systemd-user unit, and verifies HTTP 200 from outside the box. Idempotent: re-run for the same surface restarts cleanly without duplicating ports, ingress rows, or units.
+---
+
+# prototype-host
+
+## Outcome
+
+A founder asks "host the landing" or "host the prototype" and ends the turn with a working public URL — `https://<surface>.<brand-hostname>` — that returns HTTP 200, backed by a dev server (or static file server) supervised by systemd so it survives reboot. No CI, no Vercel, no Pages — the install device itself serves the prototype through the brand's existing cloudflared tunnel.
+
+The skill is a composition of primitives that already exist on every Maxy Code install: cloudflared multi-hostname ingress (see [`cloudflared/references/manual-setup.md`](../../../../platform/plugins/cloudflare/references/manual-setup.md)), `systemctl --user` unit files for per-process supervision, and the agent's Bash + Read + Write + Edit tools for source scaffolding. The skill's job is to compose them deterministically so the founder never has to.
+
+## Inputs
+
+The agent gathers these before invoking any of the six phases. Defaults below; use `AskUserQuestion` only when the operator's intent is ambiguous about surface name or framework.
+
+| Input | Default | Notes |
+|---|---|---|
+| `surface` | `landing` for "host the landing"; `prototype` for "host the prototype"; otherwise ask | The DNS label; becomes `<surface>.<brand-hostname>`. Lowercase, kebab-case, must be a valid DNS label (`^[a-z0-9-]+$`, max 63 chars). |
+| `framework` | `static` for `landing`; `vite` for `prototype` | One of `static`, `vite`, `next`, `sveltekit`, `astro`. See [`references/scaffold-frameworks.md`](references/scaffold-frameworks.md). |
+| `surface-dir` | `${PROJECT_ROOT}/.docs/data-room/prototype/<surface>/` | Source tree root. |
+
+Two environment values the skill derives, never asks for:
+
+- `BRAND` — from `jq -r '.hostname' <PROJECT_ROOT>/platform/config/brand.json` (same idiom every other skill uses).
+- `BRAND_HOSTNAME` — the cloudflared root domain for this install: `jq -r '.cloudflareRootDomain // .hostname' <PROJECT_ROOT>/platform/config/brand.json`. If the field is empty, abort with literal stderr `[prototype-host] FATAL brand-hostname-unresolved — set cloudflareRootDomain in brand.json`.
+
+## Hard prerequisite — brand-pack must have run
+
+Before phase 1, check `[ -d "${PROJECT_ROOT}/.docs/data-room/06-product-ip/brand" ]` and `[ -n "$(ls -A "${PROJECT_ROOT}/.docs/data-room/06-product-ip/brand" 2>/dev/null)" ]`. If either fails, abort:
+
+```
+[prototype-host] FATAL brand-pack-missing — run brand-pack first; hosted surfaces consume 06-product-ip/brand/{color-palette,typography-system,tone-of-voice}.md
+```
+
+This is doctrinal — hosting a brandless landing ships a surface that either confounds conversion data or forces a re-render after brand-pack. The check is exit-code, not LLM judgement.
+
+## Phases
+
+Every phase emits exactly one structured stdout line on success:
+
+```
+[prototype-host] phase=<n> surface=<surface> framework=<framework> port=<port> ingress=<state> dns=<state> service=<unit> status=<systemd-state> http=<code>
+```
+
+Any phase that cannot produce its key/value pair fails by emitting literal stderr (no narration, no retry, no menu-phrasings — [[feedback_no_stdout_parsing_for_control_flow]]) and exits non-zero. The agent surfaces the stderr verbatim to the operator.
+
+### Phase 1 — Surface intake (idempotency check)
+
+If `<surface-dir>/.port` exists, this is a re-run. Read the port from `.port`, skip directly to phase 5 (systemd restart) then phase 6 (verify). Log:
+
+```
+[prototype-host] phase=1 surface=<surface> idempotent=true port=<port>
+```
+
+Otherwise proceed to phase 2.
+
+### Phase 2 — Scaffold source
+
+Run the framework's canonical scaffolder into `<surface-dir>/`. The exact commands per framework live in [`references/scaffold-frameworks.md`](references/scaffold-frameworks.md). Static `landing` is a special case: write `<surface-dir>/index.html` directly from `01-narrative/LANDING.md` using the brand tokens.
+
+Brand application (every framework):
+
+1. Read `06-product-ip/brand/color-palette.md` — extract the CSS custom properties (the file ships a `:root { --color-*: ... }` block).
+2. Read `06-product-ip/brand/typography-system.md` — extract the font-family + scale tokens.
+3. For `static`: inline both into the `<head>` of `<surface-dir>/index.html`.
+4. For framework scaffolds: write the tokens into the framework's global stylesheet entry point (`src/index.css` for Vite/Astro, `app/globals.css` for Next, `src/app.css` for SvelteKit).
+5. For the landing's hero + CTA copy: read `06-product-ip/brand/tone-of-voice.md` and apply it when rewriting `01-narrative/LANDING.md` into HTML.
+
+### Phase 3 — Port allocation
+
+First unbound port in 4100–4199:
+
+```bash
+for p in $(seq 4100 4199); do
+  ss -tln 2>/dev/null | awk '{print $4}' | grep -qE ":${p}$" || { echo "$p"; break; }
+done
+```
+
+Write to `<surface-dir>/.port`. If the range is exhausted, abort:
+
+```
+[prototype-host] FATAL port-range-exhausted range=4100-4199 — free a port or extend the range
+```
+
+The range is a skill constant (not a `brand.json` field) because it sits below every documented admin/chat/VNC band and above the OS ephemeral range default. Extending the range is a follow-up task, not a per-install knob.
+
+### Phase 4 — Cloudflared ingress edit
+
+Per [`references/cloudflared-ingress-edit.md`](references/cloudflared-ingress-edit.md):
+
+1. Append a hostname rule for `<surface>.<BRAND_HOSTNAME>` → `http://localhost:<port>` immediately before the final `http_status:404` catch-all in `${CFG_DIR}/config.yml`. The reference doc carries the exact `awk` insert pattern (sed cannot safely insert before the last line of a multi-line YAML rule).
+2. Validate: `cloudflared --origincert "${CFG_DIR}/cert.pem" --config "${CFG_DIR}/config.yml" tunnel ingress validate`. Non-zero exit aborts with the literal cloudflared error.
+3. Create DNS row: `cloudflared --origincert "${CFG_DIR}/cert.pem" tunnel route dns --overwrite-dns "${TUNNEL_ID}" <surface>.<BRAND_HOSTNAME>`. `TUNNEL_ID` comes from `${CFG_DIR}/tunnel.state` (the Step 5b file every install writes).
+4. Reload cloudflared: `systemctl --user restart ${BRAND}-cloudflared.service`.
+
+Idempotency: before appending, grep `${CFG_DIR}/config.yml` for `<surface>.<BRAND_HOSTNAME>`. If present, skip the append + DNS route + reload — the row already exists; this is a re-run after a failed phase 5 or 6.
+
+### Phase 5 — Systemd user unit
+
+Per [`references/systemd-user-service.md`](references/systemd-user-service.md), write `${HOME}/.config/systemd/user/${BRAND}-prototype-<surface>.service`. Two modes:
+
+- **Dev-server mode** (frameworks with hot-reload — Vite, Next dev, SvelteKit dev, Astro dev): `ExecStart=` runs the framework's dev command bound to `<port>` via `PORT=` or `--port`.
+- **Static file-server mode** (the `static` framework): run `npm run build` first (no-op for raw HTML), then `ExecStart=cloudflared file-server --port <port> <surface-dir>` (or `<surface-dir>/dist` for built output). No Node process for raw static landings.
+
+Then:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now "${BRAND}-prototype-<surface>.service"
+```
+
+Check `systemctl --user is-active "${BRAND}-prototype-<surface>.service"` returns `active`. If not, dump the last 50 lines of `journalctl --user -u ${BRAND}-prototype-<surface>.service -n 50 --no-pager` to stderr and abort.
+
+### Phase 6 — External verification
+
+```bash
+curl -I -m 15 "https://<surface>.<BRAND_HOSTNAME>"
+```
+
+The skill emits the full HTTP response line (e.g. `HTTP/2 200`) to chat. Anything other than `200` aborts with the full curl output as literal stderr — same setup-done contract Task 288 established for cloudflare setup. This is end-to-end proof because the chat itself runs through the same tunnel: if the cloudflared connector were dead, the agent would never have answered the operator.
+
+Final success line:
+
+```
+[prototype-host] DONE surface=<surface> url=https://<surface>.<BRAND_HOSTNAME> port=<port> service=${BRAND}-prototype-<surface>.service http=200
+```
+
+## Idempotency contract
+
+Re-running the skill with the same `<surface>` is a first-class flow, not an error:
+
+| State on re-run | Behaviour |
+|---|---|
+| `<surface-dir>/.port` exists, ingress row exists, service active | Restart the systemd unit; re-verify; emit `idempotent=true` |
+| `.port` exists, ingress row missing | Re-run phase 4 (append, validate, route, reload); restart unit; verify |
+| `.port` exists, service failed | Restart unit; if still failing, dump journal and abort |
+| Nothing exists | Fresh six-phase run |
+
+The skill never allocates a second port for the same surface, never appends a duplicate ingress row, never creates a second systemd unit with a different name.
+
+## Failure surfaces
+
+Likely failure points and the literal stderr the agent should expect:
+
+- **Port range exhausted** — `[prototype-host] FATAL port-range-exhausted range=4100-4199`
+- **Ingress validate fails** — cloudflared's own multi-line YAML error, verbatim
+- **DNS route fails** — cloudflared's stderr (typically a 1xxx error code from the API)
+- **Systemd unit fails to start** — last 50 lines of journalctl, verbatim
+- **Curl returns non-200** — full `curl -I` output, verbatim
+
+Diagnostic commands the agent should suggest on failure:
+
+```bash
+cat ${CFG_DIR}/config.yml
+cloudflared --origincert "${CFG_DIR}/cert.pem" --config ${CFG_DIR}/config.yml tunnel ingress validate
+systemctl --user status ${BRAND}-prototype-<surface>.service
+journalctl --user -u ${BRAND}-prototype-<surface>.service -n 200 --no-pager
+ss -tln | grep :<port>
+dig <surface>.<BRAND_HOSTNAME>
+```
+
+## Out of scope
+
+- Production hosting (Cloudflare Pages, Vercel, Netlify, Workers). The dev server on the install device covers the founder workflow; production deploy is a separate, later task.
+- TLS / cert handling beyond cloudflared's own.
+- Per-prototype auth gating — the public landing is public; access control is a separate skill.
+- `brand.json` schema changes. Port range is a skill constant.
+- `paths.ts` reads.
+- Multi-tunnel — one tunnel per install with multiple ingress rules is the existing pattern.
+- CI/CD or git-push deploy.
+- Pre-built framework templates beyond the framework's official `create-*` scaffolders.
+- Telemetry on the public URL — the founder wires their own (Plausible, GA, server logs).
+- A `prototype-host-remove` companion skill. For now: `systemctl --user disable --now ${BRAND}-prototype-<surface>.service` + manually strip the ingress row + delete the DNS record. Removal is a follow-up task if it becomes friction.
+
+## Multi-prototype is supported by construction
+
+Port allocation scans first-free; ingress rules are additive; systemd unit names are namespaced by `<surface>`. Running `landing` + `prototype` + `prototype-v2` simultaneously on the same install requires no special handling — invoke the skill three times with three different surface names.

package/payload/platform/plugins/venture-studio/skills/prototype-host/references/cloudflared-ingress-edit.md

@@ -0,0 +1,81 @@
+# Cloudflared ingress edit — append a hostname rule before the catch-all
+
+This is the canonical pattern for adding a new hostname → local port mapping to an existing brand cloudflared `config.yml`. Sourced from the multi-hostname ingress block documented at [`platform/plugins/cloudflare/references/manual-setup.md`](../../../../../platform/plugins/cloudflare/references/manual-setup.md) under the "Multi-ingress: adding hostnames for prototype services" section.
+
+## The config.yml shape
+
+A working brand `config.yml` always looks like:
+
+```yaml
+tunnel: <TUNNEL_ID>
+credentials-file: <CFG_DIR>/<TUNNEL_ID>.json
+ingress:
+  - hostname: admin.<BRAND_HOSTNAME>
+    service: http://localhost:<PORT>
+  - hostname: public.<BRAND_HOSTNAME>
+    service: http://localhost:<PORT>
+  - service: http_status:404
+```
+
+A new prototype rule must land **before** the `http_status:404` catch-all; otherwise cloudflared matches the catch-all first and the prototype hostname returns 404.
+
+## The append pattern
+
+`sed` cannot safely insert before the last block of a multi-line YAML rule (`- service: http_status:404` is one logical entry but the line above it might be a comment or blank). `awk` is the right primitive: scan for the literal `- service: http_status:404` line and insert two lines before it.
+
+```bash
+SURFACE="<surface>"            # e.g. landing
+PORT="<port>"                  # from <surface-dir>/.port
+HOSTNAME="${SURFACE}.${BRAND_HOSTNAME}"
+
+# Idempotency guard — skip if the hostname already appears as an ingress rule.
+if grep -qE "^[[:space:]]*-[[:space:]]+hostname:[[:space:]]+${HOSTNAME}\b" "${CFG_DIR}/config.yml"; then
+  echo "[prototype-host] ingress-row-exists hostname=${HOSTNAME} — skipping append"
+else
+  awk -v host="${HOSTNAME}" -v port="${PORT}" '
+    /^[[:space:]]*-[[:space:]]+service:[[:space:]]+http_status:404[[:space:]]*$/ {
+      print "  - hostname: " host
+      print "    service: http://localhost:" port
+    }
+    { print }
+  ' "${CFG_DIR}/config.yml" > "${CFG_DIR}/config.yml.new"
+  mv "${CFG_DIR}/config.yml.new" "${CFG_DIR}/config.yml"
+fi
+```
+
+## Validate, route, reload
+
+```bash
+# 1. Validate the YAML and ingress semantics.
+cloudflared --origincert "${CFG_DIR}/cert.pem" \
+  --config "${CFG_DIR}/config.yml" \
+  tunnel ingress validate
+
+# 2. Create the DNS row (CNAME from <hostname> to <TUNNEL_ID>.cfargotunnel.com).
+TUNNEL_ID=$(jq -r '.id // .tunnelId' "${CFG_DIR}/tunnel.state")
+cloudflared --origincert "${CFG_DIR}/cert.pem" \
+  tunnel route dns --overwrite-dns "${TUNNEL_ID}" "${HOSTNAME}"
+
+# 3. Reload the connector so it picks up the new ingress rule.
+systemctl --user restart "${BRAND}-cloudflared.service"
+```
+
+Each step is its own command, runs sequentially, exits non-zero on failure. The skill propagates the failing command's stderr verbatim — no parsing, no narration ([[feedback_no_stdout_parsing_for_control_flow]]).
+
+## What `--overwrite-dns` does
+
+If a CNAME for `<hostname>` already exists in the account's DNS (e.g. from a prior install), `tunnel route dns` errors with `record already exists`. `--overwrite-dns` replaces the existing record with one pointing at this tunnel. Use it unconditionally — the alternative (probe-then-create) doubles the API surface and races with concurrent DNS edits.
+
+## Why restart, not reload
+
+`cloudflared` watches `config.yml` only when launched with `--config-watch` (off by default in the brand service unit). `systemctl --user restart` is the deterministic way to pick up the new rule. Brief connection blip (~1s) is acceptable because the brand's admin + public hostnames already tolerate the same blip on every cloudflared upgrade.
+
+## Failure points
+
+| Symptom | Root cause | Fix |
+|---|---|---|
+| `validate: ingress rule N has no service` | `awk` inserted only the hostname line, not the service line | Re-run; the snippet emits both lines atomically per match |
+| `validate: failed to parse YAML` | A previous `awk` run left a partial line | `cat ${CFG_DIR}/config.yml` and hand-fix; the skill cannot recover from corrupt YAML |
+| `route dns: 1004 invalid hostname` | `<surface>` violates DNS label rules (uppercase, underscore, leading dash) | Re-run with a valid `<surface>`; the skill validates `^[a-z0-9-]+$` before phase 4 |
+| `route dns: 9103 unauthorized` | The cert.pem in `${CFG_DIR}` doesn't grant DNS-edit on the zone | Re-run Step 1 of the cloudflare runbook to refresh `cert.pem` |
+| Restart succeeds but `curl -I` returns 502 | The dev server isn't actually listening on `<port>` | Phase 5 (systemd) failed earlier; the skill should have caught it. Read `journalctl --user -u ${BRAND}-prototype-<surface>.service -n 50` |

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

@@ -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

@@ -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/templates/agents/public/IDENTITY.md

@@ -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

@@ -27,7 +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 + 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 |
+| 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

@@ -3,7 +3,7 @@ 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__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
+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
@@ -100,6 +100,23 @@ Write a `no-op` (no Listing produced; admin agent informed) when:
 
 `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.
@@ -121,11 +138,13 @@ The migration cypher is run once via SSH against the Pi as a manual backfill ste
 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>
+[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/`).

package/payload/premium-plugins/real-agent/plugins/buyers/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "real-agent-buyers",
-  "description": "Full buyer lifecycle — enquiry handling, qualification, viewing management, feedback collection, and educational guides for buyers and sellers.",
+  "description": "Full buyer lifecycle — enquiry handling, qualification, viewing management, feedback collection, educational guides, and the public-chat property recommender that surfaces current listings as rendered cards on visitor buyer intent.",
   "version": "0.1.0",
   "author": {
     "name": "Rubytech LLC"

package/payload/premium-plugins/real-agent/plugins/buyers/PLUGIN.md

@@ -1,6 +1,6 @@
 ---
 name: real-agent-buyers
-description: "Full buyer lifecycle — enquiry handling, qualification, viewing management, feedback collection, and educational guides for buyers and sellers."
+description: "Full buyer lifecycle — enquiry handling, qualification, viewing management, feedback collection, educational guides, and the public-chat property recommender that surfaces current listings as rendered cards on visitor buyer intent."
 tools: []
 always: false
 metadata: {"platform":{"optional":true,"embed":["public","admin"]}}
@@ -8,7 +8,7 @@ metadata: {"platform":{"optional":true,"embed":["public","admin"]}}
 
 # Real Agent — Buyer Management
 
-Five skills covering the complete buyer lifecycle from initial enquiry through viewing management and educational content.
+Six skills covering the complete buyer lifecycle from initial enquiry through viewing management and educational content, plus the public-chat property recommender that fires on visitor buyer intent.
 
 ## When to Activate
 
@@ -21,6 +21,7 @@ The user is handling buyer enquiries, qualifying applicants, managing viewings,
 | `buyer-management` | Full buyer lifecycle — enquiry, qualification, viewing, feedback, offer |
 | `buyer-feedback` | Post-viewing feedback collection via conversational check-in |
 | `property-enquiry` | Structured intake for new buyer enquiries — requirements, finances, timeline |
+| `property-recommender` | Public-chat skill — render a property card (image + blurb + listing URL) on buyer intent, sourced from `:Listing` and `:ImageObject` via memory-search |
 | `viewing-management` | Viewing lifecycle — booking, confirming, rescheduling, reminders |
 | `buyer-seller-guides` | Educational guides for buyers and sellers — first-time, upsizing, downsizing, probate |