create-theokit 1.25.3 → 2.0.0-next.1

package/templates/default/docs/ARCHITECTURE.md

@@ -1,60 +1,105 @@
 # Architecture
 
-How this TheoKit app is organized. The layout puts the **agent at the center**: the agent file and the
-folders it composes (prompts, tools, skills) live together under `agents/`, with clean names — the
+How this TheoKit app is organized. Two domains, named by what they are rather than by what they
+contain: `src/app/` is the interface — the only code that reaches a browser — and `src/server/` is
+the backend, everything that never leaves the machine.
+
+The **agent lives inside the backend**, at `src/server/agents/`, because that is what it is: it
+reads your API keys, calls tools that touch the network, and runs where the server runs. Every rule
+that applies to `server/` applies to it. Within that folder the agent is still at the center — the
+agent file and what composes it (prompts, tools, skills) sit together with clean names, the
 "file = identity" convention agent frameworks like [Eve](https://eve.dev) use.
 
 ## Project structure
 
 ```
 .
-├── agents/                 # The agent, and what composes it
-│   ├── chat.ts             #   the agent → POST /api/agents/chat, useAgent('chat')
-│   ├── prompts/            #   system prompts / personas
-│   │   └── instructions.ts
-│   ├── tools/              #   tools the agent can call
-│   │   ├── weather.ts      #     remote — current weather via open-meteo (HTTP)
-│   │   └── current-time.ts #     local — date/time in an IANA timezone (no network)
-│   └── skills/             #   procedures the model loads on demand (Skill.create)
-│       └── daily-briefing.ts    #   a real skill: time → weather → a one-line nudge
-├── app/                    # Frontend (web surface). tui → tui/, desktop → frontend/
-│   ├── page.tsx            #   the `/` route — composition root (lays out the components + the hook)
-│   ├── layout.tsx          #   root layout — composes <Header/> over the routed page
-│   ├── error/loading/not-found.tsx  #   route surface (special files)
-│   ├── about/page.tsx      #   an EXAMPLE `/about` route — shows how screens grow (delete when done)
-│   ├── components/         #   presentational UI (Tailwind, flat .tsx — no CSS modules)
-│   │   ├── Header.tsx      #     the top bar (composes Nav + theme toggle)
-│   │   ├── Nav.tsx         #     the navigation menu (a link per screen)
-│   │   ├── ChatPanel.tsx   #     the transcript + streaming indicator + starter prompts
-│   │   └── Composer.tsx    #     the input + error card + new-chat
-│   ├── hooks/              #   custom hooks
-│   │   └── use-transcript.ts  #     transcript STATE (history + streaming)
-│   └── lib/                #   app modules / config
-│       └── constants.ts    #     greeting + starter prompts
-├── server/                 # Backend routes / actions (POST/GET handlers, jobs)
-├── shared/                 # Code imported by more than one layer
-│   └── agent.ts            #   branding (name, model, greeting) — one source of truth
+├── src/
+│   ├── server/             # Backend — everything that never leaves the machine
+│   │   ├── agents/         #   The agent, and what composes it
+│   │   │   ├── chat.ts     #     the agent → POST /api/agents/chat, useAgent('chat')
+│   │   │   ├── prompts/    #     system prompts / personas
+│   │   │   │   └── instructions.ts
+│   │   │   ├── tools/      #     tools the agent can call
+│   │   │   │   ├── weather.ts       # remote — current weather via open-meteo (HTTP)
+│   │   │   │   └── current-time.ts  # local — date/time in an IANA timezone (no network)
+│   │   │   ├── skills/     #     procedures the model loads on demand (Skill.create)
+│   │   │   │   └── daily-briefing.ts  # a real skill: time → weather → a one-line nudge
+│   │   │   └── hooks/      #     lifecycle interception
+│   │   │       └── tool-audit.ts      # one structured line per tool call, with timing
+│   │   └── routes/         #   Backend routes / actions (POST/GET handlers, jobs)
+│   ├── app/                # Frontend (web surface). tui → tui/, desktop → frontend/
+│   │   ├── page.tsx        #   the `/` route — composition root (components + the hook)
+│   │   ├── layout.tsx      #   root layout — composes <Header/> over the routed page
+│   │   ├── error/loading/not-found.tsx  #   route surface (special files)
+│   │   ├── about/page.tsx  #   an EXAMPLE `/about` route (delete when done)
+│   │   ├── components/     #   presentational UI (Tailwind, flat .tsx — no CSS modules)
+│   │   │   ├── Header.tsx  #     the top bar (composes Nav + theme toggle)
+│   │   │   ├── Nav.tsx     #     the navigation menu (a link per screen)
+│   │   │   ├── ChatPanel.tsx   #   the transcript + streaming indicator + starters
+│   │   │   └── Composer.tsx    #   the input + error card + new-chat
+│   │   ├── hooks/          #   custom hooks
+│   │   │   └── use-transcript.ts  # transcript STATE (history + streaming)
+│   │   └── lib/            #   app modules / config
+│   │       └── constants.ts       # greeting + starter prompts
+│   └── shared/             # Code imported by BOTH sides — and only that
+│       └── agent.ts        #   branding (name, model, greeting) — one source of truth
+├── .theokit/               # Agent context, read at runtime — no rebuild to change it
+│   ├── THEO.md             #   prepended every turn (priority 60)
+│   ├── rules/              #   path-scoped instructions, by glob (priority 45)
+│   └── personalities/      #   swappable system prompts (agent.usePersonality)
 ├── types/                  # Framework ambient declarations (e.g. the job registry)
 ├── docs/                   # This folder
 └── theo.config.ts          # App config (name, dirs, plugins)
 ```
 
+## Two halves: what you compile, and what the agent reads
+
+`src/server/agents/` is **code** — it changes when you deploy. `.theokit/` is **data** — the agent
+reads it at runtime, so a wording change is an edit, not a release.
+
+The SDK loads context from seven sources in priority order, and yours sit inside it:
+
+| Priority | Source                    | Scope                    |
+| -------- | ------------------------- | ------------------------ |
+| 10       | `AGENTS.md`               | walks up to the git root |
+| 20       | `GEMINI.md`               | walks up to the git root |
+| 30       | `CLAUDE.md`               | walks up to the git root |
+| 40       | `.cursor/rules/*.mdc`     | glob-activated           |
+| **45**   | **`.theokit/rules/*.md`** | **glob-activated**       |
+| 50       | `.theokit/context/*.md`   | glob-activated           |
+| **60**   | **`.theokit/THEO.md`**    | this directory only      |
+
+Later wins where they conflict, so `THEO.md` is the strongest thing in the file layer — which is
+why it should hold facts rather than preferences. A preference that always wins is a preference you
+cannot override with a personality.
+
+**Personalities are not in that table**, and the reason is worth keeping straight: the seven sources
+above are _context files_, merged into every relevant turn. A personality REPLACES the system
+prompt, only while it is active, and only when someone asks for it:
+
+```ts
+await agent.usePersonality('teacher', { save: true })
+```
+
+Reserved names — `none`, `default`, `neutral` — clear it.
+
 ## 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** — thirteen sub-folder names under `agents/` (`tools/`, `skills/`, `prompts/`,
+An agent is a file: `src/server/agents/<name>.ts` → `POST /api/agents/<name>`. But the framework's scanner is
+**folder-semantic** — thirteen sub-folder names under `src/server/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
+So the names stay clean (`tools/`, not `_tools/`) and `src/server/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/`.
+prompts/tools/skills are **shared** across every agent in `src/server/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.
+`src/server/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:
+`src/server/agents/chat.ts` is thin on purpose — it wires the pieces together:
 
 ```ts
 export default AgentBuilder.create()
@@ -71,7 +116,7 @@ Grow the agent by editing its neighbours, not by inflating `chat.ts`: persona
 a new capability → `tools/<name>.ts` (then `.tool(<name>Tool)`), a documented procedure → a
 `Skill.create(...)` in `skills/<name>.ts` (add it to the `.skills([...])` list). A **skill** is
 loaded by the model on demand via the `skill_read` tool, so long procedures don't bloat every prompt. Add a
-**second agent** as another `agents/<name>.ts`.
+**second agent** as another `src/server/agents/<name>.ts`.
 
 ## Surfaces
 
@@ -79,34 +124,34 @@ The same agent is reached from three interchangeable frontends — only the tran
 
 | Surface | Frontend dir | Transport                             |
 | ------- | ------------ | ------------------------------------- |
-| web     | `app/`       | `HttpTransport` (`/api/agents/chat`)  |
+| web     | `src/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.
+All three render the same `@theokit/ui` chat and read `src/shared/agent.ts` for the greeting + model label.
 
 ## Frontend organization
 
-The web `app/` is organized **type-based**, the layout most React apps grow into:
+The web `src/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                                                 |
+| --------------- | --------------------------------------------------------- | ------------------------------------------------------- |
+| `src/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
+at a route segment (the `src/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_.
 
 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
 Next.js App Router model TheoKit implements: the special files live at the route segment, and `components/`
-/ `hooks/` / `lib/` sit alongside them. Having both at the `app/` root is the convention, not a mismatch.
+/ `hooks/` / `lib/` sit alongside them. Having both at the `src/app/` root is the convention, not a mismatch.
 (If a special file grows big, keep the thin route file and have it render a real component from
 `components/` — e.g. `loading.tsx` → `<LoadingScreen/>`.)
 
@@ -126,17 +171,17 @@ a `pages/` folder you wire by hand: that's the Next.js-style convention TheoKit
 
 ### Adding a screen
 
-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`.
+Routing is **file-based**: a screen is a folder under `src/app/` with a `page.tsx`. The folder name is the URL
+segment; the home screen is the flat `src/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 | `src/app/settings/page.tsx`         | `/settings`                                                   |
+| a nested screen      | `src/app/settings/billing/page.tsx` | `/settings/billing`                                           |
+| a dynamic screen     | `src/app/users/[id]/page.tsx`       | `/users/:id` (read the param with react-router's `useParams`) |
+| a catch-all          | `src/app/docs/[...slug]/page.tsx`   | `/docs/*`                                                     |
 
-The one-command way: **`theokit generate page settings`** creates `app/settings/page.tsx` for you. Each
+The one-command way: **`theokit generate page settings`** creates `src/app/settings/page.tsx` for you. Each
 screen can have its own `layout.tsx` / `loading.tsx` / `error.tsx` / `not-found.tsx` (the route special
 files, scoped to that segment).
 
@@ -158,11 +203,11 @@ export function SettingsLink() {
 
 TheoKit's `theokit/client` gives you the Next-parity building blocks: **`Link`** (prefetch), **`Metadata`**
 (set `<title>`/meta per route — used in `page.tsx` + `about/page.tsx`), **`Image`** (optimized `<img>`),
-**`theoFetch`** + the **`theokit/react-query`** adapter (typed data fetching against your `server/`
+**`theoFetch`** + the **`theokit/react-query`** adapter (typed data fetching against your `src/server/`
 routes), and **`useAgent`** (the chat stream). Reach for these instead of generic libraries.
 
-The primary menu is `app/components/Nav.tsx` (TheoKit `Link` + `useLocation` for the active route). A worked
-example ships as `app/about/page.tsx` (the `/about` route, linked from the `Nav`, with its own `Metadata`
+The primary menu is `src/app/components/Nav.tsx` (TheoKit `Link` + `useLocation` for the active route). A worked
+example ships as `src/app/about/page.tsx` (the `/about` route, linked from the `Nav`, with its own `Metadata`
 title); it explains this and tells you to delete it once you've got the idea.
 
 See also: [CUSTOMIZATION](./CUSTOMIZATION.md).

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                                    | `src/server/agents/chat.ts` (`.model(...)`) + the label in `src/shared/agent.ts`                                            |
+| Change the persona / rules                          | `src/server/agents/prompts/instructions.ts`                                                                                 |
+| Add a tool (an action the agent can take)           | new `src/server/agents/tools/<name>.ts`, then `.tool(<name>Tool)` in `src/server/agents/chat.ts`                            |
+| Add a skill (a procedure the model loads on demand) | `Skill.create(...)` in `src/server/agents/skills/<name>.ts`, then add it to `.skills([...])` in `src/server/agents/chat.ts` |
+| Add a second agent                                  | new `src/server/agents/<name>.ts` → auto-served at `/api/agents/<name>`, bind with `useAgent('<name>')`                     |
+| Change the greeting / app name                      | `src/shared/agent.ts`                                                                                                       |
+| Add a backend route                                 | `src/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

@@ -8,17 +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 FIRST segment of the model id in `agents/chat.ts` picks the provider, and that decides which key
+The FIRST segment of the model id in `src/server/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`     |
+| Model id in `src/server/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-frontend/SKILL.md

@@ -3,7 +3,7 @@ name: theokit-frontend
 description: TheoKit frontend — file-based routing, layouts, theoFetch typed client, useAgent, React patterns
 user-invocable: false
 paths:
-  - 'app/**'
+  - 'src/app/**'
 ---
 
 # TheoKit Frontend (React + File-Based Routing)

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

@@ -3,7 +3,7 @@ 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/**'
+  - 'src/server/routes/**'
   - 'server/channels/**'
   - '**/*gateway*'
   - '**/*webhook*'

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

@@ -3,7 +3,7 @@ name: theokit-routes
 description: TheoKit server routes — the route() builder, Zod validation, HTTP methods, dynamic params, error handling
 user-invocable: false
 paths:
-  - 'server/routes/**'
+  - 'src/server/routes/**'
   - 'server/actions/**'
 ---
 

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

@@ -3,7 +3,7 @@ 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'
 user-invocable: false
 paths:
-  - 'app/**'
+  - 'src/app/**'
   - '**/*Chat*'
   - '**/*chat*'
   - '**/*Sidebar*'

package/templates/default/dot-theokit/THEO.md

@@ -0,0 +1,54 @@
+# Product context
+
+Prepended to your agent's context on **every turn**, and it is the strongest source in the file
+layer (priority 60) — nothing else overrides it. That is what decides what belongs here.
+
+> **Not the same file as `AGENTS.md` at the root.** That one tells agents how to work on this
+> codebase: commands, layout, conventions. This one tells your agent what your product IS, for the
+> conversations it has with your users. If a sentence would help someone edit the code, it goes
+> there instead.
+
+**Put facts here, not preferences.** A preference written here wins against every personality, so a
+tone instruction in this file quietly makes `usePersonality` do nothing. Tone belongs in
+`.theokit/personalities/`; instructions about specific files belong in `.theokit/rules/`.
+
+## Why this file is here and not at the root
+
+On the SDK this project installs (`^4.52.1`, which resolves to a 4.x), `.theokit/THEO.md` is the
+**only** path a `THEO.md` is read from — a copy at the project root is read by nothing, silently.
+
+`@theokit/sdk@5` adds a root `THEO.md` (`usetheokit/theokit-sdk#531`) at priority 55, so on that
+version both locations work and `.theokit/THEO.md` still wins a conflict. 5.x is currently published
+on the `next` channel only, so moving this file to the root would break it for anyone on the default
+install — which is why the scaffold keeps it here.
+
+Two more things worth knowing if you do move it once 5.x is stable:
+
+- The root spec sets `followImports: true`, this one does not. `@file` references resolve there and
+  not here.
+- Keep the pair. `AGENTS.md` is read by Cursor, Copilot and Claude Code as well as by TheoKit, and
+  it addresses a different audience — agents that write your code, rather than the agent that talks
+  to your users. That distinction survives whichever location this file ends up in.
+
+Keep it short — every line costs tokens on every turn.
+
+## What this app is
+
+Replace this with two or three sentences: what your product does, who uses it, and the one thing an
+agent must never get wrong about it.
+
+## Vocabulary
+
+The highest-value section, and the one most projects skip. Define the words your domain uses
+differently from everyone else — a model that guesses what "account" means in your system will
+guess wrong in a way that reads as fluent, which is the hardest kind of wrong to notice.
+
+| Term   | In this app it means                     |
+| ------ | ---------------------------------------- |
+| _term_ | _the definition your team actually uses_ |
+
+## Boundaries
+
+What the agent should refuse or hand off, stated as fact rather than as tone. "Refunds are issued
+by support, never by the assistant" is a fact. "Be careful with refunds" is a preference, and it
+belongs in a personality where a user could switch it.

package/templates/default/dot-theokit/personalities/README.md

@@ -0,0 +1,35 @@
+# Personalities
+
+A personality is a **swappable system prompt**, chosen at runtime without redeploying:
+
+```ts
+await agent.usePersonality('teacher') // for this process
+await agent.usePersonality('teacher', { save: true }) // persists across restarts
+await agent.usePersonality('none') // back to the agent's own system prompt
+```
+
+`none`, `default` and `neutral` are reserved names that clear the active preset. History is kept
+across a switch — pass `{ reset: true }` to clear the session too.
+
+Each file is markdown: frontmatter describes it, the **body is the system prompt**.
+
+| Frontmatter   | Type     | Meaning                                        |
+| ------------- | -------- | ---------------------------------------------- |
+| `name`        | string   | the name you pass to `usePersonality`          |
+| `description` | string   | shown when listing presets                     |
+| `tools`       | string[] | restrict the agent to these tools while active |
+| `model`       | string   | override the model while active                |
+| `tags`        | string[] | free-form grouping                             |
+
+## Personality, rule, or system prompt?
+
+The three overlap enough that picking wrong is easy, and the difference is _when each one applies_:
+
+|                          | Applies when                                 | Changes at runtime        |
+| ------------------------ | -------------------------------------------- | ------------------------- |
+| `chat.ts` `.system(...)` | always — it is what the agent IS             | no, it ships in the build |
+| a **personality**        | while the user has it active                 | **yes**, `usePersonality` |
+| a **rule**               | when the conversation touches matching paths | no, but it is just a file |
+
+Tone and stance belong in a personality. Facts about your domain belong in `THEO.md`. Instructions
+about specific code belong in `rules/`.

package/templates/default/dot-theokit/personalities/concise.md

@@ -0,0 +1,14 @@
+---
+name: concise
+description: Short answers, no preamble — for users who already know the domain
+tags:
+  - default
+---
+
+Answer in as few words as the question honestly allows.
+
+- No preamble. Do not restate the question, do not announce what you are about to do.
+- One paragraph unless the answer genuinely has parts. Then use a list.
+- Skip the caveats a domain expert already knows. Keep the ones that would change their decision.
+- When you are unsure, say so in one sentence and say what would resolve it. Do not pad uncertainty
+  into a long hedge — a long hedge reads as confidence.

package/templates/default/dot-theokit/personalities/teacher.md

@@ -0,0 +1,17 @@
+---
+name: teacher
+description: Explains the reasoning, for someone learning the domain
+tags:
+  - onboarding
+---
+
+Explain your reasoning, not just your conclusion.
+
+- Lead with the answer, then say why it is the answer. Someone who already knew can stop at the
+  first line; someone learning reads on.
+- Name the thing you are doing when it has a name. A reader who learns the word can look it up
+  later; a reader who only sees the steps cannot.
+- When there was a real alternative, say what it was and why you did not take it. The rejected
+  option is usually the more instructive half.
+- Never simplify to the point of being wrong. If the honest answer is complicated, say it is
+  complicated and then give it.

package/templates/default/dot-theokit/rules/README.md

@@ -0,0 +1,30 @@
+# Rules
+
+Markdown files here are **path-scoped instructions**: they enter the agent's context only when the
+conversation touches a file matching their `globs`. That is what separates a rule from `THEO.md`,
+which is always present.
+
+```markdown
+---
+description: what this rule is for
+globs:
+  - src/server/routes/**/*.ts
+---
+
+Your instructions here.
+```
+
+| Frontmatter   | Type     | Meaning                            |
+| ------------- | -------- | ---------------------------------- |
+| `description` | string   | what the rule covers               |
+| `globs`       | string[] | paths that activate it             |
+| `paths`       | string[] | same idea, explicit paths          |
+| `alwaysApply` | boolean  | ignore the globs and always attach |
+| `enabled`     | boolean  | switch it off without deleting it  |
+
+A file with **no frontmatter at all** is treated as `alwaysApply: true`. That is a convenience worth
+knowing about and easy to trigger by accident: a rule you meant to scope, whose frontmatter has a
+typo, becomes a rule that fires on every turn.
+
+Rules load at priority 45 — after `CLAUDE.md` (30) and `.cursor/rules` (40), before
+`.theokit/context` (50) and `THEO.md` (60).

package/templates/default/dot-theokit/rules/server-routes.md

@@ -0,0 +1,16 @@
+---
+description: Conventions for backend route handlers
+globs:
+  - src/server/routes/**/*.ts
+---
+
+# Route handler conventions
+
+These apply when the conversation touches a file under `src/server/routes/`.
+
+- A route validates its input at the boundary with Zod and trusts it afterwards. A handler that
+  re-checks the same shape three layers down is describing distrust of its own validation.
+- Return a typed error, never a bare `null` or `-1`. The caller cannot tell a missing value from a
+  failure, and one of those is a bug worth an alert.
+- Read secrets from the environment inside the handler, never at module scope — a module-level read
+  runs at import time, which is before the process has decided whether it is a build or a boot.

package/templates/default/package.json.tmpl

@@ -16,8 +16,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.60.0",
-    "@theokit/agents": "^10.1.0",
+    "theokit": "^0.64.0",
+    "@theokit/agents": "^12.1.0",
     "@theokit/sdk": "^4.52.1",
     "@theokit/ui": "^1.1.0",
     "@usetheo/ui": "^0.26.0",

package/templates/default/{agents → src/server/agents}/chat.ts

@@ -2,6 +2,7 @@ import { AgentBuilder } from '@theokit/agents'
 import { z } from 'zod'
 
 import { BASE_INSTRUCTIONS } from './prompts/instructions.js'
+import { toolAuditHooks } from './hooks/tool-audit.js'
 import { dailyBriefingSkill } from './skills/daily-briefing.js'
 import { currentTimeTool } from './tools/current-time.js'
 import { sendNotificationTool } from './tools/send-notification.js'
@@ -67,4 +68,9 @@ export default AgentBuilder.create()
   .approval('send_notification', { question: 'Send this notification?' })
   // Skills the agent can consult on demand (hover `.skills` for how it works).
   .skills([dailyBriefingSkill])
+  // Lifecycle hooks — one structured log line per tool call, with its duration. This is the
+  // observability half of the wiring: without it, a slow or looping agent is something you infer
+  // from a complaint instead of something you read in a log. `hooks/tool-audit.ts` explains the
+  // other seven events, and why this one deliberately does not veto anything.
+  .hooks(toolAuditHooks)
   .build()

package/templates/default/src/server/agents/hooks/tool-audit.ts

@@ -0,0 +1,75 @@
+import type { HookHandlers } from '@theokit/agents'
+
+/**
+ * Lifecycle hooks — the seam where you observe or intercept the agent loop.
+ *
+ * A tool call is the moment your agent stops talking and starts *doing*: it hits the network, writes
+ * a row, sends a message. This hook makes every one of those visible, with the timing, so a slow or
+ * looping agent is something you can see in a log rather than something you infer from a user
+ * complaint.
+ *
+ * Eight events exist. These two are the pair you almost always want first:
+ *
+ * | Event | When | Can it stop the call? |
+ * |---|---|---|
+ * | `pre_tool_call` | before the tool runs | **yes** — return `{ block: true, message }` |
+ * | `post_tool_call` | after it returns | no — fire-and-forget |
+ * | `transform_tool_result` | folds the turn's results before the model sees them | rewrites |
+ * | `transform_llm_output` | folds the model's text | rewrites |
+ * | `on_session_start` / `on_session_end` | session lifecycle | no |
+ * | `pre_user_send` / `post_assistant_reply` | around a user turn | no |
+ *
+ * ## Why this one only observes
+ *
+ * `pre_tool_call` is the only hook with veto power, and it is tempting to ship a template that uses
+ * it. It is deliberately not used here: a veto encodes a policy, and any policy this file could
+ * invent would be one your app did not ask for. `send_notification` is already gated the right way
+ * — by a human approval in `chat.ts` — which is where a decision belongs when a person should make
+ * it. Reach for the veto when you have a rule of your own:
+ *
+ * ```ts
+ * pre_tool_call: (ctx) =>
+ *   ctx.name === 'delete_account' && !isAdmin(ctx)
+ *     ? { block: true, message: 'Only an admin may delete an account.' }
+ *     : undefined,
+ * ```
+ *
+ * The message goes to the MODEL, not the user — write it as an instruction the agent can act on.
+ */
+
+/** Start times by `${runId}:${name}`, so a duration survives concurrent calls in one run. */
+const started = new Map<string, number>()
+
+function key(runId: string, name: string): string {
+  return `${runId}:${name}`
+}
+
+export const toolAuditHooks: HookHandlers = {
+  pre_tool_call: (ctx) => {
+    started.set(key(ctx.runId, ctx.name), Date.now())
+    // One structured line per call. Structured, not a sentence, because the thing you will want
+    // later is a filter (`tool=weather`), and a sentence has to be parsed back apart to give you one.
+    console.info(
+      JSON.stringify({ event: 'tool.start', tool: ctx.name, runId: ctx.runId, args: ctx.args }),
+    )
+    // `undefined` lets the call through. Returning nothing is not the same as approving nothing:
+    // this hook makes no decision, and that is the point of the docblock above.
+    return undefined
+  },
+
+  post_tool_call: (ctx) => {
+    const k = key(ctx.runId, ctx.name)
+    const startedAt = started.get(k)
+    started.delete(k)
+    console.info(
+      JSON.stringify({
+        event: 'tool.end',
+        tool: ctx.name,
+        runId: ctx.runId,
+        // Absent rather than zero when the start was never seen — a duration of 0ms would read as
+        // an instant call instead of as a missing measurement.
+        ms: startedAt === undefined ? undefined : Date.now() - startedAt,
+      }),
+    )
+  },
+}