create-curb.js 0.0.0 → 1.15.0-preview.1

package/package.json

@@ -1,7 +1,30 @@
 {
   "name": "create-curb.js",
-  "version": "0.0.0",
-  "description": "Placeholder until the first Curb release.",
+  "version": "1.15.0-preview.1",
+  "description": "Create a Curb voice agent: npm create curb.js my-agent",
   "license": "Apache-2.0",
-  "repository": { "type": "git", "url": "git+https://github.com/Kugelaudio/curb.js.git" }
+  "homepage": "https://curbjs.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Kugelaudio/curb.js.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "bin": {
+    "create-curb.js": "./bin/create-curb.js"
+  },
+  "files": [
+    "bin",
+    "templates",
+    "NOTICE",
+    "RELEASE_NOTES.md"
+  ],
+  "scripts": {
+    "test": "node --test \"test/**/*.test.mjs\""
+  },
+  "dependencies": {
+    "picocolors": "^1.1.1"
+  }
 }

package/templates/default/.mcp.json

@@ -0,0 +1,6 @@
+{
+  "mcpServers": {
+    "kugelaudio": { "type": "http", "url": "https://www.kugelaudio.com/mcp" },
+    "kugelaudio-docs": { "type": "http", "url": "https://docs.kugelaudio.com/mcp" }
+  }
+}

package/templates/default/AGENTS.md

@@ -0,0 +1,160 @@
+# AGENTS.md
+
+This is a **curb.js** voice agent. React renders the agent's context (its prompt, knowledge
+and tools) instead of HTML, and the framework runs the call: speech, turn-taking,
+interruptions. You edit `src/agent/` and `context/`; components come from `"curb"`, the
+providers from `"curb/providers"`. The project starts as Juno, a demo assistant: replace
+her prompt, skills and tools with the user's agent and delete what it does not need.
+
+The agent runs on KugelAudio: its EU-hosted LLM (`kugelaudio.llm()`), Kugel Ear and Kugel TTS.
+Sign in with `npx curb login` in this folder: it opens the browser once to sign in, and
+every curb command here then runs on that login (`--no-open` only prints the link, for a
+machine without a browser). There is no key to copy; never ask for a key in the chat. A `KUGELAUDIO_API_KEY` the user sets in `.env` or the environment (an
+API key from the dashboard, for CI or a server) also works and wins over the login. Another
+LLM (`anthropic()`, `openai()`, `openaiCompatible()`) is one `llm` prop away and brings its
+own key. A turn answered 403 `LLM_NOT_ENABLED` means the user's organization does not have
+KugelAudio's LLM yet (it comes with hosted agents, in closed alpha): they ask
+hello@kugelaudio.com, or the agent uses another LLM meanwhile.
+
+**Without a shell** (claude.ai, the Claude desktop chat), or when the person asks for it, build
+in the agent's **browser project**: the platform keeps the project, the person's own browser
+tab runs it, and you work through the `kugelaudio` MCP server's tools. Run no command and ask
+the person to run none.
+
+1. `agent_list` finds the agent, or `agent_create` makes one named for what it does. `agent_open`
+   answers its session link: the person opens it beside the chat and keeps that tab open.
+   Every tool below but `agent_publish` runs in the tab, and a closed tab is refused with the
+   link to send.
+2. `agent_overview` shows the project. Read with `agent_read_file`, `agent_list_files` and
+   `agent_search`; change it with `agent_edit_file`, `agent_write_file` and `agent_delete_file`.
+   Read `reload` in each change's answer and fix `failed` diagnostics first.
+3. `agent_add_dependency` and `agent_remove_dependency` change the packages. One that needs
+   native addons, a shell or child processes does not run in the browser.
+4. `agent_request_secret` makes the tab ask the person for a key. It stays in that tab, and
+   `agent_publish` does not deploy it; say so when the live agent needs the key too.
+5. After every change run `agent_check`, then `agent_say` with what a caller says
+   (`new_conversation` after a code change). `agent_get_preview_log` shows what went wrong,
+   `agent_list_preview_conversations` and `agent_get_preview_conversation` what the person
+   said in the tab, and `agent_restart_preview` unsticks a preview.
+6. `agent_publish` puts it live. Run it only when the person asks.
+
+With a shell, the rest of this file applies as it stands.
+
+**Say what you do.** Before each step (creating the project, installing, checking, signing
+in, deploying), tell the user in one plain sentence what it does and what, if anything, they
+have to do, such as open a sign-in link. They may never have used a terminal.
+
+A new project is created with `npm create curb.js my-agent`, and you then work in
+`my-agent` (`npm create curb.js .` fills the current empty folder instead).
+
+The full guide ships in `node_modules/curb/docs/agent-guide/`: read `README.md` first, then
+`what-the-model-receives.md`, `agents-and-skills.md`, `tools.md`, `state.md` and `testing.md`.
+There is one page per task, such as `human-handoff.md` and `confirmations.md`;
+`api-reference.md` leads to every export, and `improve-from-calls.md` is the way to fix an
+agent from a call that went wrong.
+A fault in Curb itself is reported as `reporting-a-bug.md` says, with the person's yes first.
+
+## Verify every change
+
+1. `npx curb check`: type-checks `src/`, renders every skill and prints warnings. Fix every
+   error and every warning; each one names a file, a line and the fix.
+2. `npx curb say "<what the caller says>"`: one spoken turn, headless. It prints the reply,
+   each tool call and the context it changed. The next `curb say` continues the
+   conversation; `npx curb say --new "<first line>"` starts over (do that after a code change).
+3. `npx curb test`: runs every `src/**/*.scenario.ts` conversation headlessly, with scripted
+   caller lines or a simulated caller pursuing a goal, and fails on turn errors, repeated
+   sentences or a goal not reached. Keep one scenario per flow that matters (`testing.md`).
+
+4. `npm run dev`: the browser preview with chat and voice on http://127.0.0.1:4000. Open it in the person's own browser yourself (`open http://127.0.0.1:4000` on macOS, `xdg-open` on Linux, `start` on Windows): a browser built into an app, like the Claude app's Browser pane, blocks the microphone, so a call there fails.
+
+**To improve the agent, read its recent conversations first.** `npx curb conversations`
+prints the last ones the preview and `curb say` ran, with every tool call, its
+input and its result (`--last <n>`, `--id <id>`, `--json`). Calls to the hosted agent are
+read with the `kugelaudio` MCP server's `agent_list_calls`, `agent_get_call` and
+`agent_get_call_timeline` where it is signed in. Find where the agent went wrong, fix that,
+and turn the conversation into a scenario so it stays fixed.
+
+## The preview
+
+It shows what the agent sees: its prompt, the skills it has loaded and the tools it can
+call. You change the agent by editing code, never in the preview; a tool's form there only
+tries the tool, and `<Tool tryWith={{ ... }}>` fills it with values your demo data knows.
+**Copy for coding agent** copies a conversation with the skill map, so you can work from
+what really happened.
+
+## Map
+
+```text
+src/agent/agent.tsx         the agent, where every conversation starts: <Agent llm stt tts>,
+                            system prompt, skills index, tools every skill has, store
+src/agent/<name>/skill.tsx  one folder per skill, opened when needed; nested folders are sub-skills
+context/*.md                knowledge a skill reads with <Text src="file.md" />
+.env                        other providers' keys, an optional KUGELAUDIO_API_KEY; never commit it
+.data/conversations.jsonl   every local conversation: tool calls, inputs, results
+```
+
+## Rules
+
+- **Prose is one template literal**: ``<Instruction>{`...`}</Instruction>``, the same in
+  `<SystemPrompt>` and `<Text>`. Paragraphs and `- ` lists reach the model; multi-line JSX
+  text is joined into one line.
+- **A skill's description is written once**, as `meta.description` in its `skill.tsx`,
+  phrased as a routing rule ("Use for ...", "NOT for ..."). Its `<Skill>` link repeats none
+  (a `description` on the link works too, but keep one).
+- **No per-call state at module scope**: one runner serves several calls. Keep a call's
+  state in a `createAgentStore` store, never in a module-level variable.
+- **Secrets** come from `.env` locally and `npx curb secrets push` when hosted. Read them
+  in tool handlers (`process.env.NAME`); never render them into a prompt.
+- **A key never goes into a tool call.** Never paste one into a command line, a chat message
+  or an MCP tool's arguments (`agent_set_secrets` included). The user puts it in `.env`
+  themselves, and `npx curb secrets push` sends it to the hosted agent. A hosted agent gets
+  `KUGELAUDIO_API_KEY` from KugelAudio, so the default agent has nothing to push.
+- **No hard-coded names or dates.** The framework tells the model today's date on every
+  turn; set `defineAgent({ timeZone })` to the callers' zone (default UTC). Examples use
+  placeholders such as "Max Mustermann" or "the caller's name".
+- **The opening says it is an AI**: the agent's first line tells the caller they are talking
+  to an AI assistant. For exact words, use `defineAgent({ firstTurn: { say } })`.
+- **A tool's `schema` is what the model sees**: lists (`z.array`), nested objects,
+  `.nullable()`, enums, ranges and `.regex()` all reach it, so pass a list as a list, never
+  as one string to split. Give every field a `.describe()`.
+- **No prompt asks for "one moment" lines around tools**: Curb holds back the newest sentence
+  before a tool call, so a lone "One moment." is never spoken, but of two sentences the first is.
+- **Only an action with consequences** (it books, sends, pays or cancels) uses
+  `<Tool confirm={(input) => "<read-back question>"}>`: the framework runs it only after the
+  caller's next turn says yes. To repeat a detail back (a name, a number), say it in the
+  reply; a confirm tool turns the caller's next words into the answer to its question.
+- **Gate with state, not prompt text**: a tool that is not rendered does not exist for the
+  model. Render it from store state, and give a locked branch text that says how to unlock it.
+- **What counts as a successful call is code too**: `defineAgent({ goals, experiments })`
+  names each goal (a tool that must succeed, or a sentence a judge checks) and each A/B test
+  with its weighted variants, and `useVariant("<test>")` reads the call's variant. The
+  dashboard only shows the results; `authoring.md` ("Goals and A/B experiments") has the rules.
+- Tool names are unique snake_case verbs. Zod `.describe()` texts and error messages are
+  read by the model, so phrase them as the next step.
+
+## Deploy to KugelAudio
+
+`.mcp.json` registers two MCP servers for Claude Code started in this folder (it asks once
+to use them): `kugelaudio`, your KugelAudio account (sign in from `/mcp`), and
+`kugelaudio-docs`, the docs (no sign-in). Another client adds
+`https://www.kugelaudio.com/mcp` as a remote MCP server. Look KugelAudio facts up with
+`search_docs` and `read_docs_page`; for hosted agents use the `kugelaudio` server's,
+since `kugelaudio-docs` serves public pages only. Deploy and read build and call logs
+with the `kugelaudio` tools: `agent_create` (once), `agent_create_upload`, `agent_deploy`,
+`agent_get_logs`; keys reach it only through `npx curb secrets push`. Without them:
+
+```bash
+npx curb login --no-open  # once; prints a sign-in link and waits up to 5 minutes
+npx curb secrets push     # the .env keys onto the hosted agent; prints names, never values
+npx curb deploy           # build and go live; prints the playground URL
+```
+
+Not signed in? Do not stop there: run `npx curb login --no-open` in the background, give
+the user the link it prints to open in their browser on this machine, and go on once it
+prints `Signed in as`. Hosted agents are in a
+closed alpha, switched on per organization: on `CURB_HOSTED_AGENTS_NOT_ENABLED` the user
+asks hello@kugelaudio.com, and `curb dev` and `curb say` keep working meanwhile. A dry run
+is `npx curb deploy --no-activate` (or `npx curb build`, which uploads nothing).
+
+Run `npx curb check` before deploying. `.env*`, `node_modules/`, `.git/`, `.curb/` and
+`.data/` are never uploaded. Details: `node_modules/curb/docs/agent-guide/deploying.md`.

package/templates/default/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/default/README.md

@@ -0,0 +1,60 @@
+# {{APP_NAME}}
+
+A voice agent built with **curb.js**: React renders the agent's prompt, knowledge and
+tools instead of HTML. It starts as **Juno**, a demo personal assistant, so you can try
+the framework before you change anything.
+
+## Run it
+
+Sign in with `npx curb login`; there is no key to copy. Every curb command in this folder
+then runs on your login: KugelAudio's EU-hosted LLM thinks, Kugel Ear listens and Kugel TTS
+speaks. A deployed agent gets its access from KugelAudio. Prefer an API key (CI, a server)?
+Set `KUGELAUDIO_API_KEY` in `.env`; it wins over the login. Another provider's key goes in
+`.env` too, which `npm create curb.js` already wrote.
+
+```bash
+npx curb login            # sign in in the browser; Curb uses your login
+npm run dev               # preview, chat and voice on http://127.0.0.1:4000
+npx curb check            # types, render and warnings
+npx curb say "Hallo"      # one caller turn in the terminal, no browser
+```
+
+## Meet Juno
+
+Type or talk in the preview:
+
+- **"Put buy milk on my list."** The `add_task` tool updates shared state, and the task
+  list in Juno's context changes with it.
+- **"What do you know about me?"** Juno reads the about-you skill, whose profile is
+  `context/about-you.md`. Edit the file and ask again.
+- **"Wrap up my day."** The `wrap_up_day` tool exists only once a task is done, so with
+  nothing done she cannot.
+- **"How do you work?"** Juno explains how she is built.
+
+## Where things live
+
+- `src/agent/agent.tsx`: the agent, where every conversation starts: its providers
+  (`<Agent llm stt tts>`), system prompt, skills index, and the task list with its tools.
+- `src/agent/<name>/skill.tsx`: one folder per skill, opened only when the conversation
+  needs it.
+- `context/`: markdown the skills read.
+
+## Deploy to KugelAudio
+
+```bash
+npx curb login
+npx curb secrets push
+npx curb deploy
+```
+
+`deploy` prints the playground URL where you can call the live agent. Your `.env` is
+never uploaded; `secrets push` sends its values and prints only their names. Details:
+`node_modules/curb/docs/agent-guide/deploying.md`. To run the voice worker on your own LiveKit instead,
+see `node_modules/curb/docs/agent-guide/hosting.md`.
+
+## Learn more
+
+`AGENTS.md` briefs coding agents (and you) on the rules; `CLAUDE.md` imports it for
+Claude Code. `.mcp.json` connects Claude Code to your KugelAudio account (sign in from
+`/mcp`) and to the KugelAudio docs. The full guide is in
+`node_modules/curb/docs/agent-guide/`.

package/templates/default/context/about-you.md

@@ -0,0 +1,13 @@
+# About you
+
+Edit this file with your real details: the agent's knowledge hot-reloads, no restart needed.
+
+- **Name:** Your name here
+- **City:** Where you live
+- **What I do:** Your job, studies, or main project
+
+## Preferences
+
+- I prefer short answers
+- Tea, not coffee
+- Replace these bullets with your own

package/templates/default/env.example

@@ -0,0 +1,16 @@
+# Keys only. Which providers run is chosen in src/agent/agent.tsx (<Agent llm stt tts>).
+# A chosen provider whose key is missing fails with an error naming its variable; the
+# table in node_modules/curb/docs/agent-guide/configuration.md lists every key. A new
+# provider's key also goes into package.json curb.requiredRuntimeSecrets.
+# Every curb command loads .env, and `npx curb secrets push` copies it to the hosted agent.
+
+# KugelAudio runs the whole agent: its EU-hosted LLM thinks (kugelaudio.llm()), Kugel Ear
+# listens (kugelaudio.stt()) and Kugel TTS speaks (kugelaudio.tts()). A hosted agent gets
+# access from the platform.
+# Locally, KugelAudio access comes from `npx curb login`: there is no key to copy.
+# KUGELAUDIO_API_KEY=   # optional: an API key instead of npx curb login (CI, servers)
+
+# Your own LiveKit, only for `npm start` (the self-hosted voice worker):
+# LIVEKIT_URL=wss://your-project.livekit.cloud
+# LIVEKIT_API_KEY=
+# LIVEKIT_API_SECRET=

package/templates/default/gitignore

@@ -0,0 +1,15 @@
+node_modules/
+dist/
+
+# secrets — never commit these
+.env
+.env.local
+.env*.local
+.mcp-auth/
+
+# generated / runtime state
+.curb/
+.data/
+context/context.index.json
+
+.DS_Store

package/templates/default/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "{{APP_NAME}}",
+  "private": true,
+  "type": "module",
+  "curb": {
+    "requiredRuntimeSecrets": [
+      "KUGELAUDIO_API_KEY"
+    ]
+  },
+  "scripts": {
+    "dev": "curb dev",
+    "check": "curb check",
+    "start": "curb start",
+    "server": "curb server",
+    "upgrade": "curb upgrade"
+  },
+  "allowScripts": {
+    "@livekit/blingfire": false,
+    "@livekit/local-inference": false,
+    "esbuild": false,
+    "fsevents": false,
+    "onnxruntime-node": false
+  },
+  "dependencies": {
+    "curb": "{{FRAMEWORK_SPEC}}",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.17",
+    "typescript": "^6.0.3"
+  }
+}

package/templates/default/src/agent/about-you/skill.tsx

@@ -0,0 +1,52 @@
+import { Instruction, Text, Tool, z, type SkillMeta } from "curb";
+import { useAssistant } from "../agent.js";
+
+export const meta: SkillMeta = {
+  title: "About you",
+  description: "Use for anything about the user themselves: their name, preferences, facts to remember.",
+};
+
+/**
+ * A file-backed skill: the profile lives in context/about-you.md and reaches the model's
+ * context through <Text src>. Edit the markdown and Juno's knowledge changes live. The
+ * remember tool writes to the same shared store her day planner in agent.tsx reads.
+ */
+
+const rememberSchema = z.object({
+  note: z
+    .string()
+    .min(1)
+    .describe("One short fact or preference in third person, e.g. 'prefers tea over coffee'."),
+});
+
+export default function AboutYou() {
+  const notes = useAssistant((s) => s.notes);
+  const remember = useAssistant((s) => s.remember);
+
+  return (
+    <>
+      <Instruction>{`
+        Answer questions about the user from the profile below and the remembered notes.
+        While the profile still holds placeholder text, invite the user once to put their own
+        details into context/about-you.md: your knowledge updates live, no restart needed.
+      `}</Instruction>
+
+      {notes.length === 0
+        ? "No notes remembered yet this session."
+        : `Remembered this session: ${notes.join("; ")}.`}
+
+      <Tool
+        schema={rememberSchema}
+        name="remember"
+        description="Save a lasting fact or preference the user just told you about themselves."
+        success="Noted. It is now part of the context in every skill that shows it."
+        onSubmit={(input) => {
+          remember(input.note);
+          return { ok: true };
+        }}
+      />
+
+      <Text src="about-you.md" />
+    </>
+  );
+}

package/templates/default/src/agent/agent.tsx

@@ -0,0 +1,223 @@
+import {
+  Agent,
+  GlobalTools,
+  Skill,
+  Skills,
+  SystemPrompt,
+  Text,
+  Tool,
+  createAgentStore,
+  defineAgent,
+  z,
+} from "curb";
+import { kugelaudio } from "curb/providers";
+
+/**
+ * Juno, the demo assistant of a new project. This file is the agent level, where every
+ * conversation starts: her prompt, her day planner (the task list and its tools) and the
+ * skills she opens only when needed. Her profile of the user is a markdown file, and wrapping
+ * up the day exists as a tool only once a task is done. Replace her with your own agent; the
+ * shape (system prompt, skills index, tools, store) stays.
+ */
+
+export type Task = { title: string; done: boolean };
+
+export const useAssistant = createAgentStore<{
+  tasks: Task[];
+  notes: string[];
+  addTask: (title: string) => void;
+  completeTask: (title: string) => void;
+  removeTask: (title: string) => void;
+  clearCompleted: () => void;
+  remember: (note: string) => void;
+}>("juno", (set) => ({
+  tasks: [],
+  notes: [],
+  addTask: (title) =>
+    set((state) => {
+      const exists = state.tasks.some(
+        (task) => task.title.toLowerCase() === title.toLowerCase(),
+      );
+      if (exists) return state;
+      return { tasks: [...state.tasks, { title, done: false }] };
+    }),
+  completeTask: (title) =>
+    set((state) => ({
+      tasks: state.tasks.map((task) =>
+        task.title.toLowerCase() === title.toLowerCase()
+          ? { ...task, done: true }
+          : task,
+      ),
+    })),
+  removeTask: (title) =>
+    set((state) => ({
+      tasks: state.tasks.filter(
+        (task) => task.title.toLowerCase() !== title.toLowerCase(),
+      ),
+    })),
+  clearCompleted: () =>
+    set((state) => ({ tasks: state.tasks.filter((task) => !task.done) })),
+  remember: (note) => set((state) => ({ notes: [...state.notes, note] })),
+}));
+
+const addSchema = z.object({
+  title: z
+    .string()
+    .min(1)
+    .describe("Short task title, e.g. 'buy milk'. Keep it to a few words."),
+});
+
+const completeSchema = z.object({
+  title: z
+    .string()
+    .min(1)
+    .describe("Title of the task to mark done. Match a task from the open list."),
+});
+
+const removeSchema = z.object({
+  title: z.string().min(1).describe("Title of the task to remove from the list."),
+});
+
+/**
+ * Juno's day planner, in her context from the first turn. The task list is live state: a tool
+ * call updates the store, the component re-renders, and the model's context changes. Watch it
+ * in the preview's context inspector while you talk.
+ */
+function DayPlanner() {
+  const tasks = useAssistant((s) => s.tasks);
+  const notes = useAssistant((s) => s.notes);
+  const addTask = useAssistant((s) => s.addTask);
+  const completeTask = useAssistant((s) => s.completeTask);
+  const removeTask = useAssistant((s) => s.removeTask);
+  const clearCompleted = useAssistant((s) => s.clearCompleted);
+
+  const open = tasks.filter((task) => !task.done);
+  const done = tasks.filter((task) => task.done);
+
+  return (
+    <>
+      <Text>
+        {tasks.length === 0
+          ? "No tasks yet."
+          : [
+              open.length > 0 ? `Open tasks: ${open.map((t) => t.title).join(", ")}.` : null,
+              done.length > 0 ? `Done: ${done.map((t) => t.title).join(", ")}.` : null,
+            ]
+              .filter(Boolean)
+              .join(" ")}
+      </Text>
+
+      {/* Shared state across skills: the remember tool lives in /about-you,
+          but its effect is visible right here. */}
+      {notes.length > 0 ? (
+        <Text>{`Things I know about the user (remembered this session): ${notes.join("; ")}.`}</Text>
+      ) : null}
+
+      <GlobalTools>
+        <Tool
+          schema={addSchema}
+          name="add_task"
+          description="Add a task to the user's list for today."
+          success="Added to the list."
+          onSubmit={(input) => {
+            addTask(input.title.toLowerCase());
+            return { ok: true };
+          }}
+        />
+        <Tool
+          schema={completeSchema}
+          name="complete_task"
+          description="Mark a task on the list as done."
+          onSubmit={(input) => {
+            const match = open.find(
+              (task) => task.title.toLowerCase() === input.title.toLowerCase(),
+            );
+            if (!match) {
+              return {
+                ok: false,
+                message: `No open task titled "${input.title}". Retry with a title from the open task list.`,
+              };
+            }
+            completeTask(input.title);
+            return { ok: true, message: `Marked "${match.title}" done.` };
+          }}
+        />
+        <Tool
+          schema={removeSchema}
+          name="remove_task"
+          description="Remove a task from the list entirely, done or not."
+          onSubmit={(input) => {
+            removeTask(input.title);
+            return { ok: true, message: "Removed from the list." };
+          }}
+        />
+
+        {/* Structural gating: wrapping up the day does not exist for the model
+            until at least one task is done. No prompt text can route around it. */}
+        {done.length > 0 ? (
+          <Tool
+            name="wrap_up_day"
+            description="Wrap up the day: clear the completed tasks and recap what got done."
+            onSubmit={() => {
+              const count = done.length;
+              clearCompleted();
+              return {
+                ok: true,
+                message: `Day wrapped up: ${count} task${count === 1 ? "" : "s"} done and cleared, ${open.length} still open.`,
+              };
+            }}
+          />
+        ) : (
+          <Text>Wrap-up is locked: the wrap_up_day tool appears once at least one task is marked done.</Text>
+        )}
+      </GlobalTools>
+    </>
+  );
+}
+
+export function App() {
+  // The providers Juno talks through; their keys live in .env. She listens and speaks in
+  // English: another language sets `language` on both stt and tts, with a voice that speaks it.
+  return (
+    <Agent llm={kugelaudio.llm()} stt={kugelaudio.stt({ language: "en" })} tts={kugelaudio.tts()}>
+      <SystemPrompt>{`
+        You are Juno, a personal assistant for daily planning and the demo agent of this project.
+
+        You can:
+        - keep the user's task list,
+        - remember what they tell you about themselves,
+        - explain how you are built.
+
+        The task list changes only through its tools: call add_task, complete_task or remove_task first, and say a task is added or done only after the tool answered.
+
+        Greet the user as Juno and tell them that you are an AI assistant.
+        Then help them plan their day: offer to keep their task list.
+        Mention once that they can ask "how does this work?" to hear how this demo is built.
+        Be warm and brief: one or two sentences per reply.
+      `}</SystemPrompt>
+      {/* Each link's routing description is the target skill's meta.description. */}
+      <Skills>
+        <Skill path="/about-you">About you</Skill>
+        <Skill path="/how-this-works">How this works</Skill>
+      </Skills>
+      <DayPlanner />
+    </Agent>
+  );
+}
+
+export const agent = defineAgent({
+  app: App,
+  // Voice calls open with Juno's greeting; "user" waits for the caller instead.
+  firstTurn: "agent",
+  // Every turn tells the model today's date and time in this zone (default "UTC").
+  // timeZone: "Europe/Berlin",
+  preview: {
+    suggestedPrompts: [
+      "Put buy milk on my list",
+      "What do you know about me?",
+      "Remember that I prefer tea",
+      "How does this demo work?",
+    ],
+    chatPlaceholder: "What's on for today?",
+  },
+});

package/templates/default/src/agent/how-this-works/skill.tsx

@@ -0,0 +1,36 @@
+import { Instruction, Text, type SkillMeta } from "curb";
+import { useAssistant } from "../agent.js";
+
+export const meta: SkillMeta = {
+  title: "How this works",
+  description: "Use FIRST when the user asks how this demo, this agent, or the framework works.",
+};
+
+/**
+ * The demo explains itself. Loading this skill IS the demo of skill routing: the model
+ * read these instructions on demand because the user asked how things work.
+ */
+export default function HowThisWorks() {
+  const tasks = useAssistant((s) => s.tasks);
+  const notes = useAssistant((s) => s.notes);
+
+  return (
+    <>
+      <Instruction>{`
+        Explain how this agent is built, in plain spoken language, a couple of sentences at a time.
+        Invite the user to watch the preview's context inspector change while they talk.
+      `}</Instruction>
+
+      <Text>{`
+        How this project works:
+        - The agent is a React tree that renders context and tools for a language model instead of HTML.
+        - src/agent/agent.tsx is where every conversation starts: Juno's prompt, her task list and its tools are in her context from the first turn.
+        - Each folder under src/agent/ is a skill: instructions and tools the model reads on demand. Reading this skill is how this answer came about.
+        - The user's profile is the markdown file context/about-you.md, read by a Text component.
+        - Tasks and remembered notes are shared React state: a tool call updates the store, the tree re-renders, and the model's context changes. Tasks on the list right now: ${tasks.length}. Remembered notes: ${notes.length}.
+        - Wrapping up the day is gated structurally: the wrap_up_day tool does not exist in the model's context until a task is done.
+        - Everything editable lives in src/agent/ and context/, and changes hot-reload into the running conversation.
+      `}</Text>
+    </>
+  );
+}