@rubytech/create-maxy-code 0.1.0

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

@@ -0,0 +1,150 @@
+# 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, but the operator command is the same:
+
+```bash
+npx -y @rubytech/create-maxy
+```
+
+**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 registers {{productName}} as a launchd LaunchAgent at `~/Library/LaunchAgents/com.rubytech.maxy.plist` — survives logout/login and reboot. Use `launchctl print gui/$UID/com.rubytech.maxy` for service state. `--hostname <h>` sets HostName / LocalHostName / ComputerName via `sudo scutil`. macOS < 14 is refused at pre-flight.
+
+## 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
+
+## 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.
+
+## 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.
+
+**Port-drift recovery.** Devices upgraded between Tasks 647 and 666 may have drifted +1 on every upgrade because the pre-Task-666 installer wrote `Environment=PORT=<internal>` into `{hostname}.service` and the upgrade reader correctly treated `PORT=` as public. The first post-Task-666 install detects this (comparing maxy's PORT against the edge's EDGE_PORT) and emits a one-shot loud log: `[port-recovery] detected drift maxy=<X> edge=<Y> — pinning at <Y>`. Subsequent upgrades are silent. If your Cloudflare tunnel was pointing at a drifted port, the ingress `config.yml` still needs a one-time manual fix: `sed -i 's|localhost:<old>|localhost:<current>|' ~/.{configDir}/cloudflared/config.yml && cloudflared tunnel ingress validate`. {{productName}} never rewrites cloudflared config programmatically.
+
+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.
+
+**Pre-Task-662 / pre-Task-664 upgrade** — devices that ran an installer have legacy shared `maxy-edge.service` / `maxy-ttyd.service` units; devices that ran have per-brand `{hostname}-ttyd.service` units plus a pinned `/usr/local/bin/ttyd` binary. Neither is removed automatically — do this cleanup once per device before re-running any installer:
+
+```bash
+systemctl --user stop maxy-edge maxy-ttyd realagent-ttyd 2>/dev/null || true
+systemctl --user disable maxy-edge maxy-ttyd realagent-ttyd 2>/dev/null || true
+rm -f ~/.config/systemd/user/maxy-edge.service \
+      ~/.config/systemd/user/maxy-ttyd.service \
+      ~/.config/systemd/user/realagent-ttyd.service
+sudo rm -f /usr/local/bin/ttyd
+systemctl --user daemon-reload
+```
+
+## 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 used by every Chromium call site (the VNC service, the in-page Chromium wrapper, the Cloudflare tunnel OAuth spawn, and the Playwright server). 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.
+
+## 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.
+
+## 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 waitlist signups, 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,149 @@
+# 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).
+
+## 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.