@inneranimalmedia/agentsam-sdk 2.6.1 → 2.6.3

package/docs/plans/RECONCILIATION-2026-09-19.md

@@ -0,0 +1,178 @@
+# AgentSam SDK reconciliation — 2026-09-19
+
+**Status authority for the next agent.** Older notes (including
+`ASTRA-BRIEF-2026-09-18.md`) are backlog/reference only. Do not treat them as
+a live status report.
+
+Repo: `/Users/samprimeaux/agentsam-sdk`
+
+## Repository truth (verified this pass)
+
+```text
+git fetch --all --prune
+HEAD / origin/main: 88cb30daadf20b8ca22aad29dad826055cec6998
+branch: main...origin/main (clean, in sync)
+untracked (intentional): docs/plans/AGENTSAM-INTERACTIVE-UI-REQUIREMENTS.md
+```
+
+Latest merge: **PR #51** — local-first / project-owned SQLite runtime
+(`fix/model-picker-cursor-portable-catalog-20260918` → `88cb30d`).
+
+No `npm publish`. No Worker deployment for that batch.
+
+### Worktrees (run `git worktree list` before create/delete)
+
+| Path | Branch | Tip |
+| --- | --- | --- |
+| `/Users/samprimeaux/agentsam-sdk` | `main` | `88cb30d` |
+| `/Users/samprimeaux/agent-worktrees/studio-auth-ai-wiring` | `feat/studio-auth-and-ai-wiring` | `b8fffbb` |
+| `/Users/samprimeaux/agentsam-sdk-errors` | `feat/errors-v1-runtime-contract` | `f39b92b` (local; remote ahead elsewhere) |
+| `/Users/samprimeaux/agentsam-sdk-errors-integrate` | `integrate/errors-v1-main` | `0136a96` |
+| `/Users/samprimeaux/agentsam-sdk-tui-oauth` | `feat/cli-oauth-tui-productization` | `3a86138` (remote gone; tip is ancestor of main) |
+
+### Parallel remote branches to inspect before rebuilding equivalent work
+
+| Branch | Ahead of main | Behind main | Merged? |
+| --- | ---: | ---: | --- |
+| `origin/feat/studio-auth-and-ai-wiring` | 1 | 7 | No |
+| `origin/docs/cms-scaffolding-pattern-reference` | 4 | 9 | No |
+| `origin/fix/connections-binding-evidence` | 11 | 7 | No |
+| `origin/feat/errors-v1-runtime-contract` | 56 | 207 | No — do not casually rebase |
+| `origin/integrate/errors-v1-main` | 40 | 196 | No — do not casually rebase |
+| `origin/release/2.6.2-auth-closure` | 0 | 13 | **Yes** (ancestor of main) |
+
+Do **not** publish npm, deploy Workers, delete worktrees, or rewrite branches
+without explicit approval.
+
+---
+
+## A. MERGED / PROVEN
+
+1. **PR #51 storage / local runtime authority** at `88cb30d`
+   - Project-owned SQLite is the default local runtime authority
+     (`docs/architecture/STORAGE.md` + `test/integration/storage-architecture.test.mjs`).
+   - Durable Objects are **not** required for ordinary local session/runtime state;
+     reserved as optional future actor adapter.
+   - Existing app infrastructure (D1/Hyperdrive/R2/etc. when the project declares them) is respected.
+   - CLI sessions share the versioned project DB; project switches change storage authority.
+   - Raw prompts / credential fields excluded from persisted session state.
+   - Codex reported `npm run verify:release` green (335 Node tests) + PR CI + `git diff --check`.
+   - No npm publish / Worker deploy in that batch.
+
+2. **Storage Architecture Law** — implemented, not theoretical. Keep the commentary:
+   AgentSam may use Cloudflare/D1/Hyperdrive when the user/app chooses them; it must
+   not silently invent a distributed DO dependency for ordinary local runtime state.
+
+3. **`release/2.6.2-auth-closure`** — fully merged into main (tip `4ac7c08` is ancestor).
+
+4. **Legacy TUI OAuth branch** (`feat/cli-oauth-tui-productization` @ `3a86138`) —
+   ancestor of main; remote ref gone. Do not re-open as “unmerged OAuth work.”
+
+5. **`packages/work-graph`** — present on main (Astra extraction item closed).
+
+6. **`agentsam help all`** — **works on current main.** Routed via
+   `src/ui/cli/help.js` (`all` / `--all` → `renderAllHelp`). Live check:
+   `node src/cli.js help all` exits 0 and prints the full topic map.
+   Older “unimplemented / fuzzy→runtime” findings are superseded.
+
+7. **`workerApiTemplates` `dbKind` / Hyperdrive** — current main emits the selected
+   contract; `test/integration/scaffold-cloudflare.test.mjs` passes (d1 vs hyperdrive
+   wrangler/SQL/deps assertions). Treat prior “still wrong” notes as superseded unless
+   a new failing repro appears.
+
+8. **Local main == origin/main** at `88cb30d`.
+
+---
+
+## B. OPEN / CONFIRMED
+
+1. **`docs/plans/AGENTSAM-INTERACTIVE-UI-REQUIREMENTS.md`**
+   - Still **intentionally untracked**.
+   - PR #51 did **not** close interactive CLI/TUI work. Storage ≠ UI.
+
+2. **`terminal_remote` / remote exec host enrollment**
+   - **Not** the old CLI OAuth identity bug (that was fixed by paired IAM/SDK work).
+   - **Do not** assume PR #450 (or auth-closure) fixes this.
+   - Prior live evidence on the remote exec host:
+
+     ```text
+     control_plane_auth_mode: platform_bridge
+     control_plane_auth_error: platform_identity_missing
+
+     connection_key_set: false
+     platform_bridge_key_set: true
+     machine_key_set: true
+
+     account_id: null
+     connection_id: null
+     instance_id: null
+     ```
+
+   - Diagnosis: remote host **enrollment / pairing / provisioning** gap
+     (`connection_key_set=false` + null account/connection/instance), not token-shape OAuth.
+
+3. **Parallel work to inspect before rebuilding**
+   - `feat/studio-auth-and-ai-wiring` (1 commit ahead) — auth portal + AI fallback in local-studio.
+   - `docs/cms-scaffolding-pattern-reference` (4 commits) — CMS pattern reference docs.
+   - `fix/connections-binding-evidence` (11 commits) — Worker binding evidence / Wrangler tunnels.
+   - Errors branches are large and divergent; inspect only with an explicit errors mission.
+
+4. **Broader architectural backlog** (still legitimate, not tonight’s batch):
+   legacy runtime island, tool-authority duplication, command-dispatcher drift,
+   vocabulary/`workspace_id`, lineage object, `architecture/modules.yaml` — see Astra §2
+   as reference, not as current sprint status.
+
+5. **Scaffold-from-real-app** (`apps/client-cms-editor`, `apps/cad-creator` vs thin
+   `scaffold cms`) — still a design gap; do not rebuild blind.
+
+---
+
+## C. STALE / SUPERSEDED
+
+| Old claim | Why superseded |
+| --- | --- |
+| `main is now at 0795d92 (PR #50 merged)` | Main is `88cb30d` (PR #51). `0795d92` is PR #50 only. |
+| Storage architecture is “opinion / still deciding DO vs SQLite” | Implemented + release-verified on main. |
+| `release/2.6.2-auth-closure` still open / blocking | Merged into main. |
+| `platform_identity_missing` will be fixed by finishing auth-closure / CLI OAuth | Separate from remote host enrollment; OAuth path already closed. |
+| `agentsam help all` absent/broken in `src/cli.js` | Implemented in `src/ui/cli/help.js`; verified live. |
+| `packages/work-graph` still orphaned in agentsam-lab | Package exists on main. |
+| dbKind/Hyperdrive scaffold “still unresolved” (without new repro) | Tests pass on main for selected db contract. |
+| Treat Astra brief as ground truth over live git | This file is status authority; Astra is historical. |
+
+---
+
+## D. Proposed next implementation batch (narrow)
+
+**Do not redesign storage.** PR #51 closed that.
+
+### Recommended SDK batch — Interactive CLI presence (Cursor)
+
+Mission: implement the gaps in
+`docs/plans/AGENTSAM-INTERACTIVE-UI-REQUIREMENTS.md` against
+`src/ui/cli/activity.js`, `src/ui/cli/footer.js`, `src/commands/shell.js`.
+
+Constraints:
+
+- Explicitly **incorporate** that draft only when Sam says to track/commit it.
+- Until then: read it, implement against it, leave the file untracked unless told.
+- Before overlapping auth/studio UI: skim `feat/studio-auth-and-ai-wiring` (1 commit).
+- No npm publish, no Worker deploy, no worktree deletes, no branch rewrites.
+
+### Separate platform track — remote terminal enrollment (not “another OAuth fix”)
+
+Only when Sam prioritizes it:
+
+1. On the remote exec host, reconfirm the fingerprint above
+   (`connection_key_set=false`, null account/connection/instance).
+2. Fix pairing/provisioning so the host gets a real connection identity under
+   `platform_bridge`.
+3. Do **not** reopen CLI OAuth / PR #450 as the presumed fix.
+
+### Explicit non-goals for the next agent
+
+- Storage architecture redesign / DO defaulting
+- Broad “full-system audit”
+- Blind rebuild of CMS scaffold, studio auth, or connections binding without
+  inspecting the existing branches
+- `npm publish` / Worker deploy without approval

package/docs/plugins.md

@@ -0,0 +1,43 @@
+# AgentSam plugins
+
+AgentSam plugins are account-scoped installations recorded in the canonical
+`agentsam_plugins` row. A plugin owns user-facing connection state and exposes
+capabilities through `agentsam_tools`; it does not own raw OAuth tokens.
+
+The first reusable connection is `@agentsam-mcp`:
+
+- `provider_key`: `cloudflare`
+- OAuth authority: Cloudflare OAuth (`c0704bd7a7aab7216b362603e1985499`)
+- token storage: the consuming Worker’s `agentsam_cloudflare_connections`,
+  encrypted with that Worker’s `VAULT_MASTER_KEY`
+- tool keys: `agentsam-mcp.docs`, `agentsam-mcp.search`, and
+  `agentsam-mcp.execute`
+
+The sandbox package commonly called Code Mode is an execution primitive, not a
+connected plugin and not AgentSam’s reasoning loop. The execute tool uses
+`dispatch_target = 'codemode'` internally; users connect AgentSam MCP and
+never need to install an `@codemode` provider.
+
+`inneranimalmedia-cf-oauth` is a separate, host-owned confidential Cloudflare
+OAuth installation for Inner Animal Media Platform. It uses
+`https://inneranimalmedia.com/api/oauth/cloudflare/start` and its callback is
+`https://inneranimalmedia.com/api/oauth/cloudflare/callback`. It is not a
+replacement for Local Studio's PKCE `agentsam-mcp` installation and has no
+SDK-dispatched tool rows.
+
+Install the portable D1 contract and local plugin manifest in an application:
+
+```sh
+agentsam plugins install @agentsam-mcp
+```
+
+That writes `.agentsam/plugins.json` and copies
+`migrations/d1/0001_agentsam_plugin_runtime.sql`. The consuming application
+then materializes its account row with `installPlugin()` and records real
+probes in `agentsam_plugin_health_checks`. `agentsam_plugins.health_status` is
+only the materialized latest result.
+
+`@inneranimalmedia-mcp-server` is a separate IAM-authorized MCP service at
+`https://mcp.inneranimalmedia.com/mcp` with client
+`iam_mcp_inneranimalmedia`. It must not be conflated with the Cloudflare OAuth
+client used by `@agentsam-mcp`.

package/docs/tools/README.md

@@ -0,0 +1,57 @@
+# AgentSam Tools Reference
+
+Generated from the live `agentsam_tools` D1 registry (218 tools, `inneranimalmedia-business` database) on 2026-09-19. This is a **reference index**, not source of truth — the registry itself is authoritative; re-generate this if the registry drifts significantly.
+
+**Why this exists:** before building a new tool, writing a new scaffold capability, or reaching for a raw shell command to do something the platform already has a tool for, check here first. The whole point is to stop re-deriving things that already exist — this was the exact failure mode a prior audit of `agentsam-sdk` flagged repeatedly.
+
+**Stats:** 218 total · 206 active · 12 inactive · 31 high-risk · 153 never invoked (in this registry's tracked history).
+
+## Find a tool by domain
+
+| Domain | Tools | What's here |
+|---|---|---|
+| [Agent & Orchestration](./agent-and-orchestration.md) | 17 | Spawning subagents, running workflows, planning, multitask fan-out, and repo intelligence for an agent's own reasoning. |
+| [Browser & Research](./browser-and-research.md) | 20 | Automated browser control (Playwright), screenshots, script evaluation, quick-actions (scrape/crawl/PDF/markdown/links/JSON extract), AutoRAG search, and general web search/fetch. |
+| [Cloudflare Platform](./cloudflare-platform.md) | 9 | Account-level Cloudflare operations: listing Workers/D1/KV/R2, fetching Worker code, and searching Cloudflare docs. NOT data operations inside those resources — see Database & Storage for that. |
+| [CMS](./cms.md) | 17 | The real CMS execution pipeline — page/block/section create+update, publish, site-shell save, and the CMS pipeline bootstrap/extract/inject/prototype steps. This is the canonical content system; do not reinvent a thinner one in a scaffold. |
+| [Communications](./communications.md) | 21 | Email (agentsam_send_email and the full official Gmail MCP surface), iMessage (send/approval), and app push notifications. |
+| [Database & Storage](./database-and-storage.md) | 15 | D1 (query/write/delete), Supabase (query/vector/write), Hyperdrive, R2 (get/put/list/delete), KV, Vectorize, and Cloudflare Images. |
+| [Design & Media](./design-and-media.md) | 35 | Excalidraw canvas, CAD generation/jobs, Design Studio blueprints/scenes/assets, image generation/upload, video generation/embed, and the full Meshy 3D pipeline (text-to-3D, image-to-3D, rig, retexture, remesh, UV unwrap). |
+| [Filesystem & Code](./filesystem-and-code.md) | 20 | Reading/writing/searching files, AST-level codebase retrieval, code index builds, Merkle diffing, and knowledge ingestion. |
+| [GitHub](./github.md) | 36 | Every GitHub read (repos, branches, commits, PRs, issues, workflow runs) and write (commit, patch, branch, PR, comment) operation. |
+| [Integrations & Misc](./integrations-and-misc.md) | 5 | Google Drive, Resend (inactive), and raw HTTP fetch (inactive). |
+| [Memory](./memory.md) | 4 | Agent Sam's own memory commit/search/save/manager surface — semantic memory, not to be confused with this assistant's own memory system. |
+| [Terminal & Execution](./terminal-and-execution.md) | 6 | Running shell/Python/Node commands — on the user's own Mac, the always-on cloud desk, or an isolated sandbox — plus container batch exec and Code Mode. |
+| [Tickets & Platform](./tickets-and-platform.md) | 13 | The ticket lifecycle (create/get/list/set-status/add-note), plus platform-level admin: MCP audit log, ship-check, checkout-root pin/get/clear, ping. |
+
+## Quick lookup — common needs → domain
+
+- **Run a shell command** (local Mac / cloud desk / sandbox) → [Terminal & Execution](./terminal-and-execution.md)
+- **Read/write/search files, retrieve code by AST** → [Filesystem & Code](./filesystem-and-code.md)
+- **Query or write D1/Supabase/R2/KV/Vectorize** → [Database & Storage](./database-and-storage.md)
+- **List/inspect Workers, KV namespaces, R2 buckets at the account level** → [Cloudflare Platform](./cloudflare-platform.md)
+- **Create/edit/publish a page, block, or section** → [CMS](./cms.md) — do not reinvent this with a scaffold
+- **GitHub read or write of any kind** → [GitHub](./github.md)
+- **Browser automation, scraping, web search** → [Browser & Research](./browser-and-research.md)
+- **Generate an image/video/3D asset, or use Design Studio/CAD** → [Design & Media](./design-and-media.md)
+- **Send email, iMessage, or a push notification** → [Communications](./communications.md)
+- **Spawn a subagent, run a workflow, build a plan** → [Agent & Orchestration](./agent-and-orchestration.md)
+- **Semantic memory commit/search** → [Memory](./memory.md)
+- **Track a ticket, check ship status, audit MCP calls** → [Tickets & Platform](./tickets-and-platform.md)
+
+## Before you build a new tool: check for collisions
+
+5 `handler_key` values are shared by more than one distinct `tool_name` in the registry today. A shared handler_key is the strongest signal that a tool already does what you're about to build — check these before adding anything new:
+
+- `handler_key: codebase_ast` → `agentsam_codebase_retrieve`, `agentsam_knowledge_ingest_segment`
+- `handler_key: github_create_pr` → `agentsam_github_pr`, `agentsam_github_pr_create`
+- `handler_key: github_search_code` → `agentsam_github_grep`, `agentsam_github_search`
+- `handler_key: memory` → `agentsam_memory_commit`, `agentsam_memory_manager`, `agentsam_memory_save`, `agentsam_memory_search`
+- `handler_key: notify` → `agentsam_notify`, `agentsam_send_email`
+
+## Legend
+
+- **inactive** — `is_active = 0` in the registry; do not suggest these without checking why they're off first.
+- **risk: high** — `requires_approval`-tier or destructive; confirm before calling.
+- **★ heavily used** — ≥100 recorded calls; these are the proven, load-bearing tools for their domain.
+- **never used** — 0 recorded calls. Not necessarily dead — could be newly registered — but worth a second look before assuming it works as documented.

package/docs/tools/agent-and-orchestration.md

@@ -0,0 +1,49 @@
+# Agent & Orchestration
+
+Spawning subagents, running workflows, planning, multitask fan-out, and repo intelligence for an agent's own reasoning.
+
+**17 tools** in this domain.
+
+## `agent` (1)
+
+- **`agentsam_run_agent`** (Run Agent Workflow) — Execute an agentsam workflow by workflow_key (async graph runner). Requires approval in registry. _risk: high, never used_
+
+## `agent.admin` (1)
+
+- **`agentsam_tools_sync_projection`** (Sync Tool Search Projection) — Operator-only sync of canonical D1 agentsam_tools into the rebuildable Supabase semantic tool projection. D1 remains tools/list and execution authority. _risk: high, never used_
+
+## `agent.discovery` (1)
+
+- **`agentsam_search_tools`** (Search tools) — Discover Agent Sam catalog tools by capability, intent, category, or name. Returns ranked tool_key matches from agentsam_tools. Prefer exact tool_key when known. _never used_
+
+## `agent.execute` (5)
+
+- **`agentsam_create_subagent`** (Create Subagent) — Create a custom subagent profile row in agentsam_subagent_profile for this user and workspace.
+- **`agentsam_get_agent`** (Get Agent) — Get one subagent profile by slug from agentsam_subagent_profile. _never used_
+- **`agentsam_list_agents`** (List Agents) — List subagent profiles from agentsam_subagent_profile for this user and workspace (includes platform-global templates). _never used_
+- **`agentsam_plan`** (Create Plan) — Create or read workspace plans. Call with {} to create using the default goal, or read: true to fetch the active plan. _never used_
+- **`agentsam_spawn_profile`** (Spawn Subagent) — Spawn a child agent profile by slug. Creates agentsam_spawn_session row. Enforces max_spawn_depth. _never used_
+
+## `agent.repo` (1)
+
+- **`agentsam_repo_intelligence`** (Repo Intelligence) — Deterministic Git historian for architecture triage. mode=overview ranks hotspots/stability/coupling; add path_prefix and/or domain to inspect a subtree or classified domain instead of the whole repo; mode=focus + path is a one-file autopsy. Target another bound checkout with github_repo / workspace_slug / workspace_id (never a filesystem path). Optional since_days (7-365) and top_k (5-40). Not for exact symbol lookup.
+
+## `platform.orchestration` (4)
+
+- **`agentsam_multitask_cancel`** (Multitask Cancel) — Force-stop a multitask fanout by spawn_job_id. Sets cancel_requested=1 AND status=cancelled on parent + all child agent runs, closes agentsam_spawn_job. Use when soft cancel left lanes running/billing. Poll agentsam_multitask_status after. _risk: high, never used_
+- **`agentsam_multitask_spawn`** (Multitask Spawn) — Spawn 1..N child agent lanes (Cursor Task-style). Parent chat orchestrates; this tool only creates the fanout. Returns spawn_job_id + child_run_ids immediately; poll agentsam_multitask_status. Each lane REQUIRES role_slug (active agentsam_subagent_profile.slug) — no default remap. Optional timeout_seconds / lane_timeout_seconds. Requires allow_subagent_spawn; child loops run when allow_fanout_execution=1. _risk: high, never used_
+- **`agentsam_multitask_status`** (Multitask Status) — Poll multitask fanout by spawn_job_id. Returns lanes with status (queued|running|cancelling|cancelled|done|failed|awaiting_approval), cancel_requested, cost_usd, open_lane_count, ledger_diverged. If open_lane_count>0 use agentsam_multitask_cancel. _never used_
+- **`agentsam_spawn_tree`** (Inspect Spawn Tree) — READ-ONLY inspect of parent/child agent runs sharing a chain_root_id. Provide run_id or conversation_id. Does not spawn. Use agentsam_multitask_spawn to create lanes, agentsam_multitask_status to poll. _never used_
+
+## `platform.staging` (1)
+
+- **`agentsam_stage_file`** (Stage File) — Provisionally stage a file to R2 (conversation-scoped). Destination-agnostic — does NOT write GitHub tip, Local FSA, or sandbox root. Prefer this for new HTML/CSS/JS/landing pages and iterative drafts. Re-call with the same path to update. Returns staged_ref; ship via a separate tool later. Args: path (relative), content (required), mime (optional). _never used_
+
+## `workflow.context` (1)
+
+- **`workflow_context_resolve`** (Workflow Context Resolve) — Resolve only the conversation, repository, and artifact references explicitly supplied to a reusable workflow. Account id is the ownership authority; unsupported source kinds remain reference-only. _never used_
+
+## `workflow.execute` (2)
+
+- **`agentsam_workflow_status`** (Workflow Status) — Returns recent workflow run statuses for this workspace. _**inactive**, never used_
+- **`agentsam_workflow_trigger`** (Workflow Trigger) — Start a registered workflow for this workspace (POST /api/agent/workflow/start). _never used_

package/docs/tools/browser-and-research.md

@@ -0,0 +1,46 @@
+# Browser & Research
+
+Automated browser control (Playwright), screenshots, script evaluation, quick-actions (scrape/crawl/PDF/markdown/links/JSON extract), AutoRAG search, and general web search/fetch.
+
+**20 tools** in this domain.
+
+## `browser.automation` (1)
+
+- **`agentsam_playwright`** (Playwright Browser) — Full Playwright browser automation. operation: screenshot (full-page visual capture + job tracking), navigate (go to URL), scrape (get page text/DOM), capture (screenshot of current session state). In-app only — never routes through MCP server. Trusted origin enforced.
+
+## `browser.capture` (2)
+
+- **`browser_screenshot`** (Browser Screenshot) — Capture viewport screenshot from the live browser session (requires bsess_* lease). _never used_
+- **`cdt_take_screenshot`** (CDT Screenshot) — DevTools-backed screenshot including JS-rendered content. _**inactive**, never used_
+
+## `browser.debug.script` (2)
+
+- **`browser_evaluate_script`** (Browser Evaluate Script) — Evaluate JavaScript in the live browser session page (requires bsess_* lease). _never used_
+- **`cdt_evaluate_script`** (CDT Evaluate Script) — Run JavaScript in page context for element picker injection and approved debugging. _**inactive**, never used_
+
+## `browser.inspect` (3)
+
+- **`agentsam_excalidraw`** (Excalidraw Canvas) — Open Excalidraw canvas session for diagrams, wireframes, or visual planning. Available to all workspace users. _never used_
+- **`browser_content`** (Browser Content) — Get DOM content of the current browser page. Returns HTML/text snapshot.
+- **`browser_navigate`** (Browser Navigate) — Navigate browser to a URL via CDT. Returns page load status.
+
+## `browser.quickaction` (9)
+
+- **`browser_run_content`** (Browser Run Content) — Fetch fully rendered HTML after JavaScript execution. _never used_
+- **`browser_run_crawl`** (Browser Run Crawl) — Crawl a site from a starting URL with configurable depth and page limit. _never used_
+- **`browser_run_json`** (Browser Run JSON Extract) — Extract structured JSON from a webpage using a natural language prompt and schema. _never used_
+- **`browser_run_links`** (Browser Run Links) — Extract all links from a web page. _never used_
+- **`browser_run_markdown`** (Browser Run Markdown) — Fetch any URL and return clean markdown. Faster than browser_navigate for content extraction. _never used_
+- **`browser_run_pdf`** (Browser Run PDF) — Render a webpage or custom HTML as a PDF. Returns base64-encoded PDF bytes. _never used_
+- **`browser_run_scrape`** (Browser Run Scrape) — Extract structured data from specific CSS selectors on a webpage. _never used_
+- **`browser_run_screenshot`** (Browser Run Screenshot) — Stateless screenshot of any URL. Returns JPEG as base64. _never used_
+- **`browser_run_snapshot`** (Browser Run Snapshot) — Capture HTML, screenshot, markdown, and accessibility tree in one request. _never used_
+
+## `research.web` (2)
+
+- **`search_web`** (Web Search) — Search the public web through Tavily for current facts, releases, pricing, news, and official documentation. Use query for discovery; use web_fetch only when a URL is already known.
+- **`web_fetch`** (Web Fetch) — Fetch a known public URL and return text (no browser render). Use for docs pages, raw GitHub, API references.
+
+## `search.autorag` (1)
+
+- **`agentsam_autorag`** (AutoRAG Search) — Semantic search across platform docs and knowledge base via AutoRAG and pgvector. IAM platform knowledge only.

package/docs/tools/cloudflare-platform.md

@@ -0,0 +1,32 @@
+# Cloudflare Platform
+
+Account-level Cloudflare operations: listing Workers/D1/KV/R2, fetching Worker code, and searching Cloudflare docs. NOT data operations inside those resources — see Database & Storage for that.
+
+**9 tools** in this domain.
+
+## `cloudflare` (1)
+
+- **`cloudflare_whoami`** (Cloudflare Whoami) — Redacted Cloudflare credential diagnostics for the authenticated MCP actor. Returns credential_source, account ids/names, token verify status — never secrets. _never used_
+
+## `cloudflare.d1` (1)
+
+- **`agentsam_cf_d1_list`** (Cloudflare D1 List) — List D1 databases in your connected Cloudflare account. Returns name + database_id (UUID) for use with agentsam_d1_query.
+
+## `cloudflare.docs` (2)
+
+- **`migrate_pages_to_workers_guide`** (Pages → Workers Migration Guide) — Fetch Cloudflare guidance for migrating Pages projects to Workers. Use when planning framework or deploy path changes. _never used_
+- **`search_cloudflare_documentation`** (Search Cloudflare Documentation) — Search current Cloudflare product documentation (Workers, D1, R2, Workers AI, Pages, Zero Trust, etc.). Prefer over pretraining for limits, APIs, compatibility dates, and pricing. _never used_
+
+## `cloudflare.kv` (1)
+
+- **`agentsam_cf_kv_list`** (Cloudflare KV Namespaces) — List KV namespaces in your connected Cloudflare account via Bindings MCP. Use agentsam_kv_manage for key read/write. _never used_
+
+## `cloudflare.r2` (1)
+
+- **`agentsam_cf_r2_buckets`** (Cloudflare R2 Buckets) — List R2 buckets in the Cloudflare account via Bindings MCP r2_buckets_list. No required args. Optional cursor, direction, name_contains, per_page, start_after. Object listing is agentsam_r2_list. _never used_
+
+## `cloudflare.workers` (3)
+
+- **`agentsam_cf_worker_code`** (Cloudflare Worker Code) — Fetch Worker script source code via Bindings MCP. _never used_
+- **`agentsam_cf_worker_get`** (Cloudflare Worker Get) — READ-ONLY discovery: get one Worker script metadata via Bindings MCP (remote_tool=workers_get_worker). Not a deploy tool — use agentsam_worker_deploy to ship. _never used_
+- **`agentsam_cf_workers_list`** (Cloudflare Workers List) — READ-ONLY discovery: list Worker scripts in the connected Cloudflare account via Bindings MCP (remote_tool=workers_list). Not a deploy tool — use agentsam_worker_deploy to ship.

package/docs/tools/cms.md

@@ -0,0 +1,25 @@
+# CMS
+
+The real CMS execution pipeline — page/block/section create+update, publish, site-shell save, and the CMS pipeline bootstrap/extract/inject/prototype steps. This is the canonical content system; do not reinvent a thinner one in a scaffold.
+
+**17 tools** in this domain.
+
+## `cms.execute` (17)
+
+- **`agentsam_cms_block_create`** (CMS Block Create) — Create one block/component under a section. Does not publish. _never used_
+- **`agentsam_cms_block_update`** (CMS Block Update) — Update one block/component. Does not publish. _never used_
+- **`agentsam_cms_page_create`** (CMS Page Create) — Create one CMS page (draft). Does not publish. Use agentsam_cms_publish separately. _never used_
+- **`agentsam_cms_publish`** (CMS Publish) — Complete publish: draft R2 → published, D1 status=published, cache bust. Always follow with agentsam_cms_verify_live. _never used_
+- **`agentsam_cms_publish_site_shell`** (CMS Publish Site Shell) — Copy site shell draft R2 → published (src/components/iam-header.html or iam-footer.html). Run after agentsam_cms_save_site_shell. _never used_
+- **`agentsam_cms_read`** (CMS Read) — Read CMS page metadata, sections, draft/published HTML excerpts, and preview_urls. Start every revision loop here. _never used_
+- **`agentsam_cms_save_injected`** (CMS Save Injected Section) — Persist HTML fragment or full document as R2-backed cms_page_sections row + rebuild draft.html. _never used_
+- **`agentsam_cms_save_page_html`** (CMS Save Page HTML) — Write full-page HTML to R2 draft.html (preserves published status). Use for remasters and full-page rewrites. _never used_
+- **`agentsam_cms_save_site_shell`** (CMS Save Site Shell) — Write marketing chrome HTML to R2 draft keys (iam-header / iam-footer). Same as CMS editor Site Shell panel save. _never used_
+- **`agentsam_cms_section_create`** (CMS Section Create) — Create one section on an existing page. Does not publish. _never used_
+- **`agentsam_cms_section_update`** (CMS Section Update) — Update one section via domain service. Prefer over inventing page-create via agentsam_cms_write. Does not publish. _never used_
+- **`agentsam_cms_verify_live`** (CMS Verify Live URL) — Fetch live storefront URL and confirm 200 + real content (not Clean canvas / 404). Required to complete the PrimeTech loop. _never used_
+- **`agentsam_cms_write`** (CMS Write) — Update cms_page_sections.section_data, stage KV draft, write R2 draft.html. Then publish + verify. _never used_
+- **`cms_pipeline_bootstrap`** (CMS Pipeline Bootstrap) — Load CMS pages + sections tree from D1 via Python pipeline worker. _never used_
+- **`cms_pipeline_extract`** (CMS Pipeline Extract) — Parse HTML for data-cms-section slots and default D1 section stubs (Python BeautifulSoup). _never used_
+- **`cms_pipeline_inject`** (CMS Pipeline Inject) — Splice section HTML into a page shell (preview only — persist via save-injected / cms_write). _never used_
+- **`cms_pipeline_prototype`** (CMS Pipeline Prototype) — Workers AI section/HTML prototype via iam-cms-pipeline (read-only proposal; apply with agentsam_cms_write). _never used_

package/docs/tools/communications.md

@@ -0,0 +1,41 @@
+# Communications
+
+Email (agentsam_send_email and the full official Gmail MCP surface), iMessage (send/approval), and app push notifications.
+
+**21 tools** in this domain.
+
+## `comms.email` (1)
+
+- **`agentsam_send_email`** (Send Email) — Send transactional email via Resend. From address resolves from workspace_settings. Handles single send or batch loop. Requires approval. _never used_
+
+## `comms.imessage` (3)
+
+- **`agentsam_imessage_approval_status`** (iMessage approval status) — Read an iMessage approval row by token or id (pending / approved / denied / expired) plus linked agentsam_approval_queue status when present. _never used_
+- **`agentsam_imessage_request_approval`** (iMessage request approval) — Text the operator a yes/no approval over iMessage and return a token. Reply `approve <token>` or `no <token>` on the Mac. Also writes agentsam_approval_queue so an in-app card stays in sync. Status via agentsam_imessage_approval_status.
+- **`agentsam_imessage_send`** (iMessage send) — Queue an iMessage to the operator. The Mac Messages.app daemon sends it; this Worker never talks to BlueBubbles. Optional `to` is an iMessage handle (phone or email). If omitted, uses the daemon-registered self handle. _never used_
+
+## `comms.push` (1)
+
+- **`agentsam_notify`** (App Push Notify) — Send an in-app + PWA web push notification to the authenticated user. Not email — use agentsam_send_email for Resend. _never used_
+
+## `gmail` (4)
+
+- **`gmail_get_message`** (Gmail Get Message) — Fetch a single Gmail message by id with full body text (user OAuth). Use after gmail_list_inbox when triaging — distinguishes setup-in-progress vs confirmed. _never used_
+- **`gmail_list_inbox`** (Gmail List Inbox) — List recent inbox messages for the signed-in user Gmail account(s). Requires google_gmail OAuth.
+- **`gmail_modify_message`** (Gmail Modify Message) — Modify Gmail labels (read/star/archive/trash) for a message id on the user connected account. _never used_
+- **`gmail_send`** (Gmail Send) — Send email via the user connected Gmail account (google_gmail OAuth). _risk: high, never used_
+
+## `gmail.official` (12)
+
+- **`agentsam_gmail_mcp_apply_sensitive_message_label`** (Gmail Apply Sensitive Message Label) — Adds a sensitive label (Trash or Spam) to a specific message. Use to trash or mark a message as spam; find the message ID via search_threads or get_thread first. _risk: high, never used_
+- **`agentsam_gmail_mcp_apply_sensitive_thread_label`** (Gmail Apply Sensitive Thread Label) — Adds a sensitive label (Trash or Spam) to an entire thread, affecting all current and future messages in it. _risk: high, never used_
+- **`agentsam_gmail_mcp_create_draft`** (Gmail Create Draft) — Creates a new draft email. Takes recipients, subject, body; returns the draft ID. Pass replyToMessageId to reply to an existing message. Attachments not supported yet. _risk: high, never used_
+- **`agentsam_gmail_mcp_create_label`** (Gmail Create Label) — Creates a new label, supports nested labels via forward slash (e.g. `Projects/Alpha/Sprint-1`); parent labels auto-created if missing. _risk: high, never used_
+- **`agentsam_gmail_mcp_get_thread`** (Gmail Get Thread) — Retrieves a thread and its messages. `message_format` controls detail: FULL_CONTENT (default), MINIMAL (subject+snippet only), or METADATA_ONLY. _never used_
+- **`agentsam_gmail_mcp_label_message`** (Gmail Label Message) — Adds one or more labels to a message. Find message ID via search_threads/get_thread; find label ID via list_labels. _never used_
+- **`agentsam_gmail_mcp_label_thread`** (Gmail Label Thread) — Adds labels to an entire thread (current + future messages). Same ID-discovery pattern as label_message. _never used_
+- **`agentsam_gmail_mcp_list_drafts`** (Gmail List Drafts) — Lists draft emails, filterable by query, paginated via page_token. `view` controls response detail (DRAFT_VIEW_METADATA_ONLY, etc). _never used_
+- **`agentsam_gmail_mcp_list_labels`** (Gmail List Labels) — Lists user-defined labels (system labels like INBOX/TRASH/SPAM/STARRED use well-known IDs instead). Call before label_thread/label_message. _never used_
+- **`agentsam_gmail_mcp_search_threads`** (Gmail Search Threads) — Lists threads matching a query string, paginated. `view` controls detail level in returned messages (THREAD_VIEW_MINIMAL default). _never used_
+- **`agentsam_gmail_mcp_unlabel_message`** (Gmail Unlabel Message) — Removes one or more labels from a message. _never used_
+- **`agentsam_gmail_mcp_unlabel_thread`** (Gmail Unlabel Thread) — Removes labels from an entire thread. _never used_

package/docs/tools/database-and-storage.md

@@ -0,0 +1,62 @@
+# Database & Storage
+
+D1 (query/write/delete), Supabase (query/vector/write), Hyperdrive, R2 (get/put/list/delete), KV, Vectorize, and Cloudflare Images.
+
+**15 tools** in this domain.
+
+## `database.d1.delete` (1)
+
+- **`agentsam_d1_delete`** (D1 Delete) — Run DELETE (or other mutate) SQL on a D1 database in your Cloudflare account. Credentials resolve from your connected Cloudflare account. _risk: high, never used_
+
+## `database.d1.query` (1)
+
+- **`agentsam_d1_query`** (D1 Query) — Query a D1 database in your Cloudflare account. Pass database_id (UUID) + sql. If database_id is omitted, the session workspace pin is used. List UUIDs with agentsam_cf_d1_list. _★ heavily used (654 calls)_
+
+## `database.d1.write` (1)
+
+- **`agentsam_d1_write`** (D1 Write) — Run mutating SQL on a D1 database in your Cloudflare account.
+
+## `database.hyperdrive` (1)
+
+- **`hyperdrive_schema_inspect`** (Hyperdrive Schema Inspect) — List agentsam tables and columns via Hyperdrive (read-only). _**inactive**, never used_
+
+## `database.supabase.query` (1)
+
+- **`agentsam_supabase_query`** (Supabase Query) — Read-only SQL on an explicitly selected Supabase/Postgres resource. Supports PostgreSQL $1 parameters.
+
+## `database.supabase.vector` (1)
+
+- **`agentsam_supabase_vector`** (Supabase Vector) — pgvector similarity search. Platform Hyperdrive for operators; optional project for user BYOK/customer plane. _never used_
+
+## `database.supabase.write` (1)
+
+- **`agentsam_supabase_write`** (Supabase Write) — Mutating SQL on an authorized Supabase/Postgres resource. Pass sql with RETURNING, or operation=insert|update|delete with table/row/set/where. _never used_
+
+## `storage.images` (2)
+
+- **`agentsam_cf_image_upload`** (CF Image Upload (base64)) — Upload a binary image to Cloudflare Images via base64. Writes to CF Images, R2 (S3 API), and D1 images registry. _never used_
+- **`agentsam_cf_images_upload`** (CF Images Upload) — Upload an image to Cloudflare Images from a public HTTPS URL. Returns delivery URL with transform variants. Base64 not supported — image_url only. _never used_
+
+## `storage.kv.manage` (1)
+
+- **`agentsam_kv_manage`** (KV Manage) — List/read/write/delete Workers KV keys in the caller Cloudflare account. Namespace create/delete: use CF Bindings MCP tools separately. Never hardcode namespace or workspace ids. _never used_
+
+## `storage.r2.delete` (1)
+
+- **`agentsam_r2_delete`** (R2 Delete) — Delete an object from any R2 bucket. Irreversible. _risk: high, never used_
+
+## `storage.r2.get` (1)
+
+- **`agentsam_r2_get`** (R2 Get) — Read or fetch an object from any R2 bucket.
+
+## `storage.r2.list` (1)
+
+- **`agentsam_r2_list`** (R2 List Objects) — List objects in one R2 bucket (bucket required). For account-wide bucket inventory use agentsam_cf_r2_buckets instead.
+
+## `storage.r2.put` (1)
+
+- **`agentsam_r2_put`** (R2 Put) — Write an object to an R2 bucket the caller can access. Sets IAM customMetadata. Binary: prefer attachment_id or content_base64; content is UTF-8 text. _never used_
+
+## `storage.vectorize` (1)
+
+- **`agentsam_cf_vectorize`** (Cloudflare Vectorize) — Query, upsert, or delete vectors in a Vectorize index. Pass index_name and operation. _never used_

package/docs/tools/design-and-media.md

@@ -0,0 +1,64 @@
+# Design & Media
+
+Excalidraw canvas, CAD generation/jobs, Design Studio blueprints/scenes/assets, image generation/upload, video generation/embed, and the full Meshy 3D pipeline (text-to-3D, image-to-3D, rig, retexture, remesh, UV unwrap).
+
+**35 tools** in this domain.
+
+## `design` (3)
+
+- **`excalidraw_export`** (Excalidraw export) — Export the active Draw/Excalidraw canvas as PNG+SVG to R2. Prefer calling without canvasData so the open canvas exports client-side. _never used_
+- **`excalidraw_load_library`** (Excalidraw load library) — Load an Excalidraw shape library onto /dashboard/draw by slug (e.g. lofi-wireframe, web-kit, universal-ui-kit). _never used_
+- **`excalidraw_plan_map_create`** (Excalidraw plan map) — Generate an Excalidraw plan map from agentsam_plans + plan tasks. Use for multi-task plans — not general freeform drawing (prefer illustration_create). _never used_
+
+## `design.execute` (2)
+
+- **`cad_generate`** (Generate CAD Script Job) — Create an OpenSCAD, FreeCAD, or Blender CAD job from a natural-language prompt, then auto-dispatch execution. Prefer this over pasting source code. Poll cad_job_status.
+- **`cad_job_cancel`** (Cancel CAD Job) — Cancel an authenticated user-owned CAD job. Provider cancellation attempted when supported. _risk: high, never used_
+
+## `design.read` (5)
+
+- **`cad_job_status`** (CAD Job Status) — Get one scoped CAD job or list recent CAD jobs for the authenticated user and workspace.
+- **`designstudio_asset_list`** (List Design Studio Assets) — List shared 3D Studio assets and user-owned assets available in the active workspace. _never used_
+- **`designstudio_blueprint_get`** (Get Design Studio Blueprint) — Fetch one Design Studio blueprint by id, including sketch_json and preview URLs. _never used_
+- **`designstudio_blueprint_list`** (List Design Studio Blueprints) — List Design Studio design blueprints for the active workspace. _never used_
+- **`designstudio_scene_list`** (List Design Studio Scenes) — List named scene snapshots owned by the authenticated user in the active workspace. _never used_
+
+## `design.write` (2)
+
+- **`designstudio_blueprint_create`** (Create Design Studio Blueprint) — Create a Design Studio blueprint (draft intent). Defaults set_active=true. Do not generate CAD unless the user asks. _never used_
+- **`designstudio_blueprint_update`** (Update Design Studio Blueprint) — Update blueprint fields (title, status, preview URLs, sketch_json) or set_active to select it in Studio. _never used_
+
+## `media` (1)
+
+- **`illustration_create`** (Illustration Create (iam.illustration.v1)) — Single SSOT envelope for sketches (Excalidraw /draw) vs CAD blueprints (Design Studio). Pass iam.illustration.v1 with intent, fidelity, engine=auto, title, brief, constraints, payload.
+
+## `media.execute` (19)
+
+- **`agentsam_video_embed`** (Video Embed (Gemini media lane)) — Index a media_assets row into AGENTSAM_VECTORIZE_MEDIA via gemini-embedding-2 @1536. _never used_
+- **`imgx_edit_image`** (Image Edit) — Edit or modify an existing image. Only call when user explicitly asks to edit/modify/alter an image file. _**inactive**, never used_
+- **`imgx_generate_image`** (Image Generate) — Generate 1 image, or up to 4 in ONE call via variations:N (concurrent, not sequential — always use variations for multi-image asks instead of repeated calls). provider=openai|google|workers_ai.
+- **`imgx_list_providers`** (Image Providers) — List available image generation providers and their current status. _**inactive**, never used_
+- **`meshy_animate`** (Meshy Animate) — Apply a custom Meshy animation clip to a completed rig task. _never used_
+- **`meshy_convert`** (Meshy Convert) — Convert a Meshy model to requested 3D formats. _never used_
+- **`meshy_image_to_3d`** (Meshy Image to 3D) — Create a textured Meshy model from one image. _never used_
+- **`meshy_multi_image_to_3d`** (Meshy Multi-Image to 3D) — Create a Meshy model from 1–4 views of the same object. _never used_
+- **`meshy_remesh`** (Meshy Remesh) — Change topology or polygon count for an owned Meshy task or model URL. _never used_
+- **`meshy_resize`** (Meshy Resize) — Set real-world dimensions for a Meshy model. _never used_
+- **`meshy_retexture`** (Meshy Retexture) — Apply a text- or image-guided texture to an existing Meshy model. _never used_
+- **`meshy_rig`** (Meshy Rig) — Rig a humanoid Meshy model. Source should use a T-pose, no more than 300,000 faces. _never used_
+- **`meshy_text_to_3d`** (Meshy Text to 3D) — Create a Meshy Text-to-3D preview task. Spends credits; texture the preview with meshy_text_to_3d_refine. _never used_
+- **`meshy_text_to_3d_refine`** (Meshy Text to 3D Refine) — Texture a completed Meshy Text-to-3D preview. Requires the preview task id, spends credits. _never used_
+- **`meshy_uv_unwrap`** (Meshy UV Unwrap) — Generate a UV layout for an existing Meshy model. _never used_
+- **`moviemode_export`** (MovieMode Export) — Export a MovieMode video project to final output format. _never used_
+- **`moviemode_render`** (MovieMode Render) — Queue a Remotion render job for a MovieMode project timeline. _never used_
+- **`social_card_generate`** (Social Card) — Generate a social share card image from template + metadata. _**inactive**, never used_
+- **`veo_generate_video`** (Video Generate) — Generate video with Vertex Veo (async). Default destination=local; destination=stream saves to Hosted Videos when connected.
+
+## `media.manage` (1)
+
+- **`meshy_cancel_task`** (Delete Meshy Task) — Permanently delete an authenticated user-owned Meshy task and mark its IAM CAD job canceled. DELETE, not a reversible cancel. _risk: high, never used_
+
+## `media.status` (2)
+
+- **`meshy_get_task_status`** (Meshy Task Status) — Read IAM-owned Meshy job status by CAD job id. _never used_
+- **`meshy_list_tasks`** (List Meshy Tasks) — List recent IAM-owned Meshy jobs for the authenticated user and workspace. _never used_