@rubytech/create-maxy-code 0.1.0

package/payload/platform/plugins/admin/mcp/dist/index.js

@@ -0,0 +1,3495 @@
+import { initStderrTee } from "../../../../lib/mcp-stderr-tee/dist/index.js";
+initStderrTee("admin");
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { eagerTool } from "../../../../lib/mcp-eager/dist/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve, join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { appendFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { writeKey, validateKey, hasKey, keyFilePath, deleteKey } from "../../../../lib/anthropic-key/dist/index.js";
+import { writeAdminEntry, removeAdminFromAccount } from "../../../../lib/admins-write/dist/index.js";
+import { isPersistentComponent } from "../../../../lib/persistent-components/dist/index.js";
+import { deviceUrlBlock } from "../../../../lib/device-url/dist/index.js";
+import { substituteBrandPlaceholders } from "../../../../lib/brand-templating/dist/index.js";
+import { resolveEntitlement } from "../../../../lib/entitlement/dist/index.js";
+import { createHash, randomInt, randomUUID } from "node:crypto";
+import { createConnection } from "node:net";
+import { homedir, hostname as osHostname } from "node:os";
+import QRCode from "qrcode";
+import { getSession, closeDriver } from "./lib/neo4j.js";
+import { getOnboardingState, completeOnboardingStep } from "./lib/onboarding.js";
+import { findSkillOwners, computePluginReadHint, loadSkill, parseRequiredInputs } from "./skill-resolution.js";
+import { resolvePublicHostname } from "./lib/public-hostname.js";
+const server = new McpServer({
+    name: "admin",
+    version: "0.1.0",
+});
+const PLATFORM_ROOT = process.env.PLATFORM_ROOT ?? resolve(import.meta.dirname, "../../../..");
+const ACCOUNT_ID = process.env.ACCOUNT_ID;
+if (!ACCOUNT_ID) {
+    throw new Error("ACCOUNT_ID environment variable is required");
+}
+const PLATFORM_PORT = process.env.PLATFORM_PORT;
+if (!PLATFORM_PORT) {
+    throw new Error("PLATFORM_PORT environment variable is required — set by getMcpServers() in claude-agent.ts");
+}
+// Brand-aware config — reads configDir, productName, and commercialMode from
+// brand.json stamped at install time. commercialMode (Task 831) gates the
+// entitlement verifier: false (default) preserves personal-mode installs;
+// true requires a Rubytech-signed entitlement.json or the install runs locked.
+// No fallback: if brand.json is missing or incomplete, the platform wasn't properly installed.
+function resolveBrandConfig() {
+    const brandPath = resolve(PLATFORM_ROOT, "config", "brand.json");
+    if (!existsSync(brandPath)) {
+        throw new Error(`brand.json not found at ${brandPath} — platform not properly installed`);
+    }
+    try {
+        const brand = JSON.parse(readFileSync(brandPath, "utf-8"));
+        if (!brand.configDir) {
+            throw new Error(`brand.json at ${brandPath} is missing the configDir field`);
+        }
+        if (!brand.productName) {
+            throw new Error(`brand.json at ${brandPath} is missing the productName field`);
+        }
+        // Task 924 + 959 — brand.json is the single source of truth for the
+        // four brand-scoped port fields. An admin MCP probe must see the exact
+        // same numbers the rest of the platform binds; silent vncDisplay-derived
+        // fallback was a recurrence-class silent-fallback-masks-root-cause
+        // violation (Task 959) and is now loud-fail.
+        const brandLabel = String(brand.configDir).replace(/^\./, "");
+        if (typeof brand.vncDisplay !== "number") {
+            console.error(`[mcp:admin] error reason=cdp-port-unresolved brand=${brandLabel} path=${brandPath} field=vncDisplay json_keys=${Object.keys(brand).join(",")}`);
+            throw new Error(`brand.json at ${brandPath} missing required field: vncDisplay`);
+        }
+        for (const field of ["rfbPort", "websockifyPort", "cdpPort"]) {
+            if (typeof brand[field] !== "number") {
+                console.error(`[mcp:admin] error reason=cdp-port-unresolved brand=${brandLabel} path=${brandPath} field=${field} json_keys=${Object.keys(brand).join(",")}`);
+                throw new Error(`brand.json at ${brandPath} missing required field: ${field}`);
+            }
+        }
+        return {
+            configDir: brand.configDir,
+            productName: brand.productName,
+            commercialMode: brand.commercialMode === true,
+            vncDisplay: brand.vncDisplay,
+            rfbPort: brand.rfbPort,
+            websockifyPort: brand.websockifyPort,
+            cdpPort: brand.cdpPort,
+        };
+    }
+    catch (err) {
+        if (err instanceof SyntaxError) {
+            throw new Error(`brand.json at ${brandPath} is not valid JSON: ${err.message}`);
+        }
+        throw err;
+    }
+}
+const BRAND_CONFIG = resolveBrandConfig();
+const CONFIG_DIR = resolve(homedir(), BRAND_CONFIG.configDir);
+const BRAND_NAME = BRAND_CONFIG.productName;
+// Entitlement input shape for the verifier. configDir is rooted under $HOME
+// (where entitlement.json is delivered post-purchase). platformRoot is needed
+// because the verifier runs in two bundle contexts (CJS dist for MCP, ESM tsup
+// bundle for UI) — caller passes the root rather than the verifier guessing.
+const ENTITLEMENT_BRAND = {
+    configDir: CONFIG_DIR,
+    platformRoot: PLATFORM_ROOT,
+    commercialMode: BRAND_CONFIG.commercialMode,
+};
+/** Resolve current effective entitlement. Memoized inside the verifier. */
+async function currentEntitlement() {
+    const config = await readAccountConfig();
+    return resolveEntitlement(ENTITLEMENT_BRAND, {
+        accountId: typeof config.accountId === "string" ? config.accountId : "",
+        customerEmail: typeof config.customerEmail === "string" ? config.customerEmail : undefined,
+        tier: typeof config.tier === "string" ? config.tier : undefined,
+        purchasedPlugins: Array.isArray(config.purchasedPlugins)
+            ? config.purchasedPlugins
+            : undefined,
+    });
+}
+const REMOTE_PASSWORD_FILE = resolve(CONFIG_DIR, ".remote-password");
+// Resolve account directory
+function getAccountDir() {
+    const dir = resolve(PLATFORM_ROOT, "..", "data/accounts", ACCOUNT_ID);
+    if (!existsSync(dir)) {
+        throw new Error(`Account directory not found: ${dir}`);
+    }
+    return dir;
+}
+async function readAccountConfig() {
+    const configPath = join(getAccountDir(), "account.json");
+    const content = await readFile(configPath, "utf-8");
+    return JSON.parse(content);
+}
+const STAGING_ROOT = resolve(PLATFORM_ROOT, "../premium-plugins");
+const PLUGINS_DIR = resolve(PLATFORM_ROOT, "plugins");
+const CORE_PLUGINS = ["admin", "memory", "docs", "cloudflare", "anthropic"];
+// users.json lives under CONFIG_DIR (persistent) — see paths.ts comment for
+// the regression that motivated the move. Both platform/ui and this MCP plugin
+// resolve the same file via brand-aware $HOME/<configDir>, so the device-level
+// admin auth store is single-pathed across both processes (Task 904).
+const USERS_FILE = resolve(CONFIG_DIR, "users.json");
+/** Maximum number of admin users allowed per tier. */
+const MAX_ADMINS_BY_TIER = {
+    solo: 1,
+    family: 5,
+    pro: 5,
+};
+const MAX_ADMINS_DEFAULT = 5;
+function hashPin(pin) {
+    return createHash("sha256").update(pin).digest("hex");
+}
+function readUsersJson() {
+    if (!existsSync(USERS_FILE)) {
+        throw new Error("users.json not found — run the seed script first");
+    }
+    const raw = readFileSync(USERS_FILE, "utf-8").trim();
+    if (!raw)
+        return [];
+    return JSON.parse(raw);
+}
+function writeUsersJson(users) {
+    writeFileSync(USERS_FILE, JSON.stringify(users, null, 2) + "\n", "utf-8");
+}
+function generateUniquePin(users, maxRetries = 10) {
+    const existingPins = new Set(users.map(u => u.pin));
+    for (let i = 0; i < maxRetries; i++) {
+        const raw = String(randomInt(0, 10000)).padStart(4, "0");
+        const hashed = hashPin(raw);
+        if (!existingPins.has(hashed)) {
+            return raw;
+        }
+        console.error(`[admin] PIN collision during admin-add: rejecting duplicate (attempt ${i + 1}/${maxRetries})`);
+    }
+    throw new Error("Could not generate a unique PIN after multiple attempts. Specify a PIN manually.");
+}
+const VALID_PLUGIN_NAME = /^[a-z0-9-]+$/;
+/** Parse YAML frontmatter from markdown content. Returns key-value pairs. */
+function parseFrontmatter(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return {};
+    const result = {};
+    let currentKey = "";
+    let currentArray = null;
+    for (const line of match[1].split("\n")) {
+        const kvMatch = line.match(/^(\w[\w-]*):\s*(.*)$/);
+        if (kvMatch) {
+            if (currentArray && currentKey) {
+                result[currentKey] = currentArray;
+                currentArray = null;
+            }
+            const [, key, rawValue] = kvMatch;
+            const value = rawValue.replace(/^["']|["']$/g, "").trim();
+            if (value) {
+                result[key] = value;
+                currentKey = key;
+            }
+            else {
+                // Key with no inline value — next lines may be array items
+                currentKey = key;
+                currentArray = [];
+            }
+        }
+        else if (currentArray !== null) {
+            const itemMatch = line.match(/^\s*-\s+(.+)$/);
+            if (itemMatch) {
+                currentArray.push(itemMatch[1].trim());
+            }
+        }
+    }
+    if (currentArray && currentKey) {
+        result[currentKey] = currentArray;
+    }
+    return result;
+}
+// ===================================================================
+// System tools
+// ===================================================================
+function checkPort(port, timeoutMs = 1000) {
+    return new Promise((res) => {
+        const socket = createConnection(port, "127.0.0.1");
+        socket.setTimeout(timeoutMs);
+        socket.once("connect", () => { socket.destroy(); res(true); });
+        socket.once("error", () => { socket.destroy(); res(false); });
+        socket.once("timeout", () => { socket.destroy(); res(false); });
+    });
+}
+eagerTool(server, "system-status", "Check health of all Maxy platform services: Neo4j, Ollama, Cloudflare tunnel, crontab (Maxy cron entries), VNC, Chrome (CDP), specialist agents, and deployed brand identity.", {}, async () => {
+    const checks = {};
+    try {
+        // Task 580: NEO4J_URI must be explicit. The outer try/catch surfaces the
+        // unset condition as `checks.neo4j = "unreachable: NEO4J_URI unset..."`
+        // so system-status still reports cleanly — the misconfig appears in the
+        // check output instead of taking down the whole tool.
+        const neo4jUri = process.env.NEO4J_URI;
+        if (!neo4jUri) {
+            throw new Error("NEO4J_URI unset (Task 580 — no silent default)");
+        }
+        // NOTE: the port-replace below only works when the URI ends in :7687.
+        // For non-default bolt ports (e.g. :7688 on realagent) the HTTP port is
+        // bolt - 213 (see graph-proxy.ts). Pre-existing fragility — flagged as a
+        // follow-up in .docs/neo4j-uri-audit.md. Not in scope for Task 580.
+        const res = await fetch(neo4jUri.replace("bolt://", "http://").replace("7687", "7474"), { signal: AbortSignal.timeout(3000) });
+        checks.neo4j = res.ok ? "healthy" : `unhealthy (${res.status})`;
+    }
+    catch (err) {
+        checks.neo4j = `unreachable: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    try {
+        const ollamaUrl = process.env.OLLAMA_URL ?? "http://localhost:11434";
+        const res = await fetch(`${ollamaUrl}/api/tags`, {
+            signal: AbortSignal.timeout(3000),
+        });
+        if (res.ok) {
+            const data = (await res.json());
+            const models = data.models?.map((m) => m.name).join(", ") ?? "none";
+            checks.ollama = `healthy (models: ${models})`;
+        }
+        else {
+            checks.ollama = `unhealthy (${res.status})`;
+        }
+    }
+    catch (err) {
+        checks.ollama = `unreachable: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    // Cloudflare tunnel: lightweight process check (full status via tunnel-status in cloudflare plugin)
+    try {
+        execFileSync("pgrep", ["-x", "cloudflared"], { timeout: 2000 });
+        checks.cloudflare = "running";
+    }
+    catch {
+        // pgrep exits non-zero if no process found
+        try {
+            execFileSync("which", ["cloudflared"], { encoding: "utf-8", timeout: 3000 });
+            checks.cloudflare = "installed but not running";
+        }
+        catch {
+            checks.cloudflare = "not installed";
+        }
+    }
+    // Crontab — brand cron entries registered by the installer
+    try {
+        const crontabOutput = execFileSync("crontab", ["-l"], {
+            encoding: "utf-8",
+            timeout: 3000,
+        });
+        const cronBeginMarker = `# BEGIN ${BRAND_NAME.toUpperCase()} CRONS`;
+        const cronEndMarker = `# END ${BRAND_NAME.toUpperCase()} CRONS`;
+        const beginIdx = crontabOutput.indexOf(cronBeginMarker);
+        const endIdx = crontabOutput.indexOf(cronEndMarker);
+        if (beginIdx === -1 || endIdx === -1) {
+            checks.crontab = `no ${BRAND_NAME} crons registered — run the installer to register them`;
+        }
+        else {
+            const block = crontabOutput.slice(beginIdx, endIdx);
+            const entries = block
+                .split("\n")
+                .filter((line) => line.trim() && !line.startsWith("#"));
+            if (entries.length === 0) {
+                checks.crontab = `${BRAND_NAME} cron block present but empty`;
+            }
+            else {
+                const names = entries.map((line) => {
+                    const commentMatch = line.match(/#\s*(.+)$/);
+                    if (commentMatch)
+                        return commentMatch[1].trim();
+                    const scriptMatch = line.match(/([^/\s]+)\.js/);
+                    if (scriptMatch)
+                        return scriptMatch[1];
+                    return line.trim().split(/\s+/).slice(-1)[0];
+                });
+                checks.crontab = `${entries.length} registered: ${names.join(", ")}`;
+            }
+        }
+    }
+    catch {
+        checks.crontab = "no crontab configured for this user";
+    }
+    // VNC display server (this brand's rfbPort — Task 924)
+    checks.vnc = (await checkPort(BRAND_CONFIG.rfbPort)) ? "running" : "not running";
+    // Chrome CDP (this brand's cdpPort — Task 924); personal-assistant
+    // browser tools depend on this.
+    const chromeUp = await checkPort(BRAND_CONFIG.cdpPort);
+    checks.chrome = chromeUp
+        ? "running"
+        : `not running — personal-assistant browser tools degraded (CDP port ${BRAND_CONFIG.cdpPort} not listening)`;
+    // WiFi — current connection state (Task 429)
+    try {
+        const wifiScan = execFileSync("nmcli", ["-t", "-f", "ACTIVE,SSID,SIGNAL", "device", "wifi", "list"], { encoding: "utf-8", timeout: 5000 });
+        const activeLine = wifiScan.split("\n").find((l) => l.startsWith("yes:"));
+        if (activeLine) {
+            const fields = activeLine.split(/(?<!\\):/).map((f) => f.replace(/\\:/g, ":"));
+            checks.wifi = `connected to ${fields[1]} (${fields[2]}%)`;
+        }
+        else {
+            checks.wifi = "not connected";
+        }
+    }
+    catch {
+        checks.wifi = "not available";
+    }
+    // Specialist agents — read AGENTS.md registry, verify files exist
+    try {
+        const accountDir = getAccountDir();
+        const agentsMdPath = join(accountDir, "agents/admin/AGENTS.md");
+        const specialistsAgentsDir = join(accountDir, "specialists/agents");
+        if (!existsSync(agentsMdPath)) {
+            checks.specialists = "not configured (AGENTS.md missing)";
+        }
+        else {
+            const content = readFileSync(agentsMdPath, "utf-8");
+            const entries = content.match(/^- \*\*specialists:([^*]+)\*\*/gm);
+            if (!entries || entries.length === 0) {
+                checks.specialists = "not configured (AGENTS.md empty)";
+            }
+            else {
+                const lines = [];
+                for (const entry of entries) {
+                    const nameMatch = entry.match(/specialists:([^*]+)/);
+                    if (!nameMatch)
+                        continue;
+                    const name = nameMatch[1];
+                    const fileExists = existsSync(join(specialistsAgentsDir, `${name}.md`));
+                    let status = fileExists ? "ok" : "missing file";
+                    if (name === "personal-assistant" && !chromeUp) {
+                        status = "degraded — chrome not running";
+                    }
+                    lines.push(`  ${name}: ${status}`);
+                }
+                checks.specialists = `${entries.length} registered\n${lines.join("\n")}`;
+            }
+        }
+    }
+    catch {
+        checks.specialists = "error reading specialist registry";
+    }
+    // OS hostname — the device's actual network name, used for URL construction
+    try {
+        checks.hostname = osHostname();
+    }
+    catch (err) {
+        console.error("[system-status] os.hostname() failed, falling back to brand.hostname", err);
+        checks.hostname = "unknown (os.hostname failed)";
+    }
+    // Running port — PLATFORM_PORT is what the parent process passes to MCP subprocesses;
+    // PORT is the main-process variable (available in dev); 19200 is the install default.
+    checks.port = process.env.PLATFORM_PORT ?? process.env.PORT ?? "19200";
+    console.error(`[system-status] port=${checks.port} hostname=${checks.hostname}`);
+    // Local URL — pre-computed for agent URL construction (avoids hostname/port assembly errors)
+    checks.localUrl = `http://${checks.hostname}.local:${checks.port}`;
+    // Brand identity — read build-time manifest stamped by the bundler
+    try {
+        const brandPath = resolve(PLATFORM_ROOT, "config/brand.json");
+        if (!existsSync(brandPath)) {
+            checks.brand = "not configured (dev environment)";
+        }
+        else {
+            const brand = JSON.parse(readFileSync(brandPath, "utf-8"));
+            checks.brand = `${brand.productName ?? "unknown"} (hostname: ${brand.hostname ?? "unknown"})`;
+        }
+    }
+    catch (err) {
+        checks.brand = `error reading brand config: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    // configDir — the brand-specific config directory name (e.g. ".maxy", ".realagent").
+    // Resolved from brand.json at module load. Exposed here so skills can reference
+    // the actual value instead of deriving it from the brand name via LLM inference.
+    checks.configDir = BRAND_CONFIG.configDir;
+    const formatted = Object.entries(checks)
+        .map(([service, status]) => `${service}: ${status}`)
+        .join("\n");
+    return { content: [{ type: "text", text: formatted }] };
+});
+eagerTool(server, "public-hostname", "Resolve this account's canonical public hostname. Reads cloudflared ingress + alias-domains.json — the same files the platform server trusts to route. Returns a single deterministic answer; use this immediately after publish-site to construct the full URL.", {}, async () => {
+    const TAG = "[admin:public-hostname]";
+    try {
+        const result = resolvePublicHostname(CONFIG_DIR);
+        if (result.hostname !== null) {
+            console.error(`${TAG} resolved accountId=${ACCOUNT_ID} hostname=${result.hostname} source=${result.source}`);
+            const body = `hostname: ${result.hostname}\n` +
+                `isApex: ${result.isApex}\n` +
+                `source: ${result.source}\n` +
+                `usage: paste \`https://${result.hostname}<path-slug>\` to the operator — the <path-slug> comes from publish-site.`;
+            return { content: [{ type: "text", text: body }] };
+        }
+        console.error(`${TAG} empty accountId=${ACCOUNT_ID} reason=${result.reason} files-checked=cloudflared-config.yml,alias-domains.json`);
+        return {
+            content: [{
+                    type: "text",
+                    text: `hostname: (none)\nreason: ${result.reason}\n` +
+                        `No Cloudflare tunnel is configured for this account. Run the cloudflare setup-tunnel skill before publishing externally.`,
+                }],
+        };
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.error(`${TAG} error accountId=${ACCOUNT_ID} message="${errMsg.replace(/"/g, "'")}"`);
+        return {
+            content: [{ type: "text", text: `error resolving public hostname: ${errMsg}` }],
+            isError: true,
+        };
+    }
+});
+eagerTool(server, "remote-auth-status", "Check whether the remote access password is configured. When not configured, emits a device-bound URL affordance (maxy-device-url fenced block) pointing at the password setup page — this URL opens on the device's own screen when the operator clicks it. The agent never constructs the password file path or runs shell commands — this tool is the single authority.", {}, async () => {
+    const TAG = "[remote-auth-status]";
+    const platformPort = parseInt(PLATFORM_PORT, 10);
+    const setupUrl = `http://${osHostname()}.local:${platformPort}/__remote-auth/setup`;
+    try {
+        const res = await fetch(`http://127.0.0.1:${platformPort}/api/remote-auth/status`, {
+            signal: AbortSignal.timeout(5000),
+        });
+        const body = await res.json();
+        const configured = body.configured === true;
+        console.error(`${TAG} configured=${configured} port=${platformPort}`);
+        // Shape the response for both the agent (deciding what to say) and
+        // the user (seeing the device-URL button when they need to act).
+        // Configured → plain status, no URL. Unconfigured → include the
+        // fenced block so the agent can surface the button verbatim.
+        const text = configured
+            ? `Remote access password is configured.`
+            : `Remote access password is not configured. The admin interface will refuse to expose over the tunnel until one is set.\n\n` +
+                `${deviceUrlBlock({ url: setupUrl, intent: "Set remote access password", hostname: osHostname() })}\n\n` +
+                `Ask the operator to set a password — either by clicking the button above (opens the setup page on the device) or by telling you one you can pass to \`remote-auth-set-password\`.`;
+        return {
+            content: [{ type: "text", text }],
+        };
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.error(`${TAG} failed to check remote-auth status: ${errMsg}`);
+        return {
+            content: [{
+                    type: "text",
+                    text: `Cannot verify remote authentication — the web server at http://127.0.0.1:${platformPort} is not reachable: ${errMsg}. Ensure the ${BRAND_NAME} platform is running.`,
+                }],
+            isError: true,
+        };
+    }
+});
+eagerTool(server, "brand-settings", "Read the brand/styling configuration (name, tagline, colours, fonts, plugin sets). Reads from config/brand.json (stamped by the bundler at install time).", {}, async () => {
+    try {
+        const brandPath = resolve(PLATFORM_ROOT, "config", "brand.json");
+        if (!existsSync(brandPath)) {
+            return { content: [{ type: "text", text: "No brand.json found — platform not properly installed." }], isError: true };
+        }
+        const brand = JSON.parse(readFileSync(brandPath, "utf-8"));
+        return { content: [{ type: "text", text: JSON.stringify(brand, null, 2) }] };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Failed: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+});
+/* ── Plugin selector options (deterministic) ────────────────────── */
+const PLUGIN_DISPLAY = {
+    admin: { value: "admin", label: "admin", description: "Platform management — system status, account settings, logs, session control." },
+    memory: { value: "memory", label: "memory", description: "Graph memory — search, write, reindex, and ingest knowledge." },
+    docs: { value: "docs", label: "maxy-guide", description: "User guide and platform documentation — loaded on demand." },
+    cloudflare: { value: "cloudflare", label: "cloudflare", description: "Cloudflare Tunnel — expose your assistant publicly via a custom domain." },
+    anthropic: { value: "anthropic", label: "anthropic", description: "Claude connection — API key acquisition and configuration." },
+    scheduling: { value: "scheduling", label: "scheduling", description: "Calendar and scheduling — events, appointments, recurring triggers." },
+    email: { value: "email", label: "email", description: "Agent email account — setup, read, send, search." },
+    contacts: { value: "contacts", label: "contacts", description: "CRM contact management — create, lookup, update, list." },
+    tasks: { value: "tasks", label: "tasks", description: "Graph-backed task lifecycle — create, update, list, relate, complete." },
+    workflows: { value: "workflows", label: "workflows", description: "Persistent named workflows — reusable instruction sets." },
+    projects: { value: "projects", label: "projects", description: "Structured project execution — phased sprints, investigations, reviews, retrospectives." },
+    "business-assistant": { value: "business-assistant", label: "business-assistant", description: "Customer enquiries, scheduling, quoting, invoicing, daily briefings. Enhances: personal-assistant" },
+    sales: { value: "sales", label: "sales", description: "Buying signal detection, closing techniques, objection handling. Enhances: personal-assistant" },
+    "deep-research": { value: "deep-research", label: "deep-research", description: "Structured multi-source research — query decomposition, source evaluation, citation formatting. Enhances: research-assistant" },
+    telegram: { value: "telegram", label: "telegram", description: "Telegram bot setup — BotFather, admin and public channels. Enhances: personal-assistant" },
+    whatsapp: { value: "whatsapp", label: "whatsapp", description: "WhatsApp messaging, pairing, and conversation browsing. Enhances: personal-assistant" },
+    waitlist: { value: "waitlist", label: "waitlist", description: "Waitlist lifecycle — extract sign-ups, review, schedule automation." },
+    replicate: { value: "replicate", label: "replicate", description: "Image generation — photorealistic, design, and fast draft images via Replicate. Enhances: content-producer, research-assistant" },
+};
+server.tool("onboarding-plugin-options", "Return the fully-assembled multi-select options array for onboarding Step 1. Classification (core/recommended/available) is derived from brand.json — the agent renders the result directly via render-component without further transformation.", {}, async () => {
+    try {
+        const brandPath = resolve(PLATFORM_ROOT, "config", "brand.json");
+        if (!existsSync(brandPath)) {
+            return { content: [{ type: "text", text: "No brand.json found at " + brandPath + " — platform not properly installed." }], isError: true };
+        }
+        const brand = JSON.parse(readFileSync(brandPath, "utf-8"));
+        const plugins = brand?.plugins;
+        if (!plugins)
+            return { content: [{ type: "text", text: "brand.json has no plugins configuration." }], isError: true };
+        const coreSet = new Set(plugins.core ?? []);
+        const defaultSet = new Set(plugins.defaultEnabled ?? []);
+        const availableSet = new Set(plugins.available ?? []);
+        const options = [];
+        for (const name of plugins.core ?? []) {
+            const meta = PLUGIN_DISPLAY[name] ?? { value: name, label: name, description: "" };
+            options.push({ ...meta, badge: "Core", group: "Core — always active", locked: true, defaultSelected: true });
+        }
+        for (const name of plugins.defaultEnabled ?? []) {
+            if (coreSet.has(name))
+                continue;
+            const meta = PLUGIN_DISPLAY[name] ?? { value: name, label: name, description: "" };
+            options.push({ ...meta, badge: "Recommended", group: "Maxy", defaultSelected: true });
+        }
+        for (const name of plugins.available ?? []) {
+            if (coreSet.has(name) || defaultSet.has(name))
+                continue;
+            const meta = PLUGIN_DISPLAY[name] ?? { value: name, label: name, description: "" };
+            options.push({ ...meta, group: "Maxy" });
+        }
+        // Task 976: signal that the onboarding skill will append three Anthropic
+        // vertical entries from the claude-for-financial-services and
+        // knowledge-work-plugins marketplaces. The count is fixed because the
+        // skill prose always appends the same three (kyc-screener,
+        // meeting-prep-agent, pdf-viewer). Absence of this line post-install
+        // = the group was not surfaced (release blocker per task spec).
+        console.error(`[plugin-onboarding] group=anthropic-verticals presented=3`);
+        return { content: [{ type: "text", text: JSON.stringify(options, null, 2) }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+});
+eagerTool(server, "account-manage", "Read the account configuration (tier, domains, settings).", {}, async () => {
+    try {
+        const config = await readAccountConfig();
+        return {
+            content: [{ type: "text", text: JSON.stringify(config, null, 2) }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Failed: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+});
+eagerTool(server, "account-update", "Update a user-configurable setting in account.json. Valid fields: outputStyle (default|explanatory), thinkingView (default|expanded|collapsed), effort (low|medium|high|max|auto), adminModel (any Anthropic model ID), publicModel (any Anthropic model ID), defaultAgent (slug of an existing public agent, or empty string to clear). Changes take effect on the next session.", {
+    field: z.enum(["outputStyle", "thinkingView", "effort", "adminModel", "publicModel", "defaultAgent"]),
+    value: z.string(),
+}, async ({ field, value }) => {
+    const VALID = {
+        outputStyle: ["default", "explanatory"],
+        thinkingView: ["default", "expanded", "collapsed"],
+        effort: ["low", "medium", "high", "max", "auto"],
+    };
+    // defaultAgent: non-empty slug must reference an existing agent; empty string clears the field
+    if (field === "defaultAgent") {
+        const slug = value.trim();
+        if (slug) {
+            const agentConfigPath = join(getAccountDir(), "agents", slug, "config.json");
+            if (!existsSync(agentConfigPath)) {
+                return {
+                    content: [{ type: "text", text: `Agent '${slug}' not found — no config.json in agents/${slug}/` }],
+                    isError: true,
+                };
+            }
+        }
+        // empty slug is valid — handled below as a delete operation
+    }
+    // Model fields accept any non-empty string (model IDs change frequently)
+    const FREE_FORM_FIELDS = ["adminModel", "publicModel"];
+    if (FREE_FORM_FIELDS.includes(field)) {
+        if (!value.trim()) {
+            return {
+                content: [{ type: "text", text: `Invalid value for ${field}. Must be a non-empty model ID.` }],
+                isError: true,
+            };
+        }
+    }
+    else if (field !== "defaultAgent" && !VALID[field].includes(value)) {
+        console.error(`[admin:account-update] rejected field=${field} value="${value}" valid=[${VALID[field].join(", ")}]`);
+        return {
+            content: [{ type: "text", text: `Invalid value "${value}" for ${field}. Valid values: ${VALID[field].join(", ")}` }],
+            isError: true,
+        };
+    }
+    try {
+        const configPath = join(getAccountDir(), "account.json");
+        const config = await readAccountConfig();
+        const oldDefault = field === "defaultAgent" ? config.defaultAgent ?? "(none)" : undefined;
+        if (field === "defaultAgent" && !value.trim()) {
+            delete config.defaultAgent;
+        }
+        else {
+            config[field] = value;
+        }
+        await writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+        console.error(`[admin:account-update] wrote field=${field} value="${value}" path=${configPath}`);
+        if (field === "defaultAgent") {
+            if (!value.trim()) {
+                return {
+                    content: [{ type: "text", text: `Default agent cleared (was "${oldDefault}"). Visitors to the root URL will see the first available agent, or a "no agents" message if none exist. Takes effect on next page load.` }],
+                };
+            }
+            return {
+                content: [{ type: "text", text: `Default agent changed from "${oldDefault}" to "${value}". Takes effect on next page load.` }],
+            };
+        }
+        return {
+            content: [{ type: "text", text: `Updated ${field} to "${value}". Takes effect on next session.` }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Failed: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+});
+// Plugin enable/disable: deterministic write to account.json.enabledPlugins.
+// The pre-tool-use hook denies the agent's direct Edit on account.json (Task 831),
+// so the agent can no longer toggle enablement by hand-editing the file. This
+// tool is the legitimate path: validates the plugin name, refuses core plugins,
+// confirms the plugin directory exists, and atomically updates the array.
+// Entitlement-bearing fields (tier, purchasedPlugins) are NOT writable here.
+server.tool("plugin-toggle-enabled", "Enable or disable a plugin in this account by adding/removing its name from account.json's enabledPlugins array. Validates the plugin exists under platform/plugins/, refuses to disable core plugins (admin, memory, docs, cloudflare, anthropic), and writes atomically. Takes effect on next session start. Does NOT change purchasedPlugins or tier — those derive from the signed entitlement payload.", {
+    pluginName: z.string().describe("Plugin slug (lowercase a-z0-9-)."),
+    action: z.enum(["enable", "disable"]).describe("enable adds to enabledPlugins; disable removes."),
+}, async ({ pluginName, action }) => {
+    const TAG = "[admin:plugin-toggle-enabled]";
+    if (!VALID_PLUGIN_NAME.test(pluginName)) {
+        return { content: [{ type: "text", text: `${TAG} Invalid plugin name "${pluginName}". Must match ${VALID_PLUGIN_NAME}.` }], isError: true };
+    }
+    if (CORE_PLUGINS.includes(pluginName)) {
+        return { content: [{ type: "text", text: `${TAG} "${pluginName}" is a core plugin and cannot be toggled.` }], isError: true };
+    }
+    const pluginDir = resolve(PLUGINS_DIR, pluginName);
+    if (!existsSync(pluginDir) || !existsSync(join(pluginDir, "PLUGIN.md"))) {
+        return { content: [{ type: "text", text: `${TAG} Plugin "${pluginName}" not installed at ${pluginDir} (no PLUGIN.md). Install via premium-deliver or platform release.` }], isError: true };
+    }
+    try {
+        const configPath = join(getAccountDir(), "account.json");
+        const config = await readAccountConfig();
+        const current = Array.isArray(config.enabledPlugins) ? config.enabledPlugins : [];
+        let next;
+        if (action === "enable") {
+            if (current.includes(pluginName)) {
+                return { content: [{ type: "text", text: `${TAG} "${pluginName}" is already enabled.` }] };
+            }
+            next = [...current, pluginName];
+        }
+        else {
+            if (!current.includes(pluginName)) {
+                return { content: [{ type: "text", text: `${TAG} "${pluginName}" is not enabled — nothing to disable.` }] };
+            }
+            next = current.filter((n) => n !== pluginName);
+        }
+        config.enabledPlugins = next;
+        await writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+        console.error(`${TAG} ${action}d plugin=${pluginName} path=${configPath}`);
+        return { content: [{ type: "text", text: `Plugin "${pluginName}" ${action}d. Takes effect on next session.` }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `${TAG} Failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+});
+// ===================================================================
+// Admin user management tools
+// ===================================================================
+eagerTool(server, "admin-add", "Add a new admin user to this account. Creates a device-level user entry (users.json) and adds them to this account's admins list (account.json). PIN must be at least 4 digits. If no PIN is provided, a unique 4-digit PIN is generated. Returns the userId and PIN to share with the new admin.\n\nIMPORTANT — retry behaviour: if the user already stated a specific PIN earlier in the conversation and a first admin-add call failed (e.g. tier cap reached, PIN collision), every retry MUST re-pass that PIN as the `pin` parameter. Omitting `pin` on the retry auto-generates a different 4-digit PIN, silently substituting what the user asked for.", {
+    name: z.string().describe("Display name for the new admin (stored on the AdminUser node in Neo4j)."),
+    pin: z.string().optional().describe("Optional PIN (minimum 4 digits). If omitted, a unique 4-digit PIN is generated."),
+}, async ({ name, pin: rawPin }) => {
+    const TAG = "[admin]";
+    if (!name.trim()) {
+        return { content: [{ type: "text", text: `${TAG} Name is required.` }], isError: true };
+    }
+    let users;
+    try {
+        users = readUsersJson();
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `${TAG} ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+    // Enforce per-tier admin limit. Effective tier comes from the signed
+    // entitlement payload (Task 831) — editing account.json.tier directly
+    // has no effect; the verifier uses the signed value and emits a
+    // [entitlement] tampered: line if disk and signed diverge.
+    try {
+        const config = await readAccountConfig();
+        const currentAdmins = (config.admins ?? []);
+        const entitlement = await currentEntitlement();
+        const tier = entitlement.tier;
+        const maxAdmins = MAX_ADMINS_BY_TIER[tier] ?? MAX_ADMINS_DEFAULT;
+        if (currentAdmins.length >= maxAdmins) {
+            return { content: [{ type: "text", text: `${TAG} Admin limit reached (${maxAdmins} for ${tier || "this"} tier). Remove an existing admin before adding a new one.` }], isError: true };
+        }
+    }
+    catch (err) {
+        console.error(`${TAG} failed to check admin limit: ${err instanceof Error ? err.message : String(err)}`);
+        // Fail open would be unsafe — fail closed
+        return { content: [{ type: "text", text: `${TAG} Unable to verify admin limit — cannot add admin.` }], isError: true };
+    }
+    // Resolve the calling user's identity from the session environment
+    const callerUserId = process.env.USER_ID;
+    // PIN: use provided or generate. Constraint: minimum 4 digits, no upper bound.
+    let plaintextPin;
+    if (rawPin) {
+        if (rawPin.length < 4) {
+            return { content: [{ type: "text", text: `${TAG} PIN must be at least 4 digits.` }], isError: true };
+        }
+        const hashed = hashPin(rawPin);
+        if (users.some(u => u.pin === hashed)) {
+            return { content: [{ type: "text", text: `${TAG} That PIN is already in use. Choose a different PIN.` }], isError: true };
+        }
+        plaintextPin = rawPin;
+    }
+    else {
+        try {
+            plaintextPin = generateUniquePin(users);
+        }
+        catch (err) {
+            return { content: [{ type: "text", text: `${TAG} ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+        }
+    }
+    const pinHash = hashPin(plaintextPin);
+    const userId = crypto.randomUUID();
+    // Three-store admin auth invariant (Task 850 → Task 904): users.json
+    // (device-level PIN auth) and account.json admins[] (account-level role)
+    // route through the shared `admins-write` helper so the dual write has a
+    // single chokepoint. Per-leg `[admins-write]` and legacy `[admin-auth-store]`
+    // log lines fire so existing dashboards continue to grep. Neo4j AdminUser
+    // (display + graph identity) writes below remain inline because they have
+    // no dual-file invariant.
+    const userIdShort = userId.slice(0, 8);
+    const authResult = writeAdminEntry({
+        userId,
+        pin: pinHash,
+        role: "admin",
+        usersFile: USERS_FILE,
+        accountDir: getAccountDir(),
+        caller: "admin-add",
+    });
+    console.error(`[admin-auth-store] action=add userId=${userIdShort} result=${authResult.usersJsonResult} store=users${authResult.usersError ? ` error=${authResult.usersError}` : ""}`);
+    if (authResult.usersJsonResult !== "ok") {
+        return { content: [{ type: "text", text: `${TAG} Failed to write users.json: ${authResult.usersError ?? "unknown error"}` }], isError: true };
+    }
+    console.error(`[admin-auth-store] action=add userId=${userIdShort} result=${authResult.accountJsonResult} store=account${authResult.accountError ? ` error=${authResult.accountError}` : ""}`);
+    if (authResult.accountJsonResult === "fail") {
+        return { content: [{ type: "text", text: `${TAG} users.json updated; account.json write FAILED — manual reconciliation needed: ${authResult.accountError ?? "unknown error"}` }], isError: true };
+    }
+    // 3. Write to Neo4j (graph-level): AdminUser + Person + OWNS atomically,
+    //    plus ADMIN_OF edge to the LocalBusiness for this account.
+    //    Task 830 — deterministic identity creation: never delegate node
+    //    creation to the LLM. Person reuse rule mirrors writeAdminUserAndPerson
+    //    in platform/ui/app/lib/neo4j-store.ts (case-insensitive exact match
+    //    on givenName + familyName; partial-name ambiguity does NOT match —
+    //    rationalisation is a separate agent-mediated concern).
+    //    Task 850 — Neo4j-leg failure now returns is_error: true with the
+    //    [admin-auth-store] line; previously it set a soft warning string and
+    //    returned success, which is what hid the Adam Mackay incident from
+    //    the recovery agent. The user is still functional via users.json +
+    //    account.json, but the graph state is divergent and the operator
+    //    must know.
+    let personReused = false;
+    try {
+        const session = getSession();
+        try {
+            const createdAt = new Date().toISOString();
+            const trimmedName = name.trim();
+            const firstSpace = trimmedName.search(/\s/);
+            const givenName = firstSpace === -1 ? trimmedName : trimmedName.slice(0, firstSpace).trim();
+            const familyName = firstSpace === -1 ? null : (trimmedName.slice(firstSpace + 1).trim() || null);
+            // Task 897: stamp `accountId` on every AdminUser at MERGE time, both
+            // ON CREATE and ON MATCH (the latter via COALESCE so a pre-existing
+            // value isn't overwritten if it differs — which would itself be a
+            // graph-invariant violation worth surfacing). Pre-897 the missing
+            // accountId fingerprint produced :AdminUser nodes that migration 004
+            // pruned silently, costing the admin pin during onboarding.
+            const result = await session.run(`MERGE (au:AdminUser {userId: $userId})
+           ON CREATE SET au.accountId = $accountId,
+                         au.name = $name,
+                         au.createdAt = $createdAt
+           ON MATCH SET au.accountId = COALESCE(au.accountId, $accountId),
+                        au.name = $name,
+                        au.updatedAt = $createdAt
+           WITH au
+           MATCH (b:LocalBusiness {accountId: $accountId})
+           MERGE (au)-[r:ADMIN_OF]->(b)
+           ON CREATE SET r.role = 'admin', r.grantedAt = $createdAt
+           WITH au
+           OPTIONAL MATCH (existingPerson:Person {accountId: $accountId})
+           WHERE toLower(existingPerson.givenName) = toLower($givenName)
+             AND coalesce(toLower(existingPerson.familyName), '') = coalesce(toLower($familyName), '')
+           WITH au, existingPerson
+           CALL {
+             WITH au, existingPerson
+             WITH au, existingPerson WHERE existingPerson IS NOT NULL
+             MERGE (au)-[:OWNS]->(existingPerson)
+             RETURN true AS reused
+             UNION
+             WITH au, existingPerson
+             WITH au WHERE existingPerson IS NULL
+             CREATE (newPerson:Person {
+               accountId: $accountId,
+               givenName: $givenName,
+               familyName: $familyName,
+               role: 'admin-personal',
+               scope: 'admin',
+               createdAt: $createdAt
+             })
+             MERGE (au)-[:OWNS]->(newPerson)
+             RETURN false AS reused
+           }
+           RETURN reused`, { userId, name: trimmedName, createdAt, accountId: ACCOUNT_ID, givenName, familyName });
+            if (result.records.length > 0) {
+                personReused = result.records[0].get("reused");
+            }
+            // Task 897 — post-write assertion mirroring Task 785 in neo4j-store.ts.
+            // MATCH back the AdminUser we just wrote and verify every required
+            // field landed. Loud-fail the tool call if accountId or name is null
+            // so a Cypher regression that drops the field is grep-detectable.
+            const verify = await session.run(`MATCH (au:AdminUser {userId: $userId})
+           RETURN coalesce(au.accountId, '') AS accountId,
+                  coalesce(au.name, '')      AS name`, { userId });
+            const verifiedAccountId = verify.records[0]?.get("accountId") || "";
+            const verifiedName = verify.records[0]?.get("name") || "";
+            if (!verifiedAccountId || !verifiedName) {
+                throw new Error(`post-write assertion failed: AdminUser userId=${userIdShort} accountId=${verifiedAccountId || "(null)"} name=${verifiedName || "(null)"} — required fields missing after MERGE`);
+            }
+        }
+        finally {
+            await session.close();
+        }
+        console.error(`[admin] admin-add success userId=${userIdShort} accountId=${ACCOUNT_ID} name=${name.trim()} required-fields=ok personReused=${personReused}`);
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.error(`[admin-auth-store] action=add userId=${userIdShort} result=fail store=neo4j error=${errMsg}`);
+        return {
+            content: [{
+                    type: "text",
+                    text: `${TAG} users.json + account.json updated for userId ${userId} (PIN: ${plaintextPin}); Neo4j sync FAILED — manual reconciliation needed: ${errMsg}`,
+                }],
+            isError: true,
+        };
+    }
+    console.error(`${TAG} [admin-identity] adminuser-bound userId=${userIdShort} name=${name.trim()} personReused=${personReused}`);
+    console.error(`${TAG} admin added: userId=${userId} userName=${name.trim()} accountId=${ACCOUNT_ID} role=admin addedBy=${callerUserId ?? "unknown"}`);
+    return {
+        content: [{
+                type: "text",
+                text: `Admin added successfully.\n\n- **Name:** ${name.trim()}\n- **userId:** ${userId}\n- **PIN:** ${plaintextPin}\n- **Role:** admin\n\nShare the PIN with ${name.trim()} so they can log in.`,
+            }],
+    };
+});
+eagerTool(server, "admin-remove", "Remove an admin from this account. Removes them from the account's admins list (account.json) and deletes the ADMIN_OF relationship in Neo4j. Does NOT remove the device-level user entry (they may admin other accounts). Cannot remove the last admin on the account.", {
+    userId: z.string().describe("The userId of the admin to remove (use admin-list to find userIds)"),
+}, async ({ userId }) => {
+    const TAG = "[admin]";
+    const callerUserId = process.env.USER_ID;
+    // Read account.json and validate
+    let config;
+    let admins;
+    try {
+        config = await readAccountConfig();
+        admins = (config.admins ?? []);
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `${TAG} Failed to read account config: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+    const targetIndex = admins.findIndex(a => a.userId === userId);
+    if (targetIndex === -1) {
+        return { content: [{ type: "text", text: `${TAG} User ${userId} is not an admin of this account.` }], isError: true };
+    }
+    if (admins.length <= 1) {
+        return { content: [{ type: "text", text: `${TAG} Cannot remove the last admin. At least one admin must remain on the account.` }], isError: true };
+    }
+    // Resolve the admin's name from Neo4j (canonical) for the confirmation
+    // message. Best-effort — fall back to userId if the graph is unreachable.
+    let removedName = userId;
+    try {
+        const session = getSession();
+        try {
+            const result = await session.run(`MATCH (au:AdminUser {userId: $userId}) RETURN au.name AS name LIMIT 1`, { userId });
+            if (result.records.length > 0) {
+                const name = result.records[0].get("name");
+                if (name && name.trim())
+                    removedName = name.trim();
+            }
+        }
+        finally {
+            await session.close();
+        }
+    }
+    catch { /* name lookup is best-effort */ }
+    // 1. Remove from account.json — single-file write through the shared
+    // chokepoint helper. users.json is intentionally untouched (the user may
+    // admin other accounts on this device); the helper logs `usersJsonResult=skip`.
+    const removeResult = removeAdminFromAccount({
+        userId,
+        accountDir: getAccountDir(),
+        caller: "admin-remove",
+    });
+    if (removeResult.accountJsonResult === "fail") {
+        return { content: [{ type: "text", text: `${TAG} Failed to write account.json: ${removeResult.accountError ?? "unknown error"}` }], isError: true };
+    }
+    // 2. Delete ADMIN_OF relationship in Neo4j — partial failure is a warning
+    let neo4jWarning = "";
+    try {
+        const session = getSession();
+        try {
+            await session.run(`MATCH (au:AdminUser {userId: $userId})-[r:ADMIN_OF]->(b:LocalBusiness {accountId: $accountId})
+           DELETE r`, { userId, accountId: ACCOUNT_ID });
+        }
+        finally {
+            await session.close();
+        }
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.error(`${TAG} Neo4j sync failed during admin-remove: userId=${userId} error=${errMsg}`);
+        neo4jWarning = ` Note: Neo4j relationship deletion failed (${errMsg}) — will be reconciled on next seed.`;
+    }
+    console.error(`${TAG} admin removed: userId=${userId} accountId=${ACCOUNT_ID} removedBy=${callerUserId ?? "unknown"}`);
+    return {
+        content: [{
+                type: "text",
+                text: `Removed ${removedName} from this account's admin list. Their PIN still works for any other accounts they administer.${neo4jWarning}`,
+            }],
+    };
+});
+eagerTool(server, "admin-list", "List all admins for this account with their names and roles.", {}, async () => {
+    const TAG = "[admin]";
+    let admins;
+    try {
+        const config = await readAccountConfig();
+        admins = (config.admins ?? []);
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `${TAG} Failed to read account config: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+    }
+    if (admins.length === 0) {
+        return { content: [{ type: "text", text: `${TAG} No admins configured for this account.` }] };
+    }
+    // Enrich with names from Neo4j AdminUser (canonical, Task 829). Best
+    // effort — render "(unknown)" for any userId without a graph entry.
+    const userMap = new Map();
+    try {
+        const session = getSession();
+        try {
+            const result = await session.run(`UNWIND $userIds AS uid
+           MATCH (au:AdminUser {userId: uid})
+           RETURN au.userId AS userId, au.name AS name`, { userIds: admins.map(a => a.userId) });
+            for (const record of result.records) {
+                const uid = record.get("userId");
+                const name = record.get("name");
+                if (name && name.trim())
+                    userMap.set(uid, name.trim());
+            }
+        }
+        finally {
+            await session.close();
+        }
+    }
+    catch { /* name lookup is best-effort — userIds shown when graph is unreachable */ }
+    const lines = admins.map(a => {
+        const name = userMap.get(a.userId) ?? "(unknown)";
+        return `- **${name}** — role: ${a.role}, userId: ${a.userId}`;
+    });
+    return {
+        content: [{ type: "text", text: `Admins for this account:\n\n${lines.join("\n")}` }],
+    };
+});
+eagerTool(server, "admin-update-pin", "Update an existing admin user's PIN. Defaults to the calling admin if no userId is given. PIN must be at least 4 digits and unique across all users on the device. PINs are device-level: updating another admin's PIN does not require shared account membership — any admin on the device can rotate any other admin's PIN, matching the existing trust model used by admin-remove.", {
+    userId: z.string().optional().describe("The userId of the admin whose PIN to update. Defaults to the caller (the admin invoking this tool)."),
+    newPin: z.string().describe("The new PIN. Minimum 4 digits, no upper bound."),
+}, async ({ userId: targetUserId, newPin }) => {
+    const TAG = "[admin-update-pin]";
+    const callerUserId = process.env.USER_ID;
+    const userId = targetUserId ?? callerUserId;
+    const userIdLabel = userId ? userId.slice(0, 8) : "unknown";
+    if (!userId) {
+        console.error(`${TAG} userId=${userIdLabel} result=user-not-found reason=no-caller-context`);
+        return { content: [{ type: "text", text: `${TAG} No userId supplied and no caller context — cannot update.` }], isError: true };
+    }
+    if (newPin.length < 4) {
+        console.error(`${TAG} userId=${userIdLabel} result=too-short`);
+        return { content: [{ type: "text", text: `${TAG} PIN must be at least 4 digits.` }], isError: true };
+    }
+    let users;
+    try {
+        users = readUsersJson();
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.error(`${TAG} userId=${userIdLabel} result=user-not-found reason=users-json-read-failed`);
+        console.error(`[admin-auth-store] action=update-pin userId=${userIdLabel} result=fail store=users error=${errMsg}`);
+        return { content: [{ type: "text", text: `${TAG} ${errMsg}` }], isError: true };
+    }
+    const targetIndex = users.findIndex(u => u.userId === userId);
+    if (targetIndex === -1) {
+        console.error(`${TAG} userId=${userIdLabel} result=user-not-found`);
+        console.error(`[admin-auth-store] action=update-pin userId=${userIdLabel} result=fail store=users error=user-not-found`);
+        return { content: [{ type: "text", text: `${TAG} User ${userId} not found in users.json.` }], isError: true };
+    }
+    const newHash = hashPin(newPin);
+    const collidesWithOther = users.some((u, i) => i !== targetIndex && u.pin === newHash);
+    if (collidesWithOther) {
+        console.error(`${TAG} userId=${userIdLabel} result=collision`);
+        console.error(`[admin-auth-store] action=update-pin userId=${userIdLabel} result=fail store=users error=pin-collision`);
+        return { content: [{ type: "text", text: `${TAG} That PIN is already in use by another user. Choose a different PIN.` }], isError: true };
+    }
+    users[targetIndex].pin = newHash;
+    try {
+        writeUsersJson(users);
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.error(`[admin-auth-store] action=update-pin userId=${userIdLabel} result=fail store=users error=${errMsg}`);
+        return { content: [{ type: "text", text: `${TAG} Failed to write users.json: ${errMsg}` }], isError: true };
+    }
+    console.error(`${TAG} userId=${userIdLabel} result=ok`);
+    console.error(`[admin-auth-store] action=update-pin userId=${userIdLabel} result=ok store=users`);
+    const self = userId === callerUserId;
+    return {
+        content: [{ type: "text", text: `PIN updated${self ? "" : ` for userId ${userId}`}. The new PIN takes effect on the next login.` }],
+    };
+});
+server.tool("agent-image", "Upload, update, or remove an agent's image. action=set: copy the file at filePath to the agent's assets directory and update config.json with image URL and shape. action=remove: delete the image file and clear the image fields from config.json. imageShape: 'circle' for avatars/icons, 'rounded' for logos.", {
+    agentSlug: z.string().describe("Agent slug (e.g. 'coaching', 'sales')"),
+    action: z.enum(["set", "remove"]),
+    filePath: z.string().optional().describe("Absolute path to the image file (required for action=set)"),
+    imageShape: z.enum(["circle", "rounded"]).optional().describe("Image shape: circle for avatars, rounded for logos (required for action=set)"),
+}, async ({ agentSlug, action, filePath, imageShape }) => {
+    const VALID_IMAGE_EXTENSIONS = [".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg"];
+    try {
+        const accountDir = getAccountDir();
+        const agentDir = resolve(accountDir, "agents", agentSlug);
+        const configPath = resolve(agentDir, "config.json");
+        if (!existsSync(configPath)) {
+            return {
+                content: [{ type: "text", text: `Agent '${agentSlug}' not found — no config.json at agents/${agentSlug}/` }],
+                isError: true,
+            };
+        }
+        if (action === "set") {
+            if (!filePath) {
+                return {
+                    content: [{ type: "text", text: "filePath is required for action=set" }],
+                    isError: true,
+                };
+            }
+            if (!imageShape) {
+                return {
+                    content: [{ type: "text", text: "imageShape is required for action=set — use 'circle' for avatars/icons or 'rounded' for logos" }],
+                    isError: true,
+                };
+            }
+            if (!existsSync(filePath)) {
+                return {
+                    content: [{ type: "text", text: `File not found: ${filePath}` }],
+                    isError: true,
+                };
+            }
+            // Validate image extension
+            const ext = filePath.toLowerCase().split(".").pop();
+            if (!ext || !VALID_IMAGE_EXTENSIONS.includes(`.${ext}`)) {
+                return {
+                    content: [{ type: "text", text: `Not a valid image file. Supported formats: ${VALID_IMAGE_EXTENSIONS.join(", ")}` }],
+                    isError: true,
+                };
+            }
+            // Copy file to agent assets directory
+            const assetsDir = resolve(agentDir, "assets");
+            const { mkdirSync: mkdirSyncFs, copyFileSync, writeFileSync: writeFileSyncFs, renameSync } = await import("node:fs");
+            mkdirSyncFs(assetsDir, { recursive: true });
+            const filename = `agent-image.${ext}`;
+            const destPath = resolve(assetsDir, filename);
+            copyFileSync(filePath, destPath);
+            // Atomic config update: read → modify → write temp → rename
+            const configRaw = await readFile(configPath, "utf-8");
+            let config;
+            try {
+                config = JSON.parse(configRaw);
+            }
+            catch {
+                config = {};
+            }
+            config.image = `/agent-assets/${agentSlug}/${filename}`;
+            config.imageShape = imageShape;
+            const tmpPath = configPath + ".tmp";
+            writeFileSyncFs(tmpPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+            renameSync(tmpPath, configPath);
+            console.error(`[agent-config] ${agentSlug}: image=${config.image} imageShape=${imageShape} (set)`);
+            return {
+                content: [{ type: "text", text: `Image set for agent '${agentSlug}':\n  File: ${destPath}\n  URL: ${config.image}\n  Shape: ${imageShape}\n\nThe image is now accessible at ${config.image} and will appear in the public chat header.` }],
+            };
+        }
+        // action === "remove"
+        const configRaw = await readFile(configPath, "utf-8");
+        let config;
+        try {
+            config = JSON.parse(configRaw);
+        }
+        catch {
+            config = {};
+        }
+        // Delete the image file if it exists
+        if (typeof config.image === "string") {
+            const filename = config.image.split("/").pop();
+            if (filename) {
+                const imgPath = resolve(agentDir, "assets", filename);
+                if (existsSync(imgPath)) {
+                    const { unlinkSync } = await import("node:fs");
+                    unlinkSync(imgPath);
+                }
+            }
+        }
+        // Remove image fields from config
+        delete config.image;
+        delete config.imageShape;
+        const { writeFileSync: writeFileSyncRm, renameSync: renameSyncRm } = await import("node:fs");
+        const tmpPath = configPath + ".tmp";
+        writeFileSyncRm(tmpPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+        renameSyncRm(tmpPath, configPath);
+        console.error(`[agent-config] ${agentSlug}: image removed`);
+        return {
+            content: [{ type: "text", text: `Image removed for agent '${agentSlug}'. The public chat header will fall back to the account brand logo.` }],
+        };
+    }
+    catch (err) {
+        console.error(`[agent-config] agent-image failed: ${err instanceof Error ? err.message : String(err)}`);
+        return {
+            content: [{ type: "text", text: `Failed: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+});
+// ---------------------------------------------------------------------------
+// Agent config tools — deterministic reads for agent configuration
+// ---------------------------------------------------------------------------
+server.tool("agent-config-read", "Read the full config.json for a specific public agent by slug. Returns the complete configuration including slug, displayName, model, plugins, status, liveMemory, and any other fields.", {
+    slug: z.string().describe("Agent slug (directory name under agents/)"),
+}, async ({ slug }) => {
+    const TAG = "[admin:agent-config-read]";
+    // Path traversal guard
+    if (slug.includes("/") || slug.includes("\\") || slug.includes("..")) {
+        console.error(`${TAG} rejected slug="${slug}" — contains path separator or traversal sequence`);
+        return {
+            content: [{ type: "text", text: `Invalid agent slug: "${slug}" — slug must not contain path separators or traversal sequences` }],
+            isError: true,
+        };
+    }
+    try {
+        const accountDir = getAccountDir();
+        const configPath = resolve(accountDir, "agents", slug, "config.json");
+        if (!existsSync(configPath)) {
+            console.error(`${TAG} agent not found: slug="${slug}"`);
+            return {
+                content: [{ type: "text", text: `Agent "${slug}" not found — no config.json at agents/${slug}/` }],
+                isError: true,
+            };
+        }
+        const raw = readFileSync(configPath, "utf-8");
+        JSON.parse(raw); // validate JSON before returning
+        return {
+            content: [{ type: "text", text: raw }],
+        };
+    }
+    catch (err) {
+        console.error(`${TAG} failed for slug="${slug}": ${err instanceof Error ? err.message : String(err)}`);
+        return {
+            content: [{ type: "text", text: `Failed to read config for agent "${slug}": ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+});
+server.tool("agent-list", "List all public (non-admin) agents with their full configuration: slug, displayName, model, plugins, status, liveMemory, and whether each is the account's default agent.", {}, async () => {
+    const TAG = "[admin:agent-list]";
+    try {
+        const accountDir = getAccountDir();
+        const agentsDir = resolve(accountDir, "agents");
+        if (!existsSync(agentsDir)) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ agents: [], skipped: [] }, null, 2) }],
+            };
+        }
+        // Best-effort defaultAgent lookup — don't fail the whole list if account.json is unreadable
+        let defaultAgent;
+        try {
+            const accountConfig = await readAccountConfig();
+            defaultAgent = accountConfig.defaultAgent;
+        }
+        catch (err) {
+            console.error(`${TAG} failed to read account config for defaultAgent lookup: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const agents = [];
+        const skipped = [];
+        const entries = readdirSync(agentsDir, { withFileTypes: true });
+        for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name === "admin")
+                continue;
+            const configPath = resolve(agentsDir, entry.name, "config.json");
+            if (!existsSync(configPath))
+                continue;
+            try {
+                const config = JSON.parse(readFileSync(configPath, "utf-8"));
+                agents.push({
+                    slug: entry.name,
+                    displayName: config.displayName ?? entry.name,
+                    model: config.model,
+                    plugins: config.plugins,
+                    status: config.status,
+                    liveMemory: config.liveMemory === true || config.liveMemory === "true",
+                    isDefault: entry.name === defaultAgent,
+                });
+            }
+            catch (err) {
+                console.error(`${TAG} failed to parse config.json for agent "${entry.name}" — skipping: ${err instanceof Error ? err.message : String(err)}`);
+                skipped.push(entry.name);
+            }
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify({ agents, skipped }, null, 2) }],
+        };
+    }
+    catch (err) {
+        console.error(`${TAG} failed: ${err instanceof Error ? err.message : String(err)}`);
+        return {
+            content: [{ type: "text", text: `Failed to list agents: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+});
+eagerTool(server, "logs-read", "Read recent logs. Stream logs (type=agent-stream/error/session/public) are per-session — pass `sessionKey` (preferred) or the legacy `conversationId` alias to retrieve a single session's log from first [spawn] to final [process-exit]. type=agent-stream: per-session tool-use/tool-result archive (every `[tool-use]` and `[tool-result]` pair with full input + output JSON, plus raw Claude stream-json, agent events, and MCP server stderr via tee). USE THIS when investigating what an agent ACTUALLY did with its tools — server.log only carries `[persist] tool-call persisted` markers, not bodies. (`type=system` is a backwards-compatible alias for the same archive.) type=session: SSE events sent to client. type=error: Claude subprocess stderr (raw — NODE_DEBUG HTTP/NET/UNDICI traces land in agent-stream via the stream tee, not here). type=heartbeat: platform event dispatcher (check-due-events cron). type=public: public agent diagnostic log. type=server: platform server log. type=mcp: MCP server stderr (per-plugin raw). type=vnc: VNC browser viewer lifecycle.", {
+    type: z.enum(["agent-stream", "system", "session", "error", "heartbeat", "public", "server", "mcp", "vnc"]).optional(),
+    lines: z.number().optional(),
+    sessionKey: z.string().optional(),
+    conversationId: z.string().optional(),
+}, async ({ type, lines = 50, sessionKey, conversationId }) => {
+    try {
+        const LOG_DIR = resolve(getAccountDir(), "logs");
+        // Task 1006 — sessionKey is the single identifier on disk.
+        // `conversationId` is retained as a legacy alias that maps to the
+        // sessionKey-named file; Task 1007 will collapse the alias in the UI.
+        const idForResolve = sessionKey ?? conversationId;
+        if (idForResolve) {
+            if (!existsSync(LOG_DIR)) {
+                return { content: [{ type: "text", text: `Log directory does not exist: ${LOG_DIR}` }] };
+            }
+            const prefixMap = {
+                "agent-stream": "claude-agent-stream",
+                system: "claude-agent-stream", // Task 850 — backwards-compatible alias for agent-stream
+                error: "claude-agent-stderr",
+                session: "sse-events",
+                public: "public-agent-stream",
+            };
+            const resolvedType = type ?? "agent-stream";
+            const prefix = prefixMap[resolvedType];
+            if (!prefix) {
+                return {
+                    content: [{ type: "text", text: `type=${resolvedType} is not per-session. Valid per-session types: agent-stream, error, session, public. For platform-scoped types (server, vnc, heartbeat, mcp) omit the id.` }],
+                    isError: true,
+                };
+            }
+            const fileName = `${prefix}-${idForResolve}.log`;
+            const filePath = resolve(LOG_DIR, fileName);
+            if (existsSync(filePath)) {
+                const result = execFileSync("tail", ["-n", String(lines), filePath], { timeout: 5000 }).toString();
+                return { content: [{ type: "text", text: `# ${fileName}\n\n${result}` }] };
+            }
+            // Emit missing-on-resolve so the writer-side existence contract is
+            // the authoritative signal. One such line on any device is a P0.
+            try {
+                const ts = new Date().toISOString();
+                appendFileSync(resolve(CONFIG_DIR, "logs", "server.log"), `${ts} [log-tee] missing-on-resolve sessionKey=${idForResolve.slice(0, 8)} surface=mcp-logs-read reason="file-not-found-in-LOG_DIR"\n`);
+            }
+            catch {
+                // best-effort
+            }
+            return {
+                content: [{
+                        type: "text",
+                        text: `No log file found for id=${idForResolve} type=${resolvedType}. tried=[${filePath}] reason=file-not-found`,
+                    }],
+            };
+        }
+        if (!existsSync(LOG_DIR)) {
+            return { content: [{ type: "text", text: `Log directory does not exist: ${LOG_DIR}` }] };
+        }
+        // --- Session-key filtered mode: grep across log files ---
+        if (sessionKey) {
+            const prefixes = {
+                "agent-stream": "claude-agent-stream-",
+                system: "claude-agent-stream-", // Task 850 — backwards-compatible alias
+                error: "claude-agent-stderr-",
+                session: "sse-events-",
+                public: "public-agent-stream-",
+                mcp: "mcp-",
+            };
+            // When a type is explicitly provided, search only that type's files.
+            // When type is omitted, search all prefix-based log types (excludes heartbeat — no session context).
+            // server and vnc are single-file (configDir-scoped), so they have no prefix search;
+            // their matches are produced by dedicated blocks below.
+            const searchPrefixes = type && type !== "heartbeat" && type !== "server" && type !== "vnc" && prefixes[type]
+                ? { [type]: prefixes[type] }
+                : (type === "server" || type === "vnc") ? {} : prefixes;
+            const allFiles = readdirSync(LOG_DIR).filter(f => f.endsWith(".log"));
+            const sections = [];
+            // Search account-scoped prefix-based log files
+            for (const [logType, prefix] of Object.entries(searchPrefixes)) {
+                const typeFiles = allFiles
+                    .filter(f => f.startsWith(prefix))
+                    .sort(); // chronological by date suffix
+                for (const file of typeFiles) {
+                    const filePath = resolve(LOG_DIR, file);
+                    try {
+                        const result = execFileSync("grep", ["-F", sessionKey, filePath], { timeout: 5000 }).toString().trim();
+                        if (result) {
+                            sections.push(`## ${file} (${logType})\n${result}`);
+                        }
+                    }
+                    catch (grepErr) {
+                        // grep exits 1 when no lines match — that's not an error
+                        const exitCode = grepErr.status;
+                        if (exitCode !== 1)
+                            throw grepErr;
+                    }
+                }
+            }
+            // Search server.log (platform-scoped, in configDir — not account-scoped)
+            const includeServer = !type || type === "server";
+            if (includeServer) {
+                const serverLog = resolve(CONFIG_DIR, "logs", "server.log");
+                if (existsSync(serverLog)) {
+                    try {
+                        const result = execFileSync("grep", ["-F", sessionKey, serverLog], { timeout: 5000 }).toString().trim();
+                        if (result) {
+                            sections.push(`## server.log (server)\n${result}`);
+                        }
+                    }
+                    catch (grepErr) {
+                        const exitCode = grepErr.status;
+                        if (exitCode !== 1)
+                            throw grepErr;
+                    }
+                }
+            }
+            // Search vnc-boot.log (platform-scoped, in configDir) — the
+            // consolidated VNC browser viewer lifecycle log.
+            const includeVnc = !type || type === "vnc";
+            if (includeVnc) {
+                const vncLog = resolve(CONFIG_DIR, "logs", "vnc-boot.log");
+                if (existsSync(vncLog)) {
+                    try {
+                        const result = execFileSync("grep", ["-F", sessionKey, vncLog], { timeout: 5000 }).toString().trim();
+                        if (result) {
+                            sections.push(`## vnc-boot.log (vnc)\n${result}`);
+                        }
+                    }
+                    catch (grepErr) {
+                        const exitCode = grepErr.status;
+                        if (exitCode !== 1)
+                            throw grepErr;
+                    }
+                }
+            }
+            if (sections.length === 0) {
+                return { content: [{ type: "text", text: `No log lines found for session key "${sessionKey}".` }] };
+            }
+            return { content: [{ type: "text", text: `# Session timeline: ${sessionKey}\n\n${sections.join("\n\n")}` }] };
+        }
+        // --- Standard mode: tail most recent file of the requested type ---
+        const resolvedType = type ?? "agent-stream";
+        // Heartbeat log is a single fixed file, not prefix-based
+        if (resolvedType === "heartbeat") {
+            const logFile = resolve(LOG_DIR, "check-due-events.log");
+            if (!existsSync(logFile)) {
+                return { content: [{ type: "text", text: "No heartbeat log found yet. The platform cron may not have run." }] };
+            }
+            const result = execFileSync("tail", ["-n", String(lines), logFile], {
+                timeout: 5000,
+            }).toString();
+            return { content: [{ type: "text", text: `# check-due-events.log\n\n${result}` }] };
+        }
+        // Server log is a single fixed file in configDir (platform-scoped, not account-scoped)
+        if (resolvedType === "server") {
+            const serverLog = resolve(CONFIG_DIR, "logs", "server.log");
+            if (!existsSync(serverLog)) {
+                return { content: [{ type: "text", text: `No server log found at ${serverLog}` }] };
+            }
+            const result = execFileSync("tail", ["-n", String(lines), serverLog], {
+                timeout: 5000,
+            }).toString();
+            return { content: [{ type: "text", text: `# server.log\n\n${result}` }] };
+        }
+        // VNC log is a single platform-scoped file covering the full
+        // browser viewer lifecycle — see tool description for signals.
+        if (resolvedType === "vnc") {
+            const vncLogFile = resolve(CONFIG_DIR, "logs", "vnc-boot.log");
+            if (!existsSync(vncLogFile)) {
+                return { content: [{ type: "text", text: `No vnc-boot log found at ${vncLogFile}` }] };
+            }
+            const result = execFileSync("tail", ["-n", String(lines), vncLogFile], {
+                timeout: 5000,
+            }).toString();
+            return { content: [{ type: "text", text: `# vnc-boot.log\n\n${result}` }] };
+        }
+        // Task 850 — agent-stream and the legacy system alias both map to
+        // claude-agent-stream-. The fall-through default also covers them.
+        const prefix = resolvedType === "error" ? "claude-agent-stderr-"
+            : resolvedType === "session" ? "sse-events-"
+                : resolvedType === "public" ? "public-agent-stream-"
+                    : resolvedType === "mcp" ? "mcp-"
+                        : "claude-agent-stream-";
+        // Find the most recently modified file with the matching prefix
+        const match = readdirSync(LOG_DIR)
+            .filter(f => f.startsWith(prefix) && f.endsWith(".log"))
+            .map(f => ({ file: f, mtime: statSync(resolve(LOG_DIR, f)).mtimeMs }))
+            .sort((a, b) => b.mtime - a.mtime)[0];
+        if (!match) {
+            return { content: [{ type: "text", text: `No log file found for type '${resolvedType}' in ${LOG_DIR}` }] };
+        }
+        const logFile = resolve(LOG_DIR, match.file);
+        const result = execFileSync("tail", ["-n", String(lines), logFile], {
+            timeout: 5000,
+        }).toString();
+        return { content: [{ type: "text", text: `# ${match.file}\n\n${result}` }] };
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Failed to read logs: ${err instanceof Error ? err.message : String(err)}` }] };
+    }
+});
+// Task 918 — operator-authored skills are written to disk as a plugin so the
+// existing plugin-manifest loader picks them up (parsePluginFrontmatter +
+// assemblePublicPluginContent + loadEmbeddedPlugins all read from
+// <PLATFORM_ROOT>/plugins/<dir>/). Canonical = <accountDir>/plugins/<plugin>
+// survives installer rmSync (data/ excluded); the mirror under
+// <PLATFORM_ROOT>/plugins/<plugin> is rehydrated at admin session start by
+// autoDeliverUserPlugins. The agent supplies pluginName/skillName/body —
+// path is computed by this tool from ACCOUNT_ID. Symmetric write counterpart
+// to plugin-read (Task 916).
+eagerTool(server, "store-skill", "Save an operator-authored skill on disk as part of an admin-managed plugin. " +
+    "The skill becomes immediately discoverable by the admin agent (and the public agent if publicEmbed=true). " +
+    "Path is computed internally from the active account; the agent supplies content + names only. " +
+    "Re-running for the same skillName overwrites in place (drops orphan reference files).", {
+    pluginName: z.string().describe("Plugin directory name in lowercase kebab-case (e.g. 'beacons-skills'). Must not collide with a shipped plugin name."),
+    skillName: z.string().describe("Skill directory name in lowercase kebab-case (e.g. 'lead-capture')."),
+    description: z.string().describe("One-sentence skill description used in SKILL.md frontmatter and as the trigger hint for the agent."),
+    publicEmbed: z.boolean().describe("True to embed this skill in the public agent's system prompt; false for admin-only."),
+    body: z.string().describe("SKILL.md body content WITHOUT frontmatter. Frontmatter (name, description, publicEmbed) is composed by the tool."),
+    references: z.array(z.object({
+        filename: z.string().describe("Reference filename matching ^[a-z0-9-]+\\.md$ (no path separators)."),
+        content: z.string().describe("Reference file body content."),
+    })).default([]).describe("Optional reference files written under skills/<skillName>/references/."),
+}, async ({ pluginName, skillName, description, publicEmbed, body, references }) => {
+    const KEBAB_RE = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+    const REF_RE = /^[a-z0-9-]+\.md$/;
+    if (!KEBAB_RE.test(pluginName)) {
+        console.error(`[store-skill] ERROR pluginName=${pluginName} reason=invalid-kebab path=-`);
+        return { content: [{ type: "text", text: `pluginName must be lowercase kebab-case (1-64 chars, no leading/trailing hyphen): "${pluginName}"` }], isError: true };
+    }
+    if (!KEBAB_RE.test(skillName)) {
+        console.error(`[store-skill] ERROR pluginName=${pluginName} skillName=${skillName} reason=invalid-kebab path=-`);
+        return { content: [{ type: "text", text: `skillName must be lowercase kebab-case (1-64 chars, no leading/trailing hyphen): "${skillName}"` }], isError: true };
+    }
+    for (const ref of references) {
+        if (!REF_RE.test(ref.filename)) {
+            console.error(`[store-skill] ERROR pluginName=${pluginName} skillName=${skillName} reason=invalid-ref-filename ref=${ref.filename} path=-`);
+            return { content: [{ type: "text", text: `reference filename must match ^[a-z0-9-]+\\.md$: "${ref.filename}"` }], isError: true };
+        }
+    }
+    const accountDir = getAccountDir();
+    const canonicalPluginDir = resolve(accountDir, "plugins", pluginName);
+    const mirrorPluginDir = resolve(PLATFORM_ROOT, "plugins", pluginName);
+    const canonicalPluginMd = resolve(canonicalPluginDir, "PLUGIN.md");
+    const mirrorPluginMd = resolve(mirrorPluginDir, "PLUGIN.md");
+    // Collision: mirror dir exists from a shipped plugin (no canonical mirror).
+    // Refuse rather than silently shadow.
+    if (existsSync(mirrorPluginMd) && !existsSync(canonicalPluginMd)) {
+        console.error(`[store-skill] ERROR pluginName=${pluginName} skillName=${skillName} reason=collision-with-shipped path=${mirrorPluginDir}`);
+        return { content: [{ type: "text", text: `pluginName "${pluginName}" collides with a shipped plugin. Choose a different pluginName.` }], isError: true };
+    }
+    const skillDir = resolve(canonicalPluginDir, "skills", skillName);
+    const action = existsSync(resolve(skillDir, "SKILL.md")) ? "overwrite" : "create";
+    try {
+        mkdirSync(canonicalPluginDir, { recursive: true });
+        // Compose PLUGIN.md only on first write. embed=["admin","public"] +
+        // optional=false matches assemblePublicPluginContent / loadEmbeddedPlugins
+        // expectations. metadata is single-line JSON (parsePluginFrontmatter at
+        // plugin-manifest.ts:67 expects single-line) — multi-line silently falls
+        // back to platform={}.
+        if (!existsSync(canonicalPluginMd)) {
+            const pluginMd = `---
+name: ${pluginName}
+description: "Operator-authored plugin"
+tools: []
+hidden: []
+requires: []
+metadata: {"platform":{"embed":["admin","public"],"optional":false}}
+---
+
+# ${pluginName}
+
+Operator-authored plugin. Skills under \`skills/\` were created via the admin skill-builder.
+`;
+            writeFileSync(canonicalPluginMd, pluginMd);
+        }
+        // Reset skill dir before write so removed reference files don't linger.
+        if (existsSync(skillDir)) {
+            rmSync(skillDir, { recursive: true, force: true });
+        }
+        mkdirSync(skillDir, { recursive: true });
+        // Normalise description — strip newlines and tabs to keep YAML
+        // frontmatter on a single line. parsePluginFrontmatter uses a
+        // single-line regex; an embedded newline (or `\n---\n`) would
+        // otherwise corrupt the frontmatter parse and silently drop body
+        // content from the agent prompt.
+        const singleLineDescription = description.replace(/[\r\n\t]+/g, " ").trim();
+        const escapedDescription = singleLineDescription.replace(/"/g, '\\"');
+        const skillMd = `---
+name: ${skillName}
+description: "${escapedDescription}"
+publicEmbed: ${publicEmbed}
+---
+
+${body}
+`;
+        writeFileSync(resolve(skillDir, "SKILL.md"), skillMd);
+        let refCount = 0;
+        if (references.length > 0) {
+            const refsDir = resolve(skillDir, "references");
+            mkdirSync(refsDir, { recursive: true });
+            for (const ref of references) {
+                writeFileSync(resolve(refsDir, ref.filename), ref.content);
+                refCount++;
+            }
+        }
+        // Write the `.user-mirror` marker to CANONICAL first — cpSync will
+        // carry it into the platform-side mirror as part of the same recursive
+        // copy. This eliminates the post-cpSync writeFileSync race: if cpSync
+        // succeeds, the marker is already in target; if cpSync fails partway,
+        // canonical's marker is intact and the next autoDeliverUserPlugins
+        // call retries the copy. autoDeliverUserPlugins relies on the marker
+        // arriving with the source tree — never writes its own marker.
+        writeFileSync(resolve(canonicalPluginDir, ".user-mirror"), `pluginName=${pluginName}\nsource=${canonicalPluginDir}\n`);
+        // Mirror to <PLATFORM_ROOT>/plugins/<pluginName>/ so the change is
+        // visible to the loader without a session restart.
+        mkdirSync(mirrorPluginDir, { recursive: true });
+        cpSync(canonicalPluginDir, mirrorPluginDir, { recursive: true, force: true });
+        const bodyBytes = Buffer.byteLength(body, "utf-8");
+        console.log(`[store-skill] write pluginName=${pluginName} skillName=${skillName} publicEmbed=${publicEmbed} path=${canonicalPluginDir} bodyBytes=${bodyBytes} referenceCount=${refCount} action=${action}`);
+        return {
+            content: [{
+                    type: "text",
+                    text: `Skill "${skillName}" saved to plugin "${pluginName}" (${action}). publicEmbed=${publicEmbed}, references=${refCount}. Active immediately for the admin agent${publicEmbed ? "; surfaces in the public agent on next session start" : ""}.`,
+                }],
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`[store-skill] ERROR pluginName=${pluginName} skillName=${skillName} reason=${msg.slice(0, 120)} path=${canonicalPluginDir}`);
+        return { content: [{ type: "text", text: `Failed to write skill: ${msg}` }], isError: true };
+    }
+});
+eagerTool(server, "plugin-read", "Read a plugin definition (PLUGIN.md) or one of its reference files.", {
+    pluginName: z.string().describe("Name of the plugin directory (e.g. 'sales', 'business-assistant')"),
+    file: z.string().optional().describe("Specific file to read (e.g. 'references/pricing.md'). Defaults to PLUGIN.md."),
+}, async ({ pluginName, file }) => {
+    try {
+        const resolvedFile = file ?? "PLUGIN.md";
+        const pluginPath = resolve(PLATFORM_ROOT, "plugins", pluginName, resolvedFile);
+        if (!existsSync(pluginPath)) {
+            // Task 964/1000 — when the agent's pluginName/file combination misses
+            // a skill that DOES live under `plugins/*/skills/<slug>/SKILL.md`,
+            // surface the corrected pluginName AND the canonical file path so
+            // the next call is deterministic. Both wrong-`file` and wrong-`pluginName`
+            // shapes feed through `computePluginReadHint`.
+            const hint = computePluginReadHint(PLATFORM_ROOT, pluginName, resolvedFile);
+            const hintText = hint ? ` Did you mean pluginName="${hint.pluginName}", file="${hint.file}"?` : "";
+            console.log(`[plugin-read] ${pluginName}/${resolvedFile} not-found hint=${hint ? hint.pluginName : "none"}`);
+            return {
+                content: [{ type: "text", text: `Plugin file not found: ${pluginPath}.${hintText}` }],
+                isError: true,
+            };
+        }
+        console.log(`[plugin-read] ${pluginName}/${resolvedFile}`);
+        const rawContent = await readFile(pluginPath, "utf-8");
+        // Brand-substitute every plugin file before it reaches the agent —
+        // PLUGIN.md, skills/<name>/SKILL.md, references/*.md all flow through
+        // here. Missing brand.json hard-throws (Tasks 787/788 doctrine).
+        const content = substituteBrandPlaceholders(rawContent, pluginPath);
+        // Append file inventory on default calls (PLUGIN.md) so agents can discover
+        // skill and reference paths without guessing
+        if (resolvedFile === "PLUGIN.md") {
+            const pluginRoot = resolve(PLATFORM_ROOT, "plugins", pluginName);
+            const skills = [];
+            const references = [];
+            const scanDir = (base, prefix, target) => {
+                const scanPath = resolve(pluginRoot, base);
+                if (!existsSync(scanPath))
+                    return;
+                try {
+                    const walk = (current, rel) => {
+                        for (const entry of readdirSync(current)) {
+                            const full = resolve(current, entry);
+                            try {
+                                const stat = statSync(full);
+                                if (stat.isDirectory()) {
+                                    walk(full, `${rel}${entry}/`);
+                                }
+                                else if (entry.endsWith(".md")) {
+                                    target.push(`${prefix}${rel}${entry}`);
+                                }
+                            }
+                            catch { /* skip unreadable entries */ }
+                        }
+                    };
+                    walk(scanPath, "");
+                }
+                catch { /* skip unreadable directories */ }
+            };
+            scanDir("skills", "skills/", skills);
+            scanDir("references", "references/", references);
+            let inventory = "";
+            if (skills.length > 0)
+                inventory += `\nSkills: ${skills.join(", ")}`;
+            if (references.length > 0)
+                inventory += `\nReferences: ${references.join(", ")}`;
+            return { content: [{ type: "text", text: content + inventory }] };
+        }
+        return { content: [{ type: "text", text: content }] };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Failed: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+});
+// Task 964 — agent-side `Glob` fallthrough when "set up cloudflare" maps a
+// SKILL.md to the wrong plugin: skill-find walks
+// `${PLATFORM_ROOT}/plugins/*/skills/<skillName>/SKILL.md` once and returns
+// the owner. With one tool call the agent learns the correct plugin name.
+//
+// Task 1015 — `skill-load` (below) is the canonical single-call surface that
+// most agents want (resolve + read body in one shot). `skill-find` is kept
+// for callers that need only the path (e.g. tooling that lists owners
+// without reading the body).
+server.tool("skill-find", "Find which plugin owns a skill by name. Walks plugins/*/skills/<skillName>/SKILL.md and returns the owning plugin (unique), every candidate (ambiguous), or not-found. For the common resolve-and-read case, prefer `skill-load skillName=<name>` — it returns the SKILL.md body in the same call.", {
+    skillName: z.string().regex(/^[a-z0-9][a-z0-9-]*$/, "skillName must be lowercase kebab-case (a-z, 0-9, -)"),
+}, async ({ skillName }) => {
+    const start = Date.now();
+    const result = findSkillOwners(PLATFORM_ROOT, skillName);
+    const ms = Date.now() - start;
+    console.log(`[skill-find] skillName=${skillName} result=${result.status} candidates=${result.candidates.length} ms=${ms}`);
+    if (result.status === "unique") {
+        const [{ pluginName, file }] = result.candidates;
+        return {
+            content: [{
+                    type: "text",
+                    text: `pluginName="${pluginName}" file="${file}"\nTo read the body in one call, use: skill-load skillName="${skillName}"`,
+                }],
+        };
+    }
+    if (result.status === "ambiguous") {
+        const lines = result.candidates.map(c => `  pluginName="${c.pluginName}" file="${c.file}"`).join("\n");
+        return {
+            content: [{
+                    type: "text",
+                    text: `Ambiguous — skill "${skillName}" exists in ${result.candidates.length} plugins:\n${lines}`,
+                }],
+        };
+    }
+    return {
+        content: [{ type: "text", text: `not_found — no plugin owns a skill named "${skillName}"` }],
+        isError: true,
+    };
+});
+// Task 1015 — `skill-load` collapses skill resolve+read into one call.
+//
+// Why: 21 prose call sites previously said *"Load `admin/skills/plainly/SKILL.md`
+// via `plugin-read`"*. The LLM kept passing the path as `pluginName`, tripping
+// the not-found branch with the corrected-pluginName hint that Task 1000 added.
+// The recurring failure is recorded in the corrections ledger. One slug-arg
+// tool removes the path-format ambiguity at the source.
+//
+// Shape mirrors `plugin-read` (eagerTool registration, same brand-substitution
+// call) so SKILL.md bodies are byte-identical regardless of which tool reads
+// them. `plugin-read` is retained for `references/*` and `PLUGIN.md` reads —
+// those are plugin-scoped by nature and the path-as-pluginName failure pattern
+// is specific to skills (addressed by slug in prose).
+eagerTool(server, "skill-load", "Load a plugin skill's SKILL.md body by skill name. One call: resolves the owning plugin and reads the body, with brand placeholders substituted. Returns the SKILL.md body when exactly one plugin owns the skill, a candidate list when multiple plugins own it (ambiguous), or an error when no plugin owns it.", {
+    skillName: z.string().regex(/^[a-z0-9][a-z0-9-]*$/, "skillName must be lowercase kebab-case (a-z, 0-9, -)"),
+}, async ({ skillName }) => {
+    const start = Date.now();
+    try {
+        const outcome = await loadSkill(PLATFORM_ROOT, skillName);
+        if (outcome.status === "ambiguous") {
+            const ms = Date.now() - start;
+            console.log(`[skill-load] skillName=${skillName} result=ambiguous pluginName=none file=none bodyBytes=0 ms=${ms}`);
+            const lines = outcome.candidates.map(c => `  pluginName="${c.pluginName}" file="${c.file}"`).join("\n");
+            return {
+                content: [{
+                        type: "text",
+                        text: `Ambiguous — skill "${skillName}" exists in ${outcome.candidates.length} plugins:\n${lines}\nUse plugin-read with one of the listed pluginName/file pairs.`,
+                    }],
+                isError: true,
+            };
+        }
+        if (outcome.status === "not-found") {
+            const ms = Date.now() - start;
+            console.log(`[skill-load] skillName=${skillName} result=not-found pluginName=none file=none bodyBytes=0 ms=${ms}`);
+            return {
+                content: [{ type: "text", text: `not_found — no plugin owns a skill named "${skillName}"` }],
+                isError: true,
+            };
+        }
+        const content = substituteBrandPlaceholders(outcome.body, outcome.absolutePath);
+        // Task 1021 — prepend a skill-input-contract notice when the skill's
+        // frontmatter declares `requiredInputs:`. The notice tells the agent
+        // to route missing inputs through AskUserQuestion (per IDENTITY.md
+        // "Skill-input resolution"); the embedded `<!-- skill-input-contract
+        // requiredInputs=... -->` marker is the per-turn keying signal that
+        // parseClaudeStream uses to fire [skill-input-resolution] /
+        // [skill-input-missing] observability lines.
+        const requiredInputs = parseRequiredInputs(outcome.body);
+        let bodyOut = content;
+        if (requiredInputs) {
+            const slotLabels = requiredInputs.map(s => s.join(" | ")).join(", ");
+            const marker = JSON.stringify(requiredInputs);
+            const notice = `<!-- skill-input-contract requiredInputs=${marker} -->\nREQUIRED INPUTS: ${slotLabels}\nIf the operator has not supplied each of these inputs, your next tool call MUST be AskUserQuestion. Do not use memory-search, conversation-search, graph-read, or task-get to guess the missing input.\n<!-- /skill-input-contract -->\n\n`;
+            bodyOut = notice + content;
+        }
+        const ms = Date.now() - start;
+        const reqLog = requiredInputs ? ` requiredInputs=${JSON.stringify(requiredInputs)}` : "";
+        console.log(`[skill-load] skillName=${skillName} result=unique pluginName=${outcome.pluginName} file=${outcome.file} bodyBytes=${bodyOut.length}${reqLog} ms=${ms}`);
+        return { content: [{ type: "text", text: bodyOut }] };
+    }
+    catch (err) {
+        const ms = Date.now() - start;
+        console.log(`[skill-load] skillName=${skillName} result=read-error pluginName=unknown file=unknown bodyBytes=0 ms=${ms}`);
+        return {
+            content: [{ type: "text", text: `Failed to load skill "${skillName}": ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+});
+// Task 940 — `"rendered"` is a sentinel, not a persistence ack. The platform
+// UI's stream-parser intercepts this tool_use upstream of the SDK reply
+// (platform/ui/app/lib/claude-agent/stream-parser.ts:362) and emits a typed
+// `component` event that admin-agent.ts's persistMessage flushes to Neo4j as
+// a sibling :Component node.
+//
+// Task 942 — render-component is also the *server commitment surface* for
+// PERSISTENT_COMPONENTS (action-list, document-editor, rich-content-editor,
+// grid-editor). The actual file write + :KnowledgeDocument projection lives
+// in the admin server process (stream-parser path) because the SDK delivers
+// `tool_use.input` to the UI in the assistant message but the MCP handler's
+// return reaches only the agent — there is no path back to persistMessage
+// from here. This handler emits a one-line observability marker per
+// persistence-eligible call so operators can grep for the commitment, and
+// returns richer JSON so the doctrine grep
+// `render-component.*"rendered"` resolves to a persistence-aware handler
+// rather than a bare stub.
+eagerTool(server, "render-component", "Render a pre-built UI component inline in the conversation. " +
+    "Call this instead of describing a UI — the component handles input collection. " +
+    "Wait for the user's response before continuing.", {
+    name: z.string().describe("Component name from the UI suite (e.g. single-select, confirm, info-card, form, progress)"),
+    data: z.record(z.string(), z.unknown()),
+}, async ({ name, data }) => {
+    if (isPersistentComponent(name)) {
+        // Persistence-eligible: log the commitment so the live + audit grep
+        // (`[render-component-persist]`) can correlate the MCP call against
+        // the downstream :KnowledgeDocument MERGE. Byte counts come from
+        // data.html (preferred) or data.content; both being absent is a
+        // legitimate render of an empty editor and the projection is skipped
+        // server-side.
+        const html = typeof data?.html === "string" ? data.html : "";
+        const content = typeof data?.content === "string" ? data.content : "";
+        const bytes = html.length > 0 ? html.length : content.length;
+        const mimeType = html.length > 0 ? "text/html" : (content.length > 0 ? "text/markdown" : "");
+        console.error(`[render-component-persist] componentName=${name} bytes=${bytes} mimeType=${mimeType || "none"}`);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({ rendered: true, name, persistent: true, bytes, mimeType }),
+                }],
+        };
+    }
+    return { content: [{ type: "text", text: "rendered" }] };
+});
+eagerTool(server, "session-reset", "Reset the current session. Compacts conversation history to memory, clears the visible conversation, " +
+    "and starts a fresh session with a new greeting. Call when the user asks to start a new session, " +
+    "clear the conversation, or start fresh.", {}, async () => ({ content: [{ type: "text", text: "reset" }] }));
+eagerTool(server, "session-resume", "Resume a previous session. Loads the selected session's message history into the chat timeline " +
+    "and routes new messages to that conversation. Call after the user selects a session from the " +
+    "session-list results. Pass the conversationId from the selected session.", { conversationId: z.string().uuid().describe("The conversationId of the session to resume") }, async () => ({ content: [{ type: "text", text: "resumed" }] }));
+server.tool("remote-auth-set-password", "Set the remote access password. Hashes with scrypt and writes to the platform's brand-specific config directory with mode 0600. " +
+    "Validates strength (8+ chars, digit, special character, no spaces anywhere). " +
+    "Protects the admin interface when exposed over the tunnel — has no effect on the public endpoint or the tunnel itself. " +
+    "Set before `setup-tunnel.sh` — the script's post-restart verification curls the admin hostname and fails if remote-auth is not configured.", { password: z.string() }, async ({ password }) => {
+    // Validate strength — same rules as the web server's validatePasswordStrength
+    const checks = [
+        { label: "at least 8 characters", met: password.length >= 8 },
+        { label: "contains a number", met: /\d/.test(password) },
+        { label: "contains a special character", met: /[^A-Za-z0-9]/.test(password) },
+        { label: "no spaces", met: password.length > 0 && !/\s/.test(password) },
+    ];
+    const failed = checks.filter((c) => !c.met);
+    if (failed.length > 0) {
+        return {
+            content: [{ type: "text", text: `Password requirements not met: ${failed.map((c) => c.label).join(", ")}` }],
+            isError: true,
+        };
+    }
+    try {
+        const { scrypt, randomBytes } = await import("node:crypto");
+        const salt = randomBytes(32);
+        const hash = await new Promise((res, rej) => {
+            scrypt(password, salt, 64, { N: 16384, r: 8, p: 1 }, (err, key) => {
+                if (err)
+                    rej(err);
+                else
+                    res(key);
+            });
+        });
+        const stored = `${salt.toString("hex")}:${hash.toString("hex")}`;
+        const pwPath = REMOTE_PASSWORD_FILE;
+        await writeFile(pwPath, stored, { mode: 0o600 });
+        return { content: [{ type: "text", text: "Remote access password set." }] };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Failed to set password: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+});
+eagerTool(server, "api-key-store", "Validate and store an Anthropic API key. Key must start with sk-ant- and be at least 90 characters. " +
+    "Writes to the platform's brand-specific config directory. Takes effect immediately for the public agent.", { apiKey: z.string() }, async ({ apiKey }) => {
+    try {
+        writeKey(apiKey);
+        return { content: [{ type: "text", text: `API key stored at ${keyFilePath()}.` }] };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }],
+            isError: true,
+        };
+    }
+});
+eagerTool(server, "api-key-verify", "Verify the stored Anthropic API key works by making a minimal probe call. " +
+    "Returns one of: valid (key works, credits available), billing (key valid but credit balance too low — " +
+    "user must add credits at console.anthropic.com/settings/billing), auth_error (key rejected — invalid or revoked), " +
+    "missing (no key file found), error (could not verify — network issue or Anthropic outage). " +
+    "Call this on greeting, during system checks, or after storing a new key.", {}, async () => {
+    const result = await validateKey();
+    return {
+        content: [{
+                type: "text",
+                text: `Status: ${result.status}\n${result.message}`,
+            }],
+    };
+});
+// ===================================================================
+// Anthropic setup — deterministic state machine
+// ===================================================================
+/*
+ * anthropic-setup state machine (action-relay pattern)
+ *
+ * Call 1: anthropic-setup({})
+ *   ├─ no public endpoint   → { status: "not_needed" }   ← Phase 0 gate
+ *   ├─ key stored + valid?  → { status: "complete" }
+ *   ├─ key stored + billing → { status: "awaiting_credits" }
+ *   ├─ key stored + error   → { status: "error" }
+ *   └─ no key               → { status: "awaiting_signin", action }
+ *
+ * Call 2: anthropic-setup({ consoleResult: "..." })
+ *   ├─ no_session  → { status: "awaiting_signin", action }
+ *   ├─ no_org      → { status: "error" }
+ *   ├─ no_credits  → { status: "awaiting_credits", action }
+ *   ├─ success     → writeKey → validateKey → { status: "complete" }
+ *   └─ *_failed    → { status: "error" }
+ */
+const CONSOLE_BASE = "https://platform.claude.com";
+/**
+ * JavaScript expression for browser_evaluate that runs the complete
+ * Console API pipeline in one call: check session → find API org →
+ * check credits → create key. Returns a structured JSON result.
+ */
+function consoleEvaluateExpression(keyName) {
+    return `async () => {
+  try {
+    const orgsRes = await fetch("/api/organizations", { credentials: "include" });
+    if (orgsRes.status === 401 || orgsRes.status === 403) {
+      return JSON.stringify({ status: "no_session" });
+    }
+    if (!orgsRes.ok) {
+      return JSON.stringify({ status: "fetch_error", error: "organizations: " + orgsRes.status });
+    }
+    const orgs = await orgsRes.json();
+    const apiOrg = orgs.find(o => o.capabilities && o.capabilities.includes("api"));
+    if (!apiOrg) {
+      return JSON.stringify({ status: "no_org" });
+    }
+    const creditsRes = await fetch("/api/organizations/" + apiOrg.uuid + "/prepaid/credits", { credentials: "include" });
+    if (!creditsRes.ok) {
+      return JSON.stringify({ status: "fetch_error", error: "credits: " + creditsRes.status });
+    }
+    const credits = await creditsRes.json();
+    if (typeof credits.amount === "number" && credits.amount <= 0) {
+      return JSON.stringify({ status: "no_credits", orgId: apiOrg.uuid, orgName: apiOrg.name, creditUrl: "${CONSOLE_BASE}/settings/billing" });
+    }
+    const createRes = await fetch("/api/console/organizations/" + apiOrg.uuid + "/workspaces/default/api_keys", {
+      method: "POST",
+      credentials: "include",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ name: ${JSON.stringify(keyName)} })
+    });
+    if (!createRes.ok) {
+      return JSON.stringify({ status: "create_failed", error: "key creation: " + createRes.status });
+    }
+    const keyData = await createRes.json();
+    if (!keyData.raw_key) {
+      return JSON.stringify({ status: "create_failed", error: "no raw_key in response" });
+    }
+    return JSON.stringify({
+      status: "success",
+      key: keyData.raw_key,
+      keyId: keyData.id,
+      keyHint: keyData.partial_key_hint,
+      orgName: apiOrg.name,
+      credits: credits.amount
+    });
+  } catch (err) {
+    return JSON.stringify({ status: "fetch_error", error: String(err) });
+  }
+}`;
+}
+function anthropicResult(r) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(r, null, 2) }],
+        ...(r.status === "error" ? { isError: true } : {}),
+    };
+}
+/**
+ * Check whether a public-facing hostname is configured. The Anthropic API key
+ * powers the public agent only — admin runs on Claude OAuth — so without a
+ * public endpoint there is nothing for the key to power.
+ *
+ * Mirrors the runtime `isPublicHost(host)` predicate in
+ * `platform/ui/server/index.ts`: a host is public iff it starts with `public.`
+ * OR is listed in `~/{configDir}/alias-domains.json`. Step 7's form submit
+ * handler at `platform/ui/server/routes/admin/cloudflare.ts` writes secondary
+ * hostnames (apex + custom public labels) to `alias-domains.json` and skips
+ * `public.*` because the prefix itself is the signal — so the two predicates
+ * together cover every shape the form can produce.
+ *
+ * Returns true if any configured hostname satisfies either predicate.
+ */
+function hasPublicEndpointConfigured() {
+    const aliasPath = join(CONFIG_DIR, "alias-domains.json");
+    if (existsSync(aliasPath)) {
+        try {
+            const parsed = JSON.parse(readFileSync(aliasPath, "utf-8"));
+            if (Array.isArray(parsed)) {
+                const entries = parsed.filter((h) => typeof h === "string" && h.length > 0);
+                if (entries.length > 0) {
+                    return { has: true, reason: `alias-domains.json: ${entries.join(", ")}` };
+                }
+            }
+        }
+        catch {
+            // Malformed file — treat as empty; matches the server-side reader's tolerance.
+        }
+    }
+    const cfConfigPath = join(CONFIG_DIR, "cloudflared", "config.yml");
+    if (existsSync(cfConfigPath)) {
+        try {
+            const yaml = readFileSync(cfConfigPath, "utf-8");
+            const hostnames = [...yaml.matchAll(/^\s*-\s*hostname:\s*(\S+)/gm)].map((m) => m[1]);
+            const publicPrefixed = hostnames.find((h) => h.startsWith("public."));
+            if (publicPrefixed) {
+                return { has: true, reason: `cloudflared/config.yml ingress: ${publicPrefixed}` };
+            }
+        }
+        catch {
+            // Unreadable — treat as no public host.
+        }
+    }
+    return {
+        has: false,
+        reason: "no entries in alias-domains.json and no public.* hostname in cloudflared/config.yml",
+    };
+}
+eagerTool(server, "anthropic-setup", "Deterministic state machine for Anthropic API key acquisition. " +
+    "Checks current state, advances as far as possible, and returns a structured JSON result. " +
+    "On first call (no consoleResult): first verifies a public-facing endpoint is configured " +
+    "(the key only powers the public agent); if not, returns status 'not_needed'. Otherwise " +
+    "checks if a valid key is already stored. If not, returns status 'awaiting_signin' with " +
+    "a browser_evaluate action — the agent must open the browser to platform.claude.com, run " +
+    "the action's function via browser_evaluate, and pass the string result back as " +
+    "consoleResult on the next call. " +
+    "On second call (with consoleResult): parses the Console API result, stores the key, " +
+    "verifies it, and returns status 'complete'. " +
+    "Statuses: complete (key stored and verified), not_needed (no public endpoint configured — " +
+    "skip the step), awaiting_signin (user must sign in to Console), awaiting_credits (signed in " +
+    "but no credits — user must add credits), error (fatal — relay message).", {
+    consoleResult: z.string().optional().describe("JSON string result from running the browser_evaluate action returned by a prior call. " +
+        "Omit on the first call."),
+}, async ({ consoleResult }) => {
+    const log = (msg) => console.error(`[anthropic-setup] ${msg}`);
+    // ── Phase 0: gate on public endpoint existence ─────────────
+    // The API key only powers the public-facing agent. If no public hostname
+    // is configured (operator skipped step 7, or completed it without a
+    // public/apex hostname) the key has no consumer — short-circuit before
+    // any Console interaction so we never create keys the operator cannot use.
+    if (!consoleResult) {
+        const publicCheck = hasPublicEndpointConfigured();
+        if (!publicCheck.has) {
+            log(`gate: no public endpoint (${publicCheck.reason}) — returning not_needed`);
+            return anthropicResult({
+                status: "not_needed",
+                message: "No public-facing endpoint is configured, so an Anthropic API key is not needed. " +
+                    "The key powers the public agent only — admin runs on your Claude OAuth session. " +
+                    "When you set up a public hostname via Cloudflare (or apex domain), come back and " +
+                    "ask to set up the API key then.",
+            });
+        }
+        log(`gate: public endpoint present (${publicCheck.reason})`);
+    }
+    // ── Phase 1: check stored key ──────────────────────────────
+    if (!consoleResult) {
+        log("checking stored key");
+        if (hasKey()) {
+            const verification = await validateKey();
+            log(`stored key verification: ${verification.status}`);
+            switch (verification.status) {
+                case "valid":
+                    log("key valid, returning complete");
+                    return anthropicResult({
+                        status: "complete",
+                        message: `API key is stored and working. Key file: ${keyFilePath()}.`,
+                    });
+                case "billing":
+                    log("key valid but billing issue");
+                    return anthropicResult({
+                        status: "awaiting_credits",
+                        message: "API key is stored and valid, but your account has insufficient credits. " +
+                            `Add credits at ${CONSOLE_BASE}/settings/billing, then call this tool again.`,
+                        data: { url: `${CONSOLE_BASE}/settings/billing` },
+                    });
+                case "auth_error":
+                    // Deterministic transition: the state machine knows the key file
+                    // path and the only recovery is to delete and restart sign-in.
+                    // Auto-reset here so the agent never has to rediscover the path
+                    // via filesystem probes.
+                    log(`auth_error → auto-resetting: deleting revoked key at ${keyFilePath()}`);
+                    try {
+                        deleteKey();
+                    }
+                    catch (err) {
+                        const msg = err instanceof Error ? err.message : String(err);
+                        log(`auto-reset failed: ${msg}`);
+                        return anthropicResult({
+                            status: "error",
+                            message: `The stored API key was rejected and auto-reset failed: ${msg}. ` +
+                                `Manual intervention needed — remove ${keyFilePath()} and call this tool again.`,
+                        });
+                    }
+                    // Fall through to the awaiting_signin path below.
+                    break;
+                case "missing":
+                    // hasKey() returned true but readKey() returned null — shouldn't happen
+                    log("hasKey true but validate returned missing — proceeding to setup");
+                    break;
+                case "error":
+                    log(`verification failed: ${verification.message}`);
+                    return anthropicResult({
+                        status: "error",
+                        message: `Could not verify the stored key: ${verification.message}. ` +
+                            "This may be a network issue or Anthropic outage. Try again later.",
+                    });
+            }
+        }
+        else {
+            log("no key stored");
+        }
+        // No valid key — return action for Console API calls
+        const expression = consoleEvaluateExpression(BRAND_NAME);
+        log("returning awaiting_signin with browser_evaluate action");
+        return anthropicResult({
+            status: "awaiting_signin",
+            message: "No valid API key stored. Open the browser to the Anthropic Console " +
+                `(${CONSOLE_BASE}) and sign in. This is a separate service from Claude — ` +
+                "you may need to sign in again even if you used the same credentials earlier. " +
+                "Once signed in, run the browser_evaluate action below, then call this tool " +
+                "again with the result as consoleResult.",
+            data: {
+                url: CONSOLE_BASE,
+                action: {
+                    tool: "browser_evaluate",
+                    params: { function: expression },
+                },
+            },
+        });
+    }
+    // ── Phase 2: process Console API result ────────────────────
+    log("processing consoleResult");
+    let parsed;
+    try {
+        parsed = JSON.parse(consoleResult);
+    }
+    catch {
+        log(`consoleResult parse failed: ${consoleResult.slice(0, 200)}`);
+        return anthropicResult({
+            status: "error",
+            message: "Failed to parse the browser result. The Console session may have " +
+                "been lost or the browser encountered an error. Please try again — " +
+                "open the browser to platform.claude.com, sign in, and re-run the action.",
+        });
+    }
+    log(`console result status: ${parsed.status}`);
+    switch (parsed.status) {
+        case "no_session": {
+            log("no Console session — user needs to sign in");
+            const expression = consoleEvaluateExpression(BRAND_NAME);
+            return anthropicResult({
+                status: "awaiting_signin",
+                message: "Not signed in to the Anthropic Console. Please sign in at " +
+                    `${CONSOLE_BASE} and then run the browser_evaluate action below.`,
+                data: {
+                    url: CONSOLE_BASE,
+                    action: {
+                        tool: "browser_evaluate",
+                        params: { function: expression },
+                    },
+                },
+            });
+        }
+        case "no_org":
+            log("no API organization found");
+            return anthropicResult({
+                status: "error",
+                message: "No API organization found in your Anthropic account. " +
+                    "You may be signed in to a Claude consumer account instead of the API Console. " +
+                    `Sign in at ${CONSOLE_BASE} with an account that has API access.`,
+            });
+        case "no_credits": {
+            log(`no credits — org: ${parsed.orgName ?? "unknown"}`);
+            const expression = consoleEvaluateExpression(BRAND_NAME);
+            return anthropicResult({
+                status: "awaiting_credits",
+                message: `Your API organization (${parsed.orgName ?? "unknown"}) has no credits. ` +
+                    `Add credits at ${parsed.creditUrl ?? CONSOLE_BASE + "/settings/billing"}, ` +
+                    "then run the browser_evaluate action below.",
+                data: {
+                    url: parsed.creditUrl ?? `${CONSOLE_BASE}/settings/billing`,
+                    action: {
+                        tool: "browser_evaluate",
+                        params: { function: expression },
+                    },
+                },
+            });
+        }
+        case "create_failed":
+            log(`key creation failed: ${parsed.error ?? "unknown"}`);
+            return anthropicResult({
+                status: "error",
+                message: `Failed to create API key: ${parsed.error ?? "unknown error"}. ` +
+                    "This may be a permissions issue or a temporary Console error. Try again.",
+            });
+        case "fetch_error":
+            log(`fetch error: ${parsed.error ?? "unknown"}`);
+            return anthropicResult({
+                status: "error",
+                message: `Console API error: ${parsed.error ?? "unknown"}. ` +
+                    "The Console may be temporarily unavailable. Try again.",
+            });
+        case "success": {
+            if (!parsed.key) {
+                log("success status but no key in result");
+                return anthropicResult({
+                    status: "error",
+                    message: "Key creation succeeded but the key was not returned. " +
+                        "This is unexpected. Please try again.",
+                });
+            }
+            log(`key created: ${parsed.keyId ?? "unknown"} (hint: ${parsed.keyHint ?? "n/a"}) — org: ${parsed.orgName ?? "unknown"}`);
+            // Store the key — persist AFTER confirmation (sprint learning: Task 201)
+            try {
+                writeKey(parsed.key);
+                log("key stored");
+            }
+            catch (err) {
+                log(`key storage failed: ${err instanceof Error ? err.message : String(err)}`);
+                return anthropicResult({
+                    status: "error",
+                    message: `Key was created in the Console but could not be stored locally: ` +
+                        `${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+            // Verify the stored key
+            const verification = await validateKey();
+            log(`post-store verification: ${verification.status}`);
+            switch (verification.status) {
+                case "valid":
+                    log("key stored and verified");
+                    return anthropicResult({
+                        status: "complete",
+                        message: `API key created, stored at ${keyFilePath()}, and verified. ` +
+                            `Organization: ${parsed.orgName ?? "unknown"}. ` +
+                            `Credits: $${((parsed.credits ?? 0) / 100).toFixed(2)}.`,
+                    });
+                case "billing":
+                    log("key stored but billing issue on verification");
+                    return anthropicResult({
+                        status: "awaiting_credits",
+                        message: "API key created and stored, but your account has insufficient credits. " +
+                            `Add credits at ${CONSOLE_BASE}/settings/billing, then verify the key with api-key-verify.`,
+                        data: { url: `${CONSOLE_BASE}/settings/billing` },
+                    });
+                default:
+                    log(`unexpected verification status after store: ${verification.status} — ${verification.message}`);
+                    return anthropicResult({
+                        status: "error",
+                        message: `Key was stored but verification returned: ${verification.status}. ` +
+                            `${verification.message}. Try running api-key-verify manually.`,
+                    });
+            }
+        }
+        default:
+            log(`unknown console result status: ${parsed.status}`);
+            return anthropicResult({
+                status: "error",
+                message: `Unexpected result from Console: status "${parsed.status}". ` +
+                    "Please try again.",
+            });
+    }
+});
+// ===================================================================
+// Onboarding tools
+// ===================================================================
+server.tool("onboarding-get", "Read the current onboarding state from the graph. Returns which setup steps " +
+    "have been completed and their timestamps. On first call for an account, " +
+    "migrates any existing onboardingStep from account.json to the graph and " +
+    "removes it from the file. If Neo4j is unreachable, returns an error — " +
+    "the agent should skip onboarding for this session and retry next time.", {}, async () => {
+    try {
+        const state = await getOnboardingState(getSession, ACCOUNT_ID, getAccountDir());
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(state, null, 2),
+                }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Failed to read onboarding state: ${err instanceof Error ? err.message : String(err)}`,
+                }],
+            isError: true,
+        };
+    }
+});
+server.tool("onboarding-complete-step", "Mark an onboarding step as completed. Sets a completion timestamp on the step " +
+    "and updates currentStep to the highest completed step. Idempotent — completing " +
+    "an already-completed step preserves its original timestamp. Step must be 1–9. " +
+    "When step is 1, optionally pass acceptedAnthropicVerticals + declinedAnthropicVerticals " +
+    "(both required together) to emit the paired counter for the [plugin-onboarding] " +
+    "group=anthropic-verticals prefix; the skill derives both arrays from the closed set " +
+    "{kyc-screener, meeting-prep-agent, pdf-viewer} and the user's submission.", {
+    step: z.number().int().min(1).max(9).describe("The onboarding step number (1–9) to mark as completed"),
+    acceptedAnthropicVerticals: z.array(z.string()).optional().describe("Step 1 only: plugin slugs the user accepted from the Anthropic verticals group. Pass together with declinedAnthropicVerticals."),
+    declinedAnthropicVerticals: z.array(z.string()).optional().describe("Step 1 only: plugin slugs the user declined from the Anthropic verticals group. Pass together with acceptedAnthropicVerticals."),
+}, async ({ step, acceptedAnthropicVerticals, declinedAnthropicVerticals }) => {
+    try {
+        const state = await completeOnboardingStep(getSession, ACCOUNT_ID, step);
+        // Task 977: closed set lives in skill prose, not server validation — a fourth vertical updates the skill.
+        if (step === 1 && acceptedAnthropicVerticals !== undefined && declinedAnthropicVerticals !== undefined) {
+            console.error(`[plugin-onboarding] group=anthropic-verticals accepted=${acceptedAnthropicVerticals.length} declined=${declinedAnthropicVerticals.length}`);
+        }
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(state, null, 2),
+                }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Failed to complete onboarding step: ${err instanceof Error ? err.message : String(err)}`,
+                }],
+            isError: true,
+        };
+    }
+});
+// Task 704: pin the operator's persona (personal/business-owner) at step 9
+// BEFORE any graph write happens. The agent calls this immediately on the
+// user's single-select submission. The tool's job is twofold:
+//   1. Emit a deterministic [onboarding-step9-mode] log line for the
+//      diagnostic-grep path on the Pi (matches [onboarding-step-complete]
+//      format — same accountId-prefix slicing, same surrounding code).
+//   2. Return the next-action prose so the agent's branching is anchored to
+//      the tool surface, not free-text inference.
+// No persistence — the graph state (LocalBusiness exists vs Person with
+// role=admin-personal exists) remains the source of truth for gate
+// satisfaction. Re-calling this tool with a different mode on the same
+// session is allowed; the most recent log line wins for diagnostic purposes.
+server.tool("onboarding-step9-mode", "Step 9 onboarding fork: record the operator's persona (personal or " +
+    "business-owner) before any graph write. Logs the choice for diagnostic " +
+    "grep and returns the deterministic next-action prose for the agent.", {
+    mode: z
+        .enum(["personal", "business-owner"])
+        .describe("The operator's persona: 'personal' for an individual using Maxy for personal operations (including someone with an employer that is NOT being registered here), or 'business-owner' for someone setting up Maxy as the operations agent for their own company."),
+}, async ({ mode }) => {
+    console.log(`[onboarding-step9-mode] accountId=${ACCOUNT_ID.slice(0, 8)}… mode=${mode}`);
+    const nextAction = mode === "business-owner"
+        ? "Invoke the `business-profile` skill to create AdminUser + LocalBusiness and capture the business identity. Mark step 9 complete only after both nodes exist in the graph."
+        : "Ask the user for their email (one sentence). Use their name from `admin-identity` in the system prompt; split into givenName + familyName. Call `memory-write` to create the AdminUser node, then call `memory-write` to create a Person node with `role: \"admin-personal\"`, the givenName, familyName, email, and an OWNS edge from the AdminUser. Then call `onboarding-complete-step` with step 9. Do not invoke the `business-profile` skill — personal mode does not register a LocalBusiness.";
+    return {
+        content: [{
+                type: "text",
+                text: JSON.stringify({ mode, nextAction }, null, 2),
+            }],
+    };
+});
+// ===================================================================
+// Utility tools
+// ===================================================================
+eagerTool(server, "qr-generate", "Generate a QR code from text or a URL. Returns the QR code as a data URI (PNG) or saves to a file path.", {
+    data: z.string().describe("The text or URL to encode in the QR code"),
+    outputPath: z
+        .string()
+        .optional()
+        .describe("File path to save the PNG. If omitted, returns a data URI."),
+    width: z.number().optional().describe("Width in pixels (default 300)"),
+}, async ({ data, outputPath, width }) => {
+    try {
+        const options = { width: width ?? 300, margin: 2 };
+        if (outputPath) {
+            await QRCode.toFile(outputPath, data, options);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `QR code saved to ${outputPath}`,
+                    },
+                ],
+            };
+        }
+        const dataUri = await QRCode.toDataURL(data, options);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `QR code generated for: ${data}`,
+                },
+                {
+                    type: "image",
+                    data: dataUri.replace(/^data:image\/png;base64,/, ""),
+                    mimeType: "image/png",
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `QR generation failed: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// ===================================================================
+// WiFi management (Task 429)
+// ===================================================================
+eagerTool(server, "wifi", "Manage WiFi connections on this device. Actions: " +
+    "scan (list visible networks with signal strength and security), " +
+    "connect (join a network by SSID and password — warn user first if signal is below 30%), " +
+    "status (current WiFi connection details), " +
+    "saved (list remembered networks), " +
+    "forget (remove a saved network — if the user is forgetting their currently active WiFi " +
+    "connection, warn them that they may lose connectivity before calling this action).", {
+    action: z.enum(["scan", "connect", "status", "saved", "forget"]).describe("The WiFi operation to perform"),
+    ssid: z.string().optional().describe("Network name — required for connect and forget actions"),
+    password: z.string().optional().describe("Network password — required for connect action (WPA/WPA2/WPA3 PSK)"),
+}, async ({ action, ssid, password }) => {
+    /** Parse nmcli terse output into rows of colon-separated fields.
+     *  nmcli -t escapes literal colons in values as \: — split on
+     *  unescaped colons only, then unescape the fields. */
+    const parseNmcliLines = (output) => output.split("\n").filter(Boolean).map((l) => l.split(/(?<!\\):/).map((f) => f.replace(/\\:/g, ":")));
+    const logPrefix = "[wifi]";
+    try {
+        switch (action) {
+            // ── scan ──────────────────────────────────────────────────
+            case "scan": {
+                const raw = execFileSync("nmcli", ["-t", "-f", "SSID,SIGNAL,SECURITY", "device", "wifi", "list", "--rescan", "yes"], { encoding: "utf-8", timeout: 15000 });
+                const lines = parseNmcliLines(raw);
+                // Filter hidden networks (empty SSID) and deduplicate by SSID
+                const seen = new Set();
+                const networks = [];
+                for (const [name, sig, sec] of lines) {
+                    if (!name || seen.has(name))
+                        continue;
+                    seen.add(name);
+                    networks.push({ ssid: name, signal: parseInt(sig, 10) || 0, security: sec || "open" });
+                }
+                // Sort by signal strength descending
+                networks.sort((a, b) => b.signal - a.signal);
+                console.error(`${logPrefix} action="scan" result="ok" networks=${networks.length}`);
+                if (networks.length === 0) {
+                    return {
+                        content: [{ type: "text", text: "No WiFi networks found. Make sure your router is powered on and within range." }],
+                    };
+                }
+                const formatted = networks
+                    .map((n) => `${n.ssid}  (${n.signal}%  ${n.security})`)
+                    .join("\n");
+                return {
+                    content: [{ type: "text", text: `# WiFi Networks\n\n${formatted}` }],
+                };
+            }
+            // ── connect ──────────────────────────────────────────────
+            case "connect": {
+                if (!ssid) {
+                    return {
+                        content: [{ type: "text", text: "SSID is required for connect action." }],
+                        isError: true,
+                    };
+                }
+                if (!password) {
+                    return {
+                        content: [{ type: "text", text: "Password is required for connect action." }],
+                        isError: true,
+                    };
+                }
+                // Check signal strength before connecting (cherry-pick 1)
+                try {
+                    const scanRaw = execFileSync("nmcli", ["-t", "-f", "SSID,SIGNAL", "device", "wifi", "list"], { encoding: "utf-8", timeout: 10000 });
+                    const scanLines = parseNmcliLines(scanRaw);
+                    const match = scanLines.find(([name]) => name === ssid);
+                    const signal = match ? parseInt(match[1], 10) || 0 : 0;
+                    if (signal > 0 && signal < 30) {
+                        // Include warning in result but proceed with connection
+                        console.error(`${logPrefix} action="connect" ssid="${ssid}" signal=${signal} warning="weak_signal"`);
+                    }
+                }
+                catch {
+                    // Scan check is best-effort — proceed with connect regardless
+                }
+                execFileSync("nmcli", ["device", "wifi", "connect", ssid, "password", password, "--wait", "30"], { encoding: "utf-8", timeout: 35000 });
+                console.error(`${logPrefix} action="connect" ssid="${ssid}" result="connecting" password=[REDACTED]`);
+                // Post-connect verification: confirm IP assignment on wlan0 (cherry-pick 2)
+                let ip = "";
+                try {
+                    const deviceInfo = execFileSync("nmcli", ["-t", "-f", "IP4.ADDRESS", "device", "show", "wlan0"], { encoding: "utf-8", timeout: 5000 });
+                    const ipLine = deviceInfo.split("\n").find((l) => l.startsWith("IP4.ADDRESS"));
+                    if (ipLine) {
+                        // Format: IP4.ADDRESS[1]:192.168.1.100/24
+                        ip = ipLine.split(":").slice(1).join(":").split("/")[0].trim();
+                    }
+                }
+                catch {
+                    // IP check failed — connection may still be establishing
+                }
+                if (ip) {
+                    console.error(`${logPrefix} action="connect" ssid="${ssid}" result="connected" ip="${ip}"`);
+                    // Check if signal was weak and include warning
+                    let warning = "";
+                    try {
+                        const scanRaw = execFileSync("nmcli", ["-t", "-f", "SSID,SIGNAL", "device", "wifi", "list"], { encoding: "utf-8", timeout: 5000 });
+                        const match = parseNmcliLines(scanRaw).find(([name]) => name === ssid);
+                        const signal = match ? parseInt(match[1], 10) || 0 : 0;
+                        if (signal > 0 && signal < 30) {
+                            warning = `\n\nWarning: Signal strength is weak (${signal}%). Connection may be unreliable.`;
+                        }
+                    }
+                    catch {
+                        // Signal check is best-effort
+                    }
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `Connected to ${ssid}. IP address: ${ip}. You can safely unplug ethernet.${warning}`,
+                            }],
+                    };
+                }
+                else {
+                    console.error(`${logPrefix} action="connect" ssid="${ssid}" result="connected_no_ip"`);
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `Connected to ${ssid} but no IP address was assigned. Stay on ethernet. The network may require additional configuration — check with your network administrator.`,
+                            }],
+                    };
+                }
+            }
+            // ── status ───────────────────────────────────────────────
+            case "status": {
+                // Check if wlan0 exists
+                let deviceStatus;
+                try {
+                    deviceStatus = execFileSync("nmcli", ["-t", "-f", "DEVICE,TYPE,STATE", "device", "status"], { encoding: "utf-8", timeout: 5000 });
+                }
+                catch (err) {
+                    console.error(`${logPrefix} action="status" result="failed" error="${err instanceof Error ? err.message : String(err)}"`);
+                    return {
+                        content: [{ type: "text", text: `WiFi status check failed: ${err instanceof Error ? err.message : String(err)}` }],
+                        isError: true,
+                    };
+                }
+                const wifiDevice = parseNmcliLines(deviceStatus).find(([, type]) => type === "wifi");
+                if (!wifiDevice) {
+                    console.error(`${logPrefix} action="status" result="no_hardware"`);
+                    return {
+                        content: [{ type: "text", text: "No WiFi hardware detected on this device." }],
+                    };
+                }
+                if (wifiDevice[2] !== "connected") {
+                    console.error(`${logPrefix} action="status" result="not_connected" state="${wifiDevice[2]}"`);
+                    return {
+                        content: [{ type: "text", text: `WiFi is not connected. Device state: ${wifiDevice[2]}.` }],
+                    };
+                }
+                // Get detailed connection info
+                const details = execFileSync("nmcli", ["-t", "-f", "GENERAL.CONNECTION,IP4.ADDRESS,IP4.GATEWAY,GENERAL.HWADDR", "device", "show", "wlan0"], { encoding: "utf-8", timeout: 5000 });
+                const detailLines = parseNmcliLines(details);
+                const conn = detailLines.find(([k]) => k === "GENERAL.CONNECTION")?.[1] ?? "unknown";
+                const ipAddr = detailLines.find(([k]) => k.startsWith("IP4.ADDRESS"))?.[1] ?? "none";
+                const gateway = detailLines.find(([k]) => k.startsWith("IP4.GATEWAY"))?.[1] ?? "none";
+                // Get signal strength
+                let signal = "unknown";
+                try {
+                    const scanRaw = execFileSync("nmcli", ["-t", "-f", "SSID,SIGNAL", "device", "wifi", "list"], { encoding: "utf-8", timeout: 5000 });
+                    const match = parseNmcliLines(scanRaw).find(([name]) => name === conn);
+                    if (match)
+                        signal = `${match[1]}%`;
+                }
+                catch {
+                    // Signal lookup is best-effort
+                }
+                console.error(`${logPrefix} action="status" result="connected" ssid="${conn}"`);
+                return {
+                    content: [{
+                            type: "text",
+                            text: `WiFi: connected\nSSID: ${conn}\nIP: ${ipAddr}\nGateway: ${gateway}\nSignal: ${signal}`,
+                        }],
+                };
+            }
+            // ── saved ────────────────────────────────────────────────
+            case "saved": {
+                const raw = execFileSync("nmcli", ["-t", "-f", "NAME,TYPE", "connection", "show"], { encoding: "utf-8", timeout: 5000 });
+                const wifiConns = parseNmcliLines(raw).filter(([, type]) => type === "802-11-wireless");
+                console.error(`${logPrefix} action="saved" count=${wifiConns.length}`);
+                if (wifiConns.length === 0) {
+                    return {
+                        content: [{ type: "text", text: "No saved WiFi networks." }],
+                    };
+                }
+                const formatted = wifiConns.map(([name]) => name).join("\n");
+                return {
+                    content: [{ type: "text", text: `# Saved WiFi Networks\n\n${formatted}` }],
+                };
+            }
+            // ── forget ───────────────────────────────────────────────
+            case "forget": {
+                if (!ssid) {
+                    return {
+                        content: [{ type: "text", text: "SSID is required for forget action." }],
+                        isError: true,
+                    };
+                }
+                execFileSync("nmcli", ["connection", "delete", ssid], { encoding: "utf-8", timeout: 10000 });
+                console.error(`${logPrefix} action="forget" ssid="${ssid}" result="ok"`);
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Forgotten network: ${ssid}. It will no longer auto-connect.`,
+                        }],
+                };
+            }
+            default:
+                return {
+                    content: [{ type: "text", text: `Unknown WiFi action: ${action}` }],
+                    isError: true,
+                };
+        }
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.error(`${logPrefix} action="${action}" ssid="${ssid ?? ""}" result="failed" error="${errMsg}"`);
+        // Parse common nmcli error patterns into user-friendly messages
+        if (errMsg.includes("NetworkManager is not running")) {
+            return {
+                content: [{ type: "text", text: "NetworkManager is not running. Start it with: sudo systemctl start NetworkManager" }],
+                isError: true,
+            };
+        }
+        if (errMsg.includes("No network with SSID") || errMsg.includes("not found")) {
+            return {
+                content: [{ type: "text", text: `Network '${ssid}' not found — it may be out of range or the name may be incorrect.` }],
+                isError: true,
+            };
+        }
+        if (errMsg.includes("Secrets were required") || errMsg.includes("802-11-wireless-security.psk")) {
+            return {
+                content: [{ type: "text", text: `Authentication failed for '${ssid}' — the password may be incorrect.` }],
+                isError: true,
+            };
+        }
+        if (errMsg.includes("no wifi device found") || errMsg.includes("Wi-Fi device not found")) {
+            return {
+                content: [{ type: "text", text: "No WiFi hardware detected on this device." }],
+                isError: true,
+            };
+        }
+        if (errMsg.includes("ENOENT")) {
+            return {
+                content: [{ type: "text", text: "nmcli not found — NetworkManager may not be installed on this device." }],
+                isError: true,
+            };
+        }
+        if (errMsg.includes("ETIMEDOUT") || errMsg.includes("timed out") || errMsg.includes("Timeout")) {
+            return {
+                content: [{ type: "text", text: `WiFi operation timed out. The adapter may be busy — try again.` }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: `WiFi ${action} failed: ${errMsg}` }],
+            isError: true,
+        };
+    }
+});
+// ===================================================================
+// Premium plugin tools
+// ===================================================================
+server.tool("premium-list", "List available premium plugins and their delivery status. Returns structured data " +
+    "for each premium plugin in the staging area: name, type (standalone/bundle), description, " +
+    "purchase status, and delivery status (per sub-plugin for bundles).", {}, async () => {
+    try {
+        if (!existsSync(STAGING_ROOT)) {
+            return {
+                content: [{ type: "text", text: "No premium plugins available. The staging directory does not exist — premium plugins become available after the next platform update." }],
+            };
+        }
+        const config = await readAccountConfig();
+        // Effective purchasedPlugins from signed entitlement (Task 831).
+        const entitlement = await currentEntitlement();
+        const purchased = entitlement.purchasedPlugins;
+        const enabled = Array.isArray(config.enabledPlugins) ? config.enabledPlugins : [];
+        const entries = readdirSync(STAGING_ROOT, { withFileTypes: true })
+            .filter(e => e.isDirectory())
+            .sort((a, b) => a.name.localeCompare(b.name));
+        if (entries.length === 0) {
+            return {
+                content: [{ type: "text", text: "No premium plugins found in the staging area." }],
+            };
+        }
+        const plugins = [];
+        for (const entry of entries) {
+            const stagingDir = resolve(STAGING_ROOT, entry.name);
+            const bundlePath = join(stagingDir, "BUNDLE.md");
+            const pluginPath = join(stagingDir, "PLUGIN.md");
+            if (existsSync(bundlePath)) {
+                // Bundle
+                const fm = parseFrontmatter(readFileSync(bundlePath, "utf-8"));
+                const subPlugins = (Array.isArray(fm.plugins) ? fm.plugins : [])
+                    .filter(name => VALID_PLUGIN_NAME.test(name));
+                const subStatus = subPlugins.map(name => ({
+                    name,
+                    delivered: existsSync(join(PLUGINS_DIR, name, "PLUGIN.md")),
+                    enabled: enabled.includes(name),
+                }));
+                plugins.push({
+                    name: entry.name,
+                    type: "bundle",
+                    description: typeof fm.description === "string" ? fm.description : "",
+                    purchased: purchased.includes(entry.name),
+                    subPlugins: subStatus,
+                });
+            }
+            else if (existsSync(pluginPath)) {
+                // Standalone
+                const fm = parseFrontmatter(readFileSync(pluginPath, "utf-8"));
+                plugins.push({
+                    name: entry.name,
+                    type: "standalone",
+                    description: typeof fm.description === "string" ? fm.description : "",
+                    purchased: purchased.includes(entry.name),
+                    delivered: existsSync(join(PLUGINS_DIR, entry.name, "PLUGIN.md")),
+                    enabled: enabled.includes(entry.name),
+                });
+            }
+            // Skip directories that have neither BUNDLE.md nor PLUGIN.md
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(plugins, null, 2) }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Failed to list premium plugins: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+});
+server.tool("premium-deliver", "Deliver a purchased premium plugin. Copies plugin files from the staging area to the active " +
+    "plugin directory, verifies each copy, updates enabledPlugins in account.json, and scans for " +
+    "agent templates. Handles both standalone plugins and bundles (auto-detected). Idempotent — " +
+    "already-delivered sub-plugins are skipped. Returns a structured result with per-sub-plugin " +
+    "status and available templates.", {
+    pluginName: z.string().describe("Name of the premium plugin to deliver (e.g. 'real-agency', 'teaching')"),
+}, async ({ pluginName }) => {
+    const TAG = "[premium-deliver]";
+    // --- Validate plugin name ---
+    if (!pluginName || !VALID_PLUGIN_NAME.test(pluginName)) {
+        return {
+            content: [{ type: "text", text: `${TAG} Invalid plugin name "${pluginName}". Must match [a-z0-9-].` }],
+            isError: true,
+        };
+    }
+    // --- Guard against clobbering core plugins ---
+    if (CORE_PLUGINS.includes(pluginName)) {
+        return {
+            content: [{ type: "text", text: `${TAG} "${pluginName}" is a core plugin and cannot be delivered as a premium plugin.` }],
+            isError: true,
+        };
+    }
+    // --- Check staging directory ---
+    if (!existsSync(STAGING_ROOT)) {
+        return {
+            content: [{ type: "text", text: `${TAG} Premium plugins staging directory does not exist. Premium plugins become available after the next platform update.` }],
+            isError: true,
+        };
+    }
+    const stagingDir = resolve(STAGING_ROOT, pluginName);
+    if (!existsSync(stagingDir)) {
+        return {
+            content: [{ type: "text", text: `${TAG} No premium plugin named "${pluginName}" found in the staging area.` }],
+            isError: true,
+        };
+    }
+    // --- Read account config ---
+    let config;
+    try {
+        config = await readAccountConfig();
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `${TAG} Failed to read account config: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+    // Effective purchasedPlugins from signed entitlement (Task 831). The
+    // raw account.json value is ignored on commercial installs; verifier
+    // returns the signed list (or [] on anonymous-fallback).
+    const entitlement = await resolveEntitlement(ENTITLEMENT_BRAND, {
+        accountId: typeof config.accountId === "string" ? config.accountId : "",
+        customerEmail: typeof config.customerEmail === "string" ? config.customerEmail : undefined,
+        tier: typeof config.tier === "string" ? config.tier : undefined,
+        purchasedPlugins: Array.isArray(config.purchasedPlugins) ? config.purchasedPlugins : undefined,
+    });
+    const purchased = entitlement.purchasedPlugins;
+    // --- Check purchase status ---
+    if (!purchased.includes(pluginName)) {
+        return {
+            content: [{ type: "text", text: `${TAG} "${pluginName}" is not in purchasedPlugins. Record the purchase first.` }],
+            isError: true,
+        };
+    }
+    // --- Detect type: bundle vs standalone ---
+    const bundlePath = join(stagingDir, "BUNDLE.md");
+    const pluginMdPath = join(stagingDir, "PLUGIN.md");
+    const isBundle = existsSync(bundlePath);
+    const isStandalone = !isBundle && existsSync(pluginMdPath);
+    if (!isBundle && !isStandalone) {
+        return {
+            content: [{ type: "text", text: `${TAG} Staging directory "${pluginName}" contains neither BUNDLE.md nor PLUGIN.md. Invalid premium plugin.` }],
+            isError: true,
+        };
+    }
+    const items = [];
+    if (isBundle) {
+        const fm = parseFrontmatter(readFileSync(bundlePath, "utf-8"));
+        const subPluginNames = Array.isArray(fm.plugins) ? fm.plugins : [];
+        if (subPluginNames.length === 0) {
+            return {
+                content: [{ type: "text", text: `${TAG} BUNDLE.md for "${pluginName}" has an empty or missing plugins array.` }],
+                isError: true,
+            };
+        }
+        for (const sub of subPluginNames) {
+            if (!VALID_PLUGIN_NAME.test(sub)) {
+                return {
+                    content: [{ type: "text", text: `${TAG} Sub-plugin name "${sub}" in BUNDLE.md contains invalid characters. Aborting delivery.` }],
+                    isError: true,
+                };
+            }
+            if (CORE_PLUGINS.includes(sub)) {
+                return {
+                    content: [{ type: "text", text: `${TAG} Sub-plugin "${sub}" collides with a core plugin name. Aborting delivery.` }],
+                    isError: true,
+                };
+            }
+            items.push({ name: sub, sourcePath: resolve(stagingDir, "plugins", sub) });
+        }
+    }
+    else {
+        items.push({ name: pluginName, sourcePath: stagingDir });
+    }
+    const results = [];
+    const newlyEnabled = [];
+    for (const item of items) {
+        const destPath = resolve(PLUGINS_DIR, item.name);
+        // Already delivered — skip (preserves user's enable/disable state)
+        if (existsSync(join(destPath, "PLUGIN.md"))) {
+            console.log(`${TAG} ${item.name} already delivered — skipping`);
+            results.push({ name: item.name, status: "skipped" });
+            continue;
+        }
+        // Validate source
+        if (!existsSync(join(item.sourcePath, "PLUGIN.md"))) {
+            const msg = `Source PLUGIN.md missing at ${item.sourcePath}`;
+            console.error(`${TAG} FAILED ${item.name}: ${msg}`);
+            results.push({ name: item.name, status: "failed", error: msg });
+            continue;
+        }
+        // Copy
+        try {
+            cpSync(item.sourcePath, destPath, { recursive: true });
+            console.log(`${TAG} copied ${item.name} from staging`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`${TAG} FAILED to copy ${item.name}: ${msg}`);
+            results.push({ name: item.name, status: "failed", error: msg });
+            continue;
+        }
+        // Verify
+        const verifyPath = join(destPath, "PLUGIN.md");
+        if (!existsSync(verifyPath)) {
+            console.error(`${TAG} FAILED to verify ${item.name}: PLUGIN.md missing after copy`);
+            results.push({ name: item.name, status: "failed", error: "PLUGIN.md missing after copy" });
+            continue;
+        }
+        // Count skills
+        const skillsDir = join(destPath, "skills");
+        let skillCount = 0;
+        if (existsSync(skillsDir)) {
+            skillCount = readdirSync(skillsDir, { withFileTypes: true })
+                .filter(e => e.isDirectory()).length;
+        }
+        console.log(`${TAG} verified ${item.name} (${skillCount} skills)`);
+        results.push({ name: item.name, status: "delivered", skills: skillCount });
+        newlyEnabled.push(item.name);
+    }
+    // --- Update enabledPlugins (only add newly delivered, deduplicate) ---
+    if (newlyEnabled.length > 0) {
+        try {
+            // Re-read config to reduce race window
+            const freshConfig = await readAccountConfig();
+            const freshEnabled = Array.isArray(freshConfig.enabledPlugins)
+                ? freshConfig.enabledPlugins
+                : [];
+            const merged = [...new Set([...freshEnabled, ...newlyEnabled])];
+            freshConfig.enabledPlugins = merged;
+            const configPath = join(getAccountDir(), "account.json");
+            await writeFile(configPath, JSON.stringify(freshConfig, null, 2) + "\n", "utf-8");
+            console.log(`${TAG} updated enabledPlugins: added ${newlyEnabled.join(", ")}`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`${TAG} FAILED to update account.json: ${msg}`);
+            return {
+                content: [{
+                        type: "text",
+                        text: `${TAG} Plugins were copied but account.json update failed: ${msg}\n\nDelivery results:\n${JSON.stringify(results, null, 2)}`,
+                    }],
+                isError: true,
+            };
+        }
+    }
+    const templates = [];
+    // For bundles, templates live in the staging agents/ dir; for standalone, in the delivered plugin
+    const agentsSearchDirs = [];
+    if (isBundle) {
+        const bundleAgentsDir = join(stagingDir, "agents");
+        if (existsSync(bundleAgentsDir))
+            agentsSearchDirs.push(bundleAgentsDir);
+    }
+    else {
+        const pluginAgentsDir = join(PLUGINS_DIR, pluginName, "agents");
+        if (existsSync(pluginAgentsDir))
+            agentsSearchDirs.push(pluginAgentsDir);
+    }
+    for (const agentsDir of agentsSearchDirs) {
+        const subdirs = readdirSync(agentsDir, { withFileTypes: true })
+            .filter(e => e.isDirectory());
+        for (const sub of subdirs) {
+            const templateJsonPath = join(agentsDir, sub.name, "template.json");
+            if (!existsSync(templateJsonPath))
+                continue;
+            try {
+                const templateData = JSON.parse(readFileSync(templateJsonPath, "utf-8"));
+                const identityExists = existsSync(join(agentsDir, sub.name, "IDENTITY.md"));
+                const soulExists = existsSync(join(agentsDir, sub.name, "SOUL.md"));
+                if (!identityExists || !soulExists) {
+                    console.log(`${TAG} template ${sub.name} incomplete — missing ${!identityExists ? "IDENTITY.md" : "SOUL.md"}, skipping`);
+                    continue;
+                }
+                templates.push({
+                    directory: join(agentsDir, sub.name),
+                    displayName: templateData.displayName ?? sub.name,
+                    description: templateData.description ?? "",
+                    suggestedSlug: templateData.suggestedSlug,
+                });
+            }
+            catch {
+                console.log(`${TAG} template ${sub.name} has invalid template.json, skipping`);
+            }
+        }
+    }
+    // --- Build structured result ---
+    const delivered = results.filter(r => r.status === "delivered");
+    const skipped = results.filter(r => r.status === "skipped");
+    const failed = results.filter(r => r.status === "failed");
+    const totalSkills = delivered.reduce((sum, r) => sum + (r.skills ?? 0), 0);
+    const output = {
+        pluginName,
+        type: isBundle ? "bundle" : "standalone",
+        delivered: delivered.map(r => ({ name: r.name, skills: r.skills })),
+        skipped: skipped.map(r => r.name),
+        failed: failed.map(r => ({ name: r.name, error: r.error })),
+        totalDelivered: delivered.length,
+        totalSkipped: skipped.length,
+        totalFailed: failed.length,
+        totalSkills,
+        templates: templates.map(t => ({
+            displayName: t.displayName,
+            description: t.description,
+            suggestedSlug: t.suggestedSlug,
+            directory: t.directory,
+        })),
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+    };
+});
+// ---------------------------------------------------------------------------
+// file-attach — copy a generated file into the attachment store for download
+// ---------------------------------------------------------------------------
+eagerTool(server, "file-attach", "Attach a file from the account directory for delivery to the user. " +
+    "Copies the file into the attachment store and returns metadata for rendering " +
+    "a download component. The file must be within the account directory tree. " +
+    "After calling this tool, call render-component with name 'file-attachment' " +
+    "and pass the returned metadata as data.", {
+    filePath: z.string().describe("Absolute path to the file to attach"),
+}, async ({ filePath }) => {
+    const TAG = "[file-attach]";
+    if (!filePath || !filePath.trim()) {
+        return {
+            content: [{ type: "text", text: `${TAG} filePath is required` }],
+            isError: true,
+        };
+    }
+    const accountDir = getAccountDir();
+    // --- Path validation: must be within the account directory ---
+    let resolvedPath;
+    try {
+        const { realpathSync: rp } = await import("node:fs");
+        resolvedPath = rp(filePath);
+        const accountResolved = rp(accountDir);
+        if (!resolvedPath.startsWith(accountResolved + "/")) {
+            const sanitised = filePath.replace(accountDir, "<account>/");
+            console.error(`${TAG} REJECTED path=${sanitised} reason=outside_account_directory`);
+            return {
+                content: [{ type: "text", text: `${TAG} Access denied: file is outside the account directory.` }],
+                isError: true,
+            };
+        }
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            console.error(`${TAG} ENOENT path=${filePath}`);
+            return {
+                content: [{ type: "text", text: `${TAG} File not found: ${filePath}` }],
+                isError: true,
+            };
+        }
+        console.error(`${TAG} path validation error: ${err instanceof Error ? err.message : String(err)}`);
+        return {
+            content: [{ type: "text", text: `${TAG} Failed to validate file path: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+    // --- Store in attachment store ---
+    const targetUrl = `http://127.0.0.1:${PLATFORM_PORT}/api/admin/file-attach`;
+    try {
+        const res = await fetch(targetUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ filePath: resolvedPath, accountId: ACCOUNT_ID }),
+        });
+        const result = await res.json();
+        if (!res.ok || result.error) {
+            const msg = result.error || `HTTP ${res.status}`;
+            console.error(`${TAG} store failed url=${targetUrl} status=${res.status} error=${msg}`);
+            return {
+                content: [{ type: "text", text: `${TAG} Failed to attach file: ${msg} (url=${targetUrl})` }],
+                isError: true,
+            };
+        }
+        console.error(`${TAG} attached path=${resolvedPath} size=${result.sizeBytes} mime=${result.mimeType} id=${result.attachmentId}`);
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        attachmentId: result.attachmentId,
+                        filename: result.filename,
+                        sizeBytes: result.sizeBytes,
+                        mimeType: result.mimeType,
+                    }),
+                }],
+        };
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.error(`${TAG} fetch failed url=${targetUrl} error=${errMsg}`);
+        return {
+            content: [{ type: "text", text: `${TAG} Failed to attach file: could not reach platform server at ${targetUrl} (${errMsg})` }],
+            isError: true,
+        };
+    }
+});
+// ===================================================================
+// Action approval tools (EU AI Act Article 14 — human oversight)
+//
+//   Hook queues require-review actions to {accountDir}/pending-actions/.
+//   These tools let the admin list, approve, reject, or edit pending actions.
+//   On approval, the target plugin MCP server is spawned directly (dispatchStep
+//   pattern) to execute the original tool call.
+// ===================================================================
+let _pendingDir;
+function getPendingDir() {
+    if (!_pendingDir)
+        _pendingDir = resolve(getAccountDir(), "pending-actions");
+    return _pendingDir;
+}
+function readPendingActions() {
+    const pendingDir = getPendingDir();
+    if (!existsSync(pendingDir))
+        return [];
+    const files = readdirSync(pendingDir)
+        .filter(f => f.endsWith(".json") && !f.startsWith("."));
+    const actions = [];
+    for (const file of files) {
+        try {
+            const raw = readFileSync(resolve(pendingDir, file), "utf-8");
+            const parsed = JSON.parse(raw);
+            if (parsed.state === "pending") {
+                actions.push(parsed);
+            }
+        }
+        catch (err) {
+            console.error(`[approval] Failed to read pending action ${file}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return actions.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}
+function readPendingAction(actionId) {
+    const filePath = resolve(getPendingDir(), `${actionId}.json`);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        return JSON.parse(readFileSync(filePath, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+function resolvePendingAction(actionId, state, editedInput) {
+    const filePath = resolve(getPendingDir(), `${actionId}.json`);
+    if (!existsSync(filePath))
+        return false;
+    try {
+        const action = JSON.parse(readFileSync(filePath, "utf-8"));
+        if (action.state !== "pending")
+            return false;
+        action.state = state;
+        action.resolvedAt = new Date().toISOString();
+        if (editedInput)
+            action.editedInput = editedInput;
+        writeFileSync(filePath, JSON.stringify(action, null, 2), "utf-8");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function cleanupPendingAction(actionId) {
+    const pendingDir = getPendingDir();
+    const filePath = resolve(pendingDir, `${actionId}.json`);
+    try {
+        if (existsSync(filePath)) {
+            const archiveDir = resolve(pendingDir, "resolved");
+            if (!existsSync(archiveDir)) {
+                mkdirSync(archiveDir, { recursive: true });
+            }
+            renameSync(filePath, resolve(archiveDir, `${actionId}.json`));
+        }
+    }
+    catch (err) {
+        console.error(`[approval] Failed to archive pending action ${actionId}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+async function persistApprovalToolCall(opts) {
+    // Write doctrine (Task 673): a ToolCall without its owning Conversation is
+    // noise — every admin tool call belongs to a chat. When conversationId is
+    // missing or its Conversation cannot be matched, we log and skip the
+    // persist rather than create an orphan ToolCall node. The legacy
+    // OPTIONAL-MATCH + FOREACH pattern created orphans silently.
+    if (!opts.conversationId) {
+        console.error(`[approval] ToolCall skipped (no conversationId): tool=${opts.toolName} state=${opts.approvalState}`);
+        return;
+    }
+    const session = getSession();
+    try {
+        const optionalFields = [
+            opts.originalInput != null ? ", originalInput: $originalInput" : "",
+        ].join("");
+        const res = await session.run(`MATCH (c:Conversation {conversationId: $conversationId})
+       CREATE (c)-[:HAS_TOOL_CALL]->(tc:ToolCall {
+         callId: $callId,
+         toolName: $toolName,
+         pluginName: $pluginName,
+         input: $input,
+         output: $output,
+         isError: $isError,
+         agentType: 'admin',
+         accountId: $accountId,
+         approvalState: $approvalState,
+         conversationId: $conversationId,
+         createdBySource: 'admin-approval',
+         startedAt: datetime($startedAt),
+         completedAt: datetime($completedAt)
+         ${optionalFields}
+       })`, {
+            callId: randomUUID(),
+            toolName: opts.toolName,
+            pluginName: opts.pluginName,
+            input: opts.input.slice(0, 300),
+            output: opts.output.slice(0, 300),
+            isError: opts.isError,
+            accountId: ACCOUNT_ID,
+            approvalState: opts.approvalState,
+            conversationId: opts.conversationId,
+            startedAt: new Date().toISOString(),
+            completedAt: new Date().toISOString(),
+            ...(opts.originalInput != null ? { originalInput: opts.originalInput.slice(0, 300) } : {}),
+        });
+        if (res.summary.counters.updates().nodesCreated === 0) {
+            console.error(`[approval] ToolCall skipped (conversation ${opts.conversationId} not found): tool=${opts.toolName}`);
+            return;
+        }
+        console.error(`[approval] ToolCall persisted: ${opts.toolName} state=${opts.approvalState}`);
+    }
+    catch (err) {
+        console.error(`[approval] ToolCall persist failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    finally {
+        await session.close();
+    }
+}
+/**
+ * Spawn a plugin MCP server and execute a tool call directly.
+ * Same pattern as workflow-execute.ts dispatchStep.
+ */
+async function dispatchApprovedAction(plugin, tool, args, timeoutMs = 30_000) {
+    const serverPath = resolve(PLATFORM_ROOT, "plugins", plugin, "mcp", "dist", "index.js");
+    // Path traversal check
+    const pluginsRoot = resolve(PLATFORM_ROOT, "plugins");
+    if (!serverPath.startsWith(pluginsRoot + "/")) {
+        throw new Error(`Invalid plugin name: "${plugin}" — path traversal blocked`);
+    }
+    if (!existsSync(serverPath)) {
+        throw new Error(`Plugin MCP server not found: ${serverPath}`);
+    }
+    const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
+    const { StdioClientTransport } = await import("@modelcontextprotocol/sdk/client/stdio.js");
+    const env = {};
+    for (const [k, v] of Object.entries(process.env)) {
+        if (v !== undefined)
+            env[k] = v;
+    }
+    env.PLATFORM_ROOT = PLATFORM_ROOT;
+    env.ACCOUNT_ID = ACCOUNT_ID;
+    const transport = new StdioClientTransport({
+        command: process.execPath,
+        args: [serverPath],
+        env,
+        stderr: "pipe",
+    });
+    let childStderr = "";
+    const stderrStream = transport.stderr;
+    if (stderrStream) {
+        stderrStream.on("data", (chunk) => {
+            if (childStderr.length < 4096) {
+                childStderr += chunk.toString("utf-8").slice(0, 4096 - childStderr.length);
+            }
+        });
+    }
+    const client = new Client({ name: "approval-executor", version: "1.0.0" });
+    let timedOut = false;
+    const timeout = setTimeout(() => {
+        timedOut = true;
+        client.close().catch(() => { });
+    }, timeoutMs);
+    try {
+        await client.connect(transport);
+        const result = await client.callTool({ name: tool, arguments: args });
+        const contentArr = Array.isArray(result.content) ? result.content : [];
+        const text = contentArr
+            .filter((c) => c.type === "text")
+            .map((c) => c.text)
+            .join("\n");
+        return { text, isError: result.isError === true };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const stderrSuffix = childStderr ? `\nChild stderr: ${childStderr.trim()}` : "";
+        if (timedOut) {
+            throw new Error(`Tool "${tool}" on plugin "${plugin}" timed out after ${timeoutMs}ms${stderrSuffix}`);
+        }
+        throw new Error(`Tool "${tool}" on plugin "${plugin}" failed: ${msg}${stderrSuffix}`);
+    }
+    finally {
+        clearTimeout(timeout);
+        await client.close().catch(() => { });
+    }
+}
+eagerTool(server, "action-pending", "List actions that are queued for human approval. Returns each pending action's ID, " +
+    "tool name, input summary, and when it was queued. Use this to review what the agent " +
+    "wanted to do before approving or rejecting.", {}, async () => {
+    const actions = readPendingActions();
+    if (actions.length === 0) {
+        return {
+            content: [{ type: "text", text: "No pending actions. All actions are either approved, rejected, or auto-executed." }],
+        };
+    }
+    const lines = actions.map((a) => {
+        const inputSummary = JSON.stringify(a.hookPayload?.tool_input ?? {}).slice(0, 200);
+        return `- **${a.actionId}** | ${a.toolName} | queued ${a.createdAt}\n  Input: ${inputSummary}`;
+    });
+    return {
+        content: [{ type: "text", text: `## Pending Actions (${actions.length})\n\n${lines.join("\n\n")}` }],
+    };
+});
+eagerTool(server, "action-approve", "Approve a pending action and execute it immediately. The original tool call is " +
+    "executed via the target plugin's MCP server. The result is returned and an audit " +
+    "record is written to Neo4j with approvalState: approved.", {
+    actionId: z.string().describe("The action ID to approve (from action-pending)"),
+    conversationId: z.string().optional().describe("Current conversation ID for audit trail linking"),
+}, async ({ actionId, conversationId }) => {
+    const action = readPendingAction(actionId);
+    if (!action) {
+        return {
+            content: [{ type: "text", text: `Action ${actionId} not found. It may have already been resolved or the ID is incorrect.` }],
+            isError: true,
+        };
+    }
+    if (action.state !== "pending") {
+        return {
+            content: [{ type: "text", text: `Action ${actionId} is already ${action.state}. Cannot approve a resolved action.` }],
+            isError: true,
+        };
+    }
+    if (!action.pluginName) {
+        return {
+            content: [{ type: "text", text: `Action ${actionId} has no plugin name — cannot determine which MCP server to execute.` }],
+            isError: true,
+        };
+    }
+    // Mark as approved before execution
+    if (!resolvePendingAction(actionId, "approved")) {
+        return {
+            content: [{ type: "text", text: `Failed to update action ${actionId} state. The file may have been modified concurrently.` }],
+            isError: true,
+        };
+    }
+    const toolInput = action.hookPayload?.tool_input ?? {};
+    console.error(`[approval] Executing approved action: ${action.toolName} plugin=${action.pluginName} actionId=${actionId}`);
+    try {
+        const result = await dispatchApprovedAction(action.pluginName, action.toolName, toolInput);
+        // Persist audit record
+        await persistApprovalToolCall({
+            toolName: action.toolName,
+            pluginName: action.pluginName,
+            input: JSON.stringify(toolInput),
+            output: result.text,
+            isError: result.isError,
+            approvalState: "approved",
+            conversationId,
+        });
+        cleanupPendingAction(actionId);
+        return {
+            content: [{ type: "text", text: `Action approved and executed.\n\nTool: ${action.toolName}\nResult:\n${result.text}` }],
+            isError: result.isError,
+        };
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.error(`[approval] Execution failed for ${actionId}: ${errMsg}`);
+        await persistApprovalToolCall({
+            toolName: action.toolName,
+            pluginName: action.pluginName,
+            input: JSON.stringify(toolInput),
+            output: errMsg,
+            isError: true,
+            approvalState: "approved",
+            conversationId,
+        });
+        return {
+            content: [{ type: "text", text: `Action approved but execution failed: ${errMsg}` }],
+            isError: true,
+        };
+    }
+});
+eagerTool(server, "action-reject", "Reject a pending action. The action is not executed. An audit record is written " +
+    "to Neo4j with approvalState: rejected.", {
+    actionId: z.string().describe("The action ID to reject (from action-pending)"),
+    reason: z.string().optional().describe("Optional reason for rejection"),
+    conversationId: z.string().optional().describe("Current conversation ID for audit trail linking"),
+}, async ({ actionId, reason, conversationId }) => {
+    const action = readPendingAction(actionId);
+    if (!action) {
+        return {
+            content: [{ type: "text", text: `Action ${actionId} not found. It may have already been resolved or the ID is incorrect.` }],
+            isError: true,
+        };
+    }
+    if (action.state !== "pending") {
+        return {
+            content: [{ type: "text", text: `Action ${actionId} is already ${action.state}. Cannot reject a resolved action.` }],
+            isError: true,
+        };
+    }
+    if (!resolvePendingAction(actionId, "rejected")) {
+        return {
+            content: [{ type: "text", text: `Failed to update action ${actionId} state.` }],
+            isError: true,
+        };
+    }
+    const reasonSuffix = reason ? ` Reason: ${reason}` : "";
+    console.error(`[approval] Action rejected: ${action.toolName} actionId=${actionId}${reasonSuffix}`);
+    await persistApprovalToolCall({
+        toolName: action.toolName,
+        pluginName: action.pluginName ?? "unknown",
+        input: JSON.stringify(action.hookPayload?.tool_input ?? {}),
+        output: `Rejected by admin.${reasonSuffix}`,
+        isError: false,
+        approvalState: "rejected",
+        conversationId,
+    });
+    cleanupPendingAction(actionId);
+    return {
+        content: [{ type: "text", text: `Action rejected. ${action.toolName} will not be executed.${reasonSuffix}` }],
+    };
+});
+eagerTool(server, "action-edit", "Edit a pending action's input and then execute the modified version. The original " +
+    "input is preserved in the audit trail. Use this when the admin wants to modify the " +
+    "action (e.g., change the email subject) before approving.", {
+    actionId: z.string().describe("The action ID to edit (from action-pending)"),
+    editedInput: z.string().describe("The modified tool input as a JSON string"),
+    conversationId: z.string().optional().describe("Current conversation ID for audit trail linking"),
+}, async ({ actionId, editedInput, conversationId }) => {
+    const action = readPendingAction(actionId);
+    if (!action) {
+        return {
+            content: [{ type: "text", text: `Action ${actionId} not found.` }],
+            isError: true,
+        };
+    }
+    if (action.state !== "pending") {
+        return {
+            content: [{ type: "text", text: `Action ${actionId} is already ${action.state}. Cannot edit a resolved action.` }],
+            isError: true,
+        };
+    }
+    if (!action.pluginName) {
+        return {
+            content: [{ type: "text", text: `Action ${actionId} has no plugin name — cannot determine which MCP server to execute.` }],
+            isError: true,
+        };
+    }
+    let parsedInput;
+    try {
+        parsedInput = JSON.parse(editedInput);
+    }
+    catch {
+        return {
+            content: [{ type: "text", text: `Invalid JSON in editedInput. Please provide valid JSON for the tool input.` }],
+            isError: true,
+        };
+    }
+    const originalInput = action.hookPayload?.tool_input ?? {};
+    // Mark as approved with the edited input
+    if (!resolvePendingAction(actionId, "approved", parsedInput)) {
+        return {
+            content: [{ type: "text", text: `Failed to update action ${actionId} state.` }],
+            isError: true,
+        };
+    }
+    console.error(`[approval] Executing edited action: ${action.toolName} plugin=${action.pluginName} actionId=${actionId}`);
+    try {
+        const result = await dispatchApprovedAction(action.pluginName, action.toolName, parsedInput);
+        await persistApprovalToolCall({
+            toolName: action.toolName,
+            pluginName: action.pluginName,
+            input: JSON.stringify(parsedInput),
+            output: result.text,
+            isError: result.isError,
+            approvalState: "approved",
+            originalInput: JSON.stringify(originalInput),
+            conversationId,
+        });
+        cleanupPendingAction(actionId);
+        return {
+            content: [{ type: "text", text: `Action edited, approved, and executed.\n\nTool: ${action.toolName}\nResult:\n${result.text}` }],
+            isError: result.isError,
+        };
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        console.error(`[approval] Edited execution failed for ${actionId}: ${errMsg}`);
+        await persistApprovalToolCall({
+            toolName: action.toolName,
+            pluginName: action.pluginName,
+            input: JSON.stringify(parsedInput),
+            output: errMsg,
+            isError: true,
+            approvalState: "approved",
+            originalInput: JSON.stringify(originalInput),
+            conversationId,
+        });
+        return {
+            content: [{ type: "text", text: `Action edited and approved but execution failed: ${errMsg}` }],
+            isError: true,
+        };
+    }
+});
+// Cleanup on exit (SIGTERM for systemd service stops on Pi)
+const cleanup = async () => {
+    await closeDriver();
+    process.exit(0);
+};
+process.on("SIGINT", cleanup);
+process.on("SIGTERM", cleanup);
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map