create-theokit 1.25.0 → 1.25.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-theokit",
-  "version": "1.25.0",
+  "version": "1.25.2",
   "type": "module",
   "description": "Scaffold a new TheoKit project",
   "repository": {

package/templates/_bot-preset/agents/publisher.ts

@@ -20,7 +20,7 @@ export const policy = 'public'
 
 export default AgentBuilder.create()
   .input(z.object({ instruction: z.string() }))
-  .model(process.env.LLM_MODEL ?? 'openai/gpt-4o-mini')
+  .model(process.env.LLM_MODEL ?? 'openrouter/openai/gpt-4o-mini')
   .system(
     'You turn research notes into published output. Read notes with read_notes, then publish. ' +
       'Publishing is gated: a human approves it before it happens.',

package/templates/_bot-preset/agents/researcher.ts

@@ -19,7 +19,7 @@ export const policy = 'public'
 
 export default AgentBuilder.create()
   .input(z.object({ topic: z.string() }))
-  .model(process.env.LLM_MODEL ?? 'openai/gpt-4o-mini')
+  .model(process.env.LLM_MODEL ?? 'openrouter/openai/gpt-4o-mini')
   .system(
     'You research a topic and leave notes for the publisher bot. ' +
       'Write what you find with write_note; read what you already know with read_notes. ' +

package/templates/default/.env.example

@@ -2,4 +2,4 @@
 OPENROUTER_API_KEY=sk-or-v1-your-key-here
 
 # Optional: override the model declared in agents/chat.ts
-# LLM_MODEL=openai/gpt-4o-mini
+# LLM_MODEL=openrouter/openai/gpt-4o-mini

package/templates/default/CLAUDE.md

@@ -8,13 +8,13 @@ This project includes TheoKit-aware skills that activate automatically when you
 
 | Skill            | Triggers when editing                                                  | What it provides                                                                                                                            |
 | ---------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| theokit-routes   | `server/routes/**`                                                     | defineRoute API, Zod validation, HTTP methods, dynamic params                                                                               |
+| theokit-routes   | `server/routes/**`                                                     | the route() builder, Zod validation, HTTP methods, dynamic params                                                                           |
 | theokit-gateways | `server/routes/**`, `**/*webhook*`                                     | handleChannelWebhook, the `@theokit/gateway-*` adapters, signature validation, the onMessage seam                                           |
 | theokit-agents   | `**/*agent*`, `**/*tool*`, `**/*Agent*`, `**/*Tool*`                   | @Agent, @Tool, @Toolbox decorators, LLM integration                                                                                         |
 | theokit-database | `**/*schema*`, `**/*db*`, `**/drizzle*`, `**/*migration*`, `**/*seed*` | Drizzle ORM, SQLite, schema patterns, migrations                                                                                            |
 | theokit-frontend | `app/**`                                                               | File-based routing, layouts, theoFetch, useAgent                                                                                            |
 | theokit-ui       | `app/**`, `**/*Chat*`, `**/*Sidebar*`, `**/*Theme*`                    | @theokit/ui AI components: ChatThread, ChatMessage, ToolCallCard, theming (generic primitives like CodeBlock/Sidebar come from @usetheo/ui) |
-| theokit-config   | `theo.config*`, `**/*config*`                                          | defineConfig options, plugins, security, storage                                                                                            |
+| theokit-config   | `theo.config*`, `**/*config*`                                          | the config() builder, plugins, security, storage                                                                                            |
 
 ### Settings
 

package/templates/default/README.md.tmpl

@@ -56,7 +56,7 @@ your environment.
   ```ts
   export default AgentBuilder.create()
     .input(z.object({ message: z.string() }))
-    .model('openai/gpt-4o-mini')
+    .model('openrouter/openai/gpt-4o-mini')
     .system(BASE_INSTRUCTIONS)
     .tool(weatherTool)
     .approval('send_notification', { question: 'Send this notification?' })

package/templates/default/agents/chat.ts

@@ -14,9 +14,17 @@ import { weatherTool } from './tools/weather.js'
  * treats `prompts/ tools/ skills/ lib/ …` as semantic folders, so `agents/tools/weather.ts` never becomes
  * a `/api/agents/tools/weather` endpoint. Add a second agent as another `agents/<name>.ts`.
  *
- * `@theokit/sdk` runs the agent; conversation turns auto-persist per session. Provider is resolved from
- * the environment — OPENROUTER_API_KEY (preferred) OR ANTHROPIC_API_KEY / OPENAI_API_KEY; the model id is
- * provider-prefixed so OpenRouter routes it upstream (https://openrouter.ai/models).
+ * `@theokit/sdk` runs the agent; conversation turns auto-persist per session.
+ *
+ * The FIRST segment of the model id picks the provider, and the key it needs follows from that:
+ * `openrouter/…` needs `OPENROUTER_API_KEY`, `anthropic/…` needs `ANTHROPIC_API_KEY`, `openai/…`
+ * needs `OPENAI_API_KEY`. There is no magic routing — a bare `openai/gpt-4o-mini` goes to OpenAI,
+ * not through a gateway, even with an OpenRouter key present. Reaching OpenAI's catalog THROUGH
+ * OpenRouter means naming the gateway: `openrouter/openai/gpt-4o-mini`, which is what this file
+ * declares, because `.env.example` asks for `OPENROUTER_API_KEY` (one key, many models —
+ * https://openrouter.ai/models).
+ *
+ * Change the id and the key changes with it. Both live in `.env` and here; nothing else to wire.
  */
 /**
  * Who may run this agent, and against which conversation (ADR 0001).
@@ -48,7 +56,7 @@ export default AgentBuilder.create()
   // so setting it changed the model to exactly what it already was (#398, #408). One expression is
   // cheaper than an override path through the framework, and it keeps the value visible in the file
   // that decides it. The literal stays as the fallback: a scaffold has to run with no environment.
-  .model(process.env.LLM_MODEL ?? 'openai/gpt-4o-mini')
+  .model(process.env.LLM_MODEL ?? 'openrouter/openai/gpt-4o-mini')
   .system(BASE_INSTRUCTIONS)
   .tool(weatherTool)
   .tool(currentTimeTool)

package/templates/default/docs/ARCHITECTURE.md

@@ -59,7 +59,7 @@ An agent that outgrows one file becomes a folder that co-locates its own composi
 ```ts
 export default AgentBuilder.create()
   .input(z.object({ message: z.string() }))
-  .model('openai/gpt-4o-mini')
+  .model('openrouter/openai/gpt-4o-mini')
   .system(BASE_INSTRUCTIONS) // agents/prompts/instructions.ts
   .tool(weatherTool) // agents/tools/weather.ts
   .tool(currentTimeTool) // agents/tools/current-time.ts

package/templates/default/docs/CUSTOMIZATION.md

@@ -17,7 +17,7 @@ Common changes, and where they go. See [ARCHITECTURE](./ARCHITECTURE.md) for the
 
 ```ts
 // agents/tools/echo.ts
-import { tool } from 'theokit/server'
+import { tool } from 'theokit/server/define'
 import { z } from 'zod'
 
 export const echoTool = tool('echo')

package/templates/default/docs/ENVIRONMENT.md

@@ -8,9 +8,17 @@ Configuration lives in `.env` (copy `.env.example`). Nothing here is committed
 | `ANTHROPIC_API_KEY`  | one of these | Use Anthropic directly instead of OpenRouter.                                 |
 | `OPENAI_API_KEY`     | one of these | Use OpenAI directly.                                                          |
 
-The agent resolves the key from the environment at runtime (OpenRouter preferred). The model id in
-`agents/chat.ts` is provider-prefixed (e.g. `openai/gpt-4o-mini`) so OpenRouter routes it upstream — see
-<https://openrouter.ai/models>.
+The FIRST segment of the model id in `agents/chat.ts` picks the provider, and that decides which key
+is needed. It is not a hint: `openai/gpt-4o-mini` goes to OpenAI and needs `OPENAI_API_KEY`, even
+with an OpenRouter key present. Reaching another vendor's catalog THROUGH OpenRouter means naming
+the gateway first — `openrouter/openai/gpt-4o-mini`, which is what the scaffold declares, matching
+the key above. See <https://openrouter.ai/models> for the ids OpenRouter serves.
+
+| Model id in `agents/chat.ts`    | Key it needs         |
+| ------------------------------- | -------------------- |
+| `openrouter/openai/gpt-4o-mini` | `OPENROUTER_API_KEY` |
+| `anthropic/claude-sonnet-4-6`   | `ANTHROPIC_API_KEY`  |
+| `openai/gpt-4o-mini`            | `OPENAI_API_KEY`     |
 
 ```bash
 cp .env.example .env

package/templates/default/dot-claude/skills/theokit-agents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: theokit-agents
-description: TheoKit agent/LLM integration — agents/*.ts convention (defineAgent), @Agent decorator (advanced/DI), defineAgentTool, useAgent client hook
+description: TheoKit agent/LLM integration — agents/*.ts convention (AgentBuilder), the tool() builder, capabilities (advanced/DI), useAgent client hook
 user-invocable: false
 paths:
   - '**/*agent*'
@@ -25,7 +25,7 @@ import { z } from 'zod'
 
 export default defineAgent({
   input: z.object({ message: z.string() }),
-  model: 'openai/gpt-4o-mini',
+  model: 'openrouter/openai/gpt-4o-mini',
   system: 'You are a helpful assistant.',
 })
 ```
@@ -33,8 +33,11 @@ export default defineAgent({
 The endpoint streams the ai-sdk `UIMessageStream` that `useAgent` (client hook) consumes.
 `@theokit/sdk` runs the agent; conversation turns auto-persist per session — the SDK owns storage.
 
-**Provider resolution:** `OPENROUTER_API_KEY` (preferred — routes to many models) OR
-`ANTHROPIC_API_KEY` / `OPENAI_API_KEY`. Set one in `.env`.
+**Provider resolution:** the FIRST segment of the model id picks the provider, and that decides
+which key is needed — `openrouter/…` needs `OPENROUTER_API_KEY`, `anthropic/…` needs
+`ANTHROPIC_API_KEY`, `openai/…` needs `OPENAI_API_KEY`. A bare vendor prefix is a selection of that
+vendor, not a hint: reaching OpenAI's catalog through OpenRouter means naming the gateway first
+(`openrouter/openai/gpt-4o-mini`). Set the matching key in `.env`.
 
 ## Advanced Surface — @Agent Decorator (DI / class-based)
 
@@ -46,7 +49,7 @@ When you need dependency injection or composition, build the agent from **capabi
 import { applyCapabilities, AgentConfigCapability, ModelCapability } from '@theokit/agents'
 
 export const assistantAgent = applyCapabilities([
-  new ModelCapability('openai/gpt-4o-mini'),
+  new ModelCapability('openrouter/openai/gpt-4o-mini'),
   new AgentConfigCapability({
     systemPrompt: 'You are a helpful assistant.',
     maxIterations: 5,
@@ -55,32 +58,52 @@ export const assistantAgent = applyCapabilities([
 // The framework runs the LLM loop via @theokit/sdk.
 ```
 
-## Tools — defineAgentTool
+## Tools — `tool()`
 
-Declare typed tools with `defineAgentTool` (from `theokit/server`) and pass them to
-`defineAgent`'s `tools` array.
+Declare a tool with the `tool()` builder from `theokit/server/define`, then chain it onto the agent
+with `.tool(…)`. It is the same API `agents/tools/weather.ts` in this project uses — read that file
+for a working one.
+
+```typescript
+// agents/tools/current-time.ts
+import { tool } from 'theokit/server/define'
+import { z } from 'zod'
+
+export const currentTimeTool = tool('current_time')
+  .describe('Return the current ISO timestamp')
+  .input(z.object({}))
+  .execute(async () => new Date().toISOString())
+  .build()
+```
 
 ```typescript
 // agents/chat.ts
-import { defineAgent } from '@theokit/agents'
-import { defineAgentTool } from 'theokit/server'
+import { AgentBuilder } from '@theokit/agents'
 import { z } from 'zod'
 
-const currentTimeTool = defineAgentTool({
-  name: 'current_time',
-  description: 'Return the current ISO timestamp',
-  inputSchema: z.object({}),
-  handler: async () => new Date().toISOString(),
-})
+import { currentTimeTool } from './tools/current-time.js'
 
-export default defineAgent({
-  input: z.object({ message: z.string() }),
-  model: 'openai/gpt-4o-mini',
-  system: 'You are a helpful assistant.',
-  tools: [currentTimeTool],
-})
+export default AgentBuilder.create()
+  .input(z.object({ message: z.string() }))
+  .model('openrouter/openai/gpt-4o-mini')
+  .system('You are a helpful assistant.')
+  .tool(currentTimeTool)
+  .build()
 ```
 
+A tool is pure metadata plus a handler: it describes a capability and does local or HTTP work, and
+it NEVER calls an LLM — the agent decides when to invoke it.
+
+**Import from `theokit/server/define`, not `theokit/server`.** The umbrella subpath still resolves
+and prints a deprecation warning naming a removal release; every symbol lives under a domain
+subpath (`define`, `auth`, `http`, `security`, …).
+
+> **`defineAgentTool` does not exist.** Earlier versions of this skill taught it. The name is still
+> declared in the published `.d.ts`, so an editor will autocomplete it and `tsc` will accept it —
+> and there is no runtime export behind it on any subpath, so the call throws on the first request
+> (usetheokit/theokit#542). If you find it in older code or in a generated snippet, replace it with
+> the `tool()` builder above.
+
 ### Toolbox class (advanced — state + injected dependencies)
 
 A toolbox declares its tools as DATA and keeps handlers as ordinary methods, so the class can hold
@@ -174,7 +197,7 @@ Before writing custom tools, check if they already exist:
 ## Rules
 
 - Tool `name` and `description` are ALWAYS explicit — never inferred from method names (G4)
-- Tool `input` uses Zod schema — same pattern as defineRoute
+- Tool `.input()` takes a Zod schema — same pattern as `route().body(…)`
 - `@UseGuards()` works on agents (shared with HTTP pipeline)
 - `@UseInterceptors()` and `@UseFilters()` on agents are metadata-only (emit warnings)
 - Agent runtime is `@theokit/sdk` — NEVER call LLM APIs directly via fetch

package/templates/default/dot-claude/skills/theokit-config/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: theokit-config
-description: TheoKit configuration — defineConfig, plugins, security, storage, agents, build targets
+description: TheoKit configuration — the config() builder, plugins, security, storage, agents, build targets
 user-invocable: false
 paths:
   - 'theo.config*'
@@ -12,37 +12,39 @@ paths:
 ## theo.config.ts
 
 ```typescript
-import { defineConfig } from 'theokit'
-
-export default defineConfig({
-  // Basic
-  name: 'my-app', // DNS-1123 format (lowercase + hyphens)
-  port: 3000, // Dev + production port
-
-  // SSR (default: false)
-  ssr: false,
-
-  // Security (defaults are secure)
-  security: {
-    csrf: true, // CSRF protection (default: true)
-    csp: 'report-only', // Content Security Policy
-  },
-
-  // Agent runtime
-  agents: {
-    maxRegistries: 100,
-    registry: {
-      maxAgents: 100,
-      idleTimeoutMs: 30 * 60_000,
+import { config } from 'theokit'
+
+export default config()
+  .set({
+    // Basic
+    name: 'my-app', // DNS-1123 format (lowercase + hyphens)
+    port: 3000, // Dev + production port
+
+    // SSR (default: false)
+    ssr: false,
+
+    // Security (defaults are secure)
+    security: {
+      csrf: true, // CSRF protection (default: true)
+      csp: 'report-only', // Content Security Policy
+    },
+
+    // Agent runtime
+    agents: {
+      maxRegistries: 100,
+      registry: {
+        maxAgents: 100,
+        idleTimeoutMs: 30 * 60_000,
+      },
     },
-  },
 
-  // DevTools overlay (dev only)
-  devtools: true,
+    // DevTools overlay (dev only)
+    devtools: true,
 
-  // Plugins
-  plugins: [],
-})
+    // Plugins
+    plugins: [],
+  })
+  .build()
 ```
 
 ## Common Configuration Patterns
@@ -50,50 +52,58 @@ export default defineConfig({
 ### Adding CORS
 
 ```typescript
-import { defineConfig } from 'theokit'
-
-export default defineConfig({
-  // CORS is handled by the framework — configure in route-level or globally
-  security: {
-    cors: {
-      origin: ['http://localhost:3000', 'https://myapp.com'],
-      credentials: true,
+import { config } from 'theokit'
+
+export default config()
+  .set({
+    // CORS is handled by the framework — configure in route-level or globally
+    security: {
+      cors: {
+        origin: ['http://localhost:3000', 'https://myapp.com'],
+        credentials: true,
+      },
     },
-  },
-})
+  })
+  .build()
 ```
 
 ### Storage (Postgres + Redis)
 
 ```typescript
-export default defineConfig({
-  storage: {
-    postgres: [{ url: process.env.DATABASE_URL }],
-    redis: [{ url: process.env.REDIS_URL }],
-  },
-})
+export default config()
+  .set({
+    storage: {
+      postgres: [{ url: process.env.DATABASE_URL }],
+      redis: [{ url: process.env.REDIS_URL }],
+    },
+  })
+  .build()
 ```
 
 ### Rate Limiting
 
 ```typescript
-export default defineConfig({
-  rateLimit: {
-    global: { max: 100, windowMs: 60_000 },
-  },
-})
+export default config()
+  .set({
+    rateLimit: {
+      global: { max: 100, windowMs: 60_000 },
+    },
+  })
+  .build()
 ```
 
 ### OpenAPI Generation
 
 ```typescript
-export default defineConfig({
-  openapi: {
-    title: 'My App API',
-    version: '1.0.0',
-    outDir: '.theokit',
-  },
-})
+export default config()
+  .set({
+    openapi: {
+      title: 'My App API',
+      version: '1.0.0',
+      outDir: '.theokit',
+    },
+  })
+  .build()
 ```
 
 ## CLI Commands

package/templates/default/dot-claude/skills/theokit-gateways/SKILL.md

@@ -26,7 +26,7 @@ returns the `Response` your route must return.
 
 ```typescript
 import { handleChannelWebhook } from 'theokit/server/agent'
-import { telegram } from 'theokit/server/webhook' // also: discord, slack, github, stripe
+import { telegram } from 'theokit/server/webhook' // also: discord, slack, github, stripe, whatsapp
 import { parseInbound } from '@theokit/gateway-telegram'
 
 const response = await handleChannelWebhook(request, new URL(request.url).pathname, {
@@ -42,8 +42,36 @@ const response = await handleChannelWebhook(request, new URL(request.url).pathna
 The path it expects is `POST /api/agents/<name>/channels/<platform>/webhook`; `<name>` and
 `<platform>` arrive in `onMessage` as `agent` and `platform`.
 
+## Platforms that verify the endpoint first (WhatsApp, Instagram, Messenger)
+
+Meta will not deliver anything until it has verified the URL with a `GET` carrying
+`hub.mode=subscribe`, `hub.verify_token` and `hub.challenge`, and it requires the challenge echoed
+back as `text/plain`. Declare a responder per platform and mount the route for `GET` as well as
+`POST`:
+
+```typescript
+import { whatsapp, whatsappSubscribe } from 'theokit/server/webhook'
+
+const response = await handleChannelWebhook(request, new URL(request.url).pathname, {
+  validators: { whatsapp: whatsapp({ appSecret: process.env.META_APP_SECRET! }) },
+  subscribe: { whatsapp: whatsappSubscribe({ verifyToken: process.env.META_VERIFY_TOKEN! }) },
+  onMessage: async ({ payload }) => {
+    /* … */
+  },
+})
+```
+
+`appSecret` is the Meta **app secret**, not the access token — the signature is HMAC-SHA256 of it
+over the raw body. `verifyToken` is the string you typed into the Meta app when registering the URL;
+comparing it is the only thing standing between an arbitrary caller and a subscription. A `GET` for
+a platform with no `subscribe` entry answers `405`, not `404`: the platform is configured, it just
+does not do handshakes.
+
+Developing against any of this needs a public URL. `theo.config.ts` has `allowedHosts` for exactly
+that — see the framework README.
+
 **Give it a `Request` whose body has not been read.** It calls `request.json()` itself, so a wrapper
-that has already parsed the body — `defineRoute` offers a parsed `body` in its handler context —
+that has already parsed the body — `route().body(…)` offers a parsed `body` in its handler context —
 leaves nothing for it to read. Mount it where you still hold the original request, or pass a clone.
 
 `ChannelMessage` is `{ agent, platform, payload }`. There is no `request` inside `onMessage`, because

package/templates/default/dot-claude/skills/theokit-routes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: theokit-routes
-description: TheoKit server routes — defineRoute, Zod validation, HTTP methods, dynamic params, error handling
+description: TheoKit server routes — the route() builder, Zod validation, HTTP methods, dynamic params, error handling
 user-invocable: false
 paths:
   - 'server/routes/**'
@@ -9,41 +9,47 @@ paths:
 
 # TheoKit Routes
 
-## defineRoute API
+## The `route()` builder
 
 ```typescript
-import { defineRoute } from 'theokit/server/define'
+import { route } from 'theokit/server/define'
 import { z } from 'zod'
 
-// GET handler — no body, optional params/query
-export const GET = defineRoute({
-  policy: 'public',                              // who may call it — required
-  params: z.object({ id: z.coerce.number() }),   // URL params
-  query: z.object({ page: z.coerce.number().optional() }), // Query string
-  handler: ({ params, query }) => {
-    return { id: params.id, page: query?.page }
-  },
-})
-
-// POST handler — with body validation + custom status
-export const POST = defineRoute({
-  policy: ({ subject }) => subject !== null,     // any authenticated caller
-  body: z.object({
-    title: z.string().min(3),
-    done: z.boolean().default(false),
-  }),
-  status: 201,
-  handler: ({ body }) => {
-    // body is fully typed from Zod schema
+// GET — no body, optional params/query
+export const GET = route()
+  .policy('public') // who may call it — required
+  .params(z.object({ id: z.coerce.number() })) // URL params
+  .query(z.object({ page: z.coerce.number().optional() })) // query string
+  .handler(({ params, query }) => ({ id: params.id, page: query?.page }))
+  .build()
+
+// POST — body validation + custom status
+export const POST = route()
+  .policy(({ subject }) => subject !== null) // any authenticated caller
+  .body(
+    z.object({
+      title: z.string().min(3),
+      done: z.boolean().default(false),
+    }),
+  )
+  .status(201)
+  .handler(({ body }) => {
+    // body is fully typed from the Zod schema
     return db.insert(tasks).values(body).returning().get()
-  },
-})
-
-// PUT, DELETE follow the same pattern
-export const PUT = defineRoute({ policy: 'public', body: z.object({...}), handler: ({body, params}) => {...} })
-export const DELETE = defineRoute({ policy: 'public', params: z.object({id: z.coerce.number()}), handler: ({params}) => {...} })
+  })
+  .build()
 ```
 
+The chain is `.policy()`, `.params()`, `.query()`, `.body()`, `.status()`, `.response()`,
+`.csrf()`, `.handler()`, and `.build()` closes it. `server/routes/health.ts` in this project is a
+working one — read it rather than this block if the two ever disagree.
+
+`.csrf(false)` opts a single route out of CSRF enforcement. It is for endpoints that legitimately
+receive third-party POSTs — a Stripe or WhatsApp webhook, an OAuth callback — which authenticate by
+signature rather than by session. `policy('public')` answers a different question (may an
+unauthenticated caller reach this) and does NOT lift the CSRF gate: without `.csrf(false)` a webhook
+is refused `CSRF_INVALID` before its signature is ever checked.
+
 ## policy — who may call this route
 
 Required on every exported method. The scanner refuses a route file that omits it and names the
@@ -68,40 +74,40 @@ headers and no cookies: identity arrives as `subject`, established by the transp
 | `server/routes/tasks/[id].ts`      | `/api/tasks/:id`  | Dynamic param            |
 | `server/routes/users/[...slug].ts` | `/api/users/*`    | Catch-all                |
 
-## defineAction (Server Actions)
+## `action()` (Server Actions)
 
 ```typescript
-import { defineAction } from 'theokit/server/define'
+import { action } from 'theokit/server/define'
 import { z } from 'zod'
 
-export const createTask = defineAction({
-  input: z.object({ title: z.string() }),
-  handler: ({ input }) => {
-    return db.insert(tasks).values(input).returning().get()
-  },
-})
+export const createTask = action()
+  .input(z.object({ title: z.string() }))
+  .handler(({ input }) => db.insert(tasks).values(input).returning().get())
+  .build()
 ```
 
+The chain is `.input()`, `.accept()`, `.csrf()`, `.handler()`, and `.build()`.
+
 ## Error Handling
 
 ```typescript
-import { TheoError } from 'theokit'
+import { TheoError } from 'theokit/server/http'
 
-export const GET = defineRoute({
-  policy: 'public',
-  handler: ({ params }) => {
+export const GET = route()
+  .policy('public')
+  .handler(({ params }) => {
     const task = db.select().from(tasks).where(eq(tasks.id, params.id)).get()
     if (!task) throw new TheoError({ code: 'NOT_FOUND', message: 'Task not found' })
     return task
-  },
-})
+  })
+  .build()
 ```
 
 Valid error codes: `BAD_REQUEST` (400), `UNAUTHORIZED` (401), `FORBIDDEN` (403), `NOT_FOUND` (404), `CONFLICT` (409), `UNPROCESSABLE_ENTITY` (422), `TOO_MANY_REQUESTS` (429), `INTERNAL_SERVER_ERROR` (500).
 
 ## Anti-patterns
 
-- NEVER use `res.status().json()` — use defineRoute with `status:` option
-- NEVER parse `req.body` manually — use `body: z.object(...)` in defineRoute
+- NEVER use `res.status().json()` — use `.status(201)` on the `route()` chain
+- NEVER parse `req.body` manually — use `.body(z.object({ … }))` on the chain
 - NEVER create routes outside `server/routes/` — they won't be discovered
 - NEVER export non-HTTP-method names — only `GET`, `POST`, `PUT`, `DELETE`, `PATCH`

package/templates/default/package.json.tmpl

@@ -16,7 +16,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.56.0",
+    "theokit": "^0.60.0",
     "@theokit/agents": "^10.1.0",
     "@theokit/sdk": "^4.52.1",
     "@theokit/ui": "^1.1.0",