@rubytech/create-siteoffice-code 0.1.256

package/payload/platform/plugins/docs/references/access-control.md

@@ -0,0 +1,84 @@
+# Access Control
+
+## What It Is
+
+Access control determines who can chat with your public agent. By default, anyone with your public URL can start a conversation. You can restrict this so only invited people have access, and so the agent remembers each invitee separately without leaking what one visitor said to the others.
+
+## Access Modes
+
+Each public agent has one of two access modes:
+
+| Mode | Who can chat | What the agent remembers |
+|------|--------------|--------------------------|
+| Open (default) | Anyone with the URL. No login required. | Public-scope knowledge only. Nothing per-visitor. |
+| Gated | Invitation only. Visitors authenticate by clicking a fresh emailed link each session. | A separate per-visitor memory slice. Visitor A and visitor B never see each other's memory. |
+
+## How to Set It Up
+
+Tell {{productName}}: "Set my public agent to gated access" or "Make the coaching agent invitation-only."
+
+{{productName}} flips the agent's access mode. The next visitor to your public URL sees a sign-in screen instead of the chat.
+
+## Inviting Visitors
+
+Tell {{productName}}: "Invite sarah@client.co to the coaching agent."
+
+{{productName}} creates an invitation and emails the visitor a magic link. At creation time the invitation is stamped with a one-off `sliceToken` — that token is what binds every per-visitor memory write to this specific invitation for the life of the invite.
+
+Only email invitations are supported. Phone, OTP, and password flows are not part of the current build.
+
+## What Visitors Experience
+
+- **First visit (invited):** The visitor opens the email and clicks the magic link. They land on your public URL, the cookie is set, and the chat opens. No password to remember.
+- **Return visits / lost the email:** The visitor visits your URL directly, types the email they were invited on, and clicks "Send me a link." A fresh magic link arrives within seconds. The new link replaces the previous one — old links go inert.
+- **Browser close:** The cookie is session-only. Closing the tab signs the visitor out. They click the latest magic link, or request a new one, to come back.
+- **Revoked or expired:** Their next request is bounced back to the sign-in screen. They cannot get past it until you re-invite them.
+
+## Per-Visitor Memory
+
+Every gated visitor has their own ringfenced memory slice. When the agent talks to visitor A, it sees everything tagged with A's slice plus the agent's general public-scope knowledge. It cannot see visitor B's slice, and it cannot see your admin-scope notes. The same gate applies in reverse — nothing the visitor says leaks into your admin graph by accident.
+
+The slice is populated automatically at the end of each conversation. When a visitor's chat session is reaped (idle timeout, or the visitor closes the tab), a background reviewer reads the transcript and writes anything worth saving into the visitor's slice. The visitor sees the new context the next time they return.
+
+You can read what's in a visitor's slice via the cypher tools in conversation — "show me what we know about Sarah" — but the slice writes themselves happen autonomously without your involvement.
+
+## Managing Access
+
+All access management is done through conversation with {{productName}}:
+
+- "Who has access to my coaching agent?" — lists active visitors and their `sliceToken`.
+- "Revoke Sarah's access" — flips her grant to revoked AND immediately drops her active session, so she cannot continue talking on a live cookie. Her slice's historical memory stays in the graph; you can purge it separately if needed.
+- "Extend Tom's access by 30 days" — pushes the expiry date forward. Slice unchanged.
+- "Resend Sarah's invitation" — generates a fresh magic link and emails it. The slice stays the same, so her existing memory carries over.
+
+Revoking + re-inviting the same person on a new invitation produces a fresh slice — the old slice's memory does not transfer. This is by design: a fresh invitation is a fresh relationship.
+
+## Visitor Identity
+
+When a visitor is authenticated, your public agent knows their name and contact details — it reads them from the visitor's `:Person` node, which is linked to their grant. It can personalise responses ("Welcome back, Sarah") without needing to ask.
+
+## Action Approval
+
+External-facing actions — sending emails, WhatsApp messages, Telegram messages, and erasing contacts — require your approval before {{productName}} executes them. This is human oversight as required by the EU AI Act.
+
+When {{productName}} needs to send a message or perform a consequential action, it drafts the action and queues it for your review. You'll see it in your next chat turn:
+
+- "Approve it" — {{productName}} executes the action immediately
+- "Reject it" — the action is cancelled
+- "Change the subject to X" — {{productName}} modifies the action and executes the edited version
+
+Internal operations (creating tasks, updating contacts, searching memory) execute automatically without approval.
+
+### Changing the Policy
+
+Tell {{productName}} to change which actions require approval:
+
+- "Auto-send follow-up emails from now on" — emails execute without approval
+- "Require approval for all WhatsApp messages" — restores the default gating
+- "What actions currently require my approval?" — lists the current policy
+
+Changes are per-account and take effect immediately.
+
+## Filesystem Access (SMB Share)
+
+Brand isolation extends to the device filesystem. Every {{productName}} install provisions an SMB share scoped to that brand's install folder, credentialled by the brand's install owner and the {{productName}} PIN. A device that hosts more than one brand carries one share per brand; tearing one brand down never exposes another brand's files. See [Samba Share](./samba.md) for the credential model, per-OS mount syntax, and peer-brand lifecycle.

package/payload/platform/plugins/docs/references/admin-identity-gate.md

@@ -0,0 +1,81 @@
+# Native-CC admin PIN identity gate
+
+Every native-CC admin session — the operator chatting through claude.ai/code (web,
+desktop, mobile) over the per-account `claude rc` daemon — must bind a
+PIN-authenticated `userId` before any tool runs. This closes the gap where the
+daemon stamped one boot-time `USER_ID` (from `users.json`) onto every session,
+which is correct for at most one human on a multi-admin install. (Task 619.)
+
+The legacy cookie/PIN browser login (`POST /api/admin/session`) is a separate
+surface documented in [`admin-session.md`](admin-session.md); this gate covers the
+native path, which that login never touched.
+
+## How it works
+
+Three pieces, plus a standing audit. No cross-process `session_id` plumbing: the
+hook keys state by the `session_id` it reads from stdin; validation and profile
+resolution live behind one loopback endpoint.
+
+1. **Shared validator** — `ui/app/lib/admin-identity/pin-validator.ts`. The single
+   PIN primitive (`validatePin` → `match` / `miss` / `unavailable` / `corrupt`),
+   shared by the legacy browser login and the gate so the two cannot drift.
+
+2. **Loopback validate endpoint** — `POST /api/admin/identity/validate`
+   (`ui/server/routes/admin/identity.ts`). Loopback-only (rejects any request
+   carrying `x-forwarded-for`, which only edge-proxied browser requests have).
+   Body `{ pin, sessionId? }`. On a match it resolves the operator's `userName`
+   and `aboutOwner` via the same helpers the browser path uses
+   (`resolveUserIdentity`, `resolveOwnerProfileBlock`) — `loadUserProfile` is never
+   duplicated. On a miss with a `sessionId` it fires a best-effort manager
+   `POST /<sessionId>/stop` (only the UI process reliably holds the manager port).
+
+3. **PreToolUse gate hook** — `plugins/admin/hooks/pin-identity-gate.sh`, wired in
+   `setup-account.sh` as the first universal PreToolUse entry. Runs only for native
+   operator sessions (`MAXY_SESSION_ROLE=admin` and empty `MAXY_SPECIALIST` — the
+   latter excludes pty-spawned specialist/recorder sessions). Per tool call: if an
+   auth-state file exists for the `session_id`, allow; if the tool is
+   `admin-identity-authenticate`, post the PIN to the validate endpoint and on a
+   match write the state file and allow (on a miss/unavailable, deny + terminate);
+   any other tool while unauthenticated is denied with an instruction to
+   authenticate first. Enforcement is in the hook, not the agent's choice — a model
+   that skips the prompt reaches no other tool.
+
+The agent-callable surface is the eager-loaded `admin-identity-authenticate` MCP
+tool (admin plugin); the gate validates and binds before allowing it, and the tool
+returns the authenticated operator's profile to the agent.
+
+Auth state: `<accountDir>/state/admin-identity/<session_id>.json` (`{userId, ts}`).
+One file per authenticated conversation; bound for the session lifetime, not
+re-prompted per message. Task-tool specialist subagents share the operator's
+`session_id`, so they pass once the operator is authenticated.
+
+## Cases
+
+- **Zero admins / absent / empty `users.json`** → `pin-unavailable`, the gate
+  refuses; never a bound empty `userId`. A real install always has `users.json`
+  (the installer/seed writes it), so this is a misconfiguration guard.
+- **One admin** → still prompts; the single matching PIN binds that `userId`.
+- **Many admins** → each PIN binds its own `userId`. The account is fixed (the
+  install's own scope); there is no multi-account picker on this path.
+- **Mismatch** → the session is terminated on the first miss (no retry budget).
+
+## Observability
+
+One structured `[admin-identity]` line per step, correlated by `sessionId`:
+
+```
+op=loopback-spawn-received → op=pin-prompted → (op=pin-bound source=pin |
+op=pin-miss → op=session-terminated) ; the MCP tool emits op=about-owner-loaded.
+```
+
+**Standing audit** (`services/claude-session-manager/src/admin-identity-audit.ts`,
+every 60s) reconciles, independently of the hook, live native-operator sessions
+(watcher rows with `role === null` — daemon-spawned, no sidecar) that reached real
+tool use against the auth-state files. Any such session with no state file emits
+`[admin-identity] op=audit-orphan sessionId=…
+reason=loopback-session-without-authenticated-userId`. This is the no-event
+detector: a silent gate bypass leaves no per-session log line, but the audit still
+surfaces it.
+
+Diagnostic path: `journalctl --user -u <brand>-admin | grep -E '\[admin-identity\]'`,
+then filter by `sessionId` for one session's full lifeline.

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

@@ -0,0 +1,177 @@
+# Admin Session — restart survival and SDK-resume contract
+
+The admin PIN-gated session-store is the in-memory `Map<sessionKey, Session>` at [`platform/ui/app/lib/claude-agent/session-store.ts`](../../../ui/app/lib/claude-agent/session-store.ts). Every `systemctl --user restart {brand}.service` (notably the one the agent arms 3 s after Cloudflare-setup completion via `systemd-run --on-active=3s` to avoid the cgroup trap) wipes that Map. This reference documents how an admin session survives the restart without forcing PIN re-entry, and how the SDK conversation chain is preserved across the gap.
+
+## Signed sessionKey
+
+`POST /api/admin/session` mints sessionKeys as HMAC-signed tokens (same primitive as `remote-auth.ts`'s `__remote_session` cookie, generalised to `session-store.ts`):
+
+```
+v1.<base64url(payloadJson)>.<base64url(hmac-sha256(secret, payloadJson))>
+
+payload = { v: "adm", a: <accountId>, u: <userId>, c: <createdAtMs>, n: <16-byte hex nonce> }
+```
+
+The HMAC secret lives at `~/.${brand}/credentials/admin-session-secret` (mode `0o600`, parent dir `0o700`), self-provisioned on first read via the `wx`-create pattern from [`remote-auth.ts::getSecret`](../../../ui/app/lib/remote-auth.ts). The secret is separate from `REMOTE_SESSION_SECRET_FILE` (the `__remote_session` cookie key) — two token surfaces, two security domains, no token-confusion attack across schemas.
+
+**Validation path.** `validateSession(sessionKey, 'admin')`:
+
+1. In-memory `Map.get(sessionKey)` hit → existing behaviour (age check, grant check, return ok).
+2. Map miss AND `agentType === 'admin'` → `tryRehydrateAdminSession(sessionKey)`:
+   - Parse `v1.…` token, verify HMAC against the on-disk secret (timing-safe compare).
+   - Schema-validate the payload (`v === 'adm'`, all required fields present).
+   - TTL check: `Date.now() - payload.c <= 24h`. Expired → return `{kind: 'expired', ageMs}` → caller projects onto the existing `session-expired-age` rejection.
+   - Otherwise, re-register the in-memory entry with `{agentType: 'admin', accountId, userId, wantsPriorConversation: true}` and return `{kind: 'ok', …}`.
+3. Map miss with no valid token → `session-not-registered` (existing legacy `crypto.randomUUID()` sessionKeys land here).
+
+**Observability.** `[session-rehydrate-from-token] sessionKey=… accountId=… userId=… ageMs=…` fires once per successful rehydrate in `server.log`. A tampered token fails HMAC and returns `invalid-token` silently (no log line — would otherwise be a noise/attack-amplifier surface); the request's downstream `[session] middleware-reject status=401 code=session-not-registered` is sufficient.
+
+## SDK-resume contract on PIN-rebind
+
+The Anthropic SDK is stateless against its own JSONL: every cold-create with `resume: <agentSessionId>` reads `${CLAUDE_CONFIG_DIR}/projects/<encoded-cwd>/<agentSessionId>.jsonl` verbatim. The Maxy graph (`Conversation.agentSessionId`) is just the pointer into the JSONL, not a parallel transcript. The PIN-rebind contract preserves this:
+
+1. **Rehydrate** restores `(accountId, userId)` into the in-memory session. `sessionId` and `agentSessionId` are empty.
+2. **Chat-route first POST** (`platform/ui/server/routes/admin/chat.ts`):
+   - `consumeWantsPriorConversation(sessionKey)` returns true → look up prior admin conversation.
+   - `getMostRecentAdminConversationForUser(accountId, userId)` returns `{sessionId, agentSessionId}` for the most recent admin Conversation node carrying a non-null `agentSessionId`.
+   - `setSessionIdForSession(sessionKey, sessionId)` binds the prior `sessionId` so the operator's chat lands in the SAME conversation, not a new one.
+   - `setAgentSessionId(sessionKey, agentSessionId)` seeds the in-memory session's pointer; subsequent `invokeAdminAgent`'s `getAgentSessionId(sessionKey)` returns this value naturally.
+3. **`invokeAdminAgent`** passes `resume: <priorAgentSessionId>` to the SDK options. The SDK opens its on-disk JSONL for that session id and continues from there.
+
+No `<previous-context>` prompt-stuffing. No Neo4j transcript replay. The SDK reads its own JSONL — the only canonical source of multi-block content (`thinking` with signed signatures, `tool_use`/`tool_result` chains, multi-modal blocks) the graph cannot losslessly reconstruct.
+
+## PIN-rebind vs `/sessions/new`
+
+The `wantsPriorConversation` marker is the discriminator between continuity and explicit fresh-start:
+
+| Trigger | Marker set? | Chat-route behaviour |
+|---|---|---|
+| Signed-token rehydrate post-restart (`tryRehydrateAdminSession`) | yes | Resume prior conversation |
+| Explicit PIN re-entry (`POST /api/admin/session`, `createAdminSession`) | yes | Resume prior conversation |
+| Operator clicks "New conversation" (`POST /api/admin/sessions/new`) | NO | Cold-mint new conversation |
+
+Single-shot: the chat-route consumes the marker on the first POST, so subsequent chats in the same session continue with the bound `sessionId` naturally.
+
+## Observability summary
+
+Per chat POST, one `[client-acquire]` line lands in the per-conversation stream log at `{accountDir}/logs/claude-agent-stream-<sessionId>.log`:
+
+```
+[client-acquire] sessionKey=<sk12>… resume=<priorAgentSessionId8|none> reason=<warm|cold|pin-rebind>
+```
+
+- `warm` — pool entry still alive (no restart in between)
+- `cold` — fresh mint (no prior admin conversation, or `/sessions/new`)
+- `pin-rebind` — post-restart resume of prior admin conversation
+
+The pre-existing `[client-cold-create resumedFrom=<id>]` line from `client-pool.ts` fires once per actual SDK subprocess spawn; combined with `[client-acquire]` it gives a complete shape of every acquire-and-spawn event.
+
+Diagnostic grep:
+
+```bash
+grep -E '\[session-rehydrate-from-token\]|\[client-acquire\] reason=pin-rebind' ~/.${brand}/logs/server.log
+grep '\[client-acquire\]' ~/.${brand}/logs/claude-agent-stream-*.log
+```
+
+## AskUserQuestion investigation gate
+
+PreToolUse hook `platform/plugins/admin/hooks/askuserquestion-investigate-gate.sh` blocks `AskUserQuestion` when no read-only investigation tool fired in the current turn. When the admin agent surfaces the operator-visible block message instead of a menu, the next move is to search the operator's literal phrase via `ToolSearch` or `Grep` first, then re-attempt the question with evidence. Grep `[ask-gate] decision=block` on `server.log` to count recurrences. Full contract in [`.docs/hooks.md`](../../../../.docs/hooks.md) under `askuserquestion-investigate-gate.sh`.
+
+## Spawn-with-`initialMessage` wrapper
+
+The Hono route `POST /api/admin/claude-sessions` at [`platform/ui/server/routes/admin/claude-sessions.ts`](../../../ui/server/routes/admin/claude-sessions.ts) is the cookie-auth entry point for opening an admin PTY session with a first user prompt (the Sidebar new-session-with-text path). It owns the per-spawn enrichment (`aboutOwner`, `dormantPlugins`, `activePlugins`, `specialistDomains`, `tunnelUrl`) and resolves `senderId` from the admin session cookie. The session manager binds to `127.0.0.1` only so the wrapper is the sole authorised caller. `dormantPlugins` is `installed − enabledPlugins` with one exclusion: PLUGIN.md frontmatter `surface: platform` (admin, docs) marks platform-shell plugins that ship with every install and are never opt-in features, so they never surface in the `<dormant-plugins>` nudge.
+
+**Body schema.** `{channel?, permissionMode?, initialMessage?, specialist?, model?}`, cookie-auth only (`hidden: false`). `permissionMode` accepts one of five values matching Claude Code's CLI: `'default'`, `'acceptEdits'`, `'plan'`, `'auto'`, `'bypassPermissions'`. The wrapper rejects nothing structurally — string fields are coerced or defaulted (`channel` → `'browser'`, `permissionMode` → undefined, `initialMessage` → null if empty/whitespace).
+
+**Auth surface.** One: `cookie` — `requireAdminSession` validates `session_key` and resolves `senderId` from the in-memory session store. Task 626 removed the turn-recorder loopback bypass; there is no loopback caller and no `adminSessionId` body field.
+
+**Forwarded endpoint.** One upstream call per spawn-with-message: `POST {managerBase}/public-spawn` (enriched body, with `initialMessage` inlined when set). The manager appends `initialMessage` as the trailing positional argv to `claude` so the CLI processes it as the session's first user turn at PTY startup — the JSONL first `role=user` line equals `initialMessage` verbatim. No follow-up `/<sessionId>/input` call, no bracketed-paste. The HTTP response streams the spawn upstream body straight through. (Task 153.)
+
+**Caller.** `Sidebar.tsx`'s "+ New session" click opens the `NewSessionModal` (Task 223) — no POST fires on click. Modal submit POSTs `{channel:'browser', permissionMode, model, initialMessage}` where `initialMessage` is the operator's typed text verbatim; `permissionMode` and `model` are per-session overrides local to the modal. The sidebar's own mode trigger persists across refresh, new tab, and new device under `(accountId, userId)` via `/api/admin/session-defaults` (Task 239) — a single `:SpawnPreference` node MERGEd on the composite key with `permissionMode` and `model`. The on-the-wire signal that the contract held is the `[claude-session-manager:wrapper] spawn-request-in surface=cookie` log line followed by `forward-spawn-done`; it always carries `initialMessage=yes`, which a regressed client gate would flip to `no`.
+
+## Session identifiers (Task 135)
+
+The metadata pane surfaces two distinct identifier values. Task 141 collapsed the three-id model that Task 135 introduced back to Task 080's single-identity contract: claude's bridge suffix and the JSONL basename UUID are two phases of one claude-side identity, not two operator-visible identifiers. The manager resolver accepts either phase on any route. The wire emits one canonical `sessionId` — whichever phase is current — and the pane shows one row.
+
+| Operator label | What it is | Manager wire field | Log key |
+|---|---|---|---|
+| `sessionId` | Claude's session. Two phases: bridge suffix (`session_xxx`, the URL segment in `claude.ai/code/<session_xxx>`, set when claude prints the `/remote-control` URL) and JSONL basename UUID (claude's intrinsic id on disk, bound when the first turn flushes the JSONL). Both phases coexist on a live row after URL capture; the manager wire emits the bridge form when set, falling back to the JSONL basename in the pre-URL-capture window. The resolver routes either phase to the same row, so callers never need to choose. | `sessionId` (collapsed from the earlier three-field surface (see Task 141) `sessionId` + `claudeSessionId` + `bridgeSessionId`) | `sessionId=` |
+| `accountId` | Account / workspace UUID. For the admin channel, the value the manager carries as `senderId` IS the accountId; for non-admin channels the same wire field carries a phone / email / chat-id (the channel-level sender), so its log key on those paths is still `senderId=`. | `senderId` (channel-agnostic) | `accountId=` in admin-flow emit sites; `senderId=` in channel-bridge sites |
+
+## Memory MCP write-path outcome lines (Task 166)
+
+Every write-path tool in the memory plugin MCP emits one structured line per invocation to `server.log` via the loopback `/api/admin/log-ingest` route. The operator can answer "did this write succeed?" from a single greppable surface — no need to cross-reference the per-process `mcp-memory-stderr-<date>.log`.
+
+Line shapes:
+
+```
+[mcp:memory] <tool-name> account=<id|—> session=<convId|—> labels=<csv|—> name=<value|—> result=ok elementId=<id|—> ms=<n>
+[mcp:memory] <tool-name> account=<id|—> session=<convId|—> labels=<csv|—> name=<value|—> result=error reason=<slug> detail=<≤120 chars> ms=<n>
+```
+
+Enumerated `reason` slugs (failure path): `invalid-input | schema-unknown-label | schema-property-naming | account-isolation | producedby-task-not-found | constraint-violation | conflicting-element-id | invalid-target-node-id | gate-blocked | neo4j-driver-error`. Free-form error text remains in the `detail` field. New slugs are added only by amending the helper's union type; nothing silently falls through to a generic `unknown`.
+
+Wired tools: `memory-write`, `memory-update`, `memory-delete`, `memory-restore`, `memory-empty-trash`, `memory-archive-write`, `memory-ingest`, `memory-ingest-extract`, `memory-ingest-web`, `memory-reindex`, `memory-edit-attachment`, `memory-rename-attachment`, `profile-update`, `profile-delete`, `graph-prune-denylist-add`, `graph-prune-denylist-remove`, `conversation-archive-derive-insights`, `conversation-archive-enrich-rejection`, `conversation-memory-expunge`. Read-path tools (`memory-search`, etc.) are intentionally out of scope — reads do not change state and their failures already reach the caller. (Task 424 removed `memory-rank` and `memory-classify`.)
+
+Diagnostic grep:
+
+```bash
+# Did the most recent memory-write attempt land, and what was it?
+grep '\[mcp:memory\] memory-write .* result=' ~/.${brand}/logs/server.log | tail
+
+# All failed writes across every memory MCP tool, grouped by reason:
+grep '\[mcp:memory\] .* result=error' ~/.${brand}/logs/server.log | awk -F'reason=' '{print $2}' | awk '{print $1}' | sort | uniq -c | sort -rn
+
+# Did the loopback POST itself fail? (Helper falls back to stderr and re-writes
+# the structured line, so the event is never lost — this just flags that the
+# session-manager's /api/admin/log-ingest was unreachable for some window.)
+grep '\[mcp:memory\] log-ingest-failed' ~/.${brand}/logs/mcp-memory-stderr-*.log
+```
+
+The existing `mcp-memory-stderr-<date>.log` capture is unchanged on error paths — the new structured line is additive, not a relocation. Crash-mode debugging continues to read the stderr log; routine "did it land?" questions read `server.log`.
+
+**Test contract (Task 168).** Each of the 20 wired tools carries a `*-emit.test.ts` fixture under `platform/plugins/memory/mcp/src/tools/__tests__/` that mocks `fetch` and asserts the wire body. A refactor that drops `withWriteEvent` from any tool fails the matching tool's tests with a clear `expected "vi.fn()" to be called 1 times, but got 0 times` error, naming the tool. A shared helper at `__tests__/_helpers/emit-capture.ts` standardises the fetch capture + Neo4j Session stub so each tool test stays a few lines of mocks + one happy + one error assertion. Drift between the helper's body shape and the route's validator is pinned by an end-to-end test at `platform/ui/server/routes/admin/__tests__/log-ingest-mcp-end-to-end.test.ts`, which routes the helper's POST through the real Hono `log-ingest` route with a loopback `remoteAddress` shim.
+
+## Diagnosing missing tools in production (Task 183)
+
+When a database-operator spawn fails to call any of its 11 tools, the question is which of two layers dropped them:
+
+- **Outcome A — tools missing at the model boundary.** The CLI / SDK exposes fewer tools than the framework's `--allowed-tools` argv listed. The model never sees the missing names, so it cannot call them and writes nothing to the graph.
+- **Outcome B — tools present, model abstains.** The SDK exposes all 11 tools; the model has them but chooses not to call any.
+
+Three log-line shapes, all keyed on the same database-operator `sessionId`, distinguish the two:
+
+```
+[pty-spawn-tool-inventory] sessionId=<id> specialist=<name> argv-tools=<n> mcp-listed-tools=<n> exposed=<csv> not-exposed=<csv>
+[recorder-session-init]    sessionId=<id> specialist=<name> toolsExposedCount=<n> toolsExposed=<csv> toolsArgvCount=<n> toolsArgvMissingFromExposed=<csv|—> source=<probe>
+[recorder-turn]            sessionId=<id> turnIndex=<n> stopReason=<r> textBytes=<n> text=<full json-escaped> toolUseNames=<csv|—> containsToolCallText=true|false
+```
+
+- `[pty-spawn-tool-inventory]` (Task 178) measures the **framework** layer — the argv built and the MCP servers' published tools. Argv-tools count must be 11; mcp-listed-tools must be ≥ 11.
+- `[recorder-session-init]` (Task 183 — emitted by the JSONL tail in `claude-session-manager`) measures the **CLI/SDK** layer — what the SDK actually exposed to the model. The `source=` field names the data path; `toolsArgvMissingFromExposed` is the Outcome A fingerprint:
+  - `source=system.init` / `command_permissions` / `deferred_tools_delta` ⇒ the SDK wrote an init record to the JSONL and the tail matched one of the three known shapes. The bridge-attached `--remote-control` mode writes `attachment.deferred_tools_delta`; the headless SDK init record (`system.subtype=init`) is what `claude -p --output-format=stream-json` modes write.
+  - `source=headless-argv-fallback` ⇒ Task 185 finding (2026-05-20): headless `claude --verbose` PTY mode (which headless database-operator spawns use) does **not** write any tool-list record to the JSONL — none of the three probe shapes ever appears. The tail falls back to the spawner's `--allowed-tools` argv as the exposed set, independently verified by `[pty-spawn-tool-inventory]`'s `exposed=` field. Treat this source identically to a positive JSONL match: the argv set is authoritative for headless spawns.
+  - `toolsArgvMissingFromExposed=—` ⇒ all argv tools made it through; Outcome A is ruled out.
+  - Any non-`—` value enumerates the names the SDK dropped and is the diagnosis. Only meaningful when `source` is JSONL-derived; under `headless-argv-fallback` the exposed set equals argv by construction, so this field is always `—`.
+- `[recorder-turn]` measures the **model** layer — Haiku's verbatim words (Task 213: full `text=`, not the prior 240-char `textHead`) and the tool names it actually called (`toolUseNames`). `toolUseNames=—` paired with `toolsArgvMissingFromExposed=—` is the Outcome B signature: tools present, model abstained. `containsToolCallText=true` flags any assistant text that contains `<tool_call>`, `<function_calls>`, or `</invoke>` — the recorder model copying the tool-call shape into prose (the regression Task 213 closed).
+
+The three lines are emitted into `server.log` via the platform UI's `/api/admin/log-ingest` loopback route, so a single grep against `server.log` answers the question for any past, present, or future recorder spawn:
+
+```bash
+SID=<rec-sessionId>
+grep -E "\[(pty-spawn-tool-inventory|recorder-session-init|recorder-turn|mcp:(memory|contacts|tasks))\] .*sessionId=${SID}" ~/.${brand}/logs/server.log
+```
+
+**Reading the output.**
+
+1. The single `[pty-spawn-tool-inventory]` line proves what the framework provisioned. If `argv-tools < 11`, the bug is upstream of this evidence chain — the agent file or the spawn site.
+2. The single `[recorder-session-init]` line proves what the model received. If `toolsArgvMissingFromExposed` is non-`—`, the named tools were dropped by the CLI/SDK; that is Outcome A and the fix lives in the `--mcp-config` resolution or the CLI/SDK handshake.
+3. Each `[recorder-turn]` line records one assistant turn. If `toolUseNames=—` across every turn AND `toolsArgvMissingFromExposed=—`, the model could call the tools and chose not to; `text=` carries the model's verbatim reasoning (Task 213 dropped the 240-char head cap so the whole turn is observable from server.log) and is the next surface to read. A `containsToolCallText=true` row is the recorder-relapse signature: the model emitted tool-call shape as prose instead of a real `tool_use` block.
+
+**Loopback gate.** The `/api/admin/log-ingest` route is loopback-only on both the socket address and (when present) the `X-Forwarded-For` header. A LAN client whose request reaches the route via a proxy still gets a 403 because XFF tokens are required to be loopback when XFF is set. Without this gate the evidence chain would be worthless — any LAN client could forge `[recorder-session-init]` lines under a spoofed sessionId.
+
+## Out of scope
+
+- Public/WhatsApp/Telegram sessions — out of scope. Their sessionKeys remain `crypto.randomUUID()` and follow the existing rejection-on-restart contract.
+- Multi-user PIN identity carry-forward across the same signed token — the token is bound to one `userId`; rotating PINs mints a fresh token.
+- Replacing `systemctl restart` with in-process cloudflared reload — separate task. The restart-survival contract documented here is the operator's safety net while that rewrite is pending.

package/payload/platform/plugins/docs/references/admin-ui.md

@@ -0,0 +1,266 @@
+# Admin UI reference
+
+A compact map of the admin web app: every `/api/admin/*` mount, every
+sidebar surface, and the operator-facing widgets that read host or session
+state. The deep architecture lives in [`platform.md`](platform.md) (UI
+layout, session reconcile, route lifecycle) and
+[`admin-session.md`](admin-session.md) (the session-cookie / PIN-rebind /
+SDK-resume contract). This file is the index that points at them.
+
+## Scope and tree decision
+
+The `maxy-code/` tree does **not** ship a `.docs/platform.md` developer
+doc. The legacy root tree (`getmaxy/`) carries one at
+`.docs/platform.md` for the original Maxy installer; the Maxy Code tree
+keeps its architecture surface in two places:
+
+- `maxy-code-prd.md` at the repo root — product requirements and the
+  source of truth for every task in `.tasks/`.
+- `platform/plugins/docs/references/platform.md` — operator-facing
+  architecture, loaded by the docs plugin at session start.
+
+Anything that would have gone into `maxy-code/.docs/platform.md` belongs
+in one of those two files instead. `maxy-code/.docs/` itself is
+reserved for vertical / integration notes (LinkedIn extension,
+PropertyData, Real Agent standalone, MCP server inventory) — not for
+core-platform docs.
+
+## Admin Hono routes
+
+Every admin sub-app is mounted by
+[`platform/ui/server/routes/admin/index.ts`](../../../ui/server/routes/admin/index.ts)
+under a per-area prefix. The outer `requireAdminSession` middleware
+runs in `server/index.ts` before the aggregator; individual handlers
+re-apply `requireAdminSession` where they need a resolved `senderId`.
+
+`/actions` and `/version` are **not** mounted here — they live on
+`maxy-edge.service` via `server/edge-admin.ts` so the upgrade view
+survives the mid-run restart of the brand service. Double-mounting
+either is a regression.
+
+### Sessions and chat
+
+| Mount | Purpose | Key methods |
+|---|---|---|
+| `/session` | Admin cookie session: PIN-gated mint, validate, rotate. | `GET /`, `POST /` |
+| `/sessions` | Legacy admin-server conversation routes. No UI consumer remains after the ConversationsModal was retired; the surviving handlers are deletion candidates and not described here. | (legacy, no live caller) |
+| `/sidebar-sessions` | Sole data path for the sidebar Sessions list (Tasks 538 + 543). One JSONL on disk equals one row. The row's delete button (Task 543) is the only way a row disappears. Each row carries `sessionId`, `title`, `startedAt`, `live`, `isSubagent`, `pid: number \| null` (basename of the matched `sessions/<pid>.json`), and `projectDir` (the directory holding the JSONL — consumed by the delete route). The payload also carries top-level `accountId` so the pane renders the full UUID label whose first ~8 chars prefix-match the truncated Remote Control daemon entry in claude.ai/code. The legacy `rcUrl` field is gone (Task 543) — the row's external-link affordance now POSTs `/session-rc-spawn` to start a fresh local `claude --remote-control <name> --session-id <sid>` PTY on every click. | `GET /` |
+| `/session-delete` | POST `{ sessionId, projectDir }` (Task 543). Best-effort SIGTERM of the live PID (resolved from `sessions/<pid>.json` body match) then unlink the JSONL + `<sid>.meta.json` sidecar. Absent PID file is not an error. Containment: `projectDir` must live under `<CLAUDE_CONFIG_DIR>/projects/`. | `POST /` |
+| `/session-rc-spawn` | POST `{ sessionId?, name? }` (Task 543). Fire-and-forget `claude --remote-control [name] [--session-id <sid>]`. Present `sessionId` resumes; absent starts a fresh session (also used by the sidebar's "New session" button — it no longer opens claude.ai/code directly). Proxies to the manager's `/rc-spawn`, which waits up to **60 s** (Task 648, raised from 12 s) for the spawned PTY to bind and returns `{ spawnedPid, sessionId, bridgeSessionId, slug, outcome, reason }`. The Sidebar navigates the opened tab to `claude.ai/code/session_<id>` on `outcome=bound`; on `timeout` or `spawn-failed` it shows an error modal (reason + sessionId) and **never** opens a bare claude.ai/code tab. The new process registers itself as its own Remote Control entry in claude.ai/code. | `POST /` |
+| `/claude-sessions` | **Spawn surface only** (Task 500). `POST /` is the Sidebar new-session-with-prompt path, cookie-auth only (Task 626 removed the recorder loopback caller; LinkedIn ingest moved to `/rc-spawn`). The former UI-facing handlers (SSE row feed, list, resume, stop, rename, archive, delete, `/:id/meta`, `/:id/input`, `/:id/log`) were removed — the maxy dashboard no longer manages or displays sessions. | `POST /` |
+
+Task 500 — **admin session management moved entirely to claude's own interfaces** (claude.ai/code, claude desktop). A manager-owned per-account `claude rc --spawn same-dir` daemon registers the device as a Remote Control target there; the composer creates / resumes / stops / renames / archives / deletes sessions, with model + permission-mode applied at inception. The model lever is `account.json.adminModel` → `CLAUDE_CONFIG_DIR/settings.json "model"`, written by the daemon supervisor at boot. The maxy admin UI keeps a single "New session" link (`https://claude.ai/code`, opens in a new tab) and no session list, viewer, controls, or model/mode picker. The daemon supervisor lives at [`platform/services/claude-session-manager/src/rc-daemon.ts`](../../../services/claude-session-manager/src/rc-daemon.ts). The `/session-defaults` route and `SpawnPreference` node were deleted with the picker. `/new-session-failure`, `/new-session-submit`, and `/claude-capabilities` are now orphaned (consumed only by the deleted NewSessionModal) — see [`.tasks/501`](../../../.tasks/) for their removal.
+
+**Row title resolution.** Both the sidebar (`/sidebar-sessions`) and the manager's own row payload resolve a row's title in the same order: operator rename → Claude Code `ai-title` → first non-CLI user message → 8-char sessionId prefix. The operator-rename tier is the on-disk `<accountDir>/session-titles.json` (the manager's `UserTitleStore`), keyed by the CC sessionId — the sidebar reads that same file, so a write to the store lights up both surfaces with one write.
+
+**Task 624 — maxy title for public sessions.** A `role=public` webchat spawn never produces a useful Claude Code `ai-title` (an anonymous one-line visitor turn), so every public row would otherwise read identically. The webchat route (`chat.ts`) composes a deterministic title — `Web · <senderId[:8]>[ · <personId>] · <UTC YYYY-MM-DD HH:mm>` (personId present only for gated visitors) — and threads it through the bridge (`dispatchOnce` → `managerSpawn`) to the manager `POST /spawn` body as `name`. `/spawn` validates it with `validateUserTitle` and, for `role=public` only, writes it into `UserTitleStore` so it occupies the operator-rename tier and wins over `ai-title`. Admin (`/rc-spawn`) and WhatsApp titling are unchanged. Observability: every public spawn logs `[spawn] role=public … title="…"` (or `title=missing`); the manager's row builder emits `[public-title] sessionId=… unexpected titleSource=<ai|null>` on the next list read for any public row that did not resolve from the user tier.
+
+### Graph
+
+| Mount | Purpose |
+|---|---|
+| `/graph-search` | Filtered node search backing the `/graph` page filter chips. |
+| `/graph-subgraph` | Neighbourhood expansion around a focal node. |
+| `/graph-delete` | Soft-trash a node (sets `_trashed:true`). |
+| `/graph-restore` | Undo trash. |
+| `/graph-labels-in-graph` | Distinct label list for the filter dropdown. |
+| `/graph-default-view` | Account-scoped saved view (zoom, focal id, filters). |
+
+### Artefacts and files
+
+| Mount | Purpose |
+|---|---|
+| `/sidebar-artefacts` | Lists every editable artefact for the sidebar Artefacts view (KnowledgeDocuments + this account's IDENTITY / SOUL / KNOWLEDGE / specialist templates). |
+| `/sidebar-artefact-content` | Reads a single artefact's bytes for the artefact pane. |
+| `/sidebar-artefact-save` | Persists an artefact edit. |
+| `/attachment` | Per-attachment binary fetch (images, PDFs, etc.). |
+| `/files` | File browser CRUD (list, download, upload, delete). Listings put directories first, then files newest-first by `mtime` (name tie-break) so a just-changed file leads the panel. |
+
+**Artefact download resolution (Task 524).** Clicking a sidebar Artefacts row
+streams the `KnowledgeDocument`'s real backing file, which can live in one of
+three on-disk classes: the admin-UI upload store (`<DATA_ROOT>/uploads/<acc>/
+<attachmentId>/`), the agent-authored output dir (`<DATA_ROOT>/accounts/<acc>/
+output/<name>`), and the Claude-agent upload store
+(`<CLAUDE_CONFIG_DIR>/uploads/<attachmentId>/`, which is **outside** DATA_ROOT).
+`memory-ingest` persists the real path on the node as `KnowledgeDocument.sourcePath`
+(skipped for web docs, whose temp file is unlinked at ingest), so new ingests
+resolve deterministically; pre-existing rows fall back across the three classes.
+The download route (`/files/download`) accepts `root=data` (default) or
+`root=claude-uploads`; the config-dir root carries no accountId path segment, so
+it is account-scoped by a graph-ownership check (the attachmentId must map to a
+`KnowledgeDocument` carrying the caller's accountId) rather than by path
+partition. Resolution emits `[admin/sidebar-artefacts] download-resolved via=…`;
+a web/transient doc with no persisted file is `not-downloadable reason=no-persisted-file`.
+
+**`/data` File panel — refresh and reload-survival.** The panel listing is a
+snapshot from its last fetch, so a file an agent writes (or an upload/delete
+elsewhere) leaves stale rows and timestamps until something re-fetches. A
+**Refresh** button beside Upload re-fetches the current folder in place (fresh
+`mtime`s, no browser reload). The current directory is mirrored into the URL
+hash (`/data#path=<rel>`), so a browser reload restores that folder instead of
+snapping back to the data root; the hash never reaches the server and `/data`
+has no client router, so the channel is isolated. `path=` is cleared at the
+root for a clean URL.
+
+### Browser / device-browser
+
+| Mount | Purpose |
+|---|---|
+| `/browser` | Programmatic Chromium launcher used by `personal-assistant` browser-automation flows. |
+| `/browser-iframe` | Browser-iframe event ingest from the in-app preview surface. |
+| `/device-browser` | Drives the device's own browser tab (VNC Chromium on Pi). |
+
+### Diagnostics
+
+| Mount | Purpose |
+|---|---|
+| `/logs` | Server log tail with `type=stream\|error\|sse` and `sessionId` filters; powers the in-chat **View logs** popover (see [`internals.md`](internals.md) "Conversations modal — View logs"). |
+| `/events` | Generic SSE event ingest from the UI client. |
+| `/log-ingest` | Loopback-only structured log ingest for MCP and PTY-spawn observability lines (see [`admin-session.md`](admin-session.md) "Memory MCP write-path outcome lines"). |
+| `/claude-info` | Returns Claude CLI binary path, version, and OAuth status. |
+| `/claude-capabilities` | Returns the resolved capability matrix the UI uses to gate features. |
+| `/agents` | Lists every installed agent template; supports `DELETE /:slug` for user-created public agents and `POST /:slug/project` for project assignment. |
+| `/cloudflare` | Tunnel setup surface — see [`cloudflare.md`](cloudflare.md) for the OAuth flow. |
+| `/linkedin-ingest` | LinkedIn Basic Data Export ingest entry point (see [`linkedin-extension.md`](linkedin-extension.md)). |
+| `/health-brand` | Brand-process liveness + 1 s Neo4j probe. Returns `{ok, processStartedAt, version, conversationDb: 'ok'\|'error', uptimeMs}`. The `processStartedAt` is captured at module load, so a stale value after an armed restart means the brand process never came back. |
+| `/system-stats` | Host CPU / RAM / load probe. See next section. |
+
+The companion `/api/admin/version` and `/api/admin/actions` routes are
+served by `maxy-edge.service`, not this aggregator. The edge process
+keeps the upgrade view alive while the brand service restarts.
+
+## System-stats widget
+
+Source:
+[`server/routes/admin/system-stats.ts`](../../../ui/server/routes/admin/system-stats.ts)
+(route) and `SystemStatsWidget` in
+[`platform/ui/app/Sidebar.tsx`](../../../ui/app/Sidebar.tsx)
+(consumer). CSS lives under `.system-stats*` in
+[`platform/ui/app/globals.css`](../../../ui/app/globals.css).
+
+**What the widget shows.** A compact block at the foot of the sidebar
+with one row per metric: `CPU 73%` and `RAM 71%`, each followed by its
+own 4 px saturation bar. Bar fill colour is a smooth green → amber →
+red gradient computed as `hsl(140·(1−pct), 65%, 45%)` so the colour
+reflects each metric's own load. Hidden when the sidebar is collapsed
+to its 56 px icon rail.
+
+**Where the numbers come from.** `GET /api/admin/system-stats` returns a
+snapshot for the host. On Linux the route reads `/proc/stat` twice 100 ms
+apart and computes `cpuPct = 1 - idleDelta / totalDelta`; `memUsedPct`
+comes from `(MemTotal - MemAvailable) / MemTotal` in `/proc/meminfo`; the
+three load averages come from `/proc/loadavg`. A single-flight module
+cache means concurrent callers share one in-flight pair of `/proc/stat`
+reads. On darwin and other non-Linux platforms the route falls back to
+`os.totalmem() / os.freemem() / os.loadavg()` and returns `cpuPct: null`
+— the widget renders a dash rather than fake a value.
+
+**Refresh cadence.** The widget polls every 5 s
+(`SYSTEM_STATS_POLL_MS`). Polling pauses while `document.hidden` is true
+(tab in background) and resumes on `visibilitychange`. On unmount the
+interval is torn down and the visibility listener removed.
+
+**Thresholds.**
+
+| Class | Trigger | Visual |
+|---|---|---|
+| `.system-stats--warn` | `cpuPct >= 0.9` **or** `memUsedPct >= 0.9` | Widget text turns `--danger` red. Bar fill colour is independent (set by the per-bar hue gradient), so the figure text is what carries the warn signal at this band. |
+| `.system-stats--crit` | `cpuPct >= 0.98` **or** `memUsedPct >= 0.98` | Adds a 1.2 s pulsing background animation (`@keyframes system-stats-crit-pulse`) on top of the warn colour. |
+| `.system-stats__fig--warn` | Per-figure: applied to the specific CPU or RAM span that breached `0.9`. | Same red colour, lets the operator see which of the two figures crossed first. |
+
+The warn threshold matches the threshold the operator most commonly
+cares about (a fully-loaded 4-core Pi at 16 GiB RAM crosses 0.9 long
+before anything else on the host notices). The crit threshold pulses
+because it is the band where a swap-thrash episode becomes likely.
+
+**Failure handling.** Any read or parse error inside the route returns
+HTTP 200 with `{degraded: true, reason, sampledAtMs}` so the widget
+keeps showing its last-known value instead of flashing zeros. Failed
+fetches log `[admin-ui] system-stats-fetch-failed status=<code>` (or
+`reason=<message>`) to the browser console; successful polls are silent
+client-side. Server-side every poll logs one
+`[system-stats] poll cpuPct=<f3> memUsedPct=<f3> loadAvg1=<f2> swapUsedPct=<f3> platform=<linux|darwin|other> ms=<n>`
+line; errors emit
+`[system-stats] error file=<path|parse> reason=<message>`.
+
+**Diagnostic grep.**
+
+```bash
+grep '\[system-stats\] poll' ~/.${brand}/logs/server.log | tail -20
+grep '\[system-stats\] error' ~/.${brand}/logs/server.log | tail
+```
+
+A 0.000 reading that persists across many polls while `top` shows load
+is the delta-cache regression signature (the single-flight promise was
+not released).
+
+## Sidebar surfaces
+
+The sidebar is the entire left column of the admin UI. Its full layout,
+responsive breakpoints, drag-resize behaviour, and the
+new-session strip / nav rows / sessions list / footer ordering are
+documented in
+[`platform.md`](platform.md) "The Web Interface" — that paragraph is
+authoritative. This section names the surfaces and what backs each.
+
+| Surface | What it does | Backed by |
+|---|---|---|
+| `+ New session` button | Opens `NewSessionModal`, which POSTs `{channel, permissionMode, model, initialMessage}` to `/api/admin/claude-sessions`. | `claude-sessions.ts` |
+| Mode trigger | Per-`(accountId, userId)` `SpawnPreference` for `permissionMode` and `model`; persists across reload, tab, device. | `session-defaults.ts` |
+| Nav rows (Chat / People / Agents / Projects / Tasks / Artefacts) | People, Agents, Tasks open the artefact-pane Graph filtered to the matching label. Chat selects the active conversation. Artefacts swaps the list to editable documents. | `graph-search.ts`, `graph-subgraph.ts`, `sidebar-artefacts.ts` |
+| Sessions list (Active / Archived / All) | Live row store driven by SSE; manual reconcile button on the segmented control re-fetches the full id set. | `/claude-sessions/events`, `/claude-sessions` |
+| Conversations row hover actions | Inline rename, archive, delete, JSONL view / download per row. The historical `.conversations-modal` CSS block exists in `globals.css` but is no longer mounted from any TSX — Sidebar.tsx now owns every per-row affordance directly. | `claude-sessions.ts` |
+| Artefacts list | Lists every KnowledgeDocument plus this account's IDENTITY / SOUL / KNOWLEDGE / specialist templates. Click downloads the row's backing file (`downloadPath` → `GET /api/admin/files/download`) so the operator opens it in their local app; rows whose file is outside `DATA_ROOT` (bundled-fallback templates) show a "can't be downloaded" pill. The in-app artefact pane is dead pending removal (Task 518). | `sidebar-artefacts.ts`, `files.ts` |
+| System-stats widget | CPU / RAM widget at the foot of the sidebar. | `system-stats.ts` (see above) |
+| Footer | Operator avatar, name, role, and the actions popover. | `session.ts` |
+
+## Artefact pane
+
+The right-hand pane that opens when the operator selects an artefact,
+clicks a project (Graph view), or opens Browser / Data / Graph from the
+menu. It holds the surface side-by-side with the conversation so the
+chat stays live.
+
+- Editable artefacts (KnowledgeDocuments + the account's own IDENTITY /
+  SOUL / KNOWLEDGE) auto-save on type via
+  `POST /api/admin/sidebar-artefact-save`.
+- Read-only artefacts (specialist agent templates) cannot be edited
+  because they ship with Maxy and would be overwritten on the next
+  install.
+- PDF artefacts render inline; non-PDF binaries fall back to a Download
+  button when the browser has no native viewer.
+- Orphan rows (no readable file on disk, unsupported content type) show
+  a one-line banner explaining the skip instead of opening to a blank
+  pane.
+
+Below 1080 px the pane hides and Browser / Data / Graph open as
+full-window pages instead. The chat-and-pane divider is drag-resizable
+on every admin page; double-click resets to half the available width
+(viewport minus sidebar), clamped to the per-pane min-width floors. The
+chosen width is remembered across reloads.
+
+## Health vs version
+
+Two endpoints, two surfaces, two restart-survival roles:
+
+- `GET /api/admin/health-brand` (this aggregator) — brand-process
+  liveness. `processStartedAt` resets on every brand-service restart;
+  Neo4j probe is bounded to 1 s and reports
+  `conversationDb: 'ok' | 'error'`. Use this to confirm the brand
+  process came back after a Cloudflare-setup armed restart.
+- `GET /api/admin/version` (maxy-edge) — installer / brand version
+  string. Hosted on `maxy-edge.service` so the Software Update modal
+  can read it while the brand service is mid-restart.
+
+## Related references
+
+- [`platform.md`](platform.md) — UI layout, session reconcile model,
+  artefact pane behaviour in full detail, breakpoints.
+- [`admin-session.md`](admin-session.md) — admin session token, PIN-
+  rebind, SDK-resume, structured log lines.
+- [`internals.md`](internals.md) — retrieval pipeline, end-turn auto-close
+  auto-archive, graph-prune-denylist surface, conversation logs.
+- [`cloudflare.md`](cloudflare.md) — tunnel setup OAuth flow that
+  `/api/admin/cloudflare/setup` drives.
+- [`deployment.md`](deployment.md) — Pi setup; the brand-service / edge-
+  service split that the health-vs-version table above relies on.