@rubytech/create-maxy-code 0.1.36 → 0.1.38

package/payload/platform/plugins/admin/PLUGIN.md

@@ -53,6 +53,17 @@ hidden:
   - wifi
 always: true
 embed: false
+mcp:
+  command: node
+  args:
+    - ${PLATFORM_ROOT}/lib/mcp-spawn-tee/dist/index.js
+    - ${PLATFORM_ROOT}/plugins/admin/mcp/dist/index.js
+  env:
+    MCP_SPAWN_TEE_NAME: admin
+    LOG_DIR: ${LOG_DIR}
+    PLATFORM_ROOT: ${PLATFORM_ROOT}
+    ACCOUNT_ID: ${ACCOUNT_ID}
+    SESSION_ID: ${SESSION_ID}
 ---
 
 # Admin
@@ -94,6 +105,7 @@ Tools are available via the `admin` MCP server.
 - `hooks/pre-tool-use.sh` — enforces admin agent write boundaries
 - `hooks/playwright-file-guard.sh` — rewrites file:// URLs to a backgrounded loopback http.server before Playwright sees them
 - `hooks/webfetch-preflight.mjs` — short-circuits WebFetch on JS-SPA shells with a structured `WEBFETCH_CANNOT_READ_JS_SPA` error so the agent surfaces a loud failure to the owner instead of paying the 60s extraction timeout. Fail-open on any internal error.
+- `hooks/turn-completed-graph-write.sh` — Stop hook fired once per completed admin-agent turn. Gates on `MAXY_SESSION_ROLE=admin` + `MAXY_HIDDEN_SPAWN=0` so it never recurses into the hidden recorder PTY or fires on public sessions. POSTs a hidden `/spawn` against the `database-operator` specialist with the transcript tail as `stdinPayload`; the manager records the row with `hidden: true` so `/list` does not surface it.
 
 ## Failure-report breadcrumbs
 

package/payload/platform/plugins/admin/hooks/__tests__/turn-completed-graph-write.test.sh

@@ -0,0 +1,109 @@
+#!/usr/bin/env bash
+# Regression test for the Stop-hook gate that fires the database-operator
+# per completed admin-agent turn.
+#
+# Behaviour verified:
+#   1. MAXY_SESSION_ROLE!=admin → exit 0, no POST attempt, no log line.
+#   2. MAXY_HIDDEN_SPAWN=1     → exit 0, no POST attempt, no log line.
+#   3. Empty stdin            → exit 0 silently.
+#   4. Missing transcript_path → exit 0 silently.
+#   5. Happy path             → POST attempt + `turn-completed-graph-write
+#      fired conversationId=<8> tail-bytes=<n> ms=<n>` log line.
+#
+# POST is observed by binding the hook's MANAGER_PORT to a tiny netcat
+# listener that records the request body. Each case uses a separate port
+# so concurrent execution does not interfere.
+
+set -u
+
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/turn-completed-graph-write.sh"
+if [[ ! -x "$HOOK" ]]; then
+  echo "FAIL: $HOOK not executable" >&2
+  exit 1
+fi
+
+TMPFILES=()
+cleanup_test_state() {
+  for f in "${TMPFILES[@]:-}"; do
+    [[ -n "$f" ]] && rm -f "$f" 2>/dev/null || true
+  done
+}
+trap cleanup_test_state EXIT
+
+PASS=0
+FAIL=0
+pass() { echo "PASS: $1"; PASS=$((PASS + 1)); }
+fail() { echo "FAIL: $1" >&2; FAIL=$((FAIL + 1)); }
+
+# Helper: run hook with a stdin envelope + env, capture stderr + exit code.
+run_hook() {
+  local role="$1"; local hidden="$2"; local stdin_json="$3"
+  local stderr_file; stderr_file=$(mktemp); TMPFILES+=("$stderr_file")
+  local stdout_file; stdout_file=$(mktemp); TMPFILES+=("$stdout_file")
+  printf '%s' "$stdin_json" | \
+    MAXY_SESSION_ROLE="$role" \
+    MAXY_HIDDEN_SPAWN="$hidden" \
+    CLAUDE_SESSION_MANAGER_PORT="${MANAGER_PORT:-19400}" \
+    bash "$HOOK" >"$stdout_file" 2>"$stderr_file"
+  local rc=$?
+  HOOK_RC="$rc"
+  HOOK_STDERR=$(cat "$stderr_file")
+  HOOK_STDOUT=$(cat "$stdout_file")
+}
+
+# --- Case 1: role != admin → no fire --------------------------------------
+TRANSCRIPT=$(mktemp); TMPFILES+=("$TRANSCRIPT")
+printf '{"type":"user","message":{"content":"hi"}}\n' > "$TRANSCRIPT"
+ENVELOPE=$(python3 -c '
+import json, sys
+print(json.dumps({"session_id": "abcd1234-deadbeef", "transcript_path": sys.argv[1]}))
+' "$TRANSCRIPT")
+
+run_hook "public" "0" "$ENVELOPE"
+if [[ "$HOOK_RC" -ne 0 ]]; then fail "case-1 expected rc=0 got=$HOOK_RC"
+elif [[ -n "$HOOK_STDERR" ]]; then fail "case-1 expected empty stderr, got: $HOOK_STDERR"
+else pass "case-1 role=public → no fire (rc=0, stderr empty)"
+fi
+
+# --- Case 2: hidden=1 → no fire ------------------------------------------
+run_hook "admin" "1" "$ENVELOPE"
+if [[ "$HOOK_RC" -ne 0 ]]; then fail "case-2 expected rc=0 got=$HOOK_RC"
+elif [[ -n "$HOOK_STDERR" ]]; then fail "case-2 expected empty stderr, got: $HOOK_STDERR"
+else pass "case-2 hidden=1 → no fire (rc=0, stderr empty)"
+fi
+
+# --- Case 3: empty stdin → silent --------------------------------------
+run_hook "admin" "0" ""
+if [[ "$HOOK_RC" -ne 0 ]]; then fail "case-3 expected rc=0 got=$HOOK_RC"
+elif [[ -n "$HOOK_STDERR" ]]; then fail "case-3 expected empty stderr, got: $HOOK_STDERR"
+else pass "case-3 empty stdin → silent (rc=0)"
+fi
+
+# --- Case 4: missing transcript_path → silent -------------------------
+BAD_ENVELOPE='{"session_id":"x"}'
+run_hook "admin" "0" "$BAD_ENVELOPE"
+if [[ "$HOOK_RC" -ne 0 ]]; then fail "case-4 expected rc=0 got=$HOOK_RC"
+elif [[ -n "$HOOK_STDERR" ]]; then fail "case-4 expected empty stderr, got: $HOOK_STDERR"
+else pass "case-4 missing transcript_path → silent (rc=0)"
+fi
+
+# --- Case 5: happy path → POST attempt + log line ---------------------
+# Use a deliberately closed port; curl returns non-zero, which is fine —
+# the hook fires fire-and-forget and ignores curl's exit. We assert on
+# the log line and exit code only.
+MANAGER_PORT=1
+run_hook "admin" "0" "$ENVELOPE"
+unset MANAGER_PORT
+if [[ "$HOOK_RC" -ne 0 ]]; then
+  fail "case-5 expected rc=0 got=$HOOK_RC stderr=$HOOK_STDERR"
+elif ! echo "$HOOK_STDERR" | grep -q "^turn-completed-graph-write fired conversationId=abcd1234 tail-bytes="; then
+  fail "case-5 expected fired log line, got: $HOOK_STDERR"
+else
+  pass "case-5 admin foreground → fired log line emitted"
+fi
+
+# --- Summary ------------------------------------------------------------
+echo "---"
+echo "PASSED: $PASS  FAILED: $FAIL"
+[[ "$FAIL" -eq 0 ]] || exit 1
+exit 0

package/payload/platform/plugins/admin/hooks/turn-completed-graph-write.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# Stop hook — fires on every completed admin-agent turn and dispatches one
+# background PTY against `specialists:database-operator` with the just-
+# completed turn payload as stdin. The hidden PTY is the only writer to the
+# Neo4j graph; the admin agent stays focused on the operator's request.
+#
+# Gating:
+#   - MAXY_SESSION_ROLE must equal "admin" (skip public PTYs)
+#   - MAXY_HIDDEN_SPAWN must equal "0" (skip recursive fires from the
+#     hidden database-operator PTY itself; without this gate every
+#     recorder turn would spawn another recorder forever)
+#
+# Input: Claude Code's Stop hook stdin shape
+#   { "session_id": "<intrinsic>", "transcript_path": "<jsonl path>", ... }
+#
+# Output: one log line per fire on the user-facing session's stderr
+#   `turn-completed-graph-write fired conversationId=<8> tail-bytes=<n> ms=<n>`
+#
+# Failure modes are silent (exit 0) — this hook is observability + write
+# orchestration; a failure here must never break the operator's session.
+
+set -uo pipefail
+
+START_MS=$(python3 -c 'import time; print(int(time.time()*1000))')
+
+# Gate 1: only fire on admin foreground PTYs.
+if [ "${MAXY_SESSION_ROLE:-}" != "admin" ]; then
+  exit 0
+fi
+if [ "${MAXY_HIDDEN_SPAWN:-0}" = "1" ]; then
+  exit 0
+fi
+
+# Gate 2: stdin must be a JSON envelope. Fail-open on parse failure.
+if [ -t 0 ]; then
+  exit 0
+fi
+INPUT=$(cat)
+if [ -z "$INPUT" ]; then
+  exit 0
+fi
+
+# Extract session_id and transcript_path via python3 (grep on JSON is
+# fragile when values carry escaped quotes).
+PARSED=$(printf '%s' "$INPUT" | python3 -c '
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    sid = d.get("session_id", "") or ""
+    tpath = d.get("transcript_path", "") or ""
+    print(f"{sid}\t{tpath}")
+except Exception:
+    print("\t")
+' 2>/dev/null)
+SESSION_ID="${PARSED%%	*}"
+TRANSCRIPT_PATH="${PARSED#*	}"
+
+if [ -z "$SESSION_ID" ] || [ -z "$TRANSCRIPT_PATH" ] || [ ! -f "$TRANSCRIPT_PATH" ]; then
+  exit 0
+fi
+
+# Read last 64 KiB of the transcript — enough for one completed turn
+# including a moderate tool transcript, bounded so the POST body never
+# balloons. tail -c is portable across BSD and GNU.
+TAIL_BYTES=$(wc -c < "$TRANSCRIPT_PATH" 2>/dev/null | tr -d ' ')
+TAIL_BYTES="${TAIL_BYTES:-0}"
+TURN_TAIL=$(tail -c 65536 "$TRANSCRIPT_PATH" 2>/dev/null)
+
+# Manager port — environment override or compile-time default. The
+# installer's systemd unit stamps CLAUDE_SESSION_MANAGER_PORT so this
+# resolves to the brand's loopback port at runtime.
+MANAGER_PORT="${CLAUDE_SESSION_MANAGER_PORT:-19400}"
+
+# Build the /spawn body. The recorder gets the raw transcript tail in
+# stdinPayload; the recorder agent parses the JSONL records itself
+# (admin-agent JSONL is more authoritative than any post-hoc summary the
+# hook could synthesise).
+SPAWN_BODY=$(python3 -c '
+import sys, json
+sid = sys.argv[1]
+tail = sys.argv[2]
+body = {
+    "senderId": "turn-recorder",
+    "role": "admin",
+    "channel": "browser",
+    "hidden": True,
+    "specialist": "database-operator",
+    "stdinPayload": json.dumps({
+        "conversationId": sid,
+        "occurredAt": __import__("datetime").datetime.utcnow().isoformat() + "Z",
+        "transcriptTail": tail,
+    }),
+}
+print(json.dumps(body))
+' "$SESSION_ID" "$TURN_TAIL" 2>/dev/null)
+
+if [ -z "$SPAWN_BODY" ]; then
+  exit 0
+fi
+
+# Fire-and-forget POST. The manager returns 200 on URL capture (~2 s);
+# we do not wait for it. curl is preferred (universally present on
+# Linux/macOS) — failure is silent.
+curl -sS -X POST \
+  -H 'Content-Type: application/json' \
+  --max-time 5 \
+  --data "$SPAWN_BODY" \
+  "http://127.0.0.1:${MANAGER_PORT}/spawn" >/dev/null 2>&1 &
+
+END_MS=$(python3 -c 'import time; print(int(time.time()*1000))')
+ELAPSED=$((END_MS - START_MS))
+echo "turn-completed-graph-write fired conversationId=${SESSION_ID:0:8} tail-bytes=${TAIL_BYTES} ms=${ELAPSED}" >&2
+
+exit 0

package/payload/platform/plugins/admin/skills/unzip-attachment/SKILL.md

@@ -2,7 +2,7 @@
 
 Safely extract a zip archive the admin has uploaded, inventory its contents, and propose one concrete follow-up per entry class — refusing archives that attempt path traversal, symlink escape, or decompression-bomb pathologies.
 
-**Invoked from `specialists:content-producer`** when the archive is a static-site zip and the brief carries a host-website / publish-site / put-online intent — the specialist chains directly into `publish-site` on the extracted tree. For graph-bound archives (LinkedIn export, conversation transcripts, PDFs etc.), invocation routes via `specialists:database-operator` instead.
+**Invoked by the admin agent directly.** Admin owns all unzipping: the operator drops a zip, admin runs this skill against the attachment, then forwards the extracted tree to the appropriate downstream specialist — `specialists:content-producer` for static-site zips carrying a host-website / publish-site / put-online intent (it chains into `publish-site` on the extracted tree), and `specialists:librarian` for graph-bound archives (LinkedIn exports, conversation transcripts, loose PDFs, etc.). The skill itself does not dispatch; it extracts safely, inventories the result, and surfaces the post-unzip contents so admin can route.
 
 ## When to Use
 

package/payload/platform/plugins/contacts/PLUGIN.md

@@ -23,6 +23,17 @@ tools:
 always: false
 embed: false
 metadata: {"platform":{}}
+mcp:
+  command: node
+  args:
+    - ${PLATFORM_ROOT}/lib/mcp-spawn-tee/dist/index.js
+    - ${PLATFORM_ROOT}/plugins/contacts/mcp/dist/index.js
+  env:
+    MCP_SPAWN_TEE_NAME: contacts
+    LOG_DIR: ${LOG_DIR}
+    PLATFORM_ROOT: ${PLATFORM_ROOT}
+    ACCOUNT_ID: ${ACCOUNT_ID}
+    SESSION_ID: ${SESSION_ID}
 ---
 
 # Contacts

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

@@ -458,6 +458,16 @@ The SDK's per-tool override is `_meta["anthropic/alwaysLoad"]: true` on each MCP
 
 **Observability.** Spawn-time emit: `[tool-surface] session=<convId> permission_allowed=N eager_intent=E eager_set_size=T`. Turn-end emit: `[admin-agent] turn-end ... toolsearch=N toolsearch_unique=U`. A non-zero `toolsearch` on a fresh turn for an eager-intended tool means a plugin reverted to `server.tool()` — fix at the plugin's MCP registration site, not the allow-list.
 
+## Spawn-time MCP and subagent registration
+
+Each `claude` PTY spawn (admin or public) registers every callable MCP server and every dispatchable subagent before the operator's first turn. The session manager writes a per-spawn `mcp-config.json` to a scratch directory and passes it as `--mcp-config <path>` on the PTY argv. The file contains every plugin's `mcp:` block from its `PLUGIN.md` — `{command, args, env}` — with `${PLATFORM_ROOT}`, `${ACCOUNT_ID}`, `${SESSION_ID}`, and `${LOG_DIR}` expanded at write time. Admin sessions get every plugin; public sessions get only the plugins that expose at least one `publicAllowlist: true` tool. The descriptor's `command` routes through `lib/mcp-spawn-tee/dist/index.js` so each child server's stderr lands in `${LOG_DIR}/mcp-<name>-stderr-<date>.log` even on synchronous module-load throws (Task 743 wrapper).
+
+For subagents, the same spawn pushes `--add-dir` for every bundled plugin agents directory (`platform/plugins/*/agents/`, `premium-plugins/*/agents/`) — both roles — plus the per-account specialists directory `<accountDir>/specialists/agents/` (admin only). Claude Code's `subagent_type` dispatch reads the agent file off disk via the added directories; without `--add-dir` the dispatcher returns "no matching agent."
+
+A boot gate refuses to start the manager when any admin-allowlisted tool `mcp__<plugin>__*` lacks a registered server. The signal is `boot-failed reason=mcp-allowlist-without-server plugin=<p> tool=<t>` followed by `process.exit(1)`. The remediation is a one-line edit to the named `PLUGIN.md`: add the `mcp:` block. The complementary observability emit `mcp-config-allowlist-coverage admin-tools=A admin-registered=R` (where `A === R`) confirms the invariant per boot.
+
+**Per-spawn signals (server.log).** Every spawn emits `pty-spawn-mcp-config servers=<N> tools=<M> bytes=<B> path=<…>` once, plus one `pty-spawn-agents-dir role=<admin|public> path=<…>` per added directory. The diagnostic one-liner is `grep -E 'pty-spawn-mcp-config|pty-spawn-agents-dir|mcp-config-allowlist-coverage|boot-failed reason=mcp-allowlist' ~/.<brand>/logs/server.log | tail -50`.
+
 ## Tool Call Audit Trail
 
 Every tool invocation by the admin agent produces a durable `ToolCall` node in the knowledge graph, linked to the `Conversation` that triggered it. This covers all admin agent tool calls — the full history of what the agent did, when, and in what context.

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

@@ -29,19 +29,22 @@ Everything {{productName}} can do is provided by a plugin. Each plugin is a self
 - Tools (specific actions the agent can take, exposed via MCP servers)
 - Reference documents (detailed knowledge loaded on demand)
 
+**How tools and roles reach the session.** Each `claude` PTY spawn registers every plugin's MCP server and every bundled subagent directory before the operator's first turn — a per-spawn `mcp-config.json` written by the session manager and passed as `--mcp-config` on the PTY argv, plus one `--add-dir` per agents directory. Admin sessions see every plugin and every role; public sessions see only plugins with at least one public-allowlisted tool. The manager refuses to start when a plugin's `PLUGIN.md` declares tools without a matching `mcp:` block (forensic signal: `boot-failed reason=mcp-allowlist-without-server …`). See `internals.md` "Spawn-time MCP and subagent registration" for the full mechanism and `internals.md` "Tool Eagerness" for the separate ToolSearch-vs-eager registration concern.
+
 Plugins are installed and managed through conversation. You can add marketplace plugins (like Stripe) or use {{productName}}'s built-in ones (contacts, memory, Telegram).
 
 ## Roles
 
-{{productName}} has five roles it can dispatch for specific tasks — like members of your team. You don't need to configure or manage them — {{productName}} decides when to use each role and handles everything automatically. You may see activity like "Dispatching personal-assistant..." in the chat timeline when this happens.
+{{productName}} has six roles it can dispatch for specific tasks — like members of your team. You don't need to configure or manage them — {{productName}} decides when to use each role and handles everything automatically. You may see activity like "Dispatching personal-assistant..." in the chat timeline when this happens.
 
 | Role | What it does |
 |------|-------------|
 | Personal Assistant | Scheduling, platform administration, messaging channels, and browser automation |
 | Project Manager | Task and project management — creating, tracking, and completing work items |
 | Research Assistant | Web research, knowledge management, and visual production |
-| Content Producer | Document ingestion, image generation, and PDF output |
-| Database Operator | External-archive imports (LinkedIn today; other CRM sources as each one ships) and ad-hoc graph tidy-ups — prune orphans, merge duplicates, add edges |
+| Content Producer | Image generation, PDF output, and static-site hosting from prepared archives |
+| Librarian | Foreground ingester for the memory graph — owns document ingestion (PDF / text / web), conversation-transcript ingestion (WhatsApp, Telegram, Signal, iMessage, Slack, Zoom, meeting minutes, LinkedIn DMs), LinkedIn Basic Data Exports, and post-unzip trees the admin agent forwards. Returns a structured outcome to admin per ingest. |
+| Database Operator | Background recorder for the memory graph — a Stop hook fires this specialist as a hidden PTY after every completed admin turn, and it writes whatever the turn implied into the graph. The admin agent itself never writes; it asks, listens, and acts on what the recorder has already captured. |
 
 Roles are installed during setup and listed when {{productName}} introduces itself. Some premium plugins add their own specialists (e.g. the writer-craft plugin adds a manuscript reviewer). Roles installed mid-session become active from the next session.
 
@@ -49,6 +52,8 @@ Roles are installed during setup and listed when {{productName}} introduces itse
 
 {{productName}} maintains a graph database (Neo4j) of everything you've told it. People, conversations, preferences, and context are stored as connected nodes. When you ask {{productName}} something, it searches this graph to retrieve relevant context before responding.
 
+**The recording loop.** A background recorder watches every completed admin-agent turn. Once your turn finishes and the reply is on screen, a Stop hook fires the `database-operator` specialist as a hidden Claude Code session with the just-completed turn as input. The recorder decides what's worth keeping and writes through the wrapped graph writers; the admin agent itself does not write to the graph. The recorder runs on a cheap fast model so the recording adds nothing to your perceived latency, and its session never appears in the sidebar or anywhere on the operator UI. To disable it for an account, remove the `Stop` hook entry from that account's `~/.<brand>/.claude/settings.json`; there is no toggle.
+
 The memory graph is stored on your Pi. It never leaves your network.
 
 The graph view (at `/graph`) lets you explore the memory directly. Pick a category from the filter, then type to search inside it — typing makes the canvas narrower, not wider. Drag the slider to control how many matches you see (1 to 2000). If the search shows a yellow banner saying "Vector ranking unavailable," it means the local AI ranking model is offline; results are still returned using keyword match, but ordering is less semantic until the ranker recovers.
@@ -65,7 +70,7 @@ There is no dashboard, no settings panel, no menus. Everything is done through c
 
 The chat input auto-grows as you type — it expands to fit your message and shrinks back when you delete text. You can also drag the resize handle above the input to set a custom height.
 
-The admin interface is a three-pane layout: a sidebar on the left with navigation (Sessions, People, Agents, Projects, Tasks, Artefacts) and your recent conversations; the chat in the middle; and an artefact pane on the right that opens when you select a document, click a project, or open Browser, Data, or Graph from the menu, holding the surface side-by-side with the conversation so the chat stays live while you work in it. At the very top of the sidebar list, a labelled "+ New session" pill spawns a fresh Claude Code session. The Mode picker lives separately as a footer-adjacent strip sitting just above the avatar/name row: it carries a leading "Mode" label and a trigger button to its right showing the current value. Clicking the trigger opens a popover (upward, since the strip is at the foot) whose header reads "Mode" and lists the four permission modes (Ask, Accept edits, Plan, Auto) with the current selection check-marked. The sidebar's nav rows swap the list view in place: Sessions shows recent conversations, Projects shows your active work projects, and Artefacts lists every KnowledgeDocument plus this account's agent templates (your admin agent's IDENTITY, SOUL, and KNOWLEDGE files plus one entry per enabled specialist). Each recent session row carries a small status dot (filled sage for alive, hollow circle for ended) so you can read the live state at a glance without parsing the subtitle. The People, Agents, and Tasks rows are graph shortcuts: clicking each opens the artefact-pane Graph filtered to every Person, every public Agent, or every Task in your account respectively, with no side-list, because the graph itself is the result. Public agents become first-class graph entities the moment you create them, with edges to their IDENTITY/SOUL/KNOWLEDGE files, edges to every knowledge document they have access to, and edges from every conversation they have handled, so a single Agents click reveals the whole shape of who knows what and who has been talking to whom. Click an artefact row to open the document. KnowledgeDocuments and your admin agent's templates are editable: type in the document and changes save automatically; specialist agent templates are read-only because they ship with Maxy and your edits would be overwritten on the next install. PDF artefacts render inline so you can read them without leaving the pane. If your browser doesn't have a built-in PDF viewer, a Download button appears instead. Artefacts that have no readable file backing them (orphan rows, files removed from disk, unsupported content types) show a one-line banner explaining the skip instead of opening to a blank pane. Click a project row to open the Graph view focused on that project's neighbourhood; clicking a second project swaps the focus rather than stacking on top. The chat and artefact divider is drag-resizable: drag the line between the columns to make either side wider; double-click it to reset to half of the available width (viewport minus sidebar), clamped to the chat and artefact min-width floors. Your chosen width is remembered across reloads. On wider screens (>1280px) all three panes are visible. The sidebar narrows at 1280px, the artefact pane hides at 1080px (Browser, Data, and Graph then open as full-window pages instead), and the sidebar collapses to a 56px icon rail at 820px. On every viewport the chat header reads left to right as a triptych: a dedicated sidebar toggle (the panel-right icon, which swaps to panel-right-open when the sidebar is showing), the brand mark next to the title in the centre, and the menu burger on the right. This header toggle is the sole sidebar-toggle button; the sidebar itself no longer carries a duplicate. Tap the sidebar toggle to show or hide the sidebar: on phones (<720px) it slides the drawer in or out, on wider screens it collapses or expands the sidebar column. The brand mark in the centre is decorative; clicks go through the dedicated toggle so the affordance is unambiguous. The drawer animation only fires on tap (220ms slide in or out); resizing your window across the 720px boundary snaps the layout without animation, so you never see a half-open flash. At ≤640px the session metadata pane stacks each label above its value instead of the desktop two-column grid, and the row of action buttons (Open in new tab / Open JSONL / Rename / Pin / Archive / End or Purge) collapses behind a single Actions trigger that opens a popover upward from the foot of the pane. Breakpoint summary: >1280px = full sidebar + chat + artefact pane (drag-resizable divider); 1280px→1080px = sidebar narrows; 1080px→820px = artefact pane hides (Browser/Data/Graph open as full-window pages instead); 820px→720px = sidebar collapses to 56px icon rail; ≤720px = sidebar becomes off-canvas drawer (vertical stack of nav, recents list, foot, the same shape as the desktop sidebar, just on top of the chat instead of beside it).
+The admin interface is a three-pane layout: a sidebar on the left with navigation (Sessions, People, Agents, Projects, Tasks, Artefacts) and your recent conversations; the chat in the middle; and an artefact pane on the right that opens when you select a document, click a project, or open Browser, Data, or Graph from the menu, holding the surface side-by-side with the conversation so the chat stays live while you work in it. Above the SESSIONS group head — outside the scrolling sessions list — a borderless row holds two controls: a "+ New session" button on the left that spawns a fresh Claude Code session, and a Mode trigger on the right showing the current permission mode (Ask, Accept edits, Plan, or Auto). Both controls render as plain text-plus-icon affordances with no surrounding rectangle; hover only tints the background. Clicking the Mode trigger opens a popover downward from the row whose header reads "Mode" and lists the four permission modes with the current selection check-marked. The sidebar's nav rows swap the list view in place: Sessions shows recent conversations, Projects shows your active work projects, and Artefacts lists every KnowledgeDocument plus this account's agent templates (your admin agent's IDENTITY, SOUL, and KNOWLEDGE files plus one entry per enabled specialist). Each recent session row carries a small status dot (filled sage for alive, hollow circle for ended) so you can read the live state at a glance without parsing the subtitle. The People, Agents, and Tasks rows are graph shortcuts: clicking each opens the artefact-pane Graph filtered to every Person, every public Agent, or every Task in your account respectively, with no side-list, because the graph itself is the result. Public agents become first-class graph entities the moment you create them, with edges to their IDENTITY/SOUL/KNOWLEDGE files, edges to every knowledge document they have access to, and edges from every conversation they have handled, so a single Agents click reveals the whole shape of who knows what and who has been talking to whom. Click an artefact row to open the document. KnowledgeDocuments and your admin agent's templates are editable: type in the document and changes save automatically; specialist agent templates are read-only because they ship with Maxy and your edits would be overwritten on the next install. PDF artefacts render inline so you can read them without leaving the pane. If your browser doesn't have a built-in PDF viewer, a Download button appears instead. Artefacts that have no readable file backing them (orphan rows, files removed from disk, unsupported content types) show a one-line banner explaining the skip instead of opening to a blank pane. Click a project row to open the Graph view focused on that project's neighbourhood; clicking a second project swaps the focus rather than stacking on top. The chat and artefact divider is drag-resizable: drag the line between the columns to make either side wider; double-click it to reset to half of the available width (viewport minus sidebar), clamped to the chat and artefact min-width floors. Your chosen width is remembered across reloads. On wider screens (>1280px) all three panes are visible. The sidebar narrows at 1280px, the artefact pane hides at 1080px (Browser, Data, and Graph then open as full-window pages instead), and the sidebar collapses to a 56px icon rail at 820px. On every viewport the chat header reads left to right as a triptych: a dedicated sidebar toggle (the panel-right icon, which swaps to panel-right-open when the sidebar is showing), the brand mark next to the title in the centre, and the menu burger on the right. This header toggle is the sole sidebar-toggle button; the sidebar itself no longer carries a duplicate. Tap the sidebar toggle to show or hide the sidebar: on phones (<720px) it slides the drawer in or out, on wider screens it collapses or expands the sidebar column. The brand mark in the centre is decorative; clicks go through the dedicated toggle so the affordance is unambiguous. The drawer animation only fires on tap (220ms slide in or out); resizing your window across the 720px boundary snaps the layout without animation, so you never see a half-open flash. At ≤640px the session metadata pane stacks each label above its value instead of the desktop two-column grid, and the row of action buttons (Open in new tab / Open JSONL / Rename / Pin / Archive / End or Purge) collapses behind a single Actions trigger that opens a popover upward from the foot of the pane. Breakpoint summary: >1280px = full sidebar + chat + artefact pane (drag-resizable divider); 1280px→1080px = sidebar narrows; 1080px→820px = artefact pane hides (Browser/Data/Graph open as full-window pages instead); 820px→720px = sidebar collapses to 56px icon rail; ≤720px = sidebar becomes off-canvas drawer (vertical stack of nav, recents list, foot, the same shape as the desktop sidebar, just on top of the chat instead of beside it).
 
 Page titles are brand-aware: the browser tab shows your product name (e.g. `Real Agent` instead of `Maxy`) on every shell — chat, graph, and data — so a non-default brand never leaks the default name in tab strips or browser history.
 

package/payload/platform/plugins/email/PLUGIN.md

@@ -23,6 +23,17 @@ tools:
 always: false
 embed: ["admin"]
 metadata: {"platform":{}}
+mcp:
+  command: node
+  args:
+    - ${PLATFORM_ROOT}/lib/mcp-spawn-tee/dist/index.js
+    - ${PLATFORM_ROOT}/plugins/email/mcp/dist/index.js
+  env:
+    MCP_SPAWN_TEE_NAME: email
+    LOG_DIR: ${LOG_DIR}
+    PLATFORM_ROOT: ${PLATFORM_ROOT}
+    ACCOUNT_ID: ${ACCOUNT_ID}
+    SESSION_ID: ${SESSION_ID}
 ---
 
 # Email

package/payload/platform/plugins/linkedin-import/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "linkedin-import",
-  "description": "Import a LinkedIn Basic Data Export into the Maxy Neo4j graph. Skill-only plugin owned by the database-operator specialist. Opt-in per brand — not enabled by default.",
+  "description": "Import a LinkedIn Basic Data Export into the Maxy Neo4j graph. Skill-only plugin owned by the librarian specialist. Opt-in per brand — not enabled by default.",
   "version": "0.1.0",
   "author": {
     "name": "Rubytech LLC"

package/payload/platform/plugins/linkedin-import/PLUGIN.md

@@ -1,20 +1,20 @@
 ---
 name: linkedin-import
-description: "Import a LinkedIn Basic Data Export into the Maxy Neo4j graph. Skill-only plugin owned by the database-operator specialist. Opt-in per brand — not enabled by default."
+description: "Import a LinkedIn Basic Data Export into the Maxy Neo4j graph. Skill-only plugin owned by the librarian specialist. Opt-in per brand — not enabled by default."
 tools: []
 always: false
 embed: false
-specialist: database-operator
+specialist: librarian
 metadata: {"platform":{"optional":true,"pluginKey":"linkedin-import"}}
 ---
 
 # LinkedIn Import
 
-Ingests a LinkedIn Basic Data Export (unzipped directory of CSVs + subdirectories) into the Maxy Neo4j graph. Skill-only plugin — no MCP server, no admin tools added. The skill runs under the `specialists:database-operator` specialist, which owns external-archive ingestion and ad-hoc graph operations.
+Ingests a LinkedIn Basic Data Export (unzipped directory of CSVs + subdirectories) into the Maxy Neo4j graph. Skill-only plugin — no MCP server, no admin tools added. The skill runs under the `specialists:librarian` specialist, which owns foreground archive and document ingestion.
 
 ## When this applies
 
-The admin agent delegates to `specialists:database-operator` when the operator drops a `Basic_LinkedInDataExport_*` directory (or references one by path) into chat. The specialist runs the skill's archive-owner confirmation flow before any CSV is read, then ingests the CSVs the skill has references for.
+The admin agent delegates to `specialists:librarian` when the operator drops a `Basic_LinkedInDataExport_*` directory (or references one by path) into chat. The specialist runs the skill's archive-owner confirmation flow before any CSV is read, then ingests the CSVs the skill has references for.
 
 ## Intra-plugin growth
 
@@ -24,4 +24,4 @@ A LinkedIn export contains ~20 CSVs. The skill ships references for `Profile.csv
 
 - **contacts** — waitlist-shaped CRM surface. LinkedIn-imported `:Person` nodes are visible via `contact-list`, but ingestion does not go through contact tools.
 - **memory** — the underlying Cypher-write surface used by the skill (`memory-write`, `memory-update`). The skill is parameterised so all writes carry `source='linkedin'` + `createdByAgent='linkedin-import'` for provenance.
-- **database-operator specialist** — owns execution. See [admin/IDENTITY.md](../../../platform/templates/agents/admin/IDENTITY.md) delegation clause.
+- **librarian specialist** — owns execution. See [admin/IDENTITY.md](../../../platform/templates/agents/admin/IDENTITY.md) delegation clause.

package/payload/platform/plugins/linkedin-import/skills/linkedin-import/SKILL.md

@@ -5,6 +5,8 @@ description: Import a LinkedIn Basic Data Export into a {{productName}} Neo4j gr
 
 # LinkedIn Import
 
+**Invoked from `specialists:librarian`** when the operator drops a LinkedIn Basic Data Export (`Basic_LinkedInDataExport_*`) directory or references one by path. The admin agent dispatches the librarian; the librarian loads this skill.
+
 **Default parent.** Every `:Person`, `:Organization`, `:Position`, `:Skill`, and `:Message` node this skill writes is anchored to the archive-owner `:Person` (the user whose LinkedIn account produced the export). That Person is itself anchored to the account's `:LocalBusiness`. The archive owner's elementId is the first thing this skill confirms — without it, every row would land as an orphan and the importer refuses to start. Cross-hierarchy edges (`CONNECTED_ON_LINKEDIN`, `WORKS_FOR`, `HAS_SKILL`) describe the relationships; the containment edge from the archive owner is what makes the rows reachable.
 
 Ingests a LinkedIn Basic Data Export (unzipped directory of CSVs + subdirs) into a {{productName}} Neo4j graph. Every edge written corresponds to a real relationship expressed by the data — not a convenience anchor.
@@ -68,7 +70,7 @@ When the owner is an external Person (non-operator archive), the anchor is the c
 4. Invoke the deterministic write tool the reference names. For all archive references this is `mcp__memory__memory-archive-write` with `{archiveType, ownerNodeId, rows}` — the Cypher body is fixed server-side per `archiveType`, so the agent supplies parsed rows, never Cypher. The tool batches rows at 500 per transaction internally.
 5. After each file emit `[linkedin-import] file=<name> rows=<n> created=<n> matched=<n> ms=<elapsed>` using the counters returned by the write tool.
 
-**Doctrine:** raw Cypher and `cypher-shell` invocations are forbidden in this skill and its references. Writes route through `mcp__memory__memory-archive-write` (bulk archives) or `mcp__memory__memory-write` / `mcp__memory__memory-update` (single-node enrichments like `profile.md`). If a CSV needs a write shape no current MCP tool supports, file a task to extend `memory-archive-write` with a new `archiveType` handler — never improvise via Bash. See [database-operator's LOUD-FAIL prerogative](../../../../templates/specialists/agents/database-operator.md#prerogatives).
+**Doctrine:** raw Cypher and `cypher-shell` invocations are forbidden in this skill and its references. Writes route through `mcp__memory__memory-archive-write` (bulk archives) or `mcp__memory__memory-write` / `mcp__memory__memory-update` (single-node enrichments like `profile.md`). If a CSV needs a write shape no current MCP tool supports, file a task to extend `memory-archive-write` with a new `archiveType` handler — never improvise via Bash. See [librarian's LOUD-FAIL prerogative](../../../../templates/specialists/agents/librarian.md#prerogatives).
 
 **LOUD-FAIL on parse errors (structurally enforced).** When LinkedIn parser tools land that follow the `mcp__*__*-import-parse` naming convention, the harness-level `platform/plugins/admin/hooks/archive-ingest-gate.sh` will record an `isError: true` response and block every subsequent tool call this turn until the operator submits the next prompt. The hook also denies edits to `platform/plugins/*/lib/*` and JavaScript test runners (`vitest`, `bun test`, `npm test`, `npx jest`) unconditionally. The skill's "no Bash improvisation" doctrine above is the contract; the hook is the enforcement. See [.docs/hooks.md](../../../../../.docs/hooks.md) for the full gate surface.
 

package/payload/platform/plugins/linkedin-import/skills/linkedin-import/references/connections.md

@@ -110,7 +110,7 @@ Rows missing a position but present with a company produce a `WORKS_FOR` edge wi
 
 ## Post-import verification (operator-side, not agent-side)
 
-After ingest, the operator can verify counts via the `specialists:database-operator` specialist's read tools — `mcp__memory__memory-search` with `labels: ["Person"]` plus a filter, or a direct read query through `mcp__graph__maxy-graph-read_neo4j_cypher`:
+After ingest, the operator can verify counts via the `specialists:librarian` specialist's read tools — `mcp__memory__memory-search` with `labels: ["Person"]` plus a filter, or a direct read query through `mcp__graph__maxy-graph-read_neo4j_cypher`:
 
 ```cypher
 // Owner → connections count
@@ -132,4 +132,4 @@ These are **read queries**, not writes. Cypher writes from the agent are forbidd
 | Tool error "row connectedOn is not ISO 8601" | Parser left `Connected On` in `"23 Apr 2026"` form | Convert to `YYYY-MM-DD` before passing to the tool |
 | Tool error "ownerNodeId not found" | Owner-confirmation flow not run, or operator typed the wrong id | Re-run owner confirmation; pass the resulting `elementId` as `ownerNodeId` |
 | `WORKS_FOR` count « connection count | Many rows have blank company | Expected — LinkedIn doesn't force connections to list a current employer |
-| Tool not present in `init` frame | `specialists:database-operator` spawned without the `mcp__memory__memory-archive-write` token | Loud-fail per database-operator's prerogatives. Do not improvise via Bash. Operator must remediate (re-seed specialist templates) |
+| Tool not present in `init` frame | `specialists:librarian` spawned without the `mcp__memory__memory-archive-write` token | Loud-fail per librarian's prerogatives. Do not improvise via Bash. Operator must remediate (re-seed specialist templates) |

package/payload/platform/plugins/loop/PLUGIN.md

@@ -71,6 +71,17 @@ profileKeys:
   - realagent.voice_samples
 always: false
 metadata: {"platform":{"optional":true,"embed":["admin"]}}
+mcp:
+  command: node
+  args:
+    - ${PLATFORM_ROOT}/lib/mcp-spawn-tee/dist/index.js
+    - ${PREMIUM_PLUGINS_ROOT}/real-agent/plugins/loop/mcp/dist/index.js
+  env:
+    MCP_SPAWN_TEE_NAME: loop
+    LOG_DIR: ${LOG_DIR}
+    PLATFORM_ROOT: ${PLATFORM_ROOT}
+    ACCOUNT_ID: ${ACCOUNT_ID}
+    SESSION_ID: ${SESSION_ID}
 ---
 
 # Real Agent — Loop CRM

package/payload/platform/plugins/memory/PLUGIN.md

@@ -72,6 +72,17 @@ skills:
   - skills/archive-crawler/SKILL.md
 always: true
 embed: false
+mcp:
+  command: node
+  args:
+    - ${PLATFORM_ROOT}/lib/mcp-spawn-tee/dist/index.js
+    - ${PLATFORM_ROOT}/plugins/memory/mcp/dist/index.js
+  env:
+    MCP_SPAWN_TEE_NAME: memory
+    LOG_DIR: ${LOG_DIR}
+    PLATFORM_ROOT: ${PLATFORM_ROOT}
+    ACCOUNT_ID: ${ACCOUNT_ID}
+    SESSION_ID: ${SESSION_ID}
 ---
 
 # Memory

package/payload/platform/plugins/memory/skills/conversation-archive/SKILL.md

@@ -5,6 +5,8 @@ description: Source-agnostic ingest for conversation transcripts. One skill for
 
 # Conversation Archive — source-agnostic transcript ingestion
 
+**Invoked from `specialists:librarian`** — the admin agent dispatches the librarian when the operator drops a conversation transcript; the librarian loads this skill.
+
 **Default parent.** Every `:ConversationArchive` is anchored to the operator-confirmed owner (`:AdminUser` for the account owner, `:Person` for a third-party archive). The owner's elementId is supplied to the bash entry as `--owner-element-id` and becomes the containment parent for the archive node. Per-session `:Section:Conversation` chunks attach to the archive via `:PART_OF`. Participant cross-edges from the archive to each distinct sender (`:Person` / `:AdminUser`) are added alongside the containment edge — they describe the conversation, they do not substitute for the parent.
 
 One skill, one bash entry, one writer. The pipeline is identical for every conversation source. The only source-specific code is the per-source normaliser (a pluggable function under [`platform/plugins/memory/mcp/src/lib/conversation-normalisers/`](../../mcp/src/lib/conversation-normalisers/)). New sources = a new normaliser file + an enum entry, never a new skill.

package/payload/platform/plugins/memory/skills/conversation-archive-enrich/SKILL.md

@@ -5,6 +5,8 @@ description: Source-agnostic Phase 2 for any `:ConversationArchive` — walks th
 
 # Conversation Archive — chunk-anchored insight derivation
 
+**Invoked from `specialists:librarian`** — the admin agent dispatches the librarian when the operator names an existing `:ConversationArchive` and asks for enrichment / derived insights; the librarian loads this skill.
+
 One skill. Walks one `:ConversationArchive`'s chunks in pages. Per chunk, Haiku surfaces high-confidence claims via `mcp__memory__conversation-archive-derive-insights`; per claim, the operator decides `wire / skip / reject`. The tool is read-only; the only writes happen through this skill's per-row dispatch.
 
 ## When to invoke

package/payload/platform/plugins/memory/skills/document-ingest/SKILL.md

@@ -5,6 +5,8 @@ description: Universal document ingestion — maps any unstructured document (PD
 
 # Document Ingest
 
+**Invoked from `specialists:librarian`** — the admin agent dispatches the librarian when the operator hands over a document or chat archive, and the librarian loads this skill. The admin agent never calls this skill directly.
+
 **Default parent.** Every `:KnowledgeDocument` (document mode) and `:ConversationArchive` (chat mode) is anchored to a `:Project` when the dispatch brief names one, or to the account's `:LocalBusiness` when the document is account-scoped rather than project-scoped. The admin agent's brief carries the parent elementId; `memory-ingest` refuses the write if the parent is missing or does not exist. Brief-named entity wiring (Persons, Organizations, Tasks) creates cross-hierarchy edges from the document — never substitutes for the containment parent.
 
 Ingests any unstructured input — documents (PDF, text, transcript, web page) and chat archives (WhatsApp `_chat.txt`) — into the graph. Every classified section becomes one `:Section` node. **Two parent shapes, one pipeline:**
@@ -203,10 +205,10 @@ Each ingest produces up to four chat messages, each at the moment it happens. Fa
 
 | Step | Emitted by | Trigger | Content |
 |---|---|---|---|
-| 1 | Admin agent | On dispatch to database-operator | "Sending `<filename>` to database-operator for ingest." |
-| 2 | Database-operator (this skill) | After `memory-classify` returns ok | "Classified `<filename>` into `<N>` sections, covering: `<topicKeyword1>, <topicKeyword2>, …`." |
-| 3 | Database-operator (this skill) | After `memory-ingest` returns | "Created/connected: `<kind: count via edgeType to anchor>` for each kind; `<orphan-candidates: label and reason>` for any orphans; `<related entities created or merged: kind: count>`." |
-| 4 | Database-operator (this skill) | After `wire-brief-entities` step completes AND the brief named at least one entity | "Wired `<N>` brief entities: `<K>` Persons via `<edge>`, `<M>` Organizations via `<edge>`, `<T>` Tasks via `REFERENCES`. `<P>` entities not found in graph: `<comma-separated names>`." |
+| 1 | Admin agent | On dispatch to librarian | "Sending `<filename>` to librarian for ingest." |
+| 2 | Librarian (this skill) | After `memory-classify` returns ok | "Classified `<filename>` into `<N>` sections, covering: `<topicKeyword1>, <topicKeyword2>, …`." |
+| 3 | Librarian (this skill) | After `memory-ingest` returns | "Created/connected: `<kind: count via edgeType to anchor>` for each kind; `<orphan-candidates: label and reason>` for any orphans; `<related entities created or merged: kind: count>`." |
+| 4 | Librarian (this skill) | After `wire-brief-entities` step completes AND the brief named at least one entity | "Wired `<N>` brief entities: `<K>` Persons via `<edge>`, `<M>` Organizations via `<edge>`, `<T>` Tasks via `REFERENCES`. `<P>` entities not found in graph: `<comma-separated names>`." |
 
 **Step 2 failure form:** "Classifier unavailable — `<reason>`. `<filename>` not ingested. `<remediation>`." Do not call step 3.
 

package/payload/platform/plugins/outlook/PLUGIN.md

@@ -19,6 +19,17 @@ tools:
 always: false
 embed: ["admin"]
 metadata: {"platform":{"optional":true}}
+mcp:
+  command: node
+  args:
+    - ${PLATFORM_ROOT}/lib/mcp-spawn-tee/dist/index.js
+    - ${PLATFORM_ROOT}/plugins/outlook/mcp/dist/index.js
+  env:
+    MCP_SPAWN_TEE_NAME: outlook
+    LOG_DIR: ${LOG_DIR}
+    PLATFORM_ROOT: ${PLATFORM_ROOT}
+    ACCOUNT_ID: ${ACCOUNT_ID}
+    SESSION_ID: ${SESSION_ID}
 ---
 
 # Outlook

package/payload/platform/plugins/replicate/PLUGIN.md

@@ -9,6 +9,17 @@ tools:
   - name: replicate-key-verify
     publicAllowlist: false
 metadata: {"platform":{"optional":true,"recommended":true,"pluginKey":"replicate"}}
+mcp:
+  command: node
+  args:
+    - ${PLATFORM_ROOT}/lib/mcp-spawn-tee/dist/index.js
+    - ${PLATFORM_ROOT}/plugins/replicate/mcp/dist/index.js
+  env:
+    MCP_SPAWN_TEE_NAME: replicate
+    LOG_DIR: ${LOG_DIR}
+    PLATFORM_ROOT: ${PLATFORM_ROOT}
+    ACCOUNT_ID: ${ACCOUNT_ID}
+    SESSION_ID: ${SESSION_ID}
 ---
 
 # Replicate — Image Generation

package/payload/platform/plugins/scheduling/PLUGIN.md

@@ -24,6 +24,17 @@ skills:
 always: false
 embed: false
 metadata: {"platform":{}}
+mcp:
+  command: node
+  args:
+    - ${PLATFORM_ROOT}/lib/mcp-spawn-tee/dist/index.js
+    - ${PLATFORM_ROOT}/plugins/scheduling/mcp/dist/index.js
+  env:
+    MCP_SPAWN_TEE_NAME: scheduling
+    LOG_DIR: ${LOG_DIR}
+    PLATFORM_ROOT: ${PLATFORM_ROOT}
+    ACCOUNT_ID: ${ACCOUNT_ID}
+    SESSION_ID: ${SESSION_ID}
 ---
 
 # Scheduling

package/payload/platform/plugins/tasks/PLUGIN.md

@@ -31,6 +31,17 @@ tools:
   - name: project-complete
     publicAllowlist: false
 metadata: {"platform":{"always":false,"embed":[],"pluginKey":"tasks"}}
+mcp:
+  command: node
+  args:
+    - ${PLATFORM_ROOT}/lib/mcp-spawn-tee/dist/index.js
+    - ${PLATFORM_ROOT}/plugins/tasks/mcp/dist/index.js
+  env:
+    MCP_SPAWN_TEE_NAME: tasks
+    LOG_DIR: ${LOG_DIR}
+    PLATFORM_ROOT: ${PLATFORM_ROOT}
+    ACCOUNT_ID: ${ACCOUNT_ID}
+    SESSION_ID: ${SESSION_ID}
 ---
 
 # Tasks