@rubytech/create-sitedesk-code 0.1.340

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

@@ -0,0 +1,397 @@
+# 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 SiteDesk installer; the SiteDesk 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.
+
+## UI conventions
+
+**Icons are Lucide components only — no emoji.** Every glyph rendered in
+`platform/ui` JSX (the `/chat` web chat, the WhatsApp/channel readers, the
+admin shell, the `/data` grid) is a `lucide-react` component (e.g.
+`<Paperclip>`, `<FileText>`), never an emoji/emoticon character in the rendered
+string. The rule is enforced at build time by
+[`scripts/check-no-emoji-in-jsx.mjs`](../../../ui/scripts/check-no-emoji-in-jsx.mjs),
+which fails `prebuild` if any emoji codepoint appears in a `.ts`/`.tsx` file
+under `app/` (tests excluded). Inline an icon at the surrounding text size and
+colour (`size={14}` matches body text; Lucide inherits `currentColor`).
+
+## 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. One JSONL on disk equals one row. The row's delete button 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 — 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 }`. 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? }`. 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** (raised from 12 s) for the spawned PTY to bind and returns `{ spawnedPid, sessionId, bridgeSessionId, slug, outcome, reason }`. For a webchat-bound spawn (every admin-gated host's "New session", returning a same-origin `/chat?session=<id>` target — `resolveRcSpawnOutcome` → `sameOrigin:true`) the Sidebar navigates the **current** tab via `window.location.assign`, replacing the dashboard in place (back returns to it); only a claude.ai/code slug (`sameOrigin:false`, the bare-admin resume bridge, never a new-session outcome) navigates a separately-opened tab. 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**. `POST /` is the Sidebar new-session-with-prompt path, cookie-auth only (the recorder loopback caller was removed; 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 /` |
+
+**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 reasoning-effort lever is `account.json.effort` → `settings.json "effortLevel"` (accepted values `low|medium|high|xhigh`; any other value, e.g. legacy `"auto"`, leaves the key unset so claude's own default governs), written by the same read-merge-write at boot. A third inception lever, permission mode, is added: `account.json.adminPermissionMode` → `settings.json "permissions.defaultMode"` (the 5 composer-writable modes `default|acceptEdits|plan|auto|bypassPermissions`; `dontAsk` is out of scope). Unlike model/effort (top-level keys), this lever **deep-merges** the nested `permissions.defaultMode`, owning only that key and preserving sibling `permissions` keys (allow/deny/…) — what the binary and the spawn lifeline actually read. **For admin sessions, permission mode is fixed (Bypass) and not operator-chosen, while model and effort ARE operator-chosen at launch** via the composer's `+` new-session popover — a radio model list (Opus / Sonnet / Haiku) plus a 5-stop Faster→Smarter effort slider (Low / Medium / High / Extra / Max, where `max` applies via the `--effort` argv rather than `settings.json`); the popover description lives in `.docs/admin-webchat-native-channel.md`. Absent a pick (and on every resume), the daemon-pinned defaults govern: the `/chat` composer *footer* carries no live re-seat pickers — `rc-daemon.ts` pins settings.json `model`/`effortLevel`/`permissions.defaultMode` to `claude-opus-4-8[1m]` / `medium` / `bypassPermissions` regardless of `account.json` (read by the rc-spawn webchat path), and `pty-spawner.ts` forces the claude.ai/code PTY `--permission-mode` to `bypassPermissions` for `role=admin`. Public sessions are fixed to `claude-sonnet-4-6` (the `/public-spawn` chokepoint + `buildPublicWebchatSpawnRequest`), keeping `dontAsk`. The composer footer instead renders a **read-only** params row (mode · model · effort labels) plus a context-window usage figure (`pct% · ~used/~window`), all sourced from the session pointer; the full path is in `.docs/admin-webchat-native-channel.md`. The composer cannot re-seat a session, so the "no transcript" 400 on a brand-new chat is unreachable; the `/api/admin/session-reseat` + `/api/webchat/settings` routes and the dashboard re-seat form stay as off-composer surfaces. When the live session runs in `default` ("Ask permissions") mode, a tool the agent attempts that needs approval surfaces an Allow/Deny card in the composer (tool, description, argument preview); a click sends the verdict over Claude Code's channel permission relay and the tool runs or is refused — webchat is the only interactive ask surface (WhatsApp stays text-only; Telegram has no agent channel). Beyond the composer, the maxy admin UI keeps a single "New session" link (`https://claude.ai/code`, opens in a new tab) and no separate 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.
+
+**`/chat` empty-state greeting panel.** While the admin webchat has no conversation JSONL yet (`GET /api/webchat/session` → `projectDir:null`), `app/chat/page.tsx` renders a "What's up next, {givenName}?" greeting (given name = first whitespace token of the admin session's `userName`) above two read-only lists from `GET /api/webchat/greeting` (`server/routes/webchat-greeting.ts`, `requireAdminSession`-gated, `accountId`-scoped): the next 5 upcoming `:Event` rows (`eventStatus IN ['scheduled','due']`, future `COALESCE(nextRun, startDate)`, soonest first) and the outstanding `:Task` rows (`status IN ['pending','active','running']`, 5 shown + `+N more`). Read failure returns HTTP 200 `{ ok: false }` and the page shows the headline alone — the panel never blocks the composer. A third section, **Your specialists**, shows the account's installed roster — every `*.md` under `data/accounts/<accountId>/specialists/agents/`, core and `--`-prefixed premium files alike — shown by frontmatter `name` + `summary` (fallback `description`), empty dir → "No specialists installed". The roster read (`app/lib/claude-agent/specialist-roster.ts`) is isolated from the graph fallback: malformed files are skipped (`op=specialist-skipped file=<name> reason=<…>`), a whole-roster failure degrades to `specialists: []` inside the `ok: true` payload (`op=specialists-read-failed`). Logs: `[webchat:greeting] op=read account=<id8> events=<n> tasks=<n> specialists=<n> ms=<n>` / `op=read-failed reason=…`; client warns `[admin-ui] greeting-unavailable …`. The full webchat architecture lives in `.docs/admin-webchat-native-channel.md`.
+
+**`/chat` Claude-desktop transcript presentation.** The admin webchat keeps the shared `Transcript` shell (stream, follow-tail) but injects a /chat-only item renderer via the component's optional `renderItems` prop: `renderChatTimeline` in `app/chat/transcript-render.tsx`. Presentation: operator turns render as a right-aligned grey bubble showing the message text and, beneath it, a subtle always-visible time-of-day stamp (no label); delivered agent replies render as plain prose with the same time-of-day stamp beneath (the reply-document filename line stays, as prose); the stamp is HH:MM from the turn's `ts` (locale-formatted, right-aligned inside the operator bubble, left-aligned under agent prose), and a turn whose `ts` is null/unparseable shows no stamp, never an empty line — so only delivered operator and agent-reply turns are stamped, while tool runs, the collapsed "Thinking" block, and the agent-error banner stay time-free; a maximal consecutive run of `tool-call`/`tool-result` turns renders as one collapsed grey one-liner ("Used N tools ›") whose expansion shows every call and result payload — a lone call still gets the one-liner, and prose or a directive row ends a run. The WhatsApp reader (`/whatsapp`) omits the prop and keeps the default `renderTimeline`, so its rendering is unchanged; both presentations are test-pinned (`app/whatsapp/__tests__/Transcript-*.test.tsx`, `app/chat/__tests__/transcript-render.test.tsx`). **Day-divider:** both renderers insert a centered `.day-divider` row between two consecutive timeline items on different local calendar days (label `Today`/`Yesterday`, else `Sat 14 Jun 2026`), so a thread spanning midnight is never an ambiguous run of HH:MM; the first dated item gets a leading divider, a null/unparseable `ts` marks no boundary, dividers are computed over the filtered `visibleItems`, and in `/chat` a day crossover flushes any open tool/think run first so a collapsed run never spans it. Per-bubble HH:MM stamps are unchanged. Shared helpers `dayKey`/`dayLabel`/`itemTs`/`DayDivider` live in `app/whatsapp/Transcript.tsx`.
+
+**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 native webchat gateway's public spawn (`handleInbound` → `buildPublicWebchatSpawnRequest` → `managerSpawn`) to the manager `POST /public-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.
+
+**Public visitor surface.** The public-host root (`GET /`), the `/:slug` agent routes, and the admin-host `/public` / `/public-chat` previews all serve one shell, `public.html` → [`app/public-entry.tsx`](../../../ui/app/public-entry.tsx) → `PublicChat`. `PublicChat` reuses `useSession` purely as the magic-link gatekeeper — it drives `AccessGate`, resolves the agent slug from the path, and handles `?token=` verification; once the grant is satisfied it mounts `ChatSurface variant="public"`, whose transcript reads the visitor-scoped, **delivered-only** stream `GET /api/public-reader/stream` ([`server/routes/public-reader.ts`](../../../ui/server/routes/public-reader.ts)) — the visitor sees the agent's delivered prose, never the tool/tool-result/directive bytes the legacy `/api/chat` SSE render exposed. The human visitor's branding is resolved client-side by `useSession`. For the head only, the server injects per-agent link-preview meta — `<title>`, `og:title`/`og:description`/`og:image`, `theme-color`, and a per-agent favicon, resolved from the same branding cache `useSession` reads — into the served shell, so a link-preview crawler (which never runs the client bundle) gets a branded card per agent instead of one generic shell; an agent with no branding cache gets the clean brand-default shell with no empty meta tags. There is exactly one public client surface and it is 1:1 visitor↔agent: the earlier `?surface=next` A/B handle is retired, group messaging is retired (not a supported product surface), and a former `/g/<slug>` group URL now serves the same 1:1 shell — a stale bookmark gets the 1:1 chat, never a broken render.
+
+### 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 the sidebar Artefacts rows: every `:FileArtifact` under this account's tree (`relativePath STARTS WITH 'accounts/'` — all file types, excluding the separate `uploads/<id>/` subtree) plus 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. Upload is a raw-body stream (file bytes are the request body; `session_key`/`path`/`filename` in the query) written to disk without buffering — ceiling 2 GB (`MAX_DATA_UPLOAD_BYTES`), over-ceiling bodies abort mid-stream with `413`; the client shows a determinate progress bar. Distinct from the 50 MB in-memory chat-attachment cap. |
+
+**Artefact download resolution.** 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** icon inside the search bar (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.
+
+**`/data` upload — button and drag-drop.** Besides the Upload button (one OS-picked
+file, stored under a timestamped name), files and whole folders can be dragged
+onto the file-browser body to upload into the open folder. A dropped folder's
+subtree is recreated under the open folder and every contained file uploaded,
+preserving source names and relative paths (a same-named file in an existing
+folder is overwritten; empty source subfolders are skipped). The drop region
+shows an active outline while a drag is over it and is inert wherever the open
+folder is not writable (outside the operator's own `accounts/<id>/…` subtree),
+rejecting the drop with the same "Open a folder inside your account to upload"
+guidance as the button. Each drop reports an uploaded/skipped summary; a file
+that fails the 50 MB limit, the MIME allowlist, or its HTTP write is skipped
+individually without aborting the rest, and every uploaded file is indexed for
+search exactly as the button path is. The server `/files/upload` endpoint takes
+an optional `relpath` form field (the file's path relative to the drop root); it
+recreates that path's directories under the open folder, scope-checked level by
+level, and writes the file under its original basename. A flat upload (no
+`relpath`) is unchanged.
+
+**`/data` operator surface.** `/data` mounts the operator
+`HeaderMenu` (logo-left / name-centre / burger-right; flyout = Chat / Data /
+Log out) above the toolbar — the burger's Chat item returns to `/`, replacing
+the former standalone Home button. The search bar flexes to fill its toolbar
+row; the four file actions (Refresh, Upload, New folder and the list↔grid view
+toggle) sit beside it as one uniformly styled icon group, collapsing under a
+single `⋯` overflow menu at `≤640px`. File rows are two stacked full-width lines
+(name, then `size · modified`) with no file-type icon, no hover download icon,
+and no per-row delete button; a folder row keeps its glyph and navigates on tap,
+a file row downloads on tap. **Long-press** a file row to enter multi-select:
+every file row shows a selection indicator, the search bar becomes a Cancel
+control, and a fixed bottom bar offers **Share / Download / Delete** over the
+selection. Delete removes the non-protected files and keeps protected ones
+(`N protected file(s) kept`); the listing carries a per-entry `protected` flag
+from `isProtectedFromDeletion` so the UI never re-derives the rule. Share uses
+the Web Share API and is disabled where unavailable. Signals:
+`[data-ui] op=mount header=operator home=absent`, `op=select-enter`,
+`op=select-exit reason=<cancel|action>`, `op=share supported=<bool> count=<n>`.
+
+**`/data` list ↔ grid view + image thumbnails.** A toolbar toggle switches the
+file browser between the two-line list and a **grid**. In grid view, image
+files render an inline thumbnail; folders render a folder tile (still navigate
+on tap); every other file renders a labelled tile (name + size) that downloads
+on tap. Tapping a thumbnail opens a full-size overlay (reusing the chat
+attachment overlay), not a download — download stays reachable via long-press →
+select → Download. The chosen view persists across reload and `/data` ↔ `/`
+navigation (`localStorage['maxy-data-view']`). A file counts as an image only
+when its **extension** is one the inline-serve route can serve
+(`png/jpg/jpeg/gif/webp/svg`, the server's `detectMimeType` image set) — the
+sidecar `mimeType` is not consulted, so the grid never promises a thumbnail the
+serve route would refuse. Thumbnails load from the same `/api/admin/files/download`
+route with `disposition=inline` (`inlineImageUrl`), which for an `image/*` file
+returns the bytes with **no** `Content-Disposition` and a cacheable header so the
+browser renders them in an `<img>`; a non-image inline request is refused `400`,
+and the account-scope guard is identical to the attachment path. Signals:
+`[data] op=view-mode mode=<grid|list>`, `[data] op=thumb-serve path=… mime=… size=… status=200`,
+`[data] op=thumb-refused path=… reason=not-image`, and client `[data] op=thumb-error path=…`
+from a thumbnail that fails to load.
+
+**`/data` search — locate-in-files link and clear button.** Every
+search hit is a `:FileArtifact` backed by a physical file, so each result card
+whose `relativePath` is a non-empty string carries a **locate link** (folder
+icon + containing folder; root-level files show `data`). Clicking it clears the
+active search (query, results, error, chip) and navigates the file browser to
+that folder via the same `path` state + `#path=` hash contract above, so the
+file appears among its siblings and a reload restores the place. The link is a
+sibling of the clickable card, so it never triggers the row's download. Hits
+without a usable `relativePath` render no link; one
+`console.warn('[data-search] op=locate-link-missing nodeId=…')` per result set
+surfaces the index gap, and each click logs
+`[data-search] op=locate nodeId=… folder=…`. The search bar shows an **× clear
+button** while it holds text — clicking empties the input, clears results
+(restoring the file-browser body), and refocuses the input.
+
+### Browser / device-browser
+
+| Mount | Purpose |
+|---|---|
+| `/browser` | `POST /launch` — launches Chromium on the resolved transport (native display or VNC) on demand. Backs the standalone `/browser` operator page. Lifeline tag `[admin/browser/launch]`. |
+
+The in-chat / artefact-embedded brand-VNC iframe components and the
+`/browser-iframe` event-beacon route were retired and stay
+deleted; the `/device-browser` (navigate-the-device-tab) route was also
+removed and is not restored. The standalone `/browser` page is a
+sanctioned operator surface peer to `/graph` and `/data`: it embeds the live
+VNC viewer (`/vnc-viewer.html`, popout `/vnc-popout.html`) and calls
+`/api/admin/browser/launch`. On darwin (no noVNC asset) it shows a "VNC surface
+not available" state.
+
+### 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.
+
+> **Admin variant only.** Every surface below belongs to the `admin` shell
+> variant. The **operator** variant (`operator.<host>`) mounts no sidebar at
+> all: its dashboard is the persistent admin webchat at `/` and the data
+> browser at `/data`, plus a read-only **Conversations** reader reached from a
+> dynamic burger item — header order Chat → Conversations → Data → Log out, in
+> a single-column `.platform.platform-operator` grid. The operator never sees
+> the sessions list or the nav rows; the Conversations reader lists the agent's
+> inbound channel conversations (WhatsApp, Telegram, public webchat) read-only
+> via the same admin-gated reader routes, never the operator's own session. The
+> operator surface is documented in full in the internal doc
+> `maxy-code/.docs/operator-dashboard.md`.
+>
+> **Width.** The operator header, the operator chat column, and the `/data`
+> header+toolbar+body all render in one centred column bounded to
+> `--chat-measure` (48rem). That token is a `:root` design token (beside
+> `--measure`/`--gutter`); the operator-header clamp
+> (`.admin-shell-root:has(> .platform-operator) > .admin-header`), the chat-column
+> clamp (`.platform-operator > .webchat-page`), and the `/data` clamp
+> (`.data-main`) all read it, so logo and burger align to the panel edges on both
+> surfaces. The admin shell carries no `--chat-measure` consumer and stays
+> edge-to-edge; the public webchat (`.public-surface`) inherits the same value.
+>
+> **Conversations item.** The dynamic Conversations burger item appears on
+> **both** the operator chat surface and `/data` whenever ≥1 reviewable
+> conversation exists (the count/channels are fetched per surface from
+> `/whatsapp-reader/conversations` with the operator's session key). On `/data`
+> selecting it renders the same read-only reader in place (the file browser is
+> swapped for it; Back returns). The flyout-open signal
+> `[operator-ui] op=conversations-menu present=<bool> channels=[…] count=<n>`
+> fires on `/data` too — `present=false` there while the chat surface shows the
+> item is the props-not-wired signature.
+
+| 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. **The "Projects" row is brand-aware:** its visible term and the graph label it filters to both come from the injected `window.__BRAND__.primaryContainer` (`brand.json` → `server/index.ts` inject → `brand.ts` `brandPrimaryContainer()`), so SiteDesk reads "Projects" → `:Project`, SiteDesk "Jobs" → `:Job`, Real Agent "Properties" → `:Property`. A brand JSON missing `primaryContainer` falls back to Project/Projects (server logs `[brand] op=primaryContainer-default reason=absent brand=<hostname>`; the populated case logs `[brand] op=inject primaryContainer=<label>/<term>`). | `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. Every listed row carries two launch actions: the claude.ai/code resume (`ExternalLink`) and a chat-launch (`MessageSquare`) that opens `/chat?session=<full sessionId>` — the admin webchat pointed at that exact session; sending there resumes a stopped session with the webchat channel bound to that id (see `admin-webchat-native-channel.md`, "Session-targeted mode"). At the ≤720 px drawer breakpoint each row stacks into two lines — dot + title + id/stamp, then the action icons — with a divider between rows and actions at full opacity (the desktop hover-gated 0.5 opacity never resolves on touch). Below a 400 px list width each row's action icons collapse to a single `MoreHorizontal` ellipsis trigger; its popover menu lists the same actions as the inline icons but labels them with concise verbs (`Resume in claude.ai/code`, `Open in webchat`, `Stop`, `Archive` / `Unarchive`, `Rename`, `Delete`, `Re-seat`) rather than the inline icon buttons' verbose per-session aria-labels — the inline buttons keep those verbose labels because an icon-only control needs the full descriptive accessible name. **Re-seat:** Re-seat is a member action of the one `SessionRowActions` cluster, not a separate sibling control — wide it is the sliders icon inline with the other icons (sharing the cluster geometry and alignment); collapsed it is the `Re-seat` menu item, which expands the model/mode/effort form inline inside the overflow menu. The form (`SessionReseatControl`) forks the session via `/api/admin/session-reseat` and navigates to the fork (the same fork mechanism `/chat`'s pickers drive); its model picker defaults to the row's current model (a `model` field on each row, read from the JSONL tail), and mode and effort each carry a "Keep" option that omits the field. The overflow menu and the Re-seat form render through a `document.body` portal, fixed-positioned from the trigger's rect (right-aligned, flipped above the trigger when there is no room below), so neither is clipped by `.side-list`'s `overflow-y:auto`; Escape, a pointerdown outside the trigger/popover, and any scroll or resize dismiss them. | `/claude-sessions/events`, `/claude-sessions`, `/session-reseat` |
+| Channel reader nav rows (WhatsApp / Telegram) | One conditional nav row **per interactive channel that has ≥1 admin session**. Each row carries its brand glyph (WhatsApp `#25D366`, Telegram `#229ED9`); a channel with no admin session shows no row, and no install ever shows an always-empty "No conversations" row. The channel list loads **once on sidebar mount** (the per-channel counts must be known before the nav renders), so a failed load shows one muted, non-clickable line instead of channel rows. Clicking a channel row lists that channel's admin conversations; each conversation row shows a **display name** resolved by precedence `operatorName ?? whatsappName ?? senderId ?? title`: the bound `Person givenName familyName` when a `senderId`→`userId` binding exists, else the persisted WhatsApp display name (`pushName`, read from the latest `:Message:WhatsAppMessage.senderName`), else the raw `senderId`, else the agent title; the agent session title is the hover tooltip only. Under the name each row shows a **last-message-time breadcrumb** (`conv-timestamp`, same markup as the Sessions rows) formatted from the row's `lastMessageAt` (the last parseable turn's `ts`); a session with no parseable turn shows no time, never "Invalid Date". **Re-seat:** each channel conversation row carries a `SessionRowActions` cluster whose sole action is Re-seat (the row is a `conv-with-actions` shell whose open click moved onto an inner button so the cluster can sit beside it), so a WhatsApp/Telegram session's model/mode/effort is re-seatable from the dashboard exactly like a webchat row — wide it is the inline sliders icon, and below the 400 px width it folds into the `…` overflow menu identically to the Sessions rows; the channel reader row carries the same `model` field for the picker default. A click on a conversation **opens its transcript on the home surface**: on `/` it selects in place, and from any other route (`/graph`, `/data`, `/browser`) it navigates to `/?wa=<sessionId>&projectDir=<dir>`, which the root shell hydrates on mount (then strips the query so a later refresh does not re-pin a closed conversation). Server logs `[wa-reader] op=operator-name-fallback senderId=… source=whatsapp-pushname` when the pushName fallback fires and `[wa-reader] op=conversations count=<n> withTimestamp=<m>` per list build; the client logs `[admin-ui] wa-open route=… via=<in-place\|navigate> …` and `[admin-ui] wa-hydrate route=/ …`. | `/whatsapp-reader/conversations` |
+| Channel transcript (`<Transcript>`) | Reads one session's JSONL over SSE (`/whatsapp-reader/stream`) and renders both sides plus tool calls — the turns claude.ai/code hides because channel inbound is stamped `isMeta`. Every turn shows its time-of-day (HH:MM from the turn's `ts`; a null/unparseable `ts` shows no time, never "Invalid Date"). `tool-call`/`tool-result` turns render as **collapsed cards** (chevron + label + time, default collapsed, expandable per card; one card's state never affects another) so the human↔agent text is not buried in JSON; the three conversation kinds always render in full. The thread **follows the tail**: it opens at the newest turn and pins to the bottom on each live append **only while the operator is already within 32 px of the bottom** — a scroll up suppresses the jump so reading history is never yanked. While the operator is scrolled up a **jump-to-bottom control** (`.wa-jump`, bottom-right of the viewport) appears; clicking it scrolls to the newest turn and re-arms follow-tail, and it hides again at the bottom. The thread scrolls inside its grid cell (header/sidebar/footer fixed). The stream sends a 20 s heartbeat so an idle Cloudflare tunnel does not idle-drop, tags each frame with a byte-offset `id:`, and resumes from the client's `Last-Event-ID` on reconnect (no duplicate backlog); the client clears the "Stream disconnected" banner on reopen and latches it only on a terminal CLOSED state. The thread also interleaves a collapsed `⚙ directive injected (N B)` row per turn, sorted by timestamp just before the turn it informed; expanding one fetches the exact stored `prompt-optimiser-directive` bytes for that turn. The entries are listed by `GET /whatsapp-reader/directives?sessionId=` and the bytes served by `GET /whatsapp-reader/directive?sessionId=&name=`, both admin-gated and account-scoped; a missing store degrades to no rows. A centered day-divider row (`.day-divider`) marks each local calendar-day crossover between consecutive turns so a thread spanning midnight is unambiguous. | `/whatsapp-reader/stream`, `/whatsapp-reader/directives`, `/whatsapp-reader/directive` |
+| 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 `:FileArtifact` under this account's tree (`relativePath STARTS WITH 'accounts/'`, all file types, excluding the `uploads/<id>/` subtree) 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. | `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 SiteDesk 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.

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

@@ -0,0 +1,87 @@
+# AEO (Answer Engine Optimisation) — user guide
+
+The AEO plugin shapes the site for answer engines (Claude, ChatGPT, Perplexity, Google AI Overviews, Bing Copilot). It does three things: emits schema.org JSON-LD from typed graph entities, generates `/llms.txt` and `/llms-full.txt`, and audits any page against eight heuristics.
+
+## When to use it
+
+- A new page is being authored and you want it to be cited when customers ask an answer engine about your service.
+- An existing page is not being cited. Audit it to find the structural reasons.
+- You're standing up a new site and want the `llms.txt` pair generated so answer engines can index your content directly.
+
+## The tools
+
+### `aeo-emit-jsonld`
+
+Generates a `<script type="application/ld+json">` block for a typed entity. Two modes:
+
+- **From the graph.** Pass `entityId` (Neo4j elementId of an `Organization`, `Person`, `Service`, `Product`, `CreativeWork`, `FAQPage`, `RealEstateListing`, or `Event`). The tool resolves the entity, maps the label to its schema.org type, and emits the block.
+- **Inline.** Pass `label` (one of the supported page types) plus a `properties` object. Use this when the page isn't backed by a stored entity (yet) but you want the JSON-LD shape.
+
+Returns the parsed JSON-LD object and a ready-to-inline script block string. Inline the script in your page `<head>`.
+
+### `aeo-write-llms-txt`
+
+Generates the `llms.txt` / `llms-full.txt` pair for the account. Source is every `KnowledgeDocument` for the account that has a `url` property. Returns both files as strings plus a count of pages skipped because they had no URL.
+
+Wire the output to your site host. Convention: `/llms.txt` (index) and `/llms-full.txt` (concatenated content), served as `text/plain`. Format follows the current draft at `https://llmstxt.org/`.
+
+### `aeo-audit-page`
+
+Runs the eight-heuristic audit. Pass either `url` (the tool fetches) or `html` (you supply the rendered content). Returns:
+
+```
+{
+  "score": 0–100,
+  "heuristics": [
+    {
+      "name": "structured-answer",
+      "status": "pass" | "warn" | "fail",
+      "detail": "first <p> after <h1> is 142 chars",
+      "suggestion": "Add one ≤280-character <p> immediately after the <h1>…"
+    },
+    …
+  ],
+  "target": "<url or '(inline html)'>",
+  "audit": { "runAt": "<iso>", "elementId": "<set when persisted>" }
+}
+```
+
+Pass `persist: true` plus `targetKnowledgeDocumentId` to write the result as an `:AEOAudit` node linked to the document.
+
+## The eight heuristics
+
+| Heuristic | What it checks |
+|---|---|
+| `h1-present` | exactly one `<h1>` |
+| `jsonld-present` | at least one parseable JSON-LD block |
+| `structured-answer` | first `<p>` after `<h1>` is ≤280 chars |
+| `faq-section` | `FAQPage` JSON-LD on the page |
+| `meta-description` | 80–160 char `<meta name="description">` |
+| `canonical-url` | `<link rel="canonical">` present |
+| `og-tags` | `og:title` and `og:description` both set |
+| `heading-hierarchy` | no level skips (h1→h3 etc.) |
+
+`structured-answer` is the highest-impact: that one paragraph is what gets lifted into the engine's answer. A page can fail every other heuristic and still be cited if this one passes.
+
+## Observability
+
+Every tool emits a single log line per invocation:
+
+- `[aeo-emit-jsonld] entityId=… schemaType=… source=graph|inline`
+- `[aeo-llms-txt] site=… pages=… skippedNoUrl=… indexBytes=… fullBytes=…`
+- `[aeo-audit] target=… score=… fails=… warns=…`
+
+Diagnostic path: `grep -E '^\[aeo-' platform-logs/*.log | grep <urlOrEntityId>`.
+
+## What this plugin does not do
+
+- **No citation monitor — out of scope.** Tracking whether your brand is cited by Claude / ChatGPT / Perplexity / Gemini would require multi-engine answer harvesting that doesn't fit maxy-code's no-API-key architecture. Archived without sprinting. Check citation manually when needed.
+- **No auto-emission on page render.** `aeo-emit-jsonld` is callable on demand. Wiring it into the platform's page-generator render path is per-renderer work, filed as a follow-up.
+- **No publish-hook regeneration of `llms.txt`.** The tool runs on demand. Hooking it into the publish event is a follow-up.
+
+## See also
+
+- Plugin manifest: `platform/plugins/aeo/PLUGIN.md`
+- Structured-answer template: `platform/plugins/aeo/skills/structured-answer/SKILL.md`
+- Schema declaration: `platform/neo4j/schema.cypher` (search `AEOAudit`)
+- Spec source: `https://llmstxt.org/`

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

@@ -0,0 +1,44 @@
+# Admin Chat Attachments
+
+What you can drag-and-drop into the admin chat window, what happens to each file, and the size caps.
+
+## Accepted file types
+
+| Type | MIME | Notes |
+|------|------|-------|
+| Images | `image/jpeg`, `image/png`, `image/gif`, `image/webp` | Rendered inline by the agent when relevant. |
+| PDF | `application/pdf` | The agent reads the text; scanned PDFs go via OCR if available. |
+| Plain text, Markdown, CSV, HTML | `text/plain`, `text/markdown`, `text/csv`, `text/html` | Read directly. |
+| Calendar | `text/calendar` | Ingested into the graph if the agent finds a reason to keep it. |
+| Voice note | `audio/*` | Transcribed before the message is routed to the agent. |
+| **Zip archive** | `application/zip`, `application/x-zip-compressed` | Unpacked by the agent after safety checks. See below. |
+
+Anything else is refused at upload time with a message naming the type.
+
+## Size caps
+
+- **Per file:** 50 MB. Enforced at the upload endpoint — files over this limit never reach disk.
+- **Per message:** up to 5 files.
+- **Uncompressed contents of a single zip:** 100 MB. A zip whose declared uncompressed total is over this limit is refused before any byte is extracted (decompression-bomb guard).
+
+## What happens with a zip archive
+
+When you drop a `.zip` into chat, the agent:
+
+1. **Checks the archive is safe.** It refuses archives that try to write outside their own extraction folder, contain symlinks, are password-protected, or declare more than 100 MB of uncompressed content. You'll see the exact reason in chat if any check fails.
+2. **Extracts it to a fresh folder.** Contents land under `{your-account-dir}/extracted/{id}/` — one folder per archive, never mixed.
+3. **Lists what's in it.** The agent tells you the top-level entries, the total file count, and the uncompressed size.
+4. **Asks before doing anything else.** For each class of file (text/markdown, images, PDFs, other), it proposes one next step — for example "ingest these notes into memory" or "re-attach the images back to chat so you can see them" — and waits for you to say yes.
+
+Nothing is ingested, sent, or acted on automatically. The extraction is local and visible; you decide what happens next.
+
+## What is **not** supported
+
+- `tar`, `tar.gz`, `7z`, `rar` — zip only. If you have one of these, unzip/convert locally and upload the zip (or the extracted files directly).
+- Nested archives — a zip-inside-a-zip is extracted one level; you can ask the agent to unpack the inner one afterwards.
+- Password-protected zips — the agent will tell you to unlock locally and re-upload.
+- Uploads larger than 50 MB — split the archive, or upload the individual files.
+
+## Where the files live
+
+Uploads go to `{install-dir}/data/uploads/{account-id}/{file-id}/` — outside the platform wipe zone, so they survive re-installs. Extracted zip contents go to `{account-dir}/extracted/{file-id}/`. Both are local to your device.