@rubytech/create-realagent 1.0.847 → 1.0.850

package/payload/platform/plugins/docs/references/plugins-guide.md

@@ -57,12 +57,12 @@ Premium plugins are one-off purchases that grant permanent ownership. They are n
 | Plugin | Type | What it does | Public agent |
 |--------|------|-------------|-------------|
 | `teaching` | Skills | Interactive tutoring, lesson planning, and study pack generation from your knowledge base | Yes — all 3 skills serve students and parents |
-| `real-agency` | Bundle (10 sub-plugins) | UK estate agency skills — sales, listings, vendor management, buyer management, lead generation, coaching, business operations, onboarding, teaching, and Loop CRM. 2 specialist roles (negotiator, valuer) | 4 sub-plugins (estate-sales, buyers, estate-coaching, estate-onboarding) |
+| `real-agency` | Bundle (10 sub-plugins) | UK estate agency skills — sales, listings, vendor management, buyer management, lead generation, coaching, business operations, onboarding, teaching, and Loop CRM. 3 specialist roles (negotiator, valuer, compliance) | 5 sub-plugins (estate-sales, buyers, estate-coaching, estate-teaching, estate-onboarding) |
 | `writer-craft` | Skills + Agent | Manuscript review and writing craft — story architecture, reader engagement, prose craft, editorial practice, and multi-level review | No — writing craft serves the author |
 
 **How it works:** When you purchase a premium plugin, it's delivered to your {{productName}} via conversation. Tell {{productName}} "Enable the teaching plugin" and it handles the rest. Premium plugins are yours permanently — they survive updates and reinstalls.
 
-Some premium plugins are **bundles** — a single purchase that delivers multiple sub-plugins, each independently activatable. For example, Real Agency delivers 11 sub-plugins covering different aspects of estate agency work. You can enable all of them or just the ones you need (e.g., "Enable estate-sales" for just the sales skills). Enabling or disabling individual sub-plugins does not affect the others.
+Some premium plugins are **bundles** — a single purchase that delivers multiple sub-plugins, each independently activatable. For example, Real Agency delivers 10 sub-plugins covering different aspects of estate agency work. You can enable all of them or just the ones you need (e.g., "Enable estate-sales" for just the sales skills). Enabling or disabling individual sub-plugins does not affect the others.
 
 **Public agent embedding:** Premium plugins marked as public-eligible have their full content (skills and reference knowledge) embedded in public agent prompts. This means a public agent for a Real Agency member can handle buyer enquiries, book viewings, deliver coaching content, and onboard new applicants — all powered by the premium plugin's domain knowledge. Plugins marked admin-only (listings, vendors, leads, business) are only available to the account owner's admin agent.
 
@@ -72,6 +72,8 @@ Some premium plugins include pre-built public agent templates — ready-made con
 
 Some premium plugins ship pre-built workflows that are created when the plugin is enabled. These workflows are fully yours — you can inspect, edit, run, and manage them through conversation, exactly like workflows you create yourself. The plugin provides the starting point; you own the result.
 
+**If a premium plugin ever stops working** — `documents`, `teaching`, anything else you've paid for — and {{productName}} responds as if it doesn't have those tools, the platform's health check (`/api/health.missingPlugins`) will name the affected plugin. Tell {{productName}} "deliver the {{plugin}} plugin" — it re-runs the same delivery step that fires automatically at session start. If the plugin isn't in the device's staging area, re-run the installer for this brand.
+
 ## Choosing Plugins
 
 During first-time setup, {{productName}} presents a plugin selection screen where you choose which plugins to activate. Core plugins are pre-selected and locked. Recommended plugins are pre-selected but optional. You can change your mind later.

package/payload/platform/plugins/docs/references/troubleshooting.md

@@ -420,6 +420,39 @@ The installer's resolver will then see `dpkg -s chromium-browser` exit 0 for the
 
 ---
 
+## VNC browser will not start on Linux laptop — `Permission denied (13)` on SingletonLock
+
+**Symptom:** Boot log `~/.{brand}/logs/vnc-boot.log` shows:
+
+```
+Starting Chromium on :<vncDisplay> (vnc) profile=/home/<user>/.{brand}/chromium-profile CDP=:<cdpPort>
+ERROR:chrome/browser/process_singleton_posix.cc:345] Failed to create
+  /home/<user>/.{brand}/chromium-profile/SingletonLock: Permission denied (13)
+ERROR: Chromium failed to start on :<vncDisplay> (vnc) — CDP port <cdpPort> not listening (browser-specialist degraded)
+```
+
+`dmesg` (or `journalctl -k`) shows AppArmor `DENIED` lines naming `profile="snap.chromium.chromium"` and the `~/.{brand}/chromium-profile/` path. The brand admin chat reports the public-agent VNC browser as unavailable.
+
+**What it means:** Your `/usr/bin/chromium` is a snap symlink. Snap's AppArmor profile excludes hidden top-level paths under `$HOME` from its `home` interface, so writes to per-brand Chromium profile dirs at `~/.maxy/chromium-profile/` and `~/.realagent/chromium-profile/` are denied — Chromium cannot create its `SingletonLock` and never starts the CDP listener. This is exclusively a Linux-laptop problem (Ubuntu Noble); Raspberry Pi OS Bookworm ships `chromium` as a real `.deb` and is unaffected.
+
+**Fix:** Re-run the installer at version 1.0.849 or later. The installer detects the snap-confined chromium during system-dependency setup and replaces it with Google Chrome stable from Google's signed apt repo:
+
+```bash
+npx -y @rubytech/create-maxy@latest
+```
+
+The resolved non-snap binary path is recorded at `<INSTALL_DIR>/platform/config/chromium-binary.path` (single line) and read by every Chromium call site (VNC service, in-page wrapper, Cloudflare OAuth spawn, Playwright server). After re-running, verify with the bundled acceptance script:
+
+```bash
+MAXY_PLATFORM_ROOT=$HOME/<install-dir>/platform $HOME/<install-dir>/platform/scripts/test-laptop-vnc-boot.sh
+```
+
+The script exits 0 only when (1) the configured Chromium realpath is non-snap, (2) the path is absolute and executable, (3) the per-brand CDP port returns Chromium version JSON, and (4) `vnc-boot.log` since the last `[vnc.sh] start` ends with `VNC + browser stack running` and contains no `Chromium failed to start` line.
+
+**Deeper diagnostic:** `vnc.sh` and the in-page wrapper now refuse to start (and exit with a snap-Chromium reference in the boot log) when `chromium-binary.path` is absent or its realpath lands under `/snap/`. If you see those messages, the install completed before the fix shipped — re-run `npx -y @rubytech/create-maxy@latest`. Manual workaround for an emergency (not a fix): `sudo apt-get install -y google-chrome-stable` and confirm `which google-chrome-stable` is non-snap, then re-run the installer to write `chromium-binary.path`.
+
+---
+
 ## Terminal iframe renders black and cursor vanishes over the canvas
 
 **Symptom:** Header-menu Terminal click appears to succeed — no error toast, overlay opens — but the iframe renders uniformly black, keystrokes do not reach any shell, and the mouse cursor disappears the moment it enters the iframe (visible elsewhere in the page).

package/payload/platform/plugins/linkedin-import/PLUGIN.md

@@ -10,11 +10,11 @@ metadata: {"platform":{"optional":true,"pluginKey":"linkedin-import"}}
 
 # LinkedIn Import
 
-Ingests a LinkedIn Basic Data Export (unzipped directory of CSVs + subdirectories) into the Maxy Neo4j graph. Skill-only plugin — no MCP server, no admin tools added. The skill runs under the `database-operator` specialist, which owns external-archive ingestion and ad-hoc graph operations.
+Ingests a LinkedIn Basic Data Export (unzipped directory of CSVs + subdirectories) into the Maxy Neo4j graph. Skill-only plugin — no MCP server, no admin tools added. The skill runs under the `specialists:database-operator` specialist, which owns external-archive ingestion and ad-hoc graph operations.
 
 ## When this applies
 
-The admin agent delegates to `database-operator` when the operator drops a `Basic_LinkedInDataExport_*` directory (or references one by path) into chat. The specialist runs the skill's archive-owner confirmation flow before any CSV is read, then ingests the CSVs the skill has references for.
+The admin agent delegates to `specialists:database-operator` when the operator drops a `Basic_LinkedInDataExport_*` directory (or references one by path) into chat. The specialist runs the skill's archive-owner confirmation flow before any CSV is read, then ingests the CSVs the skill has references for.
 
 ## Intra-plugin growth
 

package/payload/platform/plugins/linkedin-import/skills/linkedin-import/references/connections.md

@@ -110,7 +110,7 @@ Rows missing a position but present with a company produce a `WORKS_FOR` edge wi
 
 ## Post-import verification (operator-side, not agent-side)
 
-After ingest, the operator can verify counts via the `database-operator` specialist's read tools — `mcp__memory__memory-search` with `labels: ["Person"]` plus a filter, or a direct read query through `mcp__graph__maxy-graph-read_neo4j_cypher`:
+After ingest, the operator can verify counts via the `specialists:database-operator` specialist's read tools — `mcp__memory__memory-search` with `labels: ["Person"]` plus a filter, or a direct read query through `mcp__graph__maxy-graph-read_neo4j_cypher`:
 
 ```cypher
 // Owner → connections count
@@ -132,4 +132,4 @@ These are **read queries**, not writes. Cypher writes from the agent are forbidd
 | Tool error "row connectedOn is not ISO 8601" | Parser left `Connected On` in `"23 Apr 2026"` form | Convert to `YYYY-MM-DD` before passing to the tool |
 | Tool error "ownerNodeId not found" | Owner-confirmation flow not run, or operator typed the wrong id | Re-run owner confirmation; pass the resulting `elementId` as `ownerNodeId` |
 | `WORKS_FOR` count « connection count | Many rows have blank company | Expected — LinkedIn doesn't force connections to list a current employer |
-| Tool not present in `init` frame | `database-operator` spawned without the `mcp__memory__memory-archive-write` token | Loud-fail per database-operator's prerogatives. Do not improvise via Bash. Operator must remediate (re-seed specialist templates) |
+| Tool not present in `init` frame | `specialists:database-operator` spawned without the `mcp__memory__memory-archive-write` token | Loud-fail per database-operator's prerogatives. Do not improvise via Bash. Operator must remediate (re-seed specialist templates) |

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

@@ -109,7 +109,7 @@ Before any structured write, load `references/schema-base.md` via `plugin-read`.
 
 ## Document Ingestion
 
-Document ingestion of any kind — PDFs, text, transcripts, web pages, single files — routes to the `database-operator` specialist, which loads the universal `document-ingest` skill at `skills/document-ingest/SKILL.md`. The admin agent never calls `memory-ingest` directly; it dispatches with the document path, the document subject (the anchor node), and the visibility scope.
+Document ingestion of any kind — PDFs, text, transcripts, web pages, single files — routes to the `specialists:database-operator` specialist, which loads the universal `document-ingest` skill at `skills/document-ingest/SKILL.md`. The admin agent never calls `memory-ingest` directly; it dispatches with the document path, the document subject (the anchor node), and the visibility scope.
 
 ### Pipeline
 

package/payload/platform/plugins/memory/references/schema-base.md

@@ -206,7 +206,7 @@ The classifier returns `kind` strings from the closed enumeration above. `kind`
 | `TO` | `KnowledgeDocument` → `Person` or `Organization` | Email direct recipient — written from `documentEdges` per recipient. |
 | `CC` | `KnowledgeDocument` → `Person` or `Organization` | Email cc'd recipient — written from `documentEdges` per cc. |
 | `SPEAKER` | `KnowledgeDocument` → `Person` | Voice-note / single-speaker transcript speaker — written from `documentEdges`. |
-| `MENTIONS` | `KnowledgeDocument` → `Person`, `Organization`, `Service`, `Task`, `Event`, `KnowledgeDocument`, `BrandingData` | Catch-all for entities the dispatch brief named that the document references but for which no document-shape-specific edge applies — written by `database-operator` in the `wire-brief-entities` pipeline step. |
+| `MENTIONS` | `KnowledgeDocument` → `Person`, `Organization`, `Service`, `Task`, `Event`, `KnowledgeDocument`, `BrandingData` | Catch-all for entities the dispatch brief named that the document references but for which no document-shape-specific edge applies — written by `specialists:database-operator` in the `wire-brief-entities` pipeline step. |
 | `DEFINES` | `Section:Definitions` → `DefinedTerm` | Contract definitions — written from per-section `related`. |
 
 **Ontology-growth review query.** When a document accumulates several `:Section:Other` nodes, the operator (or admin agent) can run the following Cypher to surface candidate ontology additions:

package/payload/platform/scripts/test-laptop-vnc-boot.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# Task 929 — laptop VNC + Chromium boot acceptance test.
+#
+# Asserts the four green conditions from .tasks/929 §Verification:
+#   1. The configured Chromium binary's realpath does NOT contain `/snap/`.
+#   2. The configured binary is on PATH and executable.
+#   3. http://127.0.0.1:${cdpPort}/json/version returns the Chromium version JSON.
+#   4. ~/.{configDir}/logs/vnc-boot.log ends with `VNC + browser stack running`
+#      with no preceding `Chromium failed to start` line.
+#
+# Exits non-zero on any assertion failure so this script is wired into the
+# create-maxy post-install gate — any package bump that re-introduces
+# snap-confined Chromium fails before publish (`feedback_no_admin_upgrade_path.md`).
+#
+# Usage (production / post-install): test-laptop-vnc-boot.sh
+# Usage (CI / dev shell):            MAXY_PLATFORM_ROOT=/path/to/maxy/platform test-laptop-vnc-boot.sh
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLATFORM_ROOT="${MAXY_PLATFORM_ROOT:-$(dirname "$SCRIPT_DIR")}"
+BRAND_JSON="${PLATFORM_ROOT}/config/brand.json"
+CHROMIUM_BIN_FILE="${PLATFORM_ROOT}/config/chromium-binary.path"
+
+fail()   { echo "FAIL: $*" >&2; exit 1; }
+pass()   { echo "OK: $*"; }
+
+# --- Resolve config: brand persistDir + cdpPort. brand.json is mandatory.
+[ -r "$BRAND_JSON" ] || fail "${BRAND_JSON} unreadable"
+command -v jq >/dev/null 2>&1 || fail "jq not on PATH (apt install jq)"
+CONFIG_DIR=$(jq -r '.configDir // ".maxy"' "$BRAND_JSON")
+CDP_PORT=$(jq -r '.cdpPort // 9222' "$BRAND_JSON")
+PERSIST_DIR="${HOME}/${CONFIG_DIR}"
+VNC_LOG="${PERSIST_DIR}/logs/vnc-boot.log"
+
+# --- Assertion 1: chromium-binary.path realpath is non-snap.
+[ -r "$CHROMIUM_BIN_FILE" ] || fail "${CHROMIUM_BIN_FILE} missing — installer did not write it"
+CHROMIUM_BIN="$(head -n1 "$CHROMIUM_BIN_FILE" | tr -d '[:space:]')"
+[ -n "$CHROMIUM_BIN" ] || fail "${CHROMIUM_BIN_FILE} is empty"
+[ -x "$CHROMIUM_BIN" ] || fail "configured Chromium ${CHROMIUM_BIN} is not executable"
+CHROMIUM_REALPATH="$(readlink -f "$CHROMIUM_BIN" 2>/dev/null || echo "$CHROMIUM_BIN")"
+case ":$(echo "$CHROMIUM_REALPATH" | tr '/' ':'):" in
+  *:snap:*) fail "${CHROMIUM_BIN} resolves to ${CHROMIUM_REALPATH} (snap-confined — AppArmor will deny SingletonLock writes)" ;;
+esac
+pass "[1/4] Chromium binary ${CHROMIUM_BIN} → realpath=${CHROMIUM_REALPATH} (non-snap)"
+
+# --- Assertion 2: configured binary is the same as `which chromium` resolves
+#                  to OR an absolute path bypassing PATH. Skipped if the
+#                  configured path is absolute and executable (the only thing
+#                  callers actually require). The PATH check is informational.
+if [ "${CHROMIUM_BIN#/}" = "$CHROMIUM_BIN" ]; then
+  fail "${CHROMIUM_BIN_FILE} contains a relative path — must be absolute"
+fi
+pass "[2/4] ${CHROMIUM_BIN} is an absolute, executable path"
+
+# --- Assertion 3: CDP endpoint responds with version JSON.
+CDP_URL="http://127.0.0.1:${CDP_PORT}/json/version"
+CDP_RESP="$(curl -fsS -m 5 "$CDP_URL" 2>&1 || true)"
+if ! echo "$CDP_RESP" | jq -e '.Browser // empty' >/dev/null 2>&1; then
+  fail "[3/4] ${CDP_URL} did not return Chromium version JSON. Response: ${CDP_RESP:0:500}"
+fi
+pass "[3/4] ${CDP_URL} returns Chromium version JSON"
+
+# --- Assertion 4: vnc-boot.log ends with the success line and never
+#                  emitted `Chromium failed to start` after the most recent
+#                  `[vnc.sh] start` marker.
+[ -r "$VNC_LOG" ] || fail "[4/4] ${VNC_LOG} unreadable"
+LAST_START_LINE=$(grep -n "\[vnc.sh\] start " "$VNC_LOG" | tail -n1 | cut -d: -f1)
+if [ -z "$LAST_START_LINE" ]; then
+  fail "[4/4] ${VNC_LOG} contains no [vnc.sh] start marker — vnc.sh has not been invoked yet"
+fi
+TAIL_AFTER_START=$(tail -n +"$LAST_START_LINE" "$VNC_LOG")
+if echo "$TAIL_AFTER_START" | grep -q "Chromium failed to start"; then
+  fail "[4/4] ${VNC_LOG} since last start contains 'Chromium failed to start' (boot regression)"
+fi
+if ! echo "$TAIL_AFTER_START" | grep -q "VNC + browser stack running"; then
+  fail "[4/4] ${VNC_LOG} since last start has no 'VNC + browser stack running' line — VNC boot incomplete"
+fi
+pass "[4/4] ${VNC_LOG} reports VNC + browser stack running with no Chromium failed-to-start"
+
+echo "Task 929 acceptance: PASS (4/4)"

package/payload/platform/scripts/vnc.sh

@@ -82,6 +82,46 @@ mkdir -p "$LOG_DIR"
 
 log() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" >> "$LOG_FILE"; }
 
+# Task 929 — resolve the absolute Chromium binary path from the install-time
+# config file. The installer (packages/create-maxy/src/index.ts
+# ensureNonSnapChromium + writeChromiumBinaryPathFile) writes this file with
+# the non-snap binary chosen for this device — `/usr/bin/chromium` on Pi
+# Bookworm (real .deb) or `/usr/bin/google-chrome-stable` on Ubuntu Noble
+# laptop where the system `/usr/bin/chromium` realpaths to the snap launcher.
+# Hard-fail when the file is absent or the resolved path is snap-confined:
+# the AppArmor `home` profile denies writes to ~/.{brand}/chromium-profile/
+# and Chromium will never start the CDP listener. Loud fail beats silent
+# fallback (silent-fallback-masks-root-cause).
+CHROMIUM_BIN_FILE="${PLATFORM_ROOT}/config/chromium-binary.path"
+if [ ! -r "$CHROMIUM_BIN_FILE" ]; then
+  log "[vnc.sh:chromium] FATAL: ${CHROMIUM_BIN_FILE} missing or unreadable"
+  echo "ERROR: ${CHROMIUM_BIN_FILE} missing or unreadable." >&2
+  echo "       Re-run the installer to provision a non-snap Chromium (Task 929)." >&2
+  exit 1
+fi
+CHROMIUM_BIN="$(head -n1 "$CHROMIUM_BIN_FILE" | tr -d '[:space:]')"
+if [ -z "$CHROMIUM_BIN" ]; then
+  log "[vnc.sh:chromium] FATAL: ${CHROMIUM_BIN_FILE} is empty"
+  echo "ERROR: ${CHROMIUM_BIN_FILE} is empty — re-run installer (Task 929)." >&2
+  exit 1
+fi
+if [ ! -x "$CHROMIUM_BIN" ]; then
+  log "[vnc.sh:chromium] FATAL: configured CHROMIUM_BIN=${CHROMIUM_BIN} is not executable"
+  echo "ERROR: configured Chromium binary ${CHROMIUM_BIN} is not executable — re-run installer (Task 929)." >&2
+  exit 1
+fi
+CHROMIUM_REALPATH="$(readlink -f "$CHROMIUM_BIN" 2>/dev/null || echo "$CHROMIUM_BIN")"
+case ":$(echo "$CHROMIUM_REALPATH" | tr '/' ':'):" in
+  *:snap:*)
+    log "[vnc.sh:chromium] FATAL: CHROMIUM_BIN=${CHROMIUM_BIN} resolves to ${CHROMIUM_REALPATH} (snap-confined)"
+    echo "ERROR: configured Chromium ${CHROMIUM_BIN} resolves to ${CHROMIUM_REALPATH} which is snap-confined." >&2
+    echo "       Snap AppArmor denies writes to ~/.{brand}/chromium-profile/. Re-run installer to install Google Chrome (Task 929)." >&2
+    exit 1
+    ;;
+esac
+CHROMIUM_CONFINEMENT="non-snap"
+log "[vnc.sh:chromium] bin=${CHROMIUM_BIN} realpath=${CHROMIUM_REALPATH} confinement=${CHROMIUM_CONFINEMENT}"
+
 kill_stale() {
   # Brand-scoped matchers (Task 553): pkill on --user-data-dir narrows the
   # Chromium kill to this brand's profile only, so two brands on the same
@@ -229,7 +269,7 @@ start_chrome_on() {
   mkdir -p "${CHROMIUM_PROFILE_DIR}"
   log "Starting Chromium on ${target_display} (${label}) profile=${CHROMIUM_PROFILE_DIR} CDP=:${CDP_PORT}"
 
-  DISPLAY="${target_display}" /usr/bin/chromium \
+  DISPLAY="${target_display}" "$CHROMIUM_BIN" \
     --user-data-dir="${CHROMIUM_PROFILE_DIR}" \
     --ozone-platform=x11 \
     --no-sandbox \
@@ -306,7 +346,7 @@ start_chrome_native() {
     env_vars+=("WAYLAND_DISPLAY=${NATIVE_WAYLAND_DISPLAY}")
   fi
 
-  env "${env_vars[@]}" /usr/bin/chromium \
+  env "${env_vars[@]}" "$CHROMIUM_BIN" \
     --user-data-dir="${CHROMIUM_PROFILE_DIR}" \
     "$ozone_flag" \
     --no-sandbox \

package/payload/platform/templates/agents/admin/AGENTS.md

@@ -1,10 +1,12 @@
 # Installed Roles
 
 <!-- Entries written by admin agent when roles are installed. One line per role.
-     Format: - **{name}**: {one-line rule — when to delegate to this role}
-     This exact format is required for reliable Edit-based removal.
+     Format: - **specialists:{name}**: {one-line rule — when to delegate to this role}
+     The `specialists:` prefix is the canonical dispatch ID registered by the SDK;
+     bare names are rejected by the runtime registry. This exact format is also
+     required for reliable Edit-based removal.
 
 Example (populated):
-- **personal-assistant**: Scheduling, platform administration, messaging channels, and browser automation — delegate when a task involves operational work.
-- **research-assistant**: Deep research, knowledge management, and visual production — delegate when a task requires web research or graph reorganisation.
+- **specialists:personal-assistant**: Scheduling, platform administration, messaging channels, and browser automation — delegate when a task involves operational work.
+- **specialists:research-assistant**: Deep research, knowledge management, and visual production — delegate when a task requires web research or graph reorganisation.
 -->

package/payload/platform/templates/agents/admin/IDENTITY.md

@@ -165,8 +165,8 @@ When the user asks what you can do, answer from the specialist domains, admin-ow
 - Think strategically. Surface problems before they become urgent. Recommend actions based on what you know.
 - Never state a future commitment ("I'll flag", "I'll check", "I'll remind") without immediately creating the mechanism to fulfil it — a scheduled event, a task, or a workflow trigger. A commitment without a backing mechanism is a broken promise.
 - Store everything you learn about the business in the graph — not in files.
-- For document ingestion of any kind — PDFs, text, transcripts, web pages, audio, video, single files, archives — delegate to the `database-operator` specialist. Include the document path, the document subject (account owner, the business, a third party, etc. — ask if not obvious from context), and the scope (admin/shared/public — ask if not obvious). **Not** content-producer. content-producer produces documents from the populated graph; it does not ingest. The two are opposite movements through the graph and must never be conflated.
-- For ad-hoc graph operations — pruning orphan nodes, deduplicating entities, adding edges, normalising labels, tidying schema drift — delegate to the `database-operator` specialist. Do not perform these inline; they burn admin-turn token budget and displace the conversational focus. **Not** personal-assistant — PA has no graph-write surface; misdelegation fails at the tool-gate after wasting a turn.
+- For document ingestion of any kind — PDFs, text, transcripts, web pages, audio, video, single files, archives — delegate to the `specialists:database-operator` specialist. Include the document path, the document subject (account owner, the business, a third party, etc. — ask if not obvious from context), and the scope (admin/shared/public — ask if not obvious). **Not** `specialists:content-producer`. content-producer produces documents from the populated graph; it does not ingest. The two are opposite movements through the graph and must never be conflated.
+- For ad-hoc graph operations — pruning orphan nodes, deduplicating entities, adding edges, normalising labels, tidying schema drift — delegate to the `specialists:database-operator` specialist. Do not perform these inline; they burn admin-turn token budget and displace the conversational focus. **Not** `specialists:personal-assistant` — PA has no graph-write surface; misdelegation fails at the tool-gate after wasting a turn.
 
 ## Proactive Commitment Detection
 
@@ -255,6 +255,10 @@ The platform also operates an api-wait-ping liveness gate: a heartbeat-driven st
 
 In managed context mode, conversation history is provided within `<conversation-history>` tags. Use `session-compact-status` to retrieve older archived context if needed.
 
+## Thread resumption after a sub-flow
+
+A "sub-flow" is a self-contained run of tool calls — identity repair, LEARNINGS edit, schema audit, attachment unzip — whose subject is not the operator's last stated intent. After the sub-flow returns, the conversation history still holds the operator's earlier request in full. Resume that thread yourself: name what they were asking, then pick it back up. Do not ask the operator to restate, remind, or repeat the intent. Phrases like "What were you originally asking …", "What did you want me to …", or "Remind me what …" delegate the work of holding the thread to the operator and signal that you have treated the prior turn as if it were wiped — when it was not. The exhibit for this rule is the L:2611 turn in stream-4683bd3f, where an OWNS-edge repair returned successfully and the next sentence asked the operator to restate the calendar question they had been pursuing for a thousand prior lines. The platform emits a `[thread-resumption] kind=restate-request` log line when the post-tool assistant text matches one of those phrases, so this regression class is now visible in operations logs even when the operator does not flag it.
+
 ## Tasks
 
 Tasks live in the graph — not in files. The tasks plugin manages them.

package/payload/platform/templates/specialists/agents/content-producer.md

@@ -1,6 +1,6 @@
 ---
 name: content-producer
-description: "Visual production — reads from the populated graph to produce visual artifacts: image generation, PDF rendering, and component delivery. Delegate when a task requires generating images or saving rendered pages as PDF. **Not** document ingestion — ingestion of any kind routes to `database-operator`."
+description: "Visual production — reads from the populated graph to produce visual artifacts: image generation, PDF rendering, and component delivery. Delegate when a task requires generating images or saving rendered pages as PDF. **Not** document ingestion — ingestion of any kind routes to `specialists:database-operator`."
 summary: "Produces visual output from your graph — generates images and renders pages to PDF. For example, when you need a cover image for a brief or want to save a rendered page as PDF."
 model: claude-sonnet-4-6
 tools: mcp__memory__memory-search, mcp__replicate__image-generate, mcp__plugin_playwright_playwright__browser_navigate, mcp__plugin_playwright_playwright__browser_snapshot, mcp__plugin_playwright_playwright__browser_take_screenshot, mcp__plugin_playwright_playwright__browser_pdf_save, mcp__admin__render-component, mcp__admin__file-attach
@@ -12,7 +12,7 @@ You produce visual artifacts and PDF output by reading from the already-populate
 
 ## Out of scope: ingestion of any kind
 
-content-producer reads from the graph to produce; it does not write external input into the graph. All ingestion — PDFs, text, transcripts, web pages, audio, video, single files, archives — routes to `database-operator`. Producing and ingesting are opposite movements through the graph and must never be conflated. If a brief asks you to ingest a document, return immediately and tell the admin agent to redispatch to `database-operator`.
+content-producer reads from the graph to produce; it does not write external input into the graph. All ingestion — PDFs, text, transcripts, web pages, audio, video, single files, archives — routes to `specialists:database-operator`. Producing and ingesting are opposite movements through the graph and must never be conflated. If a brief asks you to ingest a document, return immediately and tell the admin agent to redispatch to `specialists:database-operator`.
 
 ## Prerogatives
 

package/payload/premium-plugins/real-agency/BUNDLE.md

@@ -1,6 +1,6 @@
 ---
 name: real-agency
-description: "UK estate agency skills + Loop CRM integration — 10 sub-plugins covering sales, listings, vendor management, buyer management, lead generation, coaching, business operations, onboarding, teaching, and Loop CRM. 3 specialist roles (negotiator, valuer, compliance). 21 skills + 22 MCP tools."
+description: "UK estate agency skills + Loop CRM integration — 10 sub-plugins covering sales, listings, vendor management, buyer management, lead generation, coaching, business operations, onboarding, teaching, and Loop CRM. 3 specialist roles (negotiator, valuer, compliance). 27 skills + 22 MCP tools."
 plugins:
   - estate-sales
   - listings
@@ -30,10 +30,10 @@ Premium plugin bundle for UK estate agency professionals. Purchasing this bundle
 
 | Sub-Plugin | Skills | MCP Tools | Focus |
 |---|---|---|---|
-| `estate-sales` | 3 | — | Sales cycle — discovery, closing, progression |
+| `estate-sales` | 5 | — | Sales cycle — discovery, closing, progression, negotiation, sales-negotiation |
 | `listings` | 3 | — | Pre-listing through marketing — presentations, campaigns, staging |
 | `vendors` | 2 | — | Active vendor lifecycle — communication, updates |
-| `buyers` | 4 | — | Buyer lifecycle — enquiry, viewing feedback, educational guides |
+| `buyers` | 5 | — | Buyer lifecycle — enquiry, viewing feedback, educational guides, buyer management |
 | `leads` | 2 | — | Pipeline building — nurturing and prospecting |
 | `estate-coaching` | 4 | — | People development — coaching, training, performance |
 | `estate-business` | 4 | — | Business owner skills — growth, operations, brand, partnerships |

package/payload/premium-plugins/real-agency/agents/valuer.md

@@ -33,6 +33,16 @@ Return to the admin agent:
 **People search (sellers):**
 - `loop-people-search` (role: seller) finds vendor records — useful for identifying the property owner and their circumstances
 
+### Recovering from a `loop-property-search` HTTP 400
+
+When `loop-property-search` returns "All teams failed" with `HTTP 400` for every team, the Loop API has rejected the query — most often because `searchTerm` is too long, contains unsupported punctuation, or mixes multiple address lines. Do not retry the same `searchTerm` verbatim; that has been observed to fail identically a second time. Simplify in this order, retrying after each step, and stop as soon as a step returns results:
+
+1. **Drop the postcode.** A full address with postcode is often longer than the API accepts. Try the same query without the postcode segment.
+2. **Drop punctuation.** Apostrophes (e.g. `Bishop's Stortford`) and other non-alphanumeric characters can break the query. Strip them and retry.
+3. **Narrow to house name + town.** If steps 1 and 2 still return 400, reduce to the most distinctive elements — a property name (or street number + street) plus the town.
+
+If all three rungs return 400 or empty, fall back to `loop-property-detail` with a known property ID, or surface "no comparable evidence found" with the simplified queries you tried, so the agent has a record of what was attempted.
+
 ## Market appraisal preparation
 
 When preparing for a valuation, assemble this structure:

package/payload/premium-plugins/real-agency/plugins/buyers/skills/buyer-management/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: buyer-management
+description: "Handle buyer enquiries — qualification, viewing booking, feedback collection, offer capture, and ongoing buyer relationship management."
+publicEmbed: false
+---
+
+# Buyer Management
+
+Guides the full buyer lifecycle — from initial enquiry through qualification, viewing management, feedback collection, and offer capture.
+
+## When to Activate
+
+Someone asks about a property, registers interest, requests a viewing, gives post-viewing feedback, wants to make an offer, or needs rescheduling/cancelling a viewing.
+
+## Reference Table
+
+| Task | When | Reference |
+|------|------|-----------|
+| Quick qualification (5 questions) | Early in conversation to gauge seriousness fast | `references/buyer-qualification-questions.md` |
+| Qualification (full) | New buyer enquiry or property interest | `references/buyer-qualification.md` |
+| Viewing booking | Qualified buyer ready for a viewing | `references/viewing-booking.md` |
+| Feedback collection | After a viewing has taken place | `references/feedback-collection.md` |
+| Offer capture | Buyer wants to make an offer | `references/offer-capture.md` |
+| Buyer scripts & dialogue | Qualifying, encouraging offers, overcoming hesitation | `references/buyer-scripts.md` |
+| Working with buyers (Serhant) | Shoppers vs buyers, elimination process, getting off the fence | `references/buyer-working-scripts.md` |
+| Viewing management | Rescheduling, cancellations, reminders, schedule summaries | `references/viewing-management.md` |
+
+## Key Rules
+
+- Always qualify before booking a viewing — understand their position first
+- One question at a time — don't overwhelm with a qualification form
+- Never disclose vendor circumstances, other offers, or pricing flexibility
+- Never negotiate — gather information and pass to the agent
+- Update the buyer's profile in memory after every interaction
+- Frame everything around helping them, not extracting information
+- Distinguish shoppers from buyers — qualify early, invest time wisely
+- "Buying a home is a process of elimination, not selection" — guide them through narrowing down
+- Post-viewing follow-up within 2 hours — never leave a viewing without a next step
+- An offer is "just a conversation starter" — help hesitant buyers understand nothing is final until exchange
+- Never double-book a property or team member at the same time
+- Access instructions (lockbox codes, keys) are confidential — only share with the conducting agent
+- Two no-shows = flag to agent before booking further viewings

package/payload/premium-plugins/real-agency/plugins/buyers/skills/buyer-management/references/buyer-qualification-questions.md

@@ -0,0 +1,16 @@
+# Buyer qualification — 5 non‑negotiable questions (Tom Panos)
+
+Use these to quickly learn whether a buyer is serious and where their friction is.
+
+1) **How long have you been looking?**
+2) **Have you made any offers on anything?**
+3) **What is the best home you've seen so far?**
+4) **Why didn't you buy that one?**
+5) **If I had a home that was suitable, will you be looking at making an offer?**
+
+## Notes for Max
+- Ask in a friendly, curious tone.
+- Capture the answers verbatim.
+- If #5 is not a clear "yes", they're browsing. Keep warm, don't over-invest.
+
+Source: *Tom Panos — Dialogue to Get More Listings* (Estate Agency Mastermind summary)

package/payload/premium-plugins/real-agency/plugins/buyers/skills/buyer-management/references/buyer-qualification.md

@@ -0,0 +1,59 @@
+# Buyer Qualification
+
+## Purpose
+
+Understand the buyer's situation so the agent can prioritise and serve them effectively. Qualification is not interrogation — it's a conversation that helps you help them.
+
+## The MAN Framework
+
+Gather these three dimensions naturally through conversation:
+
+### Motivation
+- Why are they looking to move?
+- What's their timeline — urgent, browsing, planning ahead?
+- What drew them to this particular property or area?
+- Are they relocating? Upsizing? Downsizing? First-time buyers?
+
+### Ability
+- Do they have a property to sell? If so, what's its status?
+  - Not yet on market → early stage, may need longer
+  - On market → check how long, any interest
+  - Sold STC → stronger position
+  - No property to sell → chain-free (cash or FTB)
+- Are they buying with cash or mortgage?
+- If mortgage, do they have an Agreement in Principle (AIP)?
+- If no AIP, suggest speaking with a mortgage adviser before viewings
+
+### Need
+- What type of property are they looking for? (beds, type, garden, parking)
+- Must-haves vs nice-to-haves
+- Any dealbreakers? (location, condition, budget ceiling)
+- How far along are they in their search — just started or seen several?
+
+## Conversational Flow
+
+Don't ask all of this in one message. Weave it naturally:
+
+1. **Start warm** — thank them for their enquiry, show enthusiasm about the property they've asked about
+2. **Open with motivation** — "What's prompted your move?" or "Are you local to the area or looking to relocate?"
+3. **Bridge to ability** — "Do you have a property to sell, or are you in a position to proceed?" 
+4. **Understand need** — "What's on your wish list for your next home?"
+
+## After Qualification
+
+- **Proceedable** (chain-free, mortgage agreed, or sold STC) → book viewing promptly
+- **Needs steps** (no AIP, property not on market) → suggest next steps gently, keep them warm
+- **Browsing/long-term** → register their requirements, offer to send matching properties
+
+## Memory
+
+Save qualification status to `memory/users/{phone}/profile.md`:
+- Position (FTB, selling, sold STC, cash, renting)
+- Mortgage status (AIP yes/no, cash)
+- Requirements (beds, type, area, budget range)
+- Timeline (urgent, 3-6 months, browsing)
+- Properties of interest
+
+## Tone
+
+Curious and helpful, never clinical. You're having a chat, not filling in a form. If someone volunteers information, don't re-ask it. If they're clearly serious and ready, don't slow them down with unnecessary questions.

package/payload/premium-plugins/real-agency/plugins/buyers/skills/buyer-management/references/buyer-scripts.md

@@ -0,0 +1,63 @@
+# Buyer Scripts & Qualification Dialogue
+*Sources: Tom Panos (Real Estate Gym), Team LANC (Matt Lancashire), Serhant Agent Training Guide*
+
+## Qualifying Questions (Natural Conversation)
+
+Use these naturally — not as a checklist. Weave them into conversation.
+
+**Understanding motivation:**
+- "When buying a home, what's most important for you?"
+- "What's the best home you've seen so far?"
+- "What prevented you from making an offer on that one?"
+- "If there were 3 things you absolutely wouldn't compromise on, what would they be?"
+
+**Getting to an offer:**
+- "At what price on a contract represents great value for you?"
+- "If you could move into the right home next month, would that work for your timing?"
+
+**When a buyer is waiting for the market to bottom:**
+> "The only way to know you've bought at the bottom of the market is when the market goes up. But by then it's too late. Because the only way to know the market was at the bottom is when prices have already gone up. Do you want to make a decision based on the market, or based on your life?"
+
+## Post-Viewing Follow-Up Process
+
+**Within 2 hours of viewing:**
+1. Send warm check-in message (reference specific property, use first name)
+2. Capture overall impression, interest level, positives, concerns
+3. If interested — offer second viewing or next steps
+4. If not interested — ask what they ARE looking for (refine criteria)
+
+**10-Day Follow-Up (if no response or "thinking about it"):**
+- Brief, value-led message — share new comparable that just listed, or market insight
+- Never "just checking in" — always lead with something useful
+
+**Hot Buyer Management:**
+- Maintain a hot buyer list with key criteria
+- When new properties come to market, check against hot buyer criteria within 24 hours
+- Call (don't just text) for strong matches — "I've just seen something that ticks every box you mentioned"
+
+## Encouraging Offers
+
+**When a buyer is hesitant:**
+- "What would need to change for you to feel comfortable making an offer?"
+- "Is it the property itself, or the timing?"
+- "If this property sells to someone else this weekend, would you regret not having put an offer forward?"
+
+**When a buyer lowballs:**
+- Use comparable evidence: "Let me show you what similar properties have actually sold for recently"
+- Frame as collaboration: "Let's find a number that the seller will take seriously, so we don't lose the opportunity to negotiate"
+
+## Getting Buyers Off the Fence (Serhant)
+
+- Show them what they think they want (validates their criteria)
+- Show them the WOW listing (exceeds expectations, creates excitement)
+- Show them the consolation prize (makes the WOW listing feel essential)
+- This is about understanding their emotional journey, not manipulation
+
+## The Flip: Turning Negatives Into Positives
+
+When a buyer raises an objection about a property:
+1. **List the common objections** you expect (small garden, busy road, dated kitchen)
+2. **Find the silver lining** ("A contained garden is easy to maintain and beautify — you'll spend time enjoying it, not mowing")
+3. **Offer a solution** (share photos of beautiful small gardens, connect with a landscaper)
+
+Always acknowledge the concern genuinely before flipping it. Never dismiss a buyer's objection.

package/payload/premium-plugins/real-agency/plugins/buyers/skills/buyer-management/references/buyer-working-scripts.md

@@ -0,0 +1,54 @@
+# Working With Buyers — Scripts & Scenarios
+*Adapted from Serhant Team Agent Training Guide*
+
+## Phase 1: Selling Is ASKING
+
+### Qualify First — Shoppers vs Buyers
+You don't work with shoppers, you work with BUYERS. Determine if they're real:
+
+**Qualifying Questions:**
+1. "Where do you work?" (financial picture)
+2. "Do you currently own or rent?" (experience level + chain status)
+3. "When are you looking to move by? Is there a specific reason?" (urgency + motivation)
+4. "How long have you been looking? Seen anything you liked?" (stage in journey)
+5. "Have you already been pre-approved / spoken to a mortgage adviser?" (readiness)
+
+### Never Meet a Buyer for the First Time at a Listing
+Meet them first — in the office, for coffee, on a call. Understand their needs before showing properties.
+
+### Set Expectations
+List the steps to successfully purchasing a home. Buyers who understand the process make better decisions and don't panic at each stage.
+
+## Phase 2: Selling Is GUIDING
+
+### Elimination, Not Selection
+"Buying a home isn't a process of selection — it's a process of elimination. We'll narrow down what works and what doesn't until we find the right one."
+
+### Ask for Feedback After Every Viewing
+Don't assume silence means disinterest. Start the conversation, get them in the game.
+
+### Make Offers — Get Off the Fence
+Buyers can look forever without a push. Address the hesitation:
+
+"It's never a 'bad' time to buy. As long as you're comfortable with the purchase and don't overstretch yourself, you'll be in good shape."
+
+"I've never had a client who, at completion, said 'I got exactly what I wanted under budget!' — there's always a stretch."
+
+### Encouraging Offers
+"An offer is JUST a conversation starter. Nothing is final until contracts are exchanged."
+
+"What do you think the property is worth? What would you pay? ...[X]? Great — why don't we just see how the vendor responds?"
+
+### Make Them Fall in Love with the PROPERTY, Not the Discount
+Focus on lifestyle, not savings. "Can you see yourself here?" beats "You're getting £10k off."
+
+## Getting Buyers Off the Fence
+
+**Longer-Term Outlook:**
+"Will you be there for 5-10 years? If so, waiting for the 'perfect' property is like not taking a holiday because it might rain."
+
+**The Historical Perspective:**
+"Every buyer thinks it's SO expensive at the time. Then they look back and think they got the best deal ever."
+
+**The iPhone Analogy (for price objections):**
+If a buyer won't pay because the vendor only paid £X before — "How much did you pay for your iPhone? It costs £84 to make."