@rubytech/create-sitedesk-code 0.1.340

package/payload/platform/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "maxy-platform",
+  "private": true,
+  "workspaces": [
+    "plugins/*/mcp",
+    "services/*"
+  ],
+  "scripts": {
+    "build": "tsc -p lib/models/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json && tsc -p services/claude-session-manager/tsconfig.json && tsc -p services/whatsapp-channel/tsconfig.json && tsc -p services/webchat-channel/tsconfig.json && NODE_OPTIONS='--max-old-space-size=8192' tsc -b plugins/*/mcp/tsconfig.json",
+    "build:lib": "tsc -p lib/models/tsconfig.json && tsc -p lib/mcp-stderr-tee/tsconfig.json && tsc -p lib/mcp-spawn-tee/tsconfig.json && tsc -p lib/mcp-lifeline/tsconfig.json && tsc -p lib/mcp-eager/tsconfig.json && tsc -p lib/account-enumeration/tsconfig.json && tsc -p lib/graph-write/tsconfig.json && tsc -p lib/embed-client/tsconfig.json && tsc -p lib/graph-mcp/tsconfig.json && tsc -p lib/graph-trash/tsconfig.json && tsc -p lib/admin-conversation-purge/tsconfig.json && tsc -p lib/graph-search/tsconfig.json && tsc -p lib/graph-style/tsconfig.json && tsc -p lib/device-url/tsconfig.json && tsc -p lib/brand-templating/tsconfig.json && tsc -p lib/entitlement/tsconfig.json && tsc -p lib/task-secrets/tsconfig.json && tsc -p lib/admins-write/tsconfig.json && tsc -p lib/admin-access-password/tsconfig.json && tsc -p lib/persistent-components/tsconfig.json && tsc -p lib/require-port-env/tsconfig.json && tsc -p lib/aeo-llms-txt-writer/tsconfig.json && tsc -p lib/obsidian-parser/tsconfig.json",
+    "gen:canonical-tools": "node scripts/generate-canonical-tool-names.mjs",
+    "build:memory": "tsc -p plugins/memory/mcp/tsconfig.json",
+    "build:contacts": "tsc -p plugins/contacts/mcp/tsconfig.json",
+    "build:telegram": "tsc -p plugins/telegram/mcp/tsconfig.json",
+    "build:admin": "tsc -p plugins/admin/mcp/tsconfig.json",
+    "build:cloudflare": "tsc -p plugins/cloudflare/mcp/tsconfig.json",
+    "build:work": "tsc -p plugins/work/mcp/tsconfig.json",
+    "build:email": "tsc -p plugins/email/mcp/tsconfig.json",
+    "build:outlook": "tsc -p plugins/outlook/mcp/tsconfig.json",
+    "build:workflows": "tsc -p plugins/workflows/mcp/tsconfig.json",
+    "build:stubs": "tsc -p plugins/scheduling/mcp/tsconfig.json",
+    "build:replicate": "tsc -p plugins/replicate/mcp/tsconfig.json",
+    "build:graph-viewer": "tsc -p plugins/graph-viewer/mcp/tsconfig.json",
+    "build:claude-session-manager": "tsc -p services/claude-session-manager/tsconfig.json",
+  "build:whatsapp-channel": "tsc -p services/whatsapp-channel/tsconfig.json",
+    "build:webchat-channel": "tsc -p services/webchat-channel/tsconfig.json"
+  },
+  "overrides": {
+    "zod": "3.x"
+  }
+}

package/payload/platform/plugins/.claude-plugin/marketplace.json

@@ -0,0 +1,163 @@
+{
+  "name": "maxy-platform",
+  "owner": {
+    "name": "Rubytech LLC"
+  },
+  "plugins": [
+    {
+      "name": "admin",
+      "source": "./admin",
+      "version": "0.1.0"
+    },
+    {
+      "name": "aeo",
+      "source": "./aeo",
+      "version": "0.1.0"
+    },
+    {
+      "name": "browser",
+      "source": "./browser",
+      "version": "0.1.0"
+    },
+    {
+      "name": "business-assistant",
+      "source": "./business-assistant",
+      "version": "0.1.0"
+    },
+    {
+      "name": "cloudflare",
+      "source": "./cloudflare",
+      "version": "0.1.0"
+    },
+    {
+      "name": "contacts",
+      "source": "./contacts",
+      "version": "0.1.0"
+    },
+    {
+      "name": "deep-research",
+      "source": "./deep-research",
+      "version": "0.1.0"
+    },
+    {
+      "name": "docs",
+      "source": "./docs",
+      "version": "0.1.0"
+    },
+    {
+      "name": "email",
+      "source": "./email",
+      "version": "0.1.0"
+    },
+    {
+      "name": "graph",
+      "source": "./graph",
+      "version": "0.1.0"
+    },
+    {
+      "name": "graph-viewer",
+      "source": "./graph-viewer",
+      "version": "0.1.0"
+    },
+    {
+      "name": "linkedin-extension",
+      "source": "./linkedin-extension",
+      "version": "0.1.0"
+    },
+    {
+      "name": "linkedin-import",
+      "source": "./linkedin-import",
+      "version": "0.1.0"
+    },
+    {
+      "name": "memory",
+      "source": "./memory",
+      "version": "0.1.0"
+    },
+    {
+      "name": "notion-import",
+      "source": "./notion-import",
+      "version": "0.1.0"
+    },
+    {
+      "name": "obsidian-import",
+      "source": "./obsidian-import",
+      "version": "0.1.0"
+    },
+    {
+      "name": "outlook",
+      "source": "./outlook",
+      "version": "0.1.0"
+    },
+    {
+      "name": "projects",
+      "source": "./projects",
+      "version": "0.1.0"
+    },
+    {
+      "name": "prompt-optimiser",
+      "source": "./prompt-optimiser",
+      "version": "0.1.0"
+    },
+    {
+      "name": "quickbooks",
+      "source": "./quickbooks",
+      "version": "0.1.0"
+    },
+    {
+      "name": "replicate",
+      "source": "./replicate",
+      "version": "0.1.0"
+    },
+    {
+      "name": "sales",
+      "source": "./sales",
+      "version": "0.1.0"
+    },
+    {
+      "name": "scheduling",
+      "source": "./scheduling",
+      "version": "0.1.0"
+    },
+    {
+      "name": "slides",
+      "source": "./slides",
+      "version": "0.1.0"
+    },
+    {
+      "name": "substack-import",
+      "source": "./substack-import",
+      "version": "0.1.0"
+    },
+    {
+      "name": "telegram",
+      "source": "./telegram",
+      "version": "0.1.0"
+    },
+    {
+      "name": "url-get",
+      "source": "./url-get",
+      "version": "0.1.0"
+    },
+    {
+      "name": "whatsapp",
+      "source": "./whatsapp",
+      "version": "0.1.0"
+    },
+    {
+      "name": "work",
+      "source": "./work",
+      "version": "0.1.0"
+    },
+    {
+      "name": "workflows",
+      "source": "./workflows",
+      "version": "0.1.0"
+    },
+    {
+      "name": "x-import",
+      "source": "./x-import",
+      "version": "0.1.0"
+    }
+  ]
+}

package/payload/platform/plugins/admin/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "admin",
+  "description": "Platform administration plugin. Provides system-status, public-hostname (deterministic Cloudflare public-URL resolver, single call returning the operator's canonical hostname so agents never guess property names on :CloudflareHostname nodes), publish-site (move an extracted static-site tree under <accountDir>/sites/<slug>/, emit one canonical path slug, and refresh llms.txt at the site root — typed refusal taxonomy replaces the prior skill-prose contract), brand-settings, account-manage, capabilities-here (deterministic install-introspection — returns enabledPlugins, tier, models, installed platform + premium specialists, registered Claude Code agent types, and the brand block as a single JSON object; the canonical tool for grounding any claim about what is enabled on the current account), account-update, the multi-account managed-service lifecycle tools (account_list, account_create, account_delete, account_purge — one Rubytech operator hosting N client accounts on one house install; create/delete/purge are operator-only and purge is two-step with a typed confirmation), admin-add, admin-remove, admin-list, admin-update-pin, agent-list, agent-config-read, logs-read, plugin-read, skill-load (one-call resolve+read for SKILL.md by skill name, the canonical primitive for loading a named skill; plugin-read remains the reader for references/* and PLUGIN.md), skill-search (free-text intent → skill resolver: ranks every plugin skill's SKILL.md name+description against a query and returns the top owners with their canonical skills/<slug>/ path, so intent→skill mapping survives the available-skills menu leaving context after a compaction), store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), session-reset, session-resume, wifi, and action-approval tools (action-pending, action-approve, action-reject, action-edit) for managing the SiteDesk platform.",
+  "version": "0.1.0",
+  "author": {
+    "name": "Rubytech LLC"
+  },
+  "mcpServers": {
+    "admin": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "${CLAUDE_PLUGIN_ROOT}/lib/mcp-spawn-tee/index.js",
+        "${CLAUDE_PLUGIN_ROOT}/mcp/dist/index.js"
+      ],
+      "env": {
+        "MCP_SPAWN_TEE_NAME": "admin"
+      }
+    }
+  }
+}

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

@@ -0,0 +1,180 @@
+---
+name: admin
+surface: platform
+description: "Platform administration plugin. Provides system-status, public-hostname (deterministic Cloudflare public-URL resolver, single call returning the operator's canonical hostname so agents never guess property names on :CloudflareHostname nodes), publish-site (move an extracted static-site tree under <accountDir>/sites/<slug>/, emit one canonical path slug, and refresh llms.txt at the site root — typed refusal taxonomy replaces the prior skill-prose contract), brand-settings, account-manage, capabilities-here (deterministic install-introspection — returns enabledPlugins, tier, models, installed platform + premium specialists, registered Claude Code agent types, and the brand block as a single JSON object; the canonical tool for grounding any claim about what is enabled on the current account), account-update, the multi-account managed-service lifecycle tools (account_list, account_create, account_delete, account_purge — one Rubytech operator hosting N client accounts on one house install; create/delete/purge are operator-only and purge is two-step with a typed confirmation), admin-add, admin-remove, admin-list, admin-update-pin, agent-list, agent-config-read, logs-read, plugin-read, skill-load (one-call resolve+read for SKILL.md by skill name, the canonical primitive for loading a named skill; plugin-read remains the reader for references/* and PLUGIN.md), skill-search (free-text intent → skill resolver: ranks every plugin skill's SKILL.md name+description against a query and returns the top owners with their canonical skills/<slug>/ path, so intent→skill mapping survives the available-skills menu leaving context after a compaction), store-skill (deterministic write counterpart to plugin-read; persists operator-authored skills as plugin files under the active account), session-reset, session-resume, wifi, and action-approval tools (action-pending, action-approve, action-reject, action-edit) for managing the SiteDesk platform."
+tools:
+  - name: system-status
+    publicAllowlist: false
+    adminAllowlist: false
+  - name: public-hostname
+    publicAllowlist: false
+    adminAllowlist: false
+  - name: publish-site
+    publicAllowlist: false
+    adminAllowlist: false
+  - name: brand-settings
+    publicAllowlist: false
+    adminAllowlist: false
+  - name: account-manage
+    publicAllowlist: false
+    adminAllowlist: false
+  - name: capabilities-here
+    publicAllowlist: false
+    adminAllowlist: false
+  - name: account-update
+    publicAllowlist: false
+    adminAllowlist: false
+  - name: account_list
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: account_create
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: account_delete
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: account_purge
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: admin-add
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: admin-remove
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: admin-list
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: admin-update-pin
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: agent-list
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: agent-config-read
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: logs-read
+    publicAllowlist: false
+    adminAllowlist: false
+  - name: plugin-read
+    publicAllowlist: false
+    adminAllowlist: false
+  - name: skill-load
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: skill-search
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: store-skill
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: session-reset
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: session-resume
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: action-pending
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: action-approve
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: action-reject
+    publicAllowlist: false
+    adminAllowlist: true
+  - name: action-edit
+    publicAllowlist: false
+    adminAllowlist: true
+hidden:
+  - remote-auth-status
+  - remote-auth-set-password
+  - remote-auth-revoke-password
+  - qr-generate
+  - 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}
+    PLATFORM_PORT: ${PLATFORM_PORT}
+    MAXY_BRAND_PORT: ${MAXY_BRAND_PORT}
+mcp-manifest: auto
+---
+
+# Admin
+
+Platform management tools for both the admin and public agents. The `plugin-read` tool is available to the public agent (read-only) for loading plugin definitions and references. `skill-load skillName=<name>` is the canonical resolver+reader for SKILL.md by skill name — one call returns the body with brand placeholders substituted; `plugin-read` retains exclusive ownership of `references/*` and `PLUGIN.md` reads (both inherently plugin-scoped). All other tools are admin-only.
+
+Tools are available via the `admin` MCP server.
+
+**Intent → skill resolution.** `skill-search query="<free text>"` is the description-driven resolver: it walks every plugin's `skills/<slug>/SKILL.md`, reads frontmatter `name`+`description` only, and returns the top owners ranked by a frequency-aware match (distinctive terms dominate; common trigger words contribute little) with each owner's canonical `skills/<slug>/SKILL.md` path. It exists because the session's available-skills menu — the only other description-driven surface — is injected at session start and resume but **not** after a context compaction; once it leaves context, intent-phrased guesses miss `skill-find` (which is exact-slug only) and the agent falls back to blind `find`/`grep`. `skill-search` makes the mapping a single deterministic call regardless of whether the menu is present; feed the returned slug straight to `skill-load`. `skill-find` and `skill-load` stay exact-slug — they resolve a slug you already know — and are unchanged.
+
+**Admin-seat authoring-skill gate.** `skill-load` and `plugin-read` refuse to return the body of a content-producer-owned authoring skill — `professional-document`, `a4-print-documents`, `publish-site` — when the caller is the admin seat (`MAXY_SESSION_ROLE=admin` with no `MAXY_SPECIALIST`). The refusal relays one line — "This deliverable is owned by content-producer. Dispatch it with the Agent tool and subagent_type content-producer." — so the admin's next action is the dispatch, not inline authoring. `plugin-read` extracts the skill slug from a `skills/<slug>/…` file path (or a slug buried in `pluginName`), so the raw-SKILL.md read path can't bypass the gate; `PLUGIN.md` and plain `references/*` reads are untouched. content-producer's own spawns carry `MAXY_SPECIALIST=content-producer` and resolve these skills normally (it reaches them via the native `Skill` tool regardless), and the public seat is out of scope. The gate is a pure name+env check before any filesystem read and fails open for any non-admin or unidentified seat — it never bricks a legitimate load. Each block emits `[admin-skill-gate] role=admin skill=<name> decision=block reason=content-producer-owned`. This is the enforcement layer; the IDENTITY.md delegation paragraph documents the intent but is not the gate ([[feedback_deterministic_means_remove_llm]], [[feedback_doctrine_paragraph_is_not_a_gate]]). Skills the admin invokes directly are deliberately excluded: `unzip-attachment` (its SKILL.md says "Invoked by the admin agent directly — admin owns all unzipping", then routes the extracted tree to a specialist) and `deck-pages` (admin-owned, a content-producer refusal target). The set is each skill's own SKILL.md "Invoked by" declaration, not the admin plugin's skill catalogue (which lists these admin-hosted skills for discovery — the catalogue is the inline path this gate closes).
+
+**Three-store admin auth invariant.** `admin-add` writes to all three identity stores (`users.json` PIN auth at the persistent `~/{configDir}/users.json` location , `account.json` `admins[]` role, Neo4j `:AdminUser`/`:Person` graph identity) with per-leg `[admin-auth-store]` log lines plus the `[admins-write]` chokepoint line, and returns `is_error: true` on any leg failure naming what's already written. `admin-update-pin` writes `users.json` only and emits the same `[admin-auth-store]` line. **Single chokepoint:** every `users.json` + `account.json admins[]` mutation routes through `platform/lib/admins-write` (`writeAdminEntry` for admin-add/set-pin, `removeAdminFromAccount` for admin-remove); the static check `grep -rnE 'admins\.push\|config\.admins\s*=' platform/ \| grep -v lib/admins-write` returns 0. Direct `Edit`/`Write` on `account.json` is forbidden by IDENTITY.md doctrine — mutations go through `account-update`, `plugin-toggle-enabled`, or the `admin-*` tools. **Install + boot invariants:** the installer and admin-server boot walk every account.json admins[] vs users.json; `[install-invariant]` / `[admin-invariant] direction=… userId=<id8> source=<file>` fires per divergence with a `check complete divergences=<n>` summary. Log-only — does not block. See `.docs/agents.md` § "Three-store admin auth invariant" for the full contract.
+
+**AdminUser graph stamp + boot self-heal.** The seed cypher in `platform/scripts/seed-neo4j.sh` stamps `:AdminUser.accountId` + `:AdminUser.role='owner'` ON CREATE so the graph-write gate's account-scoped MATCH succeeds on the first user-domain write. Admin-server boot additionally runs `platform/ui/app/lib/adminuser-self-heal.ts` to repair legacy nodes whose `accountId` or `role` is null — emits `[adminuser-self-heal] healed=<N> userId=<8> accountId=<8>` once per boot, idempotent. The `graph-write-gate` reject log gains a `subReason=` field (`no-admin-user-node` / `admin-user-no-accountid` / `no-business-or-personal-profile`) for operator diagnosis. See `.docs/agents.md` § "AdminUser graph stamp contract" for the full contract.
+
+`logs-read { type: "agent-stream" }` is the canonical name for the per-conversation tool-use/tool-result archive previously called `system`; both names work and the legacy alias is preserved.
+
+**Stream log is the primary diagnostic surface for an in-progress session.** Every stream log is named by sessionKey and the stream-log file exists from the first token. The single-writer mandate (2026-05-14) mechanically enforces this contract: the single writer module at [`platform/ui/app/lib/claude-agent/stream-log-writer.ts`](../../ui/app/lib/claude-agent/stream-log-writer.ts) owns every open of `claude-agent-stream-*.log`, opens the file lazily on the first SDK token byte (via `streamLog.writeToken`), and buffers pre-token markers in memory while duplicating them to `server.log` via `console.error` so zero-token sessions retain observability. The build gate `platform/ui/scripts/check-stream-log-writer.mjs` rejects any external `appendFileSync`/`createWriteStream` against the `claude-agent-stream-*` pattern outside the writer module, plus any `claude-agent-stream-${sessionId}` literal (the pre-1013 wrong-identifier signature that produced two files for one session on the Beacons Pi 2026-05-14). The first-token invariant is bound by `platform/scripts/__tests__/first-token-creates-stream-log.test.sh`: one operator turn, one token, `claude-agent-stream-<sessionKey>.log` exists and contains the token bytes after the byte returns to the operator. The parent-process console fan-out tee in [`platform/ui/app/lib/claude-agent/logging.ts`](../../ui/app/lib/claude-agent/logging.ts) appends every `[<tag>]`-prefixed `console.error` / `console.log` line to every active session's stream log alongside `server.log`. For diagnosing an in-session issue (WhatsApp inbound, Cloudflare action, persist write, baileys error), call `logs-read { sessionKey: "<…>" }` first — the stream log carries both the agent lifecycle AND the parent-process events that occurred during the session window. The `sessionId` parameter remains a legacy alias resolving to the same sessionKey-named file. `logs-read { type: "server" }` is the cross-session escape hatch for events outside any single session window.
+
+## Skills
+
+| Task | When to use | Reference |
+|------|-------------|-----------|
+| Manage public agents | User asks to create, edit, clone, list, preview, or delete a public agent | `skills/public-agent-manager/SKILL.md` |
+| Create a new skill | User asks to create, add, or teach the agent a new capability | `skills/skill-builder/SKILL.md` |
+| Review stream logs | Admin asks to review, diagnose, or analyse a Claude agent stream log | `skills/stream-log-review/SKILL.md` |
+| Set up business profile | Admin asks to set up, complete, or update business operational data | `skills/business-profile/SKILL.md` |
+| Generate a QR code | User asks to generate, create, or make a QR code from a URL, Wi-Fi details, contact, or text | `skills/qr-code/SKILL.md` |
+| Timezone queries | User asks for the time in another city, timezone conversion, UTC offset, or DST status | `skills/datetime/SKILL.md` |
+| Manage access grants | Admin asks to invite visitors, revoke or extend access, list who has access, or set an agent's access mode | `skills/access-manager/SKILL.md` |
+| Manage plugins and settings | User asks to install, enable, disable, or configure plugins, or change account settings | `skills/plugin-management/SKILL.md` |
+| Manage specialists | User asks to install or remove a specialist subagent, or activate/deactivate premium plugin agents | `skills/specialist-management/SKILL.md` |
+| Generate print-quality PDF | User asks to create a PDF document, one-pager, brochure, or any HTML intended for print/download | `skills/a4-print-documents/SKILL.md` |
+| Compose a business document | User asks to write or draft a proposal, report (market / analysis / strategic), brief, memo, white paper, plan (non-fundraise), or case study | `skills/professional-document/SKILL.md` |
+| Manage admin users | User asks to add, remove, or list admins on this account, or change an admin PIN | `skills/admin-user-management/SKILL.md` |
+| Session reset / continue / resume | User asks to clear the session, start fresh, continue the last session, or pick up where they left off | `skills/session-management/SKILL.md` |
+| Show or download a file | User asks to view, attach, or download a file or document, or the current turn produces a document the owner needs to review | `skills/file-presentation/SKILL.md` |
+| Upgrade SiteDesk | User asks to upgrade, update, install the latest version, or accepts an upgrade offer | `skills/upgrade/SKILL.md` |
+| Run a structured sprint without `gstack` | User asks to run a sprint, execute a `.tasks/NNN-*.md`, or invokes "superpowers sprint" / "sprint without gstack" | `skills/superpowers-sprint/SKILL.md` |
+| Investigate a bug or unexpected behaviour | User asks to debug, fix a bug, find the root cause, or investigate an error | `skills/investigate/SKILL.md` |
+| Capture work as a task before implementing | User asks to "task it", create a task, or describes work that should be a task file before a sprint | `skills/task/SKILL.md` |
+| Run an insight pass on this session | Operator asks to run an insight pass, review this session, capture what we learned, or do a retrospective on the conversation | `skills/insight/SKILL.md` |
+
+## Hooks
+
+- `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/askuserquestion-investigate-gate.sh` — PreToolUse matcher=`AskUserQuestion`. Blocks the question (exit 2) when no read-only investigation tool has fired since the latest real user turn in the session JSONL. The structural fix for the failure class where the agent fabricates a menu before evidence-gathering (session `c085ec2c-46fb-4b73-8865-68cf85866ea8` 2026-05-22 — "change remote access password" → invented options "Admin PIN / Cloudflare tunnel / WiFi password" with zero prior tool_use; post-correction the agent immediately fired `remote-auth-status` → `ToolSearch` → `remote-auth-set-password`, proving it knew the moves). **Allowlist** (exact, with trailing `__<tool>` suffix-match for namespaced `mcp__plugin_<plugin>_<server>__<tool>` aliases): `ToolSearch`, `Grep`, `Glob`, `Read`, `LS`, `NotebookRead`, `Bash`, `WebFetch`, `WebSearch`, plus the read-only admin / memory MCP tools (`*-status`, `*-list`, `*-read`, `skill-find`, `memory-find-candidates`, `profile-read`, `conversation-list`, `memory-list-attachments`, `memory-read-attachment`). **Block message:** `Blocked: AskUserQuestion requires at least one investigation tool (ToolSearch, Grep, Read, *-list, *-status, *-read, skill-find, ...) earlier in this turn. Search the operator's literal phrase first.` **Log line** (stderr, one per call): `[ask-gate] decision=<allow|block> sessionId=<id8> seen=<csv|-> reason=<allowlist-hit|no-investigation|fail-open-no-transcript|fail-open-parse-error>`. **Fail-open** on missing transcript or parse error — nudges, never bricks the UI.
+- `hooks/mcp-tool-missing.sh` — **PostToolUse hook on `mcp__.*` (directive 3).** Defence-in-depth for the `No such tool available: mcp__…` failure class that the name-binding is built to eliminate. Fires on any MCP tool call; no-op unless the `tool_response` carries `No such tool available` AND the qualified name resolves to a maxy plugin (read from the generated `hooks/lib/maxy-mcp-plugins.txt`). On a maxy match it logs one deterministic `[mcp-tool-missing] server=<server> tool=<tool>` line and exits 2 with a fixed envelope on stderr, so the agent relays a named server-unavailable failure instead of narrating "warming up" or blind-retrying. A missing non-maxy bridge tool (Playwright etc., upstream-owned) passes through (exit 0). The maxy-plugin list is regenerated and gate-diffed by `platform/scripts/check-canonical-tool-names.mjs`.
+- `hooks/post-tool-use-agent.sh` — **PostToolUse hook on `Agent`.** Drains any subagent hook-decision buffers under `~/.maxy-code/logs/hook-decisions/` modified since this parent's previous PostToolUse-Agent fire (cursor file keyed by parent session id), prints one `[hook-propagate]` line per record to stdout — Claude Code attaches the stdout as a `hook_success` attachment on the parent JSONL, making the records grep-queryable from the parent session alone. Rotates consumed buffers to `consumed/`. Emits one `[hook-propagate-census] parentSession=<…> subagentHooksObserved=<N> attachmentsEmitted=<M>` line per fire to stdout and server.log; `N != M` is the propagation regression signal. The companion emitter library `hooks/lib/hook-emit.sh` is sourced by `post-tool-use-agent.sh` and any other hook that records a block decision (4 KB stderr truncation, `truncated=true` set on the record).
+- `hooks/admin-authoring-observer.sh` — **PostToolUse hook on Write and Edit.** Observation only — never blocks; exits 0 on every path. Fires when the admin agent (not a specialist subagent — gated by `MAXY_SPECIALIST` env) writes or edits a file under `<accountDir>/output/`. Walks the session transcript from the latest real-user turn forward to detect any prior `Task` `tool_use` whose `subagent_type` starts with `specialists:`. Emits one stderr line `[admin-authoring] inline-write path=<rel> priorSpecialistSpawnInTurn=<true|false|unknown>`. A `false` value on a long-form prose file is the regression signal this hook was designed to make visible — the BioSymm proposal session (admin authored a customer-facing proposal inline despite content-producer being installed) is the failure mode this surfaces mechanically. Mechanical enforcement (refuse the write, force a re-spawn) is deferred per the task spec.
+- `hooks/prompt-optimiser-directive.sh` — **UserPromptSubmit hook.** Injects the standing prompt-optimiser restatement directive plus the per-turn three-tier routing ladder as `additionalContext`: **(1)** delegate to the specialist that owns the deliverable via the Agent tool — the brief states the outcome plus binding constraints, never lines/anchors/literal text; **(2)** only if none fits, load an admin-usable skill with `skill-load`; **(3)** only if neither fits, author inline — freestyle is the named last resort. Re-emits the full agent roster (`agents/admin/AGENTS.md`) and the full admin-usable skills list (`agents/admin/ADMIN-SKILLS.md`) every turn by reading the two generated files from the account dir (the hook fires with the account dir as cwd); it never walks the plugins tree per turn. Fail-open is **visible**: a missing list logs `[prompt-optimiser] missing=<AGENTS.md\|ADMIN-SKILLS.md> emitting-partial` to stderr and the ladder still injects. The trivial-turn skip (one-word confirmation, slash-command, direct continuation) is unchanged. **Staleness:** `ADMIN-SKILLS.md` is regenerated only by `setup-account.sh`; a plugin add/remove since the last setup leaves the list stale — compare `ADMIN-SKILLS.md` mtime against the newest `SKILL.md` mtime and re-run setup to refresh. The list generator is `platform/scripts/lib/admin-skills-bootstrap.sh`; it logs `[admin-skills] scanned=<N> admin-usable=<M> no-declaration=<K>` (failure signature: `admin-usable=0` while `scanned>0`, or any `missing-declaration` line). The directive also carries a standing CAPABILITY-QUESTIONS-ARE-OWNED-WORK clause (how-to / "do you have instructions for X" / config questions about platform features are answered from the owning specialist or plugin tool/reference, never from training memory), and the hook appends a durable `<ts> [prompt-optimiser-directive] injected len=<n> session=<id>` breadcrumb to `$LOG_DIR/prompt-optimiser-directive.log` so per-turn injection is greppable, not stderr-only. The directive is also **suppressed on native channel turns** — when the parsed `.prompt` starts with the `<channel source=` event marker, the hook logs `[prompt-optimiser-directive] skipped reason=channel-turn session=<id>` to stderr and exits without injecting, because the channel service already reframes the inbound into a select-and-dispatch turn (`composeAdminContent`, see `.docs/whatsapp-inbound-lifeline.md`). Marker-matched at start-of-prompt only, so an admin/Terminal prompt that merely mentions "channel" still gets the directive; fail-open injects if the prompt cannot be parsed.
+- `hooks/prompt-optimiser-compliance.sh` — **Stop hook.** After each admin turn, reads the just-finished turn from `transcript_path` and appends `<ts> [prompt-optimiser-compliance] directive-fired no-route-taken session=<id8> prompt="<clip>"` to `$LOG_DIR/prompt-optimiser-directive.log` (and stderr) when the routing directive fired, the prompt was non-trivial (not a slash-command, not a one-word confirmation), and the turn took **no route** — no `Agent` dispatch, no `Skill` load, no `ToolSearch`, no `mcp__*` tool call. This is the standing compliance signal that surfaces the session-`da0b12d4` failure class (agent answers a capability question from memory) as a visible event instead of a silent stale answer. Directive-fired is detected by the marker `PROMPT-OPTIMISER DIRECTIVE` in the turn slice, so it is robust to the CC-version difference in how `UserPromptSubmit` `additionalContext` is recorded (`attachment`/`hook_success` vs `hook_additional_context`). **Known limitation:** "direct continuation of the prior turn" is not detectable from the transcript, so a continuation turn that legitimately needs no route can be flagged; treat the log as a review signal, not a gate. **Fail-open:** no python3, no `transcript_path`, or an unreadable transcript → exit 0, no output. Lives in the same log as the directive breadcrumb, so a single `grep` interleaves "fired" and "no-route" into one per-session timeline; cross-check via `platform/scripts/logs-read.sh <sessionKey>`. This is a lightweight transcript read, not a per-turn spawn (contrast the turn recorder below).
+- **Turn recorder — removed entirely.** The `turn-completed-graph-write.sh` Stop hook, the `/api/admin/claude-sessions` loopback bypass it relied on, the `[turn-recorder]` emitters, the envelope walker, and the recorder-auto-archive subscriber are deleted. It had been dormant for a long time (never re-registered in settings.json); the admin now writes to the graph by delegating to `database-operator` via the Task tool inside the live session, and the on-demand `/insight` pass (`skills/insight/SKILL.md`, a registered admin skill) is the per-session review. There is no per-turn spawn.
+
+## Session identifiers
+
+The metadata pane and admin logs use these three identifier names, matching what Claude Code surfaces:
+
+| Operator label | What it is | Manager wire field | Log key |
+|---|---|---|---|
+| `sessionId` | Claude's session — one identity with two phases the manager resolver maps to the same row: bridge suffix (`session_xxx` from `claude.ai/code/<session_xxx>`) and JSONL basename UUID on disk. The manager emits whichever phase is current (bridge preferred). | `sessionId` (collapsed from the earlier three-field surface) | `sessionId=` |
+| `accountId` | Account / workspace UUID. | `senderId` (channel-agnostic — same wire field carries phone/email/chat-id on non-admin channels, so its log key stays `senderId=` outside admin flow) | `accountId=` (admin flow) |
+
+Full contract lives in [admin-session.md § Session identifiers](../docs/references/admin-session.md).
+
+## SSE telemetry breadcrumbs
+
+`POST /api/admin/sse-telemetry` writes `[sse-client]` lines to `claude-agent-stream-<sessionKey>.log` so one grep against that file reconstructs a failing turn. The admin agent reads these via `logs-read`.

package/payload/platform/plugins/admin/hooks/__tests__/archive-ingest-surface-gate.test.sh

@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+# Regression test for archive-ingest-surface-gate.sh.
+#
+# Covers:
+#   Preserved-from-Task-846:
+#     1. Edit on /platform/plugins/<x>/lib/* → BLOCKED
+#     2. Edit on benign path → ALLOWED
+#     3. Bash with `npx vitest`/`bun test`/`npm test` → BLOCKED
+#     4. PostToolUse on whatsapp-export-parse with isError:true sets flag
+#     5. Subsequent PreToolUse on ANY tool → BLOCKED
+#     6. UserPromptSubmit clears flag → normal allow resumes
+#     7. PostToolUse with isError:false → flag absent
+#     8. Stale flag (>600s) auto-clears
+#   New:
+#     A. PreToolUse mcp__memory__whatsapp-export-parse → BLOCKED
+#     B. PreToolUse mcp__memory__whatsapp-export-insight-write → BLOCKED
+#     C. PreToolUse mcp__memory__memory-archive-write w/ archiveType=whatsapp-export → BLOCKED
+#     D. PreToolUse mcp__memory__memory-archive-write w/ archiveType=linkedin-connections → ALLOWED
+#     E. PreToolUse Bash invoking conversation-archive-ingest.sh → ALLOWED
+#     F. Default-allow emits a [archive-ingest-gate] decision=allow log line
+
+set -u
+
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/archive-ingest-surface-gate.sh"
+if [[ ! -x "$HOOK" ]]; then
+  echo "FAIL: $HOOK not executable" >&2
+  exit 1
+fi
+
+STATE_DIR=$(mktemp -d)
+export ARCHIVE_INGEST_GATE_STATE_DIR="$STATE_DIR"
+FLAG_FILE="$STATE_DIR/archive-ingest-parse-error.flag"
+
+cleanup() { rm -rf "$STATE_DIR"; }
+trap cleanup EXIT
+
+PASS=0
+FAIL=0
+
+run_case() {
+  local name="$1" stdin="$2" expected_exit="$3"
+  local actual_exit
+  printf '%s' "$stdin" | bash "$HOOK" >/dev/null 2>/dev/null
+  actual_exit=$?
+  if [[ "$actual_exit" -eq "$expected_exit" ]]; then
+    echo "PASS: $name (exit=$actual_exit)"
+    PASS=$((PASS + 1))
+  else
+    echo "FAIL: $name (expected exit=$expected_exit, got=$actual_exit)" >&2
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+# Preserved cases ---------------------------------------------------------
+
+run_case "Edit on platform/plugins/memory/mcp/src/lib/conversation-normalisers/whatsapp-text.ts → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Edit","tool_input":{"file_path":"/Users/x/repo/platform/plugins/memory/mcp/src/lib/conversation-normalisers/whatsapp-text.ts","old_string":"a","new_string":"b"}}' \
+  2
+
+run_case "Edit on README.md → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Edit","tool_input":{"file_path":"/Users/x/repo/README.md","old_string":"a","new_string":"b"}}' \
+  0
+
+run_case "Bash 'npx vitest run' → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"npx vitest run parse-export.test.ts"}}' \
+  2
+
+run_case "Bash 'ls -la' → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"ls -la"}}' \
+  0
+
+run_case "Bash 'bun test' → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"bun test"}}' \
+  2
+
+run_case "Bash 'npm test' → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"npm test"}}' \
+  2
+
+# New cases ----------------------------------------------------
+
+run_case "PreToolUse mcp__memory__whatsapp-export-parse → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"mcp__memory__whatsapp-export-parse","tool_input":{"filePath":"/tmp/_chat.txt","accountId":"acct1","timezone":"Europe/London"}}' \
+  2
+
+run_case "PreToolUse mcp__memory__whatsapp-export-insight-write → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"mcp__memory__whatsapp-export-insight-write","tool_input":{"kind":"MENTIONS","name":"Joel"}}' \
+  2
+
+run_case "PreToolUse memory-archive-write w/ archiveType=whatsapp-export → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"mcp__memory__memory-archive-write","tool_input":{"archiveType":"whatsapp-export","ownerNodeId":"x","accountId":"a","rows":[]}}' \
+  2
+
+run_case "PreToolUse memory-archive-write w/ archiveType=linkedin-connections → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"mcp__memory__memory-archive-write","tool_input":{"archiveType":"linkedin-connections","ownerNodeId":"x","accountId":"a","rows":[]}}' \
+  0
+
+# Bypass attempts (code-review C1): nested archiveType in rows[0]
+# or conversation must NOT defeat the block. The gate must read the
+# top-level tool_input.archiveType, not the first textual occurrence.
+run_case "BYPASS: nested rows[0].archiveType=linkedin + top-level archiveType=whatsapp-export → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"mcp__memory__memory-archive-write","tool_input":{"rows":[{"archiveType":"linkedin-connections"}],"archiveType":"whatsapp-export","ownerNodeId":"x","accountId":"a"}}' \
+  2
+
+run_case "BYPASS: conversation.archiveType=linkedin + top-level archiveType=whatsapp-export → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"mcp__memory__memory-archive-write","tool_input":{"conversation":{"archiveType":"linkedin-connections","sessionId":"x"},"archiveType":"whatsapp-export","ownerNodeId":"x","accountId":"a","rows":[]}}' \
+  2
+
+# Plugin-source-edit path block must read tool_input.file_path top-level,
+# not a nested file_path in old_string/new_string.
+run_case "BYPASS: nested file_path in old_string + top-level file_path in lib/* → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Edit","tool_input":{"file_path":"/repo/platform/plugins/memory/mcp/src/lib/conversation-normalisers/whatsapp-text.ts","old_string":"file_path:/safe/path","new_string":"x"}}' \
+  2
+
+run_case "PreToolUse Bash invoking conversation-archive-ingest.sh → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"bash platform/plugins/memory/bin/conversation-archive-ingest.sh /tmp/chat.zip --source whatsapp --owner-element-id 4:abc:1 --participant-person-ids 4:abc:2 --scope admin"}}' \
+  0
+
+# Default-allow log-line check
+LOG=$(printf '%s' '{"hook_event_name":"PreToolUse","tool_name":"Read","tool_input":{"file_path":"/tmp/foo"}}' | bash "$HOOK" 2>&1 1>/dev/null)
+if printf '%s' "$LOG" | grep -q '\[archive-ingest-gate\] decision=allow tool=Read reason=default'; then
+  echo "PASS: default-allow emits decision-log line"
+  PASS=$((PASS + 1))
+else
+  echo "FAIL: default-allow missing decision-log line. Got: $LOG" >&2
+  FAIL=$((FAIL + 1))
+fi
+
+# Block-log line includes command field for Bash
+LOG=$(printf '%s' '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"npx vitest run"}}' | bash "$HOOK" 2>&1 1>/dev/null)
+if printf '%s' "$LOG" | grep -q '\[archive-ingest-gate\] decision=block tool=Bash reason=test-runner'; then
+  echo "PASS: block emits decision-log line with reason"
+  PASS=$((PASS + 1))
+else
+  echo "FAIL: block missing decision-log line. Got: $LOG" >&2
+  FAIL=$((FAIL + 1))
+fi
+
+# Parse-error flag lifecycle (preserved)
+rm -f "$FLAG_FILE"
+run_case "PostToolUse parse-error sets flag (exit 0)" \
+  '{"hook_event_name":"PostToolUse","tool_name":"mcp__memory__whatsapp-export-parse","tool_input":{"filePath":"_chat.txt"},"tool_response":{"isError":true,"content":[{"type":"text","text":"parse-error file=_chat.txt line=1 reason=not-a-_chat.txt"}]}}' \
+  0
+[[ -f "$FLAG_FILE" ]] && { echo "PASS: parse-error flag created"; PASS=$((PASS+1)); } \
+                      || { echo "FAIL: parse-error flag NOT created" >&2; FAIL=$((FAIL+1)); }
+
+run_case "PreToolUse Read after parse-error → BLOCKED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Read","tool_input":{"file_path":"/tmp/foo"}}' \
+  2
+
+run_case "UserPromptSubmit clears flag" \
+  '{"hook_event_name":"UserPromptSubmit","prompt":"retry"}' \
+  0
+[[ ! -f "$FLAG_FILE" ]] && { echo "PASS: UserPromptSubmit cleared flag"; PASS=$((PASS+1)); } \
+                        || { echo "FAIL: UserPromptSubmit did NOT clear flag" >&2; FAIL=$((FAIL+1)); }
+
+run_case "PreToolUse Read after clearance → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Read","tool_input":{"file_path":"/tmp/foo"}}' \
+  0
+
+# Stale flag auto-clears
+PAST=$(( $(date -u +%s) - 700 ))
+echo "$PAST" > "$FLAG_FILE"
+run_case "Stale flag auto-clears, PreToolUse Read → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Read","tool_input":{"file_path":"/tmp/foo"}}' \
+  0
+
+# PostToolUse parse-success leaves flag absent
+rm -f "$FLAG_FILE"
+run_case "PostToolUse parse-success (isError:false) does NOT set flag" \
+  '{"hook_event_name":"PostToolUse","tool_name":"mcp__memory__whatsapp-export-parse","tool_input":{"filePath":"_chat.txt"},"tool_response":{"isError":false,"content":[{"type":"text","text":"{\"parsedLines\":[]}"}]}}' \
+  0
+[[ ! -f "$FLAG_FILE" ]] && { echo "PASS: parse-success leaves flag absent"; PASS=$((PASS+1)); } \
+                        || { echo "FAIL: parse-success incorrectly created flag" >&2; FAIL=$((FAIL+1)); }
+
+# Fail-closed terminal check
+if grep -q '\[ -t 0 \]' "$HOOK"; then
+  echo "PASS: fail-closed terminal check is present"
+  PASS=$((PASS + 1))
+else
+  echo "FAIL: fail-closed terminal check missing" >&2
+  FAIL=$((FAIL + 1))
+fi
+
+echo
+echo "──────── archive-ingest-surface-gate test summary ────────"
+echo "PASS: $PASS"
+echo "FAIL: $FAIL"
+
+[[ "$FAIL" -gt 0 ]] && exit 1
+exit 0