create-theokit 1.23.7 → 1.23.8

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/agents/chat.ts

@@ -12,8 +12,7 @@ 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

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/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/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-ui/SKILL.md

@@ -25,8 +25,8 @@ paths:
 npm install @theokit/ui
 
 # Or from local tarball (when using source repo)
-cd ../theo-ui && npm pack    # produces theokit-ui-X.Y.Z.tgz
-cd ../my-app && npm install ../theo-ui/theokit-ui-X.Y.Z.tgz
+cd ../theokit-ui && npm pack    # produces theokit-ui-X.Y.Z.tgz
+cd ../my-app && npm install ../theokit-ui/theokit-ui-X.Y.Z.tgz
 ```
 
 **WARNING: NEVER use `npm link ../theo-ui` or `file:../theo-ui`.** The symlink exposes the sibling's nested `node_modules/react` (typically a different version), causing dual-React: "React Element from an older version" errors, broken hooks (`useState` null), and silent render failures. `resolve.dedupe` in Vite does NOT fix this — the pnpm structure physically has two React copies. Use tarball (`npm pack` → `npm install .tgz`) instead.
@@ -160,6 +160,6 @@ const myTheme = defineTheme({
 - NEVER build a custom markdown renderer — `ChatMessageContent` handles it (including streaming partial fences)
 - NEVER build a custom code highlighter — `CodeBlock` (from `@usetheo/ui`) uses shiki (lazy-loaded)
 - Import AI-agent-surface components (ChatThread, ChatMessage, ToolCallCard, etc.) from `@theokit/ui`; import generic primitives (Button, Input, CodeBlock, PageShell, Sidebar, Avatar, Alert) from `@usetheo/ui` — both are live packages since the 2026-07-03 pivot (`@theokit/ui` depends on `@usetheo/ui`)
-- NEVER use `npm link` or `file:../theo-ui` to install — causes dual-React (use tarball or npm registry)
+- NEVER use `npm link` or `file:../theokit-ui` to install — causes dual-React (use tarball or npm registry)
 - NEVER install ALL peer deps — only install the peers for components you actually use
 - NEVER use components without wrapping in `TheoUIProvider` + `ThemeProvider` first

package/templates/default/eslint.config.mjs

@@ -12,14 +12,14 @@ export default tseslint.config(
     },
   },
   {
-    // Arquivos de declaração carregam as augmentações de módulo do TheoKit — `JobRegistry` em
-    // `types/jobs.d.ts` nasce VAZIA de propósito, para o app preencher conforme cria jobs. Sem esta
-    // exceção, um app recém-scaffoldado reprova no próprio `npm run lint` no minuto zero (#93), e a
-    // primeira lição que o TheoKit dá é que o gate dele mente.
+    // Declaration files carry TheoKit's module augmentations — `JobRegistry` in `types/jobs.d.ts`
+    // is born EMPTY on purpose, for the app to fill in as it creates jobs. Without this exception, a
+    // freshly scaffolded app fails its own `npm run lint` at minute zero (#93), and the first lesson
+    // TheoKit teaches is that its gate lies.
     //
-    // `allowInterfaces: 'always'` em vez de desligar a regra: interface vazia é a forma canônica de
-    // declaration merging, mas `type X = {}` continua sendo acusado — e esse ainda é um erro de
-    // verdade, porque `{}` aceita qualquer valor não-nulo, inclusive `0` e `""`.
+    // `allowInterfaces: 'always'` rather than disabling the rule: an empty interface is the canonical
+    // form of declaration merging, but `type X = {}` is still flagged — and that one is a real error,
+    // because `{}` accepts any non-null value, including `0` and `""`.
     files: ['**/*.d.ts'],
     rules: {
       '@typescript-eslint/no-empty-object-type': ['error', { allowInterfaces: 'always' }],

package/templates/default/index.html

@@ -1,13 +1,13 @@
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
-<head>
-  <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>TheoKit App</title>
-  <meta name="description" content="Built with TheoKit — the app your agent lives in" />
-  <link rel="icon" href="/favicon.svg" />
-</head>
-<body>
-  <div id="root"></div>
-</body>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>TheoKit App</title>
+    <meta name="description" content="Built with TheoKit — the app your agent lives in" />
+    <link rel="icon" href="/favicon.svg" />
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
 </html>

package/templates/default/package.json.tmpl

@@ -15,10 +15,10 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.46.1",
-    "@theokit/agents": "^7.3.1",
-    "@theokit/sdk": "^4.0.1",
-    "@theokit/ui": "^1.0.0",
+    "theokit": "^0.48.3",
+    "@theokit/agents": "^10.1.0",
+    "@theokit/sdk": "^4.52.1",
+    "@theokit/ui": "^1.1.0",
     "@usetheo/ui": "^0.26.0",
     "lucide-react": "^0.469.0",
     "react": "^19.0.0",