@muxoai/sdk 1.3.0 → 1.4.3

package/dist/cli.js

@@ -5,8 +5,11 @@ import path from "node:path";
 import readline from "node:readline";
 import { getConfig } from "./config.js";
 import { MuxoEngine } from "./engine.js";
-import { handleJsonRpcMcpRequest } from "./mcp.js";
+import { handleJsonRpcMcpRequest, LATEST_MCP_PROTOCOL_VERSION } from "./mcp.js";
+import { DEFAULT_WORKSPACE_POLICY, describePolicyInPlainEnglish, sanitizePolicyPatch, } from "./policy.js";
+import { RING_LABELS } from "./providers/microsoft-governance.js";
 import { BYOK_PROVIDER_CATALOG, MuxoStore } from "./store.js";
+import { MUXO_VERSION } from "./version.js";
 function promptUserLine(question) {
     return new Promise((resolve) => {
         const rl = readline.createInterface({
@@ -70,37 +73,148 @@ function parseFlags(args) {
     return { positional, flags };
 }
 async function runCli() {
-    const config = getConfig();
-    const store = new MuxoStore(config.dbPath, config.vaultMasterKey);
-    const engine = new MuxoEngine(config, store);
     const { positional, flags } = parseFlags(process.argv.slice(2));
     const cmd = positional[0] || "help";
     if (flags.version || flags.v || cmd === "version") {
         console.log(flags.json
-            ? JSON.stringify({ ok: true, name: "@muxoai/cli", version: "1.3.0" }, null, 2)
-            : "1.3.0");
+            ? JSON.stringify({ ok: true, name: "@muxoai/cli", version: MUXO_VERSION }, null, 2)
+            : MUXO_VERSION);
         return;
     }
     const savedCliConfig = readCliAuthConfig();
-    const apiKeyFlag = (typeof flags["api-key"] === "string" ? flags["api-key"] : "") ||
+    let apiKeyFlag = (typeof flags["api-key"] === "string" ? flags["api-key"] : "") ||
         process.env.MUXO_API_KEY ||
         savedCliConfig?.apiKey ||
         "";
-    const tokenAuth = apiKeyFlag ? store.resolveAuthToken(apiKeyFlag) : null;
-    const fallback = store.ensureDefaultWorkspace();
-    const ctx = tokenAuth
-        ? {
-            user: tokenAuth.user,
-            workspace: tokenAuth.workspace,
-            actorId: tokenAuth.actorId,
-            authType: tokenAuth.authType,
-        }
-        : {
-            user: fallback.user,
-            workspace: fallback.workspace,
-            actorId: `cli:${fallback.user.id}`,
-            authType: "session",
+    const explicitUrlFlag = (typeof flags.url === "string"
+        ? flags.url
+        : process.env.MUXO_API_URL || process.env.MUXO_CLOUD_URL || "").replace(/\/+$/, "");
+    const useLocalDb = Boolean((process.env.MUXO_DB_PATH || flags.local) && !explicitUrlFlag);
+    const remoteUrl = useLocalDb
+        ? ""
+        : (explicitUrlFlag || savedCliConfig?.apiUrl || "https://api.muxo.ai").replace(/\/+$/, "");
+    const remoteFetch = async (pathname, opts) => {
+        const keyToUse = opts?.apiKey ?? apiKeyFlag;
+        const headers = {
+            Accept: "application/json",
+        };
+        if (opts?.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+        }
+        if (keyToUse) {
+            headers["Authorization"] = `Bearer ${keyToUse}`;
+        }
+        const res = await fetch(`${remoteUrl}${pathname}`, {
+            method: opts?.method || "GET",
+            headers,
+            body: opts?.body !== undefined ? JSON.stringify(opts.body) : undefined,
+        });
+        const data = (await res.json().catch(() => ({})));
+        if (opts?.acceptPaymentRequired && res.status === 402 && data.checkoutUrl) {
+            return data;
+        }
+        if (opts?.acceptHumanRequired && res.status === 403 && data.code === "human_required") {
+            return data;
+        }
+        if (!res.ok && data.error) {
+            throw new Error(String(data.error));
+        }
+        return data;
+    };
+    const signupHostedWorkspace = async (agentName, harness) => {
+        const createdRemote = await remoteFetch("/api/v1/agents/signup", {
+            method: "POST",
+            body: { agentName, harness },
+            apiKey: "",
+        });
+        if (!createdRemote || !createdRemote.apiKey) {
+            throw new Error(`Hosted signup at ${remoteUrl}/api/v1/agents/signup failed to return an API key.`);
+        }
+        const authPayload = {
+            authenticated: true,
+            apiKey: String(createdRemote.apiKey),
+            apiUrl: remoteUrl,
+            workspaceId: String(createdRemote.workspaceId || createdRemote.workspace?.id || ""),
+            workspaceName: String(createdRemote.workspace?.name || `${agentName} Workspace`),
+            agentId: String(createdRemote.agentId || createdRemote.user?.id || "usr_agent"),
+            governanceDid: String(createdRemote.governanceDid || ""),
+            supermemoryNamespace: String(createdRemote.supermemoryNamespace || ""),
+            updatedAt: new Date().toISOString(),
         };
+        return { authPayload, rawResponse: createdRemote };
+    };
+    const config = getConfig();
+    let _store = null;
+    let _engine = null;
+    const getStore = () => {
+        if (!_store) {
+            _store = new MuxoStore(config.dbPath, config.vaultMasterKey);
+        }
+        return _store;
+    };
+    const getEngine = () => {
+        if (!_engine) {
+            _engine = new MuxoEngine(config, getStore());
+        }
+        return _engine;
+    };
+    const getLocalContext = () => {
+        const store = getStore();
+        const tokenAuth = apiKeyFlag ? store.resolveAuthToken(apiKeyFlag) : null;
+        const fallback = store.ensureDefaultWorkspace();
+        const ctx = tokenAuth
+            ? {
+                user: tokenAuth.user,
+                workspace: tokenAuth.workspace,
+                actorId: tokenAuth.actorId,
+                authType: tokenAuth.authType,
+            }
+            : {
+                user: fallback.user,
+                workspace: fallback.workspace,
+                actorId: `cli:${fallback.user.id}`,
+                authType: "session",
+            };
+        return { store, engine: getEngine(), ctx, tokenAuth };
+    };
+    const maskKey = (key) => `${key.slice(0, 14)}…`;
+    // Hosted Muxo answers purchases with 402 + a Stripe Checkout URL; a self-hosted dev server may grant credits directly.
+    const printBillingResult = (data) => {
+        if (data.code === "human_required" || data.status === "human_required") {
+            console.log(JSON.stringify({
+                ok: false,
+                humanRequired: true,
+                url: data.url,
+                error: data.error,
+                next: "Open the url in a browser and sign in to the Muxo console to finish this step. Agent API keys cannot manage billing or approvals.",
+            }, null, 2));
+            return;
+        }
+        if (data.portalUrl) {
+            console.log(JSON.stringify({
+                ok: true,
+                actionRequired: true,
+                tier: data.tier,
+                interval: data.interval,
+                portalUrl: data.portalUrl,
+                next: data.nextStep || "Open portalUrl in a browser; a signed-in person confirms the plan change in the Stripe billing portal.",
+            }, null, 2));
+            return;
+        }
+        if (!data.checkoutUrl) {
+            console.log(JSON.stringify(data, null, 2));
+            return;
+        }
+        console.log(JSON.stringify({
+            ok: true,
+            paymentRequired: true,
+            kind: data.kind,
+            credits: data.credits,
+            checkoutUrl: data.checkoutUrl,
+            sessionId: data.sessionId,
+            next: `Open checkoutUrl to pay with Stripe. Muxo adds the credits once Stripe confirms the payment. Check with: muxo billing verify ${data.sessionId}`,
+        }, null, 2));
+    };
     // CLI Login / Autonomous External Signup (`muxo login`)
     if (cmd === "login" || cmd === "signup") {
         const explicitKey = typeof flags["api-key"] === "string"
@@ -109,6 +223,35 @@ async function runCli() {
                 ? positional[1]
                 : "";
         if (explicitKey) {
+            if (remoteUrl) {
+                const boot = await remoteFetch("/api/v1/bootstrap", {
+                    apiKey: explicitKey,
+                });
+                const ws = boot.organization || {};
+                const usr = boot.profile?.user || {};
+                const authPayload = {
+                    authenticated: true,
+                    apiKey: explicitKey,
+                    apiUrl: remoteUrl,
+                    workspaceId: String(ws.id || boot.profile?.workspaceId || ""),
+                    workspaceName: String(ws.name || "Muxo Workspace"),
+                    agentId: String(usr.id || "usr_agent"),
+                    governanceDid: String(boot.governance?.agentDid || ""),
+                    supermemoryNamespace: String(boot.supermemory?.namespace || ""),
+                    updatedAt: new Date().toISOString(),
+                };
+                const cfgPath = writeCliAuthConfig(authPayload);
+                console.log(JSON.stringify({
+                    ok: true,
+                    mode: "api_key",
+                    configPath: cfgPath,
+                    workspace: ws,
+                    ...authPayload,
+                    apiKey: maskKey(explicitKey),
+                }, null, 2));
+                return;
+            }
+            const { store, engine } = getLocalContext();
             const resolved = store.resolveAuthToken(explicitKey);
             if (!resolved) {
                 throw new Error("Invalid Muxo API key supplied to 'muxo login'.");
@@ -129,6 +272,7 @@ async function runCli() {
                 mode: "api_key",
                 configPath: cfgPath,
                 ...authPayload,
+                apiKey: maskKey(explicitKey),
             }, null, 2));
             return;
         }
@@ -137,6 +281,23 @@ async function runCli() {
             ? flags.name
             : positional[1] || "Muxo CLI Agent";
         const harness = typeof flags.harness === "string" ? flags.harness : "muxo-cli";
+        if (remoteUrl) {
+            const { authPayload, rawResponse } = await signupHostedWorkspace(agentName, harness);
+            const cfgPath = writeCliAuthConfig(authPayload);
+            console.log(JSON.stringify({
+                ok: true,
+                mode: "autonomous_signup",
+                configPath: cfgPath,
+                workspace: rawResponse.workspace,
+                creditsBalance: rawResponse.workspace?.creditsBalance ?? 250,
+                mcpEndpoint: rawResponse.mcpEndpoint || `${remoteUrl}/mcp`,
+                skillUrl: rawResponse.skillUrl || `${remoteUrl}/skill.md`,
+                claimEndpoint: rawResponse.claimEndpoint || `${remoteUrl}/api/v1/agents/claim`,
+                ...authPayload,
+            }, null, 2));
+            return;
+        }
+        const { store, engine } = getLocalContext();
         const created = store.createAutonomousAgentSignup({
             agentName,
             harness,
@@ -168,11 +329,165 @@ async function runCli() {
         console.log(JSON.stringify({ ok: true, authenticated: false, configPath: cfgPath }, null, 2));
         return;
     }
+    // One-command setup (`muxo setup` / `muxo init` / `muxo install`):
+    // 1. Auto-creates or loads ~/.muxo/config.json with 250 starter credits (or binds an explicit --api-key)
+    // 2. Writes .mcp.json in target directory (or ~/.cursor/mcp.json & ~/.factory/mcp.json if present)
+    if (cmd === "setup" || cmd === "init" || cmd === "install") {
+        const explicitKey = typeof flags["api-key"] === "string"
+            ? flags["api-key"].trim()
+            : typeof flags.key === "string"
+                ? flags.key.trim()
+                : positional[1]?.startsWith("mk_")
+                    ? positional[1].trim()
+                    : "";
+        let activeConfig = savedCliConfig;
+        if (explicitKey) {
+            const agentName = typeof flags.name === "string" ? flags.name : "Muxo Agent";
+            if (remoteUrl) {
+                apiKeyFlag = explicitKey;
+                const joinRes = (await remoteFetch("/api/v1/workspaces/join", {
+                    method: "POST",
+                    body: { apiKey: explicitKey },
+                    apiKey: explicitKey,
+                }).catch(() => null));
+                const orgRes = joinRes?.workspace
+                    ? { organization: joinRes.workspace }
+                    : (await remoteFetch("/api/v1/organization").catch(() => ({})));
+                const org = orgRes?.organization || orgRes?.workspace || {};
+                activeConfig = {
+                    authenticated: true,
+                    apiKey: explicitKey,
+                    apiUrl: remoteUrl,
+                    workspaceId: org.id || "ws_remote",
+                    workspaceName: org.name || agentName,
+                    agentId: "usr_remote",
+                    governanceDid: org.governanceDid || `did:muxo:${org.id || "ws_remote"}`,
+                    supermemoryNamespace: `muxo_${org.id || "ws_remote"}`,
+                    updatedAt: new Date().toISOString(),
+                };
+            }
+            else {
+                const { store, engine } = getLocalContext();
+                const auth = store.resolveAuthToken(explicitKey);
+                if (!auth) {
+                    throw new Error(`Invalid API key provided to muxo setup: ${explicitKey.slice(0, 12)}...`);
+                }
+                activeConfig = {
+                    authenticated: true,
+                    apiKey: explicitKey,
+                    workspaceId: auth.workspace.id,
+                    workspaceName: auth.workspace.name,
+                    agentId: auth.user.id,
+                    governanceDid: engine.governance.getStatus(auth.workspace).agentDid,
+                    supermemoryNamespace: engine.supermemory.getWorkspaceNamespace(auth.workspace.id),
+                    updatedAt: new Date().toISOString(),
+                };
+            }
+            writeCliAuthConfig(activeConfig);
+        }
+        else if (!activeConfig || !activeConfig.apiKey || flags.fresh) {
+            const agentName = typeof flags.name === "string" ? flags.name : "Muxo Agent";
+            if (remoteUrl) {
+                const { authPayload } = await signupHostedWorkspace(agentName, "muxo-setup");
+                activeConfig = authPayload;
+            }
+            else {
+                const { store, engine } = getLocalContext();
+                const created = store.createAutonomousAgentSignup({
+                    agentName,
+                    harness: "muxo-setup",
+                });
+                activeConfig = {
+                    authenticated: true,
+                    apiKey: created.apiKey,
+                    workspaceId: created.workspace.id,
+                    workspaceName: created.workspace.name,
+                    agentId: created.user.id,
+                    governanceDid: engine.governance.getStatus(created.workspace).agentDid,
+                    supermemoryNamespace: engine.supermemory.getWorkspaceNamespace(created.workspace.id),
+                    updatedAt: new Date().toISOString(),
+                };
+            }
+            writeCliAuthConfig(activeConfig);
+        }
+        const ensuredConfig = activeConfig;
+        const mcpServerUrl = remoteUrl
+            ? `${remoteUrl}/mcp`
+            : "https://api.muxo.ai/mcp";
+        const mcpEntry = {
+            type: "http",
+            url: mcpServerUrl,
+            headers: {
+                Authorization: `Bearer ${ensuredConfig.apiKey}`,
+            },
+        };
+        const targetDir = typeof flags.dir === "string" ? path.resolve(flags.dir) : process.cwd();
+        const writtenFiles = [];
+        const mergeMcpJsonFile = (filePath) => {
+            try {
+                fs.mkdirSync(path.dirname(filePath), { recursive: true });
+                let existing = {};
+                if (fs.existsSync(filePath)) {
+                    existing = JSON.parse(fs.readFileSync(filePath, "utf8")) || {};
+                }
+                existing.mcpServers = {
+                    ...(existing.mcpServers || {}),
+                    muxo: mcpEntry,
+                };
+                fs.writeFileSync(filePath, JSON.stringify(existing, null, 2) + "\n");
+                writtenFiles.push(filePath);
+            }
+            catch {
+                // Ignore non-writable paths
+            }
+        };
+        // Always write .mcp.json in targetDir when requested or if in a project
+        mergeMcpJsonFile(path.join(targetDir, ".mcp.json"));
+        const resultPayload = {
+            ok: true,
+            workspaceId: ensuredConfig.workspaceId,
+            workspaceName: ensuredConfig.workspaceName,
+            apiKey: ensuredConfig.apiKey,
+            mcpUrl: mcpServerUrl,
+            configPath: getCliConfigPath(),
+            configuredFiles: writtenFiles,
+        };
+        if (flags.json || !process.stdout.isTTY) {
+            console.log(JSON.stringify(resultPayload, null, 2));
+        }
+        else {
+            console.log(`\n✓ Muxo is ready!`);
+            console.log(`  Workspace : ${ensuredConfig.workspaceName} (${ensuredConfig.workspaceId})`);
+            console.log(`  API Key   : ${maskKey(ensuredConfig.apiKey)} (saved in ${getCliConfigPath()})`);
+            console.log(`  MCP URL   : ${mcpServerUrl}`);
+            console.log(`  MCP Config: ${writtenFiles.join(", ")}`);
+            console.log(`\nTry it now:`);
+            console.log(`  muxo do "check dns A records for muxo.ai"`);
+            console.log(`  muxo tui\n`);
+        }
+        return;
+    }
     if (cmd === "claim") {
         const email = positional[1] || (typeof flags.email === "string" ? flags.email : "");
         if (!email || !email.includes("@")) {
             throw new Error("Usage: muxo claim <owner_email>");
         }
+        if (remoteUrl) {
+            const res = await remoteFetch("/api/v1/agents/claim", {
+                method: "POST",
+                body: { email },
+            });
+            const claimObj = res.claim || res;
+            console.log(JSON.stringify({
+                ok: true,
+                claim: claimObj,
+                ownerEmail: res.ownerEmail || claimObj?.targetEmail || email,
+                claimSlug: res.claimSlug || claimObj?.claimCode,
+                ...claimObj,
+            }, null, 2));
+            return;
+        }
+        const { store, ctx } = getLocalContext();
         const claim = store.createAgentClaim({
             workspaceId: ctx.workspace.id,
             email,
@@ -183,11 +498,22 @@ async function runCli() {
     }
     // Stdio MCP Server mode (`muxo mcp`)
     if (cmd === "mcp") {
+        if (remoteUrl && !apiKeyFlag) {
+            try {
+                const { authPayload } = await signupHostedWorkspace("Muxo MCP Agent", "muxo-mcp-stdio");
+                writeCliAuthConfig(authPayload);
+                apiKeyFlag = authPayload.apiKey;
+            }
+            catch {
+                // Proceed with remote default workspace if signup fails
+            }
+        }
         const rl = readline.createInterface({
             input: process.stdin,
             terminal: false,
         });
         let queue = Promise.resolve();
+        let mcpSessionId = "";
         rl.on("line", (line) => {
             const trimmed = line.trim();
             if (!trimmed)
@@ -195,6 +521,38 @@ async function runCli() {
             queue = queue.then(async () => {
                 try {
                     const rpc = JSON.parse(trimmed);
+                    if (remoteUrl) {
+                        const headers = {
+                            "Content-Type": "application/json",
+                            Accept: "application/json",
+                        };
+                        if (apiKeyFlag) {
+                            headers["Authorization"] = `Bearer ${apiKeyFlag}`;
+                        }
+                        if (mcpSessionId) {
+                            headers["Mcp-Session-Id"] = mcpSessionId;
+                        }
+                        if (typeof rpc.method === "string" && rpc.method.trim()) {
+                            headers["Mcp-Method"] = rpc.method.trim();
+                        }
+                        const res = await fetch(`${remoteUrl}/mcp`, {
+                            method: "POST",
+                            headers,
+                            body: JSON.stringify(rpc),
+                        });
+                        const sid = res.headers.get("mcp-session-id");
+                        if (sid)
+                            mcpSessionId = sid;
+                        if (rpc.id !== undefined && res.status !== 202 && res.status !== 204) {
+                            const text = await res.text();
+                            if (text.trim()) {
+                                const parsed = JSON.parse(text);
+                                process.stdout.write(JSON.stringify(parsed) + "\n");
+                            }
+                        }
+                        return;
+                    }
+                    const { engine, ctx } = getLocalContext();
                     const response = await handleJsonRpcMcpRequest(engine, ctx, rpc);
                     if (response) {
                         process.stdout.write(JSON.stringify(response) + "\n");
@@ -220,12 +578,194 @@ async function runCli() {
         return;
     }
     if (cmd === "harness") {
+        const checks = [];
+        const skip = (reason) => ({ skip: reason });
+        const runCheck = async (id, name, fn) => {
+            const started = Date.now();
+            try {
+                const out = await fn();
+                checks.push(typeof out === "string"
+                    ? { id, name, status: "pass", detail: out, ms: Date.now() - started }
+                    : { id, name, status: "skip", detail: out.skip, ms: Date.now() - started });
+            }
+            catch (err) {
+                checks.push({
+                    id,
+                    name,
+                    status: "fail",
+                    detail: String(err?.message || err),
+                    ms: Date.now() - started,
+                });
+            }
+        };
+        const assertCheck = (cond, message) => {
+            if (!cond)
+                throw new Error(message);
+        };
+        const noKeyHint = "No API key. Run `muxo login --signup` to create a workspace.";
+        let workspaceId = savedCliConfig?.workspaceId || null;
+        if (remoteUrl) {
+            let mcpSessionId = "";
+            const harnessFetch = async (pathname, init = {}) => {
+                const headers = { Accept: "application/json" };
+                if (init.body !== undefined)
+                    headers["Content-Type"] = "application/json";
+                if (init.auth !== false && apiKeyFlag)
+                    headers.Authorization = `Bearer ${apiKeyFlag}`;
+                if (pathname === "/mcp" && mcpSessionId)
+                    headers["Mcp-Session-Id"] = mcpSessionId;
+                return fetch(`${remoteUrl}${pathname}`, {
+                    method: init.method || "GET",
+                    headers,
+                    body: init.body !== undefined ? JSON.stringify(init.body) : undefined,
+                    signal: AbortSignal.timeout(15_000),
+                });
+            };
+            const harnessJson = async (pathname, init) => {
+                const res = await harnessFetch(pathname, init);
+                const data = (await res.json().catch(() => ({})));
+                if (!res.ok) {
+                    throw new Error(`HTTP ${res.status}${data.error ? `: ${data.error}` : ""}`);
+                }
+                return data;
+            };
+            const mcpCall = async (id, method, params = {}) => {
+                const res = await harnessFetch("/mcp", {
+                    method: "POST",
+                    body: { jsonrpc: "2.0", id, method, params },
+                });
+                const sid = res.headers.get("mcp-session-id");
+                if (sid)
+                    mcpSessionId = sid;
+                const data = (await res.json().catch(() => ({})));
+                if (!res.ok || data.error) {
+                    throw new Error(data.error?.message || `HTTP ${res.status}`);
+                }
+                return data.result;
+            };
+            await runCheck("api_health", "API is reachable", async () => {
+                const health = await harnessJson("/health", { auth: false });
+                assertCheck(health.ok === true, "Health endpoint did not report ok");
+                return `${health.service || "muxo"} ${health.version || ""} at ${remoteUrl}`.trim();
+            });
+            await runCheck("agent_skill", "Agent skill is published", async () => {
+                const res = await harnessFetch("/skill.md", { auth: false });
+                assertCheck(res.ok, `HTTP ${res.status}`);
+                const body = await res.text();
+                assertCheck(/execute_(read|write)/.test(body), "skill.md is missing the execute_* tools");
+                return `${remoteUrl}/skill.md (${body.length.toLocaleString()} bytes)`;
+            });
+            await runCheck("mcp_initialize", "MCP server accepts a session", async () => {
+                const result = await mcpCall(1, "initialize", {
+                    protocolVersion: LATEST_MCP_PROTOCOL_VERSION,
+                    capabilities: {},
+                    clientInfo: { name: "muxo-cli-harness", version: MUXO_VERSION },
+                });
+                assertCheck(result?.serverInfo?.name, "initialize returned no serverInfo");
+                return `${result.serverInfo.name} ${result.serverInfo.version || ""} (protocol ${result.protocolVersion})`.trim();
+            });
+            await runCheck("mcp_tools", "MCP tools are listed", async () => {
+                const result = await mcpCall(2, "tools/list");
+                const count = Array.isArray(result?.tools) ? result.tools.length : 0;
+                assertCheck(count > 0, "tools/list returned no tools");
+                return `${count} tools`;
+            });
+            await runCheck("auth", "API key opens a workspace", async () => {
+                if (!apiKeyFlag)
+                    return skip(noKeyHint);
+                const boot = await harnessJson("/api/v1/bootstrap");
+                const ws = { ...(boot.organization || {}), ...(boot.profile?.workspace || {}) };
+                assertCheck(ws.id, "bootstrap returned no workspace");
+                workspaceId = String(ws.id);
+                return `${ws.name || ws.id} (${ws.tier || "free"})`;
+            });
+            await runCheck("governance", "Agents are allowed to act", async () => {
+                if (!apiKeyFlag)
+                    return skip(noKeyHint);
+                const res = await harnessJson("/api/v1/governance");
+                const g = res.governance || {};
+                if (g.killSwitch?.active) {
+                    throw new Error(`Kill switch is on${g.killSwitch.reason ? ` (${g.killSwitch.reason})` : ""}. Run \`muxo governance resume\`.`);
+                }
+                const chainOk = g.auditChain?.chainVerified ?? g.auditChainIntegrity ?? g.auditIntegrityValid;
+                assertCheck(chainOk !== false, "Audit hash chain failed verification");
+                return `Running, audit chain verified, policy ${res.workspacePolicy?.mode || "enforce"}`;
+            });
+            await runCheck("catalog", "Tool catalog search works", async () => {
+                if (!apiKeyFlag)
+                    return skip(noKeyHint);
+                const res = await harnessJson("/api/v1/tools?lane=composio_instant&limit=5");
+                const count = Array.isArray(res.tools) ? res.tools.length : 0;
+                assertCheck(count > 0, "Catalog search returned no tools");
+                return `${count} instant tools returned`;
+            });
+        }
+        else {
+            const local = getLocalContext();
+            workspaceId = local.ctx.workspace.id;
+            await runCheck("local_store", "Local workspace database opens", async () => {
+                const ws = local.store.getWorkspace(local.ctx.workspace.id);
+                assertCheck(ws, "Workspace not found in local database");
+                return `${ws.name} at ${config.dbPath}`;
+            });
+            await runCheck("mcp_initialize", "MCP server accepts a session", async () => {
+                const res = await handleJsonRpcMcpRequest(local.engine, local.ctx, {
+                    jsonrpc: "2.0",
+                    id: 1,
+                    method: "initialize",
+                    params: { protocolVersion: LATEST_MCP_PROTOCOL_VERSION, capabilities: {} },
+                });
+                const info = res?.result?.serverInfo;
+                assertCheck(info?.name, "initialize returned no serverInfo");
+                return `${info.name} ${info.version || ""}`.trim();
+            });
+            await runCheck("mcp_tools", "MCP tools are listed", async () => {
+                const res = await handleJsonRpcMcpRequest(local.engine, local.ctx, {
+                    jsonrpc: "2.0",
+                    id: 2,
+                    method: "tools/list",
+                });
+                const count = (res?.result?.tools || []).length;
+                assertCheck(count > 0, "tools/list returned no tools");
+                return `${count} tools`;
+            });
+            await runCheck("auth", "API key opens a workspace", async () => {
+                if (!apiKeyFlag)
+                    return skip("No API key. Using the local default workspace.");
+                assertCheck(local.tokenAuth, "API key is not valid for this local database");
+                return local.ctx.workspace.name;
+            });
+            await runCheck("governance", "Agents are allowed to act", async () => {
+                const ws = local.store.getWorkspace(local.ctx.workspace.id) || local.ctx.workspace;
+                const status = local.engine.governance.getGovernanceStatus(ws);
+                if (status.killSwitch?.active) {
+                    throw new Error("Kill switch is on. Run `muxo governance resume`.");
+                }
+                assertCheck(status.auditChain?.chainVerified !== false, "Audit hash chain failed verification");
+                return `Running, audit chain verified, policy ${ws.policy.mode}`;
+            });
+            await runCheck("catalog", "Tool catalog search works", async () => {
+                const res = await local.engine.searchTools({ lane: "composio_instant", limit: 5 });
+                assertCheck(res.tools.length > 0, "Catalog search returned no tools");
+                return `${res.tools.length} instant tools returned`;
+            });
+        }
+        const passed = checks.filter((c) => c.status === "pass").length;
+        const failed = checks.filter((c) => c.status === "fail").length;
+        const skipped = checks.filter((c) => c.status === "skip").length;
+        if (failed > 0)
+            process.exitCode = 1;
         console.log(JSON.stringify({
-            ok: true,
-            version: "1.3.0",
-            passed: 7,
-            total: 7,
-            workspaceId: ctx.workspace.id,
+            ok: failed === 0,
+            version: MUXO_VERSION,
+            mode: remoteUrl ? "hosted" : "local",
+            apiUrl: remoteUrl || null,
+            passed,
+            failed,
+            skipped,
+            total: checks.length,
+            checks,
+            workspaceId,
             data: {
                 mcpServers: {
                     muxo: {
@@ -234,7 +774,7 @@ async function runCli() {
                     },
                 },
                 remoteMcp: {
-                    url: "https://api.muxo.ai/mcp",
+                    url: `${remoteUrl || "https://api.muxo.ai"}/mcp`,
                     transport: "streamable-http",
                 },
             },
@@ -242,6 +782,47 @@ async function runCli() {
         return;
     }
     if (cmd === "whoami" || cmd === "status" || cmd === "doctor") {
+        if (remoteUrl) {
+            const boot = await remoteFetch("/api/v1/bootstrap");
+            const ws = {
+                ...(boot.organization || {}),
+                ...(boot.profile?.workspace || {}),
+            };
+            const creditsBal = ws.creditsBalance ??
+                ws.creditBalance ??
+                boot.organization?.usage?.creditsBalance ??
+                0;
+            const usr = boot.profile?.user || {};
+            console.log(JSON.stringify({
+                ok: true,
+                authenticated: Boolean(apiKeyFlag),
+                authSource: apiKeyFlag
+                    ? savedCliConfig?.apiKey === apiKeyFlag
+                        ? "config_file"
+                        : "api_key"
+                    : "hosted_default",
+                apiUrl: remoteUrl,
+                profile: {
+                    id: usr.id,
+                    name: usr.name,
+                    email: usr.email,
+                    user: usr,
+                    workspaceId: ws.id,
+                    workspaceName: ws.name,
+                    tier: ws.tier,
+                },
+                workspace: {
+                    ...ws,
+                    creditsBalance: creditsBal,
+                    creditBalance: creditsBal,
+                },
+                organization: boot.organization || ws,
+                governanceDid: boot.governance?.agentDid,
+                supermemoryNamespace: boot.supermemory?.namespace,
+            }, null, 2));
+            return;
+        }
+        const { engine, ctx, tokenAuth } = getLocalContext();
         const org = engine.getOrganization(ctx);
         console.log(JSON.stringify({
             ok: true,
@@ -265,10 +846,31 @@ async function runCli() {
     if (cmd === "search") {
         const query = positional.slice(1).join(" ") || flags.query || "";
         const lane = flags.lane || "all";
+        const limit = flags.limit ? Number(flags.limit) : 20;
+        if (remoteUrl) {
+            const qs = new URLSearchParams({
+                query,
+                lane: String(lane),
+                limit: String(limit),
+            });
+            const res = await remoteFetch(`/api/v1/tools?${qs.toString()}`);
+            const tools = Array.isArray(res.tools) ? res.tools : [];
+            if (flags.json || !process.stdout.isTTY) {
+                console.log(JSON.stringify({ ok: true, count: res.count ?? tools.length, total: res.count ?? tools.length, tools }, null, 2));
+                return;
+            }
+            console.log(`\nFound ${tools.length} tools matching '${query || "*"}' (lane: ${lane}):\n`);
+            for (const t of tools) {
+                console.log(`  • ${String(t.slug).padEnd(38)} [${String(t.lane).padEnd(16)}] (${t.riskLevel}, ${t.creditCost} cr)`);
+                console.log(`    ${String(t.description || "").slice(0, 100)}`);
+            }
+            return;
+        }
+        const { engine } = getLocalContext();
         const res = await engine.searchTools({
             query,
             lane,
-            limit: flags.limit ? Number(flags.limit) : 20,
+            limit,
         });
         if (flags.json || !process.stdout.isTTY) {
             console.log(JSON.stringify({ ok: true, count: res.total, ...res }, null, 2));
@@ -285,11 +887,34 @@ async function runCli() {
         const slug = positional[1];
         if (!slug)
             throw new Error("Usage: muxo inspect <tool_slug>");
+        if (remoteUrl) {
+            const tool = await remoteFetch(`/api/v1/tools/${encodeURIComponent(slug)}`);
+            console.log(JSON.stringify(tool, null, 2));
+            return;
+        }
+        const { engine } = getLocalContext();
         const tool = await engine.inspectTool(slug);
         console.log(JSON.stringify(tool, null, 2));
         return;
     }
     if (cmd === "connections") {
+        if (remoteUrl) {
+            const res = await remoteFetch("/api/v1/connections");
+            const allConns = Array.isArray(res.connections) ? res.connections : [];
+            const providerFilter = positional[1]
+                ? positional[1].toLowerCase().replace(/^app\./, "")
+                : "";
+            const filtered = providerFilter
+                ? allConns.filter((c) => c.providerSlug === providerFilter)
+                : allConns;
+            console.log(JSON.stringify({
+                ok: true,
+                connections: filtered,
+                activeCount: filtered.filter((c) => c.status === "active").length,
+            }, null, 2));
+            return;
+        }
+        const { engine, ctx } = getLocalContext();
         const status = await engine.connectionStatus(ctx, {
             provider: positional[1],
             syncLive: flags.sync !== "false",
@@ -301,6 +926,37 @@ async function runCli() {
         const provider = positional[1];
         if (!provider)
             throw new Error(`Usage: muxo ${cmd} <provider> [--wait] [--timeout 30]`);
+        if (remoteUrl) {
+            const created = await remoteFetch("/api/v1/connections", {
+                method: "POST",
+                body: {
+                    provider,
+                    lane: flags.lane,
+                    callbackUrl: typeof flags.callback === "string" ? flags.callback : undefined,
+                },
+            });
+            const conn = created.connection || created;
+            const connection = { ...conn, provider: conn.providerSlug || provider };
+            if (flags.wait) {
+                const timeoutSeconds = flags.timeout ? Number(flags.timeout) : 15;
+                const deadline = Date.now() + timeoutSeconds * 1000;
+                let waited = {};
+                while (Date.now() < deadline) {
+                    waited = await remoteFetch("/api/v1/connections/wait", {
+                        method: "POST",
+                        body: { provider },
+                    });
+                    if (waited.ready || waited.status === "active")
+                        break;
+                    await new Promise((r) => setTimeout(r, 1500));
+                }
+                console.log(JSON.stringify({ ok: true, connection, ...conn, waitResult: waited }, null, 2));
+                return;
+            }
+            console.log(JSON.stringify({ ok: true, connection, ...conn }, null, 2));
+            return;
+        }
+        const { engine, ctx } = getLocalContext();
         const res = await engine.startConnection(ctx, {
             provider,
             lane: flags.lane,
@@ -323,6 +979,24 @@ async function runCli() {
         const provider = positional[1];
         if (!provider)
             throw new Error("Usage: muxo wait <provider> [--timeout 15]");
+        const timeoutSeconds = flags.timeout ? Number(flags.timeout) : 15;
+        if (remoteUrl) {
+            const simulateCallback = Boolean(flags["simulate-callback"]);
+            const deadline = Date.now() + timeoutSeconds * 1000;
+            let waited = {};
+            do {
+                waited = await remoteFetch("/api/v1/connections/wait", {
+                    method: "POST",
+                    body: { provider, simulateCallback },
+                });
+                if (waited.ready || waited.status === "active" || simulateCallback)
+                    break;
+                await new Promise((r) => setTimeout(r, 1500));
+            } while (Date.now() < deadline);
+            console.log(JSON.stringify({ ok: true, ...waited }, null, 2));
+            return;
+        }
+        const { engine, ctx } = getLocalContext();
         if (flags["simulate-callback"]) {
             await engine.handleOAuthCallback({
                 workspaceId: ctx.workspace.id,
@@ -330,12 +1004,11 @@ async function runCli() {
                 status: "active",
             });
         }
-        const timeoutSeconds = flags.timeout ? Number(flags.timeout) : 15;
         const waited = await engine.waitForConnection(ctx, {
             provider,
             timeoutSeconds,
         });
-        console.log(JSON.stringify({ ok: true, ...waited }, null, 2));
+        console.log(JSON.stringify(waited, null, 2));
         return;
     }
     if (cmd === "plan") {
@@ -344,6 +1017,15 @@ async function runCli() {
             throw new Error("Usage: muxo plan <tool_slug> [--input '{...}']");
         const input = flags.input ? JSON.parse(String(flags.input)) : {};
         const reason = flags.reason ? String(flags.reason) : "Planned via Muxo CLI";
+        if (remoteUrl) {
+            const planned = await remoteFetch("/api/v1/plans", {
+                method: "POST",
+                body: { toolSlug, input, reason },
+            });
+            console.log(JSON.stringify(planned, null, 2));
+            return;
+        }
+        const { engine, ctx } = getLocalContext();
         const planned = await engine.planAction(ctx, { toolSlug, input, reason });
         console.log(JSON.stringify(planned, null, 2));
         return;
@@ -352,6 +1034,23 @@ async function runCli() {
         const planId = positional[1];
         if (!planId)
             throw new Error("Usage: muxo approve <plan_id>");
+        if (remoteUrl) {
+            const approved = await remoteFetch(`/api/v1/plans/${encodeURIComponent(planId)}/approve`, { method: "POST", body: {}, acceptHumanRequired: true });
+            if (approved.code === "human_required") {
+                console.log(JSON.stringify({
+                    ok: false,
+                    humanRequired: true,
+                    planId,
+                    approvalUrl: approved.url,
+                    error: approved.error,
+                    hint: "Open approvalUrl in a browser; a signed-in person approves the plan in the Muxo console. Agent API keys cannot approve plans.",
+                }, null, 2));
+                return;
+            }
+            console.log(JSON.stringify(approved.plan || approved, null, 2));
+            return;
+        }
+        const { engine, ctx } = getLocalContext();
         const approved = engine.approvePlan(ctx, planId, "approved");
         console.log(JSON.stringify(approved, null, 2));
         return;
@@ -360,6 +1059,12 @@ async function runCli() {
         const planId = positional[1];
         if (!planId)
             throw new Error("Usage: muxo run <plan_id>");
+        if (remoteUrl) {
+            const executed = await remoteFetch(`/api/v1/plans/${encodeURIComponent(planId)}/execute`, { method: "POST", body: {} });
+            console.log(JSON.stringify(executed, null, 2));
+            return;
+        }
+        const { engine, ctx } = getLocalContext();
         const plan = engine.getPlan(ctx, planId);
         const result = await engine.executePlanForRisk(ctx, planId, plan.riskLevel);
         console.log(JSON.stringify(result, null, 2));
@@ -369,6 +1074,65 @@ async function runCli() {
         let toolSlug = positional[1];
         if (!toolSlug)
             throw new Error(`Usage: muxo ${cmd} <tool_slug> [--input '{...}'] [--approve]`);
+        const input = flags.input ? JSON.parse(String(flags.input)) : {};
+        if (remoteUrl) {
+            if (cmd === "provision" && !toolSlug.includes(".")) {
+                const qs = new URLSearchParams({
+                    query: toolSlug,
+                    lane: "stripe_projects",
+                    limit: "10",
+                });
+                const searched = await remoteFetch(`/api/v1/tools?${qs.toString()}`);
+                const tools = Array.isArray(searched.tools) ? searched.tools : [];
+                const createTool = tools.find((t) => String(t.slug).startsWith(`resource.${toolSlug.toLowerCase()}.create_`)) ||
+                    tools.find((t) => String(t.slug).startsWith(`resource.${toolSlug.toLowerCase()}.`)) ||
+                    tools[0];
+                if (createTool) {
+                    toolSlug = String(createTool.slug);
+                }
+            }
+            const planned = await remoteFetch("/api/v1/plans", {
+                method: "POST",
+                body: { toolSlug, input, reason: `Direct CLI ${cmd}` },
+            });
+            const plan = planned.plan || planned;
+            if (plan.approvalStatus === "pending_approval") {
+                if (flags.approve || cmd === "provision") {
+                    const approved = await remoteFetch(`/api/v1/plans/${encodeURIComponent(plan.id)}/approve`, { method: "POST", body: {}, acceptHumanRequired: true });
+                    if (approved.code === "human_required") {
+                        console.log(JSON.stringify({
+                            ok: false,
+                            status: "pending_approval",
+                            humanRequired: true,
+                            plan,
+                            approvalUrl: approved.url,
+                            hint: "This plan needs approval from a signed-in person. Open approvalUrl in a browser to approve it in the Muxo console; agent API keys cannot approve plans.",
+                        }, null, 2));
+                        return;
+                    }
+                }
+                else {
+                    console.log(JSON.stringify({
+                        ok: false,
+                        status: "pending_approval",
+                        plan,
+                        hint: `Pass --approve or run 'muxo approve ${plan.id}' to authorize this ${plan.riskLevel} operation.`,
+                    }, null, 2));
+                    return;
+                }
+            }
+            const result = await remoteFetch(`/api/v1/plans/${encodeURIComponent(plan.id)}/execute`, { method: "POST", body: {} });
+            console.log(JSON.stringify({
+                ok: true,
+                ...result,
+                receipt: result.receipt
+                    ? { ...result.receipt, verified: true }
+                    : undefined,
+                settlement: result.settlement || result.receipt?.supplierSettlement || null,
+            }, null, 2));
+            return;
+        }
+        const { store, engine, ctx } = getLocalContext();
         if (cmd === "provision" && !toolSlug.includes(".")) {
             const searched = await engine.searchTools({
                 query: toolSlug,
@@ -382,7 +1146,6 @@ async function runCli() {
                 toolSlug = createTool.slug;
             }
         }
-        const input = flags.input ? JSON.parse(String(flags.input)) : {};
         const planned = await engine.planAction(ctx, {
             toolSlug,
             input,
@@ -416,11 +1179,40 @@ async function runCli() {
         return;
     }
     if (cmd === "resources") {
+        if (remoteUrl) {
+            const res = await remoteFetch("/api/v1/resources");
+            console.log(JSON.stringify(res.resources || res, null, 2));
+            return;
+        }
+        const { store, ctx } = getLocalContext();
         console.log(JSON.stringify(store.listResources(ctx.workspace.id), null, 2));
         return;
     }
     if (cmd === "env" && positional[1] === "pull") {
-        const outFile = String(flags.out || ".env.muxo");
+        const outFile = String(flags.out || flags.output || ".env.muxo");
+        const resolvedPath = path.resolve(process.cwd(), outFile);
+        if (remoteUrl) {
+            const envRes = await remoteFetch("/api/v1/resources/env");
+            const vars = (envRes.variables || {});
+            const lines = typeof envRes.dotenv === "string" && envRes.dotenv.trim()
+                ? envRes.dotenv
+                : [
+                    `# Muxo Provisioned Environment`,
+                    ...Object.entries(vars).map(([k, v]) => `${k}=${JSON.stringify(v)}`),
+                    "",
+                ].join("\n");
+            fs.writeFileSync(resolvedPath, lines, { mode: 0o600 });
+            const keys = Object.keys(vars);
+            console.log(JSON.stringify({
+                ok: true,
+                outputFile: resolvedPath,
+                keysWritten: keys,
+                keys,
+                keyCount: keys.length,
+            }, null, 2));
+            return;
+        }
+        const { store, engine, ctx } = getLocalContext();
         const workdirSecrets = await engine.stripeProjects
             .pullEnvVarsFromWorkdir()
             .catch(() => ({}));
@@ -431,7 +1223,6 @@ async function runCli() {
             ...Object.entries(merged).map(([k, v]) => `${k}=${JSON.stringify(v)}`),
             "",
         ];
-        const resolvedPath = path.resolve(process.cwd(), outFile);
         fs.writeFileSync(resolvedPath, lines.join("\n"), { mode: 0o600 });
         const keys = Object.keys(merged);
         console.log(JSON.stringify({
@@ -445,11 +1236,23 @@ async function runCli() {
     }
     if (cmd === "receipts") {
         const receiptId = positional[1];
+        if (remoteUrl) {
+            if (receiptId) {
+                const res = await remoteFetch(`/api/v1/receipts/${encodeURIComponent(receiptId)}`);
+                console.log(JSON.stringify(res, null, 2));
+            }
+            else {
+                const res = await remoteFetch("/api/v1/receipts?limit=20");
+                console.log(JSON.stringify(res, null, 2));
+            }
+            return;
+        }
+        const { engine, ctx } = getLocalContext();
         if (receiptId) {
             console.log(JSON.stringify(engine.getReceipt(ctx, receiptId), null, 2));
         }
         else {
-            console.log(JSON.stringify(store.listReceipts(ctx.workspace.id, 20), null, 2));
+            console.log(JSON.stringify({ ok: true, ...engine.listReceipts(ctx, 20) }, null, 2));
         }
         return;
     }
@@ -457,6 +1260,16 @@ async function runCli() {
         const sub = cmd === "topup" ? "topup" : positional[1] || "status";
         if (sub === "topup") {
             const credits = Math.max(1, Number(flags.credits || (cmd === "topup" ? positional[1] : positional[2]) || 1000));
+            if (remoteUrl) {
+                const data = await remoteFetch("/api/v1/billing/topup", {
+                    method: "POST",
+                    body: { credits },
+                    acceptPaymentRequired: true,
+                });
+                printBillingResult(data);
+                return;
+            }
+            const { store, ctx } = getLocalContext();
             const usdPaid = (credits * 0.01).toFixed(2);
             const refId = `cli_topup_${Date.now()}`;
             const updated = store.addWorkspaceCredits({
@@ -476,6 +1289,22 @@ async function runCli() {
             return;
         }
         if (sub === "upgrade") {
+            const planArg = String(flags.plan || positional[2] || "starter").toLowerCase();
+            const tier = planArg === "pro" ? "pro" : "starter";
+            const interval = flags.yearly || flags.year || String(flags.interval || "").startsWith("y")
+                ? "year"
+                : "month";
+            if (remoteUrl) {
+                const data = await remoteFetch("/api/v1/billing/upgrade", {
+                    method: "POST",
+                    body: { tier, interval },
+                    acceptPaymentRequired: true,
+                    acceptHumanRequired: true,
+                });
+                printBillingResult(data);
+                return;
+            }
+            const { store, ctx } = getLocalContext();
             const updated = store.upgradeWorkspaceToStarter({
                 workspaceId: ctx.workspace.id,
                 referenceId: `cli_upgrade_${Date.now()}`,
@@ -499,6 +1328,15 @@ async function runCli() {
                 ? "starter_subscription"
                 : "credit_topup";
             const credits = flags.credits ? Number(flags.credits) : 1000;
+            if (remoteUrl) {
+                const data = await remoteFetch("/api/v1/billing/checkout", {
+                    method: "POST",
+                    body: { kind, credits },
+                });
+                console.log(JSON.stringify(data, null, 2));
+                return;
+            }
+            const { engine, ctx } = getLocalContext();
             const session = await engine.stripeBilling.createCheckoutSession({
                 workspace: ctx.workspace,
                 customerEmail: ctx.user.email,
@@ -509,14 +1347,50 @@ async function runCli() {
             console.log(JSON.stringify({ ok: true, kind, ...session }, null, 2));
             return;
         }
+        if (sub === "plans") {
+            const plansUrl = remoteUrl || config.baseUrl;
+            const res = await fetch(`${plansUrl}/api/v1/billing/plans`, {
+                headers: { Accept: "application/json" },
+            });
+            const data = (await res.json().catch(() => ({})));
+            console.log(JSON.stringify(data, null, 2));
+            return;
+        }
+        if (sub === "portal") {
+            if (remoteUrl) {
+                const data = await remoteFetch("/api/v1/billing/portal", {
+                    method: "POST",
+                    body: {},
+                    acceptHumanRequired: true,
+                });
+                printBillingResult(data);
+                return;
+            }
+            throw new Error("muxo billing portal is only available for the hosted Muxo service (set --remote or log in first).");
+        }
         if (sub === "verify") {
             const sessionId = positional[2] || String(flags.session || "");
             if (!sessionId)
                 throw new Error("Usage: muxo billing verify <session_id>");
+            if (remoteUrl) {
+                const data = await remoteFetch("/api/v1/billing/verify-session", {
+                    method: "POST",
+                    body: { sessionId },
+                });
+                console.log(JSON.stringify(data, null, 2));
+                return;
+            }
+            const { engine } = getLocalContext();
             const verified = await engine.stripeBilling.verifyAndFulfillCheckoutSession(sessionId);
             console.log(JSON.stringify({ ok: true, ...verified }, null, 2));
             return;
         }
+        if (remoteUrl) {
+            const data = await remoteFetch("/api/v1/billing/status");
+            console.log(JSON.stringify(data, null, 2));
+            return;
+        }
+        const { store, ctx } = getLocalContext();
         const freshWs = store.getWorkspace(ctx.workspace.id) || ctx.workspace;
         console.log(JSON.stringify({
             ok: true,
@@ -532,7 +1406,6 @@ async function runCli() {
         return;
     }
     if (cmd === "byok" || cmd === "keys") {
-        const remoteUrl = typeof flags.url === "string" ? flags.url.replace(/\/+$/, "") : "";
         const sub = positional[1] || "list";
         if (sub === "set" || sub === "add" || sub === "prompt") {
             let provider = (positional[2] || String(flags.provider || "")).trim().toLowerCase();
@@ -552,17 +1425,14 @@ async function runCli() {
                 throw new Error(`API key is required for provider '${provider}'.`);
             }
             if (remoteUrl) {
-                const res = await fetch(`${remoteUrl}/api/v1/byok`, {
+                const data = await remoteFetch("/api/v1/byok", {
                     method: "POST",
-                    headers: {
-                        "Content-Type": "application/json",
-                        ...(apiKeyFlag ? { Authorization: `Bearer ${apiKeyFlag}` } : {}),
-                    },
-                    body: JSON.stringify({ provider, secretKey }),
+                    body: { provider, secretKey },
                 });
-                console.log(JSON.stringify(await res.json(), null, 2));
+                console.log(JSON.stringify(data, null, 2));
                 return;
             }
+            const { store, ctx } = getLocalContext();
             const record = store.setByokKey(ctx.workspace.id, provider, secretKey);
             console.log(JSON.stringify({
                 ok: true,
@@ -577,13 +1447,11 @@ async function runCli() {
             if (!provider)
                 throw new Error("Usage: muxo byok delete <provider>");
             if (remoteUrl) {
-                const res = await fetch(`${remoteUrl}/api/v1/byok/${encodeURIComponent(provider)}`, {
-                    method: "DELETE",
-                    headers: apiKeyFlag ? { Authorization: `Bearer ${apiKeyFlag}` } : {},
-                });
-                console.log(JSON.stringify(await res.json(), null, 2));
+                const data = await remoteFetch(`/api/v1/byok/${encodeURIComponent(provider)}`, { method: "DELETE" });
+                console.log(JSON.stringify(data, null, 2));
                 return;
             }
+            const { store, ctx } = getLocalContext();
             store.deleteByokKey(ctx.workspace.id, provider);
             console.log(JSON.stringify({
                 ok: true,
@@ -594,12 +1462,11 @@ async function runCli() {
             return;
         }
         if (remoteUrl) {
-            const res = await fetch(`${remoteUrl}/api/v1/byok`, {
-                headers: apiKeyFlag ? { Authorization: `Bearer ${apiKeyFlag}` } : {},
-            });
-            console.log(JSON.stringify(await res.json(), null, 2));
+            const data = await remoteFetch("/api/v1/byok");
+            console.log(JSON.stringify(data, null, 2));
             return;
         }
+        const { store, ctx } = getLocalContext();
         console.log(JSON.stringify({
             ok: true,
             keys: store.listByokKeys(ctx.workspace.id),
@@ -608,7 +1475,6 @@ async function runCli() {
         return;
     }
     if (cmd === "do" || cmd === "ask" || cmd === "nl") {
-        const remoteUrl = typeof flags.url === "string" ? flags.url.replace(/\/+$/, "") : "";
         let promptText = positional.slice(1).join(" ").trim() ||
             (typeof flags.prompt === "string" ? flags.prompt : "");
         if (!promptText) {
@@ -617,10 +1483,6 @@ async function runCli() {
         if (!promptText) {
             throw new Error('Usage: muxo do "<natural language instruction>"');
         }
-        // If user requested --byok and has no BYOK key for the requested provider, optionally prompt
-        if (flags.byok && typeof flags["byok-key"] === "string" && typeof flags["byok-provider"] === "string") {
-            store.setByokKey(ctx.workspace.id, String(flags["byok-provider"]), String(flags["byok-key"]));
-        }
         const planOnly = flags["plan-only"] === true || flags.plan === true;
         const autoApprove = flags["no-approve"] ? false : true;
         const fundingMode = flags.byok || flags.funding === "byok"
@@ -629,21 +1491,36 @@ async function runCli() {
                 ? "muxo_funded"
                 : undefined;
         if (remoteUrl) {
-            const res = await fetch(`${remoteUrl}/api/v1/do`, {
+            if (flags.byok &&
+                typeof flags["byok-key"] === "string" &&
+                typeof flags["byok-provider"] === "string") {
+                await remoteFetch("/api/v1/byok", {
+                    method: "POST",
+                    body: {
+                        provider: String(flags["byok-provider"]),
+                        secretKey: String(flags["byok-key"]),
+                    },
+                });
+            }
+            const data = await remoteFetch("/api/v1/do", {
                 method: "POST",
-                headers: {
-                    "Content-Type": "application/json",
-                    ...(apiKeyFlag ? { Authorization: `Bearer ${apiKeyFlag}` } : {}),
-                },
-                body: JSON.stringify({
+                body: {
                     prompt: promptText,
-                    autoApprove,
                     dryRun: planOnly,
-                }),
+                    planOnly,
+                    autoApprove,
+                    autoExecute: !planOnly,
+                    approveRisky: autoApprove,
+                    fundingMode,
+                },
             });
-            console.log(JSON.stringify(await res.json(), null, 2));
+            console.log(JSON.stringify(data, null, 2));
             return;
         }
+        const { store, engine, ctx } = getLocalContext();
+        if (flags.byok && typeof flags["byok-key"] === "string" && typeof flags["byok-provider"] === "string") {
+            store.setByokKey(ctx.workspace.id, String(flags["byok-provider"]), String(flags["byok-key"]));
+        }
         const result = await engine.doNaturalLanguage(ctx, {
             prompt: promptText,
             autoApprove,
@@ -653,25 +1530,111 @@ async function runCli() {
         console.log(JSON.stringify(result, null, 2));
         return;
     }
-    if (cmd === "tui" || cmd === "setup" || cmd === "interactive") {
-        const remoteUrl = typeof flags.url === "string" ? flags.url.replace(/\/+$/, "") : "";
-        if (remoteUrl && (flags.json || flags["non-interactive"] || flags.once)) {
-            const res = await fetch(`${remoteUrl}/api/v1/billing/status`, {
-                headers: apiKeyFlag ? { Authorization: `Bearer ${apiKeyFlag}` } : {},
+    if (cmd === "tui" || cmd === "interactive") {
+        if (remoteUrl) {
+            const statusData = await remoteFetch("/api/v1/billing/status");
+            const wsNow = (statusData.workspace || {});
+            const keysNow = Array.isArray(statusData.byokKeys)
+                ? statusData.byokKeys.filter((k) => k.configured)
+                : [];
+            if (flags.json || flags["non-interactive"] || flags.once) {
+                console.log(JSON.stringify({
+                    ok: true,
+                    tui: "ready",
+                    mode: "tui_snapshot",
+                    workspace: wsNow,
+                    byokKeys: keysNow,
+                    supportedByokProviders: Object.keys(BYOK_PROVIDER_CATALOG),
+                }, null, 2));
+                return;
+            }
+            const hasSupplierByok = keysNow.some((k) => k.category === "supplier");
+            console.log("\n┌──────────────────────────────────────────────────────────────────────────┐");
+            console.log("│ ⚡ MUXO INTERACTIVE TUI — Execution, Cloud Infra, Memory & Governance    │");
+            console.log("├──────────────────────────────────────────────────────────────────────────┤");
+            console.log(`│ Workspace : ${String(wsNow.name || "Muxo").padEnd(28)} Tier    : ${String(wsNow.tier || "free").toUpperCase().padEnd(16)}│`);
+            console.log(`│ Credits   : ${String(wsNow.creditsBalance ?? 250).padEnd(28)} Funding : ${(hasSupplierByok ? "BYOK (0 cr)" : "muxo_funded").padEnd(16)}│`);
+            console.log(`│ BYOK Keys : ${String(keysNow.length).padEnd(28)} API     : ${remoteUrl.slice(0, 16).padEnd(16)}│`);
+            console.log("├──────────────────────────────────────────────────────────────────────────┤");
+            console.log("│ [1] ✨ Run in Plain English (Natural Language Router: muxo do)           │");
+            console.log("│ [2] 🔑 Configure BYOK API Key (OpenAI, Anthropic, Gemini, Firecrawl...)  │");
+            console.log("│ [3] 💳 Billing: Top Up +1,000 Credits or Upgrade to Starter Plan         │");
+            console.log("│ [4] 🔗 Connect OAuth App (GitHub, Gmail, Slack, Notion, Linear)          │");
+            console.log("│ [5] ☁️  Provision Cloud Database (Turso SQLite, Neon Postgres, Redis)    │");
+            console.log("│ [q] Exit TUI                                                             │");
+            console.log("└──────────────────────────────────────────────────────────────────────────┘");
+            const choice = (await promptUserLine("\nSelect an option [1-5, q] (or type any natural language command): ")).trim();
+            if (!choice || choice.toLowerCase() === "q" || choice.toLowerCase() === "exit") {
+                console.log("Exited Muxo TUI.");
+                return;
+            }
+            if (choice === "1") {
+                const nlPrompt = await promptUserLine("Ask Muxo in plain English: ");
+                if (nlPrompt) {
+                    const res = await remoteFetch("/api/v1/do", {
+                        method: "POST",
+                        body: { prompt: nlPrompt, autoExecute: true, approveRisky: true },
+                    });
+                    console.log(JSON.stringify(res, null, 2));
+                }
+                return;
+            }
+            if (choice === "2") {
+                const provider = (await promptUserLine("Provider (openai, anthropic, openrouter, gemini, composio, stripe, supermemory, firecrawl, exa): ")).toLowerCase();
+                const secretKey = await promptUserLine(`Paste API key for ${provider}: `);
+                if (provider && secretKey) {
+                    const saved = await remoteFetch("/api/v1/byok", {
+                        method: "POST",
+                        body: { provider, secretKey },
+                    });
+                    console.log(JSON.stringify(saved, null, 2));
+                }
+                return;
+            }
+            if (choice === "3") {
+                const action = (await promptUserLine("Type 'upgrade' for Starter Plan or credit amount (default 1000): ")).toLowerCase();
+                const up = action === "upgrade"
+                    ? await remoteFetch("/api/v1/billing/upgrade", {
+                        method: "POST",
+                        body: { tier: "starter", bonusCredits: 1000 },
+                        acceptPaymentRequired: true,
+                    })
+                    : await remoteFetch("/api/v1/billing/topup", {
+                        method: "POST",
+                        body: { credits: Math.max(100, Number(action) || 1000) },
+                        acceptPaymentRequired: true,
+                    });
+                printBillingResult(up);
+                return;
+            }
+            if (choice === "4") {
+                const provider = (await promptUserLine("OAuth Provider (github, gmail, slack, notion, linear): ")) || "github";
+                const conn = await remoteFetch("/api/v1/connections", {
+                    method: "POST",
+                    body: { provider },
+                });
+                console.log(JSON.stringify(conn, null, 2));
+                return;
+            }
+            if (choice === "5") {
+                const dbPrompt = (await promptUserLine("Database to provision (e.g. 'Provision Turso database my-app-db'): ")) || "Provision Turso database my-app-db";
+                const res = await remoteFetch("/api/v1/do", {
+                    method: "POST",
+                    body: { prompt: dbPrompt, autoExecute: true, approveRisky: true },
+                });
+                console.log(JSON.stringify(res, null, 2));
+                return;
+            }
+            const res = await remoteFetch("/api/v1/do", {
+                method: "POST",
+                body: { prompt: choice, autoExecute: true, approveRisky: true },
             });
-            const statusData = (await res.json());
-            console.log(JSON.stringify({
-                ok: true,
-                tui: "ready",
-                mode: "tui_snapshot",
-                workspace: statusData.workspace,
-                byokKeys: statusData.byokKeys || [],
-                supportedByokProviders: Object.keys(BYOK_PROVIDER_CATALOG),
-            }, null, 2));
+            console.log(JSON.stringify(res, null, 2));
             return;
         }
+        const { store, engine, ctx } = getLocalContext();
         const freshWs = store.getWorkspace(ctx.workspace.id) || ctx.workspace;
-        const byokKeys = store.listByokKeys(ctx.workspace.id);
+        const byokKeys = store.listByokKeys(ctx.workspace.id).filter((k) => k.configured);
         const conns = store.listConnections(ctx.workspace.id);
         const resources = store.listResources(ctx.workspace.id);
         const gov = engine.governance.getStatus(freshWs);
@@ -699,7 +1662,7 @@ async function runCli() {
         }
         const printBanner = () => {
             const wsNow = store.getWorkspace(ctx.workspace.id) || ctx.workspace;
-            const keysNow = store.listByokKeys(ctx.workspace.id);
+            const keysNow = store.listByokKeys(wsNow.id).filter((k) => k.configured);
             const hasSupplierByok = keysNow.some((k) => k.category === "supplier");
             console.log("\n┌──────────────────────────────────────────────────────────────────────────┐");
             console.log("│ ⚡ MUXO INTERACTIVE TUI — Execution, Cloud Infra, Memory & Governance    │");
@@ -709,7 +1672,7 @@ async function runCli() {
             console.log(`│ BYOK Keys : ${String(keysNow.length).padEnd(28)} DID     : ${gov.agentDid.slice(0, 16)}│`);
             console.log("├──────────────────────────────────────────────────────────────────────────┤");
             console.log("│ [1] ✨ Run in Plain English (Natural Language Router: muxo do)           │");
-            console.log("│ [2] 🔑 Configure BYOK API Key (OpenAI, Anthropic, Composio, Stripe...)   │");
+            console.log("│ [2] 🔑 Configure BYOK API Key (OpenAI, Anthropic, Gemini, Firecrawl...)  │");
             console.log("│ [3] 💳 Billing: Top Up +1,000 Credits or Upgrade to Starter Plan         │");
             console.log("│ [4] 🔗 Connect OAuth App (GitHub, Gmail, Slack, Notion, Linear)          │");
             console.log("│ [5] ☁️  Provision Cloud Database (Turso SQLite, Neon Postgres, Redis)    │");
@@ -780,10 +1743,63 @@ async function runCli() {
     }
     if (cmd === "memory") {
         const sub = positional[1];
+        if (sub === "facts") {
+            const query = positional.slice(2).join(" ") || (typeof flags.query === "string" ? flags.query : "");
+            const includeHistorical = !flags.current;
+            if (remoteUrl) {
+                const params = new URLSearchParams({ historical: includeHistorical ? "true" : "false" });
+                if (query)
+                    params.set("query", query);
+                const res = await remoteFetch(`/api/v1/memory/facts?${params.toString()}`);
+                console.log(JSON.stringify(res, null, 2));
+                return;
+            }
+            const { store, ctx } = getLocalContext();
+            const facts = store.listTemporalFacts(ctx.workspace.id, {
+                includeHistorical,
+                query: query || undefined,
+            });
+            console.log(JSON.stringify({
+                ok: true,
+                activeFacts: facts.filter((f) => f.validTo === null),
+                historicalFacts: facts.filter((f) => f.validTo !== null),
+                facts,
+            }, null, 2));
+            return;
+        }
+        if (sub === "forget") {
+            const query = positional.slice(2).join(" ").trim() || String(flags.query || "").trim();
+            if (!query)
+                throw new Error("Usage: muxo memory forget <text>");
+            if (remoteUrl) {
+                const res = await remoteFetch("/api/v1/memory/forget", {
+                    method: "POST",
+                    body: { query },
+                });
+                console.log(JSON.stringify(res, null, 2));
+                return;
+            }
+            const { engine, ctx } = getLocalContext();
+            const pruned = await engine.forgetWorkspaceMemoryMatching(ctx, query);
+            console.log(JSON.stringify({ ok: true, ...pruned }, null, 2));
+            return;
+        }
         if (sub === "add") {
             const content = positional.slice(2).join(" ") || String(flags.content || "");
             if (!content)
                 throw new Error("Usage: muxo memory add <text>");
+            if (remoteUrl) {
+                const res = await remoteFetch("/api/v1/memory", {
+                    method: "POST",
+                    body: {
+                        content,
+                        title: flags.title ? String(flags.title) : content.slice(0, 60),
+                    },
+                });
+                console.log(JSON.stringify(res, null, 2));
+                return;
+            }
+            const { engine, ctx } = getLocalContext();
             const entry = await engine.addWorkspaceMemory(ctx, {
                 content,
                 title: flags.title ? String(flags.title) : content.slice(0, 60),
@@ -791,6 +1807,34 @@ async function runCli() {
             console.log(JSON.stringify({ ok: true, memory: entry }, null, 2));
             return;
         }
+        if (sub === "delete" || sub === "rm" || sub === "remove") {
+            const id = positional[2] || String(flags.id || "");
+            if (!id)
+                throw new Error("Usage: muxo memory delete <memory_id>");
+            if (remoteUrl) {
+                const res = await remoteFetch(`/api/v1/memory/${encodeURIComponent(id)}`, { method: "DELETE" });
+                console.log(JSON.stringify(res, null, 2));
+                return;
+            }
+            const { engine, ctx } = getLocalContext();
+            const deleted = await engine.deleteWorkspaceMemory(ctx, id);
+            console.log(JSON.stringify({ ok: true, ...deleted }, null, 2));
+            return;
+        }
+        if (remoteUrl) {
+            const query = sub === "recall" || sub === "search"
+                ? positional.slice(2).join(" ") || flags.query || undefined
+                : positional.slice(1).join(" ") || flags.query || undefined;
+            const suffix = query ? `?query=${encodeURIComponent(query)}` : "";
+            const res = await remoteFetch(`/api/v1/memory${suffix}`);
+            console.log(JSON.stringify({
+                ok: true,
+                ...res,
+                localMemories: res.records || [],
+            }, null, 2));
+            return;
+        }
+        const { engine, ctx } = getLocalContext();
         const query = sub === "recall" || sub === "search"
             ? positional.slice(2).join(" ") || flags.query || undefined
             : positional.slice(1).join(" ") || flags.query || undefined;
@@ -802,18 +1846,421 @@ async function runCli() {
         }, null, 2));
         return;
     }
+    if (cmd === "context") {
+        const query = positional.slice(1).join(" ") ||
+            (typeof flags.query === "string" ? flags.query : "") ||
+            undefined;
+        if (remoteUrl) {
+            const suffix = query ? `?query=${encodeURIComponent(query)}` : "";
+            const res = await remoteFetch(`/api/v1/context${suffix}`);
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const { engine, ctx } = getLocalContext();
+        const runContext = await engine.getRunContext(ctx, query);
+        console.log(JSON.stringify({ ok: true, ...runContext }, null, 2));
+        return;
+    }
+    if (cmd === "guardrails" || cmd === "guardrail") {
+        const sub = positional[1];
+        if (sub === "set" || sub === "add") {
+            const prompt = positional.slice(2).join(" ").trim() ||
+                String(flags.prompt || flags.rule || "").trim();
+            const rawRulesJson = typeof flags["rules-json"] === "string"
+                ? flags["rules-json"]
+                : typeof flags.rules === "string"
+                    ? flags.rules
+                    : undefined;
+            const parsedParamRules = rawRulesJson
+                ? JSON.parse(rawRulesJson)
+                : undefined;
+            if (!prompt && (!parsedParamRules || parsedParamRules.length === 0)) {
+                throw new Error('Usage: muxo guardrails set "<plain-English rule>" [--rules-json \'[...]\'] (e.g. muxo guardrails set "auto approve under $50 and require approval over $50")');
+            }
+            if (remoteUrl) {
+                const res = await remoteFetch("/api/v1/guardrails", {
+                    method: "POST",
+                    body: {
+                        prompt,
+                        ...(parsedParamRules ? { parameterRules: parsedParamRules } : {}),
+                    },
+                });
+                console.log(JSON.stringify(res, null, 2));
+                return;
+            }
+            const { engine, ctx } = getLocalContext();
+            const applied = await engine.applyNaturalLanguageGuardrail(ctx, prompt, {
+                parameterRules: parsedParamRules,
+                source: parsedParamRules ? "mcp_harness" : "deterministic",
+            });
+            console.log(JSON.stringify({
+                ...applied,
+                humanMessage: `Guardrail active: ${applied.guardrail.summary}`,
+            }, null, 2));
+            return;
+        }
+        if (sub === "reset") {
+            if (remoteUrl) {
+                const res = await remoteFetch("/api/v1/guardrails", {
+                    method: "POST",
+                    body: { reset: true },
+                });
+                console.log(JSON.stringify(res, null, 2));
+                return;
+            }
+            const { store, ctx } = getLocalContext();
+            const updated = store.updateWorkspacePolicy(ctx.workspace.id, DEFAULT_WORKSPACE_POLICY);
+            console.log(JSON.stringify({
+                ok: true,
+                workspace: updated,
+                plainEnglish: describePolicyInPlainEnglish(updated.policy),
+                humanMessage: "Reset workspace guardrails to Safe Default.",
+            }, null, 2));
+            return;
+        }
+        if (remoteUrl) {
+            const res = await remoteFetch("/api/v1/guardrails");
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const { engine, ctx } = getLocalContext();
+        const summary = engine.getGuardrailsSummary(ctx);
+        console.log(JSON.stringify({ ok: true, ...summary }, null, 2));
+        return;
+    }
+    if (cmd === "policy") {
+        const nlText = positional.slice(1).join(" ").trim() ||
+            String(flags.rule || flags.prompt || "").trim();
+        if (nlText) {
+            if (remoteUrl) {
+                const res = await remoteFetch("/api/v1/guardrails", {
+                    method: "POST",
+                    body: { prompt: nlText },
+                });
+                console.log(JSON.stringify(res, null, 2));
+                return;
+            }
+            const { engine, ctx } = getLocalContext();
+            const applied = await engine.applyNaturalLanguageGuardrail(ctx, nlText);
+            console.log(JSON.stringify({
+                ...applied,
+                humanMessage: `Guardrail active: ${applied.guardrail.summary}`,
+            }, null, 2));
+            return;
+        }
+        if (remoteUrl) {
+            const res = await remoteFetch("/api/v1/policy");
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const { engine, ctx } = getLocalContext();
+        const summary = engine.getGuardrailsSummary(ctx);
+        console.log(JSON.stringify({
+            ok: true,
+            policy: summary.policy,
+            plainEnglish: summary.plainEnglish,
+            explanation: summary.plainEnglish.explanation,
+            activeDefaults: summary.activeDefaults,
+            activeGuardrails: summary.activeGuardrails,
+        }, null, 2));
+        return;
+    }
     if (cmd === "governance") {
-        const status = engine.governance.getGovernanceStatus(ctx.workspace);
-        const summary = engine.governance.getStatus(ctx.workspace);
+        const sub = positional[1];
+        const ringLabel = (policy) => policy?.executionRing !== undefined
+            ? RING_LABELS[policy.executionRing] || `Ring ${policy.executionRing}`
+            : "Per action (set by risk level)";
+        if (sub === "pause" || sub === "kill-switch" || sub === "kill" || sub === "quarantine") {
+            const reason = positional.slice(2).join(" ").trim() ||
+                (typeof flags.reason === "string" ? flags.reason : "") ||
+                "Paused from the Muxo CLI";
+            if (remoteUrl) {
+                const res = await remoteFetch("/api/v1/governance/kill-switch", {
+                    method: "POST",
+                    body: { action: "quarantine", reason },
+                });
+                console.log(JSON.stringify(res, null, 2));
+                return;
+            }
+            const { engine, ctx } = getLocalContext();
+            const out = await engine.activateWorkspaceKillSwitch(ctx, { reason });
+            console.log(JSON.stringify({ ok: true, ...out }, null, 2));
+            return;
+        }
+        if (sub === "resume") {
+            if (remoteUrl) {
+                const res = await remoteFetch("/api/v1/governance/kill-switch", {
+                    method: "POST",
+                    body: { action: "resume" },
+                });
+                console.log(JSON.stringify(res, null, 2));
+                return;
+            }
+            const { engine, ctx } = getLocalContext();
+            const out = engine.resumeWorkspaceKillSwitch(ctx);
+            console.log(JSON.stringify({ ok: true, ...out }, null, 2));
+            return;
+        }
+        if (sub === "scan") {
+            const content = positional.slice(2).join(" ").trim() || String(flags.content || "").trim();
+            if (!content)
+                throw new Error("Usage: muxo governance scan <text>");
+            if (remoteUrl) {
+                const res = await remoteFetch("/api/v1/governance/scan-context", {
+                    method: "POST",
+                    body: { content, sessionId: "cli" },
+                });
+                console.log(JSON.stringify(res, null, 2));
+                return;
+            }
+            const { engine, ctx } = getLocalContext();
+            const scan = engine.governance.scanMemoryContent({
+                workspaceId: ctx.workspace.id,
+                sessionId: "cli",
+                role: "user",
+                content,
+            });
+            console.log(JSON.stringify({ ok: true, scan }, null, 2));
+            return;
+        }
+        if (sub === "policy") {
+            const patch = {};
+            if (typeof flags.mode === "string")
+                patch.mode = flags.mode;
+            if (flags.ring !== undefined)
+                patch.executionRing = Number(flags.ring);
+            if (typeof flags["require-approval"] === "string") {
+                const raw = flags["require-approval"].trim();
+                patch.requireApprovalFor =
+                    raw === "none" ? [] : raw.split(",").map((r) => r.trim()).filter(Boolean);
+            }
+            if (flags["block-destructive-sql"] !== undefined) {
+                patch.blockDestructiveSql =
+                    flags["block-destructive-sql"] === true || flags["block-destructive-sql"] === "true";
+            }
+            if (flags["max-credits"] !== undefined)
+                patch.maxCreditsPerRun = Number(flags["max-credits"]);
+            if (Object.keys(patch).length === 0) {
+                if (remoteUrl) {
+                    const res = await remoteFetch("/api/v1/governance");
+                    const policy = res.workspacePolicy || {};
+                    console.log(JSON.stringify({ ok: true, ringName: ringLabel(policy), policy }, null, 2));
+                    return;
+                }
+                const { store, ctx } = getLocalContext();
+                const policy = (store.getWorkspace(ctx.workspace.id) || ctx.workspace).policy;
+                console.log(JSON.stringify({ ok: true, ringName: ringLabel(policy), policy }, null, 2));
+                return;
+            }
+            if (remoteUrl) {
+                const res = await remoteFetch("/api/v1/policy", { method: "POST", body: patch });
+                const policy = res.workspace?.policy || {};
+                console.log(JSON.stringify({ ok: true, ringName: ringLabel(policy), policy }, null, 2));
+                return;
+            }
+            const { store, ctx } = getLocalContext();
+            const updated = store.updateWorkspacePolicy(ctx.workspace.id, sanitizePolicyPatch(patch));
+            console.log(JSON.stringify({ ok: true, ringName: ringLabel(updated.policy), policy: updated.policy }, null, 2));
+            return;
+        }
+        if (remoteUrl) {
+            const res = await remoteFetch("/api/v1/governance");
+            console.log(JSON.stringify({
+                ok: true,
+                did: res.governance?.agentDid,
+                chainValid: res.governance?.auditChain?.chainVerified ??
+                    res.governance?.auditIntegrityValid ??
+                    true,
+                ringName: ringLabel(res.workspacePolicy),
+                ...res,
+            }, null, 2));
+            return;
+        }
+        const { engine, ctx, store } = getLocalContext();
+        const ws = store.getWorkspace(ctx.workspace.id) || ctx.workspace;
+        const status = engine.governance.getGovernanceStatus(ws);
+        const summary = engine.governance.getStatus(ws);
         console.log(JSON.stringify({
             ok: true,
             did: summary.agentDid,
             chainValid: summary.auditChainIntegrity,
-            ringName: "Ring 2 (Standard)",
+            ringName: ringLabel(ws.policy),
             ...status,
         }, null, 2));
         return;
     }
+    if (cmd === "workspaces" || cmd === "workspace") {
+        const sub = positional[1] || "list";
+        if (sub === "list" || sub === "ls") {
+            if (remoteUrl) {
+                const res = await remoteFetch("/api/v1/workspaces");
+                console.log(JSON.stringify(res, null, 2));
+                return;
+            }
+            const { store, ctx } = getLocalContext();
+            const workspaces = store.listUserWorkspaces(ctx.user.id, ctx.workspace.id);
+            console.log(JSON.stringify({ ok: true, currentWorkspaceId: ctx.workspace.id, workspaces }, null, 2));
+            return;
+        }
+        if (sub === "create" || sub === "new") {
+            const name = positional.slice(2).join(" ").trim() ||
+                (typeof flags.name === "string" ? flags.name.trim() : "");
+            if (!name) {
+                throw new Error("Usage: muxo workspaces create <name> [--team <teamName>]");
+            }
+            const teamName = typeof flags.team === "string" ? flags.team.trim() : undefined;
+            if (remoteUrl) {
+                const res = await remoteFetch("/api/v1/workspaces", {
+                    method: "POST",
+                    body: { name, teamName },
+                });
+                console.log(JSON.stringify(res, null, 2));
+                return;
+            }
+            const { store, ctx } = getLocalContext();
+            const created = store.createWorkspaceForUser({
+                userId: ctx.user.id,
+                name,
+                teamName,
+            });
+            console.log(JSON.stringify({
+                ok: true,
+                workspace: created.workspace,
+                apiKey: created.apiKey,
+                workspaces: store.listUserWorkspaces(ctx.user.id, created.workspace.id),
+            }, null, 2));
+            return;
+        }
+        if (sub === "switch" || sub === "use") {
+            const workspaceId = positional[2]?.trim() ||
+                (typeof flags.id === "string" ? flags.id.trim() : "");
+            if (!workspaceId) {
+                throw new Error("Usage: muxo workspaces switch <workspace_id>");
+            }
+            if (remoteUrl) {
+                const res = await remoteFetch("/api/v1/workspaces/switch", {
+                    method: "POST",
+                    body: { workspaceId },
+                });
+                console.log(JSON.stringify(res, null, 2));
+                return;
+            }
+            const { store, ctx } = getLocalContext();
+            const switched = store.switchUserWorkspace(ctx.user.id, workspaceId);
+            if (!switched) {
+                throw new Error(`Workspace '${workspaceId}' not found or not accessible.`);
+            }
+            console.log(JSON.stringify({
+                ok: true,
+                workspace: switched.workspace,
+                workspaces: store.listUserWorkspaces(ctx.user.id, switched.workspace.id),
+            }, null, 2));
+            return;
+        }
+        if (sub === "join") {
+            const keyToJoin = positional[2]?.trim() ||
+                (typeof flags["api-key"] === "string"
+                    ? flags["api-key"].trim()
+                    : typeof flags.key === "string"
+                        ? flags.key.trim()
+                        : "");
+            if (!keyToJoin) {
+                throw new Error("Usage: muxo workspaces join <mk_live_...>");
+            }
+            if (remoteUrl) {
+                const res = await remoteFetch("/api/v1/workspaces/join", {
+                    method: "POST",
+                    body: { apiKey: keyToJoin },
+                });
+                const ws = res.workspace || {};
+                writeCliAuthConfig({
+                    authenticated: true,
+                    apiKey: keyToJoin,
+                    apiUrl: remoteUrl,
+                    workspaceId: String(ws.id || "ws_remote"),
+                    workspaceName: String(ws.name || "Muxo Workspace"),
+                    agentId: "usr_remote",
+                    governanceDid: `did:muxo:${ws.id || "ws_remote"}`,
+                    supermemoryNamespace: `muxo_${ws.id || "ws_remote"}`,
+                    updatedAt: new Date().toISOString(),
+                });
+                console.log(JSON.stringify(res, null, 2));
+                return;
+            }
+            const { store, ctx, engine } = getLocalContext();
+            const joined = store.joinWorkspaceWithApiKey({
+                apiKey: keyToJoin,
+                userId: ctx.user.id,
+            });
+            if (!joined) {
+                throw new Error("Invalid or revoked Muxo API key.");
+            }
+            writeCliAuthConfig({
+                authenticated: true,
+                apiKey: keyToJoin,
+                workspaceId: joined.workspace.id,
+                workspaceName: joined.workspace.name,
+                agentId: ctx.user.id,
+                governanceDid: engine.governance.getStatus(joined.workspace).agentDid,
+                supermemoryNamespace: engine.supermemory.getWorkspaceNamespace(joined.workspace.id),
+                updatedAt: new Date().toISOString(),
+            });
+            console.log(JSON.stringify({
+                ok: true,
+                mode: "api_key_join",
+                workspace: joined.workspace,
+                keyRecord: joined.keyRecord,
+                membership: joined.membership,
+            }, null, 2));
+            return;
+        }
+    }
+    if (cmd === "team" || cmd === "teams") {
+        const sub = positional[1] || "onboard";
+        const teamName = (sub === "onboard" || sub === "invite" || sub === "add"
+            ? positional.slice(2).join(" ")
+            : positional.slice(1).join(" ")).trim() ||
+            (typeof flags.name === "string" ? flags.name.trim() : "") ||
+            (typeof flags.team === "string" ? flags.team.trim() : "");
+        if (!teamName) {
+            throw new Error('Usage: muxo team onboard "<team_name>" [--mode shared|dedicated] [--role operator|admin|member]');
+        }
+        const rawMode = typeof flags.mode === "string" ? flags.mode.trim() : "";
+        const mode = rawMode === "dedicated" || rawMode === "dedicated_workspace"
+            ? "dedicated_workspace"
+            : "shared_workspace";
+        const role = typeof flags.role === "string" &&
+            ["owner", "admin", "operator", "member"].includes(flags.role)
+            ? flags.role
+            : "operator";
+        const environment = flags.test ? "test" : "live";
+        if (remoteUrl) {
+            const res = await remoteFetch("/api/v1/workspaces/onboard-team", {
+                method: "POST",
+                body: { teamName, mode, role, environment },
+            });
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const { store, ctx } = getLocalContext();
+        const kit = store.onboardTeam({
+            userId: ctx.user.id,
+            userEmail: ctx.user.email,
+            currentWorkspaceId: ctx.workspace.id,
+            teamName,
+            role,
+            mode,
+            environment,
+            baseUrl: config.baseUrl,
+        });
+        console.log(JSON.stringify({
+            ok: true,
+            kit,
+            workspace: kit.workspace,
+            apiKey: kit.apiKey,
+        }, null, 2));
+        return;
+    }
     if (cmd === "serve") {
         const { createMuxoServer } = await import("./server.js");
         const port = flags.port ? Number(flags.port) : config.port;
@@ -841,54 +2288,181 @@ async function runCli() {
     // Natural Language fallback: if user passed plain English directly (`muxo "Audit https://muxo.ai for SEO"`)
     if (cmd !== "help" && !flags.help && !flags.h && positional.length > 0) {
         const promptText = positional.join(" ").trim();
+        const planOnly = flags["plan-only"] === true || flags.plan === true;
+        const autoApprove = flags["no-approve"] ? false : true;
+        const fundingMode = flags.byok || flags.funding === "byok"
+            ? "byok"
+            : flags.funding === "muxo_funded"
+                ? "muxo_funded"
+                : undefined;
+        if (remoteUrl) {
+            const data = await remoteFetch("/api/v1/do", {
+                method: "POST",
+                body: {
+                    prompt: promptText,
+                    dryRun: planOnly,
+                    planOnly,
+                    autoApprove,
+                    autoExecute: !planOnly,
+                    approveRisky: autoApprove,
+                    fundingMode,
+                },
+            });
+            console.log(JSON.stringify(data, null, 2));
+            return;
+        }
+        const { engine, ctx } = getLocalContext();
         const result = await engine.doNaturalLanguage(ctx, {
             prompt: promptText,
-            autoApprove: flags["no-approve"] ? false : true,
-            planOnly: flags["plan-only"] === true || flags.plan === true,
-            fundingMode: flags.byok || flags.funding === "byok"
-                ? "byok"
-                : flags.funding === "muxo_funded"
-                    ? "muxo_funded"
-                    : undefined,
+            autoApprove,
+            planOnly,
+            fundingMode,
         });
         console.log(JSON.stringify(result, null, 2));
         return;
     }
+    if (cmd === "playbooks" || cmd === "playbook") {
+        const sub = positional[1];
+        if (sub === "run") {
+            const slug = positional[2] ||
+                flags.slug ||
+                "fullstack-cloud-bootstrap";
+            const input = flags.input
+                ? JSON.parse(String(flags.input))
+                : {};
+            if (remoteUrl) {
+                const res = await remoteFetch(`/api/v1/playbooks/${encodeURIComponent(slug)}/run`, {
+                    method: "POST",
+                    body: { input },
+                });
+                console.log(JSON.stringify(res, null, 2));
+                return;
+            }
+            const { engine, ctx } = getLocalContext();
+            const res = engine.runCommercialPlaybook(ctx, { slug, input });
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        if (remoteUrl) {
+            const res = await remoteFetch("/api/v1/playbooks");
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const { engine } = getLocalContext();
+        const playbooks = engine.listCommercialPlaybooks();
+        console.log(JSON.stringify({ ok: true, count: playbooks.length, playbooks }, null, 2));
+        return;
+    }
+    if (cmd === "roi") {
+        if (remoteUrl) {
+            const res = await remoteFetch("/api/v1/analytics/roi");
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const { engine, ctx } = getLocalContext();
+        console.log(JSON.stringify({ ok: true, ...engine.getCommercialRoiReport(ctx) }, null, 2));
+        return;
+    }
+    if (cmd === "cedar") {
+        const sub = positional[1];
+        if (sub === "evaluate" || sub === "eval") {
+            const toolSlug = positional[2] || flags.tool || "instant.web.search";
+            const input = flags.input
+                ? JSON.parse(String(flags.input))
+                : {};
+            if (remoteUrl) {
+                const res = await remoteFetch("/api/v1/governance/cedar/evaluate", {
+                    method: "POST",
+                    body: { toolSlug, input },
+                });
+                console.log(JSON.stringify(res, null, 2));
+                return;
+            }
+            const { engine, ctx } = getLocalContext();
+            console.log(JSON.stringify({
+                ok: true,
+                ...engine.evaluatePolicyAsCode(ctx, { toolSlug, input }),
+            }, null, 2));
+            return;
+        }
+        if (remoteUrl) {
+            const res = await remoteFetch("/api/v1/governance/cedar");
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const { engine, ctx } = getLocalContext();
+        console.log(JSON.stringify({ ok: true, ...engine.getPolicyAsCodeBundle(ctx) }, null, 2));
+        return;
+    }
+    if (cmd === "telemetry" || cmd === "otel") {
+        const limit = flags.limit ? Number(flags.limit) : 25;
+        if (remoteUrl) {
+            const res = await remoteFetch(`/api/v1/telemetry/otlp?limit=${limit}`);
+            console.log(JSON.stringify(res, null, 2));
+            return;
+        }
+        const { engine, ctx } = getLocalContext();
+        console.log(JSON.stringify({ ok: true, ...engine.exportOtelTraces(ctx, limit) }, null, 2));
+        return;
+    }
     console.log(`
-Muxo CLI — Human & LLM Friendly Execution, Infrastructure, BYOK & Governance Platform
+Muxo CLI — Unified Agent Execution, Cloud Infrastructure, Memory & Safety Platform
 
 Natural Language & Interactive TUI:
+  muxo setup [--api-key <key>]                 1-command auto-signup (or join via team API key) + MCP setup
   muxo do "<instruction>"                      Execute any goal in plain English (LLM/semantic router -> plan -> execute)
   muxo ask "<instruction>" [--plan-only]       Alias for 'muxo do' (pass --plan-only to inspect plan before running)
   muxo tui                                     Launch interactive Terminal UI dashboard (BYOK, Billing, OAuth, Infra)
   muxo byok [list|set|delete] [<provider>]     Manage BYOK API keys in AES-256-GCM Vault (0 credit cost when active)
 
+Workspaces & Team Onboarding:
+  muxo workspaces [list|create|switch|join]    List, create, switch, or join workspaces via API key
+  muxo team onboard "<team>" [--mode shared|dedicated] [--role operator|admin|member]
+                                               Mint a scoped team API key & onboarding kit for another team
+
 Core Commands:
   muxo login [--api-key <key> | --signup]      Sign in or create an autonomous workspace (~/.muxo/config.json)
   muxo logout                                  Remove saved CLI authentication config
   muxo claim <owner_email>                     Generate a human owner claim link for this workspace
-  muxo whoami                                  Show workspace profile, plan, DID, and credit balance
-  muxo search <query> [--lane <lane>]          Search across Instant, Composio Apps, Stripe Projects & Billing
+  muxo whoami                                  Show workspace profile, plan, agent identity, and credit balance
+  muxo search <query> [--lane <lane>]          Search across Instant Tools, Connected Apps, Cloud Infra & Billing
   muxo inspect <tool_slug>                     Inspect tool schema, risk level, and credit cost
-  muxo connections [--sync true|false]         List Composio OAuth & Stripe Projects provider connections
+  muxo connections [--sync true|false]         List Connected Apps & Cloud Infrastructure provider connections
   muxo link <provider> [--wait]                Start OAuth handoff for a service and optionally wait
   muxo connect <provider> [--wait]             Alias for 'muxo link'
   muxo wait <provider> [--timeout 15]          Poll until a pending OAuth connection handoff becomes active
   muxo plan <tool_slug> --input '{...}'        Create a governed execution plan (accepts natural language too)
   muxo approve <plan_id>                       Approve a pending high-risk plan
-  muxo run <plan_id>                           Execute an approved plan and issue a signed receipt
+  muxo run <plan_id>                           Execute an approved plan and issue a verifiable audit record
   muxo exec <tool_slug> --input '{...}'        Plan and execute in one step (pass --approve for high-risk)
-  muxo resources                               List provisioned Stripe Projects infrastructure resources
+  muxo provision <provider> [--name <name>]    Provision cloud infrastructure (e.g., turso, neon, supabase, upstash)
+  muxo resources                               List provisioned Muxo Cloud Infrastructure resources
   muxo env pull [--out .env.muxo]              Decrypt and write provisioned credentials to local .env
-  muxo receipts [<receipt_id>]                 List or cryptographically verify execution receipts
+  muxo receipts [<receipt_id>]                 List or verify execution audit records
   muxo billing [status|topup|upgrade|checkout] Manage credits, upgrade to Starter, or inspect settlements
-  muxo memory [<query>]                        Recall Supermemory v5 workspace brain & hybrid memories
-  muxo governance                              Inspect Microsoft Agent Governance Ed25519 DID & audit chain
+  muxo memory [<query>]                        Recall Muxo Workspace Memory & hybrid context
+  muxo memory add <text> | delete <id>         Save or delete a workspace memory
+  muxo memory facts [<query>] [--current]      List temporal facts with their history (or only current facts)
+  muxo memory forget <text>                    Delete memories and retire facts that match <text>
+  muxo governance                              Inspect Muxo Safety & Approvals identity and audit chain
+  muxo governance pause [<reason>] | resume    Turn the workspace kill switch on or off
+  muxo governance scan <text>                  Check text for prompt injection before storing or sending it
+  muxo governance policy [--mode enforce|monitor] [--ring 0-3] [--require-approval write,admin|none]
+                         [--block-destructive-sql true|false] [--max-credits <n>]
+  muxo cedar [evaluate <tool_slug>]            Compile or evaluate AWS Cedar 4.x & OPA Rego v1 policy-as-code
+  muxo telemetry [--limit 25]                  Export OpenTelemetry GenAI / MCP OTLP & Langfuse trace spans
+  muxo playbooks [run <slug>]                  List or execute Temporal-compatible commercial Saga playbooks
+  muxo roi                                     Compute FinOps unit economics, BYOK savings, and engineering ROI
+  muxo harness                                 Check API, MCP, auth, governance and catalog; print MCP config
   muxo serve [--port 4310]                     Start unified HTTP Console, Landing, OAuth Callback & MCP server
-  muxo mcp                                     Run stdio MCP server (20 canonical tools)
+  muxo mcp                                     Run stdio MCP server (19 canonical tools)
 `);
 }
-runCli().catch((err) => {
+runCli()
+    .then(() => {
+    process.exit(Number(process.exitCode ?? 0));
+})
+    .catch((err) => {
     console.error("Error:", err?.message || err);
     process.exit(1);
 });