@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

package/docs/architecture/previews/codebaseindex-guided-path/CODEBASEINDEX_GUIDED_PATH.md

@@ -0,0 +1,202 @@
+# Codebaseindex Guided Path — Template Lanes + Inventory-First UX
+
+**Status:** PLAN · LOCKED intent (2026-09-25)  
+**Product:** AgentSam · pipeline `sam.codebaseindex.index.run` · operation `codebaseindex.ingest`  
+**Audience:** SDK CLI/TUI, Local Studio, future customer “bring your own vector lane” templates
+
+---
+
+## 1. Host SSOT today — Supabase tables (Gemini @ 1536)
+
+Owner IAM path: **Gemini Embedding 2 → 1536-d → Supabase pgvector**, written via **node-api** edge (`POST /codebase/ingest`, vector RPCs). D1 owns control/structure; Postgres owns vectors.
+
+### Live code-intelligence projections (`agentsam` schema)
+
+| Table | Role |
+|-------|------|
+| `agentsam.agentsam_codebase_chunks_gemini_embedding_2_1536` | Chunk-level retrieval vectors (primary ANN for code Q&A) |
+| `agentsam.agentsam_codebase_files_gemini_embedding_2_1536` | File-level vectors |
+| `agentsam.agentsam_codebase_ast_symbols_gemini_embedding_2_1536` | Symbol ANN |
+
+### Related semantic / twin tables (same embed family, different corpora)
+
+| Table | Role |
+|-------|------|
+| `agentsam.agentsam_gemini_semantic_embeddings_1536` | Unified semantic authority (memory + code symbol projections by `corpus_type` / `record_kind`) |
+| `agentsam.agentsam_documents_gemini_embedding_2_1536` | Document ingest twin (node-api `/vectors/ingest`) |
+
+### Retired (do not write for new runs)
+
+| Table | Note |
+|-------|------|
+| `agentsam.agentsam_codebase_*_oai3large_1536` | Legacy OpenAI code lanes |
+
+### Control plane (D1 — not Supabase, but paired)
+
+| Table | Role |
+|-------|------|
+| `code_repositories` | Account-owned repo identity |
+| `agentsam_code_index_job` / `agentsam_code_index_job_file` | Run progress (`cidxrun_*`) |
+| `codebase_ast_nodes` / `codebase_dep_edges` | Structural units + deps |
+| `agentsam_pgvector_lane_registry` | Purpose → live PG table + model + dims |
+| `agentsam_fs_merkle_snapshots` | Merkle evidence receipts |
+| `agentsam_codebase_index_health` | Staleness / weekly health |
+
+**I/O path (owner):** Worker / SDK → **node-api** (Deno edge) → Hyperdrive / session pooler → Supabase PG.
+
+---
+
+## 2. End goal — templateable vector lanes
+
+Owner setup is already live. Customers should get the **same harness**, parameterized:
+
+```text
+                    codebaseindex.ingest (guided)
+                              │
+              ┌───────────────┼───────────────┐
+              ▼               ▼               ▼
+         local_exact     supabase_pgvector   cloudflare_vectorize
+         (SQLite)        (+ node-api edge)   (CF binding)
+              │               │               │
+         Ollama/paid     Gemini@1536     project Vectorize
+         on this machine  BYO Supabase    BYO index/model
+```
+
+| Lane | Who runs compute | Where vectors live | When to offer |
+|------|------------------|--------------------|---------------|
+| **Local** | User machine | `.agentsam/knowledge/index.sqlite` | Default; Ollama free embed OK |
+| **Supabase + node-api** | Their edge (template of IAM node-api) | Their `agentsam.*` PG tables | They opt into hosted ANN |
+| **CF Vectorize** | Worker/plugin binding | Their Vectorize index | They already live on CF |
+
+**Template rule:** ship **contracts + migrations + edge stubs**, not a shared multi-tenant dump of IAM tables into customer projects. Owner IAM remains the reference implementation.
+
+Same-model law still holds per generation: vectors written with profile `P` are only queried with profile `P` (fingerprint of provider/model/dims/params).
+
+---
+
+## 3. Guided path (inventory first — LOCK this UX)
+
+One option at a time. Plan/dry-run is **not** “skip inventory.”
+
+```text
+① Provider / connection
+        ↓
+② Scan → file map inventory (Merkle + facet view)
+        ↓
+③ Include / exclude against the map
+        ▼
+④ Embedding model + dimensions (discovered, not hardcoded)
+        ↓
+⑤ Vector lane / data source
+   · local SQLite
+   · Supabase + node-api (Hyperdrive)
+   · Cloudflare Vectorize
+        ↓
+⑥ Dry-run / plan receipt (work-graph stages)
+        ↓
+⑦ Confirm → run (progress on Gantt + CLI)
+```
+
+### CLI / TUI (lightweight)
+
+| Step | Interaction |
+|------|-------------|
+| ① | `select` configured providers + optional `agentsam providers` deep-link; Ollama online badge from `ollama list` |
+| ② | Run `repository.inspect` / Merkle; print compact tree + counts; `--json` for Studio |
+| ③ | `text` include / exclude; optional local chat assist; never invent denylist |
+| ④ | `select` from **discovered** embed models only |
+| ⑤ | `select` lane; if Supabase → collect URL/env names + offer node-api scaffold; if Vectorize → binding/index |
+| ⑥ | `plan` emits work-graph JSON + pretty plan card |
+| ⑦ | `confirm` then run; stream stage events |
+
+Terminal aesthetic: short notes, one clack prompt per step, `tip: use skill agentsam-codebaseindex`, no wall of presets.
+
+### Studio / localhost Gantt
+
+Work-graph is the **source of truth** for the job; Gantt/timeline are projections.
+
+Example stages (bars):
+
+1. `connect` — providers resolved  
+2. `inventory` — file map / merkle  
+3. `scope` — include/exclude locked  
+4. `embed_profile` — model + dims  
+5. `lane` — local | supabase | vectorize  
+6. `plan` — dry-run receipt  
+7. `index` — parse / chunk / embed  
+8. `activate` — verify + ready  
+
+Local Studio (or this preview) polls `agentsam_code_index_job` / local generation receipts and feeds `createGanttModel(graph)`.
+
+---
+
+## 4. Supabase + node-api customer path (what “template” means)
+
+When the user picks **Supabase / Hyperdrive**:
+
+1. Scaffold edge from IAM `supabase/functions/node-api` **pattern** (ingest + account-scoped vector query RPCs).  
+2. Apply PG migrations that create **their** `agentsam.agentsam_codebase_*` (or lane-registry–driven table names).  
+3. Wire `AGENTSAM_DATABASE_URL` / Hyperdrive binding names into knowledge `lane.backend = supabase_pgvector`.  
+4. Register row in **their** `agentsam_pgvector_lane_registry` (or SDK lane config) pointing at table + model + dims.  
+5. Runs still use `codebaseindex.ingest` / `sam.codebaseindex.index.run` — only the **provider adapter** changes.
+
+Owner machine: skip scaffold; credentials and node-api already exist → wizard jumps to inventory.
+
+---
+
+## 5. CF Vectorize path (valid peer, not code-index SSOT for IAM)
+
+IAM host law keeps **code index vectors off Vectorize**. Customer template may still choose Vectorize for **their** product:
+
+- Plugin scope: binding + index + model + dims  
+- Knowledge `lane.backend = cloudflare_vectorize`  
+- Same guided steps ①–⑦; stage `lane` records Vectorize target in the receipt  
+
+Do not silently redirect owner IAM full-index onto Vectorize.
+
+---
+
+## 6. Local Ollama value (strategic I/O)
+
+| Use | How |
+|-----|-----|
+| Free semantic search | `agentsam search --semantic` against local generation |
+| Pre-filter before paid chat | Retrieve top-k chunks → pass only those to hosted model |
+| Offline agent turns | Shell/agent retrieve while Ollama is up |
+| Scope assist | Chat model (e.g. `qwen2.5-coder`) suggests include/exclude only |
+
+Query must use **same** embed profile as write (e.g. `mxbai-embed-large:latest` @ 1024).
+
+---
+
+## 7. Implementation slices (ordered)
+
+| Slice | Deliverable |
+|-------|-------------|
+| **A** | Reframe CLI wizard to ①→⑦ (inventory before scope); `plan` prints work-graph stages |
+| **B** | Emit `codebaseindex.job.graph.v1` JSON consumed by work-graph Gantt |
+| **C** | Local Studio / preview page binding graph → Gantt (this doc’s companion HTML) |
+| **D** | Lane picker adapters: local (done-ish), supabase+node-api scaffold stub, vectorize scope probe |
+| **E** | Customer template pack: migrations + edge stub + README (no IAM secrets) |
+
+---
+
+## 8. Acceptance checks
+
+- [ ] Wizard never jumps to embed/lane before an inventory receipt exists (or user explicitly skips with `--skip-inventory`).  
+- [ ] Exclude is user-authored (blank = none).  
+- [ ] Embed options come only from credentials + live Ollama tags.  
+- [ ] Plan/dry-run produces work-graph JSON + human card.  
+- [ ] Gantt shows the same stage ids as CLI.  
+- [ ] Choosing Supabase does not mutate owner IAM tables when running as a customer template.  
+- [ ] Semantic retrieve fails closed on embedding-profile mismatch.
+
+---
+
+## Related
+
+- Host SSOT: `inneranimalmedia/docs/platform/codebase-index-ssot-2026-07.md`  
+- SAM kernel: `docs/architecture/SAM_KERNEL.md`  
+- Skill: `skills/agentsam-codebaseindex/SKILL.md`  
+- Work-graph: `packages/work-graph` (`createGanttModel`)  
+- Preview: `docs/architecture/previews/codebaseindex-guided-path/`

package/docs/architecture/previews/codebaseindex-guided-path/index.html

@@ -0,0 +1,321 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Codebaseindex Guided Path — Preview</title>
+  <style>
+    :root {
+      color-scheme: light;
+      --bg: #f4f1ea;
+      --ink: #1a1c1e;
+      --muted: #5c6370;
+      --panel: #fffcf7;
+      --line: #d8d0c4;
+      --accent: #2f6f4e;
+      --accent-2: #b45309;
+      --bar: #3d7a5a;
+      --bar-done: #2f6f4e;
+      --bar-run: #c27803;
+      --bar-wait: #9aa3af;
+      --mono: "IBM Plex Mono", ui-monospace, Menlo, monospace;
+      --sans: "Source Sans 3", "Segoe UI", system-ui, sans-serif;
+      --display: "Fraunces", Georgia, serif;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      font: 16px/1.5 var(--sans);
+      color: var(--ink);
+      background:
+        radial-gradient(1200px 600px at 10% -10%, #e8efe8 0%, transparent 55%),
+        radial-gradient(900px 500px at 100% 0%, #f3e6d4 0%, transparent 50%),
+        var(--bg);
+    }
+    main { max-width: 1080px; margin: 0 auto; padding: 40px 24px 80px; }
+    h1 {
+      font-family: var(--display);
+      font-weight: 550;
+      font-size: clamp(1.8rem, 3vw, 2.4rem);
+      margin: 0 0 8px;
+      letter-spacing: -0.02em;
+    }
+    .sub { color: var(--muted); margin: 0 0 28px; max-width: 62ch; }
+    .pill {
+      display: inline-block;
+      font: 12px/1 var(--mono);
+      padding: 5px 9px;
+      border: 1px solid var(--line);
+      border-radius: 999px;
+      margin-right: 6px;
+      background: var(--panel);
+    }
+    section {
+      background: var(--panel);
+      border: 1px solid var(--line);
+      border-radius: 4px;
+      padding: 20px 22px;
+      margin: 0 0 18px;
+    }
+    section h2 {
+      margin: 0 0 12px;
+      font-size: 0.95rem;
+      text-transform: uppercase;
+      letter-spacing: 0.06em;
+      color: var(--muted);
+      font-weight: 650;
+    }
+    ol.steps {
+      list-style: none;
+      margin: 0;
+      padding: 0;
+      display: grid;
+      gap: 8px;
+    }
+    ol.steps li {
+      display: grid;
+      grid-template-columns: 36px 1fr;
+      gap: 12px;
+      align-items: start;
+      padding: 10px 12px;
+      border: 1px solid transparent;
+      border-radius: 4px;
+    }
+    ol.steps li.active {
+      border-color: var(--accent);
+      background: #eef6f1;
+    }
+    ol.steps .n {
+      font: 700 14px/36px var(--mono);
+      width: 36px; height: 36px;
+      text-align: center;
+      border-radius: 50%;
+      background: #e7ece7;
+      color: var(--accent);
+    }
+    ol.steps li.active .n { background: var(--accent); color: #fff; }
+    ol.steps strong { display: block; }
+    ol.steps span { color: var(--muted); font-size: 0.92rem; }
+    table { width: 100%; border-collapse: collapse; font-size: 0.92rem; }
+    th, td { text-align: left; padding: 8px 10px; border-bottom: 1px solid var(--line); vertical-align: top; }
+    th { color: var(--muted); font-weight: 600; font-size: 0.78rem; text-transform: uppercase; letter-spacing: 0.04em; }
+    code { font-family: var(--mono); font-size: 0.84em; }
+    .lanes {
+      display: grid;
+      grid-template-columns: repeat(3, 1fr);
+      gap: 12px;
+    }
+    @media (max-width: 800px) { .lanes { grid-template-columns: 1fr; } }
+    .lane {
+      border: 1px solid var(--line);
+      border-radius: 4px;
+      padding: 14px;
+      min-height: 140px;
+    }
+    .lane h3 { margin: 0 0 6px; font-size: 1rem; }
+    .lane p { margin: 0; color: var(--muted); font-size: 0.9rem; }
+    .lane.pick { outline: 2px solid var(--accent); background: #f3faf6; }
+    .gantt { display: grid; gap: 8px; margin-top: 8px; }
+    .gantt-row {
+      display: grid;
+      grid-template-columns: 140px 1fr 72px;
+      gap: 10px;
+      align-items: center;
+    }
+    .gantt-row .label { font: 12px/1.2 var(--mono); }
+    .track {
+      height: 18px;
+      background: #ece7df;
+      border-radius: 3px;
+      position: relative;
+      overflow: hidden;
+    }
+    .bar {
+      position: absolute;
+      top: 0; bottom: 0;
+      border-radius: 3px;
+      background: var(--bar-wait);
+    }
+    .bar.done { background: var(--bar-done); }
+    .bar.run { background: var(--bar-run); }
+    .bar.wait { background: var(--bar-wait); opacity: 0.55; }
+    .status { font: 11px/1 var(--mono); color: var(--muted); text-align: right; }
+    .cli {
+      font: 13px/1.55 var(--mono);
+      background: #1b1f24;
+      color: #d7e0ea;
+      padding: 14px 16px;
+      border-radius: 4px;
+      white-space: pre-wrap;
+    }
+    .cli .dim { color: #8b95a5; }
+    .cli .ok { color: #6dcea2; }
+    .cli .tip { color: #e0b35a; }
+    a.doc { color: var(--accent); }
+    .actions { display: flex; gap: 8px; flex-wrap: wrap; margin-top: 10px; }
+    button {
+      font: 13px/1 var(--sans);
+      padding: 9px 12px;
+      border: 1px solid var(--line);
+      background: #fff;
+      border-radius: 4px;
+      cursor: pointer;
+    }
+    button.primary { background: var(--accent); color: #fff; border-color: var(--accent); }
+  </style>
+</head>
+<body>
+  <main>
+    <p>
+      <span class="pill">plan preview</span>
+      <span class="pill">sam.codebaseindex.index.run</span>
+      <span class="pill">codebaseindex.ingest</span>
+    </p>
+    <h1>Codebaseindex guided path</h1>
+    <p class="sub">
+      Inventory first, then scope, then vector lane. Owner IAM already runs Gemini@1536 → Supabase via node-api;
+      customers get the same harness as a template (local · Supabase+edge · CF Vectorize).
+      Spec:
+      <a class="doc" href="./CODEBASEINDEX_GUIDED_PATH.md">CODEBASEINDEX_GUIDED_PATH.md</a>
+    </p>
+
+    <section>
+      <h2>Wizard · one option at a time</h2>
+      <ol class="steps" id="steps"></ol>
+      <div class="actions">
+        <button type="button" id="prev">Back</button>
+        <button type="button" class="primary" id="next">Next step</button>
+        <button type="button" id="reset">Reset</button>
+      </div>
+    </section>
+
+    <section>
+      <h2>Vector lane choices</h2>
+      <div class="lanes">
+        <div class="lane" data-lane="local">
+          <h3>Local SQLite</h3>
+          <p>Ollama / paid embed on this machine. Free semantic search offline. Default for SDK.</p>
+        </div>
+        <div class="lane" data-lane="supabase">
+          <h3>Supabase + node-api</h3>
+          <p>BYO edge (IAM node-api template) → Hyperdrive/PG. Host SSOT pattern for Gemini@1536.</p>
+        </div>
+        <div class="lane" data-lane="vectorize">
+          <h3>CF Vectorize</h3>
+          <p>Valid customer lane via binding/index. Not IAM host code-index SSOT.</p>
+        </div>
+      </div>
+    </section>
+
+    <section>
+      <h2>Job Gantt · work-graph projection</h2>
+      <p class="sub" style="margin-bottom:12px">Same stage ids the CLI should emit in <code>codebaseindex.job.graph.v1</code>.</p>
+      <div class="gantt" id="gantt"></div>
+    </section>
+
+    <section>
+      <h2>Supabase tables (host code index)</h2>
+      <table>
+        <thead><tr><th>Table</th><th>Role</th></tr></thead>
+        <tbody>
+          <tr><td><code>agentsam.agentsam_codebase_chunks_gemini_embedding_2_1536</code></td><td>Chunk ANN</td></tr>
+          <tr><td><code>agentsam.agentsam_codebase_files_gemini_embedding_2_1536</code></td><td>File vectors</td></tr>
+          <tr><td><code>agentsam.agentsam_codebase_ast_symbols_gemini_embedding_2_1536</code></td><td>Symbol ANN</td></tr>
+          <tr><td><code>agentsam.agentsam_gemini_semantic_embeddings_1536</code></td><td>Unified semantic authority</td></tr>
+          <tr><td><code>agentsam.agentsam_documents_gemini_embedding_2_1536</code></td><td>Documents twin</td></tr>
+        </tbody>
+      </table>
+    </section>
+
+    <section>
+      <h2>CLI/TUI sketch</h2>
+      <div class="cli" id="cli"></div>
+    </section>
+  </main>
+  <script type="module">
+    const STEPS = [
+      { id: 'connect', title: 'Provider / connection', detail: 'Discover credentials + Ollama. Owner skips scaffold.' },
+      { id: 'inventory', title: 'Scan → file map', detail: 'repository.inspect / Merkle inventory before any exclude.' },
+      { id: 'scope', title: 'Include / exclude', detail: 'User-authored paths; optional local chat assist.' },
+      { id: 'embed', title: 'Model + dimensions', detail: 'Discovered only — e.g. mxbai-embed-large:latest @ 1024.' },
+      { id: 'lane', title: 'Vector data source', detail: 'local · supabase+node-api · cloudflare_vectorize' },
+      { id: 'plan', title: 'Dry-run / plan', detail: 'Work-graph receipt — not a silent jump to write.' },
+      { id: 'run', title: 'Confirm → run', detail: 'Progress events feed this Gantt + terminal.' },
+    ];
+
+    const GANTT = [
+      { id: 'connect', start: 0, end: 10, status: 'done' },
+      { id: 'inventory', start: 10, end: 28, status: 'done' },
+      { id: 'scope', start: 28, end: 40, status: 'done' },
+      { id: 'embed_profile', start: 40, end: 48, status: 'run' },
+      { id: 'lane', start: 48, end: 58, status: 'wait' },
+      { id: 'plan', start: 58, end: 70, status: 'wait' },
+      { id: 'index', start: 70, end: 92, status: 'wait' },
+      { id: 'activate', start: 92, end: 100, status: 'wait' },
+    ];
+
+    let step = 1;
+    let lane = 'local';
+
+    const stepsEl = document.getElementById('steps');
+    const ganttEl = document.getElementById('gantt');
+    const cliEl = document.getElementById('cli');
+
+    function renderSteps() {
+      stepsEl.innerHTML = STEPS.map((s, i) => `
+        <li class="${i === step ? 'active' : ''}">
+          <div class="n">${i + 1}</div>
+          <div><strong>${s.title}</strong><span>${s.detail}</span></div>
+        </li>`).join('');
+    }
+
+    function renderGantt() {
+      ganttEl.innerHTML = GANTT.map((row) => `
+        <div class="gantt-row">
+          <div class="label">${row.id}</div>
+          <div class="track"><div class="bar ${row.status}" style="left:${row.start}%;width:${row.end - row.start}%"></div></div>
+          <div class="status">${row.status}</div>
+        </div>`).join('');
+    }
+
+    function renderCli() {
+      const s = STEPS[step];
+      cliEl.innerHTML = [
+        `<span class="dim">agentsam codebaseindex</span>`,
+        `<span class="tip">tip: use skill agentsam-codebaseindex</span>`,
+        ``,
+        `<span class="ok">✓</span> step ${step + 1}/${STEPS.length} · ${s.id}`,
+        `  ${s.title}`,
+        `  lane preference: <span class="ok">${lane}</span>`,
+        ``,
+        step === 1 ? `  inventory: merkle_root=ab12… files=482 facets ready` : `  <span class="dim">(advance to see inventory framing)</span>`,
+        step >= 4 ? `  embed: discovered ollama|mxbai-embed-large:latest|1024` : '',
+        step >= 5 ? `  data source → ${lane === 'supabase' ? 'node-api → agentsam.agentsam_codebase_chunks_…' : lane}` : '',
+        step >= 6 ? `  plan receipt → codebaseindex.job.graph.v1` : '',
+      ].filter(Boolean).join('\n');
+    }
+
+    function renderLanes() {
+      document.querySelectorAll('.lane').forEach((el) => {
+        el.classList.toggle('pick', el.dataset.lane === lane);
+      });
+    }
+
+    function paint() {
+      renderSteps();
+      renderGantt();
+      renderCli();
+      renderLanes();
+    }
+
+    document.getElementById('next').onclick = () => { step = Math.min(STEPS.length - 1, step + 1); paint(); };
+    document.getElementById('prev').onclick = () => { step = Math.max(0, step - 1); paint(); };
+    document.getElementById('reset').onclick = () => { step = 0; lane = 'local'; paint(); };
+    document.querySelectorAll('.lane').forEach((el) => {
+      el.addEventListener('click', () => { lane = el.dataset.lane; paint(); });
+    });
+
+    paint();
+  </script>
+</body>
+</html>

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)