@inneranimalmedia/agentsam-sdk 2.6.1 → 2.6.3

package/docs/CLI_SHELL.md

@@ -55,6 +55,8 @@ Current controls include:
 /whoami      authenticated IAM identity + safe credential status
 /session     current cumulative token/cost/resume receipt
 /cf          bounded Cloudflare/Workers operations
+/connections live account / terminal / Worker / Cloudflare connection evidence
+/tunnel      real Cloudflare Tunnel picker backed by Wrangler
 /status      local project / DB / Git / PTY health
 /settings    project/runtime/terminal/model preferences
 /pwd         working directory
@@ -86,7 +88,7 @@ Provider files are machine-local and must not be group/world-readable on POSIX s
 
 `agentsam models` uses the credential internally for safe provider discovery but never returns the secret. Its public status reports only safe facts such as provider, configured state, source class, and provider-verified model availability.
 
-IAM login is also machine-local rather than repository state. A successful browser authentication may persist the `sdk_` bearer under `~/.agentsam/auth/session.json` with restrictive permissions. `agentsam whoami`, deploy, tunnel, and context detection can reuse that validated session. Project `.agentsam/config.json` remains portable and must not become a second identity database.
+IAM login is also machine-local rather than repository state. A successful browser authentication may persist the `sdk_` bearer under `~/.agentsam/auth/session.json` with restrictive permissions. `agentsam whoami`, deploy, and context detection can reuse that validated session. Cloudflare Tunnel management uses Wrangler's own authenticated Cloudflare identity rather than IAM bearer state. Project `.agentsam/config.json` remains portable and must not become a second identity database.
 
 ```bash
 agentsam whoami
@@ -209,7 +211,7 @@ SDK developers can preview rendering experiments from this repository, but those
 
 `agentsam init` owns portable repository/project setup. User identity, provider secrets, session history, execution approvals, and provider continuation state are machine/account runtime state and must not be written into portable project configuration.
 
-Local development does not require a cloud account. Cloud infrastructure is added intentionally.
+Local development does not require a cloud account. Cloud infrastructure is added intentionally. When Cloudflare Tunnel is selected, Agent Sam delegates discovery and lifecycle to Wrangler (`tunnel list`, `info`, `run`, `create`, and `quick-start`) instead of maintaining a parallel named-tunnel implementation.
 
 ## Design rule
 

package/docs/CMS_CONTEXTUAL_COMPOSER.md

@@ -0,0 +1,38 @@
+# CMS Editor — Agent Sam Contextual Composer
+
+24 Sept 2026 · build target for `apps/client-cms-editor` (agentsam-sdk), proven on Fuel & Free Time, then brought into Inner Animal Media.
+
+## Ideal-state packages (FNF = proving ground)
+
+These FNF packages are **examples of the ideal state**, not permanent homes. Each becomes an SDK-packaged prebuild:
+
+| Proving ground (FNF) | SDK target | Role |
+|---|---|---|
+| `packages/agentsam-workbench` | `@inneranimalmedia/agentsam-workbench` | miniAgentSam + contextual composer |
+| `packages/heuristic-theme` | `@inneranimalmedia/heuristic-theme` | **Stock CMS theme preset** |
+| `packages/commerce-analytics` | `@inneranimalmedia/commerce-analytics` | Commerce analytics surfaces |
+
+`agentsam create … --preset cms` should land on **heuristic-theme** as the basic stock theme.
+
+## Interaction loop (required)
+
+1. **Select** an object on the live canvas.
+2. **Ask** (or agent proactively offers) — right panel scopes to selection.
+3. **Suggest** — one primary suggestion card (action title + rationale + chevron), not a chat wall.
+4. **Accept** (card click) → generation starts (no extra confirm).
+5. **Generate** — polished gradient overlay on canvas + contained monospace code stream with soft gradient veil (trust/transparency, not approval UI). Phases: Reading selection → Drafting markup → Writing styles → Wiring settings.
+6. **Land** — gradient cross-fades to real block; left inspector flashes updated fields; composer posts confirmation.
+
+Left panel is always a real layers tree + property inspector (text, layout, typography preset, appearance, padding, remove) bound to the **same** block model the agent edits.
+
+## Implementation
+
+- Primitives: `packages/agentsam-workbench/src/agent/ContextualComposer.tsx` (+ CSS)
+- Host wiring: `apps/client-cms-editor/frontend/src/CmsAgentSurface.tsx` with `contextual`
+- Threads persist per page/site via `localStorage` (survive redock/resize — portable agent)
+
+## Open decisions (from spec)
+
+- Generation preview dock: default **inside right composer**; canvas keeps the gradient overlay.
+- Threads: persisted per project key; scoped optionally to selection without discarding other threads.
+- Pipeline: host-owned `planSuggestion` / `runGeneration` (AgentSam runtime / MCP) — demos ship with local stubs.

package/docs/MERKLE.md

@@ -68,3 +68,7 @@ const comparison = diffTrees(baseline, current);
 ```
 
 The library is local filesystem tooling. It adds no Worker bindings, user/workspace identity, or network calls. The interoperable content hash format is specified in [MERKLE_V1](../protocol/MERKLE_V1.md), and semantic identity in [FILEMETA_V1](../protocol/FILEMETA_V1.md).
+
+## AutoRAG use
+
+AutoRAG consumes this package's content root and optional semantic metadata root as source evidence. During a code plan it compares those roots with the previous generation, reports changed paths, and reuses unchanged parsed chunks/vectors where their content identity still matches. Merkle is deterministic filesystem evidence; it is not a dependency graph, an AST graph, a vector index, or a replacement for Git history.

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/SDK_WORKER.md

@@ -47,16 +47,17 @@ agentsam-sdk
 ├─ AGENTSAM_WAI        -> Workers AI provider
 ├─ EXECOS              -> execos service binding
 ├─ PTY_SERVICE         -> iam-vpc VPC service
-├─ IAM_ORIGIN          -> https://inneranimalmedia.com
+├─ IAM_OAUTH_ISSUER    -> https://inneranimalmedia.com
+├─ IAM_ORIGIN          -> migration fallback
 ├─ IAM_CLIENT_ID       -> public OAuth client id
 ├─ IAM_CLIENT_SECRET   -> secret
-├─ AGENTSAM_SDK_KEY    -> secret
+├─ AGENTSAM_API_KEY    -> aak_ account credential (only when a reusable account credential is needed)
 └─ AGENTSAM_BRIDGE_KEY -> secret
 ```
 
 Hosted model credentials are secrets: `XAI_API_KEY`, `OPENAI_API_KEY`, and `GEMINI_API_KEY`. Grok model inference is the `XAI_API_KEY` provider lane and is independent from the pre-wired Grok gate viewer identity/session system.
 
-`AGENTSAM_WORKER_ROLE` is not part of the SDK contract. `IAM_OAUTH_ISSUER` and `AGENTSAM_SDK_TOKEN` are SDK 2.5 migration-read aliases only; new configuration uses `IAM_ORIGIN` and `AGENTSAM_SDK_KEY`.
+`AGENTSAM_WORKER_ROLE` is not part of the SDK contract. `IAM_OAUTH_ISSUER` is the canonical IAM authority; `IAM_ORIGIN` is a migration fallback. Reusable account API credentials use `AGENTSAM_API_KEY` with an `aak_` prefix. Browser login sessions and machine/infrastructure credentials remain separate and must not be promoted into account API keys.
 
 ## Ollama
 

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)