@inneranimalmedia/agentsam-sdk 2.6.3 → 2.6.5

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/brand/AGENT_SAM_ICON_GRAMMAR.md

@@ -0,0 +1,70 @@
+# AgentSam icon & motion grammar
+
+Family system for product marks and UI glyphs. Static identity stays quiet and architectural; runtime motion (Computational Hyperspace) is spectral and dimensional — not the icon itself.
+
+## Brand hierarchy
+
+```text
+AgentSam                         master brand
+├── Local Studio                 product identity
+├── CAD Creator                  product identity
+├── Ecommerce                    product identity
+├── CLI                          surface identity
+└── future apps
+```
+
+Related without sharing the exact same icon. One recognizable **master silhouette** (abstract SAM core / aperture / dimensional mark — readable at 16–24 px). Each product adds a single cue:
+
+| Product | Cue on master geometry |
+|---|---|
+| Local Studio | workspace / portal |
+| CAD Creator | dimensional plane / cube |
+| Ecommerce | modular product-card |
+
+## Icon grammar
+
+| Attribute | Rule |
+|---|---|
+| Base | graphite / near-black dimensional surface |
+| Accent | spectral blue → violet; amber only for special active states |
+| Geometry | rounded, slightly architectural |
+| Detail | one dominant shape, max 2–3 secondary forms |
+| Text | never in the app icon |
+| Lighting | restrained edge/highlight — not glossy clip-art |
+| Small sizes | simplify rather than shrink detail |
+| Status icons | separate semantic system from product logos |
+| Motion | slow depth/parallax; no bouncing/spinning clutter |
+
+## Asset drop paths (desktop shell)
+
+| Asset | Path |
+|---|---|
+| App / Dock / tray PNG (prefer **1024×1024**) | `packages/agentsam-desktop-shell/icons/<app_id>/icon.png` |
+| Vector mark | `packages/agentsam-desktop-shell/icons/<app_id>/*.svg` |
+| Manifest | `packages/agentsam-desktop-shell/manifests/<app_id>.json` → `icon_set`, `icon_mark_svg` |
+
+Build: `cd packages/agentsam-desktop-shell && npm run build:brand -- local-studio`  
+Optional: `AGENTSAM_ICON_URL=https://…/logo.png` overrides local files.
+
+`build-brand.mjs` must honor `icon_mark_svg` when `icon.png` is missing (rasterize → `src-tauri/icons/`).
+
+## UI glyphs (not product logos)
+
+One semantic layer — design system picks the glyph family:
+
+```jsx
+<Icon name="workspace" />
+<Icon name="terminal" />
+<Icon name="activity" />
+<Icon name="repository" />
+<Icon name="warning" />
+```
+
+Do not mix Heroicons / Lucide / random SVGs / macOS symbols as the AgentSam brand identity. Platform-native symbols OK only for OS chrome.
+
+## Identity vs motion
+
+- **Static identity:** quiet / recognizable / architectural  
+- **Runtime motion:** spectral / dimensional / computational (Hyperspace)
+
+See also: `docs/plans/LOCAL-STUDIO-GRADUATION-2026-09-26.md`.

package/docs/content-studio/HOST_MOUNT_CHECKLIST.md

@@ -0,0 +1,71 @@
+# Host mount checklist — Content Studio (Path A / Commit 6)
+
+Portable packages are ready for host adapters. Full OAuth / production mounts
+are Path B / host-app work — do **not** fork packages per host.
+
+## Shared mount contract
+
+Each host supplies a `ContentRuntime` via `createContentRuntime({...})`:
+
+| Seam | Local Studio | IAM dashboard | Fuel & Free Time (customer) |
+|---|---|---|---|
+| `account` / `actor` | desktop session | IAM auth session | customer tenant session |
+| `providers` / capability adapters | local + optional CF | R2 / Images / Drive / Stream | customer-scoped providers |
+| `brandResolver` | project BrandPack projection | org BrandPack projection | customer BrandPack projection |
+| `knowledge` | local / injected | host Vectorize/AutoRAG/pgvector | customer knowledge adapter |
+| `localHost` | Tauri / agentsamd bridge | usually `unavailable` | usually `unavailable` |
+| `routes` / `permissions` | desktop RouteMap | IAM RouteMap | customer RouteMap |
+| UI | `<ContentStudio runtime={rt} />` | same | same |
+
+## Do
+
+1. Build runtime in the **host** app (not inside `agentsam-content-studio`).
+2. Derive UI tabs/actions from `await runtime.capabilities()`.
+3. Keep BrandPack authority in `agentsam-brand` / `brand.pack.json`.
+4. Use `inferBrandAssociation` only as proposals + ScoreCard evidence.
+5. Use `@inneranimalmedia/agentsam-cloudflare-images` for CF Images HTTP.
+
+## Don't
+
+- Import Tauri / raw `fs` / agentsamd into reusable UI packages.
+- Hardcode R2 / Images / Drive / Vectorize tabs in Content Studio.
+- Embed real customer BrandPack fixtures in generic packages.
+- Seed fictional `DEMO_BRAND_PROJECTIONS` into production `/content` runtimes.
+- Run IAM `deploy:full` from this SDK repo for content-studio work.
+
+## Local Studio mount (wired)
+
+- Route: `/content` → `ContentStudioPage` mounts `<ContentStudio runtime={…} />`
+- Runtime factory: `apps/local-studio/frontend/src/lib/content/createLocalStudioContentRuntime.ts`
+- **Identity:** resolved from `useCurrentUserState()` / Auth session — fail closed when missing.
+  No `acct_local_studio` / `local-studio-user` production defaults.
+- **Brand:** empty `ContentBrandResolver` projections until host injects BrandPack (Path B).
+  Fictional demos live only in `demoBrandProjections.ts` (tests/examples).
+- **LocalContentHost (desktop):** native Rust Tauri `local_content_bridge` —
+  `rfd` pickers, opaque `localref_*` / `localdir_*`, granted roots, browse in place,
+  copy only on `import_to_library`. **Does not require** monorepo Node or global Node.
+- **LocalContentHost (browser/dev):** File System Access API when available; else
+  explicit browser-import (`import_bytes`, 32 MiB) via Node `/api/content/local/bridge`.
+- Knowledge / BrandSimilarity: noop adapters (no Vectorize hardcode)
+- agentsamd: probed via Tauri `ensure_agentsamd` / health; FS ops are native Rust until
+  agentsamd ships native `/v1/fs` (documented migration target)
+
+## Packaged-app contract
+
+| Requirement | Status |
+|---|---|
+| Works from `/Applications` without repo checkout | Native Rust FS — yes |
+| No global Node for content FS | Desktop native — yes; Node bridge is browser/dev only |
+| Native Open File / Open Folder | `rfd` via `pick_files` / `pick_directory` |
+| Selected file not copied until import | Yes — `import_to_library` is separate |
+| Opaque refs only to UI/models | Yes — absolute paths stay in Rust/grant store |
+
+## Remaining for true 3-host E2E (Path B)
+
+- agentsamd native `/v1/fs` + watch (migration from native Rust bridge)
+- IAM dashboard route + OAuth-scoped providers
+- F&F admin mount with customer account scope
+- Production BrandPack projection into Local Studio `brandResolver`
+- Harvest Go pipeline → SiteGraph / TokenGraph → package-readiness ScoreCards
+- Brand package migration onto shared CF Images transport (content already uses it)
+- Beta / outcome calibration receipts for accept/reject (does not mutate evidence)