@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.3

package/docs/PROJECT_CONFIG.md

@@ -57,10 +57,13 @@ Current schema:
 D1 / runtime stores         runs, plans, tasks, executions, model history, subagents
 Merkle snapshot store       filesystem evidence and snapshot lineage
 Git                         source-control authority
+knowledge generations       indexed evidence history; never mutable project config
 ```
 
 Do **not** add account/user/tenant/workspace identity, current run IDs, active task state, PTY/session/connection IDs, current Merkle roots, provider credentials, deployment receipts, model history, or subagent execution records to the project manifest.
 
+AutoRAG manages the existing `.agentsam/knowledge.json` authority. It may add a portable repository/project key and explicit lane/profile settings there; it does not create per-lane, retrieval, backend, or credential config files. `workspace_id` is legacy read compatibility only, not universal knowledge authority.
+
 `repository.id` is the portable repository authority for Agent Sam surfaces. Existing `knowledge.json.repository_id` remains readable during migration, but when both files exist the IDs must agree. Git remote discovery is fallback/adoption evidence rather than a second persistent identity.
 
 For a repository already hosted on a known Git provider, IDs use the portable form such as `github:owner/repo`. Repositories without a provider identity receive a durable `local:<uuid>` ID.

package/docs/REPOSITORY_KNOWLEDGE.md

@@ -72,6 +72,8 @@ The current SDK contains a portable/local knowledge slice with deterministic rep
 
 That is useful as a standalone implementation. It is not presented as the architecture of every Agent Sam host.
 
+`@inneranimalmedia/agentsam-sdk/autorag` is the higher-level façade over that same engine. It performs discovery, recommends bounded source scopes, manages the existing knowledge config, selects explicit provider/backend lanes, and runs probes. It never becomes a second indexing runtime. The lower-level engine remains available through `@inneranimalmedia/agentsam-sdk/knowledge`.
+
 ## InnerAnimal production implementation
 
 The InnerAnimal platform is a separate host implementation with a broader code-intelligence pipeline: repository/index generations, a dedicated Tree-sitter parsing service, D1 structural nodes/edges, structural-first graph retrieval, semantic projections, and bounded hydration.

package/docs/THEME_REFINERY.md

@@ -0,0 +1,120 @@
+# Theme Refinery — Archaeology → Product Graph
+
+**Law:** discover ≠ promote · install ≠ activate · automation ≠ authority  
+**SSOT for registry:** live `inneranimalmedia-business` D1 (`agentsam_products` + `asset_relationships` + evidence/artifacts)  
+**SSOT for packages:** `agentsam-sdk` workspaces (`@inneranimalmedia/heuristic-theme`, `@inneranimalmedia/theme-*`)
+
+Python owns deterministic harvest/normalize/preview/QA. AgentSam owns interpretation. **Every meaningful product unit must reconcile into D1** — filesystem-only runs are incomplete.
+
+## Pipeline states
+
+```
+old scattered website
+        ↓ discover + fingerprint          → evidence snapshot (website/repository)
+        ↓ make portable                   → work/theme-harvest/<slug>/
+        ↓ make previewable                → preview/ + agentsam_artifacts
+        ↓ classify + document             → agentsam_products UPSERT (prototype)
+        ↓ normalize structure             → apps/<slug> (scaffolded)
+        ↓ map reusable features           → feature.v1 + asset_relationships
+        ↓ visual/product refinement       → AgentSam (preserve design, replace plumbing)
+        ↓ QA + screenshots + receipts     → quality_reports + evidence
+        ↓ promote                         → production (human authority)
+apps/<sellable-theme>  +  @inneranimalmedia/theme-<slug>
+```
+
+## Product unit kinds (`agentsam_products.kind`)
+
+| Kind | Use when |
+|------|----------|
+| `app` | Sellable site/APP (`insurance-site`) |
+| `theme` | Visual/design product or stock shell (`heuristic-theme`) |
+| `sdk-package` | npm boundary (`@inneranimalmedia/theme-insurance-site`) |
+| `section` / `block` | Reusable CMS pieces (also may write `cms_component_templates`) |
+| `ui-component` | Header/nav shells extracted for reuse |
+| `integration` | Provider adapters (Resend, Square, …) |
+| `service` | Worker/backend service |
+| `script` / `solution` / `collection` / `product` / `product-line` | As classified |
+
+**Status ladder:** `prototype` → `scaffolded` → `wired` → `production` (→ `deprecated`)
+
+UPSERT by stable `slug`. Never delete/recreate to refresh metadata.
+
+## D1 reconciliation (required)
+
+### 1. `agentsam_products` — canonical identity
+
+- Resolve `repository_id` from live `code_repositories` (never invent IDs).
+- Set `canonical_path` (e.g. `apps/insurance-site`, `packages/theme-insurance-site`).
+- Rely on existing triggers for `defined_in` → `code_repository`.
+- Provenance in `metadata` only (no secrets). See `protocol/theme-refinery/product-metadata.schema.json`.
+
+### 2. `asset_relationships` — topology
+
+Idempotent UPSERT on `(source_type, source_id, target_type, target_id, relationship_type)`.
+
+Preferred verbs already in use: `defined_in`, `depends_on`, `consumed_by`, `builds_shell_for`, `integrates_with`, `packaged_as`, `runtime_for`, `exposes_tool`, `provides_workflow`, `sourced_from`, …
+
+Example:
+
+```
+insurance-site --sourced_from--> (evidence / donor path hash)
+insurance-site --packaged_as--> @inneranimalmedia/theme-insurance-site
+insurance-site --depends_on--> theme.storefront.shell / cms contracts
+```
+
+### 3. `agentsam_evidence_snapshots` — point-in-time proof
+
+Fingerprint, intake, pre/post visual, link scans.  
+Product row = durable summary; snapshot = detailed evidence.
+
+### 4. `agentsam_artifacts` — durable previews/docs
+
+Screenshots, preview bundles, help exports. Link via relationships (`has_preview`, `documented_by` — extend vocabulary intentionally).
+
+### 5. `agentsam_quality_reports` — only when a real report artifact exists
+
+### 6. `cms_themes` vs product identity
+
+Style tokens → `cms_themes`. Sellable APP → `agentsam_products`. Link; do not substitute.
+
+### 7. `cms_component_templates`
+
+Only for extracted reusable sections/blocks — not whole sites.
+
+### 8. Discovery inputs (merge automatically)
+
+- `~/company-map/machine/projects.json` + `git-roots.json`
+- `~/IAM-Library/01_Template_Candidates`
+- live D1 `apps` (historical inventory — discovery/backfill only)
+- existing `agentsam_products` + `code_repositories`
+- explicit donor roots
+
+`apps` / `client_apps` are **not** the new SSOT. Backfill into `agentsam_products`.
+
+## CLI surface (target)
+
+```
+agentsam theme harvest <path>     # archaeology packet + evidence + product UPSERT (prototype)
+agentsam theme preview <slug>     # gallery-ready artifacts
+agentsam theme normalize <slug>   # proposed plan (scaffolded/wired)
+agentsam theme promote <slug>     # human-gated → production
+agentsam themes                   # status table from D1 + filesystem
+```
+
+## Reconciliation receipt
+
+Every run emits `ThemeRefineryReconciliationReceipt` (`protocol/theme-refinery/reconciliation-receipt.schema.json`):
+
+discovered / matched / registered / updated / unchanged products · repositories resolved · relationships · evidence · artifacts · quality reports · CMS themes/templates · tools/workflows linked · duplicates · promotions · failures.
+
+**Run incomplete if only files were written.**
+
+## Packages (current)
+
+| Package | Role |
+|---------|------|
+| `@inneranimalmedia/heuristic-theme` | Stock CMS `theme.storefront.shell` |
+| `@inneranimalmedia/theme-<slug>` | Installable gallery theme contracts |
+| `apps/theme-gallery-preview` | Proving surface / historical mounts — not the package SSOT |
+
+Preserve design, replace plumbing: old auth/email/uploads/CMS → current feature vocabulary.

package/docs/architecture/PROVIDER-TOOLS-AND-COMPACTION.md

@@ -0,0 +1,60 @@
+# Provider tools and conversation compaction
+
+Canonical capability schemas stay in `protocol/`. The Responses runner validates
+selected schemas before any paid pre-turn compaction or inference. Provider
+adapters also compile at their HTTP boundary for direct SDK callers.
+
+`src/providers/tool-schema.js` owns a bounded supported JSON Schema dialect:
+objects, scalar types/enums, arrays and nested anyOf, with supported scalar bounds.
+It strips annotation metadata without confusing schema keywords with property
+names. OpenAI/Grok strict projections close every object and make optional
+properties required-and-nullable. The runtime restores those optional nulls to
+omission before invoking canonical handlers. Gemini uses its JSON Schema field,
+`parametersJsonSchema`, not the incompatible OpenAPI `parameters` field.
+
+Unknown/unsupported validation keywords, refs, dynamic dictionaries, malformed
+required arrays, missing array items and invalid types fail locally with the
+provider, tool and schema path. This is deliberately not a general JSON Schema
+compiler: adding refs/compositions requires a tested projection, not dropping
+validation keywords or changing strict mode. Provider/API acceptance still needs
+live integration evidence; local validation cannot prove model availability or
+all future provider restrictions.
+
+`knowledge.search` has a real schema for text, bounded search limits, semantic
+selection and generation. Runtime-owned cwd is injected by the runner.
+
+## Interactive compaction
+
+- `/compact` uses the selected active session/model's existing native `compact()`.
+- `/compact status` reports support, active context, canonical threshold,
+  automatic state and the latest receipt.
+- `/context` includes the same model-policy threshold and compaction support.
+- `/session` and `/usage` include provider compaction usage/cost in cumulative totals.
+
+The exact returned output is canonical continuation input. It may contain both
+ordinary provider-returned items and encrypted items; it must not be filtered to
+only encrypted items, decoded, or turned into a homemade summary. A dedicated
+session record in the same project SQLite stores only the latest pending returned
+window (maximum 10 MiB), separately from generic session JSON. It is atomically
+saved with its usage/cost receipt, survives resume, and is deleted when a new
+provider response ID successfully replaces it. This storage is local access-
+restricted SQLite, not an application-level encrypted store; it must never be
+exported as knowledge, telemetry, or model reasoning logs.
+
+Automatic pre-turn compaction includes usage/cost in totals and can checkpoint
+its output before the subsequent model call. A failed continuation leaves the
+saved compacted window available for retry. Providers lacking declared native
+compaction fail closed for the manual command. The local context-item truncation
+module is unchanged.
+
+OpenAI normal requests use server-side `context_management` when the model
+explicitly declares compaction and a canonical policy threshold. The same
+`autoCompact: false` option disables both automatic paths. Response-ID chaining
+sends only new input; standalone compaction clears the old ID and uses the exact
+returned window. Server-side usage is accounted from the normal response.
+
+Sources checked during implementation:
+- https://developers.openai.com/api/docs/guides/function-calling
+- https://ai.google.dev/api/generate-content#FunctionDeclaration
+- https://developers.openai.com/api/docs/guides/compaction
+- https://developers.openai.com/api/reference/python/resources/beta/subresources/responses/methods/compact

package/docs/architecture/STORAGE.md

@@ -0,0 +1,87 @@
+# AgentSam storage architecture
+
+## Authorities
+
+AgentSam's own local execution state defaults to one database per project:
+`<projectRoot>/.agentsam/data/agentsam.sqlite`. A model or provider switch
+keeps the same ProjectSession and storage authority. A `cwd` change inside the
+project also keeps it. Switching repositories selects a new project authority.
+
+The user's application keeps its actual storage. In this repository,
+`apps/local-studio/backend/wrangler.jsonc` declares a deployed Worker with D1,
+Hyperdrive, R2, Workers AI, and service bindings. AgentSam must honor those
+bindings for Worker features. Its local SQLite session state does not replace
+the Worker's data, provision new cloud state, or start an implicit sync. Inspect
+the project's real deployment and data bindings before choosing storage for
+application features. Use local SQLite for application data only when the user
+selects it or the task benefits from a clearly scoped local cache or scratch
+store.
+
+Cloudflare, Postgres/Supabase, object stores, and vector systems are connected
+infrastructure. Their use is explicit and governed by the user's project and
+credentials. Ordinary `agentsam` boot requires none of them. Durable Objects
+are reserved for a future optional actor adapter with a demonstrated need for
+globally addressed, serialized distributed actors. No default runtime path may
+require one.
+
+## Runtime state and lifecycle
+
+`src/local/runtime-store.js`, `src/local/sqlite.js`, and
+`src/local/migrations.js` own the local relational runtime and its versioned
+SQL. `src/lib/local-sessions.js` writes resumable session records to the same
+database. The older `~/.agentsam/sessions/*.json` files are a read-only
+compatibility source: a session is imported only when its saved project root
+matches the selected project. New sessions do not write there.
+`agentsam resume` lists sessions for the current project; use
+`agentsam resume --cwd <project-path>` when invoking it elsewhere. Opaque
+provider response IDs can continue across process restarts. Provider message
+arrays remain in memory for the active shell and are not stored in generic
+session state. An explicit native compaction saves only its latest returned
+window in the separate `agentsam_provider_continuations` session record, bounded
+to 10 MiB. It is replaced on compaction and deleted after successful continuation.
+Generic session JSON retains only a presence marker and a usage/cost receipt.
+The returned window may contain plaintext provider items as well as encrypted
+items; local SQLite file permissions protect access, not application-level
+encryption. It is never a knowledge source. Outside that explicit checkpoint,
+providers without an opaque continuation ID start a fresh model conversation
+after process restart.
+
+| Lifecycle | Keep | Expire or discard |
+| --- | --- | --- |
+| persistent | project configuration, selected model metadata, valuable cache | stale derived copies |
+| session | safe continuation IDs, status, usage, bounded receipts | raw prompts and provider message arrays |
+| work_cycle | accepted objective/plan, final checkpoint and evidence | search frontier and rejected candidates |
+| ttl | useful temporary context digest until expiry | expired digest/scratch |
+| scratch | recoverable intermediate state only while needed | all obsolete scratch |
+
+Existing runtime tables carry their own status and expiry fields where
+applicable. New persisted concepts require a migration, an owner, and a
+cleanup rule. Credentials stay in the existing credential-specific machine
+stores. Session state retains no access/refresh tokens, provider keys, cookies,
+or raw prompts. Blob and vector data do not belong behind a pretend universal
+relational interface. `SQLITE_RUNTIME_CAPABILITIES` reports transactions,
+relational queries, application-managed expiry, and local-only storage; it
+does not claim shared remote state, blob/vector storage, or actor semantics.
+
+## Connected infrastructure and sync
+
+Use the cheapest appropriate authority already available. Local session and
+run state belongs in SQLite. Remote relational application data may belong in
+the user's D1 or Postgres. Blobs may belong in the user's object store; vectors
+in the selected vector system. An explicit remote integration must state its
+source authority, owner, direction, retry, conflict, freshness, and deletion
+policy before copying state between stores. Connected D1 does not move a local
+ProjectSession into D1.
+
+## Enforcement
+
+The existing source boundary verifier rejects a new Durable Object dependency
+in the default shell, runtime store, agent, and provider paths. It also checks
+that resumable sessions use the canonical project SQLite database and that
+runtime schema definitions stay in versioned migrations. Focused storage tests
+cover project-root selection, project isolation, model-independent session
+storage, migration behavior, and secret-free session rows.
+
+See [Provider tools and compaction](PROVIDER-TOOLS-AND-COMPACTION.md) for the
+continuation contract and [knowledge lifecycle proposal](../../protocol/knowledge/LIFECYCLE.md)
+for blackboard, knowledge, evidence, and store-selection boundaries.

package/docs/cad-project-tools.md

@@ -0,0 +1,69 @@
+# CAD project tools — implementation contract
+
+Ticket: tkt_ae8044139c294a6a. Work branch: feat/cad-project-tools-20260922.
+
+## Geometry and surfaces
+CAD Creator's editable DesignProject is canonical: coordinates, wall thickness/heights, furniture and room polygons are inches; scale must equal 1. Door/window locations are ratios along their host wall. IDs survive edits and native generation. Display units do not rescale the document.
+
+The existing IAM Design Studio BIM viewport consumes GLB with placement metadata. It does not edit a FreeCAD/BIM object tree. Blender receives metres; exported GLB is the preview interchange, while project JSON remains editable. There is no IFC semantic roundtrip in this implementation.
+
+The courtyard fixture is a reference-derived massing baseline with a 72 by 60 foot bounding envelope, two 22 foot wings and 28 foot centre span. The envelope is not enclosed floor area. Height is an explicit assumption. Roof generation, nonrectangular floor triangulation and parametric-object evaluation are not yet supported by this native adapter and fail explicitly.
+
+## Shared handlers
+Nine tools: project get, validate, atomic apply, save, restore; native build, inspect, render, export. Schemas live in shared/cad/src/domain/project-tools.js, geometry validation/edits in project-contract.js, and execution in src/lib/cad/project-runtime.js.
+
+CLI, SDK agent capability adapter, CAD Creator HTTP API and frontend tool dispatcher invoke these same handlers. App builds package the runtime and Blender adapter, including standalone scaffolds.
+
+Save requires expected_revision (0 for new). Restore creates another immutable revision. CLI edits emit filesystem-backed SSE updates to the app; unsaved browser edits are retained on conflict. Native receipts bind content hashes and model digests to exact revisions.
+
+## Running
+From the SDK checkout:
+```sh
+node bin/agentsam cad project tools
+node bin/agentsam cad project save request.json --root /absolute/project-root
+node bin/agentsam cad project workflows
+node bin/agentsam cad project workflow cad.house_baseline baseline-request.json --root /absolute/project-root
+node bin/agentsam cad project workflow cad.edit_preview edit-request.json --root /absolute/project-root
+npm run dev --prefix apps/cad-creator
+```
+Baseline request is {project: DesignProject}; edit request is {project_id, expected_revision, operation}. Set AGENTSAM_CAD_PROJECT_ROOT on the app to the same --root used by the CLI. Open the saved project ID using the revision panel.
+
+Local state is .agentsam/cad/projects, native artifacts .agentsam/cad/artifacts, and workflow evidence .agentsam/cad/workflow-runs under the selected root. A native engine is required; there is no simulated success.
+
+## Existing D1 structures
+No tables are added.
+
+| Existing structure | Role |
+|---|---|
+| agentsam_tools | Schema, handler_key cad_project, capability, lifecycle/visibility |
+| agentsam_capabilities + agentsam_tool_capabilities | Existing design.read/write/export with exact operations |
+| designstudio_design_blueprints | Editable project in sketch_json; revision/hash in generation_config_json |
+| scene_snapshots + R2 | Immutable project snapshots; CAD_PROJECT type; owner-scoped access |
+| agentsam_workflows / nodes / edges | Baseline and edit-preview graphs, pinned tools, prerequisites |
+| agentsam_workflow_runs | Account-owned workflow execution |
+| agentsam_executions / execution_steps | Per-tool attempt and verification output |
+| agentsam_artifacts / execution_artifacts | Private durable output and per-execution evidence; only populate for actual uploaded objects |
+| agentsam_workspace_state / plans / plan tasks / work tracking checkpoint | Existing GOAP work tracking, separate from geometry and execution evidence |
+
+D1ProjectStore implements the existing blueprint/snapshot mapping with injected D1 and R2 bindings, authenticated host scope and transactional optimistic concurrency. It has been tested against the existing schemas. The local app currently uses FileProjectStore; it does not claim automatic cloud synchronisation.
+
+GOAP metadata exposes prerequisites and effects. Effects are returned only after completed verified execution. The existing /goap work tracker has not been replaced by a new planner; consuming these action definitions through its planner remains an integration task.
+
+## Registry and hosted boundary
+Generate: node scripts/cad-registry.mjs
+Check committed/source parity: node scripts/cad-registry.mjs --check
+Check a live D1 export: node scripts/cad-registry-verify.mjs live-rows.json
+
+registry/cad-project includes generated tools, schemas, bindings, capability associations, workflow graphs and SQL. The IAM repo carries the identical manifest and migration plus its backend cad_project bridge. Transport adds sdk_root/project_root and nests the common schema in input. It resolves account identity from authenticated run context and executes through the owned local terminal lane.
+
+The seed deliberately registers tools inactive and workflows draft. Local native proof is not hosted deployment proof. Do not activate until the IAM binding is deployed and the catalog path completes the same roundtrip. Do not widen OAuth/client grants as part of seeding.
+
+## Verification
+```sh
+node --test test/cad-project.test.mjs test/cad-project-d1.test.mjs test/cad-project-workflow.test.mjs
+AGENTSAM_TEST_NATIVE_CAD=1 node --test test/cad-project-native.test.mjs
+npm run package:verify --prefix apps/cad-creator
+AGENTSAM_TEST_CAD_APP=1 node --test test/cad-project-app.test.mjs
+node scripts/cad-registry.mjs --check
+```
+Verified on the local Mac: real .blend, GLB and PNG; edit/restore rebuild; both workflows; production app API + SSE + stale-write rejection; package build/typecheck/tests. Hosted deployment, browser visual review, D1 host wiring and IFC roundtrip are not claimed by these checks.

package/docs/cms-scaffolding-pattern-reference.md

@@ -0,0 +1,73 @@
+# CMS scaffolding pattern reference — sections/blocks/schema
+
+_Reference captured 2026-09-18; reconciled against current SDK tree 2026-09-19._
+
+The pattern worth copying isn't a framework, it's a separation: reusable sections and blocks with a typed schema, page composition as pure data (templates), and an editor UI generated automatically from each section or block's schema — never hand-built per section or block. Every tool below implements this same separation differently; this doc tracks how, so agentsam-sdk's version can be compared against them as it's built.
+
+## The core pattern
+
+Shopify's [theme architecture](https://shopify.dev/docs/storefronts/themes/architecture) is the cleanest real-world example of the separation worth copying. Six primitives, each with one job:
+
+| Primitive | Job | Who edits it |
+| --- | --- | --- |
+| Layout file | Repeated shell (header/footer) every page renders inside | Developer |
+| Template (JSON) | Which sections appear on a page, in what order — pure data, no markup | Merchant, via editor |
+| Section group | Container letting merchants add/remove/reorder sections in fixed zones (header, footer) | Merchant |
+| Section | A reusable, self-contained module with its own `{% schema %}` block defining its editable fields | Developer writes it, merchant configures it |
+| Block | A repeatable sub-item inside a section (one testimonial card inside a testimonials section) | Merchant |
+| Snippet | Small reusable code partial, invisible to merchants, no schema | Developer only |
+
+The part that matters most: **a section's schema is what generates its settings panel in the editor.** Nobody hand-builds a settings UI per section — the editor reads the schema and renders the right inputs (text field, image picker, color swatch, range slider) automatically. Add a new section with a new schema and the editor already knows how to edit it.
+
+## How the leading tools implement the same pattern
+
+Every modern visual builder is solving the same problem Shopify solved — register a section or block once, get its editor UI for free — with a different registration API and a different ownership model.
+
+| Tool | Registration call | Schema lives | Editor UI | Code ownership |
+| --- | --- | --- | --- | --- |
+| [Shopify (Dawn)](https://shopify.dev/docs/storefronts/themes/architecture) | `{% schema %}` tag at the bottom of a `.liquid` section file | Inside the section file itself | Auto-generated from schema, zero custom UI code | Hosted — themes only run on Shopify |
+| [Plasmic](https://docs.plasmic.app/learn/registering-code-components) | `PLASMIC.registerComponent(Component, meta)` | JS object passed at registration (`props` field) | Auto-generated panel in Plasmic Studio from `meta.props` | Can generate/export React code into your own repo |
+| [Makeswift](https://docs.makeswift.com/developer/docs/reference/makeswiftruntime/reactruntime/register-component) | `runtime.registerComponent(Component, { type, label, props })` | `props` object, values are "Controls" (`Style`, `TextInput`, etc.) | Panel built from the Controls you pass per prop | Runs inside your own Next.js codebase |
+| [Builder.io](https://www.builder.io/c/docs/input-types) | `Builder.registerComponent(Component, { name, inputs })` | `inputs` array, each with a `name` + `type` (string, color, richText, object, list…) | Auto-generated from `inputs`, same input-type system also drives their headless CMS data models | Hosted headless CMS; components live in your repo |
+| [Webstudio](https://github.com/webstudio-is/webstudio) | Not confirmed against a cited source — don't take this as a specific API to copy | Not confirmed against a cited source | Visual canvas editor | Verified: fully open source, self-hostable — you own data, components, and infrastructure |
+
+The pattern is identical across the sourced rows: **schema → editor UI writes itself.** The only real axis of difference is who owns the runtime — Shopify and Builder.io are hosted platforms you build on top of; Plasmic and Makeswift let the component code live in your own repo, which is closer to what agentsam-sdk needs, though the portable core still can't be React-specific (see below).
+
+## Gap check: where our current setup stands
+
+The real gap isn't "we don't have this pattern" — IAM already has most of it. The real gap is that it's owned by IAM, not portable, and not consistently used. That authority split is the actual problem to solve.
+
+| Pattern element | In IAM | In SDK | Notes |
+| --- | --- | --- | --- |
+| Section/block registry + schema | Yes | Partial | `apps/client-cms-editor` now consumes section/block schema catalogs and exposes registry-backed section/block/template UX, but canonical schema authority is still supplied by the host/backend rather than owned as a portable SDK registry |
+| Data-only page composition | Partial | Partial | `apps/client-cms-editor` models and consumes structured Page → Section → Block data; what's still missing is portable authoritative storage, a versioned template/publication manifest, and renderer convergence between editor preview and publish |
+| Auto-generated editor UI | Partial | Partial | `apps/client-cms-editor/frontend/src/CmsEditor.tsx` has a schema-driven `ContentInspector` that reads registry field definitions and renders controls from them, but it still depends on host/backend-supplied schemas rather than an SDK-owned portable registry |
+| Debug/schema metadata isolated from public render | Historical gap | Re-verify | The 2026-09-18 `/work` audit found `route:` / `section:` / `cms:` strings rendering visibly. Treat that as historical evidence to regression-test, not as a claim about the current deployed renderer without a fresh probe. |
+
+**Storage law**, once extracted: D1 holds identity, relationships, ordering, lifecycle, structured state, and artifact pointers. R2 holds media, imported source, generated HTML, and heavy/versioned artifacts. KV holds only current-publication/cache pointers and invalidation — never identity or source of truth.
+
+The honest read: the Dawn zips are raw material (real, tested HTML patterns worth mining for section ideas), not architecture to extend as-is — they predate the schema concept entirely. IAM's CMS core is a different case: the registry/schema authority exists, and the SDK now contains `apps/client-cms-editor` with Page → Section → Block modeling plus schema-driven inspector controls. What's still missing is portable ownership of that authority and renderer convergence. That's the extraction problem, not an invention problem.
+
+## Target blended pattern for agentsam-sdk
+
+What to take from each:
+
+- **From Shopify** — the schema-in-the-definition convention (a section or block ships its own field definitions) and the strict split between layout / template-as-data / section / block. This is the skeleton, and it already exists in IAM's registry — it needs extracting, not inventing.
+- **From Plasmic** — the registration call shape, as a reference for ergonomics only. The portable core can't be React-specific, since the Worker and public runtime must not be forced to ship React just to render a page.
+- **From Makeswift** — the idea of typed "Controls" per field carrying their own validation, options, custom widgets, and conditional behavior — not just a type string. The current `apps/client-cms-editor` inspector already selects controls from schema field definitions; richer validation, options, conditional behavior, and portable control metadata remain the gap.
+- **From Builder.io** — the unified input-type system spanning both components and data models, so the same schema vocabulary describes a section/block's fields and a content model's fields — one type system, not two.
+- **From Webstudio** — the ownership stance: open-source, self-hostable, infrastructure-ownable — the business owns data/components/infrastructure outright. Non-negotiable given the resale plan.
+
+The portable contract is **schema + renderer key/adapters + optional editor-control overrides** — not "React component + schema." A section or block definition is: a versioned schema (fields, types, defaults, motion settings), a renderer key the Worker and public runtime resolve to a deterministic renderer, and optional editor-control overrides for the React-based editor specifically. That's what lets React power the editor without forcing the Worker or public runtime to ship React at all.
+
+AgentSam doesn't need to invent this pattern. The current SDK already has the client CMS editor surface and schema-driven inspection; IAM still owns more of the canonical registry/schema authority. The remaining work is extraction and convergence: move portable authority into shared SDK contracts, bind schemas to deterministic renderer keys/adapters, keep every editor panel schema-driven, and package the result with local and Cloudflare host adapters.
+
+## Sources
+
+- [Shopify theme architecture](https://shopify.dev/docs/storefronts/themes/architecture)
+- [Shopify Dawn reference theme](https://github.com/Shopify/dawn)
+- [Plasmic — registering code components](https://docs.plasmic.app/learn/registering-code-components)
+- [Plasmic — code components API reference](https://docs.plasmic.app/learn/code-components-ref)
+- [Makeswift — registerComponent reference](https://docs.makeswift.com/developer/docs/reference/makeswiftruntime/reactruntime/register-component)
+- [Builder.io — custom component input types](https://www.builder.io/c/docs/input-types)
+- [Webstudio](https://github.com/webstudio-is/webstudio)

package/docs/plans/AGENTSAM-INTERACTIVE-UI-REQUIREMENTS-codex-tui-20260919.md

@@ -0,0 +1,113 @@
+# AgentSam Interactive Shell — UI Requirements
+
+Reference implementation: OpenAI Codex CLI's TUI, observed directly running
+in `~/agentsam-sdk` on 2026-09-19. Codex is not the target — its specific
+*patterns* are. Sam's stated reason for all five, verbatim: "trustworthy.
+never wondering if my machine died/something failed. its present.
+professional." That's the actual spec — every item below exists to answer
+"is this thing still alive and what is it doing" at a glance, continuously,
+without the user asking.
+
+Read this whole file before touching UI code. Each item below is graded
+against the real current state of `src/ui/cli/activity.js`,
+`src/ui/cli/footer.js`, and `src/commands/shell.js` — checked directly, not
+assumed.
+
+## 1. Elapsed-time "Working" indicator — mostly built, missing the interrupt hint
+
+**Current state:** `src/ui/cli/activity.js`'s `createInlineActivity()` already
+renders `◐ Working · 6.2s` with a live-updating spinner + elapsed time via
+`setInterval`. This is the right foundation — reuse it, don't replace it.
+
+**Gap:** Codex's line reads `Working (6s • esc to interrupt)`. Ours has no
+interrupt hint. Add it to the `frame()` render in `activity.js`:
+
+```js
+write(`\r${CLEAR_LINE}  ${icon} ${label} ${pc.dim('· ' + elapsed(now() - startedAt) + ' · esc to interrupt')}`);
+```
+
+Only show the hint when the shell is actually listening for an interrupt
+keypress — don't print a false affordance. Wire the esc handler in
+`shell.js` if one doesn't already exist for the active-task state.
+
+## 2. Shimmer/gradient sweep across the "Working" label
+
+**Current state:** the spinner icon (◐◓◑◒) animates; the label text
+(`Working`) is static plain `pc.cyan`. No gradient.
+
+**Build:** a per-frame brightness/color sweep across the label characters —
+the common technique is picking a moving highlight index into the string
+and rendering characters near it brighter (or a different color) than the
+rest, advancing the index each `frame()` tick alongside the spinner. This
+stays inside `activity.js`'s existing `frame()` function — same timer, same
+interval, just render the label through a small `shimmer(label, tick)`
+helper instead of a flat `pc.cyan(label)`. Keep it subtle — "faint," per
+the ask, not a strobe. Terminal color support varies; fall back to the
+current flat rendering when `process.stdout` doesn't report truecolor/256
+support, don't assume every terminal handles it.
+
+## 3. Persistent status footer — extend, don't rebuild
+
+**Current state:** `renderCliFooter()` in `src/ui/cli/footer.js` already
+renders `model · ctx N% · ↑tokens ↓tokens · [cache] · [tier] · [elapsed]`.
+Solid foundation, wrong field set for this ask.
+
+**Add two fields:**
+- **Project/cwd** — the directory the session is rooted in. Codex shows
+  `directory: ~/agentsam-sdk` in its startup card and keeps it visible.
+  Pass `cwd` (already available everywhere `renderCliFooter` is called
+  from, per `shell.js`'s `state.cwd`) and prepend a shortened form (`~`-
+  collapsed, like Codex does) to the footer parts array.
+- **Current action / connection state** — the live "what is this session
+  doing or waiting on" field, equivalent to Codex's `Log in to Cloudflare
+  API` in its title bar. This needs a piece of session state that gets set
+  whenever the shell is mid-auth-flow, mid-tool-call, or blocked on
+  something external, and cleared back to a neutral state (e.g. "Ready")
+  otherwise. Surface it in the footer render, not just the terminal title
+  bar — the terminal title updates only help if the user is looking at the
+  tab; the footer is always in view.
+
+**Render order matters:** put project and current-action first/most
+prominent since those answer "where am I and is it alive," with the
+existing model/context/token detail after — that ordering matches why this
+whole feature is being asked for.
+
+## 4. Inline diffs on file edits
+
+**Current state:** not checked in depth against `fs_edit_file`/patch
+call sites — flagging as a requirement, not yet scoped. When an
+interactive session edits a file (`fs_edit_file`, `agentsam_github_patch`
+equivalents, or anything routed through the scaffold/CMS write paths),
+show a compact unified diff (red/green line-level) inline in the session
+output, the way Codex renders a diff block immediately after an edit
+tool call. Don't build a separate diff renderer if one already exists
+elsewhere in the SDK (check `src/ui/` and `src/lib/` for an existing
+diff-formatting utility before writing a new one — this is exactly the
+kind of thing that gets silently reinvented).
+
+## 5. Paste-collapse for large pasted input
+
+**Current state:** not present. Pasting a large block into the interactive
+prompt currently shows the raw text inline (or is unhandled — check
+`readline` setup in `shell.js`).
+
+**Build:** detect a paste event (readline's `keypress`/bracketed-paste
+handling, or a heuristic on input arriving faster than typing speed),
+and once pasted content crosses a size threshold, collapse the prompt
+display to `[Pasted Content N chars]` — keeping the full content as the
+actual submitted value, only changing what's rendered in the input line.
+Codex's threshold and exact wording are the reference; match that format
+(`[Pasted Content <n> chars]`) since it's already a pattern the user
+recognizes from daily use.
+
+## Implementation order
+
+1. §1 (interrupt hint) — smallest change, extends existing working code.
+2. §3 (footer fields) — second smallest, same file, no new subsystems.
+3. §5 (paste-collapse) — self-contained in `shell.js`'s input handling.
+4. §2 (shimmer) — cosmetic, do after the functional gaps are closed.
+5. §4 (inline diffs) — needs a scoping pass first (check for an existing
+   diff renderer before writing one); do last.
+
+None of this blocks anything else in the current laundry list — it's a
+parallel track, not a dependency of the auth-closure or scaffold work.

package/docs/plans/AGENTSAM-INTERACTIVE-UI-REQUIREMENTS.md

@@ -0,0 +1,85 @@
+# AgentSam Interactive CLI UI/UX Requirements
+
+**Authority:** `AGENTSAM.md`  
+**Status:** Implemented on `feat/cli-interactive-presence` (PR #56)  
+**Target:** Interactive terminal shell (`agentsam shell` / `src/commands/shell.js`)
+
+---
+
+## 1. Context & Motivation
+
+AgentSam's interactive shell provides a developer-facing agent environment. While core reasoning and tool execution run beneath the surface, the terminal UI must deliver immediate responsiveness, spatial awareness, and non-blocking control comparable to Codex CLI.
+
+Existing primitives (`src/ui/cli/activity.js`, `src/ui/cli/footer.js`) provide the baseline spinner, token counts, and basic footers. This specification establishes the five critical UX behaviors required for a production-grade interactive terminal.
+
+---
+
+## 2. The Five Core UX Patterns
+
+### 2.1 Elapsed Timer with Interrupt Hint
+- **Behavior:** During model generation or tool execution, the inline activity indicator must display a running timer and explicit interrupt guidance.
+- **Display format:**
+  ```text
+  ◐ Working · 6.2s · ctrl-c to cancel
+  ```
+- **Lifecycle:**
+  - Spinner cycles through unicode states (`◐ ◓ ◑ ◒`).
+  - Timer updates at ~100ms intervals.
+  - On SIGINT (`Ctrl+C`), gracefully aborts the in-flight step and preserves session context.
+
+### 2.2 Shimmer / Active State Sweep
+- **Behavior:** The active status label ("Working", "Executing tool", "Synthesizing") undergoes a smooth visual highlight sweep across the text, indicating live background compute.
+- **Rendering details:**
+  - Truecolor ANSI gradient sweep across character indices.
+  - 256-color fallback on restricted terminals.
+  - Complete bypass (static text) when `NO_COLOR` is set in the environment or terminal does not support colors.
+
+### 2.3 Persistent Model, Project, and Connection Status Footer
+- **Behavior:** Printed at shell start and refreshed after commands or state changes to maintain environmental orientation.
+- **Fields:**
+  - **Project identity & root:** Name, directory path.
+  - **Git status:** Current branch, clean/dirty state.
+  - **Active model:** Model identifier, provider, reasoning mode.
+  - **Context window usage:** Input/output tokens, % of context window consumed.
+  - **Shortcuts bar:** Quick reference for `/` commands, `@` file references, `!` shell escapes, and cancellation.
+
+### 2.4 Diff Preview Formatter (`/diff`)
+- **Behavior:** When the user enters `/diff` or asks for review, format git diffs with high-legibility syntax highlighting directly in the terminal stream.
+- **Formatting rules:**
+  - Header lines: bold cyan / dim path metadata.
+  - Hunk headers (`@@ ... @@`): magenta / bold.
+  - Additions (`+`): emerald green.
+  - Deletions (`-`): rose red.
+  - Must strictly honor `NO_COLOR` to avoid corrupting scripted outputs or piped terminals.
+
+### 2.5 Bracketed Paste Collapsing
+- **Behavior:** Pasting large blocks of code, error stack traces, or logs into the prompt must not flood the terminal scrollback or disorient the user.
+- **Threshold:** Input exceeding **5 lines** OR **300 characters**.
+- **Display format:**
+  ```text
+  [Pasted 42 lines (1,840 chars) — Enter to run, Backspace to clear]
+  ```
+- **Keybindings:**
+  - `Enter`: Submit the collapsed payload directly to the model turn.
+  - `Backspace`: Discard the pasted block cleanly without leaving dangling characters.
+  - Normal typing remains un-collapsed.
+
+---
+
+## 3. Implementation Map
+
+| Requirement | Module | Contract / Export |
+|---|---|---|
+| Elapsed timer & interrupt hint | `src/ui/cli/activity.js` | `createInlineActivity({ interruptHint: true })` |
+| Truecolor shimmer sweep | `src/ui/cli/activity.js` | `renderShimmer(text, frame)` |
+| Persistent status footer | `src/ui/cli/footer.js` | `renderCliFooter(state)` |
+| Diff preview renderer | `src/ui/cli/footer.js` | `renderDiffPreview(diffText)` |
+| Bracketed paste collapsing | `src/commands/shell.js` | Paste buffer interceptor in readline loop |
+
+---
+
+## 4. Verification Contract
+
+- `test/cli/runtime-ui.test.mjs`: Validates ANSI formatting, shimmer fallback under `NO_COLOR`, footer fields, and diff coloration.
+- `test/shell.test.mjs`: Validates readline paste collapse and command execution flow.
+- Zero ANSI escape code leakage into non-interactive or file-redirected runs.