@inneranimalmedia/agentsam-sdk 2.6.4 → 2.6.7

package/docs/plans/MACHINE-FIRST-APPS-TUI-2026-09-24.md

@@ -0,0 +1,227 @@
+---
+name: Machine-first apps TUI
+overview: "Fully plan Batches A–D of the Universal ingest stack in agentsam-sdk: Machine Intelligence docs + decision primitives, world-state/`inspect`, calculated maturity + verify, ingest feeding world-state, and a Clack TUI `agentsam apps` catalog to select/preview/scaffold/deploy packaged prebuilds of past work."
+todos:
+  - id: batch-a-docs-primitives
+    content: "Batch A: MACHINE_INTELLIGENCE.md + predicate/choice/score + confidence policy + decision receipts"
+    status: pending
+  - id: batch-b-world-maturity-verify
+    content: "Batch B: world-state envelope for inspect; expand app discovery; calculated maturity; strengthen verify-*"
+    status: pending
+  - id: batch-d1-clack-apps
+    content: "Batch D1: agentsam apps Clack TUI catalog — select app → Preview/Info/Doctor/Scaffold/Deploy (maturity-gated)"
+    status: pending
+  - id: batch-c-ingest
+    content: "Batch C: universal ingest (paste/path/stdin) feeding world-state with sensitive redaction"
+    status: pending
+  - id: batch-d2-distribute-mini
+    content: "Batch D2–D3: agentsam app add / npm distribute curated apps; mini kept tiny in docs/help"
+    status: pending
+isProject: false
+---
+
+# Machine-first AgentSam + Apps Clack Catalog
+
+**Home:** [`/Users/samprimeaux/agentsam-sdk`](/Users/samprimeaux/agentsam-sdk) · supersedes pending todos in [UNIVERSAL-INGEST-MACHINE-FIRST-2026-09-24.md](./UNIVERSAL-INGEST-MACHINE-FIRST-2026-09-24.md)
+
+**Locked product intent:** Apps become a Clack/TUI selectable catalog of packaged previews/prebuilds of past work. Selecting an app leads to Preview (primary), then Scaffold/Add, then Deploy when maturity allows. Machine Intelligence + world-state make that catalog honest (calculated maturity, not hand badges).
+
+## Intent (unchanged except Apps UX)
+
+Audit and strengthen in place. No repo redesign for package purity. Proof = real `apps/*` + harvested sites. Mini stays the tiny lane.
+
+```text
+MINI  — tiny local artifact (agentsam mini)
+APP   — Clack catalog → preview / scaffold / npm distribute
+WORLD — arbitrary path → world-state → progressive normalize
+```
+
+Maturity ladder (calculated, observable):
+
+```text
+harvested → scaffolded → wired → verified → releasable → production
+```
+
+## Architecture
+
+```mermaid
+flowchart TB
+  appsDir[apps_star] --> discover[discover_manifests]
+  discover --> catalog[Clack_apps_menu]
+  catalog --> preview[Preview_local]
+  catalog --> scaffold[Scaffold_or_app_add]
+  catalog --> deploy[Deploy_if_releasable]
+  pathIn[Path_paste_stdin] --> ingest[detect_extract_catalog]
+  ingest --> world[WORLD_STATE]
+  discover --> world
+  scan[repository_snapshot_merkle_brand] --> world
+  world --> maturity[Calculated_maturity]
+  maturity --> catalog
+  world --> primitives[predicate_choice_score]
+  primitives --> policy[confidence_policy]
+  policy --> next[next_actions]
+  verify[verify_package_boundaries_app] --> maturity
+```
+
+## Current baselines to leverage (do not rebuild)
+
+| Piece | Path | Use |
+|-------|------|-----|
+| CLI router (`app`/`apps` alias) | [`src/cli.js`](/Users/samprimeaux/agentsam-sdk/src/cli.js) | Route bare `apps` → TUI |
+| App commands today | [`src/commands/app.js`](/Users/samprimeaux/agentsam-sdk/src/commands/app.js) | Extend discovery + actions; today only `agentsam.app.json` (4 product apps) |
+| Clack already | `@clack/prompts` in help/models/providers/scaffold | Same patterns for apps menu |
+| Inspect | [`src/commands/product.js`](/Users/samprimeaux/agentsam-sdk/src/commands/product.js) → [`repository-snapshot.js`](/Users/samprimeaux/agentsam-sdk/src/capabilities/repository-snapshot.js) | Expand into world-state envelope |
+| Progression / next | [`src/progression/engine.js`](/Users/samprimeaux/agentsam-sdk/src/progression/engine.js) | Feed maturity next-actions |
+| Brand Intelligence | [`docs/BRAND_INTELLIGENCE.md`](/Users/samprimeaux/agentsam-sdk/docs/BRAND_INTELLIGENCE.md) + `packages/agentsam-brand` | Consumer of world-state + primitives |
+| Verify | `scripts/verify-package.mjs`, `verify-source-boundaries.mjs` | Strengthen; wire into maturity |
+| Theme apps | `.agentsam/app.json` on 7 harvested sites | Include in catalog (today invisible to `listAppManifests`) |
+
+---
+
+## Batch A — Machine Intelligence foundation
+
+### A1. Docs
+- Add [`docs/MACHINE_INTELLIGENCE.md`](/Users/samprimeaux/agentsam-sdk/docs/MACHINE_INTELLIGENCE.md): ladder, MINI/APP/WORLD, confidence ≠ risk, receipts, LLM as one handler.
+- Cross-link Brand Intelligence + Repository Intelligence + this Apps catalog.
+- Demote mini as architectural poster in help copy (Batch D completes that).
+
+### A2. Decision primitives (AgentSam-owned)
+- New module under `src/intelligence/` (or `packages/agentsam-intelligence` if boundary requires): `predicate`, `choice`, `score`, `distribution`.
+- Confidence policy: abstention, hierarchical degrade, confidence ≠ risk.
+- Decision receipts: `{input_hash, primitive, result, confidence, risk?, next}`.
+- Protocol schemas under `protocol/` mirroring brand capability style.
+- First consumer path: classify app maturity gate OR brand scan route — one real path with a receipt, not a demo.
+
+**Acceptance A:** Doc lands; ≥1 classification path emits a decision receipt without a model.
+
+---
+
+## Batch B — World-state + every app observable
+
+### B1. World-state envelope
+Converge into one JSON envelope (new capability `world.state` or extend `repository.snapshot` with a stable `world` view):
+
+- files / hashes / MIME (snapshot + merkle)
+- AST / routes / APIs (existing intelligence slices)
+- brand packet (when present)
+- app manifest + provenance
+- verify receipts
+- maturity + next_actions
+
+`agentsam inspect [path]` returns this envelope for arbitrary paths **and** every `apps/*`.
+
+### B2. Discovery + maturity engine
+Extend [`listAppManifests`](/Users/samprimeaux/agentsam-sdk/src/commands/app.js):
+
+1. Prefer `agentsam.app.json` (product apps).
+2. Fall back to `.agentsam/app.json` (theme-refinery / harvested).
+3. Still list dirs under `apps/` that lack manifests as `harvested` with low maturity (observable, not hidden).
+
+Calculated maturity gates (facts, not labels):
+
+| Stage | Gate examples |
+|-------|----------------|
+| harvested | dir exists; optional gallery/canonical paths |
+| scaffolded | package.json / wrangler / preview root present |
+| wired | bin + commands.preview/doctor resolve |
+| verified | doctor + app contract / boundary checks pass |
+| releasable | verify receipts green; no donor junk in publish set; secrets marked |
+| production | deploy receipt / remote binding evidence |
+
+### B3. Strengthen verify-\*
+- `verify-package` / `verify-source-boundaries`: keep; add app-level contract checks invoked by `agentsam app doctor` and maturity.
+- Imperfect apps stay listed; failures become receipts on the catalog row.
+
+**Acceptance B:** `agentsam inspect apps/cad-creator` and `agentsam inspect apps/church-site` both emit world-state; `agentsam app list --json` shows maturity for every `apps/*`.
+
+---
+
+## Batch C — Universal ingest → world-state
+
+- Paste / path / stdin → detect → extract → sensitive candidates (confidence ≠ risk; redact before preview/model) → catalog → world-state.
+- Safe localhost gallery / Brand Packet = projections of world-state.
+- Fixtures = harvested sites + real app slices (not mini, not toy repos).
+- Wire into existing ZIP ingest only as one path (`scripts/ingest-app-zips.py`); CLI front door is `agentsam inspect` / shell paste, not a separate product brand.
+
+**Acceptance C:** Ingest a harvested site fixture → world-state row appears in apps discovery or inspect output with sensitive fields redacted.
+
+---
+
+## Batch D — Apps Clack catalog + distribute + mini clarity
+
+### D1. Clack TUI is the primary `agentsam apps` UX (locked)
+
+When TTY and no subcommand (or `--interactive`):
+
+```text
+agentsam apps
+  → Clack select: catalog of apps
+       label: name · id · maturity · kind(product|theme|incoming)
+  → Clack select: action
+       Preview | Info | Doctor | Scaffold / Add | Deploy
+```
+
+**Action rules (locked):**
+
+| Action | When enabled | Behavior |
+|--------|--------------|----------|
+| **Preview** | maturity ≥ scaffolded and preview command/bin exists | Existing `runAppBin(..., preview)` / theme gallery preview — local packaged prebuild |
+| **Info** | always | Manifest + world-state summary |
+| **Doctor** | wired+ | Existing doctor bin / calculated checks |
+| **Scaffold / Add** | scaffolded+ | `agentsam app scaffold <id> <dir>` or new `agentsam app add <id>` into cwd/target; ships runtime/scaffold only |
+| **Deploy** | maturity ≥ releasable | Delegate to existing app wrangler / `agentsam deploy` path; refuse with next_actions if below gate |
+
+Non-TTY / scripted: keep `agentsam app list|info|doctor|preview|scaffold` and add:
+
+- `agentsam app add <id> [dir]`
+- `agentsam app list --json` (maturity fields)
+- `agentsam apps` with args still routes to same command tree
+
+Implementation touchpoints:
+
+- Expand [`src/commands/app.js`](/Users/samprimeaux/agentsam-sdk/src/commands/app.js) with `runAppsInteractive()` using `@clack/prompts` `select` / `confirm` (same style as [`src/ui/cli/help.js`](/Users/samprimeaux/agentsam-sdk/src/ui/cli/help.js)).
+- [`src/cli.js`](/Users/samprimeaux/agentsam-sdk/src/cli.js): bare `apps` with empty argv → interactive; `app list` stays non-interactive default for scripts.
+
+### D2. npm distribute
+- Curate publishable set for product apps (cad / cms / studio / ecommerce) toward `@inneranimalmedia/<app>` or documented `agentsam app add` from registry.
+- Exclude donor/reference junk per existing RELEASES / local-studio donor notes.
+- Catalog marks `distributable: true` only when releasable gates pass.
+
+### D3. Mini lane
+- Keep `agentsam mini` working; docs/help state it is the tiny utility lane, not the proof of architecture.
+- Apps catalog is the poster for packaged past work.
+
+**Acceptance D:** On a TTY, `agentsam apps` opens Clack menu listing product + harvested apps with maturity; selecting Preview boots a local prebuild; Deploy is offered only for releasable apps; `agentsam mini` still works; docs state MINI/APP/WORLD.
+
+---
+
+## Explicit non-goals
+
+- Repo redesign for package purity
+- New toy apps as proof
+- Hiding imperfect apps from the catalog
+- TypeSafe/Jev vocabulary
+- Auto-fetch remotes / execute imported HTML
+- Jumping every path to LLM
+- Replacing `agentsam shell` interactive UI work (already planned separately)
+
+## Execution order
+
+1. **Batch A** (docs + primitives) — unblocks vocabulary
+2. **Batch B** (world-state + maturity + verify + discovery) — unblocks honest catalog
+3. **Batch D1** (Clack `agentsam apps` menu) — ship usable select/preview as soon as maturity stubs exist; refine gates as B hardens
+4. **Batch C** (ingest → world-state) — feeds catalog/inspect
+5. **Batch D2–D3** (npm distribute + mini framing)
+
+Suggested first PR slice after plan approval: A1+A2 + B2 discovery expansion + D1 Clack menu with stub maturity (wired from manifest presence), then deepen world-state/verify.
+
+## Validation (each batch)
+
+- `node --check` on touched JS
+- Existing `test/cli/*.test.mjs` + new tests for maturity calculation and interactive path (mock Clack or non-TTY `--json`)
+- `npm run verify:package` / `verify:boundaries` before any distribute claim
+- Manual TTY: `agentsam apps` → select `local-studio` → Preview
+
+## Optional hygiene (non-blocking)
+
+Review leftover `/Users/samprimeaux/agent-worktrees/*` clones (stale SDK @ 892 behind, etc.) when convenient.

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