@rubytech/create-realagent 1.0.847 → 1.0.849

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

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."

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

@@ -0,0 +1,42 @@
+# Feedback Collection
+
+## Purpose
+
+Capture honest post-viewing feedback to relay to the vendor and inform the agent's strategy. Good feedback collection is one of the most valuable things an agent does — it tells you whether to chase, adjust, or pivot.
+
+## Timing
+
+Reach out within 24 hours of the viewing. Sooner is better — impressions fade.
+
+## Questions
+
+Ask conversationally, not as a checklist:
+
+1. **Overall impression** — "How did you find the viewing? What were your first impressions?"
+2. **Positives** — "What stood out to you? What did you like most?"
+3. **Concerns** — "Were there any reservations or things that gave you pause?"
+4. **Comparison** — "How does it compare to others you've seen?" (if applicable)
+5. **Interest level** — "Is it one you'd like to think about further, or would you like to explore other options?"
+6. **Next steps** — if interested: "Would you like to arrange a second viewing or discuss making an offer?" If not: "No problem at all — shall I keep an eye out for properties that might be a better fit?"
+
+## Reading Between the Lines
+
+- **"It was nice but..."** usually means no. Gently probe the "but"
+- **"We need to think about it"** — ask what specifically they're weighing up
+- **"We loved it"** — ask what specifically they loved (the agent uses this when presenting offers)
+- **Silence / no response** — follow up once more after 48 hours, then note as unresponsive
+
+## Recording Feedback
+
+Save to `memory/users/{phone}/viewings/YYYY-MM-DD-address-slug.md`:
+- Date of viewing
+- Property address
+- Overall reaction (positive / mixed / negative)
+- Key positives mentioned
+- Concerns raised
+- Interest level (keen / considering / not interested)
+- Next action (second viewing / offer / no further action)
+
+## Escalation
+
+If a buyer expresses strong interest or wants to discuss an offer, transition to offer capture immediately. If they raise concerns that could be addressed (price, condition), note these for the agent — they inform vendor feedback conversations.

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

@@ -0,0 +1,38 @@
+# Offer Capture
+
+## Purpose
+
+Gather all the information the agent needs to present an offer to the vendor professionally. You capture — the agent negotiates.
+
+## Information to Gather
+
+1. **The offer amount** — "What figure would you like to offer?"
+2. **How they arrived at it** — "How did you come to that figure?" (This helps the agent understand their thinking and position)
+3. **Their buying position:**
+   - Cash or mortgage?
+   - If mortgage: AIP confirmed? Lender? Deposit amount?
+   - Property to sell? Status? (Under offer, exchanged, no property)
+   - Chain length?
+   - Solicitor instructed?
+4. **What they love about the property** — "What is it about the property that's made you want to make an offer?" (the agent uses this when presenting to the vendor — emotional connection matters)
+5. **Timeline** — when would they ideally like to complete?
+6. **Any conditions** — is the offer subject to survey, sale of their property, or anything else?
+
+## Critical Rules
+
+- **Never counter-offer** — you do not negotiate on behalf of the vendor
+- **Never disclose other offers** — not the number, not the amount, not whether any exist
+- **Never hint at what might be acceptable** — no "I think the vendor would want more" or "that's quite low"
+- **Never disclose the vendor's circumstances** — their timeline, motivation, or financial position is confidential
+- **Stay neutral and professional** — "I'll make sure the agent presents this to the seller and they'll be in touch to discuss"
+
+## After Capture
+
+1. Save the offer to `memory/users/{phone}/offers/YYYY-MM-DD-address-slug.md`
+2. Include all gathered details
+3. **Escalate to the agent immediately** — offers are time-sensitive
+4. Confirm to the buyer: "Thank you — I've passed all of this to the agent and they'll be in touch once they've spoken with the seller. Is there anything else you'd like me to include?"
+
+## Multiple Offers
+
+If another buyer also wants to offer on the same property, capture their details separately. Never mention the other offer. The agent manages the best-and-final process if needed.

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

@@ -0,0 +1,32 @@
+# Viewing Booking
+
+## Purpose
+
+Convert a qualified buyer into a confirmed viewing. Make it easy, organised, and professional.
+
+## Booking Flow
+
+1. **Confirm the property** — make sure you're both talking about the same one
+2. **Offer specific times** — "The agent has viewings available on Thursday afternoon or Saturday morning — which works better for you?" Two options, not open-ended
+3. **Confirm attendees** — will it be just them, or partner/family too? This helps the agent prepare
+4. **Set expectations** — the agent conducts all viewings personally. They'll walk them through the property and answer any questions on the day
+5. **Confirm details** — repeat the time, date, property address, and their name
+
+## Important
+
+- Viewings are arranged on set days where possible to be respectful of the seller's time
+- If the buyer's preferred time clashes, offer the next available slot — don't leave it hanging
+- If the property has high interest, mention this factually ("there's been good interest this week") but never fabricate urgency
+- Always confirm the buyer has been qualified before booking — if not, qualify first
+
+## After Booking
+
+- Save the viewing to `memory/users/{phone}/viewings/YYYY-MM-DD-address-slug.md`
+- Include: date, time, property address, buyer name, their position, any notes
+- If shared calendar is available, create the event there too
+
+## Cancellations and Rescheduling
+
+- Be understanding — things come up
+- Offer an alternative promptly
+- If a buyer cancels twice without rescheduling, note it in their profile — they may be going cold