@tangle-network/create-agent-app 0.44.36

package/template/agent.config.ts

@@ -0,0 +1,113 @@
+/**
+ * agent.config.ts — the DATA surface of this agent product.
+ *
+ * This is the ONE file you fill to define who the agent is, what it may propose,
+ * what knowledge gates its loop, and which integrations it connects. It is plain
+ * data consumed by `@tangle-network/agent-app`'s modules through typed seams —
+ * NOT behavior. Do not put control flow here; that lives in `src/` (the chat
+ * route + composer). See CUSTOMIZE.md for the ordered fill-checklist and AGENTS.md
+ * for the layering contract.
+ *
+ * Every field below is stubbed with a placeholder. Replace the placeholders; keep
+ * the shape. `pnpm typecheck` proves the shape; `pnpm test` proves the wiring.
+ */
+
+import { defineAgentApp } from '@tangle-network/agent-app/config'
+
+export const config = defineAgentApp({
+  // ① IDENTITY — who is the agent? (Discovery: "Whose job does this do, in whose
+  //    voice, under what hard rules?")
+  identity: {
+    name: '__PROJECT_NAME__',
+    persona:
+      'You are an operations partner for <DOMAIN>. You automate the standing ' +
+      'workflows, stay grounded in real records, and route every regulated or ' +
+      'client-facing step to a named human for approval. Replace this paragraph ' +
+      'with the real persona — it is the spine of the system prompt.',
+    // Standing workflows, hard rules, tone — appended verbatim after the persona.
+    systemPromptFragments: [
+      'Never fabricate a figure (price, coverage, identifier, regulatory clause). ' +
+        'Cite a real record or say NOT ON FILE.',
+    ],
+    // Named disclaimers the UI / chat pipeline can select by id.
+    disclaimers: {
+      'not-advice':
+        'This assistant prepares proposals for a licensed human to review and ' +
+        'approve. It does not itself give regulated advice or take regulated action.',
+    },
+  },
+
+  // ② TAXONOMY — what can the agent PROPOSE, and which proposals are regulated?
+  //    (Discovery: "Which actions change client state or are legally gated, so a
+  //    certified human must approve before they execute?")
+  //    `regulatedTypes` MUST be a subset of `proposalTypes`. Regulated proposals
+  //    CANNOT execute without a named certified approver — this is the
+  //    human-in-the-loop invariant. Keep regulated steps regulated.
+  taxonomy: {
+    proposalTypes: ['recommend', 'contact', 'escalate'],
+    regulatedTypes: ['escalate'],
+  },
+
+  // ③ KNOWLEDGE — what must the agent KNOW before it acts, and where does it learn?
+  //    (Discovery: "What facts gate the loop — what's the minimum the agent must
+  //    have grounded before it's allowed to propose?")
+  //    `requirements` are declarative gates scored from workspace state by the
+  //    Cloudflare preset's KnowledgeStateAccessor (config-set or rows-exist rules).
+  //    `sources` are what the acquisition loop may read. `loop` tunes the gate.
+  knowledge: {
+    sources: [
+      // Domain docs you drop in ./knowledge are read as `vault://` sources.
+      { uri: 'vault://knowledge', kind: 'vault' },
+      // Add web / regulation / integration sources the researcher may pull from.
+      // { uri: 'https://example.gov/regulation', kind: 'regulation' },
+    ],
+    requirements: [
+      {
+        id: 'workspace-profile-set',
+        description: 'The workspace has a configured business profile.',
+        category: 'company_specific',
+        acquisitionMode: 'ask_user',
+        importance: 'blocking',
+        freshness: 'static',
+        // Satisfied when a config dot-path is set on the workspace.
+        satisfiedBy: { config: 'profile.businessName', nonEmpty: true },
+      },
+      {
+        id: 'has-client-records',
+        description: 'At least one client/lead record exists to ground outreach.',
+        category: 'domain_specific',
+        acquisitionMode: 'query_connector',
+        importance: 'high',
+        freshness: 'daily',
+        // Satisfied when >= 1 row exists in a workspace-scoped table.
+        satisfiedBy: { table: 'knowledge', minRows: 1 },
+      },
+    ],
+    loop: {
+      goal: 'Ground every client-facing claim against a real record before proposing.',
+      minConfidence: 0.7,
+      freshness: 'session',
+    },
+  },
+
+  // ⑤ INTEGRATIONS — what systems does the agent read/write through?
+  //    (Discovery: "Which CRMs / data sources / messaging channels does the
+  //    workflow touch?") These are @tangle-network/agent-integrations catalog
+  //    kinds. Reads run immediately; writes return approval-required → a proposal.
+  integrations: {
+    enabled: [
+      // 'salesforce',
+      // 'whatsapp',
+    ],
+  },
+
+  // UI — may the agent emit generated views (render_ui)? Optional.
+  ui: {
+    generatedUi: true,
+  },
+
+  // MODEL — omit to resolve from env (TANGLE_API_KEY) at boot via
+  // resolveTangleModelConfig. Pin here only if you need a fixed model.
+})
+
+export type Config = typeof config

package/template/knowledge/README.md

@@ -0,0 +1,24 @@
+# knowledge/
+
+Domain documents the agent grounds on. This directory is DATA — drop files here;
+do not write code.
+
+## Walk this
+
+1. Drop your real domain docs in here as `.md` / `.txt` / `.json` (regulation,
+   product sheets, provider lists, playbooks). One topic per file. Subdirectories
+   are fine.
+2. Register external research sources (URLs, regulation feeds, integration refs)
+   in `agent.config.ts` under `knowledge.sources` — those are what the acquisition
+   loop reads on top of these local files.
+3. Run `pnpm knowledge:ingest` to enumerate inputs (DRY) and, once a model-backed
+   driver is wired, drive the acquisition loop (`--run`).
+
+## What gates what
+
+- The files here + `knowledge.sources` feed the BUILD loop (acquire grounded
+  knowledge). See KNOWLEDGE.md.
+- `knowledge.requirements` in `agent.config.ts` is the ACT gate — what the agent
+  must KNOW before it's allowed to propose. Scored from live workspace state.
+
+Do not commit secrets. Knowledge is content, not credentials.

package/template/scripts/knowledge-ingest.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// knowledge:ingest — the build-loop entry (NOT the act-gate; see KNOWLEDGE.md).
+//
+// This runs in Node (it touches the filesystem), never on the Worker edge path.
+// It enumerates the domain docs you dropped under ./knowledge and the research
+// sources declared in agent.config.ts, then drives the knowledge acquisition
+// loop. By default it runs in DRY mode — it reports what WOULD be ingested so you
+// can verify the inputs before spending model calls. Wire a real model-backed
+// driver/decider (see the createKnowledgeLoop block below) and pass --run to
+// execute the loop.
+//
+// Why a script and not a route: agent-knowledge owns disk I/O over a KB `root`;
+// the acquisition loop proposes knowledge pages that a confidence gate accepts or
+// drops. Grounding (sources) is always recorded; a low-confidence PROPOSAL is
+// dropped — propose, don't apply. Tune the gate in KNOWLEDGE.md.
+
+import { readdir, readFile } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { existsSync } from 'node:fs'
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..')
+const KNOWLEDGE_DIR = join(ROOT, 'knowledge')
+const RUN = process.argv.includes('--run')
+
+async function listDocs(dir) {
+  if (!existsSync(dir)) return []
+  const out = []
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) out.push(...(await listDocs(join(dir, entry.name))))
+    else if (/\.(md|txt|json)$/i.test(entry.name)) out.push(join(dir, entry.name))
+  }
+  return out
+}
+
+// Read agent.config.ts as text to discover declared sources without a TS runtime.
+async function readDeclaredSources() {
+  const cfgPath = join(ROOT, 'agent.config.ts')
+  if (!existsSync(cfgPath)) return []
+  const text = await readFile(cfgPath, 'utf8')
+  // Pull `{ uri: '…', kind: '…' }` literals out of the knowledge.sources block.
+  const sources = []
+  const re = /\{\s*uri:\s*['"]([^'"]+)['"](?:\s*,\s*kind:\s*['"]([^'"]+)['"])?\s*\}/g
+  let m
+  while ((m = re.exec(text))) sources.push({ uri: m[1], kind: m[2] ?? 'unknown' })
+  return sources
+}
+
+async function main() {
+  const docs = await listDocs(KNOWLEDGE_DIR)
+  const sources = await readDeclaredSources()
+
+  console.log('knowledge:ingest')
+  console.log(`  local docs (./knowledge): ${docs.length}`)
+  for (const d of docs) console.log(`    - ${d.slice(ROOT.length + 1)}`)
+  console.log(`  declared sources (agent.config.ts): ${sources.length}`)
+  for (const s of sources) console.log(`    - [${s.kind}] ${s.uri}`)
+
+  if (!RUN) {
+    console.log('')
+    console.log('DRY run. Pass --run to drive the acquisition loop.')
+    console.log('Wire a model-backed driver + decider first — see the commented block in this file and KNOWLEDGE.md.')
+    return
+  }
+
+  // To actually run the loop, install @tangle-network/agent-knowledge +
+  // @tangle-network/agent-runtime (peers), give the loop a KB `root` on disk and
+  // a model-backed driver, then:
+  //
+  //   import { createKnowledgeLoop } from '@tangle-network/agent-app/knowledge-loop'
+  //   import { config } from '../agent.config.ts'  // via a TS loader / tsx
+  //   const loop = createKnowledgeLoop(config.knowledge, {
+  //     root: KNOWLEDGE_DIR,
+  //     driver: async ({ systemPrompt, userMessage }) => ({ finalText: await callModel(systemPrompt, userMessage) }),
+  //     defaultMinConfidence: config.knowledge.loop?.minConfidence ?? 0.7,
+  //   })
+  //   const result = await loop.run()
+  //   console.log('applied:', result.applied)
+  //
+  throw new Error('--run requires a wired model-backed driver. See KNOWLEDGE.md before enabling.')
+}
+
+main().catch((err) => {
+  console.error(`knowledge:ingest: ${err.message}`)
+  process.exit(1)
+})

package/template/src/agent-app.ts

@@ -0,0 +1,77 @@
+/**
+ * src/agent-app.ts — the COMPOSER. Code, not data.
+ *
+ * Turns the declarative `agent.config.ts` + your Cloudflare bindings into the
+ * wired runtime surfaces:
+ *   - tool handlers (the agent→app side channel) over the house D1 + KV preset,
+ *   - the proposal taxonomy (from config.taxonomy — including the regulated set),
+ *   - the knowledge gate accessor (scores config.knowledge.requirements from D1),
+ *   - the resolved model config.
+ *
+ * This is the seam between DATA (config) and ENGINE (agent-app modules). You do
+ * NOT edit `@tangle-network/agent-app` to change behavior; you edit this file to
+ * compose its seams differently, or override a single handler. Default to the
+ * preset — drop down to a custom handler only when the house stack genuinely
+ * cannot express your persistence. See AGENTS.md "DATA vs CODE".
+ */
+
+import { config } from '../agent.config'
+import {
+  createPresetToolHandlers,
+  createD1KnowledgeStateAccessor,
+  type D1Like,
+  type VaultKv,
+} from '@tangle-network/agent-app/preset-cloudflare'
+import { resolveTangleModelConfig } from '@tangle-network/agent-app/runtime'
+import {
+  buildKnowledgeRequirements,
+  deriveSignals,
+} from '@tangle-network/agent-app/knowledge'
+import type { AppToolHandlers, AppToolTaxonomy } from '@tangle-network/agent-app/tools'
+
+/** The Cloudflare bindings the worker hands the composer. */
+export interface AppBindings {
+  /** D1 database — satisfies the preset's structural {@link D1Like}. */
+  DB: D1Like
+  /** KV namespace used as the artifact vault — satisfies {@link VaultKv}. */
+  VAULT: VaultKv
+}
+
+export interface ComposedAgentApp {
+  handlers: AppToolHandlers
+  taxonomy: AppToolTaxonomy
+  /** Score the config's knowledge requirements against live workspace state. */
+  knowledgeGate: (workspaceId: string) => Promise<ReturnType<typeof buildKnowledgeRequirements>>
+  /** Resolve the model config from env. Lazy + fail-loud: composing the app does
+   *  NOT require model env; only the chat path that actually streams does. */
+  resolveModel: () => ReturnType<typeof resolveTangleModelConfig>
+}
+
+/**
+ * Compose the agent app from config + bindings. No domain value is hard-coded:
+ * the taxonomy comes from `config.taxonomy`, the gate from
+ * `config.knowledge.requirements`. Swap a handler here if (and only if) the
+ * preset cannot express your persistence.
+ */
+export function createAgentApp(bindings: AppBindings): ComposedAgentApp {
+  const handlers = createPresetToolHandlers({ db: bindings.DB, vault: bindings.VAULT })
+
+  const taxonomy: AppToolTaxonomy = {
+    proposalTypes: config.taxonomy.proposalTypes,
+    regulatedTypes: config.taxonomy.regulatedTypes,
+  }
+
+  async function knowledgeGate(workspaceId: string) {
+    const accessor = createD1KnowledgeStateAccessor({
+      db: bindings.DB,
+      workspaceId,
+      // Resolve workspace config however your app stores it; stub returns nothing
+      // until you wire real workspace config (see CUSTOMIZE.md ③).
+      config: () => undefined,
+    })
+    const signals = await deriveSignals(config.knowledge.requirements, accessor)
+    return buildKnowledgeRequirements(config.knowledge.requirements, signals)
+  }
+
+  return { handlers, taxonomy, knowledgeGate, resolveModel: () => resolveTangleModelConfig() }
+}

package/template/src/worker.ts

@@ -0,0 +1,128 @@
+/**
+ * src/worker.ts — the chat route. Code, not data.
+ *
+ * The minimal wired entry: a Cloudflare Worker that runs one bounded tool-loop
+ * turn per chat request, with the agent→app tool side channel wired to the
+ * preset handlers and the OpenAI-compatible Tangle Router as the backend.
+ *
+ * What this proves: the agent can call `submit_proposal` / `schedule_followup` /
+ * `render_ui` / `add_citation`, each call is validated against your
+ * `config.taxonomy` and persisted by the preset — with regulated proposals
+ * fail-closed to the approval queue (never auto-executed). You extend the route;
+ * you do not edit `@tangle-network/agent-app`.
+ *
+ * Replace the system-prompt assembly + per-turn context recovery with your real
+ * auth/session once you have one. Keep the human-in-the-loop invariant: regulated
+ * proposals stay proposals.
+ */
+
+import { config } from '../agent.config'
+import { createAgentApp, type AppBindings } from './agent-app'
+import {
+  buildAppToolOpenAITools,
+  createAppToolRuntimeExecutor,
+  isAppToolName,
+  type AppToolContext,
+} from '@tangle-network/agent-app/tools'
+import {
+  runAppToolLoop,
+  createOpenAICompatStreamTurn,
+  type LoopEvent,
+  type LoopMessage,
+  type LoopToolCall,
+  type ToolLoopEvent,
+  type ToolLoopResult,
+} from '@tangle-network/agent-app/runtime'
+
+interface ChatRequest {
+  message: string
+  /** Trusted server-side in a real app; taken from the body here for the skeleton. */
+  userId?: string
+  workspaceId?: string
+  threadId?: string | null
+}
+
+/**
+ * The OpenAI-compat stream yields the app's rich `LoopEvent` (it adds UI-only
+ * `reasoning` / `usage` deltas). The awaitable loop consumes only `text` +
+ * `tool_call`, so narrow the rest onto the substrate's `other` channel. (The
+ * streaming `streamAppToolLoop` path takes the rich stream directly via
+ * `extractText` / `extractToolCall` and needs no narrowing.)
+ */
+function narrowToToolLoopEvents(
+  streamTurn: (messages: LoopMessage[]) => AsyncIterable<LoopEvent>,
+): (messages: LoopMessage[]) => AsyncIterable<ToolLoopEvent> {
+  return (messages) =>
+    (async function* () {
+      for await (const ev of streamTurn(messages)) {
+        if (ev.type === 'text') yield { type: 'text', text: ev.text }
+        else if (ev.type === 'tool_call') yield { type: 'tool_call', call: ev.call }
+        else yield { type: 'other', event: ev }
+      }
+    })()
+}
+
+/** Assemble the system prompt from the config identity (DATA → prompt). */
+function buildSystemPrompt(): string {
+  const fragments = [
+    config.identity.persona,
+    ...(config.identity.systemPromptFragments ?? []),
+    ...Object.values(config.identity.disclaimers ?? {}),
+  ]
+  return fragments.join('\n\n')
+}
+
+export default {
+  async fetch(request: Request, env: AppBindings): Promise<Response> {
+    const url = new URL(request.url)
+    if (url.pathname !== '/chat' || request.method !== 'POST') {
+      return new Response('Not found', { status: 404 })
+    }
+
+    const body = (await request.json()) as ChatRequest
+    if (!body.message) {
+      return new Response(JSON.stringify({ error: 'message is required' }), {
+        status: 400,
+        headers: { 'Content-Type': 'application/json' },
+      })
+    }
+
+    const app = createAgentApp(env)
+
+    // Trusted per-turn context. In production recover this from your auth/session,
+    // NEVER from model tool args — the model must not be able to forge identity.
+    const ctx: AppToolContext = {
+      userId: body.userId ?? 'anonymous',
+      workspaceId: body.workspaceId ?? 'default',
+      threadId: body.threadId ?? null,
+    }
+
+    const executor = createAppToolRuntimeExecutor({
+      handlers: app.handlers,
+      taxonomy: app.taxonomy,
+      ctx,
+    })
+
+    const tools = buildAppToolOpenAITools(app.taxonomy)
+
+    const result = await runAppToolLoop({
+      systemPrompt: buildSystemPrompt(),
+      userMessage: body.message,
+      streamTurn: narrowToToolLoopEvents(createOpenAICompatStreamTurn({ ...app.resolveModel(), tools })),
+      executeToolCall: (call: LoopToolCall) => executor({ toolName: call.toolName, args: call.args }),
+      isExecutableTool: isAppToolName,
+    })
+
+    return new Response(
+      JSON.stringify({
+        text: result.finalText,
+        toolResults: result.toolResults.map((t: ToolLoopResult['toolResults'][number]) => ({
+          label: t.label,
+          outcome: t.outcome,
+        })),
+        turns: result.turns,
+      }),
+      { headers: { 'Content-Type': 'application/json' } },
+    )
+  },
+}

package/template/tests/agent-app.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest'
+import { config } from '../agent.config'
+import { createAgentApp } from '../src/agent-app'
+import type { D1Like, VaultKv } from '@tangle-network/agent-app/preset-cloudflare'
+
+// Tiny in-memory fakes for D1 + KV so the composer runs without Cloudflare.
+function fakeDb(): D1Like {
+  return {
+    prepare() {
+      return {
+        bind() {
+          return this
+        },
+        async first<T>() {
+          return null as T | null
+        },
+        async run() {
+          return { success: true }
+        },
+        async all<T>() {
+          return { results: [] as T[] }
+        },
+      }
+    },
+  } as unknown as D1Like
+}
+
+function fakeVault(): VaultKv {
+  const store = new Map<string, string>()
+  return {
+    async get(key: string) {
+      return store.get(key) ?? null
+    },
+    async put(key: string, value: string) {
+      store.set(key, value)
+    },
+  } as unknown as VaultKv
+}
+
+describe('agent.config', () => {
+  it('regulatedTypes is a subset of proposalTypes (human-in-the-loop invariant)', () => {
+    for (const t of config.taxonomy.regulatedTypes) {
+      expect(config.taxonomy.proposalTypes).toContain(t)
+    }
+  })
+
+  it('has a non-empty identity persona', () => {
+    expect(config.identity.persona.length).toBeGreaterThan(0)
+  })
+})
+
+describe('createAgentApp', () => {
+  it('composes handlers + taxonomy from config without hard-coded domain values', () => {
+    const app = createAgentApp({ DB: fakeDb(), VAULT: fakeVault() })
+    expect(app.taxonomy.proposalTypes).toEqual(config.taxonomy.proposalTypes)
+    expect(typeof app.handlers.submitProposal).toBe('function')
+    expect(typeof app.knowledgeGate).toBe('function')
+  })
+
+  it('a submitted proposal is queued (regulated never auto-executes)', async () => {
+    const app = createAgentApp({ DB: fakeDb(), VAULT: fakeVault() })
+    const regulated = config.taxonomy.regulatedTypes[0]
+    if (!regulated) return
+    const r = await app.handlers.submitProposal(
+      { type: regulated, title: 'test', description: null },
+      { userId: 'u', workspaceId: 'w', threadId: null },
+    )
+    // The preset returns a pending proposal id; it is NOT an executed side effect.
+    expect(typeof r.proposalId).toBe('string')
+  })
+})

package/template/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts'],
+  },
+})

package/template-chat/.dev.vars.example

@@ -0,0 +1,18 @@
+# Copy to .dev.vars for local development (never commit .dev.vars).
+# Production: `wrangler secret put <NAME>` for each secret.
+
+# better-auth HMAC secret — generate one: openssl rand -base64 32
+BETTER_AUTH_SECRET=REPLACE_WITH_RANDOM_SECRET
+
+# Tangle Router key the harness bills model calls against.
+TANGLE_API_KEY=
+# Optional router override; omit for the platform default.
+# TANGLE_ROUTER_URL=
+
+# Sandbox gateway credentials — the agent runs in a Tangle sandbox. Without
+# these every turn fails loud (there is no mock agent).
+SANDBOX_API_KEY=
+SANDBOX_GATEWAY_URL=
+
+# Model override without a redeploy (falls back to config.model.default).
+# MODEL_NAME=

package/template-chat/AGENTS.md

@@ -0,0 +1,73 @@
+# AGENTS.md — you are customizing a chat agent-app
+
+You are a coding agent working in a project generated by `create-agent-app --chat`.
+This project is a thin customization layer on top of `@tangle-network/agent-app`
+(the shell): the whole server chat vertical — auth, thread/message persistence,
+streaming turns with buffered replay, multimodal uploads, human-in-the-loop asks —
+is ASSEMBLED from shell factories, not written here. Walk this contract before you
+touch anything. It is a checklist, not prose — follow it in order.
+
+## 0. Orient
+
+- [ ] Read this file end to end.
+- [ ] Read `CUSTOMIZE.md` — the ordered fill-checklist. It is your task list.
+- [ ] Run `pnpm install && pnpm typecheck && pnpm test`. Confirm green BEFORE editing.
+      The test suite includes the end-to-end turn gate (fake sandbox producer →
+      streamed turn → persisted transcript) — it proves the assembly, not stubs.
+
+## 1. The one rule (layering)
+
+> You change behavior by editing DATA and the COMPOSER — never by editing
+> `@tangle-network/agent-app`.
+
+- The shell owns mechanism: turn protocol + hook order (`createChatTurnRoutes`
+  over agent-runtime's `handleChatTurn`), persistence columns (`createChatTables`),
+  the upload inline-vs-sandbox split, the interaction answer contract, auth guards.
+- You own: `agent.config.ts` + `prompts/system.md` (DATA), `src/` (the COMPOSER +
+  routes), `migrations/` (must mirror the schema — the e2e test executes it),
+  `public/` (the dev page). That is the whole surface.
+
+## 2. DATA vs CODE — know which file you're in
+
+- [ ] DATA → `agent.config.ts`: name, system prompt, model default + effort,
+      harness, renderable ask kinds. Plain values. If you're writing an `if`,
+      you're in the wrong file.
+- [ ] DATA → `prompts/system.md`: the persona. State intents and hard rules,
+      never implementations — no shell commands, CLI flags, or install scripts.
+      The executing agent chooses tools at execution time.
+- [ ] CODE → `src/chat.ts`: the COMPOSER. Wires config + env into the shell's
+      factories. Extend seams here (billing hooks, `transformFinalText`,
+      `onTurnComplete`); never re-implement what a factory already does.
+- [ ] CODE → `src/sandbox.ts`: the sandbox lane (box naming, credentials,
+      profile). All agent intelligence lives IN the sandbox; this file only
+      reaches it.
+- [ ] CODE → `src/worker.ts`: routing only. New endpoint = new handler in
+      `src/chat.ts`, one `if` here.
+
+## 3. Invariants — fail-closed, never relax
+
+- [ ] TRUSTED CONTEXT: `userId`/`workspaceId` come from the better-auth SESSION,
+      never from a request body or model output. The `authorize` seam is the only
+      place identity is established — keep it that way.
+- [ ] THREAD ACCESS: an inaccessible thread reads as 404, indistinguishable from
+      a missing one. A cross-workspace probe must not learn the thread exists.
+- [ ] NO MOCK AGENT: without sandbox credentials a turn fails loud with a clear
+      error. Never add a canned-response fallback — a fake answer is worse than
+      an honest failure.
+- [ ] AGENT-NATIVE: intelligence and tooling live in the sandboxed agent;
+      durability (rows, turn buffer) and money live here. If you're about to
+      parse the agent's prose for data, stop — that's a schema-validated tool's
+      job (see the shell's `/tools`).
+- [ ] GROUNDING: the persona's fabrication rule stays. A real record or an
+      explicit "NOT ON FILE".
+
+## 4. Verify (every change ends here)
+
+- [ ] `pnpm typecheck` — clean. Proves the assembly matches the shell contract.
+- [ ] `pnpm test` — green. The e2e gate runs the REAL migration + REAL factories
+      with one fake (the sandbox event feed). If it fails, the app drifted from
+      the framework — fix the drift, not the test.
+- [ ] For a real deploy: fill `wrangler.toml` + `.dev.vars`, run
+      `pnpm db:migrate:local`, then `pnpm dev` and exercise the dev page.
+
+If any of these is red, you are not done. Do not weaken a test to pass.

package/template-chat/CLAUDE.md

@@ -0,0 +1,6 @@
+# CLAUDE.md
+
+The behavior contract for this project lives in `AGENTS.md`. Read it first, then
+walk `CUSTOMIZE.md` (the fill-checklist).
+
+@AGENTS.md