create-theokit 1.25.1 → 1.25.3

package/package.json

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

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/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/dot-claude/rules/theokit-conventions.md

@@ -2,7 +2,7 @@
 
 ## Imports
 
-- Use `theokit/server/define` for defineRoute, defineAction, defineWebSocket
+- Use `theokit/server/define` for `route()`, `action()`, `websocket()`, `tool()`
 - Use `theokit/client` for theoFetch, createAppClient
 - Use `theokit/server/auth` for session/auth APIs
 - NEVER import from `theokit/dist/...` or `theokit/src/...`
@@ -13,12 +13,12 @@
 - Zod is the single source of truth for types and validation
 - Define schema ONCE with `z.object(...)`, derive types with `z.infer<>`
 - NEVER duplicate a Zod schema as a manual TypeScript interface
-- NEVER parse request body manually — use `body:` in defineRoute
+- NEVER parse request body manually — use `.body(z.object({ … }))` on the `route()` chain
 
 ## Routes
 
 - File at `server/routes/tasks/[id].ts` maps to `/api/tasks/:id`
-- Export HTTP method handlers: `export const GET = defineRoute({...})`
+- Export HTTP method handlers: `export const GET = route().policy('public').handler(…).build()`
 - Every method declares `policy` — who may call it. `'public'` is a valid answer and an explicit one;
   omitting it fails the build with the file named
 - Use `params: z.object({...})` for URL params, `body:` for request body

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*'
@@ -20,14 +20,14 @@ Create an `agents/<name>.ts` file at the project root. It is automatically serve
 
 ```typescript
 // agents/chat.ts
-import { defineAgent } from '@theokit/agents'
+import { AgentBuilder } from '@theokit/agents'
 import { z } from 'zod'
 
-export default defineAgent({
-  input: z.object({ message: z.string() }),
-  model: 'openrouter/openai/gpt-4o-mini',
-  system: 'You are a helpful assistant.',
-})
+export default AgentBuilder.create()
+  .input(z.object({ message: z.string() }))
+  .model('openrouter/openai/gpt-4o-mini')
+  .system('You are a helpful assistant.')
+  .build()
 ```
 
 The endpoint streams the ai-sdk `UIMessageStream` that `useAgent` (client hook) consumes.
@@ -58,32 +58,52 @@ export const assistantAgent = applyCapabilities([
 // The framework runs the LLM loop via @theokit/sdk.
 ```
 
-## Tools — defineAgentTool
+## Tools — `tool()`
+
+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'
 
-Declare typed tools with `defineAgentTool` (from `theokit/server`) and pass them to
-`defineAgent`'s `tools` array.
+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: 'openrouter/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
@@ -177,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
@@ -185,7 +205,7 @@ Before writing custom tools, check if they already exist:
 
 ## Anti-patterns
 
-- NEVER call OpenAI/Anthropic/OpenRouter APIs directly — use `defineAgent` or `@Agent`
+- NEVER call OpenAI/Anthropic/OpenRouter APIs directly — use `AgentBuilder.create()`
 - NEVER reimplement tool calling loop — the SDK handles it
 - NEVER reimplement file/search/shell tools — use `@theokit/sdk-tools` (readFile, writeFile, search, etc.)
 - NEVER store conversations manually — SDK persistence is automatic (the SDK owns storage)

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
@@ -125,4 +135,4 @@ Env vars are loaded from `.env` (dev) and `.env.production` (build). NEVER commi
 - NEVER hardcode secrets in theo.config.ts — use environment variables
 - NEVER set `security.csrf: false` in production
 - NEVER use `ssr: true` without understanding hydration (start with `false`)
-- NEVER add plugins that don't match `defineTheoPlugin` interface
+- NEVER add plugins that don't match `TheoPlugin` interface

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

@@ -71,7 +71,7 @@ Developing against any of this needs a public URL. `theo.config.ts` has `allowed
 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`