create-theokit 1.23.7 → 1.23.10

package/package.json

@@ -1,8 +1,17 @@
 {
   "name": "create-theokit",
-  "version": "1.23.7",
+  "version": "1.23.10",
   "type": "module",
   "description": "Scaffold a new TheoKit project",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/usetheokit/theokit.git",
+    "directory": "packages/create-theokit"
+  },
+  "homepage": "https://github.com/usetheokit/theokit/tree/main/packages/create-theokit#readme",
+  "bugs": {
+    "url": "https://github.com/usetheokit/theokit/issues"
+  },
   "license": "Apache-2.0",
   "bin": {
     "create-theokit": "./dist/cli.js"
@@ -15,6 +24,7 @@
     "cross-spawn": "^7.0.6"
   },
   "publishConfig": {
+    "provenance": true,
     "access": "public"
   },
   "engines": {

package/templates/default/.env.example

@@ -1,5 +1,5 @@
 # LLM API key (OpenRouter, Anthropic, or OpenAI)
 OPENROUTER_API_KEY=sk-or-v1-your-key-here
 
-# Optional: override the model declared by ModelCapability
+# Optional: override the model declared in agents/chat.ts
 # LLM_MODEL=openai/gpt-4o-mini

package/templates/default/CLAUDE.md

@@ -9,6 +9,7 @@ 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-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 |

package/templates/default/README.md.tmpl

@@ -2,78 +2,115 @@
 
 Built with [TheoKit](https://theokit.dev) — **Build the app your agent lives in.**
 
-This is the default template: a working **agent chat surface** wired to a mock
-streaming agent, ready for you to plug in your LLM. Run it and you immediately
-see your agent talking — that's the point.
+This is the default template: a **working agent chat**, end to end. The thread
+streams real replies, the tools really run, and the approval prompt really gates
+the side-effecting one. Run it and you are talking to your agent.
 
 ## Getting Started
 
 ```bash
-# Install dependencies
-npm install
+# 1. Install dependencies
+pnpm install
 
-# Start development server (HMR)
-npm run dev
+# 2. Point the agent at a provider (OpenRouter, Anthropic, or OpenAI)
+cp .env.example .env && $EDITOR .env
+
+# 3. Start the dev server (HMR)
+pnpm dev
 ```
 
-Open the app and chat with the agent. Edit the agent at `agents/chat.ts`
-(pick your model / add tools) — the `@theokit/sdk` runtime resolves OpenRouter /
-Anthropic / Ollama / OpenAI from env vars (see the file's header comment).
+Open the app and chat. Edit `agents/chat.ts` to change the model, add tools, or
+swap the persona — `@theokit/sdk` is the runtime and resolves the provider from
+your environment.
 
 ## Project Structure
 
 ```
 {{name}}/
-├── app/
-│   ├── page.tsx              # Chat surface (@theokit/ui: ChatThread, ChatComposer, …)
-│   └── layout.tsx            # Root layout
+├── agents/                 # The agent, and what composes it
+│   ├── chat.ts             #   the agent → POST /api/agents/chat
+│   ├── prompts/            #   system prompts / personas
+│   ├── tools/              #   tools the agent can call (weather, current-time, …)
+│   └── skills/             #   procedures the model loads on demand
+├── app/                    # Frontend — file-based routing
+│   ├── page.tsx            #   the `/` route — composition root
+│   ├── layout.tsx          #   root layout
+│   ├── components/         #   presentational UI
+│   ├── hooks/              #   custom hooks — where state lives
+│   └── lib/                #   app modules / config
 ├── server/
-│   └── routes/
-│       ├── chat.ts           # Streaming agent endpoint (mock — replace with your LLM)
-│       └── health.ts         # GET /api/health
-├── tailwind.config.ts        # TheoUI design tokens
-├── theo.config.ts            # TheoKit configuration
-└── .env.example              # Environment variables
+│   └── routes/health.ts    # GET /api/health
+├── shared/agent.ts         # Branding (name, model, greeting) — one source of truth
+├── docs/                   # ARCHITECTURE · CUSTOMIZATION · ENVIRONMENT
+├── theo.config.ts          # TheoKit configuration
+└── .env.example            # Environment variables
 ```
 
 ## Key Concepts
 
-- **Agent chat surface** — `app/page.tsx` renders `@theokit/ui` chat components
-  driven by the streaming endpoint.
-- **`agents/chat.ts` (`defineAgent`)** — one file auto-served at `POST /api/agents/chat`,
-  streaming the ai-sdk `UIMessageStream` wire; `useAgent('/api/agents/chat')` on the client
-  reconstructs `UIMessage[]` you render via `message.parts`. `@theokit/sdk` owns
-  conversation persistence and provider resolution.
-- **`defineAgentTool`** — declare typed tools (the template ships a
-  `current_time` example).
-
-## About `@theokit/sdk`
-
-`@theokit/sdk` is the agent runtime this template depends on. Its publish to the
-public npm registry is **operator-deferred** — if `npm install` cannot resolve
-it yet, scaffold the registry-free variant instead (see Bare mode below) and add
-the SDK once it is published.
-
-## Bare mode (`--bare`)
-
-Want the minimal "Hello Theo" scaffold with **no** agent UI and **no** unpublished
-registry dependencies? Scaffold with `--bare`:
+- **An agent is a file.** `agents/chat.ts` is served at `POST /api/agents/chat` —
+  nothing to register. Add a second agent as another `agents/<name>.ts`.
+- **`AgentBuilder`** is the authoring surface. The chain accumulates type-state, so
+  `.build()` without `.model()` is a compile error, not a runtime surprise:
+
+  ```ts
+  export default AgentBuilder.create()
+    .input(z.object({ message: z.string() }))
+    .model('openai/gpt-4o-mini')
+    .system(BASE_INSTRUCTIONS)
+    .tool(weatherTool)
+    .approval('send_notification', { question: 'Send this notification?' })
+    .skills([dailyBriefingSkill])
+    .build()
+  ```
+
+- **A tool is a file too** — `tool('name').describe(…).input(z.object({…})).execute(…).build()`.
+  Pure metadata plus a handler; it never calls an LLM.
+- **The sub-folders under `agents/` are semantic, not routes.** `prompts/`, `tools/`,
+  `skills/` and friends are skipped by the scanner, so `agents/tools/weather.ts`
+  never becomes a phantom `/api/agents/tools/weather` endpoint.
+- **`useAgent`** binds the client to the agent and hands you the transcript:
+  `const { thread, send, status, reset, error } = useAgent('/api/agents/chat')`.
+- **Human-in-the-loop.** `.approval(tool, …)` pauses the run before that tool and
+  asks. Ask the agent to "notify me that …" to see it.
+- **Styling is wired for you.** Tailwind v4 and `@theokit/ui` are detected and
+  configured by the framework — there is no `tailwind.config.ts` to maintain.
+
+Deeper detail lives in [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md);
+customization and environment variables have their own pages beside it.
+
+## Adding a screen
+
+Routing is file-based: a screen is a folder under `app/` with a `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` |
+
+Or run `theokit generate page settings`, then link it from `app/components/Nav.tsx`.
+
+## Other scaffolds
+
+The same agent runs behind a terminal or desktop frontend — only the transport
+changes. Scaffold them with `--surface=tui` (Ink) or `--surface=desktop` (Tauri).
+
+Want the opposite — a plain app with no agent and no `@theokit/*` runtime
+dependencies? Scaffold with `--bare`: a Hello Theo page and the same clean
+structure to grow into.
 
 ```bash
-npm create theokit my-app -- --template=default --bare
+npx create-theokit my-app --bare
 ```
 
-`--bare` strips `@theokit/ui`, `@theokit/sdk`, `lucide-react`, and the Tailwind
-toolchain, replaces `app/page.tsx` with a plain "Hello Theo" page, and removes
-the mock chat route — a scaffold that always installs without registry access.
-
 ## Commands
 
 ```bash
-npm run dev          # Start dev server with HMR
-npm run build        # Build for production
-npm run start        # Run production build
-npm run test         # Run tests (vitest)
-npm run lint         # ESLint check
-npm run typecheck    # TypeScript type check
+pnpm dev          # Start dev server with HMR
+pnpm build        # Build for production
+pnpm start        # Run the production build
+pnpm test         # Run tests (vitest)
+pnpm lint         # ESLint check
+pnpm typecheck    # TypeScript type check
 ```

package/templates/default/_gitignore

@@ -25,8 +25,11 @@ pnpm-debug.log*
 *.pem
 *.tsbuildinfo
 
-# database
-data/
+# framework-written app data — conversation transcripts (.data/agent-sessions/**/*.jsonl)
+# and the local SQLite DB both live here. This said `data/`, without the dot, and
+# matched nothing the framework writes: every prompt, answer, tool input and tool
+# result went into version control on the first commit after the first run (#395).
+.data/
 
 # editors
 .vscode/

package/templates/default/agents/chat.ts

@@ -12,16 +12,43 @@ import { weatherTool } from './tools/weather.js'
  * agent; it composes its neighbours under `agents/`: the persona in `prompts/`, capabilities in `tools/`,
  * procedures in `skills/`. Those folders are that concern, NOT extra routes — the framework's scanner
  * 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`. See
- * `docs/ARCHITECTURE.md`.
+ * 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).
  */
+/**
+ * Who may run this agent, and against which conversation (ADR 0001).
+ *
+ * Every agent declares this; `'public'` is the decision, not the absence of one — and it is the
+ * honest one for a scaffold with no login. It means: the endpoint resumes whatever conversation the
+ * caller names, so anyone holding a session id may read and continue it. That is a capability
+ * model, and it is fine while the ids are the random UUIDs the client mints.
+ *
+ * The moment this app has users, replace it with the owner check:
+ *
+ * ```ts
+ * import { requireOwner } from 'theokit/server/define'
+ *
+ * export const policy = ({ subject, params }) =>
+ *   requireOwner(subject, ownerOfConversation(params.sessionId))
+ * ```
+ *
+ * `subject` is whatever `server/context.ts` put on `ctx.subject`; `params` carries
+ * `{ agent, endpoint, sessionId?, approvalId? }`. One declaration covers the run, the thread
+ * routes, the approval surface and MCP.
+ */
+export const policy = 'public'
+
 export default AgentBuilder.create()
   .input(z.object({ message: z.string() }))
-  .model('openai/gpt-4o-mini')
+  // `LLM_MODEL` is honoured HERE, not by the framework, because this is where the model is
+  // declared and this file is yours. `.env.example` documented the variable and nothing read it,
+  // 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')
   .system(BASE_INSTRUCTIONS)
   .tool(weatherTool)
   .tool(currentTimeTool)

package/templates/default/app/components/ChatPanel.tsx

@@ -1,8 +1,9 @@
 import { ChatThread, ChatMessage, AgentStreaming, QuickActionChips } from '@theokit/ui'
-import { type UIMessage } from '@theokit/ui'
 import { ScrollArea } from '@usetheo/ui'
+import { type UIMessage } from 'theokit/client'
 
 import { MODEL_NAME, STARTERS } from '../lib/constants'
+import { toRenderable } from '../lib/renderable'
 
 /**
  * The scrolling transcript: the message thread + a live streaming indicator + the starter prompts (shown
@@ -25,7 +26,7 @@ export function ChatPanel({
       <div className="mx-auto flex w-full max-w-3xl flex-col gap-4 px-6 py-6">
         <ChatThread>
           {thread.map((message) => (
-            <ChatMessage key={message.id} message={message} />
+            <ChatMessage key={message.id} message={toRenderable(message)} />
           ))}
           {isStreaming && <AgentStreaming model={MODEL_NAME} />}
         </ChatThread>

package/templates/default/app/components/Nav.tsx

@@ -4,8 +4,7 @@ import { Link } from 'theokit/client'
 /**
  * The primary navigation menu. Add one entry per screen you add under `app/` (a screen is a folder with a
  * `page.tsx` — `app/settings/page.tsx` → `/settings`). Uses TheoKit's `Link` (react-router's Link + route
- * prefetch on hover/focus) and computes the active route from `useLocation`. See
- * `docs/ARCHITECTURE.md` § Adding a screen.
+ * prefetch on hover/focus) and computes the active route from `useLocation`.
  */
 const LINKS = [
   { to: '/', label: 'Chat', exact: true },

package/templates/default/app/hooks/use-transcript.ts

@@ -1,7 +1,6 @@
 'use client'
 
-import { type UIMessage } from '@theokit/ui'
-import { useAgent } from 'theokit/client'
+import { useAgent, type UIMessage } from 'theokit/client'
 
 import { GREETING } from '../lib/constants'
 
@@ -12,7 +11,14 @@ import { GREETING } from '../lib/constants'
  * hand-rolled transcript (local history + commit-once effect + inflight-merge) is gone — the store owns it.
  */
 export interface ChatTranscript {
-  /** The full transcript to render (greeting + committed history + the in-flight reply while streaming). */
+  /**
+   * The full transcript (greeting + committed history + the in-flight reply while streaming).
+   *
+   * Typed as the framework's `UIMessage` — the shape `useAgent` actually returns — and NOT as the
+   * component library's. Two earlier versions of this template typed it as the renderer's type and
+   * a fresh scaffold failed its own `typecheck` (usetheokit/theokit#80, #396). `app/lib/renderable.ts`
+   * converts at the one place that renders.
+   */
   thread: UIMessage[]
   isStreaming: boolean
   hasError: boolean

package/templates/default/app/layout.tsx

@@ -14,7 +14,14 @@ export default function RootLayout() {
   return (
     <div className="grid h-screen w-screen grid-rows-[auto_1fr] bg-background text-foreground">
       <Header />
-      <main className="flex h-full flex-col overflow-hidden">
+      {/*
+        `data-theo-scroll` marks this as a scroll container, so its offset is restored on back
+        navigation (usetheokit/theokit#421). Browsers and react-router only ever restore the
+        DOCUMENT; in a shell like this one the document never scrolls, so without the marker there
+        is nothing to restore. The value is the id — add the attribute to any other element you
+        scroll, with a different value.
+      */}
+      <main data-theo-scroll="main" className="flex h-full flex-col overflow-hidden">
         <Outlet />
       </main>
     </div>

package/templates/default/app/lib/constants.ts

@@ -1,4 +1,5 @@
-import { type UIMessage, type QuickAction } from '@theokit/ui'
+import { type QuickAction } from '@theokit/ui'
+import { type UIMessage } from 'theokit/client'
 import { Sparkles } from 'lucide-react'
 
 import { AGENT } from '../../shared/agent'

package/templates/default/app/lib/renderable.ts

@@ -0,0 +1,78 @@
+import type {
+  ToolInvocationState,
+  UIMessage as RenderableMessage,
+  UIMessagePart as RenderablePart,
+} from '@theokit/ui'
+import type { UIMessage } from 'theokit/client'
+
+/**
+ * The seam between what the framework STREAMS and what the component library RENDERS.
+ *
+ * `useAgent().thread` hands you `UIMessage` from `theokit/client` — the wire shape, whose parts are
+ * deliberately open (`{ type: string; [key: string]: unknown }`) so a `data-*` part or a part kind
+ * invented after your app was written still arrives intact. `<ChatMessage>` wants `@theokit/ui`'s
+ * `UIMessage`, whose parts are a closed discriminated union.
+ *
+ * Both are right, and neither can be made assignable to the other without one of them giving up
+ * what it is for. So the APP owns the conversion — which is where it belongs: your app chose the
+ * renderer, and the framework does not know about it. Two prior versions of this template typed the
+ * transcript as the renderer's type and let TypeScript discover the mismatch on the first
+ * `tsc --noEmit` of a fresh scaffold (usetheokit/theokit#80, #396).
+ *
+ * Nothing here is a cast. Each branch checks the fields that branch needs and builds a value the
+ * renderer's type accepts; a part it cannot vouch for is DROPPED rather than forced through, which
+ * is the honest outcome for a part this version of the library has no renderer for.
+ */
+
+/** The tool states `@theokit/ui` knows how to render. Anything else is not renderable here. */
+const TOOL_STATES = [
+  'input-streaming',
+  'input-available',
+  'approval-requested',
+  'approval-responded',
+  'output-available',
+  'output-error',
+  'output-denied',
+] as const
+
+function isToolState(value: unknown): value is ToolInvocationState {
+  return typeof value === 'string' && (TOOL_STATES as readonly string[]).includes(value)
+}
+
+function toRenderablePart(part: UIMessage['parts'][number]): RenderablePart | null {
+  const { type } = part
+
+  if (type === 'text' || type === 'reasoning') {
+    return typeof part.text === 'string' ? { type, text: part.text } : null
+  }
+
+  if (type === 'dynamic-tool' || type.startsWith('tool-')) {
+    // A tool part the renderer can draw needs both of these; a half-built one is skipped rather
+    // than drawn with holes.
+    if (typeof part.toolCallId !== 'string' || !isToolState(part.state)) return null
+    return {
+      ...part,
+      type: type === 'dynamic-tool' ? 'dynamic-tool' : `tool-${type.slice('tool-'.length)}`,
+      toolCallId: part.toolCallId,
+      state: part.state,
+    }
+  }
+
+  if (type.startsWith('data-')) {
+    return { ...part, type: `data-${type.slice('data-'.length)}`, data: part.data }
+  }
+
+  // A kind this version of `@theokit/ui` has no renderer for. Dropping it keeps the rest of the
+  // message readable; forcing it through would render nothing and hide the reason.
+  return null
+}
+
+/** Project one streamed message into the shape `<ChatMessage>` renders. */
+export function toRenderable(message: UIMessage): RenderableMessage {
+  return {
+    id: message.id,
+    role: message.role,
+    parts: message.parts.map(toRenderablePart).filter((part) => part !== null),
+    ...(message.metadata === undefined ? {} : { metadata: message.metadata }),
+  }
+}

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/app/page.tsx

@@ -17,7 +17,7 @@ import { useChatTranscript } from './hooks/use-transcript'
  * Add a SCREEN: routing is file-based — a screen is a folder under `app/` with a `page.tsx`
  * (`app/settings/page.tsx` → `/settings`; `app/users/[id]/page.tsx` → `/users/:id`). Run
  * `theokit generate page <name>`, then add a link in `app/components/Nav.tsx`. This route is `/` (see the
- * example `app/about/page.tsx` + `docs/ARCHITECTURE.md` § Adding a screen).
+ * example `app/about/page.tsx`).
  */
 export default function Page() {
   const [composerValue, setComposerValue] = useState('')

package/templates/default/docs/ARCHITECTURE.md

@@ -42,12 +42,16 @@ folders it composes (prompts, tools, skills) live together under `agents/`, with
 ## Clean names, no phantom routes
 
 An agent is a file: `agents/<name>.ts` → `POST /api/agents/<name>`. But the framework's scanner is
-**folder-semantic** — the conventional sub-folders under `agents/` (`prompts/`, `tools/`, `skills/`,
-`lib/`, `hooks/`, `channels/`, `connections/`, `subagents/`, `schedules/`) are **that concern, not routes**.
+**folder-semantic** — thirteen sub-folder names under `agents/` (`tools/`, `skills/`, `prompts/`,
+`lib/`, `hooks/`, `channels/`, `connections/`, `subagents/`, `schedules/`, `sandbox/`, `workflows/`,
+`evals/`, `memory/`) are **that concern, not routes**.
 So the names stay clean (`tools/`, not `_tools/`) and `agents/tools/weather.ts` never becomes a phantom
 `/api/agents/tools/weather` endpoint. Markdown (`skills/*.md`) is never scanned either way. The
 prompts/tools/skills are **shared** across every agent in `agents/`.
 
+An agent that outgrows one file becomes a folder that co-locates its own composition —
+`agents/<name>/index.ts` with `tools/` and `prompts/` beside it. Same route, same identity.
+
 ## Composition
 
 `agents/chat.ts` is thin on purpose — it wires the pieces together:

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

@@ -107,7 +107,7 @@ export class TaskTools {
   }
 }
 
-// compõe no agente:
+// compose onto the agent:
 //   new ToolboxCapability(new TaskTools(db), { namespace: 'tasks' })  → tasks.list_tasks
 ```
 

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

@@ -91,7 +91,7 @@ export default defineConfig({
   openapi: {
     title: 'My App API',
     version: '1.0.0',
-    outDir: 'docs/api',
+    outDir: '.theokit',
   },
 })
 ```

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.