create-theokit 1.23.8 → 1.23.11

package/templates/default/app/page.test.tsx

@@ -1,7 +1,10 @@
 // @vitest-environment jsdom
 import { render, screen } from '@testing-library/react'
 import { describe, it, expect } from 'vitest'
-import { ChatThread, ChatMessage, type UIMessage } from '@theokit/ui'
+import { ChatThread, ChatMessage } from '@theokit/ui'
+import { type UIMessage } from 'theokit/client'
+
+import { toRenderable } from './lib/renderable'
 import Page from './page'
 
 /**
@@ -22,7 +25,10 @@ describe('default chat page', () => {
     expect(screen.getByLabelText('New chat')).toBeDefined()
   })
 
-  it('ChatMessage accepts a UIMessage and renders its message container (auto-dispatch)', () => {
+  it('a streamed message renders through the conversion the app actually uses', () => {
+    // Typed as what `useAgent()` RETURNS, not as what `<ChatMessage>` takes. Those are different
+    // types on purpose, and a scaffold that conflated them failed its own typecheck twice
+    // (usetheokit/theokit#80, #396). `toRenderable` is the seam, and this is what exercises it.
     const assistant: UIMessage = {
       id: 'a-0',
       role: 'assistant',
@@ -30,7 +36,7 @@ describe('default chat page', () => {
     }
     const { container } = render(
       <ChatThread>
-        <ChatMessage message={assistant} />
+        <ChatMessage message={toRenderable(assistant)} />
       </ChatThread>,
     )
     expect(container.querySelector('[data-slot="chat-message"]')).not.toBeNull()

package/templates/default/docs/ARCHITECTURE.md

@@ -60,10 +60,10 @@ An agent that outgrows one file becomes a folder that co-locates its own composi
 export default AgentBuilder.create()
   .input(z.object({ message: z.string() }))
   .model('openai/gpt-4o-mini')
-  .system(BASE_INSTRUCTIONS)   // agents/prompts/instructions.ts
-  .tool(weatherTool)           // agents/tools/weather.ts
-  .tool(currentTimeTool)       // agents/tools/current-time.ts
-  .skills([dailyBriefingSkill])                 // agents/skills/daily-briefing.ts
+  .system(BASE_INSTRUCTIONS) // agents/prompts/instructions.ts
+  .tool(weatherTool) // agents/tools/weather.ts
+  .tool(currentTimeTool) // agents/tools/current-time.ts
+  .skills([dailyBriefingSkill]) // agents/skills/daily-briefing.ts
   .build()
 ```
 
@@ -77,11 +77,11 @@ loaded by the model on demand via the `skill_read` tool, so long procedures don'
 
 The same agent is reached from three interchangeable frontends — only the transport differs:
 
-| Surface | Frontend dir | Transport |
-|---------|--------------|-----------|
-| web | `app/` | `HttpTransport` (`/api/agents/chat`) |
-| tui | `tui/` | `InProcessTransport` |
-| desktop | `frontend/` | `ChannelTransport` (`@theokit/tauri`) |
+| Surface | Frontend dir | Transport                             |
+| ------- | ------------ | ------------------------------------- |
+| web     | `app/`       | `HttpTransport` (`/api/agents/chat`)  |
+| tui     | `tui/`       | `InProcessTransport`                  |
+| desktop | `frontend/`  | `ChannelTransport` (`@theokit/tauri`) |
 
 All three render the same `@theokit/ui` chat and read `shared/agent.ts` for the greeting + model label.
 
@@ -89,19 +89,19 @@ All three render the same `@theokit/ui` chat and read `shared/agent.ts` for the
 
 The web `app/` is organized **type-based**, the layout most React apps grow into:
 
-| Folder | Holds | Example |
-|---|---|---|
-| `app/` root | the **route surface** — the only files the router serves | `page.tsx`, `layout.tsx`, `error/loading/not-found.tsx` |
-| `components/` | presentational UI (flat `.tsx`; Tailwind, no CSS modules) | `Header`, `ChatPanel`, `Composer` |
-| `hooks/` | custom hooks — where **state** lives | `use-transcript.ts` |
-| `lib/` | app modules / config | `constants.ts` |
+| Folder        | Holds                                                     | Example                                                 |
+| ------------- | --------------------------------------------------------- | ------------------------------------------------------- |
+| `app/` root   | the **route surface** — the only files the router serves  | `page.tsx`, `layout.tsx`, `error/loading/not-found.tsx` |
+| `components/` | presentational UI (flat `.tsx`; Tailwind, no CSS modules) | `Header`, `ChatPanel`, `Composer`                       |
+| `hooks/`      | custom hooks — where **state** lives                      | `use-transcript.ts`                                     |
+| `lib/`        | app modules / config                                      | `constants.ts`                                          |
 
 ### Route files are not components
 
 `page` · `layout` · `loading` · `error` · `not-found` are **route conventions**, not components. The
 router binds them by **name + location**: matched by `^(page|layout|error|loading|not-found)\.(tsx|ts|jsx|js)$`
 at a route segment (the `app/` root is the `/` route). `loading.tsx` becomes that route's Suspense
-fallback, `error.tsx` its error boundary — *because they sit there, with that name*.
+fallback, `error.tsx` its error boundary — _because they sit there, with that name_.
 
 So `loading.tsx` looks like a component (it renders a spinner) but it is **not** one — move it into
 `components/` and the router no longer finds it, and the route loses its loading UI. This is exactly the
@@ -114,12 +114,12 @@ Two rules make the rest work and keep it honest:
 
 1. **State in a hook, view in components.** This is the pattern every serious chat frontend converges on
    (Vercel `ai-chatbot`, the AI SDK docs). `page.tsx` is a thin composition root — it lays out `<ChatPanel>`
-   + `<Composer>` and pulls transcript state from `useChatTranscript`. The tricky history + in-flight merge
-   is isolated + unit-tested (`hooks/use-transcript.test.ts`); the components are dumb and prop-driven.
+   - `<Composer>` and pulls transcript state from `useChatTranscript`. The tricky history + in-flight merge
+     is isolated + unit-tested (`hooks/use-transcript.test.ts`); the components are dumb and prop-driven.
 2. **Folders aren't routes.** A folder is served only when it holds a `page`/`layout`/… file, so
    `components/`, `hooks/`, `lib/` are never routes (Next-style colocation). Add `utils/`, `styles/`,
    `assets/` when you actually have a helper, a global stylesheet, or an image — a scaffold ships the
-   folders it *uses*, not empty placeholders (YAGNI).
+   folders it _uses_, not empty placeholders (YAGNI).
 
 The entry point is framework-owned — there is no `main.tsx`/`index.js`. Routes are files (`page.tsx`), not
 a `pages/` folder you wire by hand: that's the Next.js-style convention TheoKit is built on.
@@ -129,12 +129,12 @@ a `pages/` folder you wire by hand: that's the Next.js-style convention TheoKit
 Routing is **file-based**: a screen is a folder under `app/` with a `page.tsx`. The folder name is the URL
 segment; the home screen is the flat `app/page.tsx`.
 
-| You want | Create | Serves |
-|---|---|---|
-| a `/settings` screen | `app/settings/page.tsx` | `/settings` |
-| a nested screen | `app/settings/billing/page.tsx` | `/settings/billing` |
-| a dynamic screen | `app/users/[id]/page.tsx` | `/users/:id` (read the param with react-router's `useParams`) |
-| a catch-all | `app/docs/[...slug]/page.tsx` | `/docs/*` |
+| You want             | Create                          | Serves                                                        |
+| -------------------- | ------------------------------- | ------------------------------------------------------------- |
+| a `/settings` screen | `app/settings/page.tsx`         | `/settings`                                                   |
+| a nested screen      | `app/settings/billing/page.tsx` | `/settings/billing`                                           |
+| a dynamic screen     | `app/users/[id]/page.tsx`       | `/users/:id` (read the param with react-router's `useParams`) |
+| a catch-all          | `app/docs/[...slug]/page.tsx`   | `/docs/*`                                                     |
 
 The one-command way: **`theokit generate page settings`** creates `app/settings/page.tsx` for you. Each
 screen can have its own `layout.tsx` / `loading.tsx` / `error.tsx` / `not-found.tsx` (the route special
@@ -144,10 +144,16 @@ files, scoped to that segment).
 `<Outlet/>`), but prefer TheoKit's own client primitives over the raw react-router ones:
 
 ```tsx
-import { Link } from 'theokit/client'      // react-router Link + route prefetch (intent | viewport)
-import { useLocation } from 'react-router'  // for active-link styling
-
-<Link to="/settings" prefetch="intent">Settings</Link>
+import { Link } from 'theokit/client' // react-router Link + route prefetch (intent | viewport)
+import { useLocation } from 'react-router' // for active-link styling
+
+export function SettingsLink() {
+  return (
+    <Link to="/settings" prefetch="intent">
+      Settings
+    </Link>
+  )
+}
 ```
 
 TheoKit's `theokit/client` gives you the Next-parity building blocks: **`Link`** (prefetch), **`Metadata`**

package/templates/default/docs/CUSTOMIZATION.md

@@ -2,16 +2,16 @@
 
 Common changes, and where they go. See [ARCHITECTURE](./ARCHITECTURE.md) for the full layout.
 
-| I want to… | Edit |
-|------------|------|
-| Change the model | `agents/chat.ts` (`.model(...)`) + the label in `shared/agent.ts` |
-| Change the persona / rules | `agents/prompts/instructions.ts` |
-| Add a tool (an action the agent can take) | new `agents/tools/<name>.ts`, then `.tool(<name>Tool)` in `agents/chat.ts` |
-| Add a skill (a procedure the model loads on demand) | `Skill.create(...)` in `agents/skills/<name>.ts`, then add it to `.skills([...])` in `agents/chat.ts` |
-| Add a second agent | new `agents/<name>.ts` → auto-served at `/api/agents/<name>`, bind with `useAgent('<name>')` |
-| Change the greeting / app name | `shared/agent.ts` |
-| Add a backend route | `server/routes/<name>.ts` |
-| Change the provider key | `.env` — `OPENROUTER_API_KEY` (or `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`). See [ENVIRONMENT](./ENVIRONMENT.md) |
+| I want to…                                          | Edit                                                                                                           |
+| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Change the model                                    | `agents/chat.ts` (`.model(...)`) + the label in `shared/agent.ts`                                              |
+| Change the persona / rules                          | `agents/prompts/instructions.ts`                                                                               |
+| Add a tool (an action the agent can take)           | new `agents/tools/<name>.ts`, then `.tool(<name>Tool)` in `agents/chat.ts`                                     |
+| Add a skill (a procedure the model loads on demand) | `Skill.create(...)` in `agents/skills/<name>.ts`, then add it to `.skills([...])` in `agents/chat.ts`          |
+| Add a second agent                                  | new `agents/<name>.ts` → auto-served at `/api/agents/<name>`, bind with `useAgent('<name>')`                   |
+| Change the greeting / app name                      | `shared/agent.ts`                                                                                              |
+| Add a backend route                                 | `server/routes/<name>.ts`                                                                                      |
+| Change the provider key                             | `.env` — `OPENROUTER_API_KEY` (or `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`). See [ENVIRONMENT](./ENVIRONMENT.md) |
 
 ## Adding a tool
 

package/templates/default/docs/ENVIRONMENT.md

@@ -2,11 +2,11 @@
 
 Configuration lives in `.env` (copy `.env.example`). Nothing here is committed — `.env` is gitignored.
 
-| Variable | Required | What it does |
-|----------|----------|--------------|
+| Variable             | Required     | What it does                                                                  |
+| -------------------- | ------------ | ----------------------------------------------------------------------------- |
 | `OPENROUTER_API_KEY` | one of these | Provider key. OpenRouter is the default gateway (many models behind one key). |
-| `ANTHROPIC_API_KEY` | one of these | Use Anthropic directly instead of OpenRouter. |
-| `OPENAI_API_KEY` | one of these | Use OpenAI directly. |
+| `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

package/templates/default/dot-claude/rules/theokit-conventions.md

@@ -19,6 +19,8 @@
 
 - File at `server/routes/tasks/[id].ts` maps to `/api/tasks/:id`
 - Export HTTP method handlers: `export const GET = defineRoute({...})`
+- 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
 - Use `status: 201` for creation responses, not manual `res.status()`
 

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

@@ -3,17 +3,17 @@ name: theokit-agents
 description: TheoKit agent/LLM integration — agents/*.ts convention (defineAgent), @Agent decorator (advanced/DI), defineAgentTool, useAgent client hook
 user-invocable: false
 paths:
-  - "**/*agent*"
-  - "**/*Agent*"
-  - "**/*tool*"
-  - "**/*Tool*"
-  - "**/*toolbox*"
-  - "**/*Toolbox*"
+  - '**/*agent*'
+  - '**/*Agent*'
+  - '**/*tool*'
+  - '**/*Tool*'
+  - '**/*toolbox*'
+  - '**/*Toolbox*'
 ---
 
 # TheoKit Agents & Tools
 
-## Server Surface — agents/*.ts (zero-config convention)
+## Server Surface — agents/\*.ts (zero-config convention)
 
 Create an `agents/<name>.ts` file at the project root. It is automatically served at
 `POST /api/agents/<name>` (dev + build) with no manual route wiring.
@@ -162,12 +162,12 @@ consumeUIMessageStream(response, (message) => {
 
 Before writing custom tools, check if they already exist:
 
-| Package | What it provides | When to use |
-|---------|-----------------|-------------|
-| `@theokit/sdk` | `Agent.create()`, `Tool.create()` (primitive), `Run.stream()` | Core agent runtime — always installed |
+| Package              | What it provides                                                                                                                 | When to use                                                        |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `@theokit/sdk`       | `Agent.create()`, `Tool.create()` (primitive), `Run.stream()`                                                                    | Core agent runtime — always installed                              |
 | `@theokit/sdk-tools` | Ready-made tools: `createReadFileTool`, `createWriteFileTool`, `createSearchTextTool`, `createGlobTool`, `createShellTool`, etc. | **Check here FIRST** before writing custom tools for coding agents |
-| `@theokit/di-agent` | DI-powered agent with decorator injection | When using dependency injection pattern |
-| `@theokit/di` | Core DI container (`@Injectable`, `@Inject`) | When `@theokit/di-agent` needs explicit bindings |
+| `@theokit/di-agent`  | DI-powered agent with decorator injection                                                                                        | When using dependency injection pattern                            |
+| `@theokit/di`        | Core DI container (`@Injectable`, `@Inject`)                                                                                     | When `@theokit/di-agent` needs explicit bindings                   |
 
 **`Tool.create()` in `@theokit/sdk` is the primitive API.** For coding agents, `@theokit/sdk-tools` has batteries-included tools that wrap `Tool.create()` with file system access, search, shell execution, etc. Don't reimplement what `sdk-tools` already provides.
 

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

@@ -3,8 +3,8 @@ name: theokit-config
 description: TheoKit configuration — defineConfig, plugins, security, storage, agents, build targets
 user-invocable: false
 paths:
-  - "theo.config*"
-  - "**/*config*"
+  - 'theo.config*'
+  - '**/*config*'
 ---
 
 # TheoKit Configuration
@@ -16,16 +16,16 @@ import { defineConfig } from 'theokit'
 
 export default defineConfig({
   // Basic
-  name: 'my-app',            // DNS-1123 format (lowercase + hyphens)
-  port: 3000,                // Dev + production port
+  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
+    csrf: true, // CSRF protection (default: true)
+    csp: 'report-only', // Content Security Policy
   },
 
   // Agent runtime

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

@@ -3,11 +3,11 @@ name: theokit-database
 description: TheoKit database — Drizzle ORM, SQLite schema, migrations, seeds, db commands
 user-invocable: false
 paths:
-  - "**/*schema*"
-  - "**/*db*"
-  - "**/drizzle*"
-  - "**/*migration*"
-  - "**/*seed*"
+  - '**/*schema*'
+  - '**/*db*'
+  - '**/drizzle*'
+  - '**/*migration*'
+  - '**/*seed*'
 ---
 
 # TheoKit Database (Drizzle + SQLite)
@@ -22,7 +22,9 @@ export const tasks = sqliteTable('tasks', {
   id: integer('id').primaryKey({ autoIncrement: true }),
   title: text('title').notNull(),
   done: integer('done', { mode: 'boolean' }).notNull().default(false),
-  createdAt: text('created_at').notNull().default(sql`CURRENT_TIMESTAMP`),
+  createdAt: text('created_at')
+    .notNull()
+    .default(sql`CURRENT_TIMESTAMP`),
 })
 
 export const users = sqliteTable('users', {
@@ -74,10 +76,13 @@ db.delete(tasks).where(eq(tasks.id, 1)).run()
 import { db } from './index.js'
 import { tasks } from './schema.js'
 
-await db.insert(tasks).values([
-  { title: 'Learn TheoKit', done: false },
-  { title: 'Build an agent', done: false },
-]).run()
+await db
+  .insert(tasks)
+  .values([
+    { title: 'Learn TheoKit', done: false },
+    { title: 'Build an agent', done: false },
+  ])
+  .run()
 
 console.log('Seeded database')
 ```

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

@@ -3,22 +3,22 @@ name: theokit-frontend
 description: TheoKit frontend — file-based routing, layouts, theoFetch typed client, useAgent, React patterns
 user-invocable: false
 paths:
-  - "app/**"
+  - 'app/**'
 ---
 
 # TheoKit Frontend (React + File-Based Routing)
 
 ## File-Based Routing
 
-| File | URL | Purpose |
-|------|-----|---------|
-| `app/page.tsx` | `/` | Home page |
-| `app/layout.tsx` | (wrapper) | Root layout (wraps all pages) |
-| `app/error.tsx` | (error) | Error boundary |
-| `app/loading.tsx` | (loading) | Suspense fallback |
-| `app/not-found.tsx` | (404) | Not found page |
-| `app/about/page.tsx` | `/about` | Nested route |
-| `app/tasks/[id]/page.tsx` | `/tasks/:id` | Dynamic route |
+| File                      | URL          | Purpose                       |
+| ------------------------- | ------------ | ----------------------------- |
+| `app/page.tsx`            | `/`          | Home page                     |
+| `app/layout.tsx`          | (wrapper)    | Root layout (wraps all pages) |
+| `app/error.tsx`           | (error)      | Error boundary                |
+| `app/loading.tsx`         | (loading)    | Suspense fallback             |
+| `app/not-found.tsx`       | (404)        | Not found page                |
+| `app/about/page.tsx`      | `/about`     | Nested route                  |
+| `app/tasks/[id]/page.tsx` | `/tasks/:id` | Dynamic route                 |
 
 ## Typed API Client (theoFetch)
 
@@ -98,7 +98,7 @@ consumeUIMessageStream(response, (message) => {
 ## Path Aliases
 
 ```typescript
-import { db } from '@/server/db'          // @/ = project root
+import { db } from '@/server/db' // @/ = project root
 import { tasks } from '@/server/db/schema'
 ```
 

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

@@ -0,0 +1,71 @@
+---
+name: theokit-gateways
+description: Receiving messages from Telegram, WhatsApp, Slack and other platforms — handleChannelWebhook, the @theokit/gateway-* adapters, signature validation, the onMessage seam
+user-invocable: false
+paths:
+  - 'server/routes/**'
+  - 'server/channels/**'
+  - '**/*gateway*'
+  - '**/*webhook*'
+---
+
+# TheoKit Gateways
+
+Receiving a message from a messaging platform spans three packages, and each owns one part of it.
+
+| Package              | Its half                                                                                                                                                         |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `theokit` (here)     | The HTTP route and the signature check. `handleChannelWebhook` verifies the signature, parses the body, and hands your app the parsed JSON as `payload: unknown` |
+| `@theokit/gateway-*` | Translating that payload into a canonical event, so your app never re-declares a platform's wire format                                                          |
+| `@theokit/sdk`       | Not involved in this path today                                                                                                                                  |
+
+## Wiring one
+
+`handleChannelWebhook` is not mounted for you. It takes a `Request`, the URL path, and a config, and
+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 { parseInbound } from '@theokit/gateway-telegram'
+
+const response = await handleChannelWebhook(request, new URL(request.url).pathname, {
+  validators: { telegram: telegram({ secretToken: process.env.TELEGRAM_SECRET_TOKEN! }) },
+  onMessage: async ({ agent, platform, payload }) => {
+    const event = parseInbound(payload)
+    if (event === null) return // not a message this adapter handles — see below
+    // hand `event` to your agent
+  },
+})
+```
+
+The path it expects is `POST /api/agents/<name>/channels/<platform>/webhook`; `<name>` and
+`<platform>` arrive in `onMessage` as `agent` and `platform`.
+
+**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 —
+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
+the body was read and the signature checked before it ran.
+
+## Never throw out of `onMessage`
+
+`onMessage` is awaited **before** the 200 is built, and `handleChannelWebhook` does not catch around
+it. A throw there means the 200 is never built: mounted in a TheoKit route, the rejection reaches
+that route's error boundary and is answered 500 — the platform sees a failed delivery where it
+expected an acknowledgement.
+
+This is why every adapter's translator returns `null` (or `undefined`) for a payload it does not
+recognise rather than throwing. Handle the `null` and answer normally.
+
+## Which adapters go through this seam
+
+Only platforms that deliver by **webhook**. Telegram and the SMS providers export `parseInbound`
+under that name; LINE, WhatsApp Cloud and Teams export their translation under their own names, each
+with its own signature — read the one you are using.
+
+Adapters whose transport is a long-lived connection — Discord, Slack, Mattermost, Matrix, e-mail,
+and WhatsApp's `web` and `baileys` backends — do **not** go through this seam. They own their
+transport, and running one alongside a TheoKit server needs a process lifecycle this scaffold does
+not set up.

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

@@ -3,8 +3,8 @@ name: theokit-routes
 description: TheoKit server routes — defineRoute, Zod validation, HTTP methods, dynamic params, error handling
 user-invocable: false
 paths:
-  - "server/routes/**"
-  - "server/actions/**"
+  - 'server/routes/**'
+  - 'server/actions/**'
 ---
 
 # TheoKit Routes
@@ -17,6 +17,7 @@ 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 }) => {
@@ -26,6 +27,7 @@ export const GET = defineRoute({
 
 // 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),
@@ -38,18 +40,33 @@ export const POST = defineRoute({
 })
 
 // PUT, DELETE follow the same pattern
-export const PUT = defineRoute({ body: z.object({...}), handler: ({body, params}) => {...} })
-export const DELETE = defineRoute({ params: z.object({id: z.coerce.number()}), handler: ({params}) => {...} })
+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}) => {...} })
 ```
 
+## policy — who may call this route
+
+Required on every exported method. The scanner refuses a route file that omits it and names the
+file, so absence is a build error rather than a route silently open to everyone.
+
+```typescript
+policy: 'public' // open, and said out loud
+policy: ({ subject }) => subject !== null // any authenticated caller
+policy: ({ subject, params }) => requireOwner(subject, ownerOf(params.id)) // this subject owns this record
+```
+
+`requireOwner` comes from `theokit/server`. The policy is evaluated identically over HTTP and
+in-process, so a desktop or terminal surface gets the same answer a browser does. It receives no
+headers and no cookies: identity arrives as `subject`, established by the transport.
+
 ## File-to-URL Mapping
 
-| File path | URL | Notes |
-|-----------|-----|-------|
-| `server/routes/health.ts` | `GET /api/health` | Static route |
-| `server/routes/tasks/index.ts` | `/api/tasks` | Index route (GET + POST) |
-| `server/routes/tasks/[id].ts` | `/api/tasks/:id` | Dynamic param |
-| `server/routes/users/[...slug].ts` | `/api/users/*` | Catch-all |
+| File path                          | URL               | Notes                    |
+| ---------------------------------- | ----------------- | ------------------------ |
+| `server/routes/health.ts`          | `GET /api/health` | Static route             |
+| `server/routes/tasks/index.ts`     | `/api/tasks`      | Index route (GET + POST) |
+| `server/routes/tasks/[id].ts`      | `/api/tasks/:id`  | Dynamic param            |
+| `server/routes/users/[...slug].ts` | `/api/users/*`    | Catch-all                |
 
 ## defineAction (Server Actions)
 
@@ -71,6 +88,7 @@ export const createTask = defineAction({
 import { TheoError } from 'theokit'
 
 export const GET = defineRoute({
+  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' })

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

@@ -1,15 +1,15 @@
 ---
 name: theokit-ui
-description: "@theokit/ui AI-native component library — AI-agent surfaces (ChatThread, ChatMessage, ChatComposer, ToolCallCard, AgentStream), theming, providers; generic primitives (CodeBlock, Sidebar, Button) come from @usetheo/ui"
+description: '@theokit/ui AI-native component library — AI-agent surfaces (ChatThread, ChatMessage, ChatComposer, ToolCallCard, AgentStream), theming, providers; generic primitives (CodeBlock, Sidebar, Button) come from @usetheo/ui'
 user-invocable: false
 paths:
-  - "app/**"
-  - "**/*Chat*"
-  - "**/*chat*"
-  - "**/*Sidebar*"
-  - "**/*sidebar*"
-  - "**/*theme*"
-  - "**/*Theme*"
+  - 'app/**'
+  - '**/*Chat*'
+  - '**/*chat*'
+  - '**/*Sidebar*'
+  - '**/*sidebar*'
+  - '**/*theme*'
+  - '**/*Theme*'
 ---
 
 # @theokit/ui — AI-native Component Library (AI-agent surfaces)
@@ -99,31 +99,32 @@ function ChatPage() {
 
 ### AI-agent-surface components (from `@theokit/ui`)
 
-| Component | Purpose | Key Props |
-|-----------|---------|-----------|
-| `ChatThread` | Scrollable message container | `children` (ChatMessage elements) |
-| `ChatMessage` | Single message bubble | `role: 'user' \| 'assistant'`, `children` |
-| `ChatMessageContent` | Markdown + code rendering | `markdown: string` (handles streaming partial) |
-| `ChatComposer` | Message input + submit | `onSubmit: (text) => void`, `disabled?: boolean` |
-| `ToolCallCard` | Display agent tool invocations | — |
-| `AgentStream` | Lower-level stream renderer | — |
+| Component            | Purpose                        | Key Props                                        |
+| -------------------- | ------------------------------ | ------------------------------------------------ |
+| `ChatThread`         | Scrollable message container   | `children` (ChatMessage elements)                |
+| `ChatMessage`        | Single message bubble          | `role: 'user' \| 'assistant'`, `children`        |
+| `ChatMessageContent` | Markdown + code rendering      | `markdown: string` (handles streaming partial)   |
+| `ChatComposer`       | Message input + submit         | `onSubmit: (text) => void`, `disabled?: boolean` |
+| `ToolCallCard`       | Display agent tool invocations | —                                                |
+| `AgentStream`        | Lower-level stream renderer    | —                                                |
 
 ### Generic primitives (from `@usetheo/ui`)
 
 Moved out of `@theokit/ui` in the 2026-07-03 AI-exclusive pivot. Import these from `@usetheo/ui`.
 
-| Component | Purpose | Key Props |
-|-----------|---------|-----------|
-| `CodeBlock` | Syntax-highlighted code | `code: string`, `language?: string` (uses shiki, lazy-loaded) |
-| `PageShell` | App layout with sidebar slot | `sidebar?: ReactNode`, `children` |
-| `Sidebar` | Collapsible side panel | `children` |
-| `Button`, `Input`, `Textarea` | Form primitives (themed) | — |
-| `Avatar` | User/agent avatar | — |
-| `Alert` | Status messages | — |
+| Component                     | Purpose                      | Key Props                                                     |
+| ----------------------------- | ---------------------------- | ------------------------------------------------------------- |
+| `CodeBlock`                   | Syntax-highlighted code      | `code: string`, `language?: string` (uses shiki, lazy-loaded) |
+| `PageShell`                   | App layout with sidebar slot | `sidebar?: ReactNode`, `children`                             |
+| `Sidebar`                     | Collapsible side panel       | `children`                                                    |
+| `Button`, `Input`, `Textarea` | Form primitives (themed)     | —                                                             |
+| `Avatar`                      | User/agent avatar            | —                                                             |
+| `Alert`                       | Status messages              | —                                                             |
 
 ## Peer Dependencies (install only what you use)
 
 **Chat/markdown path** (most apps need these):
+
 ```bash
 npm install mdast-util-from-markdown mdast-util-to-hast mdast-util-gfm \
   hast-util-to-jsx-runtime hast-util-sanitize hast-util-from-html \
@@ -131,6 +132,7 @@ npm install mdast-util-from-markdown mdast-util-to-hast mdast-util-gfm \
 ```
 
 **DO NOT install** unless you use the specific components:
+
 - `mermaid` — only for diagram rendering components
 - `katex` — only for math/LaTeX rendering
 - `roughjs` / `perfect-freehand` — only for whiteboard/drawing components

package/templates/default/eslint.config.mjs

@@ -2,7 +2,14 @@ import tseslint from 'typescript-eslint'
 import prettierConfig from 'eslint-config-prettier'
 
 export default tseslint.config(
-  { ignores: ['dist/', 'node_modules/'] },
+  // `.theokit/` is build output — `theokit build` writes generated `.d.ts` there, and linting it
+  // reports ~1800 style findings in code nobody wrote. A developer who adds a real error of their
+  // own then cannot find it, which is the whole cost: not a broken build, a useless gate.
+  //
+  // ESLint flat config does NOT read `.gitignore`, so the one file that already knows what is
+  // generated is not the file ESLint consults. `@eslint/compat`'s `includeIgnoreFile` would close
+  // that permanently and is worth considering; this is the one-line version that works today.
+  { ignores: ['dist/', 'node_modules/', '.theokit/'] },
   ...tseslint.configs.recommended,
   prettierConfig,
   {