create-theokit 1.4.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-theokit",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "type": "module",
   "description": "Scaffold a new TheoKit project",
   "license": "Apache-2.0",

package/templates/default/agents/chat.ts

@@ -1,25 +1,20 @@
 import { agent } from '@theokit/agents'
 import { z } from 'zod'
 
-import { BASE_INSTRUCTIONS } from './_lib/instructions.js'
-import { weatherTool } from './_tools/weather.js'
+import { BASE_INSTRUCTIONS } from './prompts/instructions.js'
+import { weatherTool } from './tools/weather.js'
 
 /**
- * Chat agent — the zero-config `agents/*.ts` convention.
+ * The `chat` agent — served at `POST /api/agents/chat` and bound by `useAgent('chat')`. This file IS the
+ * 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`.
  *
- * This one file is auto-served at `POST /api/agents/chat` (dev + build), streaming the
- * ai-sdk `UIMessageStream` that `useAgent('chat')` consumes on the client. No manual route,
- * no manual client wiring. `@theokit/sdk` runs it; conversation turns auto-persist per
- * session (the SDK owns storage).
- *
- * Provider: resolved from the environment — OPENROUTER_API_KEY (preferred — gateway to many
- * models) OR ANTHROPIC_API_KEY / OPENAI_API_KEY. The `model` id is prefixed with the provider
- * namespace so OpenRouter routes it upstream (see https://openrouter.ai/models).
- *
- * The agent is composed from its neighbours (see `docs/ARCHITECTURE.md`): the persona lives in
- * `agents/_lib/instructions.ts` and tools in `agents/_tools/` (both underscore-prefixed so the
- * route scanner skips them). Add a tool with `tool('name')…build()` and chain it via `.tool(...)`;
- * add a skill as `agents/skills/<name>.md`.
+ * `@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).
  */
 export default agent()
   .input(z.object({ message: z.string() }))

package/templates/default/agents/prompts/instructions.ts

@@ -0,0 +1,10 @@
+/**
+ * The `chat` agent's system prompt (persona + rules). Lives in `prompts/` — a semantic sub-folder the
+ * framework's agent scanner skips, so it never becomes a route. Grow the persona here instead of inlining
+ * a long string in `index.ts`.
+ */
+export const BASE_INSTRUCTIONS = `You are a helpful assistant living inside a TheoKit app.
+
+- Answer clearly and concisely.
+- When the user asks about current weather, call the \`weather\` tool instead of guessing.
+- If you are unsure, say so rather than inventing an answer.`

package/templates/default/agents/skills/getting-started.md

@@ -1,20 +1,21 @@
 # Getting started
 
 A **skill** is a Markdown file that documents a repeatable task for your agent — a recipe it (and you) can
-follow. Skills live in `agents/skills/` and are plain `.md`, so the route scanner ignores them; reference
-them from your instructions or load them into a prompt as your app grows.
+follow. Skills live in the agent's `skills/` folder and are plain `.md`; reference them from your prompt or
+load them into context as your app grows.
 
-This example just documents the scaffold itself:
+This example documents the scaffold itself:
 
 ## Answer a question
 
 1. Read the user's message.
-2. If it needs live weather, call the `weather` tool (see `agents/_tools/weather.ts`).
+2. If it needs live weather, call the `weather` tool (see `../tools/weather.ts`).
 3. Otherwise answer directly, concisely.
 
-## Add a capability
+## Add a capability to this agent
 
-- **A tool** (an action the agent can take) → `agents/_tools/<name>.ts`, then `.tool(<name>Tool)` in
+- **A tool** (an action the agent can take) → `agents/tools/<name>.ts`, then `.tool(<name>Tool)` in
   `agents/chat.ts`.
 - **A skill** (a documented procedure) → a new `agents/skills/<name>.md` like this one.
-- **The persona / rules** → edit `agents/_lib/instructions.ts`.
+- **The persona / rules** → edit `agents/prompts/instructions.ts`.
+- **A whole new agent** → a new folder `agents/<name>/index.ts` → served at `/api/agents/<name>`.

package/templates/default/agents/{_tools → tools}/weather.ts

@@ -5,8 +5,8 @@ import { z } from 'zod'
  * An example agent tool — current weather for a place, via the keyless open-meteo API.
  *
  * A tool is PURE metadata + a handler: it describes a capability and runs local/HTTP work; it NEVER calls
- * an LLM (the agent decides when to invoke it). Lives in `agents/_tools/` (underscore-prefixed) so the
- * route scanner skips it — it is imported into `agents/chat.ts` and chained with `.tool(weatherTool)`.
+ * an LLM (the agent decides when to invoke it). Lives in `tools/` — a semantic sub-folder the agent
+ * scanner skips — and is imported into `chat.ts` and chained with `.tool(weatherTool)`.
  *
  * Add your own the same way: `tool('name').describe(...).input(z.object({...})).execute(async (input) => …).build()`.
  */

package/templates/default/docs/ARCHITECTURE.md

@@ -1,18 +1,19 @@
 # Architecture
 
-How this TheoKit app is organized. The layout puts the **agent at the center** and keeps a clean split
-between the agent, the backend, the frontend, and cross-layer code.
+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
+"file = identity" convention agent frameworks like [Eve](https://eve.dev) use.
 
 ## Project structure
 
 ```
 .
-├── agents/                 # The agent lives here (auto-served at POST /api/agents/<name>)
-│   ├── chat.ts             #   the agent — composed from its neighbours below
-│   ├── _lib/               #   internal helpers (underscore = NOT a route)
-│   │   └── instructions.ts #     the system prompt / persona
-│   ├── _tools/             #   tools the agent can call (underscore = NOT a route)
-│   │   └── weather.ts      #     example: tool('weather')…build()
+├── 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      #     tool('weather')…build()
 │   └── skills/             #   Markdown procedures the agent (and you) can follow
 │       └── getting-started.md
 ├── app/                    # Frontend (web surface). tui → tui/, desktop → frontend/
@@ -24,13 +25,14 @@ between the agent, the backend, the frontend, and cross-layer code.
 └── theo.config.ts          # App config (name, dirs, plugins)
 ```
 
-## Why `_lib/` and `_tools/` have an underscore
+## Clean names, no phantom routes
 
-The framework turns **every `.ts` under `agents/` into a `POST /api/agents/<name>` endpoint** (that is the
-zero-config convention that lets `useAgent('chat')` bind with no manual wiring). Files that are *not*
-agents — the persona, the tools — would otherwise become phantom endpoints, so they live in
-underscore-prefixed folders, which the route scanner skips (the same convention Next.js uses for private
-folders). `skills/` needs no underscore because Markdown is never scanned.
+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**.
+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/`.
 
 ## Composition
 
@@ -40,13 +42,14 @@ folders). `skills/` needs no underscore because Markdown is never scanned.
 export default agent()
   .input(z.object({ message: z.string() }))
   .model('openai/gpt-4o-mini')
-  .system(BASE_INSTRUCTIONS)   // agents/_lib/instructions.ts
-  .tool(weatherTool)           // agents/_tools/weather.ts
+  .system(BASE_INSTRUCTIONS)   // agents/prompts/instructions.ts
+  .tool(weatherTool)           // agents/tools/weather.ts
   .build()
 ```
 
-Grow the agent by editing its neighbours, not by inflating `chat.ts`: persona → `_lib/instructions.ts`,
-a new capability → `_tools/<name>.ts` (then `.tool(<name>Tool)`), a documented procedure → `skills/<name>.md`.
+Grow the agent by editing its neighbours, not by inflating `chat.ts`: persona → `prompts/instructions.ts`,
+a new capability → `tools/<name>.ts` (then `.tool(<name>Tool)`), a documented procedure →
+`skills/<name>.md`. Add a **second agent** as another `agents/<name>.ts`.
 
 ## Surfaces
 

package/templates/default/docs/CUSTOMIZATION.md

@@ -5,18 +5,18 @@ Common changes, and where they go. See [ARCHITECTURE](./ARCHITECTURE.md) for the
 | I want to… | Edit |
 |------------|------|
 | Change the model | `agents/chat.ts` (`.model(...)`) + the label in `shared/agent.ts` |
-| Change the persona / rules | `agents/_lib/instructions.ts` |
-| Add a tool (an action the agent can take) | new `agents/_tools/<name>.ts`, then `.tool(<name>Tool)` in `agents/chat.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 documented procedure) | new `agents/skills/<name>.md` |
-| Change the greeting / app name | `shared/agent.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
 
 ```ts
-// agents/_tools/echo.ts
+// agents/tools/echo.ts
 import { tool } from 'theokit/server'
 import { z } from 'zod'
 
@@ -29,7 +29,7 @@ export const echoTool = tool('echo')
 
 ```ts
 // agents/chat.ts
-import { echoTool } from './_tools/echo.js'
+import { echoTool } from './tools/echo.js'
 // …
   .tool(weatherTool)
   .tool(echoTool)   // chain as many as you need

package/templates/default/package.json.tmpl

@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "theokit": "^0.30.3",
+    "theokit": "^0.31.0",
     "@theokit/agents": "^0.35.2",
     "@theokit/sdk": "^2.13.0",
     "@theokit/ui": "^1.0.0",

package/templates/default/agents/_lib/instructions.ts

@@ -1,15 +0,0 @@
-/**
- * The agent's base system prompt.
- *
- * Kept in `agents/_lib/` (an underscore-prefixed folder) so the framework's `agents/*` route scanner
- * skips it — only real agents like `agents/chat.ts` become `POST /api/agents/<name>` endpoints. Import
- * this into an agent's `.system(...)`; grow it here (persona, guardrails, tool guidance) instead of
- * inlining a long string in the agent file.
- */
-import { AGENT } from '../../shared/agent.js'
-
-export const BASE_INSTRUCTIONS = `You are ${AGENT.name}, a helpful assistant living inside a TheoKit app.
-
-- Answer clearly and concisely.
-- When the user asks about current weather, call the \`weather\` tool instead of guessing.
-- If you are unsure, say so rather than inventing an answer.`