@muxoai/sdk 1.2.3 → 1.3.0

package/package.json

@@ -1,20 +1,80 @@
 {
   "name": "@muxoai/sdk",
-  "version": "1.2.3",
-  "description": "Muxo TypeScript & Node.js SDK — Governed Agent Execution, OAuth Handoff, Cloud Provisioning & Cryptographic Receipts",
+  "version": "1.3.0",
+  "description": "Muxo — Unified Execution, Provisioning & Governance Platform over Composio, Stripe Projects, Microsoft Agent Governance & Supermemory",
+  "private": false,
   "license": "MIT",
   "homepage": "https://muxo.ai",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/muxoai/muxo.git"
   },
+  "keywords": [
+    "muxo",
+    "agents",
+    "mcp",
+    "cli",
+    "sdk",
+    "composio",
+    "stripe",
+    "governance",
+    "supermemory"
+  ],
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
-  "main": "./index.js",
-  "types": "./index.d.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./sdk": {
+      "types": "./dist/sdk.d.ts",
+      "default": "./dist/sdk.js"
+    }
+  },
+  "bin": {
+    "muxo": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src/catalogues",
+    "vendor/microsoft-governance/package.json",
+    "vendor/microsoft-governance/dist",
+    "plugins",
+    ".agents",
+    ".claude-plugin",
+    ".codex",
+    "README.md",
+    "ARCHITECTURE.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node --no-warnings dist/server.js",
+    "dev": "tsx watch src/server.ts",
+    "cli": "tsx src/cli.ts",
+    "mcp": "tsx src/cli.ts mcp",
+    "test": "node --no-warnings --import tsx --test tests/*.test.ts"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
   "dependencies": {
-    "@muxoai/platform": "1.2.3"
+    "@composio/core": "^0.6.4",
+    "@noble/ciphers": "^2.0.1",
+    "@noble/curves": "^1.8.1",
+    "@noble/ed25519": "^2.2.3",
+    "@noble/hashes": "^1.7.1",
+    "js-yaml": "^4.1.1",
+    "supermemory": "^5.0.2",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
   }
-}
+}

package/plugins/muxo/.app.json

@@ -0,0 +1,8 @@
+{
+  "apps": {
+    "muxo": {
+      "id": "plugin_asdk_app_muxo_platform_v1",
+      "category": "Productivity"
+    }
+  }
+}

package/plugins/muxo/.claude-plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "muxo",
+  "version": "1.2.3",
+  "description": "Governed agent execution across 1,000+ Connected Apps (managed OAuth handoff), Instant Tools (search, scrape, crawl, SEO audit), live Cloud Infrastructure provisioning, Supermemory v5 recall, and Microsoft Agent Governance Ed25519 receipts.",
+  "author": {
+    "name": "Muxo",
+    "email": "founders@muxo.ai",
+    "url": "https://muxo.ai"
+  },
+  "homepage": "https://muxo.ai",
+  "repository": "https://github.com/muxo-ai/muxo",
+  "license": "MIT",
+  "skills": "./skills/",
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": "./.mcp.json"
+}

package/plugins/muxo/.codex-plugin/plugin.json

@@ -0,0 +1,55 @@
+{
+  "name": "muxo",
+  "version": "1.2.3",
+  "description": "Your agent decides what to do — Muxo governs, provisions, remembers, and executes it. Unified access to 1,000+ SaaS apps (managed OAuth handoff), Instant Tools (search, scrape, crawl, SEO audit), live Cloud Infrastructure provisioning (Postgres, Redis, SQLite, Storage), Supermemory v5 contextual recall, and Ed25519-signed Microsoft Agent Governance receipts through the hosted app or local CLI.",
+  "author": {
+    "name": "Muxo",
+    "email": "founders@muxo.ai",
+    "url": "https://muxo.ai"
+  },
+  "homepage": "https://muxo.ai",
+  "repository": "https://github.com/muxo-ai/muxo",
+  "license": "MIT",
+  "keywords": [
+    "muxo",
+    "openai",
+    "chatgpt",
+    "codex",
+    "app",
+    "mcp",
+    "cli",
+    "oauth",
+    "infrastructure",
+    "governance",
+    "supermemory",
+    "integrations",
+    "automation",
+    "productivity"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "apps": "./.app.json",
+  "onboardingSkill": "./skills/setup/SKILL.md",
+  "interface": {
+    "displayName": "Muxo",
+    "shortDescription": "Governed SaaS apps, cloud infra, instant web/SEO tools & memory",
+    "longDescription": "Discover, plan, authorize via OAuth handoff, and execute governed actions across 1,000+ Connected Apps (GitHub, Gmail, Slack, Notion, Linear), Instant Tools (web search, scrape, multi-page crawl, technical SEO audit), and live Cloud Infrastructure (Neon Postgres, Turso SQLite, Supabase, Cloudflare, Vercel) with Supermemory v5 workspace recall and Ed25519 cryptographic receipts.",
+    "developerName": "Muxo",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "Write"
+    ],
+    "websiteURL": "https://muxo.ai",
+    "privacyPolicyURL": "https://muxo.ai/privacy",
+    "termsOfServiceURL": "https://muxo.ai/terms",
+    "defaultPrompt": [
+      "Audit https://muxo.ai for technical SEO and crawl its top pages.",
+      "Connect my GitHub or Gmail account and open a tracking issue for our next release.",
+      "Provision a free Turso SQLite database and pull the credentials into .env.muxo."
+    ],
+    "composerIcon": "./assets/logo.png",
+    "logo": "./assets/logo.png",
+    "brandColor": "#6366F1"
+  }
+}

package/plugins/muxo/.mcp.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "muxo": {
+      "type": "streamable-http",
+      "url": "https://api.muxo.ai/mcp",
+      "command": "npx",
+      "args": ["-y", "@muxoai/platform@latest", "mcp"],
+      "oauth": {
+        "clientId": "muxo-openai-plugin",
+        "callbackPort": 3118,
+        "scopes": [
+          "muxo:mcp",
+          "muxo:read",
+          "muxo:execute",
+          "muxo:provision"
+        ]
+      },
+      "extensions": {
+        "com.openai": {
+          "auth": {
+            "type": "mixed",
+            "client": {
+              "mode": "dcr"
+            },
+            "authorizationUrl": "https://api.muxo.ai/oauth/authorize",
+            "tokenUrl": "https://api.muxo.ai/oauth/token",
+            "registrationUrl": "https://api.muxo.ai/oauth/register",
+            "baseScopes": [
+              "muxo:mcp",
+              "muxo:read",
+              "muxo:execute",
+              "muxo:provision"
+            ]
+          }
+        }
+      }
+    }
+  }
+}

package/plugins/muxo/assets/logo.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" width="128" height="128">
+  <rect width="128" height="128" rx="28" fill="#090A0F"/>
+  <rect x="8" y="8" width="112" height="112" rx="22" fill="none" stroke="#6366F1" stroke-width="4"/>
+  <path d="M32 88V40L64 68L96 40V88" fill="none" stroke="#F4F4F6" stroke-width="10" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="64" cy="92" r="7" fill="#34D399"/>
+</svg>

package/plugins/muxo/hooks/hooks.json

@@ -0,0 +1,27 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${PLUGIN_ROOT}/hooks/session-start.sh\"",
+            "timeout": 8
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${PLUGIN_ROOT}/hooks/user-prompt-submit.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/muxo/hooks/session-start.sh

@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+set -u
+
+cat >/dev/null 2>&1 || true
+
+CACHE="${TMPDIR:-/tmp}/muxo-plugin-toolkits.cache"
+REPO_CLI="$(cd "$(dirname "$0")/../../.." 2>/dev/null && pwd)/dist/cli.js"
+
+run_muxo() {
+  if [ -n "${MUXO_CLI_BIN:-}" ] && [ -x "${MUXO_CLI_BIN}" ]; then
+    "${MUXO_CLI_BIN}" "$@"
+  elif [ -f "$REPO_CLI" ] && command -v node >/dev/null 2>&1; then
+    node "$REPO_CLI" "$@"
+  elif command -v muxo >/dev/null 2>&1; then
+    muxo "$@"
+  else
+    return 127
+  fi
+}
+
+cache_pid=""
+if (command -v muxo >/dev/null 2>&1 || [ -f "$REPO_CLI" ]); then
+  (
+    tmp="$(mktemp "${CACHE}.XXXXXX" 2>/dev/null)" || exit 0
+    printf '%s\n' \
+      github gmail slack notion linear jira hubspot calendar stripe \
+      neon supabase turso upstash cloudflare vercel prisma mongodb \
+      hackernews dns supermemory governance >"$tmp" 2>/dev/null
+    if [ -s "$tmp" ]; then
+      mv -f "$tmp" "$CACHE" 2>/dev/null || rm -f "$tmp" 2>/dev/null
+    else
+      rm -f "$tmp" 2>/dev/null
+    fi
+  ) &
+  cache_pid=$!
+fi
+
+# Detached 24h self-update check for Codex marketplace installs
+SELF_UPDATE_STATE="${HOME:-}/.muxo/plugin-codex-self-update.json"
+if [ -n "${HOME:-}" ] && command -v codex >/dev/null 2>&1; then
+  now="$(date +%s)"
+  last="$(sed -n 's/.*"lastAttempt"[[:space:]]*:[[:space:]]*\([0-9]\{1,\}\).*/\1/p' "$SELF_UPDATE_STATE" 2>/dev/null | head -n 1)"
+  if [ -z "$last" ] || [ "$((now - last))" -ge 86400 ]; then
+    own_version="$(sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' \
+      "$(dirname "$0")/../.codex-plugin/plugin.json" 2>/dev/null | head -n 1)"
+    (
+      mkdir -p "${SELF_UPDATE_STATE%/*}" || exit 0
+      printf '{"lastAttempt":%s,"lastResult":"running"}\n' "$now" >"$SELF_UPDATE_STATE" || exit 0
+      result="error"
+      if codex plugin marketplace upgrade muxo; then
+        added="$(codex plugin add muxo@muxo --json 2>/dev/null \
+          | sed -n 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -n 1)"
+        if [ -n "$added" ]; then
+          if [ "$added" = "$own_version" ]; then result="current"; else result="updated"; fi
+        fi
+      fi
+      printf '{"lastAttempt":%s,"lastResult":"%s"}\n' "$now" "$result" >"$SELF_UPDATE_STATE"
+    ) >/dev/null 2>&1 </dev/null &
+  fi
+fi
+
+if ! command -v muxo >/dev/null 2>&1 && [ ! -f "$REPO_CLI" ]; then
+  cli_status="The local Muxo CLI is not installed. Run \`npm install -g muxo-platform && muxo login\` to enable local CLI workflows. Until it is available, use callable hosted Muxo MCP tools."
+else
+  cli_status="The local Muxo CLI is available but is not signed in; run \`muxo login\` before choosing it."
+  if whoami_output="$(run_muxo whoami 2>&1)" \
+    && [ -n "$(printf '%s' "$whoami_output" | tr -d '[:space:]')" ] \
+    && ! printf '%s' "$whoami_output" | grep -Eiq '"authenticated"[[:space:]]*:[[:space:]]*false|not[[:space:]-]+logged[[:space:]-]+in'; then
+    cli_status="The local Muxo CLI is available and signed in (governed Ed25519 identity + Supermemory v5 recall active)."
+  fi
+fi
+
+[ -n "$cache_pid" ] && wait "$cache_pid" 2>/dev/null
+
+line="This is a terminal/Codex/Droid session with the Muxo plugin. Prefer the local Muxo CLI (\`muxo\`) for governed SaaS actions (\`app.*\`), zero-auth Instant tools (\`instant.*\`), live cloud infrastructure provisioning (\`resource.*\`), OAuth handoff (\`muxo link <provider> --wait\`), and \`.env\` credential pulls (\`muxo env pull\`). ${cli_status} Use callable hosted Muxo MCP tools when the CLI is unavailable or the user explicitly requests MCP. Never automatically replay an uncertain write or provisioning action through the other surface."
+
+if command -v jq >/dev/null 2>&1; then
+  jq -n --arg c "$line" \
+    '{hookSpecificOutput:{hookEventName:"SessionStart",additionalContext:$c}}'
+else
+  esc="$(printf '%s' "$line" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g')"
+  printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"%s"}}\n' "$esc"
+fi
+
+exit 0

package/plugins/muxo/hooks/user-prompt-submit.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+set -u
+
+CACHE="${TMPDIR:-/tmp}/muxo-plugin-toolkits.cache"
+[ -f "$CACHE" ] && [ -s "$CACHE" ] || exit 0
+
+REPO_CLI="$(cd "$(dirname "$0")/../../.." 2>/dev/null && pwd)/dist/cli.js"
+if ! command -v muxo >/dev/null 2>&1 && [ ! -f "$REPO_CLI" ]; then
+  exit 0
+fi
+
+payload="$(cat)"
+if command -v jq >/dev/null 2>&1; then
+  prompt="$(printf '%s' "$payload" | jq -r '.prompt // empty' 2>/dev/null)"
+else
+  prompt=""
+fi
+[ -n "$prompt" ] || prompt="$payload"
+
+norm="$(printf '%s' "$prompt" \
+  | tr '[:upper:]' '[:lower:]' \
+  | tr -c 'a-z0-9' ' ')"
+norm=" $norm "
+
+matched=0
+while IFS= read -r kw; do
+  [ -n "$kw" ] || continue
+  case "$norm" in
+    *" $kw "*) matched=1; break ;;
+  esac
+done <"$CACHE"
+
+[ "$matched" -eq 1 ] || exit 0
+
+line="You mentioned a SaaS app, cloud infrastructure provider, or memory/governance operation that Muxo governs. Prefer the local Muxo CLI (\`muxo search\`, \`muxo link <provider> --wait\`, \`muxo exec\`, \`muxo env pull\`) in terminal sessions, or use callable hosted Muxo MCP tools (\`search_tools\`, \`plan_action\`, \`start_connection\`, \`wait_for_connection\`, \`execute_*\`) when in hosted mode. Never replay an uncertain write or provisioning call through the other surface."
+
+if command -v jq >/dev/null 2>&1; then
+  jq -n --arg c "$line" \
+    '{hookSpecificOutput:{hookEventName:"UserPromptSubmit",additionalContext:$c}}'
+else
+  esc="$(printf '%s' "$line" | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g')"
+  printf '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"%s"}}\n' "$esc"
+fi
+
+exit 0

package/plugins/muxo/mcp.json

@@ -0,0 +1,38 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "muxo": {
+      "type": "streamable-http",
+      "url": "https://api.muxo.ai/mcp",
+      "oauth": {
+        "clientId": "muxo-openai-plugin",
+        "callbackPort": 3118,
+        "scopes": [
+          "muxo:mcp",
+          "muxo:read",
+          "muxo:execute",
+          "muxo:provision"
+        ]
+      },
+      "extensions": {
+        "com.openai": {
+          "auth": {
+            "type": "mixed",
+            "client": {
+              "mode": "dcr"
+            },
+            "authorizationUrl": "https://api.muxo.ai/oauth/authorize",
+            "tokenUrl": "https://api.muxo.ai/oauth/token",
+            "registrationUrl": "https://api.muxo.ai/oauth/register",
+            "baseScopes": [
+              "muxo:mcp",
+              "muxo:read",
+              "muxo:execute",
+              "muxo:provision"
+            ]
+          }
+        }
+      }
+    }
+  }
+}

package/plugins/muxo/plugin.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "muxo",
+  "version": "1.2.3",
+  "description": "Your agent decides what to do — Muxo governs, provisions, remembers, and executes it. Unified access to 1,000+ SaaS apps (managed OAuth handoff), Instant Tools (search, scrape, crawl, SEO audit), live Cloud Infrastructure provisioning (Postgres, Redis, SQLite, Storage), Supermemory v5 contextual recall, and Ed25519-signed Microsoft Agent Governance receipts.",
+  "author": {
+    "name": "Muxo",
+    "email": "founders@muxo.ai",
+    "url": "https://muxo.ai"
+  },
+  "homepage": "https://muxo.ai",
+  "repository": "https://github.com/muxo-ai/muxo",
+  "license": "MIT",
+  "keywords": [
+    "muxo",
+    "openai",
+    "chatgpt",
+    "codex",
+    "mcp",
+    "cli",
+    "oauth",
+    "infrastructure",
+    "governance",
+    "supermemory",
+    "integrations",
+    "automation",
+    "productivity"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./mcp.json",
+  "extensions": {
+    "com.openai": {
+      "apps": "./.app.json",
+      "onboardingSkill": "./skills/setup/SKILL.md",
+      "interface": {
+        "displayName": "Muxo",
+        "shortDescription": "Governed SaaS apps, cloud infra, instant web/SEO tools & memory",
+        "longDescription": "Discover, plan, authorize via OAuth handoff, and execute governed actions across 1,000+ Connected Apps (GitHub, Gmail, Slack, Notion, Linear), Instant Tools (web search, scrape, multi-page crawl, technical SEO audit), and live Cloud Infrastructure (Turso SQLite, Neon Postgres, Supabase, Upstash Redis, Resend) with Supermemory v5 workspace recall and Ed25519 cryptographic receipts.",
+        "developerName": "Muxo",
+        "category": "Productivity",
+        "capabilities": [
+          "Interactive",
+          "Write"
+        ],
+        "websiteURL": "https://muxo.ai",
+        "privacyPolicyURL": "https://muxo.ai/privacy",
+        "termsOfServiceURL": "https://muxo.ai/terms",
+        "defaultPrompt": [
+          "Audit https://muxo.ai for technical SEO and crawl its top pages.",
+          "Connect my Gmail or GitHub account via OAuth handoff and fetch recent items.",
+          "Provision a Turso SQLite database and store its connection secrets in the Muxo Vault."
+        ],
+        "composerIcon": "./assets/logo.png",
+        "logo": "./assets/logo.png",
+        "brandColor": "#6366F1"
+      }
+    }
+  }
+}

package/plugins/muxo/skills/muxo/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: muxo
+description: Route governed Muxo work between the hosted MCP-backed app and the local Muxo CLI. Use when a user wants to read or act on external SaaS services (GitHub, Gmail, Slack, Notion, Linear, Jira, HubSpot), run zero-OAuth Instant tools (web search, scrape, DNS, Hacker News), provision cloud infrastructure (Neon Postgres, Turso SQLite, Supabase, Cloudflare, Vercel, Prisma), recover a missing OAuth connection via handoff, recall workspace context from Supermemory v5, or verify Ed25519-signed Microsoft Agent Governance receipts.
+---
+
+# Muxo
+
+Choose a surface from the capabilities available in the current task, then keep the workflow on that surface unless the task itself requires the other one.
+
+## Choose the surface
+
+1. In a terminal, Codex, Claude Code, or Droid environment, prefer the local Muxo CLI (`muxo`) for Muxo work, especially when pulling `.env` credentials (`muxo env pull`), scripting workflows, or running interactive OAuth handoffs (`muxo link <provider> --wait`). If `muxo` is missing, explain how to install or sign in (`muxo login`) before choosing it; do not install software without user approval. Read [references/cli.md](references/cli.md) before using that surface.
+2. In ChatGPT web/app or another environment without a usable terminal, use callable, authorized hosted Muxo MCP tools. Read [references/mcp.md](references/mcp.md) before using that surface.
+3. If both surfaces are available in a terminal environment, use the CLI unless the user explicitly requests the hosted MCP surface or the required capability exists only there.
+4. If neither surface is available, explain both setup paths: authorize or enable the hosted Muxo MCP server (`POST /mcp` or autonomous signup at `POST /api/v1/agents/signup`), or sign in to the CLI (`muxo login`).
+
+Do not tell a user in ChatGPT web/app or another hosted-only environment to install the CLI before using callable hosted MCP tools.
+
+## Execute safely across Muxo's 4 pillars
+
+- **Discover & Inspect**: For an unknown capability across Instant Tools (`instant.*`), Connected Apps (`app.*`), or Cloud Infrastructure (`resource.*`), discover the tool first (`search_tools` / `muxo search`), inspect its schema (`inspect_tool` / `muxo inspect`), and then plan it.
+- **External User OAuth Handoff**: When `plan_action` returns `authHandoff.required: true` (or a tool reports a missing connection), present `authHandoff.redirectUrl` to the user, poll `wait_for_connection` (or `muxo wait <provider>`), and resume the original plan once `status === "active"`.
+- **Single-Execution & Governance**: Every mutation or provisioning call creates a governed `plan_*` evaluated by Microsoft Agent Governance (`McpSecurityScanner ──► PolicyEngine ──► AgentIdentity Ed25519 DID ──► DecisionRecord`). Execute each confirmed plan exactly once on its matching risk lane (`execute_read`, `execute_write`, `execute_admin`, `execute_financial`, `execute_provisioning`, `execute_destructive`).
+- **Uncertain Write Boundary**: After a timeout or unclear write/provisioning result, check `get_run` or `get_receipt` before doing anything else. Never automatically retry an uncertain write through the other surface.
+- **Secret Custody**: Provisioned infrastructure credentials are encrypted in the Muxo AES-256-GCM Vault and redacted from Supermemory v5. Never expose raw tokens, connection secrets, or authentication material in chat responses.

package/plugins/muxo/skills/muxo/references/cli.md

@@ -0,0 +1,57 @@
+# Local Muxo CLI
+
+Prefer this path in terminal, Codex, Claude Code, and Droid environments when the `muxo` command is available. It supports governed SaaS actions (`app.*`), zero-OAuth Instant tools (`instant.*`), live cloud infrastructure provisioning (`resource.*`), interactive OAuth handoffs, and local `.env` credential pulls.
+
+## Workflow
+
+1. **Check or initialize external user authentication**:
+   ```bash
+   muxo whoami
+   # Create an isolated autonomous workspace & save credentials to ~/.muxo/config.json:
+   muxo login --signup --name "MyAgent"
+   # Or sign in with an existing mk_live_* key:
+   muxo login --api-key mk_live_<your_key>
+   # Optional: generate a human owner claim link for the workspace:
+   muxo claim founder@company.com
+   ```
+
+2. **Discover and inspect tools across all 3 lanes**:
+   ```bash
+   muxo search "github issue" --lane composio_sdk
+   muxo search "turso" --lane stripe_projects
+   muxo inspect app.github.create_issue
+   ```
+
+3. **External user OAuth handoff (`muxo link`)**:
+   - If a toolkit is not connected, start the OAuth handoff and optionally poll until the user completes browser authorization:
+   ```bash
+   muxo link github --wait --timeout 60
+   # Or poll an existing pending connection handoff:
+   muxo wait github --timeout 30
+   ```
+
+4. **Plan and execute governed operations**:
+   ```bash
+   # One-step governed plan + execute (pass --approve for high-risk/provisioning):
+   muxo exec instant.hackernews.top_stories --input '{"limit":5}'
+   muxo exec resource.turso.database --input '{"resource_name":"app-db"}' --approve
+
+   # Or explicit two-step plan -> approve -> run:
+   muxo plan app.github.create_issue --input '{"owner":"acme","repo":"app","title":"Bug"}'
+   muxo approve plan_<id>
+   muxo run plan_<id>
+   ```
+
+5. **Pull encrypted cloud infrastructure credentials into local `.env`**:
+   ```bash
+   muxo env pull --out .env.muxo
+   ```
+
+6. **Recall Supermemory v5 context & verify Ed25519 governance receipts**:
+   ```bash
+   muxo memory "database provisioning"
+   muxo governance
+   muxo receipts <rcpt_id>
+   ```
+
+If a write or provisioning call's result is uncertain, inspect `muxo receipts` or `muxo resources` before retrying. Do not replay an uncertain write through the hosted MCP surface.

package/plugins/muxo/skills/muxo/references/mcp.md

@@ -0,0 +1,25 @@
+# Hosted Muxo MCP App
+
+Use this path in ChatGPT web/app, when no usable terminal exists, or when the user explicitly requests the hosted MCP surface. The runtime's tool descriptions and schemas are the source of truth.
+
+## Workflow
+
+1. **Context & Memory Recall**: Call `get_run_context({ query })` when workspace facts, prior execution history (Supermemory v5), provisioned resources, or Microsoft Agent Governance status are relevant to the task.
+2. **Discovery & Schema Inspection**:
+   - Call `search_tools({ query, lane })` across `composio_instant` (`instant.*`), `composio_sdk` (`app.*`), or `stripe_projects` (`resource.*`).
+   - Call `inspect_tool({ tool_slug })` to inspect the JSON input schema, `riskLevel`, and `creditCost`.
+3. **Governed Planning**:
+   - Call `plan_action({ tool_slug, input, reason })` to evaluate policy, scan for prompt injection (`McpSecurityScanner`), sign an Ed25519 `DecisionRecord`, and receive `plan.id`.
+4. **External User OAuth Handoff & Recovery**:
+   - If `plan_action` returns `authHandoff.required: true` (or a connection is missing), share `authHandoff.redirectUrl` (or call `start_connection({ provider })`) so the user can authorize in their browser.
+   - Poll `wait_for_connection({ provider, timeout_seconds: 15 })` until `connected: true` (`status: "active"`), then resume the original `plan.id`.
+5. **Risk-Scoped Execution & Receipts**:
+   - Call the matching execution tool (`execute_read`, `execute_write`, `execute_admin`, `execute_financial`, `execute_provisioning`, or `execute_destructive`) with `{ plan_id }`.
+   - Call `get_receipt({ receipt_id })` to verify the dual HMAC-SHA256 + Ed25519 cryptographic receipt when audit proof is needed.
+
+## Failure boundaries
+
+- If a read fails safely, correct its inputs or select a better tool and try again.
+- If a write or infrastructure provisioning call times out or returns an unclear result, call `get_run({ run_id })` or `get_receipt({ receipt_id })` to verify the outcome.
+- Do not replay an uncertain hosted write through the CLI.
+- Do not request CLI installation when the hosted MCP surface can complete the task.

package/plugins/muxo/skills/setup/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: setup
+description: Guided onboarding skill for setting up the Muxo plugin in OpenAI ChatGPT and Codex. Helps users verify workspace authorization, connect external SaaS apps via OAuth handoff, provision cloud infrastructure, or install the local Muxo CLI.
+---
+
+# Muxo Onboarding & Setup
+
+Welcome to **Muxo** — the unified execution, cloud provisioning, contextual memory, and governance platform for OpenAI ChatGPT and Codex.
+
+## Step 1: Verify your Muxo connection
+
+1. If you are in **ChatGPT** or **Codex** with the hosted Muxo MCP server (`https://api.muxo.ai/mcp`) enabled:
+   - Call `get_profile` and `get_organization` to confirm your workspace ID, credit balance (`fundingMode: "muxo_funded"`), and active governance policy.
+2. If you are in a terminal environment and prefer the local CLI:
+   ```bash
+   npx -y @muxoai/cli@latest login --signup --name "my-agent"
+   muxo whoami
+   ```
+
+## Step 2: Connect your first SaaS app or run an Instant tool
+
+- **Zero-OAuth Instant Tools (`instant.*`)** work immediately with no setup:
+  - Web search (`instant.web.search`), page scraping (`instant.web.scrape`), multi-page crawling (`instant.web.crawl`), technical SEO audits (`instant.seo.audit`), Hacker News (`instant.hackernews.top_stories`), and DNS lookups (`instant.dns.lookup`).
+- **Connected Apps (`app.*`)** use automatic OAuth handoff:
+  - Plan any action (e.g., `app.github.create_issue` or `app.gmail.fetch_emails`) via `plan_action`.
+  - If the app is not connected yet, `plan_action` returns `authHandoff.redirectUrl`. Open that link to authorize, then call `wait_for_connection({ provider })` to resume.
+- **Cloud Infrastructure (`resource.*`)** provisions live databases and services via Stripe Projects:
+  - Provision Turso SQLite (`resource.turso.database`), Neon Postgres (`resource.neon.postgres`), Supabase (`resource.supabase.project`), or Upstash Redis (`resource.upstash.redis`) and pull encrypted `.env` credentials via `muxo env pull`.