@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

package/docs/plans/TOMORROW-EXTENSIVE-TODO-2026-09-26.md

@@ -0,0 +1,221 @@
+# Tomorrow — comprehensive work list (2026-09-26 evening snapshot)
+
+**Repo:** `/Users/samprimeaux/agentsam-sdk` · `main`  
+**Also read:** [`TOMORROW-MACHINE-FIRST-BRIEFING.md`](./TOMORROW-MACHINE-FIRST-BRIEFING.md) · [`MACHINE_INTELLIGENCE.md`](../MACHINE_INTELLIGENCE.md)  
+**Settings merge:** Settings v2 (`packages/agentsam-settings` + Local Studio host) is **on `main`** as of this evening. Fixture-backed localhost UI — **no D1/vault migration yet**.
+
+**Preserve:** do not reset/stash/regenerate unrelated WIP. Inspect `git status` before editing. Other open branch (not merged tonight): `feat/project-control-workbench-20260925` @ `agentsam-sdk-project-control` worktree.
+
+---
+
+## A. Visual signoff — Settings v2 (do first if UI not yet approved)
+
+- [ ] Cold-load Local Studio Settings on localhost: `/settings/general` and all 13 units  
+- [ ] Nested views: `agents?view=models`, `customize?view=mcps`, `keys?view={credentials,secrets,sessions,audit}`  
+- [ ] Fixture modes: `?fixture=first-run|degraded|security-findings`  
+- [ ] Confirm package boundary feels right: `packages/agentsam-settings` owns UI/contracts; Local Studio only composes host  
+- [ ] **Do not** apply D1 migrations or rewrite vault from this pass until signoff  
+
+**Package layout already on main:**
+
+```text
+packages/agentsam-settings/   contracts · fixtures · frontend
+apps/local-studio/.../settings/   LocalStudioSettingsPage · manifest · routes
+```
+
+---
+
+## B. Settings backend (after UI signoff) — order matters
+
+### B0. Design freeze
+
+Three credential lanes stay physically distinct:
+
+| Lane | Durable store | Plaintext |
+|------|---------------|-----------|
+| Account `aak_*` / `AGENTSAM_API_KEY` | `agentsam_api_credentials` (hash) | once at create/rotate via hosted `/api/sdk/api-keys` |
+| Service / bridge `AGENTSAM_BRIDGE_KEY` | **new** `agentsam_service_credentials` (per-caller hash) | once; retire global “assert any X-User-Id” |
+| Provider BYOK | `user_secrets` encrypted | never to browser; test/status only |
+
+`VAULT_MASTER_KEY` stays Worker secret. AES-GCM AAD must bind **`account_id : secret_id : v1`** (not mutable name).
+
+### B1. Host + routes
+
+```text
+apps/local-studio/backend/settings/
+  http/router.*
+  services/{account-credentials,service-credentials,vault-secrets,sessions,audit,usage}.*
+  adapters/{iam-control-plane,d1-vault,credential-usage,vault-crypto}.*
+```
+
+Browser API (no unwrap endpoint):
+
+- `GET/POST/DELETE …/api/settings/credentials/account[/:id/rotate]`  
+- `…/credentials/service[/:id/rotate]`  
+- `GET/POST/PATCH/DELETE …/api/settings/secrets` + `POST …/:id/test`  
+- `GET/DELETE …/sessions` · `GET …/audit` · `GET …/usage`  
+
+Account mint **adapts** to existing `/api/sdk/api-keys` — do not duplicate mint algorithm.
+
+### B2. Replace fixture → read-only real adapters
+
+- [ ] Wire `/api/auth/me` account id into host  
+- [ ] Read-only credentials/secrets/sessions from real stores  
+- [ ] Keep UI green while adapters land  
+
+### B3. Normalize vault ownership
+
+- [ ] Kill Worker vault paths that invent `user_id` / `tenant_id` / `workspace_id` as identity  
+- [ ] All rows keyed by `account_id` → `accounts.id` (= `auth_users.id` normalized)  
+- [ ] Migration **last**, after code paths exist  
+
+### B4. Service credentials + usage ledger
+
+- [ ] Table `agentsam_service_credentials` (per `account_id` + `caller_kind`/`caller_id`)  
+- [ ] Append-only `credential_usage_events` for Last used / Monthly spend  
+- [ ] Materialize `last_used_at` / `usage_count` on credential rows  
+
+### B5. Production identity cleanup (Settings + Studio)
+
+- [ ] Audit `apps/local-studio/frontend/src/lib/auth/*` → KEEP / REPLACE / PREVIEW / DELETE  
+- [ ] Production session from `/api/auth/me` (packages/identity) — **not** Better Auth / Grok / PGLite donor authority  
+- [ ] No second “Local Studio user”  
+
+---
+
+## C. Desktop installer + IAM identity (Connor / newuser123)
+
+**Production already healthy:** `/`, `/auth/login`, `/agentsam` (cbad565 era). Desktop shell: `packages/agentsam-desktop-shell`, manifest `local-studio`.
+
+### C1. Rebuild real installed app
+
+- [ ] Confirm `packages/agentsam-desktop-shell/manifests/local-studio.json`  
+  - `base_url`: `https://agentsam.inneranimalmedia.com`  
+  - `launch_path`: `/agentsam` (**never** `/`)  
+- [ ] Build macOS `.app` + `.dmg`; replace `/Applications/AgentSam Local Studio.app`  
+- [ ] Prove cold launch opens `/agentsam`  
+- [ ] Do **not** redesign Workbench or bundle Vite app in this slice  
+
+### C2. One identity authority
+
+```text
+auth_users → one canonical account
+  ├── Local Studio preferences
+  ├── provider vault
+  ├── terminal connections
+  └── app/product state
+```
+
+- [ ] No Tauri auth DB; no Local-Studio-only accounts  
+- [ ] Hosted Studio uses `GET/POST /api/auth/{me,login,signup,logout}` + `/api/oauth/*`  
+
+### C3. Existing-user signup UX
+
+- [ ] `email_already_registered` → “An account already exists. Sign in instead.” → `/auth/login?next=/agentsam`  
+- [ ] Preserve `next=/agentsam` through signup/login/reset/Google/GitHub/Cloudflare/logout  
+- [ ] OAuth-only users: offer provider login / password-setup — **not** “create another account”  
+- [ ] Auto email-link only when provider **verified** email ownership  
+
+### C4. Thin desktop auth adapter
+
+- [ ] session status · begin login · finish callback · logout  
+- [ ] System browser → IAM portal → one-time `agentsamstudio://callback?code=…`  
+- [ ] Deep link = **single-use code only** (no session cookie / API key / OAuth token in URL)  
+- [ ] Reuse existing Rust deep-link plumbing  
+
+### C5. Real installer surface
+
+- [ ] Canonical: `npx @inneranimalmedia/agentsam-sdk app install local-studio`  
+- [ ] `curl …/install/studio | bash` → same machinery  
+- [ ] Preserve old `--app studio` CLI-launcher behavior if needed for compat; add explicit **desktop** mode  
+- [ ] Do **not** publish `apps/local-studio` (private 0.0.0) to npm as the app  
+- [ ] Optional later: tiny `@inneranimalmedia/agentsam-local-studio` shim  
+- [ ] Commands: `app install|doctor|open|uninstall local-studio`  
+- [ ] Installer: OS/arch → download → digest/signature → install → receipt → register → doctor  
+
+### C6. Release truth
+
+- [ ] Receipt distinguishes `dev_unsigned` | `signed` | `notarized`  
+- [ ] Use `desktop_shell_releases` / `agentsam-desktop-updates` / R2 — no second release backend  
+- [ ] If Worker/table not live → **blocked step**, not fake success  
+
+### C7. Acceptance — Connor / newuser123
+
+Prove clean-user path; return SHA in/out, artifact paths, installer command, new-user + existing-IAM + OAuth results, signing state, blockers.
+
+Non-goals this slice: agentsamd, bundled offline UI, updater redesign, new auth framework.
+
+---
+
+## D. Machine-first apps / world-state / Clack catalog
+
+**Docs already land:** `docs/MACHINE_INTELLIGENCE.md` + plans under `docs/plans/*2026-09-24*`.
+
+### Acceptance (without a model)
+
+1. [ ] List every `apps/*` with calculated maturity + provenance + verify  
+2. [ ] `agentsam inspect` harvested site **and** serious app → **world-state** envelope  
+3. [ ] Answer what/where/contents/capabilities/reusable/missing/verified/next from receipts  
+4. [ ] Decision primitives + confidence-policy receipt on ≥1 path (extend existing `src/sam/decision/`)  
+5. [ ] `agentsam mini` still works  
+6. [ ] Docs state ladder + MINI/APP/WORLD — **scaffold done**; keep help copy aligned  
+
+### Batch order
+
+| Batch | Work |
+|-------|------|
+| A | Decision receipt on maturity/brand path (docs done) |
+| B | World-state envelope; expand `listAppManifests` to `.agentsam/app.json` + bare dirs; maturity engine; strengthen `verify:*` |
+| D1 | Clack `agentsam apps` menu (Preview/Info/Doctor/Scaffold/Deploy maturity-gated) |
+| C | Paste/path/stdin ingest → world-state (not toy fixtures) |
+| D2–D3 | Curated distribute; demote mini as poster |
+
+### CLI gaps (from tonight’s inventory)
+
+| Gap | Action |
+|-----|--------|
+| No `agentsam app add` / `app install` | Add for desktop + scaffold; feature add stays top-level `agentsam add` |
+| World-state = marketing phrase | Converge snapshot + merkle + brand + verify + maturity |
+| Maturity engine missing | Calculated gates only |
+| Theme apps invisible to `listAppManifests` | Discover `.agentsam/app.json` |
+| D1 `agentsam_products` / `asset_relationships` | Wire remote upsert (local-projection only today) |
+| No `/v1/scan` | Inspect first; scan shares engine later |
+| Wasm `--cloudflare-wasm` | Reserved; not this week unless unblocked |
+
+Non-goals: toy demos as proof; auto-fetch remotes; execute imported HTML; TypeSafe vocabulary.
+
+**UI contract:** `AGENTSAM-INTERACTIVE-UI-REQUIREMENTS.md` = implemented (`ctrl-c`). Codex-TUI file = observational (`esc`).
+
+---
+
+## E. Project Control TUI (separate track — do not conflate)
+
+Still **not** the shipped tabbed ANSI Project Control product. Primitives exist (`work-graph`, `src/ui/cli/*`, activity.v1 in-memory). Branch `feat/project-control-workbench-20260925` remains open.
+
+Tomorrow only if bandwidth after A–D:
+
+- [ ] `AgentSamProjectSnapshot` contract  
+- [ ] Persist `agentsam.activity.v1` (SQLite) — activity is **in-memory** today  
+- [ ] Local SQLite GOAP adapter (stop defaulting user GOAP to `inneranimalmedia-business`)  
+- [ ] CLI TUI tabs under `src/ui/cli/tui/` (picocolors; no Ink)  
+
+---
+
+## F. Hygiene / ops
+
+- [ ] Push/PR any leftover worktrees after review (`project-control`)  
+- [ ] Optional: clean stale `/Users/samprimeaux/agent-worktrees/*` clones  
+- [ ] Confirm published SDK version vs docs (`2.6.4` installables; bump notes if needed)  
+- [ ] Site: `npm run site:publish` uses `--remote` (fixed) for Learn/ASFB assets  
+
+---
+
+## Suggested tomorrow morning order
+
+1. Settings visual signoff (A) — 30–60m  
+2. Identity donor audit + signup UX (B5 + C3) — unblocks Connor  
+3. Machine-first Batch B discovery + stub maturity (D) — unlocks honest `agentsam apps`  
+4. Desktop rebuild cold-launch proof (C1) if installer is the day’s P0  
+5. Settings read-only adapters (B2) only after A signed off  
+
+**Do not** start D1 vault migration and desktop notarization and world-state rewrite in the same PR.

package/docs/plans/TOMORROW-MACHINE-FIRST-BRIEFING.md

@@ -0,0 +1,145 @@
+# Tomorrow briefing — Machine-first apps / world-state
+
+**Date staged:** 2026-09-26  
+**Home:** agentsam-sdk `main`  
+**Start here:** [MACHINE_INTELLIGENCE.md](../MACHINE_INTELLIGENCE.md) · **Full TODO:** [TOMORROW-EXTENSIVE-TODO-2026-09-26.md](./TOMORROW-EXTENSIVE-TODO-2026-09-26.md)
+
+This file is the review index for the next work session. Plans that lived only under `.cursor/plans/` are now copied into `docs/plans/`.
+
+---
+
+## Acceptance checklist (do these)
+
+Without a model, AgentSam can:
+
+1. List every `apps/*` with calculated maturity + provenance + verify status  
+2. `agentsam inspect` a harvested site and a serious app → world-state  
+3. Answer what / where / contents / capabilities / reusable / missing / verified / next from receipts  
+4. Expose decision primitives + a confidence-policy receipt on ≥1 classification path  
+5. Keep `agentsam mini` working as the tiny lane  
+6. Docs state machine-first ladder + MINI / APP / WORLD → **done scaffold:** `docs/MACHINE_INTELLIGENCE.md`
+
+### Non-goals
+
+- Toy demos as proof  
+- Auto-fetch remotes  
+- Execute imported HTML  
+- TypeSafe vocabulary  
+- Repo redesign for package purity  
+- Hiding imperfect apps  
+- Mini as architectural poster  
+
+### Interactive UI note
+
+| File | Role |
+|------|------|
+| [AGENTSAM-INTERACTIVE-UI-REQUIREMENTS.md](./AGENTSAM-INTERACTIVE-UI-REQUIREMENTS.md) | **Implemented contract** — interrupt = `ctrl-c` |
+| [AGENTSAM-INTERACTIVE-UI-REQUIREMENTS-codex-tui-20260919.md](./AGENTSAM-INTERACTIVE-UI-REQUIREMENTS-codex-tui-20260919.md) | Observational Codex-TUI brief — `esc` / paste notes differ; do not override the canonical file |
+
+Shell interactive work is **separate** from Apps Clack catalog (`agentsam apps`).
+
+---
+
+## Work orders (copied into repo)
+
+| Doc | Role |
+|-----|------|
+| [UNIVERSAL-INGEST-MACHINE-FIRST-2026-09-24.md](./UNIVERSAL-INGEST-MACHINE-FIRST-2026-09-24.md) | Locked intent, branch hygiene, Batches A–D, acceptance |
+| [MACHINE-FIRST-APPS-TUI-2026-09-24.md](./MACHINE-FIRST-APPS-TUI-2026-09-24.md) | Superseding detail: Clack `agentsam apps`, maturity gates, execution order |
+
+**Suggested order:** Batch A (docs + primitives) → Batch B (world-state + maturity) → Batch D1 (Clack menu with stub maturity) → Batch C (ingest) → Batch D2–D3 (distribute + mini framing).
+
+---
+
+## Docs map by acceptance item
+
+### 1–3 · Apps inventory / inspect / receipts
+
+| Path | Note |
+|------|------|
+| [../MACHINE_INTELLIGENCE.md](../MACHINE_INTELLIGENCE.md) | Ladder + world-state target |
+| [../CAPABILITIES.md](../CAPABILITIES.md) | `repository.snapshot` |
+| [../MERKLE.md](../MERKLE.md) | Hashes / integrity |
+| [../REPOSITORY_INTELLIGENCE.md](../REPOSITORY_INTELLIGENCE.md) | Inspect substrate |
+| [../REPOSITORY_KNOWLEDGE.md](../REPOSITORY_KNOWLEDGE.md) | Index / search |
+| [../BRAND_INTELLIGENCE.md](../BRAND_INTELLIGENCE.md) | World-state consumer |
+| [../THEME_REFINERY.md](../THEME_REFINERY.md) | Harvest ladder + 7 sites |
+| [../architecture/SAM_KERNEL.md](../architecture/SAM_KERNEL.md) | `agentsam inspect` |
+| [../CLI_SHELL.md](../CLI_SHELL.md) | Shell surface |
+| [../../protocol/INSPECT_VIEWS_V1.md](../../protocol/INSPECT_VIEWS_V1.md) | Inspect views contract |
+| [../../protocol/README.md](../../protocol/README.md) | APP vs FEATURE |
+| `apps/*/agentsam.app.json` · `apps/*/.agentsam/app.json` | Manifests (product + harvested) |
+| `apps/*/IMPORT_PROVENANCE.json` | Provenance where present |
+| `protocol/theme-refinery/receipts/*` | Harvest / registry receipts |
+
+### 4 · Decision primitives + confidence
+
+| Path | Note |
+|------|------|
+| [../architecture/SAM_DECISION_WORK_RECEIPT.md](../architecture/SAM_DECISION_WORK_RECEIPT.md) | Shipped choose/score/check (no TypeSafe) |
+| [../architecture/SAM_ACTIVITY_RECOVERY_RECEIPT.md](../architecture/SAM_ACTIVITY_RECOVERY_RECEIPT.md) | Activity stream (in-memory store today) |
+| `protocol/sam/decision-receipt.v1.schema.json` (+ state/question/answer/evaluation/calibration/outcome) | Schemas |
+| `src/sam/decision/` | Implementation |
+| Site twin: `apps/frontend/public/site/docs/sam/structured-decisions/` | Field manual HTML |
+
+### 5 · Mini
+
+| Path | Note |
+|------|------|
+| [../MINI.md](../MINI.md) | `agentsam mini` lane |
+
+### 6 · Ladder + MINI/APP/WORLD
+
+| Path | Note |
+|------|------|
+| [../MACHINE_INTELLIGENCE.md](../MACHINE_INTELLIGENCE.md) | **SSOT for framing** |
+
+---
+
+## Current `apps/*` surface (proof targets)
+
+| App | Kind signal |
+|-----|-------------|
+| `cad-creator` | product — `agentsam.app.json` |
+| `client-cms-editor` | product |
+| `ecommerce-cms-agentsam` | product |
+| `local-studio` | product |
+| `church-site` … `shinshu-site` (7) | harvested — `.agentsam/app.json` |
+| `theme-gallery-preview`, `frontend`, `project-control`, `agentsam-go-worker`, `_incoming` | maturity TBD via calculated gates |
+
+---
+
+## Code touchpoints (do not rebuild)
+
+| Piece | Path |
+|-------|------|
+| CLI router / `app` alias | `src/cli.js` |
+| App commands | `src/commands/app.js` |
+| Inspect / snapshot | `src/commands/product.js` → `src/capabilities/repository-snapshot.js` |
+| Progression / next | `src/progression/engine.js` |
+| Decision | `src/sam/decision/` |
+| Clack patterns | `src/ui/cli/help.js` (+ `@clack/prompts`) |
+| Verify | `scripts/verify-package.mjs`, `scripts/verify-source-boundaries.mjs` |
+
+---
+
+## Secondary context (not the work order)
+
+- [NEXT-AGENT-HANDOFF.md](./NEXT-AGENT-HANDOFF.md)  
+- [RECONCILIATION-2026-09-19.md](./RECONCILIATION-2026-09-19.md)  
+- [MULTI-AGENT-SPRINTS-2026-09-19.md](./MULTI-AGENT-SPRINTS-2026-09-19.md)  
+- [../architecture/SAM_MACHINE_NORMALIZATION_PRECOMMIT_REPORT.md](../architecture/SAM_MACHINE_NORMALIZATION_PRECOMMIT_REPORT.md)  
+- [../DEPLOY_RECEIPTS.md](../DEPLOY_RECEIPTS.md)  
+
+Ignore: `~/Downloads/TOMORROW-AGENT-SAM-FIX.md` (unrelated Shinshu dashboard).
+
+---
+
+## First slice when you sit down
+
+1. Skim `MACHINE_INTELLIGENCE.md` + this briefing  
+2. Confirm decision receipt path still green: `node --test test/integration/sam-decision.test.mjs` (or project equivalent)  
+3. Expand `listAppManifests` to include `.agentsam/app.json` + bare `apps/*` dirs  
+4. Stub calculated maturity on `agentsam app list --json`  
+5. Wire ≥1 maturity/brand path through existing decision primitives → receipt  
+6. Smoke: `agentsam mini templates` still works  

package/docs/plans/UNIVERSAL-INGEST-MACHINE-FIRST-2026-09-24.md

@@ -0,0 +1,215 @@
+---
+name: Universal ingest stack
+overview: Strengthen agentsam-sdk in place—machine-first world state for every app/world, native decision primitives, distributable apps, mini kept as the tiny lane. Proof is real apps and harvested sites, not new demos. Branch hygiene complete on clean main.
+todos:
+  - id: branch-audit
+    content: "DONE 2026-09-24: audited + deleted completed local/remote branches and worktrees; only main remains"
+    status: completed
+  - id: machine-intel-docs
+    content: "Batch A — Land protocol/docs Machine Intelligence scaffold (ladder, primitives, confidence≠risk, receipts, MINI/APP/WORLD)"
+    status: pending
+  - id: decision-primitives
+    content: "Batch A — Native predicate/choice/score/distribution + confidence policy + decision receipts (AgentSam-owned, not TypeSafe)"
+    status: pending
+  - id: world-state
+    content: "Batch B — Converge snapshot+Merkle+AST+brand+harvest into world-state; agentsam inspect for arbitrary paths + every apps/*"
+    status: pending
+  - id: app-maturity
+    content: "Batch B — Calculated maturity + provenance/hashes/capabilities/relationships/verify/next for every apps/*"
+    status: pending
+  - id: verify-strengthen
+    content: "Batch B — Strengthen verify-package/source-boundaries, app contract tests, registry receipts (imperfect = observable)"
+    status: pending
+  - id: ingest-on-worlds
+    content: "Batch C — Universal ingest/extract/sensitive/catalog feeding world-state; fixtures = harvested sites + real apps"
+    status: pending
+  - id: app-distribute
+    content: "Batch D — Graduate curated apps toward npm install / agentsam app add (runtime/scaffold only; exclude donor junk)"
+    status: pending
+  - id: mini-keep-tiny
+    content: "Batch D — Keep mini as instant zero-dep utility lane; demote from architectural poster framing in docs/help"
+    status: pending
+  - id: disk-clutter
+    content: "Optional hygiene — review leftover /Users/samprimeaux/agent-worktrees/* dirs (not linked worktrees; some 50–254MB clones)"
+    status: pending
+isProject: false
+---
+
+# Machine-first AgentSam — strengthen worlds in place
+
+## Intent (locked)
+
+**Audit and strengthen the current system. Do not redesign the repo around package purity.**
+
+Home: [`/Users/samprimeaux/agentsam-sdk`](/Users/samprimeaux/agentsam-sdk) @ clean `main` (`c017da3` Brand Intelligence).
+
+Preserve ownership:
+
+| Layer | Role |
+|-------|------|
+| `apps/*` | Product authoring SSOT — real worlds at uneven maturity |
+| `packages/*` | Reusable / packageable capability surfaces |
+| `protocol/*` | Portable contracts + evidence |
+| `src/*` | AgentSam runtime / CLI machinery |
+| `mini` | Intentionally tiny utility lane — **not** the architectural proof |
+
+**Proof already exists:** `local-studio`, `cad-creator`, `client-cms-editor`, `ecommerce-cms-agentsam`, seven harvested sites. Imperfection is maturity state, not exclusion:
+
+```text
+harvested → scaffolded → wired → verified → releasable → production
+```
+
+## Product scales
+
+```text
+MINI  — tiny local artifact, instant preview, seconds
+APP   — complete packaged product (npm install / agentsam app add), minutes
+WORLD — arbitrary repo → deterministic world state → progressive normalize
+```
+
+---
+
+## Branch audit — COMPLETE (2026-09-24)
+
+Repo now: **local `main` only**, synced to `origin/main` @ `c017da3`. No linked git worktrees besides the primary checkout.
+
+### Deleted (fully on main — tip == merge-base / 0 ahead)
+
+| Branch | Local | Remote | Notes |
+|--------|:-----:|:------:|-------|
+| `chore/package-release-system-20260923` | deleted | deleted | ancestor |
+| `feat/cad-project-tools-20260922` | deleted | deleted | + worktree removed |
+| `feat/feature-capability-snapshots-20260924` | deleted | deleted | ancestor |
+| `fix/local-studio-cms-resolution-and-route-map-20260924` | deleted | deleted | ancestor |
+| `integrate/identity-oauth-finish-20260924` | deleted | n/a | + worktree removed |
+| `integrate/unified-tool-provider-event-contracts-20260924` | deleted | deleted | + worktree removed |
+| `feat/unified-tool-provider-event-contracts-20260923` | n/a | deleted | cherry-`+` completeful commit superseded on main |
+| `feat/agentsam-queue-control-20260923` | n/a | deleted | 0 ahead / 33 behind |
+| `feat/goap-planner-backend` | n/a | deleted | 0 ahead / 112 behind |
+| `rescue/ecommerce-cms-untracked-20260919` | n/a | deleted | 0 ahead / 125 behind |
+
+### Errors-v1 claim — verified, then deleted
+
+| Branch | Ahead by SHA | Verdict |
+|--------|-------------:|---------|
+| `feat/errors-v1-runtime-contract` | 44 | Remotes already gone. Knowledge/Gemini/error adapter files **byte-identical to main** (reconcile via `976506d` / PR #53). Only `test/error-diagnostics.test.mjs` differed; **main is newer**. No unique work to cherry-pick. |
+| `integrate/errors-v1-main` | 40 | Same story; overlaps feat line. Deleted local tip. |
+
+### Remaining git branches
+
+**None** (besides `main` / `origin/main`).
+
+### Leftover disk (not git branches — optional hygiene)
+
+Under `/Users/samprimeaux/agent-worktrees/` (not registered with `git worktree list`):
+
+| Dir | Approx | Note |
+|-----|--------|------|
+| `agentsam-lab` | clone on `main` | separate checkout |
+| `agentsam-sdk` | clone **892 behind** origin/main | stale duplicate — safe delete candidate |
+| `auth-scoped-terminal-lanes` | ~55M | no `.git`; contains `AgentSamRemix` |
+| `cad-release` | empty | leftover shell |
+| `gemini-env` | ~53M | contains `inneranimalmedia` tree |
+| `mcp-account-owned-code-retrieve` | ~254M | MCP server tree |
+| `mcp-search-execute-stabilization` | ~254M | MCP server tree |
+| `memory-v2-contract` | ~2.3M | MCP server tree |
+
+These are **disk clutter**, not unfinished SDK feature branches. Clean when ready; not blocking Batch A–D.
+
+---
+
+## Logical batches of work left (on main)
+
+No branch merge queue. All remaining work is **new implementation on clean main**, grouped as:
+
+### Batch A — Machine Intelligence foundation
+**Todos:** `machine-intel-docs`, `decision-primitives`
+
+- `docs/MACHINE_INTELLIGENCE.md` + protocol schemas for predicate / choice / score / distribution + decision receipts
+- Shared AgentSam-owned primitives + confidence policy (confidence ≠ risk; abstention; hierarchical degrade)
+- Cross-link Brand Intelligence + ingestion as consumers of the same ladder
+- Framing: LLM is one handler inside AgentSam
+
+### Batch B — World-state + every app observable
+**Todos:** `world-state`, `app-maturity`, `verify-strengthen`
+
+- Converge Merkle / `repository.snapshot` / AST / brand / harvest / manifests into one **world-state** envelope
+- `agentsam inspect` works for arbitrary paths **and** every `apps/*`
+- Calculated maturity + provenance + hashes + capabilities + relationships + verify receipts + next actions
+- Strengthen `verify-package.mjs`, `verify-source-boundaries.mjs`, app contract tests, registry receipts
+- Prefer calculated facts over hand labels; imperfect apps stay included
+
+**Current app surface (proof targets, not toys):**
+
+| App | Manifest signal |
+|-----|-----------------|
+| `cad-creator` | `agentsam.app.json` + `.agentsam/app.json` |
+| `client-cms-editor` | same |
+| `ecommerce-cms-agentsam` | same |
+| `local-studio` | same |
+| `church-site` … `shinshu-site` (7 harvested) | `.agentsam/app.json` (theme-refinery) |
+| `theme-gallery-preview`, `frontend`, `_incoming` | maturity TBD via calculated gates |
+
+### Batch C — Ingest feeds world-state
+**Todos:** `ingest-on-worlds`
+
+- Paste / path / stdin → detect → extract → catalog → world-state
+- Sensitive candidates: confidence ≠ risk; redact before preview/model
+- Safe localhost gallery / Brand Packet = **projections** of world-state
+- Fixtures = harvested sites + real app slices (not mini, not toy repos)
+
+### Batch D — APP distribution + mini lane clarity
+**Todos:** `app-distribute`, `mini-keep-tiny`
+
+- Graduate curated apps toward `npm install @inneranimalmedia/<app>` / `agentsam app add`
+- Ship runtime/build/scaffold; exclude donor/reference junk
+- Keep mini as scaffold/preview/zero-dep utilities; demote from poster-child docs/help
+
+### Optional — Disk hygiene
+**Todo:** `disk-clutter`
+
+- Review/remove stale `agent-worktrees/*` clones (especially `agentsam-sdk` @ 892 behind)
+
+---
+
+## Architecture (unchanged)
+
+```mermaid
+flowchart TB
+  repo[Repository_or_App] --> scan[Deterministic_scanner]
+  scan --> files[files_hashes_MIME]
+  scan --> code[AST_routes_APIs]
+  scan --> assets[images_GLB_fonts_URLs]
+  files --> world[WORLD_STATE]
+  code --> world
+  assets --> world
+  world --> classify[Decision_primitives]
+  classify --> route[Confidence_policy_routing]
+  route --> next[Progression_next_actions]
+  world --> brand[brand.scan_consumer]
+  world --> preview[Local_gallery_optional]
+  world --> llm[LLM_only_on_ambiguity]
+```
+
+## Explicit non-goals
+
+- Repo redesign for package purity
+- New toy/demo apps as architectural proof
+- Requiring finished status before inclusion
+- TypeSafe/Jev dependency or product vocabulary
+- Mini as showcase
+- Auto-fetch remotes / auto-delete orphans / execute imported HTML
+- Jump every path to Level-4 LLM
+
+## Acceptance
+
+Without a model, AgentSam can:
+
+1. List every `apps/*` with calculated maturity + provenance + verify status
+2. `agentsam inspect` a harvested site and a serious app → world-state
+3. Answer what/where/contents/capabilities/reusable/missing/verified/next from receipts
+4. Expose decision primitives + a confidence-policy receipt on ≥1 classification path
+5. Keep `agentsam mini` working as the tiny lane
+6. Docs state machine-first ladder + MINI/APP/WORLD
+
+Suggested next execution: **Batch A** (docs + decision primitives), then **Batch B** against real apps.

package/docs/plugins.md

@@ -8,8 +8,8 @@ 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`
+- token storage: the consuming Worker’s `user_oauth_tokens`
+  (`provider=cloudflare`), sealed with that Worker’s `VAULT_MASTER_KEY`
 - tool keys: `agentsam-mcp.docs`, `agentsam-mcp.search`, and
   `agentsam-mcp.execute`