create-theokit 0.1.0-alpha.9 → 0.2.1

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "create-theokit",
-  "version": "0.1.0-alpha.9",
+  "version": "0.2.1",
   "type": "module",
   "description": "Scaffold a new TheoKit project",
   "license": "Apache-2.0",
+  "scripts": {
+    "build": "tsup"
+  },
   "bin": {
     "create-theokit": "./dist/cli.js"
   },
@@ -13,8 +16,5 @@
   ],
   "dependencies": {
     "cross-spawn": "^7.0.6"
-  },
-  "scripts": {
-    "build": "tsup"
   }
-}
+}

package/templates/api-only/README.md.tmpl

@@ -0,0 +1,78 @@
+# {{name}}
+
+TheoKit API-only project. Backend routes with Zod validation + typed responses — no frontend bundle, no React.
+
+> 📚 **Full docs:** https://docs.theokit.dev
+
+## Quick start
+
+```bash
+# 1. Set your provider key if you wire an agent route later
+echo 'OPENROUTER_API_KEY=sk-or-v1-...' > .env
+
+# 2. Boot the dev server
+npx theokit dev
+
+# 3. Probe the health route
+curl http://localhost:3000/api/health
+```
+
+You should see `{"status":"ok"}`. The server is now serving the routes under `server/routes/`.
+
+## Templates
+
+- **default** — TheoUI chat composer + agent route.
+- **dashboard** — nested layouts + sidebar.
+- **api-only** (this one) — server routes without React.
+- **postgres** — Drizzle ORM + migrations.
+- **saas** — full app with auth, billing, sessions.
+
+## What the framework auto-loads
+
+- **`.env` → `process.env`**. Edit `.env`; restart the dev server.
+- **`.theo/` build output cleanup** on every `theokit build`.
+- **Route discovery** — every `server/routes/*.ts` becomes a wired endpoint.
+
+## Project structure
+
+```
+server/
+├── routes/
+│   ├── health.ts     GET  /api/health  — returns {status:"ok"}
+│   └── users.ts      CRUD /api/users   — Zod-validated body
+theo.config.ts        Framework config
+.env                  Secrets — never committed (.gitignore)
+```
+
+## Sample requests
+
+```bash
+# Health check
+curl http://localhost:3000/api/health
+
+# Create a user (POST with JSON body)
+curl -X POST http://localhost:3000/api/users \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"Alice","email":"alice@example.com"}'
+
+# List users
+curl http://localhost:3000/api/users
+```
+
+## Common commands
+
+| Command | What it does |
+|---|---|
+| `npx theokit dev` | Dev server with HMR + structured logs |
+| `npx theokit build` | Production build → `.theo/` |
+| `npx theokit start` | Serve the production build |
+| `npx theokit routes` | List all routes detected |
+| `npm run typecheck` | TypeScript strict check (no emit) |
+
+## Add a new route
+
+Drop a `.ts` file in `server/routes/`. Use `defineRoute` from `theokit/server` for Zod-validated handlers, or export `GET`/`POST` directly.
+
+## License
+
+Apply your own. The TheoKit framework is Apache-2.0.

package/templates/api-only/package.json.tmpl

@@ -10,13 +10,19 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.1.0-alpha.8",
+    "theokit": "^0.2.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
+    "@types/node": "^22.10.0",
     "typescript": "^5.7.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
   }
 }

package/templates/api-only/server/routes/webhooks/echo.ts

@@ -0,0 +1,34 @@
+import { defineWebhook } from 'theokit/server'
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import { z } from 'zod'
+
+/**
+ * Echo webhook — demonstrates `defineWebhook` HMAC-SHA256 pattern
+ * without depending on an external provider (Stripe, GitHub, etc.).
+ *
+ * Self-test:
+ *   SECRET=$(openssl rand -base64 32)
+ *   echo -n '{"message":"hi"}' | openssl dgst -sha256 -hmac "$SECRET"
+ *   curl -X POST localhost:3000/api/webhooks/echo \
+ *     -H "x-echo-signature: <hex from above>" \
+ *     -H "Content-Type: application/json" \
+ *     -d '{"message":"hi"}'
+ */
+const ECHO_SECRET = process.env.ECHO_WEBHOOK_SECRET ?? ''
+
+export const POST = defineWebhook({
+  verify: ({ rawBody, headers }) => {
+    if (ECHO_SECRET === '') return false
+    const sig = headers.get('x-echo-signature') ?? ''
+    const expected = createHmac('sha256', ECHO_SECRET).update(rawBody).digest('hex')
+    try {
+      return timingSafeEqual(Buffer.from(sig, 'utf-8'), Buffer.from(expected, 'utf-8'))
+    } catch {
+      return false
+    }
+  },
+  inputSchema: z.object({ message: z.string() }),
+  handler: async ({ input }) => {
+    return Response.json({ echoed: input.message, timestamp: new Date().toISOString() })
+  },
+})

package/templates/dashboard/README.md.tmpl

@@ -0,0 +1,76 @@
+# {{name}}
+
+TheoKit dashboard project. Build the app your agent lives in — with nested layouts and a sidebar wired from day one.
+
+> 📚 **Full docs:** https://docs.theokit.dev
+
+## Quick start
+
+```bash
+# 1. Set your provider key (OpenRouter recommended — one key, any model)
+echo 'OPENROUTER_API_KEY=sk-or-v1-...' > .env
+
+# 2. Boot the dev server
+npx theokit dev
+```
+
+Open the printed URL. The default surface is a dashboard shell with sidebar nav + content area, ready to host your agent panels.
+
+## Templates
+
+- **default** — TheoUI chat composer + agent route.
+- **dashboard** (this one) — nested layouts + sidebar nav.
+- **api-only** — server routes without React.
+- **postgres** — Drizzle ORM + migrations.
+- **saas** — full app with auth, billing, sessions.
+
+## What the framework auto-loads
+
+- **`.env` → `process.env`**. Edit `.env`; restart the dev server.
+- **`.theo/` build output cleanup** on every `theokit build`.
+- **Tailwind + `@usetheo/ui` styling** auto-configured for the TheoUI surface.
+
+## Project structure
+
+```
+app/                  Frontend (file-based routing with nested layouts)
+├── layout.tsx        root wrapper — TheoUI provider + theme
+├── page.tsx          /              — dashboard home
+├── dashboard/
+│   ├── layout.tsx    /dashboard/*   — sidebar shell
+│   └── page.tsx      /dashboard     — primary panel
+server/               Backend (explicit routes)
+├── routes/
+│   └── health.ts     GET /api/health
+theo.config.ts        Framework config
+tailwind.config.ts    Tailwind theme tokens
+.env                  Secrets — never committed
+```
+
+## Common commands
+
+| Command | What it does |
+|---|---|
+| `npx theokit dev` | Dev server with HMR + devtools overlay |
+| `npx theokit build` | Production build → `.theo/` |
+| `npx theokit start` | Serve the production build |
+| `npx theokit check` | Lint for upgrade-readiness |
+| `npx theokit routes` | List all routes + actions detected |
+| `npm run typecheck` | TypeScript strict check (no emit) |
+
+## Add a new panel
+
+```bash
+mkdir -p app/dashboard/billing
+cat > app/dashboard/billing/page.tsx <<'EOF'
+export default function BillingPage() {
+  return <h2>Billing</h2>
+}
+EOF
+```
+
+The route appears at `/dashboard/billing` after HMR.
+
+## License
+
+Apply your own. The TheoKit framework is Apache-2.0.

package/templates/dashboard/package.json.tmpl

@@ -10,13 +10,19 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.1.0-alpha.8",
+    "theokit": "^0.2.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
+    "@types/node": "^22.10.0",
     "typescript": "^5.7.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
   }
 }

package/templates/dashboard/server/crons/cleanup-conversations.ts

@@ -0,0 +1,50 @@
+import { defineCron } from 'theokit/server/cron'
+import { readdir, stat, rm } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+
+/**
+ * Daily GC of stale conversation transcripts.
+ *
+ * The `@usetheo/sdk` Agent persists chat history under
+ * `.theokit/agents/<agentId>/messages.jsonl`. With no TTL the directory
+ * grows unbounded — production foot-gun. This cron removes any agent
+ * directory whose `messages.jsonl` hasn't been touched in 30 days.
+ */
+const MAX_AGE_DAYS = 30
+const AGENTS_DIR = '.theokit/agents'
+
+export default defineCron('cleanup-conversations', {
+  schedule: '0 4 * * *', // Daily 04:00 UTC
+  handler: async ({ log }) => {
+    const root = resolve(process.cwd(), AGENTS_DIR)
+    const cutoff = Date.now() - MAX_AGE_DAYS * 24 * 60 * 60 * 1000
+    let removed = 0
+    let kept = 0
+    let entries: Awaited<ReturnType<typeof readdir>>
+    try {
+      entries = await readdir(root, { withFileTypes: true })
+    } catch {
+      log.info({ msg: 'No agents dir yet — first run', dir: root })
+      return
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      const agentDir = join(root, entry.name)
+      const messagesFile = join(agentDir, 'messages.jsonl')
+      try {
+        const s = await stat(messagesFile)
+        if (s.mtimeMs < cutoff) {
+          await rm(agentDir, { recursive: true, force: true })
+          removed++
+        } else {
+          kept++
+        }
+      } catch {
+        // messages.jsonl missing → orphan dir, remove
+        await rm(agentDir, { recursive: true, force: true }).catch(() => {})
+        removed++
+      }
+    }
+    log.info({ msg: 'cleanup-conversations complete', removed, kept, maxAgeDays: MAX_AGE_DAYS })
+  },
+})

package/templates/default/README.md.tmpl

@@ -2,6 +2,8 @@
 
 TheoKit project. Build the app your agent lives in — routing, auth, real-time, deploy — wired.
 
+> 📚 **Full docs:** https://docs.theokit.dev
+
 ## Quick start
 
 ```bash

package/templates/default/app/page.tsx

@@ -160,7 +160,7 @@ export default function Page() {
       return
     }
     const action = QUICK_ACTIONS.find((a) => a.id === id)
-    if (action) handleSubmit(action.label)
+    if (action) handleSubmit(typeof action.label === 'string' ? action.label : '')
   }
 
   const isStreaming = status === 'streaming'
@@ -221,9 +221,9 @@ export default function Page() {
                 return (
                   <AgentErrorCard
                     key={item.id}
-                    kind="model"
+                    kind="tool-failure"
                     title="Agent error"
-                    description={item.message}
+                    detail={item.message}
                   />
                 )
               })}
@@ -240,8 +240,8 @@ export default function Page() {
               <AgentErrorCard
                 kind="network"
                 title="Stream ended with an error"
-                description="The connection to the agent endpoint was interrupted. Reset to try again."
-                action={
+                detail="The connection to the agent endpoint was interrupted. Reset to try again."
+                actions={
                   <Button variant="ghost" size="sm" onClick={() => reset()}>
                     Reset
                   </Button>

package/templates/default/package.json.tmpl

@@ -10,9 +10,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.1.0-alpha.8",
-    "@usetheo/sdk": "^1.1.0",
-    "@usetheo/ui": "^0.12.0-next.0",
+    "theokit": "^0.2.0",
+    "@usetheo/sdk": "^1.3.0",
+    "@usetheo/ui": "^0.12.0",
     "lucide-react": "^0.469.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
@@ -20,10 +20,16 @@
     "zod": "^3.24.0"
   },
   "devDependencies": {
+    "@types/node": "^22.10.0",
     "typescript": "^5.7.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "tailwindcss": "^4.0.0",
     "@tailwindcss/vite": "^4.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
   }
 }

package/templates/default/server/crons/cleanup-conversations.ts

@@ -0,0 +1,59 @@
+import { defineCron } from 'theokit/server/cron'
+import { readdir, stat, rm } from 'node:fs/promises'
+import type { Dirent } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+/**
+ * Daily GC of stale conversation transcripts.
+ *
+ * The `@usetheo/sdk` Agent persists chat history under
+ * `.theokit/agents/<agentId>/messages.jsonl`. With no TTL the directory
+ * grows unbounded — production foot-gun. This cron removes any agent
+ * directory whose `messages.jsonl` hasn't been touched in 30 days.
+ */
+const MAX_AGE_DAYS = 30
+const AGENTS_DIR = '.theokit/agents'
+
+export default defineCron('cleanup-conversations', {
+  schedule: '0 4 * * *', // Daily 04:00 UTC
+  handler: async ({ traceId }) => {
+    const root = resolve(process.cwd(), AGENTS_DIR)
+    const cutoff = Date.now() - MAX_AGE_DAYS * 24 * 60 * 60 * 1000
+    let removed = 0
+    let kept = 0
+    let entries: Dirent[]
+    try {
+      entries = (await readdir(root, { withFileTypes: true })) as unknown as Dirent[]
+    } catch {
+      console.info(JSON.stringify({ msg: 'No agents dir yet — first run', dir: root, traceId }))
+      return
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue
+      const agentDir = join(root, String(entry.name))
+      const messagesFile = join(agentDir, 'messages.jsonl')
+      try {
+        const s = await stat(messagesFile)
+        if (s.mtimeMs < cutoff) {
+          await rm(agentDir, { recursive: true, force: true })
+          removed++
+        } else {
+          kept++
+        }
+      } catch {
+        // messages.jsonl missing → orphan dir, remove
+        await rm(agentDir, { recursive: true, force: true }).catch(() => {})
+        removed++
+      }
+    }
+    console.info(
+      JSON.stringify({
+        msg: 'cleanup-conversations complete',
+        removed,
+        kept,
+        maxAgeDays: MAX_AGE_DAYS,
+        traceId,
+      }),
+    )
+  },
+})

package/templates/default/server/routes/chat.ts

@@ -34,34 +34,36 @@ export const POST = defineAgentEndpoint({
         ? (body as { message?: string })
         : {}
     const { message = '' } = safeBody
-    const orKey = process.env.OPENROUTER_API_KEY
-    const anKey = process.env.ANTHROPIC_API_KEY
-    const apiKey = orKey !== undefined && orKey.length > 0 ? orKey : anKey
-    // Model defaults — escolhidos pra ser cheap + funcionais empíricamente em 2026-05-28.
-    // Stranger pode trocar pra modelo de sua preferência.
-    const modelId =
-      orKey !== undefined && orKey.length > 0
-        ? 'openai/gpt-4o-mini' // OpenRouter route — cheap (~$0.15/1M tokens) + always available
-        : 'claude-sonnet-4-5-20250929' // direct Anthropic
-    if (apiKey === undefined || apiKey.length === 0) {
-      yield {
-        type: 'error',
-        message: 'Set OPENROUTER_API_KEY or ANTHROPIC_API_KEY in your .env to enable the agent.',
-      }
-      return
+    // Provider resolution centralizada (Strategy pattern) — theokit/server resolve
+    // apiKey + baseUrl + provider automático via OPENROUTER_API_KEY / OPENAI_API_KEY /
+    // ANTHROPIC_API_KEY presente no env. Wire protocol: OpenAI Chat Completions
+    // (universal — todos os providers implementam essa API). Consumer NÃO tem
+    // conditionals sobre provider — é responsabilidade do framework.
+    // Wrap full agent lifecycle in try/catch — provider errors (invalid KEY,
+    // 401, rate-limit, model-not-found, 5xx) MUST surface as AgentEvent
+    // 'error' so the client renders an actionable message instead of a
+    // silent SSE closure. Dogfood chaos Phase 12 validates this contract.
+    try {
+      const { agent } = await createConversationHistory({
+        request,
+        response: { headers: cookieHeaders },
+        options: {
+          // Model id is prefixed with the provider namespace. When using
+          // OPENROUTER_API_KEY (default), prefixes route to the correct
+          // upstream — `openai/`, `anthropic/`, `google/`, `meta-llama/`,
+          // `mistralai/`, `groq/`, etc. See https://openrouter.ai/models.
+          // Without the prefix the SDK falls back to a stub response.
+          model: { id: 'openai/gpt-4o-mini' },
+          tools: [currentTime],
+        },
+      })
+      const run = await agent.send(message, { signal })
+      yield* streamAgentRun(run)
+      // Intentionally NO agent.dispose() — the agent stays registered so the
+      // next request from the same conversation resumes it (continuity).
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      yield { type: 'error', message: `Agent error: ${msg}` }
     }
-    const { agent } = await createConversationHistory({
-      request,
-      response: { headers: cookieHeaders },
-      options: {
-        apiKey,
-        model: { id: modelId },
-        tools: [currentTime],
-      },
-    })
-    const run = await agent.send(message, { signal })
-    yield* streamAgentRun(run)
-    // Intentionally NO agent.dispose() — the agent stays registered so the
-    // next request from the same conversation resumes it (continuity).
   },
 })

package/templates/postgres/README.md.tmpl

@@ -0,0 +1,83 @@
+# {{name}}
+
+TheoKit project with Postgres + Drizzle ORM wired. Schema-first, migration-aware, typed end-to-end.
+
+> 📚 **Full docs:** https://docs.theokit.dev
+
+## Quick start
+
+```bash
+# 0. Provision Postgres
+#    Option A — local docker (one-liner):
+docker run --name pg -e POSTGRES_PASSWORD=dev -p 5432:5432 -d postgres:16
+#    Option B — hosted: neon.tech, supabase.com, fly.io
+
+# 1. Set env
+cat > .env <<'EOF'
+DATABASE_URL=postgres://postgres:dev@localhost:5432/postgres
+OPENROUTER_API_KEY=sk-or-v1-...
+EOF
+
+# 2. Generate + apply migrations
+pnpm db:generate
+pnpm db:migrate
+
+# 3. Boot the dev server
+npx theokit dev
+```
+
+Open the printed URL. The default surface includes a sample users API backed by Postgres.
+
+## Templates
+
+- **default** — TheoUI chat composer + agent route.
+- **dashboard** — nested layouts + sidebar.
+- **api-only** — server routes without React.
+- **postgres** (this one) — Drizzle ORM + migrations.
+- **saas** — full app with auth, billing, sessions.
+
+## What the framework auto-loads
+
+- **`.env` → `process.env`**. `DATABASE_URL` must be set before `pnpm db:migrate`.
+- **`.theo/` build output cleanup** on every `theokit build`.
+- **Drizzle schema** under `db/schema.ts` drives migrations + typed query builder.
+
+## Project structure
+
+```
+app/                  Frontend
+├── page.tsx          /              — sample UI
+server/
+├── routes/
+│   ├── health.ts     GET  /api/health
+│   └── users.ts      CRUD /api/users  — backed by db.users
+db/
+├── schema.ts         Drizzle schema (tables + relations)
+├── client.ts         Drizzle client (used by routes)
+└── migrations/       Generated SQL files (committed)
+drizzle.config.ts     Drizzle CLI config
+theo.config.ts        Framework config
+.env                  Secrets — never committed
+```
+
+## Common commands
+
+| Command | What it does |
+|---|---|
+| `npx theokit dev` | Dev server with HMR |
+| `npx theokit build` | Production build |
+| `npx theokit start` | Serve production build |
+| `pnpm db:generate` | Generate SQL migration from `db/schema.ts` |
+| `pnpm db:migrate` | Apply pending migrations to `DATABASE_URL` |
+| `pnpm db:studio` | Open Drizzle Studio UI |
+| `npm run typecheck` | TypeScript strict check |
+
+## Troubleshooting
+
+- **`pnpm db:migrate` fails with "ECONNREFUSED"** → check `DATABASE_URL` host:port + Postgres is running (`docker ps` or hosted dashboard).
+- **`relation "users" does not exist`** → you forgot `pnpm db:migrate`. Run it.
+- **Schema change not reflected** → `pnpm db:generate` first, then `pnpm db:migrate`.
+
+## License
+
+Apply your own. The TheoKit framework is Apache-2.0.

package/templates/postgres/package.json.tmpl

@@ -14,7 +14,7 @@
     "db:studio": "drizzle-kit studio"
   },
   "dependencies": {
-    "theokit": "^0.1.0-alpha.8",
+    "theokit": "^0.2.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "drizzle-orm": "^0.45.0",
@@ -22,9 +22,15 @@
     "zod": "^3.24.0"
   },
   "devDependencies": {
+    "@types/node": "^22.10.0",
     "typescript": "^5.7.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "drizzle-kit": "^0.31.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
   }
 }

package/templates/postgres/server/jobs/log-message.ts

@@ -0,0 +1,26 @@
+import { defineJob } from 'theokit/server/jobs'
+import { z } from 'zod'
+import { appendFile, mkdir } from 'node:fs/promises'
+import { resolve, dirname } from 'node:path'
+
+/**
+ * Background job demonstrating `defineJob` + `ctx.queue.enqueue` pattern.
+ *
+ * Triggered from `server/routes/users.ts` POST handler via:
+ *   await ctx.queue.enqueue('log-message', { userId, message })
+ *
+ * Per ADR-0003 (transactional outbox), enqueue is deferred until the
+ * route handler commits successfully — handler throws → 0 jobs dispatched.
+ */
+export default defineJob('log-message', {
+  input: z.object({ userId: z.string(), message: z.string() }),
+  handler: async ({ input, log }) => {
+    // v1.1 EC-9: anchor path to process.cwd() — handler CWD may differ from
+    // project root when running via external job runner.
+    const auditPath = resolve(process.cwd(), '.theo/audit.log')
+    await mkdir(dirname(auditPath), { recursive: true })
+    const line = `${new Date().toISOString()} user=${input.userId} msg=${input.message}\n`
+    await appendFile(auditPath, line)
+    log.info({ msg: 'audit logged', userId: input.userId, path: auditPath })
+  },
+})

package/templates/saas/README.md.tmpl

@@ -0,0 +1,103 @@
+# {{name}}
+
+TheoKit SaaS template — auth, sessions, billing-ready, and an agent route. The full stack for shipping an account-aware product on day one.
+
+> 📚 **Full docs:** https://docs.theokit.dev
+
+## Quick start
+
+```bash
+# 0. Provision Postgres (sessions + users)
+docker run --name pg -e POSTGRES_PASSWORD=dev -p 5432:5432 -d postgres:16
+# Or use a hosted Postgres (neon.tech / supabase.com)
+
+# 1. Set env (generate a strong session secret)
+cat > .env <<EOF
+DATABASE_URL=postgres://postgres:dev@localhost:5432/postgres
+SESSION_SECRET=$(openssl rand -base64 32)
+OPENROUTER_API_KEY=sk-or-v1-...
+EOF
+
+# 2. Migrate the schema
+pnpm db:generate
+pnpm db:migrate
+
+# 3. Boot the dev server
+npx theokit dev
+```
+
+## Sample auth flow
+
+```bash
+# Register
+curl -X POST http://localhost:3000/api/register \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"alice@example.com","password":"strong-passphrase"}'
+
+# Login (saves session cookie)
+curl -X POST http://localhost:3000/api/login \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"alice@example.com","password":"strong-passphrase"}' \
+  -c cookies.txt
+
+# Authenticated request
+curl http://localhost:3000/api/me -b cookies.txt
+```
+
+## Templates
+
+- **default** — TheoUI chat composer + agent route.
+- **dashboard** — nested layouts + sidebar.
+- **api-only** — server routes without React.
+- **postgres** — Drizzle ORM + migrations.
+- **saas** (this one) — full app with auth, billing, sessions.
+
+## What the framework auto-loads
+
+- **`.env` → `process.env`**. `SESSION_SECRET`, `DATABASE_URL`, `OPENROUTER_API_KEY` all required.
+- **Encrypted sessions** (AES-256-GCM) via `SESSION_SECRET`.
+- **`.theo/` build output cleanup** on every `theokit build`.
+
+## Project structure
+
+```
+app/                  Frontend
+├── page.tsx          /            — landing
+server/
+├── routes/
+│   ├── login.ts      POST /api/login    — sets session cookie
+│   ├── logout.ts     POST /api/logout   — clears session
+│   ├── me.ts         GET  /api/me       — requireAuth() guarded
+│   └── agent.ts      POST /api/agent    — agent SSE, requireAuth()
+db/
+├── schema.ts         users + sessions tables (Drizzle)
+└── migrations/       generated SQL (committed)
+drizzle.config.ts     Drizzle config
+theo.config.ts        Framework config
+.env                  Secrets — never committed
+```
+
+## Common commands
+
+| Command | What it does |
+|---|---|
+| `npx theokit dev` | Dev server with HMR + auth |
+| `npx theokit build` | Production build |
+| `npx theokit start` | Serve production build |
+| `pnpm db:generate` | Generate SQL migration |
+| `pnpm db:migrate` | Apply migrations |
+| `npm run typecheck` | TypeScript strict check |
+
+## Adding billing
+
+Stripe is the canonical path — add `STRIPE_SECRET_KEY` to `.env`, mount `server/routes/billing/webhook.ts` via `defineWebhook`, and wire plan checks into `requireAuth()`.
+
+## Troubleshooting
+
+- **`SESSION_SECRET must be at least 32 bytes`** → regenerate with `openssl rand -base64 32`.
+- **`relation "users" does not exist`** → run `pnpm db:migrate` first.
+- **`401 Unauthorized` on `/api/me`** → login first; cookie must be sent (`-b cookies.txt`).
+
+## License
+
+Apply your own. The TheoKit framework is Apache-2.0.

package/templates/saas/package.json.tmpl

@@ -14,8 +14,8 @@
     "db:studio": "drizzle-kit studio"
   },
   "dependencies": {
-    "theokit": "^0.1.0-alpha.8",
-    "@usetheo/ui": "^0.12.0-next.0",
+    "theokit": "^0.2.0",
+    "@usetheo/ui": "^0.12.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "react-router": "^7.0.0",
@@ -24,9 +24,15 @@
     "zod": "^3.24.0"
   },
   "devDependencies": {
+    "@types/node": "^22.10.0",
     "typescript": "^5.7.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "drizzle-kit": "^0.31.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild"
+    ]
   }
 }

package/templates/saas/server/routes/agent.ts

@@ -1,10 +1,20 @@
 import { defineAgentEndpoint, requireAuth, type AgentEvent } from 'theokit/server'
+import { trackAgentRun } from 'theokit/server/cost'
 import type { RequestContext } from '../context.js'
 
 /**
  * Protected agent endpoint. `requireAuth` fires BEFORE the stream starts;
  * unauthorized requests get 401 immediately — no SSE bytes leak.
  *
+ * Observability: wraps the run with `trackAgentRun` to surface per-user
+ * cost + token usage to the configured `UsageStorageAdapter` (configure via
+ * `theo.config.ts > cost.storage`). Also feeds the devtools `Agents` tab
+ * (when running in dev).
+ *
+ * NOTE: `costUsd: 0` is a v1 stub. Pricing table integration is a
+ * `@usetheo/sdk` follow-up (R0.5.11). Devtools tab renders "$0.0000" —
+ * indicates "cost tracking not yet calibrated for this model".
+ *
  * Replace the mock generator with your LLM provider call.
  */
 export const POST = defineAgentEndpoint<{ message: string }, RequestContext>({
@@ -12,10 +22,28 @@ export const POST = defineAgentEndpoint<{ message: string }, RequestContext>({
     requireAuth(ctx.session)
     const body = (await request.json()) as { message?: string }
     const msg = body.message ?? ''
-    yield {
-      type: 'message',
-      content: `Hello ${ctx.session.email}, you said: "${msg}"`,
+    try {
+      yield {
+        type: 'message',
+        content: `Hello ${ctx.session.email}, you said: "${msg}"`,
+      }
+      yield { type: 'message', content: '(Replace this mock with your LLM.)' }
+    } finally {
+      // Always emit observability — even on stream error / abort.
+      // `storage` resolved from theo.config.ts > cost.storage (undefined =
+      // no-op; configure to enable persistence + devtools tab visibility).
+      // To enable persistent cost tracking: wire `cost: { storage }` into
+      // `theo.config.ts` and forward via context. Demo passes `undefined`
+      // (no-op storage; still fires devtools dispatcher in dev mode).
+      await trackAgentRun(
+        {
+          userId: ctx.session.email,
+          model: 'mock/echo',
+          tokens: { input: msg.length, output: 0 }, // crude — real impl uses tokenizer
+          costUsd: 0, // v1 stub
+        },
+        { storage: undefined },
+      )
     }
-    yield { type: 'message', content: '(Replace this mock with your LLM.)' }
   },
 })

package/templates/saas/server/routes/billing/stripe-webhook.ts

@@ -0,0 +1,49 @@
+import { defineWebhook } from 'theokit/server'
+import { createHmac, timingSafeEqual } from 'node:crypto'
+import { z } from 'zod'
+
+/**
+ * Stripe webhook receiver.
+ *
+ * Verifies `Stripe-Signature` header per Stripe's documented HMAC-SHA256
+ * scheme (https://stripe.com/docs/webhooks/signatures). Real impl would
+ * handle `checkout.session.completed`, `invoice.paid`, etc.
+ *
+ * Setup:
+ *   1. Create webhook endpoint in Stripe Dashboard pointing to /api/billing/stripe-webhook
+ *   2. Copy signing secret → `.env` STRIPE_WEBHOOK_SECRET
+ *   3. Test locally: `stripe listen --forward-to localhost:3000/api/billing/stripe-webhook`
+ */
+const STRIPE_SECRET = process.env.STRIPE_WEBHOOK_SECRET ?? ''
+
+export const POST = defineWebhook({
+  verify: ({ rawBody, headers }) => {
+    if (STRIPE_SECRET === '') return false
+    const sigHeader = headers.get('stripe-signature') ?? ''
+    // Stripe format: `t=<unix-ts>,v1=<hash>` (potentially also v0)
+    const parts: Record<string, string> = {}
+    for (const pair of sigHeader.split(',')) {
+      const [k, v] = pair.split('=')
+      if (k && v) parts[k.trim()] = v.trim()
+    }
+    const t = parts['t']
+    const v1 = parts['v1']
+    if (!t || !v1) return false
+    const signedPayload = `${t}.${rawBody}`
+    const expected = createHmac('sha256', STRIPE_SECRET).update(signedPayload).digest('hex')
+    try {
+      return timingSafeEqual(Buffer.from(v1, 'utf-8'), Buffer.from(expected, 'utf-8'))
+    } catch {
+      return false
+    }
+  },
+  inputSchema: z.object({ type: z.string(), data: z.unknown() }),
+  handler: async ({ input, log }) => {
+    log.info({ msg: 'stripe webhook received', type: input.type })
+    // TODO: dispatch by input.type:
+    //   - 'checkout.session.completed' → activate subscription
+    //   - 'invoice.paid' → extend access
+    //   - 'invoice.payment_failed' → notify user + retry plan
+    return Response.json({ received: true })
+  },
+})

package/LICENSE

@@ -1,201 +0,0 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for describing the origin of the Work and
-      reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright 2026 usetheo.dev
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.