@rubytech/create-maxy-code 0.1.0

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

@@ -0,0 +1,119 @@
+# Memory Guide
+
+## How Memory Works
+
+{{productName}} maintains a graph of everything you've told it. Contacts, conversations, preferences, relationships, business context — all stored as connected nodes in a local Neo4j database on your Raspberry Pi.
+
+When you ask {{productName}} about something, it searches this graph first. It retrieves relevant context before responding, which is why {{productName}} can pick up where you left off even across separate sessions.
+
+The graph lives entirely on your hardware. Nothing is sent to the cloud.
+
+## What Gets Remembered
+
+{{productName}} stores:
+
+- **Contacts** — people, companies, relationships between them
+- **Conversations** — key decisions, commitments, follow-ups mentioned in chat
+- **Preferences** — things you've told {{productName}} about how you like to work
+- **Context** — project status, ongoing threads, background you've shared
+
+{{productName}} remembers details you mention naturally: "I'm meeting with Sarah on Thursday" creates a memory that Thursday has a meeting with Sarah.
+
+## Telling {{productName}} to Remember Something
+
+Just say it naturally:
+
+- "Remember that I prefer morning calls"
+- "Note that the Johnson account is on hold until March"
+- "My wife's name is Emma, keep that in mind"
+
+{{productName}} will confirm and store it.
+
+## How {{productName}} learns how you work
+
+{{productName}} also learns how you work without you having to teach it deliberately. Six broad areas cover the way most operators run a business — communication, scheduling, decisions, workflow, content, and interaction. Inside each area sits a small set of concrete fields ({{productName}} tracks around 28 in total) such as your preferred channel, quiet hours, workday start time, risk tolerance, content tonality, or address form. {{productName}} tracks which of these specific fields you have spoken into and which are still empty. While any are empty, it folds one organic question per turn into the conversation aimed at the next gap — never a list, never a form, never the same question twice. If you tell {{productName}} a field doesn't apply to you ("I work weekends, weekend availability isn't a thing for me"), it marks that field as covered and never re-asks. Once every field is either set or marked not-applicable, the proactive questions stop and {{productName}} answers what you ask without volunteering more. This is why session 300 should feel sharper than session 3: the longer you work together, the less {{productName}} needs to ask.
+
+## Telling {{productName}} to Forget Something
+
+Be direct:
+
+- "Forget everything about the Johnson account"
+- "Remove Sarah's contact record"
+- "Clear what you know about my pricing preferences"
+- "Delete that pricing guide I uploaded"
+
+{{productName}} will confirm before deleting anything significant. Documents are soft-deleted first (excluded from search but recoverable for 7 days). Say "permanently delete" to remove immediately.
+
+## Managing Documents
+
+### Listing files
+
+Ask: "What files do I have stored?" or "List my attachments"
+
+{{productName}} shows all uploaded files with their ingestion status — whether they've been processed into the knowledge graph.
+
+When you upload something for ingestion, {{productName}} emits a one-line size estimate before it starts: short documents (<5K chars) classify in ~10s; mid-size (10K–20K chars) take ~45–90s; very large (>20K) up to ~3 minutes. If the classifier exceeds its 3-minute ceiling {{productName}} aborts loudly with a "Classifier unavailable — timeout" blocker and writes nothing — you can re-upload or split the document.
+
+### Reading files
+
+Ask: "Show me what's in the pricing guide" or "Read the quarterly report"
+
+{{productName}} returns the full content of text and markdown files, extracted text from PDFs, and metadata for images.
+
+### Editing files
+
+Ask: "Update the pricing in that document" or "Change the introduction paragraph"
+
+{{productName}} reads the file, makes the edit, and prepares it for re-ingestion into the knowledge graph. Only text and markdown files can be edited — PDFs and images cannot.
+
+### Renaming files
+
+Ask: "Rename that file to quarterly-report-q1.pdf"
+
+{{productName}} updates the filename in both the stored metadata and the knowledge graph.
+
+### Deleting documents
+
+Ask: "Delete the old pricing guide"
+
+By default, documents are soft-deleted — they stop appearing in search results but remain recoverable for 7 days. To permanently delete immediately, say "permanently delete" or "force delete".
+
+## Searching Memory
+
+Ask naturally:
+
+- "What do you know about Tom Henderson?"
+- "What did I last discuss about the Acme proposal?"
+- "Who have I met from the fintech conference?"
+
+## Listing and counting
+
+{{productName}} answers relational questions — "list all my people", "how many tasks do I have", "find the person with email X", "show me the 20 most recently created nodes" — via direct read-only Cypher against your Neo4j. This is faster and more precise than semantic search when the question is "the exact set where", not "things similar to".
+
+You can also open a visual view of your graph at any time from the burger menu → **Graph**. Click the **Filter** button in the toolbar to open the filter menu — it lists only the top-level entity types in your schema (Conversation, Person, Task, KnowledgeDocument, …), one row per type, showing your per-type node count and sorted so the most-connected types sit at the top. Child types (messages inside a conversation, sections inside a document), conversation channel variants (admin vs public), message role variants (user vs assistant), and workflow execution plumbing (`ToolCall`, `WorkflowRun`, `WorkflowStep`, `StepResult`) never appear as filter rows — you reach children by clicking the parent and exploring its neighbourhood. Active rows render a force-directed map, coloured by label. Click a node to pivot into its 1-hop neighbourhood; click another node inside that neighbourhood to pivot again. Clicking a Message shows its details in the side panel; the Conversation view stays put — you read sibling messages without losing the chain on canvas. A breadcrumb strip above the canvas shows where you are (`Filter › Conversation › AssistantMessage`). The **Back** control pops one level — three clicks in always undoes with three Back presses; the filter view is the irreducible root. Click the **×** inside the filter menu to clear your chip selection. Type in the search box to highlight matches; submitting a search also widens the filter to include any node types the hits belong to, so relevant matches render instead of disappearing into a "not in current view" banner.
+
+Conversations and Messages carry role/channel sublabels so you can read the chat topology by colour alone — admin vs public conversations and user vs assistant messages render in distinct shades on the canvas. The filter menu intentionally does not split them into separate rows — the base chip is the entry point; you see the variants as colours once you're inside a neighbourhood.
+
+**Save a default view:** once you have the rows you want, click **Set default view** in the filter menu. Next time you open **Graph**, those rows are pre-selected and your data renders immediately. The default is per-admin, per-account — each admin on each account has their own.
+
+**Delete a node:** drag it to the trash icon top-right of the canvas. No confirmation — deletes are reversible for 30 days. To restore, toggle **Show trashed** inside the filter menu and click **Restore** on the node, or ask {{productName}} in chat ("restore the <label> I just deleted"). Deleting a conversation also trashes its messages in the same step, so they reappear together on restore.
+
+**Bulk cleanup of conversations in chat:** when you ask {{productName}} to clean up conversations in bulk ("trash all empty conversations," "clean up the single-assistant tests"), the agent uses a deterministic selector with a fixed set of filter names — it cannot author custom delete queries. The server re-runs the same filter on every candidate before it trashes, so a stale list can't destroy something the filter wouldn't match now. If the filter matches nothing, {{productName}} reports "no candidates" and nothing happens.
+
+The page reads only your own brand's Neo4j — a Maxy device and a Real Agent device share no graph state even when on the same laptop. No credentials are required; the view inherits your admin session.
+
+**Typo-proof cypher.** When {{productName}} runs direct Cypher to answer a relational question, the query is checked against your Neo4j's live label and relationship-type taxonomy before it executes. Cypher that references an unknown name (an edge or label that does not exist in your graph) is rejected for writes and flagged with a warnings header for reads, so {{productName}} never silently acts on a query that targeted the wrong set of nodes. You should not see this — it runs invisibly — but it is the safety net that stops a fabricated edge name from producing "empty" results that are really just unreachable. Before acting on a bulk operation {{productName}} surfaces the result count and a sample; if it ever describes a cypher rejection, that means its first attempt was malformed and it corrected itself.
+
+## Write doctrine
+
+Every new node in {{productName}}'s graph is created with at least one connection to an existing node. A contact connects to the conversation or organisation it came from; a task connects to the session that raised it or the entities it will affect; a session summary connects to the conversation it summarises. A node with no connection is noise — it cannot be attributed, traversed, or explained — so the graph refuses to create one. If {{productName}} ever tries to record something without a link, the write is rejected and {{productName}} asks you to clarify where it belongs.
+
+Every node also carries a provenance stamp — which agent wrote it, in which session, via which tool. You never see these fields, but they are how operators trace unusual growth back to the code path that produced it, and why your graph stays clean over time.
+
+**Two write surfaces, one substrate.** General agents write through schema-aware helpers — {{productName}} can record a new contact, a new commitment, a new preference without ever typing a database query, and the helper enforces the connection-and-provenance rule above structurally. The graph-steward role (the specialist {{productName}} dispatches when you ask for graph hygiene — "merge those two duplicate contacts," "wire those four tasks to the meeting," "rename the legacy label across the graph") additionally has a raw Cypher write tool for the multi-step operations the helpers cannot express. The steward role internalises the same connection-and-provenance discipline in its prompt; a post-write audit emits a warning on every breach so the same rules apply to both surfaces. Both paths feed the same hourly orphan trend and the same forensic provenance fields — read-side, you cannot tell the two apart, and that is the point.
+
+## Privacy
+
+All memory is stored on your local Raspberry Pi. The Neo4j database never leaves your network. {{productName}} does not sync memory to any cloud service or third party.
+
+If you want to wipe everything and start fresh, ask: "Reset my memory graph." {{productName}} will ask for confirmation before doing so.

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

@@ -0,0 +1,90 @@
+# Migration Guide — Taskmaster to {{productName}}
+
+Guide for communicating the migration process to customers moving from Taskmaster to {{productName}}.
+
+## What the customer needs to know
+
+### What stays the same
+
+- **All contacts** are transferred — every person the assistant knows about
+- **Business information** — address, team details, listings, and operational context
+- **Conversation history** — previous chats are preserved as reference material
+- **Media files** — uploaded documents, images, and voice notes are carried over
+- **Access PIN** — the existing login PIN is reused (no new PIN needed)
+
+### What changes
+
+- **The assistant has new names.** Taskmaster's admin agent (e.g., "Ivan") and public agent (e.g., "Jon") are replaced by the {{productName}} equivalents. The migrated data is accessible to the new agents, but the personality and capabilities are upgraded.
+
+- **The web address changes.** Taskmaster used Tailscale URLs (`*.ts.net`) for web access. These are permanently replaced by a new local address (`http://{hostname}.local:{port}`). The old URLs stop working immediately. Provide the customer with their new URL.
+
+- **WhatsApp must be re-paired.** The WhatsApp connection is tied to the physical device session. After migration, the customer must scan a new QR code from their phone to reconnect WhatsApp. This is a one-time step — once paired, it stays connected.
+
+- **Skills are upgraded.** Taskmaster's skills are replaced by {{productName}}'s plugin system. The functionality is equivalent or better, but the names and capabilities may differ.
+
+### What the customer needs to do
+
+1. **Nothing during migration** — the entire process is handled by the operator.
+
+2. **After migration completes:**
+   - Open the new web URL (provided by the operator)
+   - Log in with the existing PIN
+   - **Re-pair WhatsApp:** Open the admin chat, ask the assistant to "Connect WhatsApp" — a QR code will appear. Scan it with the WhatsApp app on their phone.
+   - Test the connection by sending a WhatsApp message to the business number
+
+3. **Update any saved bookmarks or shortcuts** with the new web URL.
+
+4. **Inform team members** (if applicable) about the WhatsApp re-pairing — they don't need to do anything, but may notice a brief gap in automated responses during the transition.
+
+## Communication template
+
+Use this as a starting point for customer communication:
+
+---
+
+**Subject: Your assistant is getting an upgrade**
+
+Hi {customer_name},
+
+We're upgrading your assistant from Taskmaster to {brand_name}. Here's what you need to know:
+
+**What's happening:** We're transferring all your data — contacts, conversations, business info, and files — to the new system. Everything you've built with the assistant carries over.
+
+**What you need to do:**
+1. Open your new web address: {new_url}
+2. Log in with your existing PIN
+3. Reconnect WhatsApp by asking the assistant to "Connect WhatsApp" and scanning the QR code
+
+**Important:** Your old web address ({old_url}) will no longer work. Please update any bookmarks.
+
+**What's better:** {brand_name} includes upgraded capabilities — better scheduling, workflow automation, and an improved chat experience. Your assistant will guide you through the new features.
+
+If you have any questions, just ask!
+
+---
+
+## Operator checklist
+
+Pre-migration:
+- [ ] Export completed successfully (check export summary counts)
+
+Install:
+- [ ] {{productName}} installed (`npx -y @rubytech/create-realagent` or `@rubytech/create-maxy`)
+- [ ] Hostname set correctly (if different from brand default)
+- [ ] Port configured (if different from brand default — override via `~/.{brand}/.env`)
+
+Import:
+- [ ] Import script run (`bash migrate-import.sh ./bundle ~/{installDir}`)
+- [ ] Contacts visible in Neo4j (`cypher-shell` verification query)
+- [ ] PIN accepted (log in via browser to verify)
+
+Knowledge ingestion:
+- [ ] Admin agent told to read and memorise `memory/shared/business.md`
+- [ ] Admin agent told to read and memorise `memory/shared/team.md`
+- [ ] Admin agent told to read and memorise other key shared/admin memory files
+- [ ] "What's the business address?" returns the correct answer in admin chat
+
+Post-migration:
+- [ ] Customer notified of new URL
+- [ ] Customer re-pairs WhatsApp
+- [ ] Old Tailscale URL confirmed dead

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

@@ -0,0 +1,69 @@
+# Outlook Plugin — Operator Guide
+
+The `outlook` plugin gives the admin agent read-only access to Microsoft 365 / Outlook.com via Microsoft Graph. Per-account OAuth (Auth Code + PKCE), encrypted token storage, automatic refresh.
+
+## Quickstart
+
+1. **Register an Entra app once per Maxy install** — see `platform/plugins/outlook/references/auth.md` for full steps. Set `OUTLOOK_CLIENT_ID` (and `OUTLOOK_TENANT_ID`, default `common`) in the operator's environment.
+2. **Per account: register the Outlook account** — in admin chat, ask the agent to "register my Outlook account". The agent runs `outlook-account-register`, which prints an authorization URL.
+3. **Open the URL in the VNC browser** — sign in to your Microsoft account, consent to the requested scopes (`offline_access`, `User.Read`, `Mail.Read`, `Calendars.Read`, `Contacts.Read`).
+4. **Done.** Subsequent tool calls (mail, calendar, contacts) use the persisted refresh token transparently.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `outlook-account-register` | Run the PKCE flow for this account. One-time per account; re-run if tokens expire (90 days) or consent is revoked. |
+| `outlook-mail-list` | Recent mail. Default top=25, folder=Inbox. |
+| `outlook-mail-search` | Microsoft Graph `$search` over the mailbox. |
+| `outlook-calendar-list` | Calendar events in next rangeDays days (default 7, max 365). |
+| `outlook-calendar-event` | Full detail of a single event by id. |
+| `outlook-contacts-list` | Top contacts. Default top=50. |
+| `outlook-mailbox-info` | Health probe — auth state, refresh-window, folder count. |
+
+## Observability
+
+All log lines start with `[outlook-mcp]` and write to `server.log`. They are key=value, account-scoped:
+
+| Event | Line shape |
+|-------|------------|
+| Auth init | `auth-init account=<id> codeChallenge=<sha256-prefix-8> redirectPath=<callback-path>` |
+| Auth callback | `auth-callback account=<id> elapsedMs=<N>` |
+| Auth ok | `auth-ok account=<id> graphUserId=<id> scopes=<csv> tokenExpSec=<N>` |
+| Token refreshed | `token-refreshed account=<id> oldExpSec=<N> newExpSec=<N>` |
+| Refresh failed | `token-refresh-failed account=<id> reason=<err>` (terminal) |
+| Mail list | `mail-list account=<id> folder=<id-or-Inbox> count=<N> elapsedMs=<N>` |
+| Mail search | `mail-search account=<id> query=<trunc-32> count=<N> elapsedMs=<N>` |
+| Calendar list | `calendar-list account=<id> rangeDays=<N> count=<N> elapsedMs=<N>` |
+| Calendar event | `calendar-event account=<id> eventId=<trunc-12> elapsedMs=<N>` |
+| Contacts list | `contacts-list account=<id> count=<N> elapsedMs=<N>` |
+| Mailbox info | `mailbox-info account=<id> tokenWithinRefreshWindow=<bool> folderCount=<N>` |
+| Graph error | `graph-error account=<id> status=<N> code=<graphErrorCode> retryAfterMs=<N-or-null>` |
+| On-prem rejected | `on-prem-rejected account=<id> mailServer=<host>` (terminal) |
+
+## Diagnostic paths
+
+```bash
+# All outlook lines for one account, last 50
+ssh laptop 'grep -E "^\[outlook-mcp\]" ~/.maxy/logs/server.log | grep "account=<id>" | tail -50'
+
+# Token-leak audit — must always return zero
+grep -rn -iE "Bearer |access_token=" ~/.maxy/logs/server.log | head
+```
+
+Latency triage: `mail-list count=0 elapsedMs<200` consistent → permissions issue; `elapsedMs > 5000` → Graph slowness or DNS.
+
+## Failure modes
+
+| Operator-visible message | Cause | Fix |
+|---|---|---|
+| `Outlook not connected for account=X; run outlook-account-register` | Tokens never saved | Run register tool |
+| `Outlook refresh token expired for account=X; run outlook-account-register` | >90 days since last refresh, or consent revoked | Run register tool |
+| `Outlook token refresh failed for account=X; re-auth required` | Network down at refresh time, or refresh token invalidated | Verify network; re-register |
+| `Outlook auth expired for account=X; run outlook-account-register` | Refresh-then-retry still got 401 | Re-register |
+| `Outlook rate-limited without Retry-After hint` | Graph 429 with no backoff guidance | Wait + retry; if persistent, file bug |
+| `Microsoft Graph does not support on-premises Exchange. Use earlier platform fixes (IMAP).` | Mailbox is on hybrid Exchange | Use the `email` plugin |
+
+## Out of scope
+
+Write tools (send, draft, move, flag), OneDrive / Files, push notifications, on-premises Exchange, M365 admin scopes (`User.Read.All`, `AuditLog.Read.All`), public-agent exposure, multi-tenant federation. See `platform/plugins/outlook/PLUGIN.md` for the full out-of-scope list.

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

@@ -0,0 +1,111 @@
+# How {{productName}} Works
+
+## The Short Version
+
+{{productName}} runs on a Raspberry Pi in your home. It uses Claude (Anthropic's AI) as its brain and extends it with plugins — modular capabilities like contacts, Telegram, and memory. Everything stays local: your data, your conversations, your memory graph.
+
+## The Raspberry Pi
+
+{{productName}} is a server that lives on your local network. It's always on, always available, and accessible:
+
+- **Locally:** `maxy.local:19200` (or the IP address of your Pi)
+- **Remotely:** via your personal domain, routed through a Cloudflare tunnel
+
+The Pi runs the web interface, the AI agent, and all the plugin servers. When you send a message, the Pi processes it — not a cloud service.
+
+## The Two Agents
+
+{{productName}} runs two agents simultaneously:
+
+**Admin agent (you)** — full access to all tools and plugins. This is the agent you interact with at your local or remote URL. It can read and write contacts, send Telegram messages, manage your account, and perform any task you have plugins for. Protected by your PIN. Your admin agent runs through your own Claude Code OAuth session — it never bills the Anthropic API. Authentication and SDK details are documented in the developer doc `.docs/platform.md` admin-agent section.
+
+**Public agent (visitors)** — read-only access. Handles enquiries from people who reach your public URL. It can answer questions about your business and collect waitlist signups, but it cannot access your private data or take actions.
+
+## Plugins
+
+Everything {{productName}} can do is provided by a plugin. Each plugin is a self-contained package:
+
+- Behaviour instructions (how the agent should act)
+- Tools (specific actions the agent can take, exposed via MCP servers)
+- Reference documents (detailed knowledge loaded on demand)
+
+Plugins are installed and managed through conversation. You can add marketplace plugins (like Stripe) or use {{productName}}'s built-in ones (contacts, memory, Telegram).
+
+## Roles
+
+{{productName}} has five roles it can dispatch for specific tasks — like members of your team. You don't need to configure or manage them — {{productName}} decides when to use each role and handles everything automatically. You may see activity like "Dispatching personal-assistant..." in the chat timeline when this happens.
+
+| Role | What it does |
+|------|-------------|
+| Personal Assistant | Scheduling, platform administration, messaging channels, and browser automation |
+| Project Manager | Task and project management — creating, tracking, and completing work items |
+| Research Assistant | Web research, knowledge management, and visual production |
+| Content Producer | Document ingestion, image generation, and PDF output |
+| Database Operator | External-archive imports (LinkedIn today; other CRM sources as each one ships) and ad-hoc graph tidy-ups — prune orphans, merge duplicates, add edges |
+
+Roles are installed during setup and listed when {{productName}} introduces itself. Some premium plugins add their own specialists (e.g. the writer-craft plugin adds a manuscript reviewer). Roles installed mid-session become active from the next session.
+
+## Memory
+
+{{productName}} maintains a graph database (Neo4j) of everything you've told it. People, conversations, preferences, and context are stored as connected nodes. When you ask {{productName}} something, it searches this graph to retrieve relevant context before responding.
+
+The memory graph is stored on your Pi. It never leaves your network.
+
+The graph view (at `/graph`) lets you explore the memory directly. Pick a category from the filter, then type to search inside it — typing makes the canvas narrower, not wider. Drag the slider to control how many matches you see (1 to 2000). If the search shows a yellow banner saying "Vector ranking unavailable," it means the local AI ranking model is offline; results are still returned using keyword match, but ordering is less semantic until the ranker recovers.
+
+## The Web Interface
+
+The web app runs on your Pi on port 19200. A small always-on front door (`maxy-edge`) owns that port and the remote terminal transport — so when the Software Update command restarts the app server, the browser-side terminal keeps streaming bytes exactly like an SSH session would. The edge also hosts the update flow's own routes (the sudo prompt, the action launcher, the SSE progress stream, the installed-version poll), so the Software Update modal's log panel does not go blank during the app-server restart window — it keeps receiving lines, heartbeats, and the final exit event unbroken. Login cookies are HMAC-signed with a shared key on disk, so both processes recognise the same session without any coordination and you do not have to log in again after an update. Every request is also classified as LAN or external based on the network shape it arrived on — LAN browsers reach admin directly; the remote password screen only appears on the tunnel-exposed admin domain. It provides:
+
+- **Admin chat** (at `/`) — your primary interface, PIN-protected
+- **Public chat** (at `/{agent-name}`) — visitor-facing agents, each with their own URL. On public hostnames, the root path serves the default agent.
+- **Telegram bot landing** (at `/bot`)
+
+There is no dashboard, no settings panel, no menus. Everything is done through conversation.
+
+The chat input auto-grows as you type — it expands to fit your message and shrinks back when you delete text. You can also drag the resize handle above the input to set a custom height.
+
+The admin interface is a three-pane layout: a sidebar on the left with your brand mark, navigation (Chat, People, Agents, Projects, Tasks, Artefacts), and your recent conversations; the chat in the middle; and an artefact pane on the right that opens when you select a document, click a project, or open Browser, Data, or Graph from the menu — holding the surface side-by-side with the conversation so the chat stays live while you work in it. The sidebar's nav rows swap the list view in place — Chat shows recent conversations, Projects shows your active work projects, and Artefacts lists every KnowledgeDocument plus this account's agent templates (your admin agent's IDENTITY, SOUL, and KNOWLEDGE files plus one entry per enabled specialist). The People, Agents, and Tasks rows are graph shortcuts: clicking each opens the artefact-pane Graph filtered to every Person, every public Agent, or every Task in your account respectively, with no side-list — the graph itself is the result. Public agents become first-class graph entities the moment you create them, with edges to their IDENTITY/SOUL/KNOWLEDGE files, edges to every knowledge document they have access to, and edges from every conversation they have handled, so a single Agents click reveals the whole shape of who knows what and who has been talking to whom. Click an artefact row to open the document. KnowledgeDocuments and your admin agent's templates are editable — type in the document and changes save automatically; specialist agent templates are read-only because they ship with Maxy and your edits would be overwritten on the next install. PDF artefacts render inline so you can read them without leaving the pane. If your browser doesn't have a built-in PDF viewer, a Download button appears instead. Artefacts that have no readable file backing them (orphan rows, files removed from disk, unsupported content types) show a one-line banner explaining the skip instead of opening to a blank pane. Click a project row to open the Graph view focused on that project's neighbourhood — clicking a second project swaps the focus rather than stacking on top. The chat / artefact divider is drag-resizable — drag the line between the columns to make either side wider; double-click it to reset to half of the available width (viewport minus sidebar), clamped to the chat / artefact min-width floors. Your chosen width is remembered across reloads. On wider screens (>1280px) all three panes are visible. The sidebar narrows at 1280px, the artefact pane hides at 1080px (Browser, Data, and Graph then open as full-window pages instead), and the sidebar collapses to a 56px icon rail at 820px. On phones (<720px) the sidebar slides in as a drawer from the left when you tap the brand-mark logo at the start of the chat header (the same logo is the open trigger; inside the open drawer's header, the sidebar toggle is the close affordance) — the drawer animation only fires on tap (220ms slide in or out); resizing your window across the 720px boundary snaps the layout without animation, so you never see a half-open flash. Breakpoint summary: >1280px = full sidebar + chat + artefact pane (drag-resizable divider); 1280px→1080px = sidebar narrows; 1080px→820px = artefact pane hides (Browser/Data/Graph open as full-window pages instead); 820px→720px = sidebar collapses to 56px icon rail; ≤720px = sidebar becomes off-canvas drawer (vertical stack of brand mark, nav, recents list, foot — same shape as the desktop sidebar, just on top of the chat instead of beside it). When the sidebar is collapsed to the 56px icon rail, clicking the Artefacts icon expands the rail back open so the artefact list is visible — the row was previously a silent no-op in collapsed state.
+
+Page titles are brand-aware: the browser tab shows your product name (e.g. `Real Agent` instead of `Maxy`) on every shell — chat, graph, and data — so a non-default brand never leaks the default name in tab strips or browser history.
+
+The Data search panel ranks results by combining vector similarity with keyword (BM25) matching. Each row shows a one-line score breakdown — `vector 0.NN · bm25 0.NN · combined 0.NN` — so you can tell whether a row surfaced because of meaning, exact-keyword match, or both. A bm25 column of `0.00` across every row means your search term wasn't in the keyword index, so ranking fell back to pure vector similarity (this can produce surprising results — the breakdown tells you when to interpret with caution). Above the result list, a chip row shows the unique types in your current results — click one to filter, click again to clear. Click any row to jump straight to that node's neighbourhood in the Graph; from the artefact pane the graph opens alongside chat, from the standalone Data page it opens in place.
+
+## Software Update and Cloudflare Setup
+
+There is no free-form terminal surface in the admin UI — ad-hoc shell access stays on SSH. The two flows that used to need a terminal (upgrade, Cloudflare tunnel setup) run as **detached actions** instead.
+
+**Software Update flow.** Click Upgrade in the modal → the modal asks for your sudo password once → the admin server validates it and launches a transient `systemd-run --user` unit running `npx -y @rubytech/create-maxy@latest`. The action unit is a peer of the brand service (not a child), so the installer's mid-run `systemctl --user restart maxy` does not kill the upgrade itself — it finishes running, then the web UI reloads on the new version. The modal shows a live log panel with three event types:
+- every stdout/stderr line the installer emits, timestamped server-side;
+- a heartbeat every 5 seconds carrying `state=active` + `last_phase` so you can see the installer is alive even during silent phases (tarball download, dep install);
+- a final banner on exit with the return code and elapsed time.
+
+If the browser drops the SSE connection mid-upgrade (typical during the maxy restart window), the panel reconnects within two seconds and replays any lines you missed from the persisted log.
+
+**Mid-turn stream-drop banners.** If a chat turn ends abruptly the bubble shows one of two messages depending on what actually happened. You see "Server is restarting — reconnect will happen automatically." only when the app server itself emits the restart signal — typically during a Software Update or a Cloudflare setup that re-launches the brand service. You see "Lost connection — retrying." when your browser's connection to the Pi dropped mid-stream while the server was still up — typically a flaky Wi-Fi moment or the tunnel hiccupping. Either way the chat resumes once the connection is back; the previously-rendered messages stay on screen so you don't lose context.
+
+**Cloudflare setup flow.** Same pattern — POST to `/api/admin/cloudflare/setup` launches a `cloudflare-setup` action that runs `~/setup-tunnel.sh <brand> <port> <hostname...>`. When the script emits the OAuth consent URL on stdout, the log panel surfaces an **"Authorise in Cloudflare"** button; clicking it opens the consent page in a new tab. After you approve, the script's callback receives `cert.pem` and the setup continues through `tunnel create`/`route`/`run`. On devices where a VNC Chromium is also running, the script can drive the click via CDP automatically (same button remains a harmless safety net). Setup failures return a `CloudflareSetupError` carrying `inputsAlreadyHeld:{admin,public,apex}` and `discoveryResults:{tunnels,domains}` (from the process-lifetime discovery cache `/tunnels` and `/domains` populate on success); the form appends both fields as a fenced JSON block to the chat-relay body so the agent's next reply quotes held values verbatim rather than re-soliciting hostnames.
+
+**Active-chat stream-log click telemetry.** Clicking "Stream log" in the active chat fetches the URL inline (`/api/admin/logs?type=stream&conversationId=…&download=1`), emits a `[stream-log-click] status=<c> bytes=<n> conversationId=<tail>` line in `server.log` via the `/api/_client-error` event pipe, and downloads the same response. Operator-grep `[stream-log-click] status=404` for client/server identity mismatches.
+
+**Bundle-mtime session prelude.** Each admin session boot stamps `[boot] bundleMtime=<iso> conversationId=<tail>` in `server.log` next to `[plugins] MCP servers for session:`; the value is consumed by the Cloudflare setup route's retry-decision branch (it compares against the most recent terminal `:Task.completedAt`), never by the LLM. The prior `<deployment>` block was removed in 2026-05-13 doctrine fix because the admin LLM read it as narration permission for internal state; the route now owns the retry decision, the agent restates the literal envelope.
+
+**Post-action restatement block (2026-05-13 doctrine fix).** `assembleSystemPrompt` injects `<post-action>actionId=<id> outcome=<completed|failed> phase=<phase> at=<iso></post-action>` into the system prompt whenever the dispatcher resolves a terminal `:Task {kind:"cloudflare-tunnel-login"}` on the conversation. Agent-type-agnostic. The IDENTITY clause "If `<post-action>` is present, restate the literal outcome and stop" routes the operator-visible reply. Observability: `[post-action-block] injected|no-prior-action|lookup-failed` log line every turn.
+
+**Admin reply scrub (2026-05-13 doctrine fix).** Closed-list token scrub at `platform/ui/app/lib/admin-reply-scrub.ts`; tokens `bundle`, `bundleMtime`, `overnight`, `the fix may`, `was patched`, `re-rendering`, `paste the output`, `run the script`, `re-attempt`. Hit records a violation under `llm-narrates-internal-state` (rule_family `extension`) and emits `[admin-reply-scrub] agent=<name> tokens_found=[…] reply_blocked=false`. Future doctrine paragraphs naming a new internal token MUST extend the list in the same PR.
+
+**Sudo password** is prompted once per upgrade. The admin server pipes it to `sudo -S -v` to validate + cache, then forwards it to the action unit via `systemd-run --setenv=SUDO_PASSWORD` so the installer's in-unit `sudo -S` reads it directly — per-TTY sudoers configurations where the user-level cache does not cover a fresh systemd-run unit still work. The password is never written to any log, SSE frame, or persisted file.
+
+**Log files.** Each action writes its full output to `~/.maxy/logs/actions/<actionId>.log` for seven days. `journalctl --user --identifier=maxy-action-<actionId>` gives the systemd-level view.
+
+**Authorisation** is inherited from the same `canAccessAdmin()` gate that wraps every `/api/admin/*` route.
+
+## AI Content Provenance
+
+When your public agent sends a message to someone — via email, WhatsApp, Telegram, or SMS — the platform automatically includes a brief disclosure that the content was generated by AI. This is transparent and cannot be turned off.
+
+- **Email:** an `X-AI-Generated` header and a footer line are added to every outbound email
+- **WhatsApp and Telegram:** a short line is appended to the message body
+- **SMS:** a brief suffix is appended when the message is AI-composed
+
+Messages you write yourself (e.g. typing directly in WhatsApp) are not marked — the disclosure applies only to content composed by the AI agent.

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

@@ -0,0 +1,174 @@
+# Plugins Guide
+
+## What a Plugin Is
+
+A plugin extends what {{productName}} can do. Each plugin adds a focused capability — contacts management, Telegram messaging, scheduling, email, research. Plugins are modular: you enable only what you need.
+
+{{productName}}'s own capabilities are plugins too. Marketplace plugins (like Stripe) work the same way — {{productName}} manages all of them through conversation.
+
+## Plugin Groups
+
+### Core (always active)
+
+These are part of {{productName}}'s foundation and cannot be disabled:
+
+| Plugin | What it does |
+|--------|-------------|
+| `admin` | Platform management — system status, account settings, logs, session control. Also hosts the cross-cutting `plainly` skill: every text-producing agent (admin, public, every specialist) applies a plain-English precision pass to prose returned to humans, as a prime-directive prerogative. Agent-to-machine payloads (image-generate prompts, memory-write arguments, cypher) pass through verbatim. Enforced mechanically by `.claude/hooks/precision-check.sh`. |
+| `memory` | Graph memory — search, write, reindex, and ingest knowledge |
+| `maxy-guide` | User guide and platform documentation (this plugin) |
+| `cloudflare` | Cloudflare Tunnel — remote access via your custom domain |
+| `anthropic` | Claude connection — API key acquisition and configuration |
+| `scheduling` | Calendar and scheduling — events, appointments, recurring triggers. Any activity involving time (date, timestamp, day of week, month, duration) routes through `time-resolve` first. Two read-only tools (`current-datetime`, `time-resolve`) are always available to every public agent regardless of enabled plugins. |
+| `email` | Agent email account — setup, read, send, reply, search, auto-respond |
+| `tasks` | Task lifecycle — create, update, list, relate, complete |
+| `workflows` | Persistent named workflows — reusable instruction sets |
+| `contacts` | CRM contact management — create, lookup, update, list |
+
+### {{productName}} Plugins (user-selectable)
+
+These are enabled during onboarding and can be added or removed at any time. Some plugins enhance a specific specialist role — when enabled, that specialist gains additional capabilities.
+
+| Plugin | What it does | Enhances |
+|--------|-------------|----------|
+| `business-assistant` | Customer enquiries, scheduling, quoting, invoicing, daily briefings | Personal assistant |
+| `sales` | Buying signal detection, closing techniques, objection handling | Personal assistant |
+| `deep-research` | Structured multi-source research — query decomposition, source evaluation, citations | Research assistant |
+| `projects` | Structured project execution — phased sprints, investigations, reviews, retrospectives | Project manager |
+| `telegram` | Telegram bot — BotFather setup, messaging, channels | Personal assistant |
+| `whatsapp` | WhatsApp messaging, pairing, and conversation browsing | Personal assistant |
+| `waitlist` | Waitlist lifecycle — extract sign-ups from conversations, review | — |
+| `replicate` | Image generation — three models for photorealistic, design, and fast draft images | Content producer, Research assistant |
+| `linkedin-import` | Import a LinkedIn Basic Data Export — Profile and Connections today, more CSVs as references land | Database operator |
+| `memory/skills/conversation-archive` | Source-agnostic conversation transcript ingest. One skill for WhatsApp `_chat.txt`, Telegram, Signal, LinkedIn DMs, Zoom transcript, meeting minutes, iMessage, Slack — `--source <enum>` selects the per-source normaliser. Single Bash entry — `bash platform/plugins/memory/bin/conversation-archive-ingest.sh <archive> --source <enum> --owner-element-id <id> --participant-person-ids <csv> --scope <admin\|public>` — runs normalise → operator-confirms owner + every distinct sender → sessionize at gap-hours boundaries (default 12h) → classify each session via Haiku (`memory-classify` with `mode='chat'`) into topic-bounded `:Section:Conversation` chunks → memory-ingest with `parentLabel='ConversationArchive'`, `source=<enum>`. Re-imports are delta-append. Auto-creating participants is forbidden — any sender outside the operator-confirmed closed set LOUD-FAILs with `parser-miss`. Phase 0 ships only `whatsapp`; other normalisers land per-source. Distinct from the live `whatsapp` plugin (Baileys). | Database operator |
+| `memory/skills/conversation-archive-enrich` | Phase 2 for any named `:ConversationArchive` — source-agnostic per-row insight derivation. Operator-triggered (never auto-fires on Phase 1 completion). Walks `:Section:Conversation` chunks in pages via the read-only MCP tool `mcp__memory__conversation-archive-derive-insights`; surfaces high-confidence claims for per-row operator gate (`wire / skip / reject`) over four kinds — `mention`, `task`, `preference`, `observed-relationship`. Idempotent on `(elementId(chunk), kind, contentHash)` — re-runs collapse identical claims. Haiku runs on OAuth (admin-side LLM never the API key); confidence floor is a hedging-avoidance instruction in the system prompt, not a numeric post-filter. | Database operator |
+
+### Claude Official (marketplace)
+
+Third-party plugins from the Claude marketplace:
+
+| Plugin | What it does |
+|--------|-------------|
+| `stripe` | Live access to payment and business data |
+
+### Claude Anthropic Verticals (marketplace, opt-in)
+
+Optional plugins from Anthropic's vertical marketplaces. The installer registers `claude-for-financial-services` and `knowledge-work-plugins` so the install commands work; none are auto-installed. You pick each deliberately during first-run onboarding (Step 1) or by name at any time.
+
+| Plugin | Marketplace | What it does |
+|--------|-------------|-------------|
+| `kyc-screener` | `claude-for-financial-services` | Parses onboarding documents, runs a rules engine, flags gaps. Outputs are draft work product for human review — your compliance specialist owns sign-off. Relevant to UK estate agents under MLR 2017. |
+| `meeting-prep-agent` | `claude-for-financial-services` | Briefing pack before every client meeting, FSI-flavoured templates. Overlaps with the business-assistant calendar-prep flow — choose one deliberately. |
+| `pdf-viewer` | `knowledge-work-plugins` | Live interactive viewer to view, annotate, and sign PDFs — mark up contracts, fill forms, stamp approvals, place signatures, download the annotated copy. Click-through replaces conversation for this surface (v0.2.0, different shape from chat-driven skills). |
+
+Install verbatim:
+
+- `claude plugin install kyc-screener@claude-for-financial-services`
+- `claude plugin install meeting-prep-agent@claude-for-financial-services`
+- `claude plugin install pdf-viewer@knowledge-work-plugins`
+
+Onboarding observability for this group: Step 1 emits `[plugin-onboarding] group=anthropic-verticals presented=3` when the three entries are offered, then `[plugin-onboarding] group=anthropic-verticals accepted=<n> declined=<n>` when Step 1 completes — derived from your submission against the closed set above. Grep `~/.{productName}/logs/server.log` for the full prefix to see both halves of the funnel.
+
+### Premium Plugins
+
+Brand decides which premium plugins ship. Maxy installs ship only `platform/plugins/*`. Real Agent installs ship every plugin under `platform/plugins/*` plus every bundle under `premium-plugins/*`. There is no per-account purchase record; brand identity is the gate.
+
+| 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 (11 sub-plugins) | UK estate agency skills — sales, listings, vendor management, buyer management, lead generation, coaching, business operations, onboarding, teaching, Loop CRM, and property brochures. 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:** Every boot {{productName}} delivers the brand's premium plugins from staging into `platform/plugins/` and stamps `enabledPlugins` against what is actually on disk. No conversation needed — the brand's full set is active from the first turn after install. Updates and reinstalls re-deliver from staging.
+
+Some premium plugins are **bundles** — multiple sub-plugins shipped under one directory in `premium-plugins/`, each independently activatable. For example, Real Agency ships 11 sub-plugins covering different aspects of estate agency work. They are all enabled by default. Sub-plugins you don't want active can be turned off individually with "disable <name>"; enabling or disabling individual sub-plugins does not affect the others.
+
+If you ask {{productName}} about a tool from a plugin your brand does not ship (for example, a Maxy install asking about a Real Agent Loop CRM tool), {{productName}} responds with a structured `<tool-surface-error>` envelope naming the missing plugin and the remedy, rather than improvising with a generic alternative.
+
+**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.
+
+Some premium plugins include specialist helpers that {{productName}} can dispatch for specific tasks (e.g. the writer-craft plugin includes a manuscript reviewer). These are activated automatically when the plugin is enabled.
+
+Some premium plugins include pre-built public agent templates — ready-made configurations for customer-facing agents. When you enable the plugin, {{productName}} shows you what templates are available and offers to create agents from them. You review and approve every file before the agent is created. The template is a starting point — you can edit the identity, personality, plugins, and settings to make it yours. The result is a standard public agent, indistinguishable from one you created from scratch.
+
+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.
+
+## Adding or Removing Plugins
+
+Tell {{productName}}:
+
+- "Enable the Telegram plugin"
+- "Add the Stripe plugin"
+- "Disable the waitlist plugin"
+
+{{productName}} handles the installation or removal. If the plugin requires any setup (API keys, bot tokens, configuration), {{productName}} will walk you through it.
+
+## Viewing Your Plugins
+
+Ask {{productName}}: "What plugins do I have?" or "List my plugins."
+
+## Operator-Authored Plugins (skill-builder output)
+
+Skills you create at runtime through the admin `skill-builder` skill are saved on disk as their own plugin under `data/accounts/{accountId}/plugins/{pluginName}/`. The admin agent calls `mcp__admin__store-skill`, which composes `PLUGIN.md` (on first call) and `skills/{skillName}/SKILL.md` plus any reference files. The agent supplies `pluginName`, `skillName`, `description`, `publicEmbed`, `body`, and optional references — the path is computed by the tool, never by the agent.
+
+These operator-authored plugins survive reinstall because the installer's wipe zone excludes `data/`. At admin session start the platform mirrors `data/accounts/{accountId}/plugins/*` into the runtime plugins directory so the same `parsePluginFrontmatter` / `assemblePublicPluginContent` / `loadEmbeddedPlugins` loaders that read shipped and premium plugins also pick up operator-authored ones — no special-case loader path. The admin agent sees every operator skill by default; per-skill `publicEmbed: true|false` controls which skills surface to the public agent.
+
+To edit an operator-authored skill later, ask {{productName}} to update it — the admin agent re-runs `store-skill` for the same `pluginName`/`skillName` and the new content overwrites in place. To remove one, delete the directory under `data/accounts/{accountId}/plugins/{pluginName}/skills/{skillName}/` (or the whole plugin) — the next session start re-mirrors the remaining skills only.
+
+`pluginName` collisions with shipped plugin names are refused by `store-skill` with a structured error. See [.docs/agents.md](../../../../.docs/agents.md) § "Operator-authored skills as plugin files" for the full contract.
+
+## Brand Templating (for plugin and skill authors)
+
+Skill content, plugin manifests, agent templates, and reference files reference the operator-visible brand name only via the literal `{{productName}}` placeholder. The platform substitutes from `brand.json.productName` at read time — Maxy installs render `Maxy`, Real Agent installs render `Real Agent`, all from the same source content.
+
+**Author rule:** never write the literal string `Maxy` (or any brand name) in shipped skill, plugin, or template content. Use `{{productName}}` whenever the operator should see the brand name. The audit grep `grep -rn "\bMaxy\b" platform/plugins/admin/skills/ platform/plugins/*/skills/ platform/templates/agents/` must return zero matches; a literal brand name is a defect, not a stylistic choice.
+
+The runtime substitution happens at every read site that flows content into a system prompt or operator-visible UI: the admin agent's `plugin-read` tool (references + `PLUGIN.md`), the `skill-load` tool (SKILL.md by skill name — one-call resolver+reader, the canonical primitive for SKILL.md), the public agent's recursive plugin assembly, and `IDENTITY` / `SOUL` / `AGENTS` / `KNOWLEDGE` markdown reads. Missing or empty `productName` hard-fails — there is no fallback to a default brand string. See [.docs/agents.md](../../.docs/agents.md) § "Brand templating" for the full contract.
+
+## MCP Plugin Observability (for plugin authors)
+
+Every `console.error` line from a plugin's MCP server can be teed into the per-conversation agent stream log so a single `logs-read` call returns one conversation's full timeline — agent events and plugin diagnostics interleaved in chronological order.
+
+**Opt-in (one line at the top of the MCP server's entry file):**
+
+```typescript
+import { initStderrTee } from "../../../../lib/mcp-stderr-tee/dist/index.js";
+initStderrTee("your-plugin-name");
+```
+
+After this, every `console.error("[your-tool]...")` from any tool in the plugin appears as `[<iso-ts>] [mcp:your-plugin-name] [your-tool]...` in the per-conversation stream log `claude-agent-stream-{conversationId}.log`, alongside the usual agent events. The raw per-server file `mcp-your-plugin-name-stderr-{date}.log` is still produced for deep-dive grep.
+
+**How the tee decides which file to write to:** the platform sets `STREAM_LOG_PATH` as an environment variable on every MCP server spawn, pointing to the conversation-scoped stream log. The MCP server does not know about conversations — it just trusts `STREAM_LOG_PATH`. Multiple concurrent conversations produce multiple concurrent MCP server processes, each teeing to its own file; no cross-conversation leakage.
+
+**`STREAM_LOG_PATH` reaches every Claude Code child.** The platform now sets `STREAM_LOG_PATH` on the parent `claude` spawn env itself (not only on MCP server envs), so the bundled Bun runtime inherits it and every Bash-tool subprocess the CLI spawns sees it too. Opt-in shell scripts — currently `setup-tunnel.sh`, `reset-tunnel.sh`, and `list-cf-domains.sh` under `platform/plugins/cloudflare/scripts/` — read the variable, guard against a missing value with a loud exit, and tee subprocess output line-by-line into the same per-conversation file. Each spawn writes one `[spawn-env] STREAM_LOG_PATH=set pid=… conversationId=… site=…` line so the env-propagation is auditable per session. The chat UI tails the same file for lines matching `^\[([^\]]+)\] \[([a-z][a-z0-9-]*)((?::[a-z0-9:_-]+)?)\] ` — any lowercase scope shape participates on first write (earlier platform fixes generalised from the pre-592 enum `setup-tunnel|reset-tunnel`) — and emits them as `script_stream` SSE events; see `.docs/web-chat.md` for the contract. Inner-layer helpers that a.sh wrapper spawns (e.g. `list-cf-domains.ts` via `node --experimental-strip-types`) must write phase lines directly to `STREAM_LOG_PATH` rather than relying on stderr propagation; the build-gate `platform/ui/scripts/check-stream-log-contract.mjs` enforces this and is the definitive reference for the three allowed patterns (tee-wrapped, direct-write, or explicit stderr-only marker).
+
+**Retrieve MCP diagnostic lines for a conversation:**
+
+- All servers: `logs-read { type: "system", conversationId: "..." }` → grep `[mcp:<name>]` on the returned stream log.
+- One server raw feed: `logs-read { type: "mcp" }` → tails the most recent `mcp-<name>-stderr-*.log` (per-plugin, not per-conversation).
+
+**Tee-state markers** land in the stream log: `[platform] [mcp-tee-attach] server=<name> streamLogPath=...` when the tee wires up, `[platform] [mcp-tee-skip] server=<name> destination=... reason=...` when a destination fails (missing `LOG_DIR`, unwritable path, `STREAM_LOG_PATH` not set, etc.), `[platform] [mcp-tee-detach] server=<name>` on graceful shutdown. If a server invoked tools but no `[mcp:<name>]` lines appear in the conversation's log, look for the skip marker first.
+
+**Main-subprocess stderr.** The same teeing pattern applies to the main Claude Code subprocess's stderr — every line lands in the per-conversation stream log as `[subproc-stderr] …`, with lifecycle markers `[subproc-stderr-tee-attached] pid=…` and `[subproc-stderr-tee-detached] pid=… bytes=N lines=N`. A `bytes=0 lines=0` detach means the tee was attached but the subprocess emitted nothing on stderr — which is the normal state today, because the Claude Code CLI is a bundled Bun runtime binary that does not honour Node's `NODE_DEBUG` env var. The platform records this explicitly with one line per spawn: `[subproc-debug-unavailable] reason=bundled-bun-binary-ignores-node-debug pid=… cli=claude`. A reader who finds a `[spawn]` without these markers should treat that as a regression of the tee infrastructure, not as silence.
+
+## Failure-path observability contract (earlier platform fixes + earlier platform fixes)
+
+The `initStderrTee` wrapper writes to the per-conversation stream log and per-server raw file via `createWriteStream` — async, buffered. Any diagnostic `console.error(…)` followed by an immediate `process.exit(…)` is lost: the event loop never drains the WriteStream before the process terminates. Same race for any synchronous module-load throw: Node's uncaught-exception handler writes the stack to raw fd 2 and exits before the patched async stream flushes. The platform's `[mcp-init-error] tail="(no stderr file)"` line — operationally useless — is the public symptom of this race.
+
+**Two layers now close the gap, each load-bearing on its own:**
+
+1. **Plugin-side sync-write discipline.** Plugins that call `process.exit` during module load (rare — `graph-mcp` is the in-tree example; it spawns a child at boot to proxy upstream stdio) use `fs.appendFileSync` at every named exit path to guarantee the cause lands in both log destinations before exit. Lines follow the `[mcp:<name>] [<plugin-prefix>] <cause>` format so existing `grep '[mcp:<name>]'` investigator paths work. Each destination is wrapped in its own try/catch — an unwritable log must not mask the primary failure. This is the discipline propagated to any plugin author who knows their failure paths.
+
+2. **Parent-side `mcp-spawn-tee` wrapper.** Every node-based core MCP server is spawned via the `lib/mcp-spawn-tee` wrapper rather than `node <entry>` directly. The wrapper spawns the real entry with `stdio: ['inherit', 'inherit', 'pipe']` and writes child stderr chunks to `${LOG_DIR}/mcp-${name}-stderr-<date>.log` via `appendFileSync` while passing the same chunks through to its own stderr (Claude Code's consumer is unchanged). Synchronous `appendFileSync` survives `process.exit`, so the per-server file captures even (a) module-load throws before `initStderrTee` runs, (b) `MODULE_NOT_FOUND` on the entry script itself, and (c) anything else a plugin author missed. The wrapper writes `[mcp-spawn-tee-attached] server=<name> pid=<n>` on attach and forwards SIGTERM/SIGINT to the child. This is the layer that makes capture independent of plugin discipline. Playwright stays unwrapped because it spawns via `npx`, not `node`.
+
+A third layer closes the same gap from the platform side: when `claude-agent.ts` observes an `init` event with any MCP server reporting `status:"failed"`, it reads the last 512 bytes of `${LOG_DIR}/mcp-<name>-stderr-<date>.log` and emits `[mcp-init-error] server=<name> tail=<quoted>` into the stream log. Absent file → `tail="(no stderr file)"`; empty file → `tail="(empty)"`. With the spawn-tee wrapper now interposing on every core MCP, `tail="(no stderr file)"` post-Task-743 means the wrapper itself is broken — file follow-up.
+
+**Signal inventory after a failed session:** `[init] FAILED MCP servers: <names>` (names), `[mcp-init-error] server=<name> tail=…` (cause for each, from the platform's tail probe), `[mcp-spawn-tee-attached] server=<name> pid=<n>` (proof the wrapper attached), `[mcp-spawn-tee-exit] server=<name> code=<n>|signal=<s>` (proof the wrapper saw the exit), and optionally `[mcp:<name>] [<plugin>] …` from plugin-side sync-writes. Their union gives the investigator three independent sources for the same failure.
+
+**Boot-smoke as publish-time gate.** The memory MCP carries `scripts/boot-smoke.sh` that spawns `dist/index.js` with stub env, sleeps 2s, asserts `kill -0 <pid>`, and reports `[boot-smoke] memory ok|FAILED tail=<n-lines>`. Wired to `prepublish` in `plugins/memory/mcp/package.json`. The pattern is propagatable to other plugin MCPs — it's deliberately not generalised yet because each plugin's stub-env requirements differ (memory needs ACCOUNT_ID + PLATFORM_ROOT + NEO4J_URI + SESSION_ID; others differ).