@muxoai/sdk 1.2.3 → 1.4.2

package/.agents/plugins/marketplace.json

@@ -0,0 +1,22 @@
+{
+  "name": "muxo",
+  "interface": {
+    "displayName": "Muxo Plugins"
+  },
+  "plugins": [
+    {
+      "name": "muxo",
+      "version": "1.4.2",
+      "description": "Governed execution across 1,000+ Connected Apps, Instant Tools (search, scrape, crawl, SEO audit), Cloud Infrastructure provisioning, Workspace Memory recall, and cryptographic execution receipts.",
+      "source": {
+        "source": "local",
+        "path": "./plugins/muxo"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_USE"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

package/.claude-plugin/marketplace.json

@@ -0,0 +1,32 @@
+{
+  "name": "muxo",
+  "description": "Official Muxo plugin marketplace for governed execution across Connected Apps, Instant Tools, Cloud Infrastructure, and Workspace Memory.",
+  "owner": {
+    "name": "Muxo",
+    "email": "founders@muxo.ai",
+    "url": "https://muxo.ai"
+  },
+  "metadata": {
+    "description": "Official Muxo plugin marketplace for governed execution across Connected Apps, Instant Tools, Cloud Infrastructure, and Workspace Memory.",
+    "version": "1.4.2"
+  },
+  "plugins": [
+    {
+      "name": "muxo",
+      "source": {
+        "source": "npm",
+        "package": "@muxoai/cli"
+      },
+      "strict": false,
+      "description": "Governed execution across 1,000+ Connected Apps, Instant Tools (search, scrape, crawl, SEO audit), Cloud Infrastructure provisioning, Workspace Memory recall, and verifiable audit records.",
+      "version": "1.4.2",
+      "category": "Productivity",
+      "skills": [
+        "./plugins/muxo/skills/muxo",
+        "./plugins/muxo/skills/setup"
+      ],
+      "hooks": "./plugins/muxo/hooks/hooks.json",
+      "mcpServers": "./plugins/muxo/.mcp.json"
+    }
+  ]
+}

package/.codex/config.toml

@@ -0,0 +1,12 @@
+# OpenAI Codex Configuration for Muxo
+# Reference: https://developers.openai.com/codex/plugins
+
+[plugins."muxo@muxo"]
+enabled = true
+
+# TOML MCP Alternative (~/.codex/config.toml):
+[mcp_servers.muxo]
+url = "https://api.muxo.ai/mcp"
+# Or for local stdio proxy (requires Node.js 22+):
+# command = "npx"
+# args = ["-y", "@muxoai/cli@latest", "mcp"]

package/ARCHITECTURE.md

@@ -0,0 +1,121 @@
+# Muxo Internal Architecture & Open-Source Ecosystem Blueprint
+
+> **Purpose:** Definitive internal engineering guide on how to build Muxo cleanly, what external/open-source infrastructure to leverage, what legacy complexity from `muxoai` and `muxo2` to permanently drop, and how our four pillars (**Composio**, **Stripe Projects**, **Microsoft Agent Governance Toolkit**, and **Supermemory v5**) fit together.
+
+---
+
+## 1. Core Thesis: What Muxo Actually Is
+
+Developers already have an agent harness (**Claude Code, Cursor, Factory Droid, OpenCode, Pi, Mastra, Vercel AI SDK, or Google ADK**). They do **not** want another mandatory chat window or proprietary agent framework.
+
+**Muxo is the Unified Execution, Infrastructure, Memory, and Governance Boundary for existing agents.**
+
+A customer connects their agent to **one Muxo MCP endpoint (`/mcp`)** with **one Muxo key (`mk_live_...`)**, and Muxo handles:
+
+```text
+Agent (Claude / Cursor / Droid / Mastra / Pi / AI SDK)
+  │
+  ▼
+Muxo Gateway (app.muxo.ai / api.muxo.ai)
+  ├─► 1. Microsoft Agent Governance Toolkit (@microsoft/agent-governance-sdk)
+  │      McpSecurityScanner ──► PolicyEngine ──► AgentIdentity (Ed25519 DID) ──► AuditLogger ──► DecisionRecord
+  │
+  ├─► 2. Supermemory v5 Contextual Brain (supermemory SDK v5)
+  │      Workspace Profile (/ns/{ws}/profile) + Hybrid Recall (/ns/{ws}/search) + Post-Run Memory (/ns/{ws}/document)
+  │
+  ├─► 3. Execution & Provisioning Lanes
+  │      ├─► Lane A: Composio Instant (instant.*)  ──► Zero-OAuth tools (search, scrape, repo intel, HN, DNS)
+  │      ├─► Lane B: Composio SDK (app.*)          ──► 500+ Managed OAuth SaaS tools (GitHub, Slack, Gmail, Linear...)
+  │      └─► Lane C: Stripe Projects (resource.*)  ──► Live Cloud Infrastructure Provisioning + AES-256-GCM Secret Vault
+  │
+  └─► 4. Cryptographic Receipt & Prepaid Ledger
+         HMAC-SHA256 + Ed25519 Signed Receipt Chain + Stripe Checkout Credit Fulfillment
+```
+
+---
+
+## 2. Ecosystem Evaluation: What to Use vs. What to Drop
+
+Across `muxoai` (gen 1) and `muxo2` (gen 2, 203,443 LOC), the biggest mistake was rebuilding infrastructure that best-in-class open-source packages and managed APIs already solve. Here is our strict **Keep / Adopt / Drop** decision matrix:
+
+| Layer / Candidate | Verdict | Why & How Muxo Uses It | What It Replaces from `muxoai` / `muxo2` |
+| :--- | :--- | :--- | :--- |
+| **Composio SDK & Tool Router** (`backend.composio.dev/api/v3`) | **ADOPT (Core Lane)** | Provides 500+ managed OAuth integrations (`app.*`), user-scoped Connect Links, and schema discovery without Muxo maintaining custom OAuth apps for every SaaS provider. | Replaces custom per-provider OAuth brokers and bespoke SaaS connectors. |
+| **Composio Instant & `agents.composio.dev` Pattern** | **ADOPT (Core Lane + Onboarding)** | 1) Zero-setup `instant.*` tools work immediately on workspace creation.<br>2) We adopt the **`agents.composio.dev` 2-call autonomous signup pattern** (`POST /api/v1/agents/signup` + `POST /api/v1/agents/claim`) so an agent can self-provision a Muxo workspace in one HTTP call and later hand ownership over to its human via a claim slug. | Replaces complex multi-step human-only bootstrap ceremonies for CLI/agent onboarding. |
+| **Stripe v2 Provisioning REST API & CLI** (`https://api.stripe.com/v2/provisioning/*`, `Stripe-Version: 2026-09-30.preview` + `stripe projects` v0.50.0) | **ADOPT (Core Lane — HTTP v2 + Node Runtime)** | Provisions real databases, caches, and cloud services (`neon/postgres`, `upstash/redis`, `turso`, `supabase`, `supermemory/memory`, etc.) directly over HTTP via `POST /v2/provisioning/resources` and reveals secrets via `POST /v2/provisioning/resources/:id/reveal_access_configuration` (with automatic CLI/managed fallback) into Muxo's AES-256-GCM vault. Works natively in both Node.js and Cloudflare Workers V8 isolates! | Replaces `muxo2`'s broken 4-worker Cloudflare Container + mTLS bridge (`projects-gateway` + `projects-executor`). See Section 3 below. |
+| **Microsoft Agent Governance Toolkit** (`@microsoft/agent-governance-sdk` v5.0.0) | **ADOPT (Core Governance)** | A 40 KB, zero-dependency, MIT-licensed SDK providing `McpSecurityScanner` (prompt-injection & exfiltration detection), `PolicyEngine` (YAML/JSON rules + risk gates), `AgentIdentity` (Ed25519 DIDs), and `AuditLogger` (SHA-256 tamper-evident hash chain). | Replaces **~18,000 LOC** of custom authority seals, custom policy DSLs, and hand-rolled audit chains in `muxo2`. |
+| **Supermemory v5** (`supermemory` `^5.0.1`) | **ADOPT (Fail-Open Contextual Brain)** | Gives every Muxo workspace an isolated `/ns/muxo-v5-{hash}` brain with automatic `static` + `dynamic` profiles (`client.profile`), sub-50ms hybrid search (`client.search`), and governed post-run memory (`client.add`). Also natively deployable via Stripe Projects (`supermemory/memory`)! | Replaces **~25,000 LOC** of `muxoai/packages/brain` + Python `context-engine` (Graphiti + Neo4j + Vectorize + D1). |
+| **Mastra (`@mastra/mcp`), Pi (`pi`), Vercel AI SDK (`ai`), Google ADK** | **CLIENT ECOSYSTEM (Do Not Bundle Inside Server)** | These are **agent harnesses** that *consume* Muxo over `/mcp` and `/skill.md`. Bundling an agent framework inside the Muxo server violates "Existing-Agent First" and bloats the runtime. Instead, `app.muxo.ai` and `muxo mcp-config` generate instant copy-paste connectors for Mastra, Pi, Vercel AI SDK, Claude Code, Cursor, and Factory Droid. | Drops `muxoai/packages/harness` (`@cloudflare/think` + custom chat UI) from the core execution server. |
+| **Open-Source Monid** (`monid-upstream`) | **OPTIONAL / DEFER** | `muxoai` imported 413 Monid definitions, but 408 were unquoted and 69 had broken request/output hooks (`LEARNING.md` F10/F11). Composio Instant + Composio SDK + Stripe Projects already cover >95% of real developer tasks with live execution. | Drops 400+ unverified/quarantined static connector stubs and the Deno fixture bridge. |
+| **Web Surfaces (`muxo.ai`, `docs.muxo.ai`, `app.muxo.ai`)** | **KEEP & UNIFY** | • **`muxo.ai`**: Existing Astro interactive provider-grid canvas (`web/`).<br>• **`docs.muxo.ai`**: Existing Mintlify deployment (`subdomain: muxo-ai`).<br>• **`app.muxo.ai`**: Built-in operator console in `muxo3` sharing the exact `muxo.ai` design tokens and navigation links. | Replaces 60,000+ LOC of duplicate SSR rendering in `muxo2/apps/console` and `muxo2/apps/web`. |
+
+---
+
+## 3. Why Stripe Projects Provisioning Failed in `muxo2` — And Why It Works Live in `muxo3`
+
+### Why `muxo2` Disabled Stripe Projects Provisioning
+In `muxo2` (`projects-production-completion-plan.md`), the runtime was built on **Cloudflare Workers (V8 isolates)**. Because V8 isolates cannot spawn OS processes or run the native Go `stripe` CLI and `~/.stripe/plugins/apps/projects/0.50.0/stripe-projects-cli` binary:
+1. `muxo2` tried to wrap the Stripe CLI inside a separate **Cloudflare Container (`apps/projects-executor`)** behind a second **Cloudflare Worker (`apps/projects-gateway`)** with custom CA fingerprint pinning, UID=0 root directory checks, and 55-second container cold-start budgets.
+2. Inside the container, the `stripe-projects-cli` plugin was invoked directly without `PROJECTS_STANDALONE=1` or exceeded container memory/startup deadlines, resulting in `SIGKILL` and 9 consumed diagnostic attempts.
+
+### Why It Works 100% Live in `muxo3` (Native Stripe v2 Provisioning HTTP API + CLI)
+In `muxo3` (`src/providers/stripe-projects.ts` and `worker/index.ts`), we integrate Stripe's gated **v2 Provisioning REST API** (`https://api.stripe.com/v2/provisioning/*` with header `Stripe-Version: 2026-09-30.preview`) alongside the local CLI:
+1. **Direct Stripe v2 Provisioning HTTP REST Client (Zero Container Required, V8 Isolate Ready):** Both `StripeProjectsAdapter` (Node.js) and `worker/index.ts` (Cloudflare Workers) call Stripe's `/v2/provisioning/*` REST endpoints directly over HTTPS using `Authorization: Bearer <sk_live_...|rk_live_...>` and `Stripe-Version: 2026-09-30.preview`:
+   - **Eligibilities:** `GET /v2/provisioning/eligibility` (`v2.provisioning.eligibility`)
+   - **Catalog Providers:** `GET /v2/provisioning/catalog/providers` (`v2.provisioning.provider`)
+   - **Catalog Service Details:** `GET /v2/provisioning/catalog/services` (`v2.provisioning.provider_service_detail`)
+   - **Payment Profiles & Spend Limits:** `GET /v2/provisioning/payment_profile` & `POST /v2/provisioning/payment_profile/update_limit` (`v2.provisioning.payment_profile`)
+   - **Payment Method Requests:** `POST /v2/provisioning/payment_method_requests` (`v2.provisioning.payment_method_request`)
+   - **Projects:** `POST /v2/provisioning/projects` (`v2.provisioning.project`)
+   - **Provider Connections:** `GET /v2/provisioning/provider_connections` & `POST /v2/provisioning/provider_connections/:id/unlink` (`v2.provisioning.provider_connection`)
+   - **Provider Connection Requests:** `POST /v2/provisioning/provider_connection_requests`, `GET /v2/provisioning/provider_connection_requests/:id`, & `POST /v2/provisioning/provider_connection_requests/:id/submit_information` (`v2.provisioning.provider_connection_request`)
+   - **Resources:** `POST /v2/provisioning/resources`, `POST /v2/provisioning/resources/link`, `GET /v2/provisioning/resources/:id`, `POST /v2/provisioning/resources/:id`, `POST /v2/provisioning/resources/:id/remove`, `POST /v2/provisioning/resources/:id/unlink`, `POST /v2/provisioning/resources/:id/rotate_credentials`, & `POST /v2/provisioning/resources/:id/submit_information` (`v2.provisioning.resource`)
+   - **Access Configurations (Secret Reveal):** `POST /v2/provisioning/resources/:id/reveal_access_configuration` (`v2.provisioning.resource.access_configuration` returning `{ configuration: Record<string, string>, expires_at }`)
+2. **Automatic Multi-Tier Fallback:** If the Stripe key does not yet have the `2026-09-30.preview` gate enabled, `StripeProjectsAdapter` transparently falls back to the local `stripe projects` CLI (when a `.projects` directory is present) or Muxo Cloud Managed Infrastructure.
+3. **Encrypted Vault Custody:** Immediately after `POST /v2/provisioning/resources` and `POST /v2/provisioning/resources/:id/reveal_access_configuration` (or `stripe projects env --pull`), `StripeProjectsAdapter` encrypts the returned credentials with **AES-256-GCM** using a per-workspace HKDF-derived key in `MuxoStore` (`src/store.ts`), exposing them only via owner-authenticated `muxo env pull`, `GET /api/v1/resources/env`, or `POST /api/v1/provisioning/resources/:id/reveal_access_configuration`.
+
+---
+
+## 4. Detailed Architecture of the 4 Core Pillars in `muxo3`
+
+### Pillar 1: Microsoft Agent Governance Toolkit (`src/providers/microsoft-governance.ts`)
+
+Every call to `plan_action` and `execute_<risk>` passes through the Microsoft Agent Governance pipeline:
+
+```mermaid
+flowchart LR
+    A[Agent Tool Call] --> B[McpSecurityScanner]
+    B --> C[PolicyEngine]
+    C --> D[AgentIdentity Ed25519]
+    D --> E[AuditLogger Hash Chain]
+    E --> F[Signed DecisionRecord]
+```
+
+1. **`McpSecurityScanner`:** Scans tool inputs and schemas for prompt injection (`ignore previous instructions`), shell injection, path traversal (`../`), and credential leaks before a plan is created.
+2. **`PolicyEngine`:** Loads workspace governance rules (`allow` / `deny`, blocked tool patterns, risk-level approval gates, and `monitor` vs. `enforce` mode).
+3. **`AgentIdentity`:** Mints a persistent Ed25519 cryptographic Decentralized Identifier (`did:agent:muxo:<workspaceSlug>`) per workspace and signs the canonical decision payload.
+4. **`AuditLogger`:** Appends the decision to a SHA-256 hash chain (`previousHash ──► hash`), verifies chain integrity (`audit.verify()`), and embeds the resulting **`DecisionRecord`** inside the `ActionPlan` and `ExecutionReceipt`.
+
+### Pillar 2: Supermemory v5 Contextual Brain (`src/providers/supermemory.ts`)
+
+Supermemory v5 provides context-aware tool execution without turning Muxo into a heavyweight LLM host:
+1. **Strict Namespace Isolation:** Every workspace maps to `muxo-v5-<sha256(workspaceId).slice(0, 24)>` (matching Supermemory v5's `^[a-zA-Z0-9_:-]+$` regex).
+2. **Secret Redaction Guard:** Before any content is sent to `client.add()`, `SupermemoryAdapter.sanitizeContent()` strips bearer tokens, API keys (`sk_live_`, `mk_live_`, `sm_`, `ak_`), connection strings (`postgres://`, `redis://`), and `.env` assignments so secrets **never** leave the local AES-256-GCM vault.
+3. **Context-Aware `plan_action` & `get_run_context`:**
+   - When an agent calls `get_run_context`, Muxo fetches `client.profile(namespace)` (returning `static` workspace facts and `dynamic` recent context) alongside active Stripe Projects resources.
+   - When an agent calls `plan_action({ toolSlug, input, reason })`, Muxo runs `client.search(namespace, { query: "${toolSlug} ${reason}", searchMode: "hybrid" })` and attaches top relevant workspace memories (`memoryContext`) to the plan response.
+4. **Automatic Post-Execution Learning:** When a governed run finishes (`execute_<risk>`), Muxo records a sanitized execution summary (`taskType: "memory"`, `dreaming: true`) into the workspace's Supermemory namespace so future runs remember what infrastructure was provisioned and what actions succeeded.
+
+### Pillar 3: Agent-First Autonomous Onboarding (`POST /api/v1/agents/signup`)
+
+Inspired directly by `https://agents.composio.dev/`:
+- **Call 1 (`POST /api/v1/agents/signup`):** An autonomous agent calls `/api/v1/agents/signup` with zero human interaction required. Muxo mints an isolated workspace (`amber-cedar-otter`), an Ed25519 Agent DID (`did:agent:muxo:amber-cedar-otter`), a scoped API key (`mk_live_...`), and a Supermemory v5 namespace, returning ready-to-use MCP configuration immediately.
+- **Call 2 (`POST /api/v1/agents/claim` — Optional):** When the agent wants a human owner to take over the workspace (to approve `provisioning` / `financial` actions or top up Stripe credits), it calls `/api/v1/agents/claim` with `{ email }` and receives a single-use `claim_slug` URL for the human operator.
+
+### Pillar 4: Unified Web Surfaces (`muxo.ai`, `docs.muxo.ai`, `app.muxo.ai`)
+
+| Surface | Domain | Source Location | Role |
+| :--- | :--- | :--- | :--- |
+| **Marketing & Interactive Provider Canvas** | `muxo.ai` | `/Users/test/muxo3/web` (Astro) & built-in `GET /landing` | Interactive draggable grid of 60+ app & cloud providers with keyboard/search navigation (`Catalog.astro`). |
+| **Documentation** | `docs.muxo.ai` | Mintlify (`subdomain: muxo-ai`) | Guides, 18 MCP operation reference, CLI & SDK quickstarts, and governance documentation. |
+| **Operator Console & Runtime** | `app.muxo.ai` | `/Users/test/muxo3/src/ui/console-html.ts` (`GET /`) | Live workspace console for Catalog & Instant Try, Connected Apps, Stripe Projects Vault, Approvals & Receipts, **Supermemory Brain**, **Microsoft Agent Governance**, and **Stripe Billing**. |

package/README.md

@@ -1,53 +1,107 @@
 # Muxo (`@muxoai/platform` / `@muxoai/cli` / `@muxoai/sdk`)
 
-Muxo (`v1.2.3`) is the unified execution, cloud infrastructure provisioning, contextual memory, and cryptographic governance platform for AI agents and applications. Customers and their agents interact exclusively with **Muxo** — never with underlying tool or cloud infrastructure providers directly.
+Muxo (`v1.4.2`) is the unified execution, cloud infrastructure provisioning, contextual memory, and cryptographic governance platform for AI agents and applications. Customers and their agents interact exclusively with **Muxo** — either via structured tool slugs or free-form **Natural Language** (`muxo do`, `POST /api/v1/do`, `client.do()`, and MCP `plan_action`).
 
 See [`ARCHITECTURE.md`](./ARCHITECTURE.md) for the complete internal engineering blueprint, open-source ecosystem Keep/Adopt/Drop matrix, and 4-pillar architecture.
 
-Under the hood, Muxo unifies **four core pillars** behind one **19-operation MCP contract**, OpenAI Plugin (`agent-plugins.org/1.0.0`), REST API, CLI (`@muxoai/cli`), TypeScript SDK (`@muxoai/sdk`), and Web Console (`https://app.muxo.ai`):
+Under the hood, Muxo unifies **four core pillars** plus **Natural Language Routing** and **BYOK (Bring Your Own Key) 0-Credit Execution** behind one **19-operation MCP contract**, OpenAI Plugin (`agent-plugins.org/1.0.0`), REST API, Interactive CLI/TUI (`@muxoai/cli`), TypeScript SDK (`@muxoai/sdk`), and Web Console (`https://app.muxo.ai`):
 
-1. **Composio Connected Apps (`app.*`) & Instant (`instant.*`)** — Managed OAuth SaaS integrations (`app.github.*`, `app.gmail.*`, `app.slack.*`, `app.notion.*`, `app.linear.*`) with live browser OAuth handoff (`wait_for_connection`), zero-OAuth instant capabilities (`instant.web.search`, `instant.web.scrape`, `instant.web.crawl`, `instant.seo.audit`, `instant.hackernews.top_stories`, `instant.github.repo_intel`, `instant.dns.lookup`, `instant.composio.workbench`), plus **Autonomous 2-Call Agent Signup & Claim** (`POST /api/v1/agents/signup` + `POST /api/v1/agents/claim`).
-2. **Stripe Projects Cloud Infrastructure (`resource.*`) + Merchant-of-Record Billing (`muxo_funded`)** — Governed cloud resource provisioning across 60+ providers (`Turso`, `Neon`, `Supabase`, `Cloudflare`, `Vercel`, `Upstash`, `Resend`, `Railway`, `Render`, etc.) with automatic companion plan resolution, AES-256-GCM encrypted secret custody (`muxo env pull`), and unified credit settlement where users purchase Muxo credits and Muxo settles supplier costs from its master accounts.
-3. **Supermemory v5 Contextual Brain (`/ns/muxo-v5-*`)** — Isolated per-workspace long-term static facts, dynamic session context, and hybrid semantic search recalled before every tool plan (`plan_action` & `get_run_context`), with strict secret redaction before memory ingestion.
-4. **Microsoft Agent Governance Toolkit (`@microsoft/agent-governance-sdk` v5.0.0)** — Every planned and executed operation passes through `Agent ──► McpSecurityScanner ──► PolicyEngine ──► AgentIdentity (Ed25519 DID) ──► AuditLogger (SHA-256 chain) ──► DecisionRecord` and produces an HMAC-SHA256 verifiable receipt.
+1. **Connected Apps (`app.*`) & Instant Tools (`instant.*`)** — Managed OAuth SaaS integrations (`app.github.*`, `app.gmail.*`, `app.slack.*`, `app.notion.*`, `app.linear.*`) with live browser OAuth handoff (`wait_for_connection`), zero-OAuth instant capabilities (`instant.web.search`, `instant.web.scrape`, `instant.web.crawl`, `instant.seo.audit`, `instant.hackernews.top_stories`, `instant.github.repo_intel`, `instant.dns.lookup`, `instant.composio.workbench`), plus **CLI-first Autonomous 2-Call Agent Signup & Claim** (`POST /api/v1/agents/signup` + `POST /api/v1/agents/claim`).
+2. **Cloud Infrastructure (`resource.*`) + Unified Credit Billing (`muxo_funded`) & BYOK (`byok`)** — Governed cloud resource provisioning across 60+ providers (`Turso`, `Neon`, `Supabase`, `Cloudflare`, `Vercel`, `Upstash`, `Resend`, `Railway`, `Render`, etc.) with automatic companion plan resolution, AES-256-GCM encrypted secret custody (`muxo env pull`), unified credit settlement (`muxo_funded`), and **0-credit BYOK mode** (`muxo byok set <provider>`) when you bring your own supplier or LLM API keys.
+3. **Workspace Memory (`/ns/muxo-v5-*`)** — Isolated per-workspace long-term static facts, dynamic session context, and hybrid semantic search recalled before every tool plan (`plan_action` & `get_run_context`), with strict secret redaction before memory ingestion.
+4. **Safety & Approvals (Muxo Guardrails)** — Every planned and executed operation passes through prompt-injection security scanning, workspace policy evaluation, cryptographic agent identity (`did:agent:muxo:*`), and produces a verifiable execution audit record.
 
 ---
 
-## Install & Quickstart (External Users & Agents)
+## Install & Quickstart (Humans, Harnesses & Agents)
+
+> **Requirement:** `@muxoai/cli` requires **Node.js 22+** (`node >= 22.0.0`).
 
 ```bash
-# 1. Install the Muxo CLI or run directly via npx
+# 1. Install the Muxo CLI or run directly via npx (requires Node.js 22+)
 npm install -g @muxoai/cli@latest
 
-# 2. Zero-browser autonomous signup (creates ~/.muxo/config.json with mk_live_* key + 250 starter credits)
+# 2. CLI-first autonomous signup against the hosted workspace (creates ~/.muxo/config.json with mk_live_* key + 250 starter credits)
 muxo login --signup --name "my-agent"
 
-# 3. Verify workspace, governance DID, and credit balance
-muxo whoami
+# 3. Launch the Interactive Terminal TUI (Natural Language bar, BYOK Vault, Billing & Status)
+muxo tui
 
-# 4. Run zero-OAuth Instant Tools (Crawl, SEO Audit, DNS, Web Search)
-muxo exec instant.seo.audit --input '{"url":"https://muxo.ai","keywords":["muxo","agent","governance"]}'
-muxo exec instant.web.crawl --input '{"url":"https://muxo.ai","maxPages":3}'
+# 4. Run tools in plain English via the Natural Language Router
+muxo do "check dns A records for muxo.ai"
+muxo do "get top 5 hacker news stories"
+muxo do "audit seo for https://muxo.ai"
 
-# 5. Connect an OAuth SaaS App (Gmail, GitHub, Slack, Notion, Linear)
-muxo link gmail --wait
+# 5. Bring Your Own Key (BYOK) for LLM routing or 0-credit supplier execution
+muxo byok set openai      # Interactive hidden/line prompt if key omitted
+muxo byok set composio    # Executes app.* and instant.* tools at 0 Muxo credit cost
+muxo byok list
 
-# 6. Provision Live Cloud Infrastructure (Turso, Neon, Supabase, Upstash) & Pull Encrypted Secrets
+# 6. Manage Billing, Credits & Plans (Starter $29/mo, Pro $99/mo, yearly 2 months free)
+muxo billing status
+muxo billing plans
+muxo billing topup 1000
+muxo billing upgrade --plan pro --yearly
+muxo billing portal
+
+# 7. Connect an OAuth SaaS App (browser consent handoff) & Provision Live Cloud Infrastructure
+muxo link gmail --wait
 muxo provision turso --input '{"database_name":"my-agent-db"}' --approve
 muxo env pull --out .env.muxo
-```
-
-## Official OpenAI Plugin & MCP Server (`https://api.muxo.ai/mcp`)
 
-Muxo ships a portable OpenAI Plugin (`plugins/muxo/plugin.json` & `plugins/muxo/mcp.json`) and Streamable HTTP MCP Server compliant with [OpenAI Plugins](https://developers.openai.com/plugins/build/plugins) and [OpenAI MCP Server](https://developers.openai.com/plugins/build/mcp-server) specifications:
-
-- **Streamable HTTP MCP Endpoint**: `https://api.muxo.ai/mcp` (and `https://app.muxo.ai/mcp`)
-- **Local Stdio MCP Command**: `npx -y @muxoai/cli@latest mcp`
-- **OAuth 2.1 Discovery & DCR/PKCE**:
-  - `https://api.muxo.ai/.well-known/oauth-protected-resource/mcp` (RFC 9728)
-  - `https://api.muxo.ai/.well-known/oauth-authorization-server` (RFC 8414)
-  - `POST https://api.muxo.ai/oauth/register` (Dynamic Client Registration)
-  - `GET https://api.muxo.ai/oauth/authorize` & `POST https://api.muxo.ai/oauth/token` (PKCE `S256`)
+# 8. Check your setup, memory, and safety controls
+muxo harness                                   # API, MCP, auth, kill switch, audit chain, catalog (exit 1 on failure)
+muxo memory facts                              # Facts with history; add --current for current facts only
+muxo memory forget "old staging database"      # Delete matching memories and retire their facts
+muxo governance scan "text to check"           # Prompt-injection check before storing or forwarding text
+muxo governance pause "incident review"        # Kill switch: stop all agent actions in the workspace
+muxo governance resume
+muxo governance policy --ring 2 --block-destructive-sql true --require-approval financial,destructive
+```
+## Official Plugins, Marketplaces & MCP Setup (`https://api.muxo.ai/mcp`)
+
+Muxo ships a portable OpenAI Plugin (`plugins/muxo/plugin.json` & `plugins/muxo/mcp.json`), Claude Code Plugin (`plugins/muxo/.claude-plugin/plugin.json`), and Streamable HTTP MCP Server:
+
+- **Streamable HTTP MCP Endpoints**: `https://api.muxo.ai/mcp` and `https://app.muxo.ai/mcp`
+- **Local Stdio MCP Command** (requires Node.js 22+, proxies to hosted workspace): `npx -y @muxoai/cli@latest mcp`
+- **Claude Code Marketplace (`muxo@muxo`)**:
+  ```bash
+  claude plugin marketplace add https://api.muxo.ai/.claude-plugin/marketplace.json
+  claude plugin install muxo@muxo
+  ```
+- **OpenAI Codex Marketplace & TOML MCP Alternative**:
+  - **Marketplace (Git Repository or Local Directory)**: Add a Git repository or local directory containing `.agents/plugins/marketplace.json`, then enable `[plugins."muxo@muxo"]` in `.codex/config.toml`.
+  - **TOML MCP Alternative (`~/.codex/config.toml`)**:
+    ```toml
+    [mcp_servers.muxo]
+    url = "https://api.muxo.ai/mcp"
+    ```
+    Or for local stdio proxy (requires Node.js 22+):
+    ```toml
+    [mcp_servers.muxo]
+    command = "npx"
+    args = ["-y", "@muxoai/cli@latest", "mcp"]
+    ```
+- **Claude Desktop**:
+  - **Hosted MCP (Custom Connectors)**: Open **Settings → Connectors → Add custom connector** and enter `https://api.muxo.ai/mcp`.
+  - **Local Stdio Server (`claude_desktop_config.json`, requires Node.js 22+)**:
+    ```json
+    {
+      "mcpServers": {
+        "muxo": {
+          "command": "npx",
+          "args": ["-y", "@muxoai/cli@latest", "mcp"]
+        }
+      }
+    }
+    ```
+- **ChatGPT**:
+  - Open **Plugins → + → Add custom MCP server** (at `https://chatgpt.com/plugins`) and enter `https://api.muxo.ai/mcp`.
+  - **OAuth 2.1 Discovery (CIMD or DCR + PKCE)**:
+    - `https://api.muxo.ai/.well-known/oauth-protected-resource/mcp` (RFC 9728)
+    - `https://api.muxo.ai/.well-known/oauth-authorization-server` (RFC 8414)
+    - Client registration can use **Client ID Metadata Documents (CIMD)** or **Dynamic Client Registration (DCR)** (`POST https://api.muxo.ai/oauth/register`); `/oauth/register` is supported when a client uses DCR rather than running on every flow.
+    - `GET https://api.muxo.ai/oauth/authorize` & `POST https://api.muxo.ai/oauth/token` (PKCE `S256`)
 - **SEP-2640 Skills Import Extension (`io.modelcontextprotocol/skills`)**: `skills/list`, `skills/get`, and `resources/read` serving `skill://muxo/muxo/SKILL.md` and `skill://muxo/setup/SKILL.md` with `sha256` integrity digests.
 - **Tool Annotations & Multi-Account Profile**: All 19 tools include `title` and `annotations` (`readOnlyHint`, `destructiveHint`, `openWorldHint`), plus `_meta["openai/profile"]: true` on `get_profile` and Company Knowledge `search`/`fetch` compatibility.
 
@@ -62,8 +116,8 @@ Muxo ships a portable OpenAI Plugin (`plugins/muxo/plugin.json` & `plugins/muxo/
 | `src/store.ts` | SQLite (`node:sqlite`) store, AES-256-GCM secret vault, credit/settlement ledger, memories, agent claims, and HMAC-SHA256 receipt chain |
 | `src/providers/composio-sdk.ts` | Live Composio v3 Connected Apps adapter (catalog search, OAuth sessions/links, tool execution) |
 | `src/providers/composio-instant.ts` | Live Composio Instant adapter (`search`, `scrape`, `crawl`, `seo.audit`, `hackernews`, `github.repo_intel`, `dns.lookup`, `workbench`) |
-| `src/providers/stripe-projects.ts` | Live Stripe Projects CLI bridge (`status`, `catalog`, `add`, `rotate`, `remove`, `env --pull`) |
-| `src/providers/stripe-billing.ts` | Live Stripe Checkout billing (`$29/mo Starter Plan` & `$10 / +1,000 Credits Pack`) |
+| `src/providers/stripe-projects.ts` | Live Stripe v2 Provisioning REST API (`2026-09-30.preview`) & Stripe Projects CLI bridge (`eligibility`, `catalog`, `payment_profile`, `provider_connections`, `resources`, `reveal_access_configuration`, `rotate`, `remove`, `env --pull`) |
+| `src/providers/stripe-billing.ts` | Live Stripe Checkout billing (Starter `$29/mo`, Pro `$99/mo`, yearly billing & credit packs with volume discounts) |
 | `src/providers/microsoft-governance.ts` | Microsoft Agent Governance Toolkit v5.0.0 (`McpSecurityScanner`, `PolicyEngine`, `AgentIdentity` Ed25519 DID, `AuditLogger`) |
 | `src/providers/supermemory.ts` | Supermemory v5 Contextual Brain (`profile`, hybrid `search`, secret-redacted `add`, `delete`) |
 | `src/engine.ts` | Unified Governance, Memory & Execution Engine implementing all 19 canonical MCP operations |

package/dist/clerk.d.ts

@@ -0,0 +1,35 @@
+export interface ClerkConfig {
+    publishableKey: string;
+    frontendApi: string;
+    authorizedParties: string[];
+    jwtKey?: string;
+    secretKey?: string;
+}
+export interface ClerkSession {
+    userId: string;
+    sessionId: string;
+    email?: string;
+    emailVerified?: boolean;
+}
+export interface ClerkProfile {
+    email: string | null;
+    emailVerified: boolean;
+    name: string | null;
+    /** Every verified address on the account, lowercased, primary included. */
+    verifiedEmails: string[];
+}
+export interface ClerkEnv {
+    CLERK_PUBLISHABLE_KEY?: string;
+    CLERK_SECRET_KEY?: string;
+    CLERK_JWT_KEY?: string;
+    CLERK_AUTHORIZED_PARTIES?: string;
+}
+/** Derives the Clerk Frontend API origin encoded in a publishable key (pk_live_/pk_test_). */
+export declare function clerkFrontendApi(publishableKey: string): string | null;
+export declare function readClerkConfig(env: ClerkEnv, fallbackAuthorizedParty?: string): ClerkConfig | null;
+export declare function looksLikeJwt(token: string): boolean;
+/** Verifies a Clerk session JWT (RS256) and returns the session identity, or null if invalid. */
+export declare function verifyClerkSessionToken(token: string, config: ClerkConfig, nowSeconds?: number): Promise<ClerkSession | null>;
+/** Reads the primary email and name for a Clerk user through the Backend API. */
+export declare function fetchClerkProfile(userId: string, secretKey: string): Promise<ClerkProfile | null>;
+export declare function clerkBrowserScriptUrl(frontendApi: string): string;

package/dist/clerk.js

@@ -0,0 +1,201 @@
+const RS256 = { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" };
+const JWKS_TTL_MS = 10 * 60 * 1000;
+const JWKS_RETRY_MS = 30 * 1000;
+const CLOCK_SKEW_SECONDS = 5;
+function base64UrlToBytes(input) {
+    const normalized = input.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized + "=".repeat((4 - (normalized.length % 4)) % 4);
+    const binary = atob(padded);
+    const bytes = new Uint8Array(new ArrayBuffer(binary.length));
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+function decodeJsonSegment(segment) {
+    try {
+        const parsed = JSON.parse(new TextDecoder().decode(base64UrlToBytes(segment)));
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Derives the Clerk Frontend API origin encoded in a publishable key (pk_live_/pk_test_). */
+export function clerkFrontendApi(publishableKey) {
+    const match = /^pk_(?:live|test)_([A-Za-z0-9+/=_-]{4,512})$/.exec(publishableKey.trim());
+    if (!match)
+        return null;
+    let decoded;
+    try {
+        decoded = new TextDecoder().decode(base64UrlToBytes(match[1]));
+    }
+    catch {
+        return null;
+    }
+    if (!decoded.endsWith("$"))
+        return null;
+    const host = decoded.slice(0, -1);
+    if (!/^(?=.{4,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/i.test(host))
+        return null;
+    return `https://${host.toLowerCase()}`;
+}
+export function readClerkConfig(env, fallbackAuthorizedParty) {
+    const publishableKey = (env.CLERK_PUBLISHABLE_KEY || "").trim();
+    if (!publishableKey)
+        return null;
+    const frontendApi = clerkFrontendApi(publishableKey);
+    if (!frontendApi)
+        return null;
+    const configured = (env.CLERK_AUTHORIZED_PARTIES || "")
+        .split(",")
+        .map((s) => s.trim().replace(/\/+$/, ""))
+        .filter(Boolean);
+    const authorizedParties = configured.length
+        ? configured
+        : fallbackAuthorizedParty
+            ? [fallbackAuthorizedParty.replace(/\/+$/, "")]
+            : [];
+    return {
+        publishableKey,
+        frontendApi,
+        authorizedParties,
+        jwtKey: (env.CLERK_JWT_KEY || "").trim() || undefined,
+        secretKey: (env.CLERK_SECRET_KEY || "").trim() || undefined,
+    };
+}
+export function looksLikeJwt(token) {
+    return /^eyJ[A-Za-z0-9_-]*\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/.test(token);
+}
+async function importPemKey(pem) {
+    const body = pem
+        .replace(/\\n/g, "\n")
+        .replace(/-----BEGIN PUBLIC KEY-----/, "")
+        .replace(/-----END PUBLIC KEY-----/, "")
+        .replace(/\s+/g, "");
+    return crypto.subtle.importKey("spki", base64UrlToBytes(body), RS256, false, ["verify"]);
+}
+// Only public verification keys are cached; never tokens or user data.
+const jwksCache = new Map();
+const pemCache = new Map();
+async function loadJwks(frontendApi) {
+    const res = await fetch(`${frontendApi}/.well-known/jwks.json`, {
+        headers: { Accept: "application/json" },
+        redirect: "manual",
+    });
+    if (res.status !== 200)
+        throw new Error(`Clerk JWKS unavailable (HTTP ${res.status})`);
+    const doc = (await res.json());
+    const keys = new Map();
+    for (const jwk of doc.keys || []) {
+        if (jwk.kty !== "RSA" || typeof jwk.kid !== "string")
+            continue;
+        if (jwk.use && jwk.use !== "sig")
+            continue;
+        const key = await crypto.subtle.importKey("jwk", { kty: "RSA", n: String(jwk.n), e: String(jwk.e), alg: "RS256", ext: true }, RS256, false, ["verify"]);
+        keys.set(jwk.kid, key);
+    }
+    return keys;
+}
+async function verificationKey(config, kid) {
+    if (config.jwtKey) {
+        let key = pemCache.get(config.jwtKey);
+        if (!key) {
+            key = await importPemKey(config.jwtKey);
+            pemCache.set(config.jwtKey, key);
+        }
+        return key;
+    }
+    if (!kid)
+        return null;
+    const now = Date.now();
+    const cached = jwksCache.get(config.frontendApi);
+    const fresh = cached && now - cached.fetchedAt < JWKS_TTL_MS;
+    if (cached?.keys.has(kid) && fresh)
+        return cached.keys.get(kid);
+    // Refetch for unknown kids (key rotation), but not more than once per retry window.
+    if (!cached || !fresh || now - cached.fetchedAt > JWKS_RETRY_MS) {
+        const keys = await loadJwks(config.frontendApi);
+        jwksCache.set(config.frontendApi, { keys, fetchedAt: now });
+        return keys.get(kid) || null;
+    }
+    return cached.keys.get(kid) || null;
+}
+/** Verifies a Clerk session JWT (RS256) and returns the session identity, or null if invalid. */
+export async function verifyClerkSessionToken(token, config, nowSeconds = Math.floor(Date.now() / 1000)) {
+    if (!looksLikeJwt(token) || token.length > 16_384)
+        return null;
+    const [headerPart, payloadPart, signaturePart] = token.split(".");
+    const header = decodeJsonSegment(headerPart);
+    const payload = decodeJsonSegment(payloadPart);
+    if (!header || !payload || header.alg !== "RS256")
+        return null;
+    let key;
+    try {
+        key = await verificationKey(config, typeof header.kid === "string" ? header.kid : undefined);
+    }
+    catch {
+        return null;
+    }
+    if (!key)
+        return null;
+    let valid = false;
+    try {
+        valid = await crypto.subtle.verify(RS256, key, base64UrlToBytes(signaturePart), new TextEncoder().encode(`${headerPart}.${payloadPart}`));
+    }
+    catch {
+        return null;
+    }
+    if (!valid)
+        return null;
+    if (payload.iss !== config.frontendApi)
+        return null;
+    if (typeof payload.exp !== "number" || payload.exp + CLOCK_SKEW_SECONDS < nowSeconds)
+        return null;
+    if (typeof payload.nbf === "number" && payload.nbf - CLOCK_SKEW_SECONDS > nowSeconds)
+        return null;
+    if (typeof payload.iat === "number" && payload.iat - CLOCK_SKEW_SECONDS > nowSeconds)
+        return null;
+    if (typeof payload.azp === "string" &&
+        config.authorizedParties.length > 0 &&
+        !config.authorizedParties.includes(payload.azp.replace(/\/+$/, ""))) {
+        return null;
+    }
+    if (payload.sts !== undefined && payload.sts !== "active")
+        return null;
+    if (typeof payload.sub !== "string" || !/^user_[A-Za-z0-9]{1,128}$/.test(payload.sub))
+        return null;
+    return {
+        userId: payload.sub,
+        sessionId: typeof payload.sid === "string" ? payload.sid : "",
+        email: typeof payload.email === "string" ? payload.email.toLowerCase() : undefined,
+        emailVerified: payload.email_verified === true,
+    };
+}
+/** Reads the primary email and name for a Clerk user through the Backend API. */
+export async function fetchClerkProfile(userId, secretKey) {
+    try {
+        const res = await fetch(`https://api.clerk.com/v1/users/${encodeURIComponent(userId)}`, {
+            headers: { Authorization: `Bearer ${secretKey}`, Accept: "application/json" },
+        });
+        if (!res.ok)
+            return null;
+        const user = (await res.json());
+        const addresses = user.email_addresses || [];
+        const primary = addresses.find((e) => e.id === user.primary_email_address_id) || addresses[0];
+        const name = [user.first_name, user.last_name].filter(Boolean).join(" ").trim() || user.username || null;
+        return {
+            email: primary?.email_address ? primary.email_address.toLowerCase() : null,
+            emailVerified: primary?.verification?.status === "verified",
+            name,
+            verifiedEmails: addresses
+                .filter((e) => e.email_address && e.verification?.status === "verified")
+                .map((e) => e.email_address.toLowerCase()),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function clerkBrowserScriptUrl(frontendApi) {
+    return `${frontendApi}/npm/@clerk/clerk-js@5/dist/clerk.browser.js`;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};