@rubytech/create-siteoffice-code 0.1.256

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

@@ -0,0 +1,303 @@
+# Deployment Guide
+
+## Hardware Requirements
+
+- Raspberry Pi 5 (16GB RAM minimum) with Raspberry Pi OS, **or**
+- Mac with macOS 14 (Sonoma) or newer — both Apple Silicon and Intel
+- 256GB storage minimum
+- Always-on power and network connection
+
+## macOS install
+
+On macOS the installer uses Homebrew + launchd instead of apt + systemd. No flags are required on a laptop:
+
+```bash
+npx -y @rubytech/create-maxy-code            # default brand
+npx -y @rubytech/create-realagent-code       # realagent brand
+```
+
+**Prerequisite:** Homebrew. If `brew` is missing, the installer refuses with `Homebrew not found. Install from https://brew.sh and re-run.` Install Homebrew once via the official one-liner, then re-run. The installer never installs Homebrew itself.
+
+**Hostname / printed URL.** Without `--hostname`, the installer reads `scutil --get LocalHostName` and prints the completion URL as `http://<that-name>.local:<port>`. No sudo, no system change — your Mac's existing local network name is what mDNS will resolve. With `--hostname <h>`, the installer sets `HostName` / `LocalHostName` / `ComputerName` to `<h>` via `sudo scutil` (one password prompt, all-or-nothing rollback within the three-call batch) so the URL becomes `http://<h>.local:<port>`. Grep `~/.<brand>/logs/install-*.log` for `[create-maxy] darwin-hostname-mode=` to confirm which path ran (`scutil-get`, `scutil-set`, or `brand-fallback`).
+
+**LaunchAgent.** The installer registers `{{productName}}` as a launchd LaunchAgent at `~/Library/LaunchAgents/com.rubytech.<brand-hostname>.plist` — for example `com.rubytech.maxy-code.plist`. Survives logout/login and reboot via `KeepAlive=true` and `RunAtLoad=true`. Two brands on the same Mac get two distinct plists (brand-hostname-keyed), so install order is independent. Use `launchctl print gui/$UID/com.rubytech.<brand-hostname>` for service state. The `[create-maxy] launchd-plist=<path> loaded=true` line in the install log confirms `launchctl bootstrap` accepted the plist; `loaded=false exit=<n>` is the failure signal (run `plutil -lint <path>` to diagnose).
+
+**Cloudflare on darwin.** The installer brew-installs the `cloudflared` binary so it is on PATH, but does not invoke `cloudflared service install` or `cloudflared tunnel route dns` — public reach is opt-in. After install, the operator runs `cloudflared tunnel login` (browser-driven) followed by the existing tunnel-setup flow if they want a public address. Grep `[create-maxy] darwin-cloudflare-skip=true` in the install log to confirm the installer took the documented skip path.
+
+**Uninstall.** `npx -y @rubytech/create-maxy-code uninstall` (or the realagent equivalent) bootsout the LaunchAgent, removes the plist, and deletes `~/.<brand>/`. Homebrew-installed dependencies (curl, git, unzip, jq, poppler, ffmpeg, node@22, neo4j, cloudflared) remain — remove them with `brew uninstall` if you want a clean slate.
+
+**Pre-flight.** macOS < 14 is refused at pre-flight via `parseSwVers` (`sw_vers -productVersion` must be `≥ 14`).
+
+**Diagnostic grep recipe.** After a Mac install, the canonical log path is `~/.<brand>/logs/install-*.log`. One pass tells you everything:
+
+```bash
+grep -E '^\[create-maxy\] (platform|darwin-hostname-mode|darwin-cloudflare-skip|launchd-plist|init-logging FAILED)=' \
+  ~/.<brand>/logs/install-*.log
+```
+
+Every successful Mac install contains, in order: `platform=darwin`, `darwin-hostname-mode=…`, `darwin-cloudflare-skip=true`, every brew install/verify line, `launchd-plist=… loaded=true`. Absence of any of these is the failure signal.
+
+## Initial Setup
+
+The {{productName}} installer handles the full setup. Run it on your Pi:
+
+```bash
+npx -y @rubytech/create-maxy
+```
+
+This installs all dependencies (Node.js, Neo4j, Cloudflare tunnel, Claude Code), configures the platform, and starts all services.
+
+## What the Installer Does
+
+1. Installs system dependencies
+2. Installs Claude Code (the AI engine) and configures it
+3. Installs and starts Neo4j (the memory database)
+4. Installs and configures the Cloudflare tunnel for remote access
+5. Creates your account and sets your PIN
+6. Starts the {{productName}} web server on port 19200
+7. Configures systemd so everything restarts automatically if the Pi reboots
+
+## First admin session — install-time defaults
+
+There is no onboarding state machine. At install time the installer writes three defaults into `data/accounts/<accountId>/account.json` (`enabledPlugins` from the brand's default set, `outputStyle: "default"`, `thinkingView: "default"`) and stamps a minimal `agents/admin/SOUL.md`. Diagnostic lines on the Pi:
+
+```
+[install-defaults] account-json plugins=<n> outputStyle=default thinkingView=default
+[install-defaults] soul-md path=<path>
+```
+
+Grep for both in `~/.<brand>/logs/install-*.log`. Absence after a clean install is the failure signal.
+
+## Plugin cache refresh on upgrade
+
+Claude Code loads each platform plugin's skills, commands, and MCP from a per-install snapshot under `~/.<brand>/.claude/plugins/cache/<marketplace>/<plugin>/<version>/`, recorded as `installPath` in `installed_plugins.json` — not from the live tree. The local marketplaces (`maxy-platform`, `maxy-premium-*`) are *directory sources*: an upgrade overwrites their tree in place with no version bump. `claude plugin install` and `claude plugin update` both short-circuit on the unchanged version, so the snapshot would otherwise freeze at first-install time and newly-shipped skills would never register (Task 643).
+
+The installer therefore **resyncs every directory-source plugin on every run**: `claude plugin uninstall` then `claude plugin install`, the only sequence that rebuilds the snapshot from the live tree. Remote marketplaces (the Anthropic ones, GitHub externals) keep version-pinned idempotence. Diagnostic lines on the Pi:
+
+```
+[plugin-install] recache <name>@<marketplace>
+[plugin-install] audit <name>@<marketplace> live-skills=<n> cache-skills=<m>
+[plugin-install] WARN cache-drift <name>@<marketplace> live-skills=<n> cache-skills=<m>
+```
+
+Grep `~/.<brand>/logs/install-*.log`. After an upgrade every directory-source plugin shows a `recache` line and an `audit` line whose `live-skills` and `cache-skills` counts are equal. A `WARN cache-drift` line — or unequal counts — means the snapshot did not fully rebuild and the running agent will see stale skills.
+
+The first user-domain write the agent attempts (e.g. recording who the operator is) hits the graph-write gate's `Write blocked (no-admin-user)` or `Write blocked (no-local-business)` error. The agent then asks the persona question, persists the answer through the `business-profile` skill or `profile-update.personFields`, and proceeds. The error itself is the signal — grep `Write blocked` in `~/.<brand>/logs/server.log` to confirm.
+
+Cloudflare, WhatsApp, Telegram, and any other dormant capability surfaces on owner request via the `<dormant-plugins>` sentinel the manager injects per-spawn. Execution is the existing plugin skill (`cloudflare:cloudflare`, etc.) — no banner, no per-step flag.
+
+### Per-spawn system-prompt sentinels
+
+Every PTY spawn injects an `--append-system-prompt` block composed of these sentinel sections in fixed order:
+
+| Sentinel | Source | Behaviour on resolve failure |
+|---|---|---|
+| `<host>` | brand.json + boot-time LAN resolution | spawn refuses with `host-context-unresolved` |
+| `<identity>` | `<accountDir>/agents/<role>/IDENTITY.md` | spawn refuses with `identity-unresolved` |
+| `<soul>` | `<accountDir>/agents/<role>/SOUL.md` | spawn refuses with `identity-unresolved` |
+| `<about-owner>` | upstream `loadUserProfile` + `formatProfileSummary` (UI process) | sentinel renders the prose body with `NOTHING (operator-data source unavailable: \`<reason>\`)` on line one; spawn proceeds |
+| `<specialist-domains>` | `<accountDir>/specialists/agents/*.md` frontmatter (UI process) | sentinel omitted when set is empty |
+| `<plugin-manifest>` | enabled plugins' PLUGIN.md frontmatter + skill SKILL.md frontmatter (UI process) | sentinel omitted when set is empty |
+| `<dormant-plugins>` | installed-minus-enabled set from `platform/plugins/` and `account.json`, excluding plugins whose PLUGIN.md frontmatter sets `surface: platform` (platform-shell — ships with every install, never opt-in). Absent `surface` field defaults to `feature` (dormant-eligible). | sentinel omitted when set is empty |
+
+Diagnostic line per spawn (`~/.<brand>/logs/server.log`):
+
+```
+[pty-spawn] sessionId=<id> appendSystemPromptBytes=<n> identityBytes=<n> soulBytes=<n> aboutOwnerBytes=<n> dormantPluginsBytes=<n> pluginManifestBytes=<n> specialistDomainsBytes=<n> accountDir=<path> role=<admin|public> hostname=<h> lanIPv4=<ip> adminUrl=<url> tunnelUrl=<url|none>
+```
+
+The `pty-spawn-start` line additionally carries `hooksResolved=<event1,event2,…>` — the hook event names Claude Code would actually load for that PTY (resolved by walking the same `$CLAUDE_CONFIG_DIR/settings.json` plus the cwd-to-.git path Claude Code itself uses). A Stop hook registered in a settings file outside the loader's scope shows up as a missing event in this list.
+
+Zero `aboutOwnerBytes` on any admin spawn is a regression: the upstream resolver dropped the field entirely. The prose body always carries the unconditional MAXIMISE imperative on line two, so the byte count is positive even on a fresh-account spawn whose line one is `NOTHING`. Zero `dormantPluginsBytes` on a Maxy install with `cloudflare` not enabled is likewise a regression. Zero `pluginManifestBytes` on any account with enabled plugins means the upstream walker failed silently.
+
+The manager also runs a boot-time self-test that renders a fixture compose call against synthetic inputs and refuses to start if any sentinel is missing:
+
+```
+[claude-session-manager] startup-self-test system-prompt-sentinels=ok
+```
+
+LOUD-FAIL output is `startup-self-test system-prompt-sentinels=fail missing=<tag>` followed by an immediate process exit. Catches IDENTITY-promise-vs-emitter drift at boot rather than at the first real spawn.
+
+### Pre-publish boot smoke
+
+`platform/scripts/smoke-boot-services.sh` runs inside `prepublishOnly` of the installer (`packages/create-maxy-code/`). For every service in its `SERVICES` list it builds a synthetic install dir that mirrors what `seed-neo4j.sh` writes on first boot — real templates copied from `platform/templates/agents/admin/*.md` and `platform/templates/specialists/agents/*.md` into both `<accountDir>/` and `<platformRoot>/templates/`, real plugin `PLUGIN.md` manifests, plus a `.claude/` dir for `CLAUDE_CONFIG_DIR`. The fixture stamps the same env shape the installer's systemd unit writes (dummy `NEO4J_URI`/`NEO4J_PASSWORD` — the manager only checks presence at boot; the live cypher gate runs separately). Then it spawns `node dist/index.js`, waits up to 10 s for the `startup-self-test identity-drift=` line (the last startup self-test the manager logs), SIGTERMs, and fails publish if any `boot-failed reason=` or `^\[.*\] fatal ` line appears. The script asserts each of the three startup self-tests (`specialist-tool-drift=ok`, `system-prompt-sentinels=ok`, `identity-drift=ok`) is present — the real-templates fixture is what makes the assertions non-trivial; Task 438 added it after the 0.1.143 / 0.1.147 / 0.1.155 / 0.1.156 install regressions slipped past an empty fixture. The original Task 099 motivation still holds (module-load regressions tsc and vitest miss — e.g. a stray `require()` in an ESM-typed package).
+
+Cypher schema gate (Task 438): the same script applies `platform/neo4j/schema.cypher` to the maintainer's local Neo4j via `cypher-shell`, using `NEO4J_URI` / `NEO4J_USER` / `NEO4J_PASSWORD` env (same shape `seed-neo4j.sh` reads — falls back to `platform/config/.neo4j-password` for the password). The dev's database is the test surface; schema commands use `IF NOT EXISTS` / `IF EXISTS` so re-apply is idempotent. Catches Neo4j 4 → 5 syntax drift (e.g. 0.1.151's `DROP FULLTEXT INDEX`) at publish time, not on a real install. Absence of `cypher-shell` on PATH or unset `NEO4J_URI` fails the gate loudly — the same toolchain the installer requires on every device.
+
+Companion lint: `platform/scripts/check-no-esm-require.mjs` rejects `require(` calls in any `.ts/.tsx/.js` file inside a package with `"type": "module"`, also wired into `prepublishOnly`. Allowlist lives at the top of the script.
+
+## Service Management
+
+{{productName}} runs via systemd and starts automatically on boot. You don't need to start it manually. To check if it's running, ask {{productName}} "Check system status."
+
+If you need to restart the service manually (rare), ask {{productName}} to do it for you.
+
+## Browsing the brand filesystem on your LAN (SMB)
+
+Every install provisions a per-brand SMB share against the brand's install folder. See [Samba Share](./samba.md) for the share path, credentials, per-OS mount instructions, peer-brand lifecycle, and the LAN-only binding posture.
+
+## Remote Access via Cloudflare
+
+{{productName}} uses a Cloudflare tunnel to make your local Pi accessible from anywhere without opening router ports. The tunnel is configured during setup and runs as a background service.
+
+Setting it up: say "Set up remote access." {{productName}} walks you through signing into Cloudflare, picking your domain (if you have more than one on your Cloudflare account), and then shows a form where you pick a short name that becomes your admin address. For example, entering `joel` gives you `https://joel.your-domain.com` for admin access. You can also pick a separate address for the public chat, or leave it blank to skip public access. The form only accepts valid address characters (lowercase letters, numbers, hyphens) — {{productName}} never asks you to type your full URL in chat.
+
+Your admin URL looks like: `https://joel.maxy.chat` (the short name is whatever you picked in the form).
+
+To check the tunnel status: ask {{productName}} "Check Cloudflare tunnel status."
+
+To restart the tunnel: ask {{productName}} "Restart the Cloudflare tunnel."
+
+## Checking Service Status
+
+Ask {{productName}}: "Check system status."
+
+The `system-status` tool reports the health of all services: Neo4j, the web server, the Cloudflare tunnel, and all active MCP servers.
+
+## If {{productName}} Won't Start
+
+From the Pi directly:
+
+```bash
+sudo systemctl status maxy
+sudo journalctl -u maxy -n 50
+```
+
+The logs will show which service failed to start and why. Common causes:
+
+- **Neo4j not started** — run `sudo systemctl start neo4j` and retry
+- **Port 19200 already in use** — check for another process: `lsof -i:19200`
+- **Claude OAuth expired** — the next admin session will prompt you to re-authenticate
+- **NEO4J_URI guard throws** — the admin agent probes device reality at boot and fails closed on three shapes (earlier platform fixessucceeding earlier platform fixes):
+    - `no Neo4j listening on [ports]` — nothing is bound; start `neo4j.service` or `neo4j-<brand>.service`, or edit `NEO4J_URI` to a port a Neo4j is actually running on.
+    - `port:X not listening; only:Y is live` — single-brand device where `.env` names a port the local Neo4j isn't bound to; edit `NEO4J_URI` in `~/{configDir}/.env` to match the live port (shown in the `[neo4j-probe] listening=[…]` log line).
+    - `port:X disagrees with brand.json neo4jPort:Y` — co-tenant device (2+ Neo4js listening) where `.env` names the other brand's port; edit `NEO4J_URI` to match `brand.neo4jPort`, or correct `neo4jPort` in `brand.json` and reinstall. Preserves the earlier platform fixes orphan-write protection on multi-brand devices.
+
+## Systemd units on each device
+
+Each installed brand runs two per-brand `--user` systemd units (earlier platform fixes + — unit filenames are prefixed with the brand's `hostname` so two brands on the same device never share a unit file):
+
+- `{hostname}.service` — the admin + public HTTP server on `127.0.0.1:19201` (public port + 1). Restarted by the upgrade flow; short downtime is expected during steps 8→11 of an upgrade. An earlier fix: the unit carries two port env vars — `PORT=<public>` (canonical public port, read by the upgrade detector) and `MAXY_UI_INTERNAL_PORT=<public+1>` (the port maxy-ui actually binds).
+- `{hostname}-edge.service` — the always-on public listener on the configured port (default 19200). Reverse-proxies HTTP to the main brand service and handles `/websockify` (VNC) WebSocket upgrades locally. An earlier fix: also hosts `/api/admin/actions/*` and `/api/admin/version*` — the Software Update modal's own routes — so the log stream survives the brand service's restart window. Does NOT restart during an upgrade — the browser WebSocket stays connected by construction.
+
+Upgrade and Cloudflare setup run as detached actions: `systemd-run --user` transient units per invocation with stdout+stderr persisted to `~/.maxy/logs/actions/<actionId>.log` and streamed to the UI via SSE. No boot-time service file exists for these.
+
+If an action looks stuck, read `~/.maxy/logs/actions/<actionId>.log` directly for the full output, or `journalctl --user --identifier=maxy-action-<actionId>` for systemd's record.
+
+## Linux laptops: snap-confined Chromium replacement
+
+On Ubuntu 24.04 (Noble) the system Chromium binary at `/usr/bin/chromium` is a symlink into the snap. Snap's AppArmor profile denies writes to hidden directories under your home folder, so the per-brand Chromium profile at `~/.{brand}/chromium-profile/` is unwritable and the VNC browser never starts. Pi installs (Debian Bookworm) are unaffected because Bookworm ships a real `.deb` chromium.
+
+The installer detects this case during system-dependency setup and replaces the snap binary with Google Chrome stable, installed from Google's signed apt repo. The chosen binary's absolute path is recorded in `<INSTALL_DIR>/platform/config/chromium-binary.path` and read by the two call sites that launch Chromium — the VNC service and the in-page Chromium wrapper. (The `browser` plugin never launches its own Chromium; it attaches over CDP to the VNC Chromium that `vnc.sh` starts with `--remote-debugging-port`, so it doesn't consult this path.) If you ever see `chromium-binary.path missing` or `Chromium ... resolves to ... which is snap-confined` in `~/.{brand}/logs/vnc-boot.log`, re-run the installer to re-provision.
+
+The post-install acceptance gate at `platform/scripts/test-laptop-vnc-boot.sh` runs four checks: the configured Chromium realpath is non-snap, the path is absolute and executable, the per-brand CDP port returns Chromium version JSON, and the VNC boot log ends with `VNC + browser stack running` with no preceding `Chromium failed to start`. The gate runs automatically at the end of every install on Linux; manual invocation is `MAXY_PLATFORM_ROOT=<install-dir>/platform <install-dir>/platform/scripts/test-laptop-vnc-boot.sh`.
+
+A separate operator-side harness at `platform/scripts/installer-device-verify.sh <published-version>` runs after every npm publish to confirm the installer reaches a terminal-success marker on each device in the operator's manifest. Two markers are accepted because the installer's CDP probe behaves differently per `DISPLAY_MODE`: `Browser automation ready (CDP connected)` on Pi (virtual display, persistent Chromium) and `[cdp-check] skipped reason=native-display` on laptop (native display, on-demand Chromium). Either is a pass. The harness is operator-only — end users do not run it.
+
+## Plugin registration at install time
+
+The installer registers Claude Code plugins on the device as the last step before the brand service starts. After registration, `claude plugin list` on the Pi shows every Maxy platform plugin shipped by the brand, every premium sub-plugin shipped by the brand, and any external plugins the brand declares (e.g. Telegram, Discord, iMessage from `claude-plugins-official`). Spawned `claude` sessions inherit those plugins from `~/.claude/` — the session manager passes no `--mcp-config` argv.
+
+**Where the manifests come from.** The Maxy plugin source tree uses `PLUGIN.md` (YAML frontmatter) for plugin metadata, not Claude Code's native `.claude-plugin/plugin.json`. At bundle time, `scripts/generate-plugin-manifests.mjs` walks the payload and synthesises a Claude-Code-native `plugin.json` per plugin plus a `marketplace.json` at each tree root. The generator runs in `packages/create-maxy-code/scripts/bundle.js` after platform + premium plugins are copied into the payload, so the deployed install directory carries:
+
+- `<INSTALL_DIR>/platform/plugins/<name>/.claude-plugin/plugin.json` per platform plugin
+- `<INSTALL_DIR>/platform/plugins/.claude-plugin/marketplace.json` (marketplace `maxy-platform`)
+- `<INSTALL_DIR>/premium-plugins/real-agent/plugins/<sub>/.claude-plugin/plugin.json` per sub-plugin
+- `<INSTALL_DIR>/premium-plugins/real-agent/plugins/.claude-plugin/marketplace.json` (`maxy-premium-real-agent`)
+- `<INSTALL_DIR>/premium-plugins/{teaching,writer-craft}/.claude-plugin/plugin.json` for bundle-root plugins
+- `<INSTALL_DIR>/premium-plugins/.claude-plugin/marketplace.json` (`maxy-premium`)
+
+Generator schema:
+
+| Field | Source | Notes |
+|---|---|---|
+| `name` | directory name (or `PLUGIN.md#name`) | Used as `<name>` in `plugin install` |
+| `description` | `PLUGIN.md` frontmatter `description` | Falls back to "{name} plugin" if absent |
+| `version` | `"0.1.0"` | Single version across all generated manifests |
+| `author` | `{ "name": "Rubytech LLC" }` | Object form required by Claude Code's validator |
+| `mcpServers["<name>"]` | only when `mcp/dist/index.js` exists | `{ "type": "stdio", "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/dist/index.js"] }` |
+
+Skills, agents, hooks, and commands directories at the plugin root are auto-discovered by Claude Code — no explicit field needed.
+
+**Install flow** (`registerLocalAndExternalPlugins()` in `packages/create-maxy-code/src/index.ts`):
+
+1. Discover every `.claude-plugin/marketplace.json` under the install directory.
+2. For each one not already in `claude plugin marketplace list`, run `claude plugin marketplace add <dir>`. Pre-existing entries log `[plugin-marketplace] added <name> idempotent=true`.
+3. Snapshot `claude plugin list` once.
+4. Build the desired plugin set = (every local marketplace's plugin entries) + (`brand.json#externalPlugins`).
+5. For each desired plugin not in the snapshot, run `claude plugin install <name>@<marketplace> --scope user`. Already-installed plugins log `idempotent=true`. Failures log `[plugin-install] ERROR <name>@<src> exit=<n> stderr=<short>` but do not abort the installer — one plugin failing must not block the rest.
+
+External channel plugins (telegram, discord) are installed but not configured at install time. The operator pairs a channel by running `/<name>:configure <token>` in a real session; no token is read from the install environment.
+
+**Brand declaration** — `brands/<brand>/brand.json#externalPlugins`:
+
+```jsonc
+"externalPlugins": [
+  { "name": "telegram", "marketplace": "claude-plugins-official", "channelPlugin": true },
+  { "name": "discord",  "marketplace": "claude-plugins-official", "channelPlugin": true },
+  { "name": "imessage", "marketplace": "claude-plugins-official", "channelPlugin": true }
+]
+```
+
+`channelPlugin: true` signals the session manager to include the entry in the spawn-time `--channels plugin:<name>@<marketplace>` argv. The session manager's `/public-spawn` and `/resume` HTTP routes accept an optional `channels: string[]` body field that maps directly to those argv flags. When the field is absent or empty, the spawn argv is byte-identical to today's `['--verbose', '--remote-control']` shape.
+
+**Diagnostic path** — `grep "\[plugin-install\]" ~/.<brand>/logs/install-*.log | tail -50`; compare row count against `cat brand.json | jq '.externalPlugins | length'` plus the on-disk plugin count under `<INSTALL_DIR>/platform/plugins/` and `<INSTALL_DIR>/premium-plugins/`.
+
+**Premium MCP dependency install** — Premium-plugin MCP servers ship `dist/` + `package.json` in the bundle but not `node_modules` (npm pack strips them, same as `server/`). `buildPlatform()` discovers every `<INSTALL_DIR>/premium-plugins/<bundle>/plugins/<plugin>/mcp/package.json` and runs `npm install --omit=dev` there, wiping any prior `node_modules` first. The summary log line `[install] premium-mcp-install dirs=<n>` is emitted before the loop runs, so `dirs=0` is itself a regression signal when a brand ships premium plugins.
+
+## Running multiple brands on one device
+
+A single Pi or laptop can host more than one brand (for example Maxy and Real Agent) side by side. Each brand runs as its own service on its own port, with its own install directory and its own data. Installing one brand does not touch the other.
+
+- **Separate:** each brand has its own install folder (`~/maxy/`, `~/realagent/`), its own config folder (`~/.maxy/`, `~/.realagent/`), its own web port, its own Cloudflare tunnel state, its own edge systemd unit (`maxy-edge.service` vs `realagent-edge.service`), and by default its own Neo4j database (Maxy on bolt port 7687, Real Agent on 7688). Action runner units are transient and per-invocation, not per-brand, so no naming conflict is possible.
+- **Brand-isolated Neo4j:** when a brand provisions a dedicated Neo4j instance (any port other than 7687), the installer stops and disables the apt-package's system `neo4j.service` after enabling the brand-dedicated unit, so only one Neo4j process holds the shared `/var/lib/neo4j/run/` PID file. The seed step receives the brand-correct `NEO4J_URI` and `NEO4J_PASSWORD` as explicit environment variables — the seed script no longer carries a `bolt://localhost:7687` default. A failed dedicated start aborts the install loudly with a journalctl tail; there is no silent fallback to the system instance. Stop/disable targets the literal `neo4j.service` only, so peer brands running their own `neo4j-{brand}.service` are unaffected.
+- **Peer-aware system-unit guard:** before stopping the system `neo4j.service`, the installer checks whether any other brand on the device still depends on it — that is, has `NEO4J_URI=bolt://localhost:7687` in its `~/.<peer>/.env`. If so, the system unit is left enabled and active, and the install log shows `[neo4j] system unit kept active — peer brand <name> depends on port 7687` instead of the usual `[neo4j] disabling system unit` line. This prevents a `create-realagent` install from disabling Maxy's database on a host where Maxy still uses the shared system instance (the earlier platform fixes reproducer on Neo's laptop, 2026-04-28). On single-brand hosts and on multi-brand hosts where every peer runs a dedicated port, behaviour is unchanged. The dedicated unit exports `NEO4J_HOME=<per-brand-data-dir>` alongside `NEO4J_CONF`, so `server.directories.run`, `server.directories.plugins`, and `server.directories.import` resolve per-brand — no collision with `/var/lib/neo4j/run/neo4j.pid`. The conf sed-overrides, mkdir-p, chown, and unit-write are idempotent and re-run on every install, so a host whose prior install left a broken unit recovers on retry.
+- **Shared:** both brands share the system Chromium/VNC stack, the Ollama model server, and the `cloudflared` command itself. Browser automation is serialised — one admin session at a time across both brands.
+
+To install a second brand on a device that already runs the first, just run the other installer. No flags needed for isolation:
+
+```bash
+# Already running Maxy on port 20000. Install Real Agent on a different port:
+npx -y @rubytech/create-realagent --port 19500
+```
+
+Uninstalling one brand removes only that brand's state when the other brand is present: this brand's install folder, config folder, its own Neo4j data (if it runs a dedicated instance; shared data is left alone), its Cloudflare tunnel, and its systemd service. Shared binaries (Ollama, `cloudflared`), apt packages, and device-wide caches (`~/.claude`, `~/.ollama`) are left in place because the other brand is still using them. When no other brand is present, the uninstaller performs a full device decommission as before.
+
+## Version provenance
+
+The version that the burger-menu badge displays is the same string the installer wrote to disk. Five links in the chain, each with its own log signal so a wrong badge can be traced to the broken hop in one grep:
+
+1. `packages/create-maxy-code/package.json` — `version` field. Bumped manually by the operator (`bin/publish-installers.sh:7`) before each publish. Single source of truth for every brand at a given release; the bundle script propagates one bump to every brand.
+2. `packages/create-maxy-code/src/index.ts:3828-3830` — the installer reads its own `package.json` into the `PKG_VERSION` constant at start-up.
+3. `packages/create-maxy-code/src/index.ts:2018` — the installer writes `PKG_VERSION` to `<configDir>/.${BRAND.hostname}-version` and logs `[install] version-marker written path=<absolute> version=<semver>`. Absence of that line in install.log means no marker was written for this run.
+4. `platform/ui/server/routes/admin/version.ts` — the `/api/admin/version` route resolves `config/brand.json` per request, reads `config/.${brandHostname}-version`, and logs `[admin/version] outcome=<...> installed=<...> versionFile=<resolved-path> npmPackage=<resolved-name>`. On any brand.json defect (file missing, parse failure, or missing `hostname` / `npm.packageName` field) it emits one `[admin/version] brand-config-fallback reason=<file-missing|parse-failed|field-missing> field=<hostname|npm.packageName> using=<default>` per (reason, field) pair per process, then falls back to the defaults (`maxy` / `@rubytech/create-maxy`). No fallback line in the process log = brand.json resolved cleanly.
+5. `platform/ui/app/components/header/HeaderMenu.tsx` — the menu renders `v${versionInfo.installed}` from the route's JSON response.
+
+Diagnostic when the menu shows the wrong version:
+
+```bash
+# 1. Marker file actually on disk?
+ssh <device> 'cat ~/.<brand>-code/install/platform/config/.<brandHostname>-version'
+
+# 2. What did the route resolve to?
+ssh <device> 'grep "\[admin/version\]" ~/.<brand>-code/logs/server.log | tail -5'
+
+# 3. Any silent brand.json fallback?
+ssh <device> 'grep "brand-config-fallback" ~/.<brand>-code/logs/server.log'
+```
+
+Empty output from step 3 = brand.json resolved cleanly and the badge reflects the file from step 1.
+
+## Upgrading
+
+To upgrade {{productName}} to the latest version, ask {{productName}}: "Upgrade {{productName}}." The platform checks the current device identity (hostname and port via `system-status`), then re-runs the installer with explicit `--hostname` and `--port` flags to preserve them across the upgrade.
+
+The docs plugin (this plugin) is upgraded in the same step — you always have the documentation that matches your installed version.
+
+### Automatic upgrade alert
+
+{{productName}} checks for new releases on every admin session start — whenever you log in, reload the page, or return to the admin chat. When a newer version is available, the Software Update window opens automatically showing your current and the latest version, with a one-click Upgrade button. Dismissing the window (click outside or the close button) defers the alert until your next login or reload; no alert is shown when you are already on the latest version.
+
+The upgrade runs inside a live terminal embedded in the Software Update window — you see each installation step stream as it happens, and any password prompts from `sudo` appear directly in the terminal for you to answer. Closing the window does not cancel the upgrade; re-opening it reattaches to the same shell so you can see what happened while disconnected.
+
+The header menu's version indicator still reflects real-time status: a green dot means you are up to date, and an accent-coloured dot means an upgrade is available. Opening the menu refreshes the version check, so a long-lived session can still surface an upgrade that became available after login without reloading the page.

package/payload/platform/plugins/docs/references/getting-started.md

@@ -0,0 +1,82 @@
+# Getting Started with {{productName}}
+
+## What {{productName}} Is
+
+{{productName}} is your Operations Manager — an operations layer that runs on a device on your premises. It plays four roles: follows through on your commitments, responds to your customers at any hour, handles your finances (quotes, invoices, chasing), and manages your picture — what's overdue, what's at risk, what needs a decision.
+
+You don't adopt a new system. You just talk, and the organisation happens. {{productName}} connects to your services — WhatsApp, Telegram, email, your contacts, your calendar — and acts proactively. It remembers context across conversations and takes action on your behalf.
+
+Because {{productName}} runs locally, your data stays in your home. It never passes through someone else's cloud.
+
+## The Two Interfaces
+
+**Admin (you)** — accessed at your local address (e.g. `maxy.local:19200`) or remotely via your Cloudflare domain. The admin interface is protected by a PIN. This is where you manage {{productName}}: configure settings, manage contacts, review activity, and have full conversations. The admin agent has access to all your plugins and can take action.
+
+**Public (visitors)** — anyone who reaches your public URL gets the public agent. It handles product enquiries, collects prospect details, and answers questions about your business. It cannot read or write your private data.
+
+## First Power-On (New Device)
+
+If your device has no WiFi configured and no ethernet cable connected, it creates a temporary WiFi network for setup:
+
+1. Power on the device and wait about 60 seconds
+2. On your phone, look for a WiFi network called **{ProductName}-Setup** (e.g. `{{productName}}-Setup`)
+3. Connect to that network — a setup page opens automatically
+4. Select your home WiFi network from the list and enter the password
+5. The device connects to your WiFi and the temporary network disappears
+6. Your phone automatically reconnects to your home WiFi
+
+After WiFi is configured, open your browser and go to `{hostname}.local:19200` (the setup page shows this address).
+
+If you already have ethernet connected, the temporary WiFi network does not appear — go directly to the admin interface.
+
+## First Run
+
+When you first open the admin interface:
+
+1. Set your PIN — this protects access to the admin interface
+2. Connect to Claude — {{productName}} will guide you through connecting to your Claude account
+3. Enter your PIN to log in
+4. {{productName}} walks you through onboarding: choosing which plugins to activate, connecting to WiFi (skip if already configured via the setup network above), setting up remote access, and configuring your account
+
+This setup is resumable — if you close the browser mid-setup, {{productName}} picks up where you left off next time.
+
+After install, a live admin terminal is available inside the Software Update window — your Pi's shell, accessible through the admin UI, for upgrades and any other shell work without needing to SSH.
+
+## How to Use {{productName}}
+
+Conversation is the only interface. Type or speak what you need:
+
+- "Add John Smith to my contacts, he's a potential client from the conference"
+- "Schedule a call with Sarah for Thursday at 2pm"
+- "What did I last discuss with Tom?"
+- "Send a Telegram message to the team: standup in 10 minutes"
+- "Create a one-pager PDF about our new product launch"
+
+{{productName}} understands plain language. You don't need to learn commands or navigate menus.
+
+### Voice Notes
+
+When the text field is empty, a microphone button appears in place of the send button. Tap it to record a voice note — speak naturally and tap send when done. {{productName}} transcribes your voice note and responds to what you said, the same as if you had typed it. You can also pause and resume recording, or tap the trash icon to discard and start over.
+
+Voice recording requires a secure connection (HTTPS). When accessing {{productName}} over the local network via HTTP, use the tunnel URL for voice notes.
+
+You can also drop, paste, or pick an audio file (`.opus`, `.ogg`, `.m4a`, `.mp3`, `.wav`, `.webm`) into the chat composer — for example a voice note forwarded from WhatsApp. The file is transcribed the same way the in-browser recording is, and only the transcript reaches {{productName}}; the audio itself is discarded after transcription.
+
+## What {{productName}} Remembers
+
+{{productName}} maintains a memory graph of everything important: contacts, conversations, preferences, relationships, and context. When you tell {{productName}} something, it stores it. When you ask about something later, it retrieves it.
+
+You can always tell {{productName}} to remember or forget specific things: "Remember that I prefer morning calls" or "Forget what I said about the Johnson account."
+
+## Reaching Your Data When {{productName}} Is Unavailable
+
+If the AI is ever unreachable — network outage, API provider down — you can still access your own data through the **Data** item in the admin header menu. It opens a page with two panels:
+
+- **Graph search** — type a keyword to search your knowledge documents, sections, and notes directly in Neo4j. No AI involved.
+- **Files** — browse everything under your install's `data/` folder. Click a folder to open it, a file to download it. Use **Upload** to drop new files into `data/uploads/`.
+
+Everything on this page works without calling any AI service. It's there so your data is never locked behind an agent that can't respond.
+
+## Getting Help
+
+Ask {{productName}} anything. If you want to know what it can do, just ask: "What can you help me with?" or "How do I set up Telegram?"

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

@@ -0,0 +1,163 @@
+# Graph View
+
+The **Graph** admin page (`/graph`) renders a force-directed view of your
+account's Neo4j subgraph. Labels on the canvas follow the zoom level, so you
+see the most useful identity at every scale.
+
+## Search and pivot
+
+Type a term in the search box to highlight matching nodes on the canvas. Hits get an amber border so you can pick them out of a busy view. Click any highlighted node to open its side panel and pivot into its neighbourhood — both clicks (hit and non-hit) behave identically.
+
+When a search is active and you click a node, the neighbourhood you pivot into is **narrowed to the search-relevant subset**. For example: searching "david" with 175 matches and clicking yourself returns the Davids you're connected to, not your entire LinkedIn graph. The narrowing applies once per pivot — clearing the search and pivoting again returns the full neighbourhood.
+
+Searches reach **every textual property** of every operator-meaningful label, including denormalised fields the platform writes specifically so search can reach them — for example, the current job title of each LinkedIn connection (originally stored on the connection edge, copied to the Person node so the fulltext index can match it).
+
+Search behaves the same here, in the agent's own memory recall, and on the `/data` page: with **no filter chips selected** a search reaches **all** labels — the same scope the agent sees — and every surface applies the **same default relevance floor**, so the same query returns the same nodes everywhere. There is no longer a "select a chip first" gate; an empty chip set means "search everything". Selecting chips narrows the result to those labels.
+
+## Conversation label tiers
+
+Conversation nodes carry the most operator-meaningful identity in the
+subgraph (the conversation name or summary, the date it started, the message
+count). They render in one of three tiers, switched by canvas scale:
+
+| Zoom | Label shape | Example |
+|------|-------------|---------|
+| Zoomed out (< 0.7×) | Compact — one line, capped at 24 characters. Preserves the no-overlap contract that matters when nodes are tightly packed. | `Maxyfi branding conflict…` |
+| Mid zoom (0.7× to 1.3×) | Wrapped — up to two lines of 24 characters each, soft-ellipsis on overflow. Full name is visible without hover. | `Maxyfi branding conflict` / `with Rubytech` |
+| Zoomed in (≥ 1.3×) | Detailed — wrapped name plus a metadata line reading `YYYY-MM-DD · N msgs`. | `Maxyfi branding conflict` / `with Rubytech` / `2026-04-23 · 7 msgs` |
+
+Non-Conversation nodes (People, Messages, Tasks, WorkflowRuns, etc.) keep
+their concise single-line labels at every zoom level — the canvas stays
+readable when you zoom out to see a large subgraph.
+
+Tier transitions are debounced so spinning the scroll wheel does not cause
+label flicker; labels only rewrite once zoom settles on a new tier.
+
+## Cluster-expand on Conversation/Message clicks (cluster-integrity fix)
+
+Clicking a Conversation node OR any Message node pulls the WHOLE
+conversation cluster onto the canvas: the Conversation node itself plus
+every Message belonging to it (via `PART_OF`), capped at 200 messages
+for layout reasons. The arrow chain along the conversation (the `NEXT`
+edges) renders for free because the inter-node relationship pass picks
+up edges where both endpoints are in the visible window.
+
+Pre-fix, clicking a middle Message expanded only its prev+next
+neighbours; the head, tail, and Conversation node dropped off, visually
+disintegrating the conversation. The new behaviour keeps the cluster
+intact across click navigation. `PART_OF` edges are now rendered between
+visible Conversation/Message pairs (previously suppressed because they
+"added no information when the Conversation node wasn't on canvas" — an
+assumption that broke the moment the cluster-expand put it there).
+
+The breadcrumb above the canvas tracks each pivot — every entry except
+the last is clickable to pop the view-stack back to that point.
+
+## Tooltips and side panel
+
+Hovering a node still shows the full 5-line tooltip (display name, labels,
+id, created at, updated at). Clicking a Conversation opens the side panel
+with the full property table — zoom-tier changes never alter these paths.
+
+The side panel carries a **Trash** button for live nodes and a **Restore**
+button for trashed nodes. Soft-delete is reversible: trashed nodes
+remain in the graph and reappear when **Show trashed** is on.
+
+## Deleting a node
+
+Two surfaces, same outcome:
+
+- **Mouse (desktop):** drag a node to the dashed Trash zone in the upper-
+  right corner of the canvas.
+- **Touch (mobile/tablet):** the dashed Trash zone is hidden because
+  vis-network's drag hit-test never fires on touch. Tap the node to open
+  the side panel, then tap **Trash**.
+
+Both paths POST to the same soft-delete endpoint; the operator-side
+behaviour is identical.
+
+## Mobile layout
+
+Below 640px viewport width the toolbar wraps: the search input claims
+its own row, the search-result slider claims its own row (full-width with
+an enlarged thumb for touch), and the Filter button + node count share
+the bottom row. The "← Back" control collapses to a left-arrow icon to
+preserve toolbar space at depth.
+
+## Trashed conversations
+
+Trashed Conversation nodes are hidden by default. Toggle **Show trashed** in
+the filter popover to surface them; they render with a faded fill and dashed
+border, with their zoom-tier labels intact. The `N msgs` count excludes
+trashed Messages, so the detailed-tier label reflects only live turns in the
+conversation.
+
+## Filtering by channel and message kind
+
+When you select **AdminConversation** or **PublicConversation** in the
+filter popover, two extra rows appear underneath the chip list:
+
+- **Channel** — Web / WhatsApp. Select one to scope the canvas to
+  conversations that came in over that channel only. Selecting both is
+  the same as selecting neither (all channels). After the migration that
+  ships with this release, every conversation carries an explicit
+  channel value — pre-existing conversations are backfilled to "Web"
+  because only the WhatsApp and Telegram intake paths ever set non-Web
+  values.
+- **Message** — User / Assistant / WhatsApp. When you've also pivoted
+  into a conversation neighbourhood (or your search hits messages
+  directly), this row scopes the messages on canvas to the chosen kind.
+  WhatsApp messages persist with their own sublabel so you can isolate
+  the live-channel cohort from the agent-path cohort within the same
+  conversation.
+
+These sub-facets compose with the chip selection. Searching with the
+AdminConversation chip selected now also reaches the body text of every
+admin message — typing a rare word like "ATM" returns every conversation
+that mentions it, not just conversations with that word in the title.
+
+## Sidebar conversations list
+
+The Recents list above the chat sidebar carries a per-row marker:
+WhatsApp conversations show a small WhatsApp glyph next to the
+conversation name. The dropdown above the list filters Recents to a
+specific channel — flipping it to **WhatsApp** hides web-chat
+conversations and vice versa.
+
+## Agents in the graph
+
+Both admin and public agents appear as `:Agent` nodes in the graph. Open
+the **Agents** entry from the sidebar to see them all. Each agent
+carries a `:HANDLED_BY` edge from every conversation it has handled, so
+you can pivot from an agent to the conversations it ran. The admin
+agent's IDENTITY, SOUL, KNOWLEDGE, and KNOWLEDGE-SUMMARY documents
+appear as :KnowledgeDocument nodes connected via `HAS_*` edges, the same
+projection shape used for public agents.
+
+## Agent-execution telemetry
+
+`ToolCall`, `StepResult`, `WorkflowStep`, and `WorkflowRun` nodes are
+agent-execution telemetry — kept for audit but noisy for day-to-day graph
+navigation (they make up roughly 9% of a typical brand's live nodes).
+They are hidden from `/graph` by default. To see them — for audit, debug,
+or tracing a specific agent run — open the filter popover and tick
+**Include agent actions** (the checkbox directly below **Show trashed**).
+Flipping it on surfaces the four labels as chips in the popover roster AND
+keeps them on the canvas when you pivot into a neighbourhood. The toggle
+is session-scoped: every new session starts with agent actions hidden, so
+the 90% domain-navigation path stays clean without having to remember to
+switch them off. Flipping it off again also drops them from any already-
+expanded neighbourhood so a click near a `ToolCall` does not re-introduce
+it.
+
+## Direct edge management
+
+`memory-edge` creates or deletes a typed directed edge between two nodes that already exist in the graph. Both nodes must belong to the same account — mismatched or foreign nodes are rejected with a structured error before any mutation runs.
+
+**Create:** MERGE is idempotent. First call returns `{created: true}`; a repeated call with the same endpoints and type returns `{created: false}`. Properties supplied on the call are stamped onto the relationship on CREATE only; a subsequent idempotent hit does not overwrite them.
+
+**Delete:** If the edge is present it is deleted and `{deleted: true}` is returned. If absent, the call is a no-op and returns `{deleted: false}`.
+
+`relationshipType` is uppercase-coerced. Types that start with an underscore (e.g. `_SOFT_DELETE`) are reserved for platform internals and are rejected.
+
+Typical flow: call `memory-search` for each endpoint to retrieve their `elementId` values, then call `memory-edge action=create relationshipType=RELATES_TO fromId=<id> toId=<id>`. The new edge appears when you hop-expand either endpoint on the `/graph` canvas.