@rubytech/create-siteoffice-code 0.1.256

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

@@ -0,0 +1,188 @@
+# 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.
+
+The tables below are the install catalogue — every plugin the platform can ship. They are not evidence of what is enabled on the current account. For the live install set, ask {{productName}} to call `capabilities-here`.
+
+## 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. This is a prompt-level skill contract, not a hook: each agent's IDENTITY loads `skill-load skillName=plainly` on its first text-producing turn and applies the pass thereafter. Hosts the `superpowers-sprint` skill: structured sprint workflow built on the `superpowers` and `code-review` upstream plugins, dispatched on "run a sprint" or any `.tasks/NNN-*.md` invocation. |
+| `memory` | Graph memory — search, write, reindex, and ingest knowledge |
+| `browser` | Headless browser rendering — `browser-render` runs a JavaScript-heavy page in the device's Chromium and returns its rendered DOM. The JS-rendering leg of retrieval: WebFetch (summary) / `url-get` (verbatim, server-rendered) / `browser-render` (JS-rendered). |
+| `maxy-guide` | User guide and platform documentation (this plugin) |
+| `cloudflare` | Cloudflare Tunnel — remote access via your custom domain |
+| `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 |
+| `prompt-optimiser` | Prompt optimiser — two modes. Chat-app mode turns a rough draft or task description into a single finished, copy-pasteable prompt tuned for Opus 4.7 adaptive thinking (claude.ai, Mac, iOS). In-session mode is applied automatically: a standing `UserPromptSubmit` directive hook (`admin/hooks/prompt-optimiser-directive.sh`) injects context every turn telling the admin agent to restate each non-trivial prompt through this skill and act on the restatement, skipped for one-word confirmations, slash-commands, and direct continuations. Compliance is behavioural — the hook steers the agent, it cannot force the skill call. |
+| `url-get` | Faithful page retrieval — fetches a server-rendered page, writes a verbatim markdown copy to an account-scoped reference file (no model in the path, so no copyright refusal), and returns the cleaned page text (capped) plus the file path. No summary and no subprocess: a caller that wants a summary invokes url-get from a delegated subagent. Use instead of WebFetch when a faithful copy is needed (e.g. ingesting your own published writing). |
+
+### {{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 |
+| `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 |
+| `notion-import` | Import a Notion workspace export (markdown + CSV) — pages, databases, hierarchy, attachments, schema-bounded relations, `@person` mentions account-filtered | Database operator |
+| `obsidian-import` | Import an extracted Obsidian vault — pages map to `:KnowledgeDocument`, wikilinks resolve to intra-vault pages or existing entities, tags become `:DefinedTerm`, embedded images become `:DigitalDocument`. Two-phase tool (dry-run → operator disambiguation → commit). | Database operator |
+| `x-import` | Import an X (Twitter) Basic Data Export — tweet stream renders as one chronological transcript and ingests as a single `:KnowledgeDocument` (`source='x'`); each DM `sessionId` ingests as one `:ConversationArchive` (`source='x-dm'`, keyed on `conversationIdentity`) via `conversation-archive-ingest.sh`. Mentions, replies, and quote-tweet authors resolve to `:Person` on lowercased `xHandle`; every handle and DM senderId confirms against existing nodes (no auto-create). Per-thread KD granularity and `:Post` / `:DirectMessage` labels are explicitly rejected. | Database operator |
+| `substack-import` | Import a Substack "Export your data" archive — per-essay `:KnowledgeDocument {kind:'substack-post'}` via librarian/document-ingest with synthetic stable `attachmentId = "substack-post-${substackPostId}"` (survives Substack edits); one `:KnowledgeDocument {kind:'substack-subscriber-roster'}` per import run with `:MENTIONS {mentionContext:'substack-subscription', tier, totalOpens, totalClicks, lastOpenedAt, lastClickedAt, engagementWindowDays}` to each subscriber `:Person` MERGEd on `(accountId, email)`. Engagement aggregates parsed from `email_activity.csv` (or `subscriber_activity.csv` / `emails.csv`); overwrite-on-reimport. No new label, no new edge type, no new graph writer. Images attach via canonical `:HAS_ENCLOSURE` (or `:MENTIONS` fallback). Bulk-gate at >200 posts or >2000 subscribers. | 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, X DMs — `--source <enum>` selects the per-source normaliser. Single Bash entry — `bash platform/plugins/memory/bin/conversation-archive-ingest.sh <archive> --source <enum> --participant-person-ids <csv> --scope <admin\|public>` — runs normalise → operator-confirms owner + every distinct sender (owner derived from env via Cypher, no flag) → sessionize at the fixed 8h gap → emit one JSON line carrying prepared sessions (turn-attributed text + per-session cursor). The dispatched specialist iterates the sessions in-turn, produces a typed-section JSON chunking for each, and calls the `memory-ingest` MCP tool with `conversationIdentity` set (writes `:ConversationArchive`, source=<enum>) once per session — chunks + cursor advance commit atomically inside one Cypher transaction, so a kill mid-archive resumes from the next session on re-issue without re-classifying anything already written. Re-imports are delta-append. Auto-creating participants is forbidden — any sender outside the operator-confirmed closed set LOUD-FAILs with `parser-miss`. 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 the parent's `:Section` chunks in pages via the read-only MCP tool `mcp__plugin_memory_memory__conversation-archive-list-chunks`; the dispatched specialist reads each chunk in-turn and emits claims under the four-kind contract (`mention`, `task`, `preference`, `observed-relationship`); the skill hands those claims to `mcp__plugin_memory_memory__conversation-archive-derive-insights` for per-kind cypher emission, then runs the per-row operator gate (`wire / skip / reject`). Idempotent on `(elementId(chunk), kind, contentHash)` — re-runs collapse identical claims. Confidence floor is a hedging-avoidance instruction the skill embeds in the specialist's per-chunk prompt, not a numeric post-filter; per Task 433 the LLM step runs in-turn from the dispatched specialist rather than as a server-side OAuth round-trip. | 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`
+
+### Premium Plugins
+
+Brand decides which premium plugins ship. The brand's `shipsPremiumBundles` field in `brand.json` is the gate; three shapes are supported:
+
+- **omitted / false** — ship nothing from `premium-plugins/` (the legacy Maxy default).
+- **`true`** — ship every bundle under `premium-plugins/*` (Real Agent / `realagent-code`).
+- **`["bundle-a", "bundle-b"]`** — ship only the named bundle directories (Maxy Code's `["venture-studio"]`). Names with no matching directory on disk are silently dropped; non-allowlisted bundles are stripped from any account that was previously stamped with them.
+
+There is no per-account purchase record; the brand decides the shipping set.
+
+| 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-agent` | Bundle (13 sub-plugins) | UK estate agency skills — sales, listings, vendor management, buyer management, lead generation, coaching, business operations, teaching, Loop CRM (five value pillars: auto-respond, viewing lifecycle, pipeline mining, listings prospecting, maintenance & preferences), PropertyData market analytics (valuation, sold prices, £/sqft baselines, £/sqft growth, demand-rent, area risk, planning precedent, UPRN matching, property-type distribution), gov.uk EPC floor-area lookup, property brochures, social-share image cards, A4 market reports, and single-address preval packs (full UK address → 4-page A4 PDF covering valuation, area, and demand). 3 specialist roles (negotiator, valuer, compliance) | 4 sub-plugins (estate-sales, buyers, estate-coaching, estate-teaching) |
+| `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 |
+| `venture-studio` | Skills + Agent | Founding-a-business workflow — office-hours discovery, brand pack, zero-to-prototype validation, and the full investor data room (business plan, prospectus, term sheet, deck blueprint, A4 print pipeline). Pre-seeds a `Project` with one `Task` per artefact so nothing gets forgotten. | No — founder-facing only |
+
+**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 Agent ships 10 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 Agent 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 deep-research 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__plugin_admin_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-{sessionId}.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.
+
+**Premium plugins.** Source lives at `premium-plugins/<bundle>/plugins/<name>/mcp/src/` — deeper than platform plugins, so the source-relative import to `platform/lib/mcp-stderr-tee/dist/index.js` uses more `../` segments. The bundler rewrites the compiled output to the canonical `../../../../lib/mcp-stderr-tee/dist/index.js` at staging time and ships `platform/lib/mcp-stderr-tee/{dist,package.json}` into `premium-plugins/<bundle>/lib/mcp-stderr-tee/` so the import resolves at deployed depth. The bundler fails loudly if `platform/lib/mcp-stderr-tee/package.json` is missing (it must pin `type` so install-location parent walks cannot mis-classify the dist file) or if any lib referenced by a rewritten import has no source dist.
+
+**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.
+
+**Bash commands stream straight into the PTY.** Maxy Code's admin and public chat run on the native Claude Code PTY (Task 287). The per-conversation server-side stream log that the retired web-UI dispatcher tailed is gone; agent-invoked Bash commands (including direct `cloudflared` invocations for Cloudflare setup — Task 288) print their stdout and stderr directly, and the PTY renders the output in chat verbatim.
+
+**Retrieve MCP diagnostic lines for a conversation:**
+
+- All servers: `logs-read { type: "system", sessionId: "..." }` → 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).

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

@@ -0,0 +1,94 @@
+# Projects Guide
+
+## What a Project Is
+
+A project is a named body of work with multiple steps, dependencies, and a lifecycle. Unlike standalone tasks, a project has child work items that can depend on each other, a health signal that tracks progress, and lifecycle phases (planning, active, blocked, verifying, complete, abandoned).
+
+Projects are ideal when the user has work involving multiple people, sequential steps, or deliverables — a kitchen refit, a client engagement, a product launch.
+
+## Creating a Project
+
+Tell {{productName}} naturally:
+
+- "Create a project for Mrs. Chen's kitchen refit — strip the old kitchen, plumbing first fix, electrical first fix, install units, then tiling and finishing"
+- "Set up a project for the bathroom renovation, standard tier, due by end of June"
+- "Start a project: boiler install for Sarah Thompson, quick job, just order parts, install, and test"
+
+{{productName}} creates the project and all work items in one step. Dependencies between steps (e.g., "install units after plumbing and electrical") are set up automatically based on the order and relationships you describe.
+
+Each project has a tier that reflects its complexity:
+- **Quick** — straightforward, few steps (e.g., boiler install)
+- **Standard** — moderate complexity, multiple phases (e.g., kitchen refit)
+- **Full** — significant scope, many dependencies (e.g., new build project)
+
+## Checking Project Status
+
+Ask naturally:
+
+- "What are my projects?"
+- "How's the kitchen refit going?"
+- "Show me the Davies bathroom project"
+- "What should I focus on?"
+
+{{productName}} shows project health at a glance:
+- **Green** — on track, no issues
+- **Amber** — warning signs (overdue task or blocker)
+- **Red** — at risk (multiple overdue, critical blocker, or stale)
+
+When you start a new conversation, {{productName}} automatically shows active project summaries so you know where things stand without asking.
+
+## Updating a Project
+
+Tell {{productName}} when things change:
+
+- "Move the kitchen refit to the active phase"
+- "The materials for the kitchen refit are delayed by a week"
+- "Update the Davies bathroom target date to July 15th"
+- "Change the boiler install to a standard tier — it's more complex than we thought"
+
+{{productName}} records phase changes and issues as part of the project's history, creating an audit trail.
+
+## Completing a Project
+
+Tell {{productName}}:
+
+- "Mark the boiler install as done"
+- "Complete the kitchen refit project"
+
+If any work items are still pending, {{productName}} will let you know and ask how to handle them — cancel, defer, or keep working on them.
+
+## Abandoning a Project
+
+If a project is no longer needed:
+
+- "Abandon the Davies bathroom — client cancelled"
+- "Stop the kitchen refit project"
+
+{{productName}} records the reason and marks the project as abandoned.
+
+## Projects vs. Tasks
+
+Use a **task** for standalone work — a single action, a reminder, a follow-up. Use a **project** when the work has multiple steps that depend on each other, a client or stakeholder, and a lifecycle that progresses through phases.
+
+When you describe multi-step work, {{productName}} will ask if you'd like to structure it as a project. Over time, it learns your preference and stops asking.
+
+## Working a Task End to End
+
+Ask {{productName}} naturally:
+
+- "What's outstanding?"
+- "What's on my plate?"
+- "What should I work on next?"
+- "Pick something to do"
+
+{{productName}} reads the ready set for your account, groups the open Tasks under their parent Projects, and asks you to pick one. You pick — it never auto-selects.
+
+Once you pick, the loop runs end to end:
+
+1. **Grounding** — pulls the Task and its surrounding context (parent Project, related documents, prior conversation) so the run starts from what is already known, not a blank slate.
+2. **Delegation** — routes the work to the right specialist surface. A research task goes to deep-research, an email reply to email composition, a document to professional-document, and so on. Nothing is reimplemented inline.
+3. **Write-back** — every artefact produced (document, email, ingested file) is linked to the Task in the graph, progress is logged on the Task, and the Task is closed when done.
+
+This means you can always trace a finished piece of work back to the Task that asked for it, and a Task that says "complete" always has its output attached.
+
+Cross-account access is refused. A Task that belongs to a different account on the same install is invisible to this loop — {{productName}} will not read it, name it, or surface it.

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

@@ -0,0 +1,80 @@
+# Samba Share
+
+Every {{productName}} install provisions a per-brand SMB network share so you can read and write the brand's install folder from Finder, File Explorer, the Files app on iOS, or any SMB-capable client on Android or Linux. No client install required — every modern OS speaks SMB natively.
+
+The share lives next to the rest of the brand. On a device that runs more than one brand, each brand gets its own stanza, its own credentials, and its own lifecycle. Tearing one brand down never touches another brand's share.
+
+## What gets provisioned
+
+The installer runs the same Samba step on every supported footprint — Raspberry Pi, Hetzner Cloud server, and self-hosted Linux laptop. Four sub-steps emit `[install-invariant] samba-provision-<step>` markers in order:
+
+1. **apt** — installs the `samba` package (skipped if `dpkg -s samba` already reports installed, so re-runs don't fight `unattended-upgrades` for the dpkg lock).
+2. **conf** — writes `/etc/samba/smb.conf` with a LAN-only `[global]` section plus a `[<brand>]` stanza pointing at the brand's install directory. The stanza is owned by the install owner (see below) and is marked `read only = no`, `browseable = yes`.
+3. **user** — deferred at install time on a fresh Pi or Hetzner box because there is no PIN to hand to `smbpasswd` yet. The user is created the moment the operator sets a PIN in the admin UI (see "PIN rotation" below).
+4. **units** — `systemctl enable --now smbd nmbd` so the share is reachable as soon as the install finishes.
+
+macOS install is a no-op for this step — the installer logs `samba-provision skipped: platform=darwin` and returns. Mac operators do not get an SMB share against their laptop.
+
+## Share path
+
+| Client | Address |
+|---|---|
+| macOS Finder | `smb://<hostname>.local` then pick the `<brand>` share |
+| Windows Explorer | `\\<hostname>.local\<brand>` |
+| Linux (`mount.cifs`, Nautilus, KDE) | `//<hostname>.local/<brand>` |
+| iOS Files | `smb://<hostname>.local` |
+| Android (Solid Explorer, CX File Explorer) | Host `<hostname>.local`, share `<brand>` |
+
+`<hostname>` is whatever the installer printed at the end of `npx @rubytech/create-<brand>-code install` — usually the brand name on a fresh Pi (`maxy-code.local`, `realagent-code.local`). `<brand>` is the same string — it is also the install folder name under the install owner's home.
+
+If `<hostname>.local` does not resolve from your client (some networks do not route mDNS), fall back to the LAN IP: `smb://192.168.1.50` on macOS, `\\192.168.1.50\<brand>` on Windows.
+
+## Credentials
+
+- **Username** — the Unix user that owns the install on the device. On a Pi or Hetzner box this is `admin`; on a self-hosted Linux laptop it is whatever Linux user ran the installer (for example `neo`). The installer persists this value to `~/.<brand>/.install-owner` so every later read uses the same identity the installer wrote.
+- **Password** — your current {{productName}} PIN. The same PIN that unlocks the admin UI unlocks the SMB share.
+
+Both halves are required. SMB never accepts a guest connection; `map to guest = bad user` is set in the global stanza.
+
+## PIN rotation
+
+There is no separate "SMB password." When you set or rotate the PIN in the admin UI, the platform's `set-pin` route runs `sudo -n smbpasswd -a -s <install-owner>` inline with the new PIN, behind a `NOPASSWD` sudoers grant written at install time and scoped to that exact command.
+
+So:
+
+- On a fresh Pi or Hetzner box, the share is reachable as soon as you set the first PIN. Before that point the `smbpasswd` entry does not exist and the mount fails with a logon error — that is expected.
+- Rotating the PIN re-syncs the SMB password to the new value on the next set-pin request. Mounts using the old PIN start failing immediately; remount with the new PIN.
+- If `set-pin` cannot read `~/.<brand>/.install-owner` (file missing or empty), it logs `[set-pin] smbpasswd sync failed owner=<unknown> rc=-1 reason=install-owner-file-missing` and skips the sync. The PIN still writes to the admin UI, but the SMB mount keeps refusing the new password until the install-owner file is restored.
+
+## LAN-only binding
+
+The `[global]` section binds smbd to loopback plus one LAN interface:
+
+```
+interfaces = lo <lan>
+bind interfaces only = yes
+```
+
+`<lan>` is whichever non-loopback interface has an IPv4 address — `wlan0` preferred, then `eth0`, then the first other interface with an address. If the device has no LAN interface at all, the installer refuses to provision and exits — there is nothing safe to bind to.
+
+This is the structural guarantee that SMB never leaves the LAN, even if upstream firewall rules are misconfigured. The Cloudflare tunnel that fronts the admin UI carries HTTPS only; it does not route SMB. **On a Hetzner box the share is therefore not reachable from the public internet** — operators reach it by `ssh -L 4445:localhost:445 admin@<tunnel-host>` and then mounting `smb://localhost:4445`, or by running the Hetzner box on a private network that the operator's machine also joins.
+
+## Peer-brand lifecycle
+
+A device that hosts more than one brand carries one stanza per brand in `/etc/samba/smb.conf`. The provisioner is idempotent and peer-safe:
+
+- **Install a second brand** — the new brand's stanza is appended next to the existing one. The shared `[global]` section is rewritten to keep the LAN-only directives current but is otherwise unchanged. Peer-brand stanzas are preserved byte-for-byte.
+- **Re-run the installer on an existing brand** — the brand's own stanza is replaced in place. Peer stanzas are not touched.
+- **Uninstall one brand** — only that brand's stanza is stripped. `smbd` is then `reload`ed so the brand share disappears from the running config without dropping connections to peer shares.
+- **Uninstall the last brand** — after the stanza is removed, the uninstaller checks `hasAnyBrandStanza()` and, if false, stops and disables `smbd`/`nmbd`, runs `smbpasswd -x <install-owner>` to drop the smbpasswd entry, and `apt-purge samba`. If any peer stanza remains, the units stay running and the package stays installed — the uninstaller logs `Leaving smbd/nmbd + samba package in place — other brand stanza remains`.
+
+The brand-stanza name is the only identifier the uninstaller matches on, so two brands with different `BRAND.hostname` values cannot collide.
+
+## Troubleshooting
+
+- **"Logon failure" on mount.** The PIN you typed does not match the current `smbpasswd` entry. Set a new PIN in the admin UI and remount. If the PIN was just rotated and the mount still fails, check `~/.<brand>/.install-owner` exists and is non-empty.
+- **Share does not show up in Finder / network browser.** mDNS may not be routed on your network. Mount by LAN IP instead of `<hostname>.local`.
+- **`smbd` not running after install.** Check the install log for the four `[install-invariant] samba-provision-<step>` markers. The `units` step running `systemctl enable --now smbd nmbd` is the last to fire; if it failed the marker prints `fail: <reason>`.
+- **Hetzner share not reachable from outside the box.** This is by design — see "LAN-only binding" above. Use SSH port forwarding.
+
+Also see [Deployment Guide](./deployment.md) for the surrounding install flow, and [Access Control](./access-control.md) for how the brand isolation extends from the admin UI to the SMB share.

package/payload/platform/plugins/docs/references/session-retrospective.md

@@ -0,0 +1,14 @@
+# Insight pass
+
+When you type `/insight` on its own in an admin session, the admin agent runs one extra review over the session so far, then carries on. It walks the conversation and writes down four kinds of thing that would otherwise be lost:
+
+- corrections and learnings you gave the agent during the session,
+- tonal and working-style preferences worth carrying forward,
+- people, decisions, commitments, or business facts that came up but were not yet saved to the graph,
+- typed edges between any new prose-bearing nodes (messages, meetings, notes, pages) and the entities they mention — the auto-extraction pass that "wires the graph" so future questions can hop from a person to the companies they founded to the events they attended.
+
+You can run it whenever you want the brain brought up to date — for example before you open a second session that needs the first session's learnings, preferences, or graph writes.
+
+The pass is one or two messages from the agent, then a short summary of what was written. It runs inside the session you are already in: nothing happens in the background, no second session is spawned, and the session is not closed, reset, or cleared — the conversation continues straight afterward against the same live state. The typed-edge pass itself is delegated to the `database-operator` specialist so the writes land where graph writes are supposed to live.
+
+You can tell the pass ran correctly by the final reply naming the five counts (learnings, tonal observations, graph updates, typed edges accepted, prose nodes scanned). The typed-edge pass is scoped by "what changed since the last completed insight pass," so two passes in a row never re-process the same nodes, and a session that never runs one simply defers its extraction to the next time you type `/insight`.

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

@@ -0,0 +1,82 @@
+# Settings
+
+## Output Style
+
+Controls how {{productName}} communicates with you.
+
+| Style | Behaviour |
+|-------|-----------|
+| `default` | Concise, direct responses — gets to the point |
+| `explanatory` | More detailed responses with educational context — explains reasoning and trade-offs |
+
+**Changing output style:** Tell {{productName}} "Switch to explanatory mode" or "Use default output style."
+
+Changes take effect on the next session. The current session continues with the existing style.
+
+## Effort Level
+
+Controls how much work {{productName}} puts into each task — specifically, how many steps it takes before stopping and checking with you.
+
+| Level | Max turns | Use when |
+|-------|-----------|----------|
+| `low` | 5 | Quick questions, simple lookups |
+| `medium` | 10 | Standard tasks — most daily use |
+| `high` | 20 | Complex multi-step tasks |
+| `auto` | 20 | Let {{productName}} decide (same ceiling as high) |
+| `max` | 40 | Long autonomous workflows |
+
+**Changing effort level:** Tell {{productName}} "Set effort to high" or "Use low effort mode."
+
+Changes take effect on the next session.
+
+## Thinking View
+
+Controls how {{productName}}'s thinking process is displayed in the chat.
+
+| Mode | Behaviour |
+|------|-----------|
+| `default` | Thinking steps shown expanded, tool use collapsed |
+| `expanded` | Everything shown expanded — thinking, tool use, and results |
+| `collapsed` | Everything collapsed — compact view, expand on tap |
+
+**Changing thinking view:** Tell {{productName}} "Show thinking by default", "Show everything expanded", or "Hide thinking."
+
+Changes take effect on the next session.
+
+## Viewing Current Settings
+
+Ask {{productName}}: "What are my current settings?" or "What output style am I using?"
+
+## Default Agent
+
+Controls which public agent serves the root URL (`/`). Visitors who go to your public site without specifying an agent slug see this agent.
+
+**Changing the default agent:** Tell {{productName}} "Make sales the default agent" or "Set the default to support."
+
+The change takes effect on the next page load. The previous default agent remains accessible at its `/{slug}` URL.
+
+## Account Preferences
+
+You can ask {{productName}} to show or change any of the following:
+
+- Default agent (which public agent serves the root URL)
+- Admin model (which Claude model powers the admin agent)
+- Public model (which Claude model powers the public agent)
+- Output style
+- Effort level
+- Context mode
+- Enabled plugins
+
+Tell {{productName}} what you want to change and it handles the rest.
+
+## PIN
+
+Your admin PIN is set during initial setup. To change it, ask {{productName}}: "Change my admin PIN."
+
+{{productName}} will ask for your current PIN to verify, then set the new one.
+
+## Adding admins
+
+To add another admin to your account, tell {{productName}}: "Add {name} as an admin with PIN {pin}." {{productName}} creates the device-level user entry (`users.json`), the account-level role entry (`account.json` admins[]), and the graph identity (Neo4j AdminUser node) — the three stores stay in lockstep. If any leg fails, {{productName}} returns an error naming exactly which store is dirty and what was already written; the admin record is partial and may need manual reconciliation. PINs are unique across all users on the device — a new admin needs a PIN no one else on the device is using.
+
+If you ask {{productName}} to add an admin with a specific PIN and it returns a tier-cap or PIN-collision error, repeat the request with the same PIN every time you retry — otherwise {{productName}} auto-generates a different 4-digit PIN, silently substituting what you asked for.

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

@@ -0,0 +1,31 @@
+# Slides — user guide
+
+The Slides plugin turns a description into a finished, self-contained HTML slide deck. The output is one `deck.html` file — inline CSS and JavaScript, no build step, no dependencies beyond Google Fonts. Open it in any browser, navigate with arrow keys or swipe, and press `P` to export to PDF.
+
+## When to use it
+
+- You need a deck and want to describe what to say rather than format slides by hand.
+- You have an existing `deck.html` and want to add slides, restyle it, or get a critique.
+- You want a presentation that lives as plain text — version-controllable, diffable, and readable without a binary editor.
+
+## The commands
+
+- **`/slides`** — generate a complete deck from a description. Auto-detects the best storytelling format (talk, pitch, sales, board, product launch) and writes a single `deck.html`. You can pass the brief inline (`/slides "a 20-minute talk on AI-assisted development"`) or run it bare and describe in the follow-up.
+- **`/slides-outline`** — draft just the structure (section-by-section) without producing HTML, so you can agree the narrative first.
+- **`/add-slide`** — insert one or more slides into an existing deck, matching its theme and components.
+- **`/slides-theme`** — restyle a deck. Three built-in themes: **Default** (warm, editorial), **Craft** (richer textures, art overlays), **Solid** (glass morphism, gradients). Any other argument is treated as a custom theme described in text or extracted from an attached image.
+- **`/slides-review`** — critique the current deck on storytelling, design, and voice consistency.
+- **`/slides-new-component`** — build a new reusable slide component aligned with the design system's tokens.
+- **`/slides-claus`** — generate a deck using the Solid theme with the Claus storytelling structure.
+
+## Storytelling formats
+
+`/slides` routes to one of six narrative structures based on your brief: conference **talk** (TED-style), **Sequoia** investor pitch, McKinsey **SCR** (situation-complication-resolution), **product launch**, **board update**, and **sales**. Name the format in your brief to force one explicitly.
+
+## What you get
+
+A 25-component design system (title slides, metric cards, quotes, comparison tables, timelines, and more), responsive layout, and three interchangeable themes — all inside one portable file.
+
+## Notes
+
+This is a frozen, vendored copy of the open-source Slides™ framework (MIT). It ships installed and available on every account; enable it per session like any other plugin if it is not already active.

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

@@ -0,0 +1,58 @@
+# Telegram Guide
+
+## What the Telegram Plugin Does
+
+The Telegram plugin connects {{productName}} to a Telegram bot. Once set up, you can:
+
+- Send messages to individuals or groups via {{productName}} ("Send a message to the team: standup in 10 minutes")
+- Receive messages from your Telegram bot and have {{productName}} respond
+- Use Telegram as a channel for {{productName}} notifications and alerts
+
+## Setup
+
+### Step 1: Create a Telegram bot
+
+1. Open Telegram and search for `@BotFather`
+2. Send `/newbot` and follow the prompts to choose a name and username
+3. BotFather will give you a token — it looks like `123456789:ABCdefGhijklMNOpqrstUVWxyz`
+4. Keep this token — you'll need it in the next step
+
+### Step 2: Connect the plugin
+
+Tell {{productName}}: "Set up Telegram" or "Configure the Telegram bot."
+
+{{productName}} will ask for your bot token, then save it and activate the plugin. The bot is now connected.
+
+### Step 3: Start the bot
+
+In Telegram, open your bot and send `/start`. The bot is now active and listening.
+
+## Sending Messages via {{productName}}
+
+Once connected, tell {{productName}} to send messages on your behalf:
+
+- "Send a Telegram message to John: I'll be 10 minutes late"
+- "Message the team channel: server maintenance at 11pm"
+- "Tell Sarah via Telegram that the proposal is ready"
+
+{{productName}} needs a chat ID or username to target a specific person or group. For groups, you'll need to add the bot to the group first.
+
+## Getting a Chat ID
+
+To message a specific person or group, {{productName}} needs their chat ID. The easiest way:
+
+1. Have the person (or yourself) send any message to your bot
+2. Ask {{productName}}: "What chat IDs have messaged the bot recently?"
+3. {{productName}} will look up the message history and show you the IDs
+
+## Message History
+
+Ask {{productName}}: "What messages has the bot received?" or "Show recent Telegram activity."
+
+## Troubleshooting
+
+**Bot not responding:** Check that the bot token is correct — ask {{productName}} "What's my Telegram bot token configured as?" and verify it matches BotFather.
+
+**Can't send to a group:** The bot must be a member of the group. Add it via the group settings in Telegram, then try again.
+
+**Messages not arriving:** Make sure the bot hasn't been blocked. Try sending `/start` to the bot directly.