@soulcraft/sdk 1.4.6 → 1.4.8

package/docs/KIT-APP-GUIDE.md

@@ -0,0 +1,932 @@
+# Kit App Guide — @soulcraft/sdk
+
+> **This guide lives at `/docs/KIT-APP-GUIDE.md` in your workspace VFS.**
+> It is here for you (the developer) AND for Briggy (the AI assistant).
+> Reference it any time you need to know what the SDK can do or how to use it.
+
+---
+
+## What You're Building
+
+A kit app is a full-stack application powered by three things:
+
+```
+@soulcraft/kits     → Domain config (kit.json manifest + SKILL.md prompts)
+@soulcraft/sdk      → Runtime: data, AI, files, realtime, auth, notifications
+Your app code       → Svelte frontend + Hono/Bun backend that wires them together
+```
+
+The SDK is your single source of truth for everything the app does at runtime.
+You don't need to install Anthropic's SDK, set up WebSockets manually, or build a
+file system abstraction. Everything is in `@soulcraft/sdk`.
+
+---
+
+## Quick Start
+
+```bash
+bun add @soulcraft/sdk @soulcraft/brainy @soulcraft/kits
+```
+
+```typescript
+// server.ts — minimal kit app server
+import { Hono } from 'hono'
+import { BrainyInstancePool, createSDK, createAuthMiddleware } from '@soulcraft/sdk/server'
+import { AI_MODELS } from '@soulcraft/sdk'
+
+const pool = new BrainyInstancePool({
+  storage: process.env.STORAGE_TYPE === 'mmap-filesystem' ? 'mmap-filesystem' : 'filesystem',
+  dataPath: process.env.BRAINY_DATA_PATH ?? './brainy-data',
+  strategy: 'per-user',
+  maxInstances: 100,
+})
+
+const app = new Hono()
+
+app.get('/api/ask', async (c) => {
+  const brain = await pool.forUser('user-hash', 'workspace-id')
+  const sdk = createSDK({ brain })
+
+  const kit = await sdk.kits.load('your-kit-id')
+  const response = await sdk.ai.complete({
+    messages: [{ role: 'user', content: c.req.query('q') ?? 'Hello' }],
+    systemPrompt: kit?.shared?.aiPersona,
+    model: AI_MODELS.sonnet,
+  })
+
+  return c.json({ answer: response.text })
+})
+
+export default { port: 3000, fetch: app.fetch, idleTimeout: 255 }
+```
+
+---
+
+## Import Guide
+
+Three import paths — **always use the right one**:
+
+```typescript
+// 1. SERVER — Hono routes, SvelteKit +server.ts, Bun scripts, background jobs
+import { BrainyInstancePool, createSDK, createAuthMiddleware } from '@soulcraft/sdk/server'
+import type { SoulcraftSessionUser, AuthContext } from '@soulcraft/sdk'
+
+// 2. BROWSER — Svelte components, SvelteKit +page.svelte, kit frontend code
+import { createBrainyProxy, HttpTransport, WsTransport, joinHallRoom } from '@soulcraft/sdk/client'
+
+// 3. SHARED — Types and constants used on both sides
+import { AI_MODELS } from '@soulcraft/sdk'
+import type { SoulcraftKitConfig, HallRoomHandle, RoomOptions } from '@soulcraft/sdk'
+```
+
+---
+
+## SDK Modules at a Glance
+
+| Module | Server | Browser | What it does |
+|--------|--------|---------|-------------|
+| `sdk.brainy` | ✅ | via proxy | Graph database: entities, relationships, semantic search |
+| `sdk.vfs` | ✅ | via proxy | Virtual filesystem: documents, code, media, kit files |
+| `sdk.ai` | ✅ | — | Claude AI: completions, streaming, tool calls |
+| `sdk.skills` | ✅ | — | SKILL.md prompts: load, list, install custom skills |
+| `sdk.kits` | ✅ | — | Kit manifests: load config, resolve template file paths |
+| `sdk.events` | ✅ | — | Event bus: react to data changes, emit custom events |
+| `sdk.auth` | ✅ | — | Capability tokens for cross-product server calls |
+| `sdk.hall` | ✅ | `joinHallRoom()` | Realtime: video, audio, transcription, concept detection |
+| `sdk.versions` | ✅ | — | Entity version history and snapshots |
+| `sdk.billing` | ✅ | — | Credits, subscriptions, Stripe, usage tracking |
+| `sdk.notifications` | ✅ | — | Email (Postmark) and SMS (Twilio) |
+| `sdk.license` | ✅ | — | License validation, AI provider config, heartbeat |
+| `sdk.formats` | ✅ | ✅ | WDOC / WSLIDE / WVIZ / WQUIZ types (no runtime object) |
+
+---
+
+## sdk.brainy — Graph Data
+
+The core data layer. Every entity in your kit app lives here as a graph node.
+Brainy provides semantic search, typed entities, and relationship traversal.
+
+```typescript
+import { NounType, VerbType } from '@soulcraft/brainy'
+
+// --- WRITE ---------------------------------------------------------------
+
+// Add an entity
+await sdk.brainy.add({
+  id: 'product-lavender-soy',
+  type: 'Product',
+  metadata: {
+    name: 'Lavender Soy Candle',
+    price: 28.00,
+    stock: 45,
+    category: 'candles',
+    kitId: 'your-kit-id',
+  },
+})
+
+// Update fields
+await sdk.brainy.update({
+  id: 'product-lavender-soy',
+  metadata: { stock: 40, lastRestocked: new Date().toISOString() },
+})
+
+// Delete
+await sdk.brainy.delete('product-lavender-soy')
+
+// --- READ ----------------------------------------------------------------
+
+// Semantic search (most powerful — uses vector similarity)
+const results = await sdk.brainy.find({
+  query: 'soy candle lavender scent',
+  type: 'Product',    // optional type filter
+  limit: 10,
+})
+
+// Keyword + filter
+const inStock = await sdk.brainy.find({
+  query: 'candles',
+  filter: { stock: { $gt: 0 } },
+})
+
+// Exact lookup by ID
+const product = await sdk.brainy.get('product-lavender-soy')
+
+// --- RELATIONSHIPS -------------------------------------------------------
+
+// Link two entities
+await sdk.brainy.relate({
+  from: 'product-lavender-soy',
+  to: 'category-candles',
+  type: 'BelongsTo',
+})
+
+// Traverse relationships
+const relations = await sdk.brainy.getRelations({
+  from: 'product-lavender-soy',
+  type: 'BelongsTo',   // optional — omit to get all
+})
+
+// Remove a link
+await sdk.brainy.unrelate({
+  from: 'product-lavender-soy',
+  to: 'category-candles',
+  type: 'BelongsTo',
+})
+
+// --- REALTIME (server-side) ----------------------------------------------
+sdk.brainy.onDataChange((event) => {
+  // event.event: 'add' | 'update' | 'delete' | 'relate' | 'unrelate'
+  // event.entity — the affected entity (add/update/delete)
+  // event.relation — { from, to, type } (relate/unrelate)
+  if (event.event === 'add') broadcastNewEntity(event.entity)
+})
+```
+
+**Brainy data model:** Every entity has `id`, `type`, `metadata` (arbitrary JSON),
+and optional `nounType` (from `@soulcraft/brainy`'s typed ontology). Use `type` for
+your kit's domain nouns (`'Product'`, `'Recipe'`, `'Character'`). `nounType` is for
+platform-level classification if needed.
+
+---
+
+## sdk.vfs — Virtual Filesystem
+
+Store documents, generated content, kit template files, and any binary data.
+VFS paths are hierarchical strings starting with `/`.
+
+```typescript
+// --- WRITE ---------------------------------------------------------------
+
+// Write a text document
+await sdk.vfs.writeFile('/projects/my-novel/chapter-01.wdoc', docContent)
+
+// Write binary (Buffer or Uint8Array)
+await sdk.vfs.writeFile('/exports/report.pdf', pdfBuffer)
+
+// Create a directory
+await sdk.vfs.mkdir('/projects/new-project', { recursive: true })
+
+// --- READ ----------------------------------------------------------------
+
+// Read file — always returns Buffer; convert for text
+const buffer = await sdk.vfs.readFile('/projects/my-novel/chapter-01.wdoc')
+const text = buffer.toString('utf-8')
+
+// List directory contents
+const entries = await sdk.vfs.readdir('/projects')
+// → ['my-novel', 'research-notes', 'exports']
+
+// File metadata
+const stat = await sdk.vfs.stat('/projects/my-novel/chapter-01.wdoc')
+// → { size: 4821, mtime: Date, isDirectory: false }
+
+// --- MANAGE --------------------------------------------------------------
+await sdk.vfs.rename('/projects/draft-name', '/projects/final-name')
+await sdk.vfs.unlink('/exports/old-report.pdf')
+await sdk.vfs.rmdir('/projects/abandoned-project', { recursive: true })
+```
+
+**Path conventions used across the platform:**
+```
+/projects/{name}/          Kit app project files
+/skills/{kitId}/           Custom skill overrides (.md files)
+/docs/                     Workspace documentation (including this file)
+/exports/                  Generated output files
+```
+
+---
+
+## sdk.ai — Claude AI Integration
+
+All three model tiers, completion and streaming, with tool call support.
+Requires `ANTHROPIC_API_KEY` in your environment.
+
+```typescript
+import { AI_MODELS } from '@soulcraft/sdk'
+
+// --- BASIC COMPLETION ----------------------------------------------------
+
+const response = await sdk.ai.complete({
+  messages: [{ role: 'user', content: 'What candles are running low on stock?' }],
+  systemPrompt: kit.shared?.aiPersona,   // from kit.json → shared.aiPersona
+  model: AI_MODELS.haiku,               // haiku for fast/cheap, sonnet for most tasks
+})
+
+// response.text         — Claude's reply (null if only tool calls returned)
+// response.toolCalls    — Array of { name, input } (null if no tool calls)
+// response.stopReason   — 'end_turn' | 'tool_use' | 'max_tokens'
+// response.usage        — { inputTokens, outputTokens }
+
+// --- WITH TOOL CALLS -----------------------------------------------------
+
+const response = await sdk.ai.complete({
+  messages: [{ role: 'user', content: 'Find all products under $20' }],
+  systemPrompt: kit.shared?.aiPersona,
+  model: AI_MODELS.sonnet,
+  tools: [
+    {
+      name: 'search_products',
+      description: 'Search the product inventory by query and price range',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: { type: 'string', description: 'Search terms' },
+          maxPrice: { type: 'number', description: 'Maximum price filter' },
+        },
+        required: ['query'],
+      },
+    },
+  ],
+})
+
+if (response.toolCalls) {
+  for (const call of response.toolCalls) {
+    if (call.name === 'search_products') {
+      const { query, maxPrice } = call.input as { query: string; maxPrice?: number }
+      const products = await sdk.brainy.find({
+        query,
+        filter: maxPrice ? { price: { $lte: maxPrice } } : undefined,
+      })
+      // Append tool result to messages and call sdk.ai.complete() again
+    }
+  }
+}
+
+// --- STREAMING -----------------------------------------------------------
+
+const stream = sdk.ai.stream({
+  messages: [{ role: 'user', content: 'Write a product description for lavender candles' }],
+  systemPrompt: 'You are a product copywriter for a candle shop.',
+  model: AI_MODELS.sonnet,
+})
+
+for await (const event of stream) {
+  if (event.type === 'text') process.stdout.write(event.text)
+  if (event.type === 'tool_use') console.log('Tool call:', event.toolCall.name)
+  if (event.type === 'done') console.log('Tokens used:', event.result.usage)
+}
+```
+
+### Model Tiers
+
+| Constant | When to use |
+|----------|-------------|
+| `AI_MODELS.haiku` | Fast lookups, data extraction, classification, simple Q&A (cheapest) |
+| `AI_MODELS.sonnet` | Most kit operations: writing, analysis, reasoning, summaries |
+| `AI_MODELS.opus` | Complex multi-step reasoning, long-form synthesis, deep analysis |
+
+---
+
+## sdk.skills — Domain Skills
+
+Skills are `SKILL.md` files that define a kit's AI persona, domain knowledge,
+and step-by-step workflows. The SDK loads them from VFS first (user overrides),
+then falls back to the bundled `@soulcraft/kits` registry.
+
+```typescript
+// Load a single skill (VFS → bundled fallback)
+const skill = await sdk.skills.load('inventory-health', 'your-kit-id')
+if (skill) {
+  // skill.id        — 'inventory-health'
+  // skill.kitId     — 'your-kit-id'
+  // skill.content   — full SKILL.md string (use as system prompt context)
+  // skill.source    — 'vfs' (user-customized) or 'bundled' (from npm package)
+  const systemPrompt = buildSystemPrompt(kit, skill.content)
+}
+
+// Load all skills for a kit
+const skills = await sdk.skills.list({ kitId: 'your-kit-id' })
+const systemPrompt = [
+  kit.shared?.aiPersona,
+  ...skills.map(s => s.content),
+].join('\n\n---\n\n')
+
+// List all skills across all kits
+const allSkills = await sdk.skills.list()
+
+// Install a custom skill into VFS (overrides bundled version for this workspace)
+await sdk.skills.install({
+  id: 'custom-upsell',
+  kitId: 'your-kit-id',
+  content: `---
+id: custom-upsell
+title: Upsell Flow
+---
+You help customers discover complementary products...`,
+})
+```
+
+**VFS path convention:** `/skills/{kitId}/{skillId}.md`
+
+---
+
+## sdk.kits — Kit Registry + File Paths
+
+Access kit manifests and resolve template file locations on disk.
+
+```typescript
+// Load a kit's config from the npm registry
+const kit = await sdk.kits.load('wicks-and-whiskers')
+if (kit) {
+  console.log(kit.id)               // 'wicks-and-whiskers'
+  console.log(kit.name)             // 'Wicks & Whiskers'
+  console.log(kit.description)      // one-sentence summary
+  console.log(kit.type)             // 'venue' | 'content' | 'app' | 'academy' | 'soulcraft'
+  console.log(kit.shared?.aiPersona)     // AI system prompt from kit.json
+  console.log(kit.shared?.suggestions)   // array of { label, prompt } suggestion chips
+}
+
+// List all available kits
+const kits = await sdk.kits.list()
+console.log(kits.map(k => `${k.id}: ${k.name}`))
+
+// Resolve template file paths (for reading kit starter files at initialization)
+const workshopFilesDir = await sdk.kits.resolveFilesPath('blog-series', 'workshop')
+// → '/path/to/node_modules/@soulcraft/kits/kits/blog-series/workshop/files'
+
+const venueFilesDir = await sdk.kits.resolveFilesPath('wicks-and-whiskers', 'venue')
+// → '/path/to/node_modules/@soulcraft/kits/kits/wicks-and-whiskers/venue/files'
+
+const skillsDir = await sdk.kits.resolveSkillsPath('blog-series')
+// → '/path/to/node_modules/@soulcraft/kits/kits/blog-series/skills'
+
+const kitsRoot = await sdk.kits.resolveKitsRoot()
+// → '/path/to/node_modules/@soulcraft/kits/kits'
+```
+
+---
+
+## sdk.events — Platform Event Bus
+
+Subscribe to and emit typed events across your app.
+Events are local to the SDK instance (same server process).
+
+```typescript
+// --- BUILT-IN EVENTS -----------------------------------------------------
+
+// React to Brainy data changes
+sdk.events.on('brainy:change', (event) => {
+  // event.event: 'add' | 'update' | 'delete' | 'relate' | 'unrelate'
+  if (event.event === 'add') console.log('New entity:', event.entity?.id)
+})
+
+// React to VFS changes
+sdk.events.on('vfs:write', ({ path, content }) => {
+  if (path.endsWith('.wdoc')) notifyCollaborators(path)
+})
+
+sdk.events.on('vfs:delete', ({ path }) => { invalidateCache(path) })
+sdk.events.on('vfs:rename', ({ from, to }) => { updateFileTree(from, to) })
+
+// --- CUSTOM EVENTS -------------------------------------------------------
+
+// Step 1: Declare your types (in a .d.ts file or at the top of your types.ts)
+declare module '@soulcraft/sdk' {
+  interface SoulcraftEventMap {
+    'order:placed': { orderId: string; total: number; userId: string }
+    'inventory:low': { productId: string; stock: number; threshold: number }
+  }
+}
+
+// Step 2: Emit + subscribe with full TypeScript type safety
+sdk.events.emit('order:placed', { orderId: 'ord-123', total: 84.00, userId: user.id })
+
+sdk.events.on('inventory:low', ({ productId, stock }) => {
+  sendLowStockAlert(productId, stock)
+})
+
+// Remove a listener
+const handler = (event) => { ... }
+sdk.events.on('brainy:change', handler)
+sdk.events.off('brainy:change', handler)
+```
+
+---
+
+## sdk.hall — Realtime Communication
+
+Video, audio, live transcription, and AI concept detection.
+Runs as a standalone service at `hall.soulcraft.com`.
+
+**Architecture:**
+```
+Your server ──(product secret)──► Hall server ◄──(session token)── Browser
+```
+Product secrets are server-only. Browsers get short-lived session tokens issued by your server.
+
+### Server Setup
+
+```typescript
+import { createHallModule } from '@soulcraft/sdk/server'
+
+const hall = createHallModule({
+  url: process.env.HALL_URL ?? 'wss://hall.soulcraft.com',
+  productName: 'workshop',                   // must match hall.toml [auth.products]
+  secret: process.env.HALL_WORKSHOP_SECRET!, // never exposed to browsers
+})
+
+await hall.connect()
+
+// Create a room (e.g. when a live session starts)
+const room = await hall.createRoom('session-abc123', {
+  maxPeers: 8,
+  enableTranscription: true,
+  enableRecording: false,
+  concepts: [
+    { nodeId: 'node-1', name: 'Maillard reaction', nounType: 'concept' },
+  ],
+})
+
+// Server-side room events
+room.on('transcriptEvent', ({ text, isFinal, speakerId }) => {
+  if (isFinal) saveTranscriptLine(text)
+})
+
+room.on('conceptMentionEvent', ({ nodeId, name, confidence }) => {
+  console.log(`Concept mentioned: "${name}" (${(confidence * 100).toFixed(0)}%)`)
+})
+
+room.on('relationProposedEvent', async ({ fromNodeId, toNodeId, verb, confidence }) => {
+  if (confidence > 0.75) {
+    await sdk.brainy.relate({ from: fromNodeId, to: toNodeId, type: verb })
+  }
+})
+
+room.on('speakerChangedEvent', ({ peerId }) => { updateActiveSpeaker(peerId) })
+room.on('peerJoinedEvent', ({ peerId, displayName }) => { addParticipant(peerId, displayName) })
+room.on('peerLeftEvent', ({ peerId }) => { removeParticipant(peerId) })
+```
+
+### Issue Session Tokens (Server → Browser)
+
+```typescript
+app.post('/api/hall/token', requireAuth, async (c) => {
+  const user = c.get('user')!
+  const { roomId } = await c.req.json<{ roomId: string }>()
+
+  const token = await hall.createSessionToken({
+    roomId,
+    userId: user.id,
+    displayName: user.name ?? user.email,
+    // ttlMs: 300_000   // default: 5 minutes
+  })
+
+  return c.json({ token })
+})
+```
+
+### Browser — Join a Room
+
+```typescript
+import { joinHallRoom } from '@soulcraft/sdk/client'
+import type { HallRoomHandle } from '@soulcraft/sdk'
+
+// 1. Get a session token from your backend
+const { token } = await fetch('/api/hall/token', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ roomId: 'session-abc123' }),
+}).then(r => r.json())
+
+// 2. Join the room
+const room: HallRoomHandle = await joinHallRoom({
+  url: 'wss://hall.soulcraft.com',
+  roomId: 'session-abc123',
+  token,
+})
+
+// 3. Add your media stream
+const stream = await navigator.mediaDevices.getUserMedia({ audio: true, video: true })
+room.addStream(stream)
+
+// 4. Handle remote peers
+room.on('trackAdded', ({ peerId, track, stream }) => {
+  const videoEl = document.getElementById(`peer-${peerId}`) as HTMLVideoElement
+  videoEl.srcObject = stream
+})
+
+room.on('transcriptEvent', ({ text, isFinal }) => {
+  appendSubtitle(text, isFinal)
+})
+
+room.on('conceptMentionEvent', ({ nodeId, confidence }) => {
+  highlightConcept(nodeId, confidence)
+})
+
+// 5. Clean up
+room.close()
+```
+
+---
+
+## Client Transports (Browser → Server Brainy)
+
+Kit frontend code connects to the server Brainy instance via one of four transports:
+
+```typescript
+import { createBrainyProxy, HttpTransport, WsTransport, SseTransport } from '@soulcraft/sdk/client'
+
+// HTTP — simple, stateless (best for read-heavy kit apps)
+const transport = new HttpTransport('https://your-app.soulcraft.com')
+const brainy = createBrainyProxy(transport)
+const items = await brainy.find({ query: 'inventory' })
+
+// WebSocket — bidirectional, real-time change push (best for collaborative apps)
+const wsTransport = new WsTransport(
+  'wss://your-app.soulcraft.com/api/brainy/ws',
+  capabilityToken,
+  'scope-key'          // optional workspace/scope key
+)
+await wsTransport.connect()
+const brainy = createBrainyProxy(wsTransport)
+
+brainy.onDataChange((event) => {
+  console.log('Live change:', event.event, event.entity?.id)
+})
+
+// SSE — lightweight server push (for read-only live dashboards)
+const sseTransport = new SseTransport('https://your-app.soulcraft.com/api/brainy/sse')
+const brainy = createBrainyProxy(sseTransport)
+```
+
+| Transport | Use when |
+|-----------|---------|
+| HTTP | Read-heavy, stateless kit app pages |
+| WebSocket | Real-time collaboration, live editing, multiplayer |
+| SSE | Dashboards that only need server-push (no writes from client) |
+
+---
+
+## BrainyInstancePool — Managing Data Storage
+
+One pool per process. The pool creates, caches, and evicts Brainy instances.
+
+```typescript
+import { BrainyInstancePool } from '@soulcraft/sdk/server'
+
+const pool = new BrainyInstancePool({
+  storage: 'mmap-filesystem',   // 'filesystem' for dev, 'mmap-filesystem' for production GCE
+  dataPath: '/mnt/brainy-data', // './brainy-data' for dev
+  strategy: 'per-user',         // 'per-user' | 'per-tenant' | 'per-scope'
+  maxInstances: 200,
+  flushOnEvict: true,           // save to disk when LRU evicts
+  onInit: async (brain, storagePath) => {
+    await runMigrations(brain)  // optional: runs after first open
+  },
+})
+
+// per-user (Workshop pattern — one Brainy per user per workspace)
+const brain = await pool.forUser(user.emailHash, workspaceId)
+
+// per-tenant (Venue pattern — one shared Brainy per tenant/location)
+const brain = await pool.forTenant('wicks-charlotte')
+
+// per-scope (custom key — for multi-brain scenarios)
+const brain = await pool.forScope(
+  `content:${courseId}`,
+  () => initBrainy(`content/${courseId}`, storagePath)
+)
+
+// Shutdown (flush all, clear cache)
+await pool.shutdown()
+```
+
+---
+
+## Authentication
+
+### Middleware (Hono)
+
+```typescript
+import { betterAuth } from 'better-auth'
+import { Database } from 'bun:sqlite'
+import {
+  SOULCRAFT_USER_FIELDS,
+  SOULCRAFT_SESSION_CONFIG,
+  computeEmailHash,
+  createAuthMiddleware,
+} from '@soulcraft/sdk/server'
+
+const auth = betterAuth({
+  database: new Database('./auth.db'),
+  secret: process.env.BETTER_AUTH_SECRET!,
+  session: SOULCRAFT_SESSION_CONFIG,
+  user: { additionalFields: SOULCRAFT_USER_FIELDS },
+  databaseHooks: {
+    user: {
+      create: {
+        before: async (user) => ({
+          data: { ...user, emailHash: computeEmailHash(user.email), platformRole: 'creator' }
+        }),
+      },
+    },
+  },
+})
+
+const { requireAuth, optionalAuth } = createAuthMiddleware(auth)
+
+app.all('/api/auth/*', (c) => auth.handler(c.req.raw))
+
+app.get('/api/data', requireAuth, async (c) => {
+  const user = c.get('user')!   // SoulcraftSessionUser — id, email, emailHash, platformRole
+  const brain = await pool.forUser(user.emailHash, 'main')
+  const sdk = createSDK({ brain })
+  // ...
+})
+```
+
+### Capability Tokens (Cross-Product Server Calls)
+
+```typescript
+import { createCapabilityToken, verifyCapabilityToken } from '@soulcraft/sdk/server'
+
+// Server A — issue a scoped token
+const token = await createCapabilityToken({
+  email: user.email,
+  scope: 'my-tenant',
+  secret: process.env.CROSS_PRODUCT_SECRET!,
+  ttlMs: 3_600_000,   // 1 hour
+})
+
+// Server B — verify in the handler
+const claims = await verifyCapabilityToken(token, process.env.CROSS_PRODUCT_SECRET!)
+if (!claims) return c.json({ error: 'Unauthorized' }, 401)
+```
+
+---
+
+## Notifications
+
+```typescript
+// Send email (uses Postmark when POSTMARK_SERVER_TOKEN is set; logs to console in dev)
+await sdk.notifications.send({
+  type: 'email',
+  to: 'user@example.com',
+  subject: 'Your order is ready',
+  html: '<h1>Ready!</h1><p>Your candle order has shipped.</p>',
+  text: 'Your candle order has shipped.',
+})
+
+// Send SMS (uses Twilio when TWILIO_* env vars are set; logs to console in dev)
+await sdk.notifications.send({
+  type: 'sms',
+  to: '+15555550100',
+  body: 'Your order has shipped!',
+})
+```
+
+In development (no API keys configured), both calls succeed silently and print to console.
+No mock setup required.
+
+---
+
+## Content Formats
+
+The SDK re-exports Soulcraft's portable content format types from `@soulcraft/formats`.
+These are types only — no runtime object on the SDK instance.
+
+```typescript
+import type {
+  WdocDocument,    // .wdoc — Workshop Document (TipTap/ProseMirror)
+  WslideSlide,     // .wslide — Workshop Slide (presentation format)
+  WvizDocument,    // .wviz — Workshop Visualization (portable graph/chart)
+  WquizQuestion,   // .wquiz — Workshop Quiz (multiple choice, fill-in, etc.)
+} from '@soulcraft/sdk'
+
+// Parse helpers (from @soulcraft/formats directly):
+import { parseWviz, parseWdoc } from '@soulcraft/formats'
+
+const vizData = parseWviz(await sdk.vfs.readFile('/projects/knowledge-graph.wviz'))
+```
+
+| Format | Extension | Description |
+|--------|-----------|-------------|
+| `WdocDocument` | `.wdoc` | Rich text document (TipTap schema) |
+| `WslideSlide` | `.wslide` | Presentation slide with layout + speaker notes |
+| `WvizDocument` | `.wviz` | Self-contained interactive graph visualization |
+| `WquizQuestion` | `.wquiz` | Quiz question with answer options and validation |
+
+---
+
+## Version History
+
+```typescript
+// Get the full version history for an entity
+const history = await sdk.versions.getHistory('product-lavender-soy')
+// → Array<{ version: number, timestamp: string, metadata: Record<string, unknown> }>
+
+// Restore a previous version
+await sdk.versions.restore('product-lavender-soy', 3)
+```
+
+---
+
+## Full Application Template
+
+A complete kit app server combining auth, data, AI, and events:
+
+```typescript
+import { Hono } from 'hono'
+import { betterAuth } from 'better-auth'
+import { Database } from 'bun:sqlite'
+import {
+  BrainyInstancePool,
+  createSDK,
+  createAuthMiddleware,
+  SOULCRAFT_USER_FIELDS,
+  SOULCRAFT_SESSION_CONFIG,
+  computeEmailHash,
+} from '@soulcraft/sdk/server'
+import { AI_MODELS } from '@soulcraft/sdk'
+
+// ── Kit config ────────────────────────────────────────────────────────────────
+
+const KIT_ID = 'your-kit-id'
+
+// ── Auth ──────────────────────────────────────────────────────────────────────
+
+const auth = betterAuth({
+  database: new Database('./auth.db'),
+  secret: process.env.BETTER_AUTH_SECRET!,
+  session: SOULCRAFT_SESSION_CONFIG,
+  user: { additionalFields: SOULCRAFT_USER_FIELDS },
+  databaseHooks: {
+    user: {
+      create: {
+        before: async (u) => ({
+          data: { ...u, emailHash: computeEmailHash(u.email), platformRole: 'creator' },
+        }),
+      },
+    },
+  },
+})
+
+const { requireAuth } = createAuthMiddleware(auth)
+
+// ── Brainy pool ───────────────────────────────────────────────────────────────
+
+const pool = new BrainyInstancePool({
+  storage: process.env.STORAGE_TYPE === 'mmap-filesystem' ? 'mmap-filesystem' : 'filesystem',
+  dataPath: process.env.BRAINY_DATA_PATH ?? './brainy-data',
+  strategy: 'per-user',
+  maxInstances: 200,
+  flushOnEvict: true,
+})
+
+// ── App ───────────────────────────────────────────────────────────────────────
+
+const app = new Hono()
+
+app.all('/api/auth/*', (c) => auth.handler(c.req.raw))
+
+app.get('/api/items', requireAuth, async (c) => {
+  const user = c.get('user')!
+  const brain = await pool.forUser(user.emailHash, 'main')
+  const sdk = createSDK({ brain })
+
+  const items = await sdk.brainy.find({
+    query: 'all items',
+    limit: 100,
+  })
+
+  return c.json({ items })
+})
+
+app.post('/api/ask', requireAuth, async (c) => {
+  const user = c.get('user')!
+  const { question } = await c.req.json<{ question: string }>()
+
+  const brain = await pool.forUser(user.emailHash, 'main')
+  const sdk = createSDK({ brain })
+
+  const kit = await sdk.kits.load(KIT_ID)
+  const skills = await sdk.skills.list({ kitId: KIT_ID })
+
+  const systemPrompt = [
+    kit?.shared?.aiPersona,
+    ...skills.map(s => s.content),
+  ].filter(Boolean).join('\n\n---\n\n')
+
+  const response = await sdk.ai.complete({
+    messages: [{ role: 'user', content: question }],
+    systemPrompt,
+    model: AI_MODELS.sonnet,
+  })
+
+  return c.json({ answer: response.text })
+})
+
+// ── Server ────────────────────────────────────────────────────────────────────
+
+export default {
+  port: Number(process.env.PORT ?? 3000),
+  fetch: app.fetch,
+  idleTimeout: 255,   // CRITICAL: prevents Bun's 10s default from killing long Brainy inits
+}
+```
+
+---
+
+## Environment Variables
+
+| Variable | Module | Required |
+|----------|--------|---------|
+| `ANTHROPIC_API_KEY` | `sdk.ai` | Yes |
+| `BETTER_AUTH_SECRET` | Auth | Yes |
+| `BRAINY_DATA_PATH` | Pool | No (default: `./brainy-data`) |
+| `STORAGE_TYPE` | Pool | No (default: `filesystem`) |
+| `SOULCRAFT_IDP_URL` | Auth (OIDC) | Production only |
+| `SOULCRAFT_OIDC_CLIENT_ID` | Auth (OIDC) | If IDP_URL is set |
+| `SOULCRAFT_OIDC_CLIENT_SECRET` | Auth (OIDC) | If IDP_URL is set |
+| `HALL_URL` | `sdk.hall` | If using realtime |
+| `HALL_{PRODUCT}_SECRET` | `sdk.hall` | If using realtime |
+| `POSTMARK_SERVER_TOKEN` | `sdk.notifications` | For email delivery |
+| `TWILIO_ACCOUNT_SID` | `sdk.notifications` | For SMS delivery |
+| `TWILIO_AUTH_TOKEN` | `sdk.notifications` | For SMS delivery |
+| `STRIPE_SECRET_KEY` | `sdk.billing` | For subscriptions |
+| `SOULCRAFT_LICENSE_KEY` | `sdk.license` | `SC-XXXX-XXXX-XXXX` format |
+
+---
+
+## For Briggy (AI Assistant)
+
+When generating kit app code, always:
+
+1. **Import from the correct entry point** — server code from `@soulcraft/sdk/server`,
+   browser code from `@soulcraft/sdk/client`, types from `@soulcraft/sdk`.
+
+2. **One pool per process, one SDK per request:**
+   ```typescript
+   // ✅ Correct
+   const pool = new BrainyInstancePool(...)              // module-level singleton
+   const brain = await pool.forUser(hash, workspaceId)  // in the request handler
+   const sdk = createSDK({ brain })                     // in the request handler
+   ```
+
+3. **Always use `AI_MODELS.*` constants** — never hardcode model ID strings.
+
+4. **Load kit context before AI calls:**
+   ```typescript
+   const kit = await sdk.kits.load(kitId)
+   const skills = await sdk.skills.list({ kitId })
+   const systemPrompt = [kit?.shared?.aiPersona, ...skills.map(s => s.content)].join('\n\n')
+   ```
+
+5. **`resolveFilesPath` is for initialization only** — read kit template files once at
+   workspace creation time, then store them in VFS. Don't call it in request handlers.
+
+6. **Bun server requires `idleTimeout: 255`** — Bun's default 10-second idle timeout kills
+   requests during Brainy cold start (~25s). Always include it in the server export.
+
+7. **Events are process-local** — `sdk.events` does not cross process or WebSocket
+   boundaries. For cross-client real-time, use the WebSocket transport or Hall.
+
+---
+
+## See Also
+
+- `docs/USAGE.md` — Complete SDK reference with all options and edge cases
+- `docs/ADR-001-sdk-design.md` — Architecture decisions and design rationale
+- `@soulcraft/kit-schema` — Full kit manifest schema with product-specific fields
+- `@soulcraft/kits` — The kit registry package (55+ domain kits)
+- `@soulcraft/formats` — WDOC / WSLIDE / WVIZ / WQUIZ types and parse helpers