@standardagents/agentbuilder-template 0.45.1 → 0.45.3

package/dist/index.js

@@ -1,521 +1,370 @@
 // src/docs/root.ts
-var ROOT_AGENTS_MD = `# Standard Agents
+var ROOT_AGENTS_MD = `# Building agents in this project
 
-This project uses Standard Agents - a framework for building AI agents on Cloudflare Workers.
+This project builds AI agents with Standard Agents. You define agents as TypeScript files under \`agents/\`. The framework discovers them, runs them, and serves a builder UI for testing them. There is no registration step and no Cloudflare configuration to write.
 
-## Architecture Overview
+Each directory under \`agents/\` has its own \`AGENTS.md\` with the full reference for that kind of file. This file covers what the pieces are, the agent the project starts with, and how to build your own.
 
-Standard Agents uses a **composition model** where four core components work together:
+## The pieces
 
+\`\`\`text
+Model -> Prompt -> Agent -> Thread
 \`\`\`
-Model \u2192 Prompt \u2192 Agent \u2192 Thread
-  \u2502        \u2502        \u2502        \u2502
-  \u2502        \u2502        \u2502        \u2514\u2500 Conversation instance (Durable Object)
-  \u2502        \u2502        \u2514\u2500 Orchestrates conversation flow
-  \u2502        \u2514\u2500 System instructions + tools
-  \u2514\u2500 LLM provider configuration
-\`\`\`
 
-**Models** define which LLM to use (provider, model ID, pricing, fallbacks).
-**Prompts** define what the LLM should do (system instructions, available tools).
-**Agents** orchestrate conversations. An agent has exactly two sides; each side is backed by a human (\`{ human: true }\`), a prompt (\`{ prompt: 'name' }\`), or a handler (\`{ handler: 'name' }\` \u2014 deterministic code from \`agents/handlers/\`).
-**Threads** are individual conversation instances with persistent storage.
-
-## Packability and Runtime Portability
-
-Treat an agent project as an installable Standard Agent package, not as a
-privileged extension of one runtime. Everything required for the declared
-agents to execute must use capabilities defined by the Standard Agent
-Specification and exported with the package.
-
-Do not make required behavior depend on private Durable Object methods,
-implementation-specific storage schemas or bindings, undocumented HTTP or
-WebSocket events, product sidecars that replace runtime behavior, or
-ThreadState._notPackableRuntimeContext. Client-side state may be an
-optimistic cache, but it must not become the only source of truth for agent
-semantics.
-
-If the specification lacks a required primitive, define the runtime-neutral
-capability in @standardagents/spec, document it in the public specification,
-implement it generically in the runtime, and add conformance coverage before
-the agent relies on it. Authentication, billing, deployment, and branded UI
-services may remain external as long as they are not required for the packed
-agent's core execution semantics.
-
-## Packaging and Definition Visibility
-
-The packer follows side \`subagents\` relationships and includes child agents
-and their dependencies. This includes hidden children and relationships with
-\`as\`. The package includes referenced handlers and exports a \`handlers\`
-registry. The pack and unpack dialogs list handlers. Unpack analysis reports an agent\u2019s handlers and side \`subagents\` relationships.
-In the pack dialog, a handler defaults to extract. Shared handlers default to copy. Extract removes
-the local file; copy keeps it. Dependencies reached by another local agent,
-including through its children, default to copy.
-
-The runtime discovers packages in \`node_modules\` and \`agents/packed/\`.
-It loads definitions from lazy registries and \`__meta\` exported by each
-package entry module. A malformed \`package.json\` or missing or invalid
-\`__meta\` produces a warning and the runtime skips that package.
-
-\`ThreadState.loadModel\`, \`loadPrompt\`, and \`loadAgent\` enforce package
-visibility. Global code can load unpacked definitions and packed entry agents.
-Packed code can load its own definitions and other packages' entry agents.
-A packed model cannot fall back to a host model with the same short name.
-A refused load returns the same not-found error as a missing definition.
-
-## How Components Compose
-
-### Basic Flow
-1. User creates a thread with an agent
-2. Agent uses its configured prompt
-3. Prompt specifies the model and tools
-4. LLM responds, potentially calling tools
-5. Tools execute and return results
-6. Loop continues until stop condition
-
-### Sub-Prompts (Prompts as Tools)
-Prompts can call other prompts as tools. This enables:
-- **Specialized reasoning**: A main prompt delegates to expert sub-prompts
-- **Structured outputs**: Sub-prompt validates and formats data
-- **Context isolation**: Sub-prompt gets fresh context without full history
+- A **model** names an LLM and the provider that serves it.
+- A **prompt** holds system instructions, picks a model, and lists the tools the model may call.
+- An **agent** is a conversation between two sides. Each side is a person (\`{ human: true }\`), a prompt (\`{ prompt: 'name' }\`), or a handler (\`{ handler: 'name' }\`, plain code).
+- A **thread** is one running conversation with an agent. It has its own message history, files, and key-value store.
+
+| Function | What it defines | Directory |
+|----------|-----------------|-----------|
+| \`defineModel()\` | An LLM and its provider | \`agents/models/\` |
+| \`defineProvider()\` | A custom provider endpoint | \`agents/providers/\` |
+| \`definePrompt()\` | Instructions, model, and tools | \`agents/prompts/\` |
+| \`defineAgent()\` | The two sides of a conversation | \`agents/agents/\` |
+| \`defineTool()\` | A function the model can call | \`agents/tools/\` |
+| \`defineHook()\` | Code that runs at lifecycle points | \`agents/hooks/\` |
+| \`defineHandler()\` | Code that takes a side's turns | \`agents/handlers/\` |
+| \`defineThreadEndpoint()\` | An HTTP route on a thread | \`agents/api/\` |
+| \`defineUserEndpoint()\` | An HTTP route on a user | \`agents/users/\` |
+
+Import \`defineThreadEndpoint\` and \`defineUserEndpoint\` from \`@standardagents/spec\`. Import the rest from \`@standardagents/builder\`.
+
+## The starter agent
+
+A project created through the Standard Agents platform starts with one working agent, **Guide**. It answers questions about building agents and about the Standard Agent Specification. Run the project, choose **Guide**, and send a message; it needs no file edits and no provider key.
+
+| File | What it is |
+|------|------------|
+| \`agents/agents/guide_agent.ts\` | The agent \`guide_agent\`: the prompt \`guide\` on one side, a person on the other |
+| \`agents/prompts/guide.ts\` | The prompt \`guide\`: its instructions, the model \`low_cost\`, and the tool \`read_docs\` |
+| \`agents/models/low_cost.ts\` | The model \`low_cost\`: a low-cost open model served by Novita AI, paid for by the platform account key |
+| \`agents/tools/read_docs.ts\` | The tool \`read_docs\`: reads a page from the builder documentation or the specification site, and no other site |
+
+Guide reads the published documentation each time it answers, so it stays current without a code change. It cannot read or change the files in this project.
+
+These four are ordinary definition files. Read them as a working example, change them, or delete them once the project has its own agents. Before deleting \`agents/models/low_cost.ts\` or \`agents/tools/read_docs.ts\`, check that no other prompt uses them. If a project does not have these files, nothing else depends on them.
+
+## Build your first agent
+
+A working agent needs three files: a model, a prompt that uses it, and an agent that uses the prompt. Create them as written.
 
 \`\`\`typescript
-// Main prompt can call 'data_extractor' as a tool
-definePrompt({
-  name: 'main_assistant',
-  tools: ['data_extractor'],  // Another prompt exposed as tool
-  // ...
+// agents/models/default.ts
+import { defineModel } from '@standardagents/builder';
+import { openai } from '@standardagents/openai';
+
+export default defineModel({
+  name: 'default',
+  provider: openai,
+  model: 'gpt-5.4-mini',
 });
 \`\`\`
 
-### Agent Handoffs (Agents as Tools)
-Agents can delegate to other agents entirely:
-- **Specialization**: Route to domain-specific agents
-- **Escalation**: Hand off to more capable agents
-- **Workflows**: Chain agents for multi-step processes
-
 \`\`\`typescript
-defineAgent({
-  name: 'triage_agent',
-  exposeAsTool: true,
-  toolDescription: 'Hand off to triage for initial assessment',
-  // ...
+// agents/prompts/assistant.ts
+import { definePrompt } from '@standardagents/builder';
+
+export default definePrompt({
+  name: 'assistant',
+  toolDescription: 'A general-purpose assistant',
+  model: 'default',
+  prompt: 'You are a helpful assistant. Answer clearly and briefly.',
+  includeChat: true,
 });
 \`\`\`
 
-## File Structure
+\`\`\`typescript
+// agents/agents/assistant_agent.ts
+import { defineAgent } from '@standardagents/builder';
 
-\`\`\`
-AGENTS.md                  # Project guidance for AI coding tools
-CLAUDE.md -> AGENTS.md     # Compatibility symlink
-vite.config.ts             # Uses builder(); Cloudflare config is generated
-tsconfig.json              # Includes agents and generated .agents types
-pnpm-workspace.yaml        # Dependency script approvals for pnpm projects
-agents/
-\u251C\u2500\u2500 agents/                # Agent definitions (defineAgent)
-\u2502   \u251C\u2500\u2500 AGENTS.md
-\u2502   \u2514\u2500\u2500 CLAUDE.md -> AGENTS.md
-\u251C\u2500\u2500 prompts/               # Prompt definitions (definePrompt)
-\u2502   \u251C\u2500\u2500 AGENTS.md
-\u2502   \u2514\u2500\u2500 CLAUDE.md -> AGENTS.md
-\u251C\u2500\u2500 handlers/              # Handler definitions (defineHandler)
-\u2502   \u251C\u2500\u2500 AGENTS.md
-\u2502   \u2514\u2500\u2500 CLAUDE.md -> AGENTS.md
-\u251C\u2500\u2500 models/                # Model configurations (defineModel)
-\u2502   \u251C\u2500\u2500 AGENTS.md
-\u2502   \u2514\u2500\u2500 CLAUDE.md -> AGENTS.md
-\u251C\u2500\u2500 providers/             # Provider definitions (defineProvider)
-\u2502   \u251C\u2500\u2500 AGENTS.md
-\u2502   \u2514\u2500\u2500 CLAUDE.md -> AGENTS.md
-\u251C\u2500\u2500 tools/                 # Custom tools (defineTool)
-\u2502   \u251C\u2500\u2500 AGENTS.md
-\u2502   \u2514\u2500\u2500 CLAUDE.md -> AGENTS.md
-\u251C\u2500\u2500 hooks/                 # Lifecycle hooks (defineHook)
-\u2502   \u251C\u2500\u2500 AGENTS.md
-\u2502   \u2514\u2500\u2500 CLAUDE.md -> AGENTS.md
-\u2514\u2500\u2500 api/                   # Thread API endpoints (defineThreadEndpoint)
-    \u251C\u2500\u2500 AGENTS.md
-    \u2514\u2500\u2500 CLAUDE.md -> AGENTS.md
+export default defineAgent({
+  name: 'assistant_agent',
+  title: 'Assistant',
+  description: 'Answers questions in a chat.',
+  sideA: { label: 'Assistant', prompt: 'assistant' },
+  sideB: { label: 'You', human: true },
+});
 \`\`\`
 
-The \`builder()\` Vite plugin generates the Worker entry, Durable Object bindings, Cloudflare Vite plugin configuration, and local \`.agents/\` support files at build time. Agent files are **auto-discovered** at runtime. No manual registration needed.
-
-Standalone local pnpm init approves \`esbuild\` and \`workerd\` before installing dependencies.
-The project policy lives in \`pnpm-workspace.yaml\`.
-The manifest also declares \`pnpm.onlyBuiltDependencies\` for pnpm 10.
-The YAML declares the project root for pnpm 9 compatibility.
-With pnpm 9 or pnpm 10 before 10.6, \`pnpm add --workspace-root <package>\` targets that project root.
-pnpm 11 may warn that the legacy manifest field is ignored.
-The YAML supplies its build approvals.
-An existing project policy is preserved.
-Local OpenRouter setup explicitly denies the SDK's optional model-type check.
-That checker writes no runtime artifacts.
-The CLI detects unsupported legacy layouts with pnpm's parser.
-Those layouts use \`--ignore-workspace\` during installation and foreground startup.
-Supported layouts retain their YAML build approvals.
-An enclosing pnpm workspace retains its policy and installation boundary.
-Contributor \`--workspace\` projects use their own policy boundary.
-The generated policy exempts \`@standardagents/*\` from \`minimumReleaseAge\`.
-That exemption permits installation on the release day.
-
-For remote local development, opt exact hostnames into the authoring boundary:
+Then run the project and talk to the agent:
 
-\`\`\`typescript
-builder({ trustedDevHosts: ['macbookserver.tail13bd39.ts.net'] })
+\`\`\`bash
+pnpm dev
 \`\`\`
 
-This never changes hosted behavior. Adding a hostname grants anyone who can
-reach the dev server through that name the ability to attempt authoring access;
-same-origin and normal authoring credential checks still apply. Wildcards,
-schemes, ports, and paths are rejected.
+Open \`http://localhost:5173\`, sign in with your Standard Agents account, choose **Assistant**, and send a message. A project with no account link signs in with the \`SUPER_ADMIN_PASSWORD\` set in \`.dev.vars\` instead. Use the package manager whose lockfile is in the project (\`npm run dev\`, \`yarn dev\`, or \`bun run dev\` work the same way). If port 5173 is in use, the dev server takes the next free port and prints its address.
 
-## ThreadState
+New and changed files under \`agents/\` load without a restart. Restart the dev server after you install a package or change \`.dev.vars\`.
 
-\`ThreadState\` is the state object available in tools and hooks:
+## Model access and keys
 
-\`\`\`typescript
-interface ThreadState {
-  // Identity (readonly)
-  threadId: string;           // Thread identifier
-  agentId: string;            // Agent identifier
-  userId: string | null;      // User identifier (if set)
-  createdAt: number;          // Creation timestamp
-  children: SubagentRegistryEntry[]; // Child instance registry
-  terminated: number | null;  // Soft-termination timestamp
-  arguments: Record<string, unknown>; // Invocation or subagent creation args
-  context: Record<string, unknown>;   // Current-execution scratch data
-  runtimeStreams?: RuntimeStreams;    // Optional live execution-host byte streams
-
-  // Methods
-  getMessages(options?): Promise<MessagesResult>;  // Get conversation history, newest first by default
-  getMessage(id): Promise<Message | null>;          // Find a persisted message by ID
-  updateMessage(id, updates): Promise<Message>;    // Update a persisted message
-  injectMessage(input): Promise<Message>;          // Add message to thread
-  queueMessage(input): Promise<void>;              // Queue message for next step
-  emit(event, data): void;                         // Broadcast a custom event to connected thread clients
-  loadModel(name): Promise<ModelConfig>;           // Load model definition
-  loadPrompt(name): Promise<PromptConfig>;         // Load prompt definition
-  loadAgent(name): Promise<AgentConfig>;           // Load agent definition
-  env(propertyName): Promise<string>;              // Resolve env value for this thread
-  setEnv(propertyName, value): Promise<void>;      // Set thread env + propagate to active descendants
-  getValue<T = unknown>(key: string): Promise<T | null>; // Read durable per-thread JSON value
-  setValue(key: string, value: unknown): Promise<void>;  // Write durable value; null/undefined deletes
-  status(): Promise<ThreadStatus>;                 // Run status { state: 'idle'|'running'|'failed', since, reason }
-  log(entry): Promise<void>;                       // App log row { name, message?, level?, status?, trigger?, request?, response?, error?, duration_ms?, cost?, data? }; no message, no execution
-  notifyParent(content): Promise<void>;            // Queue a silent message to the parent when one exists
-  setStatus(status): Promise<void>;                // Update this child in the parent registry; no-op without a parent
-  stopSession(options?): Promise<void>;            // Terminally stop the current agent session
-  getChildThread(referenceId): Promise<ThreadState | null>; // Resolve child thread
-  getParentThread(): Promise<ThreadState | null>;            // Resolve parent thread
-  terminate(): Promise<void>;                      // Soft-terminate thread
-  runCode(source, options?): CodeExecution;        // Run JS/TS in a fresh Dynamic Worker sandbox
-}
+This project is linked to a Standard Agents platform account. The CLI wrote that account's key to \`.dev.vars\` as \`STANDARD_AGENTS_API_KEY\`, and deployed projects receive it automatically. The key covers every provider package this project installs, so the example above runs without any provider account:
+
+| Provider | Package | Import |
+|----------|---------|--------|
+| OpenAI | \`@standardagents/openai\` | \`openai\` |
+| Anthropic | \`@standardagents/anthropic\` | \`anthropic\` |
+| Google | \`@standardagents/google\` | \`google\` |
+| OpenRouter | \`@standardagents/openrouter\` | \`openrouter\` |
+| xAI | \`@standardagents/xai\` | \`xai\` |
+| Groq | \`@standardagents/groq\` | \`groq\` |
+| Cerebras | \`@standardagents/cerebras\` | \`cerebras\` |
+| DeepInfra | \`@standardagents/deepinfra\` | \`deepinfra\` |
+| Novita AI | \`@standardagents/novita\` | \`novita\` |
+| Cloudflare Workers AI | \`@standardagents/cloudflare\` | \`cloudflare\` |
+
+Usage through the platform key is billed to the platform account. To use your own provider account, set that provider's key in \`.dev.vars\`; see \`agents/models/AGENTS.md\`. A project without \`STANDARD_AGENTS_API_KEY\` needs a provider key for each provider it uses.
+
+Never guess a model ID. Take it from the provider's published model list, or from the current model guide:
+
+\`\`\`bash
+npx @standardagents/cli@latest current-models
 \`\`\`
 
-\`state.arguments\` is read-only thread invocation data. Resumable \`subagent_create.arguments\` persists with the child thread, is visible to both child sides, and is also available as prompt variables. Use \`state.context\` only for mutable scratch data during the current execution; it is not durable storage.
-
-\`state.runtimeStreams\` is optional. Feature-detect it before opening a live
-byte stream. Capability names and metadata are runtime-defined; streams never
-park or survive an execution-host disconnect. See the tools guide for a full
-feature-detection, write, read, and cleanup example.
-
-\`state.emit(event, data)\` works from tools, hooks, and thread endpoints. In
-an endpoint it broadcasts immediately even though there is no active
-execution, which is useful for invalidating client snapshots after a durable
-\`setValue()\`. Events are not durable; clients must re-read state after
-reconnecting.
-
-\`state.status()\` returns the authoritative run status. \`reason\` is the raw
-stop code of the last run (\`stop_on_response\`, \`awaiting_human\`,
-\`hook_blocked\`, \`step_error\`, \u2026); a run that handed the turn to a human
-side is \`idle\`. Clients get the same value from \`GET /api/threads/:id\`
-(\`status\`) and from \`thread_status\` stream frames (snapshot on connect, then
-each change), so never poll for it. It is unrelated to \`setStatus()\`.
-
-\`state.log({ name, message, level, status, trigger, request, response, error, duration_ms, cost, data })\`
-records an application log row (\`kind: 'app'\`) shown with the thread's logs;
-only \`name\` is required. For an operation, record its outcome (\`status\`:
-success | error | skipped), what caused it (\`trigger: { kind, id?, summary? }\`),
-what was sent (\`request\`), what came back (\`response\` or \`error\`), and its
-\`duration_ms\` and \`cost\` (USD; counted in the thread's cost totals). It never creates a message or starts
-execution; oversized fields are truncated (name 120 chars, message and error
-4 KiB, data JSON 16 KiB, request and response JSON 64 KiB each).
-
-\`runCode\` has no implicit access to thread state, filesystem, network, timers, or host globals. Bridge only the exact capabilities needed through \`imports\` or \`globals\`; use \`modules\` for local relative ES modules; use \`execute\` to select the export and args to run. \`modules\` keys are graph-root relative paths; entry-source imports resolve from \`filename\` when supplied, including \`../\` parent paths that stay inside the supplied graph. TypeScript input is accepted by default and erased before evaluation. In thread endpoints, \`runCode\` forwards functions in imports, globals, and execution arguments as callable proxies. Call \`run.terminate(reason)\` to stop the sandbox. A caller disconnect also stops the run. When \`report\` is supplied, the host receives reports during the run and \`run.reports\` updates as reports arrive.
+\`.dev.vars\` holds secrets and is ignored by Git. Do not commit it or copy its values into source files.
 
-## Subagents
+## Check your work
 
-A subagent is any agent composed as a child of another agent. Relationships are declared in the \`subagents\` array of a prompt- or handler-backed agent side (never inside a prompt's \`tools\` array):
+- \`pnpm typecheck\` reports type errors in definition files.
+- The dev server terminal prints \`Failed to import <kind> <name>\` when a definition file cannot load.
+- The builder UI shows the same failure in a banner at the top of the page. A model, prompt, or agent that fails to load is missing from its list until the file is fixed.
+- A \`Cannot find module\` failure names a package that is not installed. Add it with the project's package manager, then restart the dev server.
+- Each thread in the builder UI has a Logs tab with every model request, tool call, and error.
 
-- Each subagent runs in its own thread (\`DurableThread\`)
-- Parent/child linkage is tracked in thread metadata; instances are visible in \`state.children\`
-- The relationship's owning side is where child traffic lands; parent\u2192child traffic enters in the child's side B perspective (\`role: 'user'\`), so the child's side A acts on it
-- For a prompt-backed owning side, the runtime injects the lifecycle tools \`subagents\`, \`subagent_create\`, and \`subagent_message\`; handler-backed sides reach children through \`ThreadState\` directly
-- \`subagent_create.arguments\` is validated from the receiving child's side A prompt schema and persists as \`ThreadState.arguments\` plus prompt variables for the life of the child thread
-- Child completion results are queued back to the parent when \`parentCommunication\` is \`implicit\`
-- Explicit relationships can stay idle until code calls \`state.notifyParent()\` or \`state.setStatus()\`; use \`state.stopSession({ result, notifyParent, status })\` when a tool should also terminally end the child session
-- Persistence is universal: a child's session ending never terminates its thread. The same reference remains addressable for later \`subagent_message\` calls; only explicit \`state.terminate()\` tears the thread down.
+## Project layout
 
-Access in tools:
-\`\`\`typescript
-export default defineTool('...', schema, async (state, args) => {
-  const threadId = state.threadId;
-  const creationArgs = state.arguments;
-  const { messages } = await state.getMessages();
-  const count = (await state.getValue<number>('invocation_count')) ?? 0;
-  await state.setValue('invocation_count', count + 1);
-  // ...
-});
+\`\`\`text
+AGENTS.md                  This guide
+CLAUDE.md -> AGENTS.md     The same file, for tools that read CLAUDE.md
+package.json               Dependencies; the project owns its versions
+vite.config.ts             Loads the builder() plugin
+tsconfig.json
+pnpm-workspace.yaml        pnpm settings for this project
+.dev.vars                  Local secrets (not committed)
+agents/
+\u251C\u2500\u2500 agents/                Agent definitions; starts with guide_agent.ts
+\u251C\u2500\u2500 prompts/               Prompt definitions; starts with guide.ts
+\u251C\u2500\u2500 models/                Model definitions; starts with low_cost.ts
+\u251C\u2500\u2500 providers/             Custom provider definitions
+\u251C\u2500\u2500 tools/                 Tools the model can call; starts with read_docs.ts
+\u251C\u2500\u2500 hooks/                 Lifecycle hooks
+\u251C\u2500\u2500 handlers/              Code-backed sides
+\u251C\u2500\u2500 api/                   Thread HTTP endpoints
+\u2514\u2500\u2500 users/                 User HTTP endpoints
 \`\`\`
 
-Access in hooks:
-\`\`\`typescript
-export default defineHook({
-  hook: 'before_create_message',
-  id: 'my_hook',
-  execute: async (state, message) => {
-    console.log(\`Thread: \${state.threadId}, Agent: \${state.agentId}\`);
-    return message;
-  }
-});
-\`\`\`
+Every directory under \`agents/\` contains an \`AGENTS.md\` and a \`CLAUDE.md\` link to it. The \`builder()\` plugin generates the Worker entry, the Cloudflare configuration, and the \`.agents/\` type files. Do not add a Wrangler config, a Worker entry file, or the Cloudflare Vite plugin.
 
-## Quick Reference
+## Naming
 
-| Function | Purpose | Directory |
-|----------|---------|-----------|
-| \`defineModel()\` | Configure LLM provider | \`agents/models/\` |
-| \`defineProvider()\` | Custom provider endpoints and overrides | \`agents/providers/\` |
-| \`definePrompt()\` | System instructions + tools | \`agents/prompts/\` |
-| \`defineHandler()\` | Deterministic side turns | \`agents/handlers/\` |
-| \`defineAgent()\` | Conversation orchestration | \`agents/agents/\` |
-| \`defineTool()\` | Custom tool functions | \`agents/tools/\` |
-| \`defineHook()\` | Lifecycle interception | \`agents/hooks/\` |
-| \`defineThreadEndpoint()\` | Custom API routes | \`agents/api/\` |
+- A model, prompt, or agent is named by its \`name\` field. Keep the file name the same.
+- A tool or handler is named by its file name: \`agents/tools/search_docs.ts\` is the tool \`search_docs\`.
+- A hook is named by its \`id\` field.
+- Use \`snake_case\` for all of these. End agent names with \`_agent\`.
+- A tool, a prompt, and an agent exposed as a tool share one namespace. Give them different names.
 
-## Runtime cost safety
+## Composing agents
 
-AgentBuilder bounds each Durable Object alarm invocation to 1,000,000 SQLite
-rows read and 10,000 rows written. A breach persistently quarantines that one
-object, clears its alarm, preserves all storage, and requires an explicit
-resume. Routine alarm rows are deleted when completed; effect history remains
-available with bounded retention. Deployments integrated with Brolly configure
-\`BROLLY_CONTROL_PUBLIC_KEY_JWK\` and \`BROLLY_ACCOUNT_ID\`; the built-in signed
-\`POST /api/auth/brolly-control\` route can then quarantine an exact object ID.
+A prompt's \`tools\` array can hold three kinds of names:
 
-Do not expose the Brolly private signing key to the AgentBuilder Worker. Do not
-disable the retention sweeper except as a temporary rollback while diagnosing
-a deployment.
+- A tool from \`agents/tools/\`.
+- Another prompt. The model calls it as a tool and gets its answer back. Use this for one focused model step, such as extraction or rewriting.
+- An agent with \`exposeAsTool: true\`. Calling it hands the same thread to that agent.
 
-## Runtime Utilities
+An agent side can also declare \`subagents\`. Each subagent runs in its own thread, and the parent starts and messages it with built-in tools. Use a subagent for work that takes several steps or needs its own review loop. See \`agents/agents/AGENTS.md\`.
 
-Import from \`@standardagents/builder\`:
+Prefer several small agents with a few tools each over one agent with many tools. Models choose tools more reliably from a short list.
+
+## ThreadState
+
+Tools, hooks, handlers, and thread endpoints receive a \`ThreadState\` for the thread they run in. The members used most:
+
+\`\`\`text
+state.threadId, state.agentId, state.userId     Identity
+state.arguments                                 Arguments the thread was created with
+state.getMessages({ limit, offset, order })     Message history: { messages, total, hasMore }
+state.injectMessage({ role, content })          Add a message to the thread
+state.queueMessage({ role, content })           Send a message that starts a turn
+state.getValue(key) / state.setValue(key, v)    Durable JSON values for this thread
+state.env(name) / state.setEnv(name, value)     Thread variables
+state.readFile / writeFile / findFiles ...      The thread's file system
+state.queueTool(name, args)                     Run another tool after this one
+state.invokeTool(name, args)                    Run another tool and wait for its result
+state.emit(event, data)                         Send a live event to connected clients
+state.user()                                    The thread's user, or null
+state.children / state.getChildThread(ref)      Subagent threads
+state.stopSession({ result })                   End the current session
+state.runCode(source, options)                  Run JavaScript or TypeScript in a sandbox
+state.execution                                 The running turn, or null when the thread is at rest
+\`\`\`
+
+\`agents/tools/AGENTS.md\` shows these in use. The full type is \`ThreadState\` in \`@standardagents/spec\`.
+
+## Development from another machine
+
+The \`dev\` script binds the dev server to \`127.0.0.1\`, so other machines cannot reach it. Keep it that way: \`.dev.vars\` holds a live account key.
+
+To work from another machine, forward a hostname you trust to the local port, for example through an SSH tunnel or a private reverse proxy. Then list that exact hostname for both Vite and the builder:
 
 \`\`\`typescript
-import {
-  queueTool,        // Queue another tool for execution
-  injectMessage,    // Add message without triggering execution
-  getMessages,      // Retrieve message history
-  emitThreadEvent,  // Send custom WebSocket events
-} from '@standardagents/builder';
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { builder } from '@standardagents/builder';
+
+const devHost = 'dev-machine.example.com';
+
+export default defineConfig({
+  plugins: [builder({ trustedDevHosts: [devHost] })],
+  server: { allowedHosts: [devHost] },
+});
 \`\`\`
 
-## Documentation
+Anyone who can reach the dev server through a listed hostname can attempt to sign in to it. \`trustedDevHosts\` rejects wildcards, schemes, ports, and paths, and has no effect on a deployed project.
+
+## Deploy
+
+On a plan that includes deployment, the platform builds and deploys this project each time you push a commit:
+
+\`\`\`bash
+git push
+\`\`\`
+
+\`npx @standardagents/cli@latest deploy\` does the same push. The local \`build\` script stops with a message on purpose: builds run on the platform, from the committed \`package.json\` and lockfile. Commit both.
 
-Full documentation: https://docs.standardagentbuilder.com
+## More documentation
 
-- [Architecture Overview](https://docs.standardagentbuilder.com/introduction/architecture)
-- [Models](https://docs.standardagentbuilder.com/core-concepts/models)
-- [Prompts](https://docs.standardagentbuilder.com/core-concepts/prompts)
-- [Agents](https://docs.standardagentbuilder.com/core-concepts/agents)
-- [Tools](https://docs.standardagentbuilder.com/core-concepts/tools)
-- [Hooks](https://docs.standardagentbuilder.com/core-concepts/hooks)
-- [ThreadState](https://docs.standardagentbuilder.com/core-concepts/flowstate)
-- [Thread API](https://docs.standardagentbuilder.com/core-concepts/api)
+- Reference for each definition type: the \`AGENTS.md\` in its directory.
+- Guides and API reference: https://docs.standardagentbuilder.com
+- For coding agents, a longer design guide: \`npx @standardagents/cli@latest skill\`
 `;
 
 // src/docs/models.ts
-var MODELS_AGENTS_MD = `# Model Definitions
+var MODELS_AGENTS_MD = `# Model definitions
 
-Models define which LLM provider and model to use for prompts.
+A model definition names an LLM and the provider that serves it. Prompts refer to a model by its \`name\`.
 
 ## Properties
 
 | Property | Type | Required | Description |
 |----------|------|----------|-------------|
-| \`name\` | \`string\` | Yes | Unique identifier for this model configuration |
-| \`provider\` | \`ProviderFactory\` | Yes | Imported provider factory such as \`openrouter\`, \`openai\`, or a local provider from \`agents/providers\` |
-| \`model\` | \`string\` | Yes | Model ID sent to provider API |
-| \`fallbacks\` | \`string[]\` | No | Fallback model names to try if primary fails |
-| \`inputPrice\` | \`number\` | No | Cost per 1M input tokens (USD) |
-| \`outputPrice\` | \`number\` | No | Cost per 1M output tokens (USD) |
-| \`cachedPrice\` | \`number\` | No | Cost per 1M cached input tokens |
-| \`includedProviders\` | \`string[]\` | No | Provider prefixes for OpenRouter routing |
-| \`providerTools\` | \`string[]\` | No | Provider-built-in tool names to make available for prompts using this model |
-
-## Example
+| \`name\` | \`string\` | Yes | The name prompts use to select this model |
+| \`provider\` | provider import | Yes | A provider imported from its package, or a provider from \`agents/providers/\` |
+| \`model\` | \`string\` | Yes | The model ID the provider expects |
+| \`fallbacks\` | \`string[]\` | No | Names of other models in this project to try when this one fails |
+| \`inputPrice\` | \`number\` | No | USD per 1M input tokens, for cost tracking |
+| \`outputPrice\` | \`number\` | No | USD per 1M output tokens |
+| \`cachedPrice\` | \`number\` | No | USD per 1M cached input tokens |
+| \`includedProviders\` | \`string[]\` | No | OpenRouter only: upstream providers to prefer |
+| \`providerTools\` | \`string[]\` | No | Provider-run tools this model offers to prompts |
+| \`providerOptions\` | \`object\` | No | Default request options for this provider |
+| \`capabilities\` | \`object\` | No | Overrides for what the model supports |
+
+## A first model
 
 \`\`\`typescript
+// agents/models/fast.ts
 import { defineModel } from '@standardagents/builder';
-import { openrouter } from '@standardagents/openrouter';
+import { openai } from '@standardagents/openai';
 
 export default defineModel({
-  name: 'default',
-  provider: openrouter,
-  model: 'google/gemini-3-flash-preview',
-  fallbacks: ['fast', 'cheap-heavy'],
+  name: 'fast',
+  provider: openai,
+  model: 'gpt-5.4-nano',
 });
 \`\`\`
 
-## Provider Tools
-
-Providers can expose built-in tools such as search, file search, code execution,
-or provider-specific tools through their \`getTools()\` implementation. Enable the
-provider tool names on the model with \`providerTools\`; prompts can then include
-those tools like normal tool names. Provider tools execute on the upstream
-provider, not in AgentBuilder, and successful calls are logged as provider tool
-entries.
-
-OpenRouter exposes \`web_search\`, \`web_fetch\`, \`datetime\`, and \`image_generation\`
-as provider-executed server tools. Configure optional OpenRouter parameters with
-\`providerOptions.serverTools\` on the model.
-
-## Recommended Models (OpenRouter)
-
-| Use Case | Model ID | Description |
-|----------|----------|-------------|
-| Fast/Cheap | \`z-ai/glm-4.5-air\` | Quick responses, low cost |
-| Mid-tier | \`google/gemini-3-flash-preview\` | Good balance of speed and quality |
-| Cheap Heavy | \`nvidia/nemotron-3-ultra-550b-a55b\` | Frontier open reasoning and orchestration, still affordable |
-| Heavy | \`google/gemini-3-pro-preview\` | Most capable, for complex tasks |
-
-**\u26A0\uFE0F Google Models**: When using Google models (\`google/gemini-*\`), you must enable \`reasoning\` in your prompt configuration or tool calls will fail. See the prompts AGENTS.md for details.
-
-## Provider API Keys
-
-Set these environment variables in \`.dev.vars\` (local) or Cloudflare secrets (production):
-
-| Provider | Environment Variable |
-|----------|---------------------|
-| Cloudflare Workers AI | \`CLOUDFLARE_API_TOKEN\` + \`CLOUDFLARE_ACCOUNT_ID\` |
-| Cerebras | \`CEREBRAS_API_KEY\` |
-| DeepInfra | \`DEEPINFRA_API_KEY\` |
-| Groq | \`GROQ_API_KEY\` |
-| Novita AI | \`NOVITA_API_KEY\` |
-| OpenAI | \`OPENAI_API_KEY\` |
-| Anthropic | \`ANTHROPIC_API_KEY\` |
-| OpenRouter | \`OPENROUTER_API_KEY\` |
-| Baseten Model APIs | \`BASETEN_API_KEY\` |
-| Google | \`GOOGLE_API_KEY\` |
-| xAI | \`XAI_API_KEY\` |
-| TypeSafe AI (decisions) | \`TYPESAFE_AI_API_KEY\` |
-
-If \`STANDARD_AGENTS_API_KEY\` is present and a provider-specific key is not set,
-first-party Standard Agents providers route through the hosted Standard Agents
-router. Setting a provider-specific key always uses that provider directly.
-Hosted instances reach the router through the \`STANDARD_AGENTS_ROUTER\` service
-binding when the platform provides it, including from thread endpoints. If the
-router cannot be reached, request logs record \`error_origin: platform-router\`
-instead of blaming the model provider.
-
-## Decision providers
-
-Automatic decision logging is an AgentBuilder feature, outside the spec contract.
-
-TypeSafe AI (\`@standardagents/typesafe\`) evaluates typed questions through
-\`state.decide({ provider: typesafe, model: 'jev-latest', context, questions })\`.
-It is a decision provider, so use a conversational provider for \`defineModel\`
-and prompt-backed sides. Configure \`TYPESAFE_AI_API_KEY\` for BYOK.
-Credentials may be scoped to a user/thread; destination URLs must come from
-trusted instance-admin or deployment configuration.
-
-Supply explicit string/object/array context and named \`choice\` questions with
-\`options\`, \`score\` questions with ordered \`levels\`, or \`boolean\` questions with
-optional true/false criteria. Write complete instructions and meaningful option
-or level descriptions. The provider maps context to native state, options/levels
-to criteria, and boolean to noul. Answers preserve distributions, legends, and
-confidence; boolean answers contain a 0\u20131 \`probability\` whose threshold you choose.
-Thread calls persist operation and cost logs even before the first message;
-use \`state.injectMessage()\` explicitly when a result belongs in history. See
-\`@standardagents/typesafe/README.md\` for the complete conversion contract.
-
-## User-Defined Providers
-
-Create \`agents/providers/<name>.ts\` when a provider is compatible with an existing
-provider package but needs its own API key, endpoint, icon, model list, pricing, or
-other provider behavior.
+This works in a platform-linked project as written. The project already installs \`@standardagents/openai\`, and the platform key in \`.dev.vars\` pays for the request.
 
-\`\`\`typescript
-// agents/providers/darkbloom.ts
-import { defineProvider, providerEnv } from '@standardagents/spec';
-import { openai } from '@standardagents/openai';
+## Providers this project has
 
-export default defineProvider({
-  name: 'darkbloom',
-  label: 'Darkbloom',
-  baseProvider: openai,
-  config: {
-    apiKey: providerEnv('DARKBLOOM_API_KEY', { valueType: 'secret' }),
-    baseUrl: providerEnv('DARKBLOOM_BASE_URL', {
-      valueType: 'url',
-      default: 'https://api.darkbloom.dev/v1',
-    }),
-  },
-});
+\`package.json\` lists every provider package below as a dependency, so each import resolves without an install step.
+
+| Provider | Package | Import | Your own key |
+|----------|---------|--------|--------------|
+| OpenAI | \`@standardagents/openai\` | \`openai\` | \`OPENAI_API_KEY\` |
+| Anthropic | \`@standardagents/anthropic\` | \`anthropic\` | \`ANTHROPIC_API_KEY\` |
+| Google | \`@standardagents/google\` | \`google\` | \`GOOGLE_API_KEY\` |
+| OpenRouter | \`@standardagents/openrouter\` | \`openrouter\` | \`OPENROUTER_API_KEY\` |
+| xAI | \`@standardagents/xai\` | \`xai\` | \`XAI_API_KEY\` |
+| Groq | \`@standardagents/groq\` | \`groq\` | \`GROQ_API_KEY\` |
+| Cerebras | \`@standardagents/cerebras\` | \`cerebras\` | \`CEREBRAS_API_KEY\` |
+| DeepInfra | \`@standardagents/deepinfra\` | \`deepinfra\` | \`DEEPINFRA_API_KEY\` |
+| Novita AI | \`@standardagents/novita\` | \`novita\` | \`NOVITA_API_KEY\` |
+| Cloudflare Workers AI | \`@standardagents/cloudflare\` | \`cloudflare\` | \`CLOUDFLARE_API_TOKEN\` and \`CLOUDFLARE_ACCOUNT_ID\` |
+
+If \`package.json\` does not list a provider package, add it with the project's package manager (for example \`pnpm add @standardagents/openai\`) and restart the dev server. A model whose provider package is missing fails with \`Cannot find module\`, and the builder UI shows that failure in a banner.
+
+## Keys
+
+The project needs no provider account. When no key is set for a provider, requests to it use \`STANDARD_AGENTS_API_KEY\`, the platform account key that the CLI wrote to \`.dev.vars\`. The platform bills that usage to the account.
+
+To use your own provider account, set the variable from the last column of the table in \`.dev.vars\`. A provider key always takes precedence over the platform key for that provider. For a deployed project, set the same variable in the project's settings on the platform.
+
+A provider you define in \`agents/providers/\` always uses its own key. The platform key does not cover it.
+
+A model whose provider has no key fails its run. The thread transcript names the variable to set and where to set it, and the Providers page in the builder UI marks the provider "Not configured". A missing key is not retried on the same model; fallback models on other providers still run. For other failures, the transcript shows the kind of failure and the thread's Logs tab holds the full error.
+
+## Choosing a model ID
+
+Model IDs change often. Take them from the provider's published model list instead of writing them from memory. Two commands help:
+
+\`\`\`bash
+npx @standardagents/cli@latest current-models
+npx @standardagents/cli@latest available-models --provider=openai
 \`\`\`
 
+The first prints a current guide to which models suit which work. The second lists every ID a provider serves, and needs that provider's own key in \`.dev.vars\`; the platform key alone is not enough for it.
+
+OpenRouter IDs include the lab, such as \`google/gemini-2.5-flash\`. Other providers use the lab's own ID, such as \`gpt-5.4-mini\`.
+
+## Fallbacks
+
+\`fallbacks\` names other models defined in this project. Each must exist in \`agents/models/\`.
+
 \`\`\`typescript
-// agents/models/darkbloom_chat.ts
+// agents/models/reliable.ts
 import { defineModel } from '@standardagents/builder';
-import darkbloom from '../providers/darkbloom';
+import { openrouter } from '@standardagents/openrouter';
 
 export default defineModel({
-  name: 'darkbloom_chat',
-  provider: darkbloom,
-  model: 'darkbloom-chat',
+  name: 'reliable',
+  provider: openrouter,
+  model: 'google/gemini-2.5-flash',
+  fallbacks: ['fast'],
 });
 \`\`\`
 
-Provider \`overrides\` can replace behavior such as \`getModels\`, \`getIcon\`,
-\`getTools\`, pricing/capability lookup, \`generate\`, or \`stream\`. Call \`next()\`
-inside an override to compose with the base provider; return your own value to
-replace it.
+A failed request is retried once on the same model, then each fallback is tried in order with the same two attempts. Network errors, rate limits (429), server errors (5xx), and authentication errors (401) trigger a retry.
 
-## Fallback Strategy
+## Provider tools
 
-When a model fails, fallbacks are tried in order:
-1. Primary model (2 attempts)
-2. First fallback (2 attempts)
-3. Second fallback (2 attempts)
-4. ...and so on
-
-Retries occur on: network errors, rate limits (429), server errors (5xx), auth errors (401).
-
-## OpenRouter Configuration
-
-For OpenRouter, use the full model path:
+Some providers run tools on their own servers, such as web search. List the ones a model should offer in \`providerTools\`. A prompt that uses the model can then put those names in its \`tools\`.
 
 \`\`\`typescript
+// agents/models/researcher.ts
 import { defineModel } from '@standardagents/builder';
 import { openrouter } from '@standardagents/openrouter';
 
 export default defineModel({
-  name: 'heavy',
+  name: 'researcher',
   provider: openrouter,
-  model: 'google/gemini-3-pro-preview',
-  includedProviders: ['google'],  // Prefer Google's servers
+  model: 'google/gemini-2.5-flash',
+  providerTools: ['web_search', 'web_fetch'],
 });
 \`\`\`
 
-## Best Practices
+OpenRouter offers \`web_search\`, \`web_fetch\`, \`datetime\`, and \`image_generation\`. Provider tools run at the provider, and their calls appear in the thread's logs.
+
+## Custom providers
 
-- **Name by use case**, not model ID (e.g., \`fast\`, \`default\`, \`heavy\`)
-- **Configure fallbacks** for production reliability
-- **Set pricing** for cost tracking in logs when your provider or runtime does not supply it automatically
-- **Cerebras note:** documented Cerebras models attach provider-owned \`usage.cost\` values for request logs, but custom/private Cerebras models should still set \`inputPrice\` and \`outputPrice\`
-- **DeepInfra note:** the provider reads live pricing from \`/v1/models\` and preserves response-level \`usage.estimated_cost\`; custom catalog endpoints can be configured with the provider's \`modelsUrl\` slot
-- **Novita note:** the Novita provider reads live catalog pricing from \`/openai/v1/models\`, including cache-read prices when available, and prices tiered catalog entries (such as MiniMax M3, which doubles from 524,288 prompt tokens) at the tier that matches each request's prompt size; custom/private Novita models should still set \`inputPrice\`, \`outputPrice\`, and \`cachedPrice\`
-- **Use environment variables** for API keys, never hardcode
+To reach an API that is compatible with an installed provider package but has its own endpoint and key, define a provider in \`agents/providers/\` and import it here. See \`agents/providers/AGENTS.md\`.
+
+## Practices
+
+- Name a model for its job (\`fast\`, \`default\`, \`researcher\`), so a prompt does not change when the model ID does.
+- Set \`inputPrice\` and \`outputPrice\` for a custom or private model. First-party providers report cost for the models they list.
+- Keep keys in \`.dev.vars\` and in platform settings. Never write a key in a source file.
 
 ## Documentation
 
@@ -523,301 +372,266 @@ Full reference: https://docs.standardagentbuilder.com/api-reference/define/model
 `;
 
 // src/docs/providers.ts
-var PROVIDERS_AGENTS_MD = `# Provider Definitions
+var PROVIDERS_AGENTS_MD = `# Provider definitions
 
-Provider definitions create named provider factories that wrap a base provider
-package with connection config and optional method overrides.
+Most projects never need this directory. The provider packages listed in \`agents/models/AGENTS.md\` already cover the major model providers.
 
-Use \`defineProvider()\` and export the result as the default export:
+Define a provider when an API is compatible with one of those packages but has its own endpoint, key, or behavior. A provider definition wraps a base provider package with different connection settings.
+
+## Example
 
 \`\`\`typescript
-import { defineProvider, providerEnv, providerValue } from '@standardagents/spec';
+// agents/providers/acme.ts
+import { defineProvider, providerEnv, providerValue } from '@standardagents/builder';
 import { openai } from '@standardagents/openai';
 
 export default defineProvider({
-  name: 'my_openai_compatible_provider',
-  label: 'My OpenAI-compatible Provider',
+  name: 'acme',
+  label: 'Acme AI',
   baseProvider: openai,
   config: {
-    apiKey: providerEnv('MY_PROVIDER_API_KEY', {
+    apiKey: providerEnv('ACME_API_KEY', {
       valueType: 'secret',
       required: true,
-      description: 'Provider API key.',
+      description: 'Acme AI API key.',
     }),
-    baseUrl: providerValue('https://api.example.com/v1'),
+    baseUrl: providerValue('https://api.acme.example/v1'),
   },
 });
 \`\`\`
 
-Models can then import the provider definition and use it like any other provider
-factory:
+A model imports the provider as a default import:
 
 \`\`\`typescript
+// agents/models/acme_chat.ts
 import { defineModel } from '@standardagents/builder';
-import myProvider from '../providers/my_openai_compatible_provider';
+import acme from '../providers/acme';
 
 export default defineModel({
-  name: 'custom_fast',
-  provider: myProvider,
-  model: 'gpt-4o-mini',
+  name: 'acme_chat',
+  provider: acme,
+  model: 'acme-chat-1',
 });
 \`\`\`
 
-Provider \`overrides\` can replace behavior such as \`getModels\`, \`getIcon\`,
-\`getTools\`, pricing/capability lookup, \`generate\`, or \`stream\`. Call \`next()\`
-inside an override to compose with the base provider; return your own value to
-replace it.
+Replace the endpoint, the model ID, and the variable name with the real ones for the API you are connecting. Set \`ACME_API_KEY\` in \`.dev.vars\` for local work and in the project's platform settings for a deployed project.
 
-Keep credentials in secret env values. Do not hardcode API keys in provider
-definition files.
+## Configuration values
 
-## Error attribution
+- \`providerEnv(name, options)\` reads a variable at run time. Use it for keys and for values that differ between environments. \`options\` accepts \`valueType\` (\`'secret'\`, \`'url'\`, or \`'text'\`), \`required\`, \`default\`, and \`description\`.
+- \`providerValue(value)\` is a constant written in the file. Never use it for a key.
 
-When an override catches and rethrows an upstream failure, preserve structured
-attribution with \`ProviderError\` instead of putting the provider name only in
-the message:
+A custom provider always uses the key it declares. The platform account key does not cover it.
 
-\`\`\`typescript
-import { ProviderError } from '@standardagents/builder';
+## Overrides
+
+\`overrides\` can replace or wrap methods of the base provider, such as \`getModels\`, \`getIcon\`, \`getTools\`, \`generate\`, and \`stream\`. Inside an override, call \`next()\` to run the base provider's version and return your own value to replace it.
 
+When an override catches an upstream failure and rethrows it, throw a \`ProviderError\` from \`@standardagents/builder\` so the thread's logs name the failing service:
+
+\`\`\`text
 throw new ProviderError(message, 'server_error', status, retryAfter, {
   cause: error,
-  origin: 'provider:my_openai_compatible_provider',
-  upstream: 'example-backend',
+  origin: 'provider:acme',
+  upstream: 'acme-backend',
 });
 \`\`\`
 
-\`origin\` is machine-readable (\`provider:<id>\` for provider failures), while
-\`upstream\` names the actual backend when it differs from the adapter. Builder
-request logs retain these fields and render them separately from the human
-message. Do not make operators infer the failing layer from prose.
+\`origin\` identifies the provider as \`provider:<name>\`. \`upstream\` names the backend when it differs from the provider.
+
+## Documentation
+
+Full reference: https://docs.standardagentbuilder.com/api-reference/define/model
 `;
 
 // src/docs/prompts.ts
-var PROMPTS_AGENTS_MD = `# Prompt Definitions
+var PROMPTS_AGENTS_MD = `# Prompt definitions
 
-Prompts define system instructions, model selection, and available tools for LLM interactions.
+A prompt holds the system instructions for a model, selects the model, and lists the tools the model may call. An agent side that is backed by a prompt runs it on every turn.
 
 ## Properties
 
 | Property | Type | Required | Description |
 |----------|------|----------|-------------|
-| \`name\` | \`string\` | Yes | Unique identifier for this prompt |
-| \`toolDescription\` | \`string\` | Yes | Description shown when used as a tool |
-| \`prompt\` | \`string \\| StructuredPrompt\` | Yes | System instructions |
-| \`model\` | \`string\` | Yes | Model name to use (references \`agents/models/\`) |
-| \`tools\` | \`(string \\| ToolConfig)[]\` | No | Available tools: tool names, sub-prompt names, provider tools, and exposed agent names for handoffs. Subagent relationships never appear here \u2014 they are declared on the agent side's \`subagents\` array |
-| \`includeChat\` | \`boolean\` | No | Include full conversation history |
-| \`includePastTools\` | \`boolean\` | No | Include previous tool results |
-| \`historyLimit\` | \`number\` | No | With \`includeChat\`, load only the newest top-level messages: at least N and under 2N, the cut moving N at a time (prompt-cache stable). Execution history and \`filter_messages\` see only that window; stored history is untouched |
-| \`parallelToolCalls\` | \`boolean\` | No | Allow multiple concurrent tool calls |
-| \`toolChoice\` | \`'auto' \\| 'none' \\| 'required'\` | No | Tool calling strategy |
-| \`requiredSchema\` | \`z.ZodObject\` | No | Input validation when called as tool |
-| \`variables\` | \`VariableDefinition[]\` | No | Variable declarations (\`name\`, \`type\`, \`required\`, \`scoped\`, \`description\`) |
-| \`env\` | \`Record<string, string>\` | No | Prompt-level default values for variables |
-| \`hooks\` | \`string[]\` | No | Hook IDs to run for this prompt (overrides agent hooks) |
-| \`reasoning\` | \`ReasoningConfig\` | No | Extended thinking configuration |
-| \`providerOptions\` | \`Record<string, unknown>\` | No | Provider-specific request options |
-
-## Basic Example
+| \`name\` | \`string\` | Yes | The name agents and other prompts use to refer to this prompt |
+| \`toolDescription\` | \`string\` | Yes | What this prompt does. Shown to a model that can call it as a tool |
+| \`prompt\` | \`string\` or parts array | Yes | The system instructions |
+| \`model\` | \`string\` | Yes | The \`name\` of a model in \`agents/models/\` |
+| \`tools\` | array | No | Names of tools, other prompts, provider tools, and agents exposed as tools |
+| \`includeChat\` | \`boolean\` | No | Send the conversation history with each request. Default \`false\` |
+| \`includePastTools\` | \`boolean\` | No | Send earlier tool calls and their results with each request. Default \`false\` |
+| \`historyLimit\` | \`number\` | No | With \`includeChat\`, send only the newest messages: at least this many and fewer than twice as many |
+| \`parallelToolCalls\` | \`boolean\` | No | Let the model call several tools in one step. Default \`false\` |
+| \`toolChoice\` | \`'auto'\`, \`'none'\`, or \`'required'\` | No | Whether the model may, must not, or must call a tool |
+| \`requiredSchema\` | Zod object | No | Arguments this prompt takes when it is called as a tool or started as a subagent |
+| \`variables\` | array | No | Variables this prompt needs: \`name\`, \`type\`, \`required\`, \`scoped\`, \`description\` |
+| \`env\` | \`Record<string, string>\` | No | Default values for variables |
+| \`hooks\` | \`string[]\` | No | Hook IDs to run for this prompt. Replaces the agent's hooks |
+| \`reasoning\` | \`object\` | No | Reasoning settings: \`level\`, \`maxTokens\`, \`exclude\` |
+| \`providerOptions\` | \`object\` | No | Request options for the model's provider |
+
+## A prompt with tools
 
 \`\`\`typescript
+// agents/prompts/customer_support.ts
 import { definePrompt } from '@standardagents/builder';
 
 export default definePrompt({
   name: 'customer_support',
-  toolDescription: 'Handle customer support inquiries',
+  toolDescription: 'Answer customer support questions',
   model: 'default',
-  prompt: \`You are a helpful customer support agent.
-Always be polite and professional.
-If you cannot help, escalate to a human.\`,
-  tools: ['search_knowledge_base', 'create_ticket'],
-  includeChat: true,
-});
-\`\`\`
-
-## Structured Prompts
+  prompt: \`You are a customer support agent for an online store.
 
-Include other prompts for reusable instruction blocks:
-
-\`\`\`typescript
-export default definePrompt({
-  name: 'main_assistant',
-  toolDescription: 'Primary assistant',
-  model: 'default',
-  prompt: [
-    { type: 'text', content: 'You are a helpful assistant.\\n\\n' },
-    { type: 'include', prompt: 'common_rules' },  // Includes another prompt
-    { type: 'env', property: 'ASSISTANT_TONE' },  // Inject variable value
-    { type: 'text', content: '\\n\\nBe concise.' },
-  ],
+Search the knowledge base before you answer a product question.
+If the knowledge base does not cover the question, create a ticket and tell the customer a person will follow up.
+When the customer confirms the issue is resolved, close the conversation with a one-sentence summary.\`,
+  tools: ['search_knowledge_base', 'create_ticket', 'close_conversation'],
+  includeChat: true,
+  includePastTools: true,
 });
 \`\`\`
 
-A circular prompt include raises an error that names the include chain. A prompt can include the same partial through different paths.
-
-\`type: 'env'\` inserts a resolved thread variable value. Use this only for non-secret values that are safe to expose to the LLM.
-
-The sandboxed coding prompt declares \`HTTP_HOST\` as a text variable and injects its resolved value with a structured \`{ type: 'env', property: 'HTTP_HOST' }\` prompt part. Its URL helper uses that value as the origin for files exposed from the thread \`public/\` directory and endpoints exposed from the thread \`api/\` directory. Public URLs should usually omit extensions; extensionless public paths resolve \`.html\`, then \`.js\`, then \`.ts\`, then matching \`index\` files in the same order. Browser pages should reference only public files, \`api/\` endpoints, or absolute external URLs, using relative asset URLs like \`./app\` and \`./api/todos\`; private \`src/\` files are not served directly. Public \`.ts\` files are transformed to browser JavaScript and are not server endpoints. Server-side endpoints live under the thread filesystem \`api/\` directory, and the \`api/\` directory name stays in the public URL: \`api/todo.ts\` is \`/api/threads/{threadId}/api/todo\`, while \`api/todo.ts\` is not \`/api/threads/{threadId}/todo\` or \`/api/threads/{threadId}/todos\`. Endpoint files default-export a function that accepts \`Request\` and returns \`Response\` or \`Promise<Response>\`. Endpoint code can import \`fetch\`, \`fs\`, and \`storage\`, and can import private helpers with relative paths such as \`../src/todo.ts\`. When the coding agent creates a site, page, or endpoint, it should call \`get_public_url\` with the created file path and use the returned URL.
+The model \`default\` is defined in the root \`AGENTS.md\`. The three tools are defined in \`agents/tools/AGENTS.md\`.
 
-The sandboxed coding prompt includes \`set_goal\` (write the whole goal: a short \`summary\`, a \`description\` that is the user's objective in their own words captured verbatim, plus ordered steps) and \`update_goal_step\` (flip one step's status as you start/finish it), and should check work incrementally, checking steps off as it goes and finishing with a summary once every step is done. \`coding_validate_typescript\` is only an early signal; for real verification, call helper exports with \`coding_run\`, get public URLs for pages or endpoints, then probe those URLs from \`coding_run\` using \`import { fetch } from "fetch"\`. Side-effecting endpoint checks should use disposable data and clean up through the endpoint, storage, or file cleanup path when practical. The prompt also includes \`fetch_url\` for reading known external public http(s) pages; use the \`coding_run\` fetch bridge for custom methods, headers, request bodies, or thread endpoint checks.
+## History settings
 
-Sandboxed code and \`api/\` endpoints can persist small JSON-serializable runtime data through \`import { storage } from "storage"\`. Use \`storage.get\`, \`storage.set\`, \`storage.delete\`, and \`storage.has\` with stable logical keys. Do not expose, mention, or depend on internal storage key prefixes.
+A prompt sees only its system instructions and the newest message unless you turn history on.
 
-The sandboxed coding prompt includes \`delete_file\` for removing files or empty directories from the thread filesystem. Use it to clean up obsolete implementation files, stale public assets, and abandoned endpoint routes after the replacement is working.
+- Set \`includeChat: true\` for any prompt that holds a conversation.
+- Set \`includePastTools: true\` when the model must read a tool's result to continue, which is the usual case for a prompt with tools. Without it, each request omits earlier tool calls and results, and the model may repeat a call until it reaches its step limit.
+- Leave \`includePastTools\` off when the tools only cause side effects or when their output is large or sensitive.
 
-## Tool Configuration
+## Reusing instructions
 
-Tools can be simple names or detailed configs:
+\`prompt\` can be an array of parts. An \`include\` part inserts another prompt's instructions. An \`env\` part inserts the value of a variable.
 
 \`\`\`typescript
-tools: [
-  'simple_tool',  // Just the tool name
-  {
-    name: 'complex_tool',
-    includeTextResponse: true,   // Include sub-prompt text in result
-    includeToolCalls: false,     // Exclude sub-prompt tool calls
-    includeErrors: true,         // Include error details
-    initUserMessageProperty: 'query',  // Use this arg as initial message
-  },
-],
-\`\`\`
-
-Provider-built-in tools use the same \`tools\` list once the selected model enables
-them with \`providerTools\`. AgentBuilder passes them to the provider and records
-provider-reported calls in request logs; it does not execute those tools locally.
-Generated prompt files may store these selections as \`provider:<toolName>\` to
-distinguish provider tools from local tools with the same name.
-
-### Subagents Come From the Side, Not the Tools Array
+// agents/prompts/house_rules.ts
+import { definePrompt } from '@standardagents/builder';
 
-Composition into a child thread is not a prompt-tools concern. A subagent relationship is part of the agent's structure: it is declared in the \`subagents\` array of the agent side this prompt backs, never inside the prompt's \`tools\` array (a \`tools\` entry attempting to configure a subagent relationship is a definition-time error). The side's declaration is the grant:
+export default definePrompt({
+  name: 'house_rules',
+  toolDescription: 'Shared rules for every customer-facing prompt',
+  model: 'default',
+  prompt: 'Never share one customer\\'s information with another. Never promise a refund; create a ticket instead.',
+});
+\`\`\`
 
 \`\`\`typescript
-// agents/agents/assistant_agent.ts
-sideA: {
-  prompt: 'coordinator',
-  subagents: [
-    { agent: 'calendar_agent', as: 'work_calendar',     scopedEnv: ['WORK_CAL_ID'] },
-    { agent: 'calendar_agent', as: 'personal_calendar', scopedEnv: ['PERSONAL_CAL_ID'] },
-    { agent: 'research_agent', blocking: true, maxInstances: 1 },
-    { agent: 'compaction_agent', hidden: true },
-    { agent: 'browser_agent', optional: 'ENABLE_BROWSER_AGENT' },
+// agents/prompts/billing_support.ts
+import { definePrompt } from '@standardagents/builder';
+
+export default definePrompt({
+  name: 'billing_support',
+  toolDescription: 'Answer billing questions',
+  model: 'default',
+  prompt: [
+    { type: 'text', content: 'You answer billing questions for an online store.\\n\\n' },
+    { type: 'include', prompt: 'house_rules' },
+    { type: 'text', content: '\\n\\nReply in this tone: ' },
+    { type: 'env', property: 'SUPPORT_TONE' },
   ],
-},
+  variables: [
+    { name: 'SUPPORT_TONE', type: 'text', required: false, scoped: false, description: 'Tone of voice for replies' },
+  ],
+  env: { SUPPORT_TONE: 'friendly and brief' },
+  tools: ['create_ticket'],
+  includeChat: true,
+  includePastTools: true,
+});
 \`\`\`
 
-For a prompt-backed side with non-hidden relationships, the runtime automatically injects three lifecycle tools scoped to that side's declarations:
-
-- \`subagents\` \u2014 pull-based visibility: returns the registry snapshot (reference, relationship name, agent name, status, initial arguments, creation time). Call it before \`subagent_create\` so existing instances are reused rather than duplicated.
-- \`subagent_create\` \u2014 creates (or continues) an instance. Its \`agent\` argument enumerates the side's enabled relationship *names* (\`as\`, defaulting to the unqualified part of \`agent\`), never internal agent identifiers. It requires a non-empty \`name\` for the spawned instance; AgentBuilder stores that as a \`name:<value>\` thread tag for human-friendly labels.
-- \`subagent_message\` \u2014 queues a message to an existing instance by reference.
-
-These three names are reserved; a relationship \`as\` that collides with them (or with any other tool name) is a definition-time error.
+An \`env\` part puts the value in front of the model. Use it only for values that are safe for the model and the user to see. A prompt that includes itself, directly or through another prompt, fails to load with an error that names the chain.
 
-\`subagent_create.arguments\` is shaped by the \`requiredSchema\` of the receiving child's side A prompt (parent traffic enters the child in the side B perspective, \`role: 'user'\`, so side A acts on it exactly as for an external caller). AgentBuilder validates and persists those arguments for the life of the child thread, exposes them as \`ThreadState.arguments\` and prompt variables to **both** child sides, and rehydrates them on every later activation. Missing required arguments fail creation with a structured \`subagent_arguments_required\` error.
+## Prompts as tools
 
-\`subagent_create\` accepts \`agent\`, \`name\`, and \`arguments\`.
-The relationship maps its initial message and attachments from \`arguments\`.
-Create-or-continue applies the same mappings to the existing child.
-Without a mapped message value, Builder uses the optional top-level \`message\` before falling back to serialized arguments.
-Empty arguments produce the JSON activation payload {}.
-The relationship contributes missing message and attachment fields to the model-facing argument schema.
-The model-facing schema and runtime accept optional top-level \`message\` and \`attachments\`.
-These fields are AgentBuilder extensions beyond Spec 0.2.0 Subagents \xA75 for existing callers such as Standard Code Mux.
-Relationships should migrate to \`initUserMessageProperty\` and mapped \`arguments\`.
-Strict providers may require these keys on the wire with null values to omit them.
-Mapped arguments take precedence over these compatibility fields.
-Relationship-only fields initialize messages without becoming persistent child arguments.
-
-Persistence is universal: every child instance is a persistent thread. Session end never terminates a child \u2014 a later \`subagent_message\` starts a new session with history intact; only explicit \`state.terminate()\` destroys an instance. \`blocking: true\` makes \`subagent_create\` await the child session's close and return its result; combined with \`maxInstances: 1\` and an existing instance it behaves as create-or-continue.
-
-Blocking creation and continuation return the session result through the tool result.
-That session has no implicit completion message.
-Create-or-continue acquires child execution before persisting its input.
-Admission failure leaves the continuation input unsent.
-A separate \`subagent_message\` activation retains implicit delivery under \`parentCommunication: 'implicit'\`.
-
-If required scoped vars are missing, the runtime returns \`error_code: "subagent_env_required"\` with a temporary \`GET/POST /api/threads/:threadId/variables/:requestId\` endpoint in \`error_data.endpoint\`.
-
-See \`agents/agents/AGENTS.md\` for the full \`SubagentRelationship\` option list (\`immediate\`, \`optional\`, \`hidden\`, \`parentCommunication\`, init mappings) and the ownership rules.
-
-## Input Validation
-
-Validate inputs when prompt is called as a tool:
+Any prompt can be listed in another prompt's \`tools\`. The calling model sees \`toolDescription\` and the arguments in \`requiredSchema\`, and gets the prompt's answer as the tool result. The called prompt runs once, with its own instructions and model.
 
 \`\`\`typescript
+// agents/prompts/order_extractor.ts
+import { definePrompt } from '@standardagents/builder';
 import { z } from 'zod';
 
 export default definePrompt({
-  name: 'data_extractor',
-  toolDescription: 'Extract structured data from text',
+  name: 'order_extractor',
+  toolDescription: 'Extract the order number and the problem from a customer message',
   model: 'default',
-  prompt: 'Extract the requested data from the input.',
+  prompt: 'Extract the order number and a one-sentence description of the problem. Reply with JSON: {"orderNumber": string | null, "problem": string}.',
   requiredSchema: z.object({
-    text: z.string().describe('Text to extract from'),
-    fields: z.array(z.string()).describe('Fields to extract'),
+    message: z.string().describe('The customer message to read'),
   }),
 });
 \`\`\`
 
-Provider options merge from model defaults to prompt overrides. Later values win.
+\`\`\`typescript
+// agents/prompts/returns_support.ts
+import { definePrompt } from '@standardagents/builder';
+
+export default definePrompt({
+  name: 'returns_support',
+  toolDescription: 'Handle return requests',
+  model: 'default',
+  prompt: 'You handle return requests. Use order_extractor on the first message, then create a ticket for the return.',
+  tools: [
+    { name: 'order_extractor', includeTextResponse: true, initUserMessageProperty: 'message' },
+    'create_ticket',
+  ],
+  includeChat: true,
+  includePastTools: true,
+});
+\`\`\`
+
+The object form configures a prompt used as a tool:
 
-## Extended Thinking (Reasoning)
+| Option | Meaning |
+|--------|---------|
+| \`includeTextResponse\` | Return the prompt's text answer in the tool result |
+| \`includeToolCalls\` | Return the tool calls the prompt made |
+| \`includeErrors\` | Return errors the prompt hit |
+| \`initUserMessageProperty\` | The argument to send as the prompt's user message |
+| \`initAttachmentsProperty\` | The argument that holds file paths to attach |
 
-A prompt can set \`reasoning.level\` from 0 to 100. An unset level uses the model's default. Level 0 disables reasoning when the model supports a disabling control. Otherwise, the provider selects the lowest reasoning setting. A model with no reasoning control receives no control. Each provider maps the level to the nearest option the model declares.
+## Other entries in \`tools\`
 
-A prompt's \`reasoning.level\` replaces a native effort value in \`providerOptions\`. Other \`providerOptions\` keys remain. Without a level, \`providerOptions\` apply as provided. Native effort values in a model's \`providerOptions\` remain valid.
+- **Provider tools.** When the prompt's model lists \`providerTools\`, put those names in \`tools\`. See \`agents/models/AGENTS.md\`.
+- **Agents.** An agent with \`exposeAsTool: true\` can be listed by name. Calling it hands the thread to that agent.
+- **Subagents are not listed here.** They are declared on the agent side, in \`subagents\`. For a prompt on such a side, the runtime adds three tools itself: \`subagents\`, \`subagent_create\`, and \`subagent_message\`. See \`agents/agents/AGENTS.md\`.
 
-Saved prompt input with \`reasoning.effort\` fails validation. A published package prompt with \`reasoning.effort\` loads with a warning. The runtime ignores that field.
+## Reasoning
 
-Enable for complex reasoning tasks:
+\`reasoning.level\` runs from 0 to 100. Each provider maps it to the nearest setting the model has. Leave it unset to use the model's default. Level 0 turns reasoning off when the model allows that.
 
 \`\`\`typescript
+// agents/prompts/escalation_review.ts
+import { definePrompt } from '@standardagents/builder';
+
 export default definePrompt({
-  name: 'code_reviewer',
-  toolDescription: 'Review code for issues',
-  model: 'heavy',
-  prompt: 'Review the code thoroughly...',
+  name: 'escalation_review',
+  toolDescription: 'Decide whether a support conversation needs a manager',
+  model: 'default',
+  prompt: 'Read the conversation and decide whether a manager must step in. Answer "escalate" or "continue" with one sentence of reasoning.',
+  includeChat: true,
   reasoning: {
-    level: 100,          // 0 to 100
-    maxTokens: 16000,    // Max thinking tokens
-    exclude: true,       // Don't include thinking in response
+    level: 66,
+    exclude: true,
   },
 });
 \`\`\`
 
-**\u26A0\uFE0F Google Models Require Reasoning**: When using Google models (\`google/gemini-*\`) via OpenRouter, you **must** include \`reasoning\` configuration or tool calls will fail. At minimum:
+\`exclude: true\` keeps the reasoning text out of the reply. \`maxTokens\` caps reasoning tokens for models that take a budget. Do not set \`reasoning.effort\`; it is rejected.
 
-\`\`\`typescript
-reasoning: {
-  level: 33,  // 0 to 100
-},
-\`\`\`
+Google models reached through OpenRouter (\`google/gemini-*\`) need a reasoning level before they call tools reliably. Set \`reasoning: { level: 33 }\` or higher on a prompt that gives one of those models tools.
 
 ## Hooks
 
-Attach lifecycle hooks to a prompt:
-
-\`\`\`typescript
-export default definePrompt({
-  name: 'customer_support',
-  toolDescription: 'Handle customer support',
-  model: 'default',
-  prompt: 'You are a support agent...',
-  hooks: ['limit_to_20', 'redact_pii'],  // Hook IDs from agents/hooks/
-});
-\`\`\`
+\`hooks\` lists hook IDs from \`agents/hooks/\` that run for this prompt. When a prompt lists hooks, the agent's hooks do not run for it. See \`agents/hooks/AGENTS.md\`.
 
-Prompt hooks take precedence over agent hooks. See \`agents/hooks/AGENTS.md\` for details.
+## Practices
 
-## Best Practices
-
-- **Write clear instructions** - Structure with headers and bullet points
-- **Describe tools thoroughly** - LLMs decide based on descriptions
-- **Validate inputs with Zod** - Catch errors early
-- **Use \`includeChat\`** for conversational context
-- **Name by purpose**, not model (e.g., \`support_agent\` not \`gpt4_prompt\`)
+- Write instructions for the realistic cases, including what to do when a tool fails or the answer is unknown.
+- Tell the model when to use each tool. The model decides from the tool's description and your instructions.
+- Name a prompt for its job (\`customer_support\`), not its model.
+- Keep one job per prompt. Give a second job to a second prompt and call it as a tool.
 
 ## Documentation
 
@@ -825,273 +639,315 @@ Full reference: https://docs.standardagentbuilder.com/api-reference/define/promp
 `;
 
 // src/docs/agents.ts
-var AGENT_DEFINITIONS_AGENTS_MD = `# Agent Definitions
-
-An agent is the top-level conversation orchestrator. An agent has **exactly two sides**, and each side is **backed** by exactly one of three things: a human, a prompt, or a handler. There is no agent "type" \u2014 everything about how an agent converses, composes, and terminates is derived from the backings of its two sides.
+var AGENT_DEFINITIONS_AGENTS_MD = `# Agent definitions
 
-| Backing | Who takes this side's turns | Declared as |
-|---------|-----------------------------|-------------|
-| **Human** | A person, via whatever interface the runtime provides | \`{ human: true }\` |
-| **Prompt** | A model, driven by a prompt from \`agents/prompts/\` | \`{ prompt: 'name', ... }\` |
-| **Handler** | Deterministic code from \`agents/handlers/\` | \`{ handler: 'name', ... }\` |
+An agent is a conversation between two sides, \`sideA\` and \`sideB\`. Each side is backed by exactly one of three things:
 
-Both sides are explicit. There is no implicit "missing side B is a human" default \u2014 if a person takes side B's turns, write \`sideB: { human: true }\`.
+| Backing | Who takes the side's turns | Written as |
+|---------|----------------------------|------------|
+| Human | A person, through the builder UI or your own client | \`{ human: true }\` |
+| Prompt | A model, running a prompt from \`agents/prompts/\` | \`{ prompt: 'name' }\` |
+| Handler | Code from \`agents/handlers/\` | \`{ handler: 'name' }\` |
 
-## Agent Properties
+Write both sides. There is no default for a missing side. Side A is the \`assistant\` role in the message history and side B is the \`user\` role.
 
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| \`name\` | \`string\` | Yes | Unique identifier for this agent |
-| \`sideA\` | \`SideConfig\` | Yes | Side A configuration (backing-discriminated) |
-| \`sideB\` | \`SideConfig\` | Yes | Side B configuration (backing-discriminated) |
-| \`maxSessionTurns\` | \`number\` | No | Session exchange safety cap \u2014 optional on every agent shape |
-| \`title\` | \`string\` | No | Human-readable label |
-| \`description\` | \`string\` | No | Agent summary |
-| \`icon\` | \`string\` | No | Display icon (see Icons below) |
-| \`exposeAsTool\` | \`boolean\` | No | Expose a callable entrypoint for handoffs and composition |
-| \`primary\` | \`boolean\` | No | Default true. Set false on internal handoff-target agents (e.g. domain-gearbox variants) to hide them from top-level UI agent lists; they stay fully addressable for handoffs and thread resumption |
-| \`toolDescription\` | \`string\` | No | Default model-facing description when this agent is composed or handed off to (required if exposeAsTool) |
-| \`env\` | \`Record<string, string>\` | No | Agent-level default variable values |
-| \`hooks\` | \`string[]\` | No | Hook IDs to run for this agent (fallback if prompt has no hooks) |
-| \`parentHooks\` | \`ParentHookRequirement[]\` | No | Required hooks automatically contributed to a direct parent composition (legal on any exposed agent) |
-| \`tags\` | \`string[]\` | No | Tags for categorization and filtering |
+## A chat assistant
 
-## Side Configuration
+A person on side B talks to a model on side A.
 
-A side's configuration is discriminated by its backing: exactly one of \`human\`, \`prompt\`, or \`handler\` must be present.
+\`\`\`typescript
+// agents/agents/support_agent.ts
+import { defineAgent } from '@standardagents/builder';
 
-**Human side** \u2014 \`{ human: true, label? }\`. No other properties are legal on a human side. In particular, \`subagents\` on a human side is a definition-time error (nothing there can invoke them), and stop/session bindings are meaningless.
+export default defineAgent({
+  name: 'support_agent',
+  title: 'Customer Support',
+  description: 'Answers customer questions from the knowledge base and opens tickets.',
+  sideA: {
+    label: 'Support',
+    prompt: 'customer_support',
+    sessionStop: { name: 'close_conversation', messageProperty: 'summary' },
+    maxSteps: 30,
+  },
+  sideB: { label: 'Customer', human: true },
+  hooks: ['log_tool_use'],
+});
+\`\`\`
 
-**Prompt side**
+The prompt \`customer_support\` is in \`agents/prompts/AGENTS.md\`, the tool \`close_conversation\` is in \`agents/tools/AGENTS.md\`, and the hook \`log_tool_use\` is in \`agents/hooks/AGENTS.md\`.
 
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| \`prompt\` | \`string\` | Yes | Prompt name to use (references \`agents/prompts/\`) |
-| \`label\` | \`string\` | No | Display name for this side |
-| \`subagents\` | \`SubagentRelationship[]\` | No | Side-owned child relationships (see Subagent Relationships below) |
-| \`stopOnResponse\` | \`boolean\` | No | Stop side turn on text response without tool calls (default: true) |
-| \`stopTool\` | \`string\` | No | Tool that stops this side's turn when called, with or without \`stopToolResponseProperty\` |
-| \`stopToolResponseProperty\` | \`string\` | No | Property to extract from the stop tool result. This option requires \`stopTool\`. |
-| \`maxSteps\` | \`number\` | No | Maximum step budget for this side |
-| \`sessionStop\` | \`SessionToolBinding\` | No | Terminal success lifecycle binding (object form only) |
-| \`sessionFail\` | \`SessionToolBinding\` | No | Terminal failure lifecycle binding (object form only) |
-| \`sessionStatus\` | \`SessionToolBinding\` | No | Non-terminal status lifecycle binding (object form only) |
-
-**Handler side**
+## Agent properties
 
 | Property | Type | Required | Description |
 |----------|------|----------|-------------|
-| \`handler\` | \`string\` | Yes | Handler name for this side (references \`agents/handlers/\`) |
-| \`label\` | \`string\` | No | Display name for this side |
-| \`subagents\` | \`SubagentRelationship[]\` | No | Side-owned child relationships |
-
-Handler sides have no \`maxSteps\`, \`stopOnResponse\`, or session bindings: a handler turn is a single invocation, and handlers end sessions through \`state.stopSession()\` rather than declarative bindings. See \`agents/handlers/AGENTS.md\`.
-
-Session lifecycle bindings use the object form only:
+| \`name\` | \`string\` | Yes | The agent's name. Use \`snake_case\` and end it with \`_agent\` |
+| \`sideA\` | side | Yes | Side A |
+| \`sideB\` | side | Yes | Side B |
+| \`title\` | \`string\` | No | Display name |
+| \`description\` | \`string\` | No | What the agent does |
+| \`icon\` | \`string\` | No | A URL, a data URI, or a path under the project's \`public/\` directory such as \`/icons/support.svg\` |
+| \`maxSessionTurns\` | \`number\` | No | The most exchanges one session may take |
+| \`exposeAsTool\` | \`boolean\` | No | Let prompts and other agents call this agent |
+| \`toolDescription\` | \`string\` | With \`exposeAsTool\` | What a calling model is told about this agent |
+| \`primary\` | \`boolean\` | No | Set \`false\` to hide the agent from agent lists. Default \`true\` |
+| \`env\` | \`Record<string, string>\` | No | Default variable values |
+| \`hooks\` | \`string[]\` | No | Hook IDs to run. A prompt's own \`hooks\` replace these for that prompt |
+| \`parentHooks\` | array | No | Hooks this agent adds to an agent that composes it |
+
+## Side properties
+
+A human side takes \`human: true\` and an optional \`label\`. Nothing else is allowed on it.
+
+A prompt side:
 
-\`\`\`typescript
+| Property | Type | Description |
+|----------|------|-------------|
+| \`prompt\` | \`string\` | Required. The \`name\` of a prompt |
+| \`label\` | \`string\` | Display name for the side |
+| \`stopOnResponse\` | \`boolean\` | End the side's turn when the model replies without calling a tool. Default \`true\` |
+| \`stopTool\` | \`string\` | A tool that ends the side's turn when called |
+| \`stopToolResponseProperty\` | \`string\` | The property of the stop tool's result to use as the side's reply |
+| \`maxSteps\` | \`number\` | The most model requests this side makes in one turn |
+| \`sessionStop\` | binding | The tool that ends the session successfully |
+| \`sessionFail\` | binding | The tool that ends the session as failed |
+| \`sessionStatus\` | binding | The tool that reports progress without ending the session |
+| \`subagents\` | array | Child agents this side can start |
+
+A handler side takes \`handler\` (required), \`label\`, and \`subagents\`.
+
+A binding names a tool and the arguments to read from its call:
+
+\`\`\`text
 sessionStop: {
-  name: 'complete_work',          // tool that controls the lifecycle action
-  messageProperty: 'summary',     // arg field that becomes lifecycle message text
-  attachmentsProperty: 'files',   // arg field containing attachment path(s)
+  name: 'close_conversation',     // the tool
+  messageProperty: 'summary',     // the argument that becomes the result text
+  attachmentsProperty: 'files',   // the argument that holds file paths
 }
 \`\`\`
 
-## Derivations
+The bound tool must also be listed in the prompt's \`tools\`, and must exist in \`agents/tools/\`.
 
-These follow from the backings and are never declared separately:
+## Turns and sessions
 
-- **Chat surface** \u2014 the primary conversational interface renders wherever a \`human\` backing is.
-- **Perspective** \u2014 \`role: 'user'\` is the side B perspective, \`role: 'assistant'\` is the side A perspective, for queueing, injection, and rendering alike.
-- **Subagent eligibility** \u2014 any agent may be composed as a subagent. Composing a child with a human side puts a person's step inside the composition (the child parks \`awaiting_human\` until that person responds).
-- **Termination discipline** \u2014 \`maxSessionTurns\` is optional on every agent shape, with uniform exchange counting across backings (a handler turn counts like a prompt turn). Two prompt-backed sides can ping-pong indefinitely \u2014 the cap is a voluntary safety valve, and prompt and handler authors own their termination discipline.
+A **turn** is one side acting until it stops. A **session** is the exchange of turns until the work is done.
 
-## Example: Assistant (human \xD7 prompt)
+A prompt side's turn ends at the first of these:
 
-The everyday user-facing assistant \u2014 a person on side B, a model on side A:
+1. It calls its \`sessionStop\` or \`sessionFail\` tool. The session ends too.
+2. It calls its \`stopTool\`.
+3. The model replies with text and no tool call, when \`stopOnResponse\` is \`true\`.
+4. It reaches \`maxSteps\`.
 
-\`\`\`typescript
-import { defineAgent } from '@standardagents/builder';
+A handler side's turn ends when its function returns. A human side's turn ends when the person sends a message.
 
-export default defineAgent({
-  name: 'support_agent',
-  sideA: {
-    label: 'Support',
-    prompt: 'customer_support',
-    stopOnResponse: true,
-    sessionStop: { name: 'close_ticket' },
-    maxSteps: 50,
-  },
-  sideB: { human: true },
-  tags: ['support', 'tier-1'],
-});
-\`\`\`
+A session also ends when it reaches \`maxSessionTurns\`. There is no default. Without it, a run stops only at a fallback ceiling of 250 model steps.
 
-## Example: Worker / Reviewer (prompt \xD7 prompt)
+## Two models working together
 
-Two models converse; each side sees itself as \`assistant\` and the other as \`user\`. \`maxSessionTurns\` is optional but strongly recommended here \u2014 nothing external stops two models:
+Both sides can be prompts. Each side sees its own messages as \`assistant\` and the other side's as \`user\`. Use this shape for work that benefits from review. Give the sides different jobs, name the tool that ends the session, and set \`maxSessionTurns\`, because nothing else stops two models.
 
 \`\`\`typescript
+// agents/agents/draft_agent.ts
+import { defineAgent } from '@standardagents/builder';
+
 export default defineAgent({
-  name: 'research_agent',
-  maxSessionTurns: 20,
+  name: 'draft_agent',
+  title: 'Draft and Review',
+  description: 'Writes a reply to a customer and revises it until a reviewer approves.',
   exposeAsTool: true,
-  toolDescription: 'Researches and validates findings autonomously',
+  toolDescription: 'Write a reviewed reply to a customer from a short brief',
+  maxSessionTurns: 8,
   sideA: {
-    label: 'Worker',
-    prompt: 'research_worker',
-    stopOnResponse: true,
-    sessionStatus: { name: 'set_research_status', messageProperty: 'status' },
-    sessionFail: { name: 'fail_research', messageProperty: 'reason' },
+    label: 'Writer',
+    prompt: 'draft_writer',
   },
   sideB: {
     label: 'Reviewer',
-    prompt: 'research_reviewer',
-    stopOnResponse: true,
-    sessionStop: { name: 'approve_research', messageProperty: 'summary' },
+    prompt: 'draft_reviewer',
+    sessionStop: { name: 'approve_draft', messageProperty: 'final_text' },
   },
 });
 \`\`\`
 
-## Example: Relay (handler \xD7 human)
-
-A deterministic, model-less surface: a person talks to a handler that forwards traffic to a composed child and relays answers back. Zero LLM calls happen on this thread:
-
 \`\`\`typescript
-export default defineAgent({
-  name: 'relay_agent',
-  sideA: {
-    handler: 'relay_pipe',
-    subagents: [{ agent: 'assistant_agent', maxInstances: 1 }],
-  },
-  sideB: { human: true },
+// agents/prompts/draft_writer.ts
+import { definePrompt } from '@standardagents/builder';
+import { z } from 'zod';
+
+export default definePrompt({
+  name: 'draft_writer',
+  toolDescription: 'Write a reply to a customer from a brief',
+  model: 'default',
+  prompt: 'Write a reply to the customer described in the brief. When the reviewer asks for changes, send a complete revised reply.',
+  requiredSchema: z.object({
+    brief: z.string().describe('Who the customer is, what they asked, and what the reply must say'),
+  }),
+  includeChat: true,
 });
 \`\`\`
 
-The \`relay_pipe\` handler lives in \`agents/handlers/relay_pipe.ts\` \u2014 the full worked example is in \`agents/handlers/AGENTS.md\`.
-
-## Subagent Relationships
-
-Composition into a child thread is declared on the side that owns it \u2014 never inside a prompt's \`tools\` array. The side's declaration is the grant:
-
 \`\`\`typescript
-sideA: {
-  prompt: 'coordinator',
-  subagents: [
-    { agent: 'calendar_agent', as: 'work_calendar',     scopedEnv: ['WORK_CAL_ID'] },
-    { agent: 'calendar_agent', as: 'personal_calendar', scopedEnv: ['PERSONAL_CAL_ID'] },
-    { agent: 'research_agent', blocking: true, maxInstances: 1 },
-  ],
-},
-\`\`\`
-
-- The owning side is where child traffic lands: completion, failure, and status messages arrive on the owning side's perspective. Parent\u2192child traffic enters in the child's side B perspective (\`role: 'user'\`), so the child's side A acts on it.
-- A relationship name (\`as\`, defaulting to the unqualified part of \`agent\`) may appear on at most one side, must not collide with another tool name, and must not collide with the reserved lifecycle tool names \`subagents\`, \`subagent_create\`, \`subagent_message\`.
-- For a prompt-backed owning side, the runtime injects those lifecycle tools automatically. Handler-backed owning sides need no tool grant \u2014 handlers reach children through \`ThreadState\` directly.
-- **Persistence is universal**: every child instance is a persistent thread. Session end never terminates a thread; only explicit \`state.terminate()\` destroys an instance. \`blocking\` is purely a waiting style.
+// agents/prompts/draft_reviewer.ts
+import { definePrompt } from '@standardagents/builder';
 
-Blocking \`subagent_create\` returns the session result through its tool result.
-That session has no implicit completion message.
-With \`maxInstances: 1\`, a repeated call continues the existing child.
-Continuation acquires execution before persisting its input.
-Admission failure leaves the continuation input unsent.
-A separate \`subagent_message\` activation retains implicit delivery under \`parentCommunication: 'implicit'\`.
+export default definePrompt({
+  name: 'draft_reviewer',
+  toolDescription: 'Review a draft reply to a customer',
+  model: 'default',
+  prompt: \`Review the draft for accuracy, tone, and length.
+If it is ready to send, call approve_draft with the final text.
+Otherwise reply with the specific changes you need.\`,
+  tools: ['approve_draft'],
+  includeChat: true,
+  includePastTools: true,
+});
+\`\`\`
 
-See \`agents/prompts/AGENTS.md\` for the lifecycle tools from the prompt's point of view, and the relationship option list (\`immediate\`, \`optional\`, \`hidden\`, \`parentCommunication\`, init mappings).
+The tool \`approve_draft\` is in \`agents/tools/AGENTS.md\`.
 
-## Agent Handoffs
+## Subagents
 
-When \`exposeAsTool: true\`, an agent referenced directly in a prompt's \`tools\` array is a **handoff**: the tool call transfers control of the *same thread* to the target agent, preserving history. Handoff requires the target agent to have a human side matching the thread's conversational surface.
+A side can start other agents as children. Each child runs in its own thread with its own history. Declare the children on the side that uses them:
 
 \`\`\`typescript
+// agents/agents/coordinator_agent.ts
+import { defineAgent } from '@standardagents/builder';
+
 export default defineAgent({
-  name: 'escalation_agent',
-  exposeAsTool: true,
-  toolDescription: 'Escalate to senior support for complex issues',
-  sideA: { prompt: 'senior_support' },
-  sideB: { human: true },
+  name: 'coordinator_agent',
+  title: 'Support Coordinator',
+  description: 'Talks to the customer and delegates reply writing to a reviewed drafting agent.',
+  sideA: {
+    label: 'Coordinator',
+    prompt: 'coordinator',
+    subagents: [
+      {
+        agent: 'draft_agent',
+        blocking: true,
+        maxInstances: 1,
+        initUserMessageProperty: 'brief',
+      },
+    ],
+  },
+  sideB: { label: 'Customer', human: true },
 });
 \`\`\`
 
-## Stop Semantics
+\`\`\`typescript
+// agents/prompts/coordinator.ts
+import { definePrompt } from '@standardagents/builder';
 
-Runtime stop evaluation order for prompt-backed sides:
+export default definePrompt({
+  name: 'coordinator',
+  toolDescription: 'Coordinate customer support and delegate reply writing',
+  model: 'default',
+  prompt: \`You coordinate customer support.
+For a reply that needs care, call subagent_create with agent "draft_agent", a short name, and a brief in arguments.
+Send the customer the text it returns.\`,
+  includeChat: true,
+  includePastTools: true,
+});
+\`\`\`
 
-1. **sessionStop / sessionFail** \u2014 end the session (success / terminal failure)
-2. **stopTool** \u2014 ends the current side's turn
-3. **stopOnResponse** \u2014 ends the turn when the LLM returns text without tool calls
-4. **Safety limits** \u2014 \`maxSteps\` (per side), \`maxSessionTurns\` (per session, hard limit: 250)
+Any agent can be a child. Give it \`exposeAsTool: true\` and a \`toolDescription\` so the parent's model is told what it does. Do not list the child in the prompt's \`tools\`. For a prompt side with subagents, the runtime adds three tools on its own:
 
-A handler-backed side's turn ends when its handler invocation returns. A human-backed side's turn ends when the human's inbound message is persisted.
+| Tool | What it does |
+|------|--------------|
+| \`subagents\` | Lists the children that exist, with their status |
+| \`subagent_create\` | Starts a child. Takes \`agent\` (the relationship name), \`name\` (a label for this child), and \`arguments\` |
+| \`subagent_message\` | Sends a message to an existing child |
 
-## Definition-Time Errors
+\`arguments\` follows the \`requiredSchema\` of the child's side A prompt. The child reads them as \`state.arguments\` and as prompt variables.
 
-These shapes are rejected when definitions load:
+Relationship options:
 
-1. Both sides human (reserved \u2014 may lift in a later version)
-2. \`subagents\` declared on a human-backed side
-3. A side with zero backings, or more than one of \`human\` / \`prompt\` / \`handler\`
-4. A handler side referencing an undefined handler; a prompt side referencing an undefined prompt
-5. A relationship name (\`as\`) appearing on both sides, colliding with another tool name, or colliding with a reserved lifecycle tool name
-6. Session bindings, \`maxSteps\`, or stop bindings on a non-prompt side
-7. A session binding that is not in object form
+| Option | Meaning |
+|--------|---------|
+| \`agent\` | Required. The child agent's \`name\` |
+| \`as\` | The relationship name the model sees. Defaults to the agent name. Use it to compose one agent twice |
+| \`description\` | Overrides the child's \`toolDescription\` for this relationship |
+| \`blocking\` | \`subagent_create\` waits for the child's session and returns its result |
+| \`maxInstances\` | The most children of this relationship. With \`blocking\` and \`1\`, a repeated call continues the same child |
+| \`immediate\` | Start the child when the thread is created |
+| \`parentCommunication\` | \`'implicit'\` (default) sends the child's result to the parent as a message. \`'explicit'\` sends nothing unless the child calls \`state.notifyParent()\` |
+| \`initUserMessageProperty\` | The argument to send as the child's first message |
+| \`initAttachmentsProperty\` | The argument that holds file paths to attach |
+| \`initAgentNameProperty\` | The argument to use as the child's display name |
+| \`scopedEnv\` | Variables the child must be given and does not inherit |
+| \`optional\` | A variable name. The relationship is enabled only when that variable is \`true\` |
+| \`hidden\` | Keep the relationship out of the model's tools. Code can still start it |
 
-## Hooks
+A child's thread is never deleted when its session ends. The parent can message the same child again later. Only \`state.terminate()\` ends a child for good.
 
-Attach lifecycle hooks at the agent level:
+## Handing a thread to another agent
+
+An agent with \`exposeAsTool: true\` can also be listed in a prompt's \`tools\`. Calling it hands the same thread, with its history, to that agent.
 
 \`\`\`typescript
+// agents/agents/billing_agent.ts
+import { defineAgent } from '@standardagents/builder';
+
 export default defineAgent({
-  name: 'support_agent',
-  hooks: ['log_all_messages', 'sanitize_results'],
-  sideA: { prompt: 'customer_support' },
-  sideB: { human: true },
+  name: 'billing_agent',
+  title: 'Billing Support',
+  description: 'Answers billing questions.',
+  exposeAsTool: true,
+  toolDescription: 'Hand the conversation to billing support for invoice, charge, and refund questions',
+  primary: false,
+  sideA: { label: 'Billing', prompt: 'billing_support' },
+  sideB: { label: 'Customer', human: true },
 });
 \`\`\`
 
-Agent hooks run as a fallback when the active prompt has no hooks defined. Prompt hooks always take precedence. See \`agents/hooks/AGENTS.md\` for details.
+\`\`\`typescript
+// agents/agents/triage_agent.ts
+import { defineAgent } from '@standardagents/builder';
 
-Any exposed agent can declare required parent integration hooks:
+export default defineAgent({
+  name: 'triage_agent',
+  title: 'Support Triage',
+  description: 'Greets the customer and routes billing questions to billing support.',
+  sideA: { label: 'Triage', prompt: 'triage' },
+  sideB: { label: 'Customer', human: true },
+});
+\`\`\`
 
 \`\`\`typescript
-parentHooks: [{
-  hook: 'sync_gmail_context',
-  reason: 'Makes synchronized Gmail context available to the coordinator.',
-  stage: 'before_parent', // default: after_parent
-}],
+// agents/prompts/triage.ts
+import { definePrompt } from '@standardagents/builder';
+
+export default definePrompt({
+  name: 'triage',
+  toolDescription: 'Greet a customer and route the conversation',
+  model: 'default',
+  prompt: 'Greet the customer and find out what they need. For a billing question, call billing_agent. Answer anything else yourself.',
+  tools: ['billing_agent'],
+  includeChat: true,
+});
 \`\`\`
 
-Installing the package is inert. Declaring a relationship targeting this agent
-(or adding it to a prompt as a handoff) activates the hook automatically on
-that direct parent, and composition UIs disclose the \`reason\` first. Disabled
-optional relationships contribute nothing; enabled hidden relationships still
-contribute hooks. Required hooks run with the parent's \`ThreadState\`, load
-from the child's package namespace, and fail composition closed if missing.
-User-scope hooks cannot be listed.
+The prompt \`billing_support\` is in \`agents/prompts/AGENTS.md\`.
 
-## Naming Convention
+## Definitions that are rejected
 
-Agent names **must** end with the \`_agent\` suffix (e.g., \`support_agent\`, \`research_agent\`).
-This convention is enforced by the builder UI and makes agents easily identifiable in logs and code.
+An agent fails to load when:
 
-## Icons
+- Both sides are human.
+- A side has no backing, or more than one of \`human\`, \`prompt\`, and \`handler\`.
+- A human side has anything other than \`human\` and \`label\`.
+- A handler side has \`maxSteps\`, a stop setting, or a session binding.
+- A side names a prompt or handler that does not exist.
+- \`exposeAsTool\` is \`true\` and \`toolDescription\` is missing.
+- A relationship name is used on both sides, or matches a tool name or one of the three subagent tool names.
 
-Give an agent a custom icon with the \`icon\` property: a full URL, a data URI,
-or a site-relative path served from your project's \`public/\` directory \u2014
-\`icon: '/icons/support.svg'\` expects the file at \`public/icons/support.svg\`.
-The file is served in dev and deployed with your project's assets. Agents
-without an icon (or whose icon fails to load) render a generated identicon,
-and the dashboard warns when a site-relative icon path has no matching file.
+A failed agent is missing from the builder UI's agent list, and the UI shows the error in a banner.
 
-## Best Practices
+## Practices
 
-- **Use descriptive names** (\`customer_support_agent\` not \`agent1\`)
-- **Always use the _agent suffix** - names like \`support_agent\`, \`research_agent\`
-- **Write sideB explicitly** - there is no implicit default; a user-facing agent ends with \`sideB: { human: true }\`
-- **Cap prompt \xD7 prompt agents** - set \`maxSessionTurns\` when both sides are prompt-backed; nothing external stops two models
-- **Match stop conditions to use case** - chat apps use stopOnResponse, workflows use stopTool
-- **Use labels** for clarity in logs and UI
-- **Organize with tags** for filtering
+- Give every agent a \`title\`, a \`description\`, and side labels. They appear in the builder UI and in logs.
+- Keep an agent to one domain with a short tool list. Compose agents for wider work.
+- In a prompt-and-prompt agent, set \`maxSessionTurns\` and bind a \`sessionStop\` tool.
+- Use a prompt as a tool for one model step. Use a subagent when the work needs several steps or a review.
 
 ## Documentation
 
@@ -1099,485 +955,387 @@ Full reference: https://docs.standardagentbuilder.com/api-reference/define/agent
 `;
 
 // src/docs/handlers.ts
-var HANDLERS_AGENTS_MD = `# Handler Definitions
+var HANDLERS_AGENTS_MD = `# Handler definitions
 
-A handler is a function that takes one side's turns in a conversation. When a side of an agent is backed by a handler, the runtime does not call a model to answer an inbound message \u2014 it calls the handler function once, with the thread state and the message, and whatever that function does is the side's turn.
+A handler is a function that takes one side's turns in a conversation. When an agent side is \`{ handler: 'name' }\`, the runtime calls that function once for each message that arrives on the side. No model is called for that side.
 
-A handler is **not** a hook (hooks decorate turns owned by something else, and their failures are non-fatal), **not** a tool (tools are capabilities a turn-owner chooses to invoke), and **not** an effect (effects run outside the conversation flow). Its only role is backing a side of an agent. Handlers may not be referenced by prompt \`tools\` arrays, hook lists, or effect schedules \u2014 such references are definition-time errors.
+Use a handler for a side that should act by rule: forwarding messages, replying from a lookup, or starting other agents.
 
-## Properties
+A handler is not a tool (a model does not call it) and not a hook (it owns the turn instead of observing it). It is referenced from one place only: the \`handler\` property of an agent side.
 
-| Property | Type | Required | Description |
-|----------|------|----------|-------------|
-| \`description\` | \`string\` | No | Human-facing summary |
-| \`execute\` | \`(state: ThreadState, message: Message) => Promise<void>\` | Yes | The turn implementation |
+## Defining a handler
 
-The handler's name comes from its filename: \`agents/handlers/relay_pipe.ts\` defines the handler \`relay_pipe\`. The \`message\` parameter is the full persisted message \u2014 id, role, content, silent flag, metadata, timestamps. Handlers are trusted definition code, like tools.
+The file name is the handler's name: \`agents/handlers/office_hours.ts\` defines \`office_hours\`.
 
-## Basic Example
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| \`description\` | \`string\` | No | What the handler does |
+| \`execute\` | \`(state, message) => Promise<void>\` | Yes | The turn |
 
 \`\`\`typescript
-// agents/handlers/relay_pipe.ts
+// agents/handlers/office_hours.ts
 import { defineHandler } from '@standardagents/builder';
 
 export default defineHandler({
-  description: 'Forwards inbound user traffic to the assistant child and relays answers back.',
+  description: 'Replies with the support hours. Uses no model.',
   execute: async (state, message) => {
-    // full ThreadState \u2014 forward, respond, spawn, stop, read/write KV
+    const text = typeof message.content === 'string' ? message.content.toLowerCase() : '';
+    const reply = text.includes('hours')
+      ? 'Support is open Monday to Friday, 9:00 to 17:00 UTC.'
+      : 'Ask me about our support hours.';
+
+    await state.injectMessage({ role: 'assistant', content: reply });
   },
 });
 \`\`\`
 
-Reference it from exactly one place: the \`handler\` property of an agent side:
-
 \`\`\`typescript
+// agents/agents/office_hours_agent.ts
+import { defineAgent } from '@standardagents/builder';
+
 export default defineAgent({
-  name: 'relay_agent',
-  sideA: { handler: 'relay_pipe', subagents: [{ agent: 'assistant_agent', maxInstances: 1 }] },
-  sideB: { human: true },
+  name: 'office_hours_agent',
+  title: 'Office Hours',
+  description: 'Answers questions about support hours without calling a model.',
+  sideA: { label: 'Hours', handler: 'office_hours' },
+  sideB: { label: 'Customer', human: true },
 });
 \`\`\`
 
-## Execution Model
-
-A handler-backed side's turn is:
-
-1. An inbound message arrives on the side's perspective.
-2. The runtime invokes the handler once with the thread's \`ThreadState\` and that message.
-3. The invocation returns (or throws). The turn is complete.
-
-There are no steps, no tool-choice loop, and no model requests for this side. \`maxSteps\`, \`stopOnResponse\`, \`stopTool\`, and session bindings are not legal on handler sides \u2014 a handler turn has no steps to cap and ends when \`execute\` returns. Handlers end sessions explicitly via \`state.stopSession()\`. When the agent sets \`maxSessionTurns\`, a handler turn counts toward the exchange cap exactly like a prompt turn.
-
-## Delivery Semantics
+\`message\` is the stored message that started the turn, with its \`id\`, \`role\`, \`content\`, and \`metadata\`. \`state\` is the full \`ThreadState\`, the same one tools receive; see \`agents/tools/AGENTS.md\`.
 
-Delivery to a handler is **exactly-once per message**:
+A handler speaks by calling \`state.injectMessage()\` with its own side's role: \`assistant\` for side A, \`user\` for side B. Nothing is sent on its behalf.
 
-- The handler is invoked exactly once for each inbound message on the side's perspective, in message persistence order.
-- The handler is never invoked concurrently for the same thread. Messages that arrive while a handler turn is in flight wait in the queue and are delivered one at a time, in order.
-- A message whose handler invocation failed is not automatically redelivered. Retry is a userland decision (re-send the message).
+## How a handler turn runs
 
-**Warning:** Because queued messages wait behind the in-flight turn, a long-running handler stalls its thread. A handler that awaits a \`blocking\` child session holds the delivery slot for that session's entire duration \u2014 and if that child can only finish after *another* inbound message on this thread, the thread deadlocks. Relay-style handlers should forward without blocking (\`queueMessage\` toward the child) and treat the child's replies as ordinary later turns.
+1. A message arrives on the handler's side.
+2. The runtime calls \`execute\` once with the thread state and that message.
+3. \`execute\` returns. The turn is over.
 
-## Error Semantics
+- Each message is delivered once, in the order the messages were stored.
+- One handler call runs at a time per thread. Messages that arrive during a call wait their turn.
+- A handler side has no \`maxSteps\`, \`stopOnResponse\`, \`stopTool\`, or session bindings. To end the session, call \`state.stopSession()\`.
+- A handler turn counts toward the agent's \`maxSessionTurns\`.
 
-A handler that throws is **fatal to the turn, and only the turn**:
+## Errors
 
-- The turn is marked failed and the error is surfaced in the runtime's request/execution log as a runtime-origin failure \u2014 a throwing handler never silently swallows a message.
-- The inbound message stays persisted. Nothing is rolled back.
-- The **session continues**: the failure does not end the session, terminate the thread, or poison the queue. The next inbound message gets a fresh handler invocation.
+When \`execute\` throws:
 
-If an error should end the session, the handler must do so explicitly with \`state.stopSession()\`.
+- The turn is marked failed and the error appears in the thread's logs.
+- The message that started the turn stays stored. It is not delivered again.
+- The session continues. The next message gets a new call.
 
-## Capabilities
-
-A handler receives the full \`ThreadState\` and may do anything tools can do:
-
-- **Forward** \u2014 \`(await state.getChildThread(ref)).queueMessage(...)\` toward a child, or \`state.notifyParent(...)\` toward a parent.
-- **Respond** \u2014 \`state.injectMessage({ role, content })\` in its own side's role (\`assistant\` for side A, \`user\` for side B).
-- **Spawn** \u2014 create child instances of the side's declared \`subagents\` relationships via lifecycle APIs.
-- **Control** \u2014 \`state.stopSession()\`, \`state.setStatus()\`, effects, environment, key-value store, filesystem.
-
-Handlers need no tool grants for children: the side's \`subagents\` declarations establish existence and lifecycle, and the handler reaches children through \`ThreadState\` directly. (The injected lifecycle *tools* exist for prompts \u2014 a handler calls the same operations as code.)
-
-## The Outbound Boundary
-
-Handlers get no auto-injected reply channel. If a handler (or the side it feeds) should speak to a user or an external surface, that is userland code \u2014 a tool or handler calling the messaging surface it chooses (the \`message_user\` pattern). **The runtime routes inbound; userland decides outbound.**
-
-## Livelock Discipline
-
-Handler sides do not run away on their own \u2014 a handler runs only when a message arrives. But a handler that *replies to every inbound message* paired with a prompt-backed side creates a message ping-pong with no natural stop. Handler authors own their termination discipline:
-
-- reply conditionally, not unconditionally;
-- or set \`maxSessionTurns\` on the agent (available on every shape) as a hard safety valve;
-- or end the session explicitly with \`state.stopSession()\` when the work is done.
-
-## Worked Example: the Relay
-
-A user-facing thread that does **zero model work**: every inbound user message is forwarded verbatim to a composed assistant child; every child answer is relayed back out through userland messaging. One handler expresses the entire surface:
-
-\`\`\`typescript
-// agents/handlers/relay_pipe.ts
-import { defineHandler } from '@standardagents/builder';
+To end the session on an error, catch it and call \`state.stopSession()\`.
 
-export default defineHandler({
-  description: 'Pipe user traffic to the assistant child; relay answers outward.',
-  execute: async (state, message) => {
-    const child = state.children.find(c => c.relationship === 'assistant_agent');
-    if (child) {
-      const thread = await state.getChildThread(child.reference);
-      await thread?.queueMessage({ role: 'user', content: message.content ?? '' });
-    }
-  },
-});
+## Subagents
 
-// agents/agents/relay_agent.ts
-import { defineAgent } from '@standardagents/builder';
+A handler side can declare \`subagents\`, with the same options as a prompt side (see \`agents/agents/AGENTS.md\`). A handler reaches its children through \`state\`: \`state.children\` lists them, and \`state.getChildThread(reference)\` returns a child's thread state, whose \`queueMessage()\` sends it a message. A handler needs no tools for this.
 
-export default defineAgent({
-  name: 'relay_agent',
-  sideA: {
-    handler: 'relay_pipe',
-    subagents: [{
-      agent: 'assistant_agent',
-      maxInstances: 1,
-      immediate: true,              // spawned at thread creation
-      parentCommunication: 'explicit',
-    }],
-  },
-  sideB: { human: true },
-});
-\`\`\`
+## Avoiding stalls and loops
 
-The child's answers arrive as inbound messages on side A (the owning side) and get their own handler turns, where the handler calls the project's outbound messaging tool. No model participates at any point.
+- Do not wait inside a handler for work that needs another message on the same thread. Messages queue behind the running call, so that wait never ends. Forward with \`queueMessage()\` and handle the answer as a later turn.
+- A handler that replies to every message, opposite a prompt side, never stops. Reply only when there is something to say, set \`maxSessionTurns\` on the agent, or call \`state.stopSession()\` when the work is done.
 
-## Best Practices
+## Practices
 
-- **Forward without blocking** \u2014 queue toward children and treat their replies as later turns; never hold the delivery slot on a child session
-- **Reply conditionally** \u2014 an unconditional reply opposite a prompt side is a ping-pong
-- **End sessions explicitly** \u2014 \`state.stopSession()\` when the work is done; there are no declarative session bindings on handler sides
-- **Keep handlers deterministic** \u2014 code that wants a model writes a prompt; code that wants a capability writes a tool; code that decorates writes a hook
+- Keep handlers short and rule-based. Work that needs judgment belongs in a prompt.
+- End sessions explicitly with \`state.stopSession()\`.
+- Put a capability that a model should be able to call in a tool, not a handler.
 
 ## Documentation
 
-Full reference: https://docs.standardagentbuilder.com/api-reference/define/handler
+Agent reference: https://docs.standardagentbuilder.com/api-reference/define/agent
 `;
 
 // src/docs/tools.ts
-var TOOLS_AGENTS_MD = `# Custom Tools
+var TOOLS_AGENTS_MD = `# Tools
 
-Tools extend agent capabilities beyond text generation. They allow LLMs to fetch data, perform calculations, execute side effects, and chain to other prompts or agents.
+A tool is a function a model can call. Each file in this directory defines one tool, and the file name is the tool's name: \`search_knowledge_base.ts\` defines \`search_knowledge_base\`. Use \`snake_case\` file names. A prompt offers a tool to its model by listing the name in \`tools\`.
 
-## Function Signature
+## Shape
 
-\`\`\`typescript
+\`\`\`text
 defineTool({
-  description: string,           // What the tool does (shown to LLM)
-  args?: z.ZodObject,            // Input validation schema (optional)
-  execute: (state, args) => ToolResult,  // Implementation
-  variables?: VariableDefinition[], // Declared variables (optional)
-  progressArgument?: string,     // Arg holding a short progress label, e.g. "writing index.html"
+  description,        // Required. What the tool does. The model reads this to decide when to call it
+  args,               // A z.object(...) describing the arguments. Omit for a tool with none
+  execute,            // Required. async (state, args) => ToolResult
+  variables,          // Variables the tool needs
+  progressArgument,   // The argument that holds a short progress label for the UI
 })
 \`\`\`
 
-## Basic Example
+\`execute\` returns a \`ToolResult\`:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| \`status\` | \`'success'\` or \`'error'\` | Required |
+| \`result\` | \`string\` | The output the model reads. Use JSON for structured data |
+| \`error\` | \`string\` | The message the model reads when \`status\` is \`'error'\` |
+| \`error_code\` | \`string\` | A stable code for the failure |
+| \`error_data\` | \`object\` | Structured details about the failure |
+| \`attachments\` | array | Files to attach, each \`{ name, mimeType, data }\` with base64 \`data\` |
+
+## A tool with arguments
 
 \`\`\`typescript
+// agents/tools/search_knowledge_base.ts
 import { defineTool } from '@standardagents/builder';
 import { z } from 'zod';
 
 export default defineTool({
-  description: 'Search the knowledge base for articles matching a query',
+  description: 'Search the store knowledge base. Returns up to \`limit\` articles with a title, a URL, and an excerpt.',
   args: z.object({
-    query: z.string().describe('Search query'),
-    limit: z.number().optional().default(10).describe('Max results'),
+    query: z.string().describe('What to search for, in plain words'),
+    limit: z.number().int().min(1).max(10).default(5).describe('How many articles to return'),
   }),
+  variables: [
+    {
+      name: 'KNOWLEDGE_BASE_URL',
+      type: 'text',
+      required: true,
+      scoped: false,
+      description: 'Base URL of the knowledge base search API',
+    },
+  ],
   execute: async (state, args) => {
-    const results = await searchKB(args.query, args.limit);
-    return {
-      status: 'success',
-      result: JSON.stringify(results),
-    };
+    const baseUrl = await state.env('KNOWLEDGE_BASE_URL');
+    if (!baseUrl) {
+      return { status: 'error', error: 'KNOWLEDGE_BASE_URL is not set.', error_code: 'not_configured' };
+    }
+
+    const url = new URL('/search', baseUrl);
+    url.searchParams.set('q', args.query);
+    url.searchParams.set('limit', String(args.limit));
+
+    const response = await fetch(url);
+    if (!response.ok) {
+      return {
+        status: 'error',
+        error: \`The knowledge base returned HTTP \${response.status}.\`,
+        error_code: 'upstream_error',
+      };
+    }
+
+    return { status: 'success', result: await response.text() };
   },
 });
 \`\`\`
 
-Tool variable definitions preserve \`scoped: true\`. A scoped variable blocks inheritance from the parent thread environment.
-
-\`defineTool()\` preserves \`annotations\` unchanged.
+Return an error result for a failure the model can react to, as above. The model reads \`error\` and can retry or tell the user. Let unexpected exceptions throw; the runtime records them in the thread's logs.
 
-## Argument Schemas
+## Arguments
 
-Tool args must be a top-level \`z.object(...)\`. Prefer explicit, bounded schemas made from strings, numbers, booleans, nulls, literals, enums, arrays, objects, optionals, nullables, and defaults. Avoid provider-visible recursive or open-ended schemas such as \`z.unknown()\`, \`z.any()\`, and \`z.object({}).catchall(...)\`; strict tool providers can reject the generated JSON Schema. If a tool needs arbitrary JSON input, accept it as a JSON string and parse it inside \`execute\`.
+\`args\` must be a \`z.object(...)\`. Build it from strings, numbers, booleans, enums, literals, arrays, and nested objects, with \`.optional()\`, \`.nullable()\`, and \`.default()\` as needed. Add \`.describe()\` to every field; the model reads the descriptions.
 
-## ToolResult Interface
+Avoid \`z.any()\`, \`z.unknown()\`, and open-ended records. Some providers reject the schemas they produce. For free-form JSON, take a string argument and parse it in \`execute\`.
 
-| Property | Type | Description |
-|----------|------|-------------|
-| \`status\` | \`'success' \\| 'error'\` | Whether the tool succeeded |
-| \`result\` | \`string\` | Tool output (required for success) |
-| \`error\` | \`string\` | Error message (for error status) |
-| \`error_code\` | \`string\` | Machine-readable error code |
-| \`error_data\` | \`Record<string, unknown>\` | Structured error payload |
-| \`attachments\` | \`ToolAttachment[]\` | Files to attach (images, etc.) |
-
-## ThreadState Access
+## Thread state
 
-The \`state\` parameter provides access to:
+\`state\` is the thread the tool runs in. This tool stores a record in the thread's key-value store and reads the thread's user:
 
 \`\`\`typescript
-execute: async (state, args) => {
-  // Thread information
-  const threadId = state.thread.id;
-  const thread = state.thread.instance;
-  const creationArgs = state.arguments; // Invocation or subagent creation args
-
-  // Configuration
-  const agentName = state.agent.name;
-  const modelName = state.model.name;
-
-  // Message history
-  const messages = state.messages;
-
-  // Thread variable resolution
-  const apiKey = await state.env('GOOGLE_API_KEY');
-  await state.setEnv('LAST_TOOL_RUN_AT', new Date().toISOString());
-
-  // Durable per-thread JSON values
-  const runCount = (await state.getValue<number>('run_count')) ?? 0;
-  await state.setValue('run_count', runCount + 1);
-
-  // The thread's user profile (identity only, never credentials) \u2014 for
-  // per-user personalization or entitlement checks. Null when user-less.
-  const user = await state.user();
-
-  // A thread sees its owner's skills and enabled shared skills.
-  // Load a skill body when it applies. Mutations require an instance admin.
-  const skills = await state.skills.list();
-  const skill = await state.skills.get('pdf-processing');
-  const script = await state.skills.readFile('pdf-processing', 'scripts/extract.py');
-
-  // Sandboxed JS/TS execution with explicit bridge capabilities
-  const run = state.runCode('export async function main(path) { return await read(path) }', {
-    execute: { fn: 'main', args: ['/notes.txt'] },
-    globals: {
-      read: async (path: string) => {
-        const data = await state.readFile(path);
-        return data ? new TextDecoder().decode(data) : null;
-      },
-    },
-  });
-  const codeResult = await run;
-
-  // Parent state (for sub-prompts)
-  const root = state.rootState;
-}
-\`\`\`
-
-Use \`state.runCode()\` instead of \`eval\` or \`new Function\` for model- or user-authored JavaScript/TypeScript. The sandbox starts with no ambient host capabilities; provide imports/globals explicitly, use \`modules\` for local relative ES modules, use \`execute\` to select an export and pass args, use \`report\` for streamed observations, and call \`run.terminate(reason)\` from your own timeout budget when needed. \`modules\` keys are graph-root relative paths; entry-source imports resolve from \`options.filename\` when supplied. Relative module imports may use \`./\` and \`../\` as long as they resolve within the supplied module graph. In thread endpoints, \`runCode\` forwards functions in imports, globals, and execution arguments as callable proxies. Call \`run.terminate(reason)\` to stop the sandbox. A caller disconnect also stops the run. When \`report\` is supplied, the host receives reports during the run and \`run.reports\` updates as reports arrive.
-
-### Optional Runtime Streams
+// agents/tools/create_ticket.ts
+import { defineTool } from '@standardagents/builder';
+import { z } from 'zod';
 
-Some runtimes expose live, authorized byte streams through
-\`state.runtimeStreams\`. Always feature-detect the optional surface. The
-following neutral example streams media to a workstation-hosted transcoder,
-half-closes the writable side, reads the encoded result, and cleans up:
+export default defineTool({
+  description: 'Open a support ticket for a person to follow up. Returns the ticket ID.',
+  args: z.object({
+    subject: z.string().describe('One line that names the problem'),
+    details: z.string().describe('Everything a support person needs to act on the ticket'),
+  }),
+  execute: async (state, args) => {
+    const user = await state.user();
+    const ticket = {
+      id: \`T-\${crypto.randomUUID().slice(0, 8)}\`,
+      subject: args.subject,
+      details: args.details,
+      openedBy: user?.email ?? null,
+    };
 
-\`\`\`typescript
-const runtimeStreams = state.runtimeStreams;
-if (!runtimeStreams) {
-  return { status: 'error', error: 'This runtime has no workstation streams.' };
-}
+    await state.setValue(\`ticket:\${ticket.id}\`, ticket);
+    state.emit('ticket_created', { id: ticket.id });
 
-const opened = await runtimeStreams.open({
-  capability: 'workstation_transcoder',
-  metadata: { inputFormat: 'wav', outputFormat: 'opus' },
-  timeoutMs: 10_000,
+    return { status: 'success', result: JSON.stringify({ ticketId: ticket.id }) };
+  },
 });
-if (!opened.ok) {
-  return { status: 'error', error: opened.error, error_code: opened.code };
-}
-
-try {
-  const writer = opened.stream.writable.getWriter();
-  try {
-    await writer.write(sourceMedia);
-    await writer.close();
-  } finally {
-    writer.releaseLock();
-  }
+\`\`\`
 
-  const reader = opened.stream.readable.getReader();
-  const encoded: Uint8Array[] = [];
-  try {
-    for (;;) {
-      const { value, done } = await reader.read();
-      if (done) break;
-      encoded.push(value);
-    }
-  } finally {
-    reader.releaseLock();
-  }
+Each ticket has its own key. \`getValue()\` followed by \`setValue()\` is two separate steps, so code that reads a shared list, changes it, and writes it back can overwrite a record that other code just added. Store each record under its own key.
 
-  const closed = await opened.stream.closed;
-  if (!closed.ok) throw new Error(closed.error ?? 'Transcoding failed.');
-  return { status: 'success', result: \`Received \${encoded.length} chunks.\` };
-} finally {
-  opened.stream.close();
-}
-\`\`\`
+What \`state\` offers:
 
-\`readable\` carries host-to-runtime bytes; \`writable\` carries
-runtime-to-host bytes. Streams are live and non-durable. \`close()\` is
-idempotent, and the \`closed\` promise settles once.
+| Use | Members |
+|-----|---------|
+| Identity | \`threadId\`, \`agentId\`, \`userId\`, \`arguments\` |
+| Messages | \`getMessages()\`, \`getMessage(id)\`, \`injectMessage()\`, \`queueMessage()\`, \`updateMessage()\` |
+| Durable values | \`getValue(key)\`, \`setValue(key, value)\`; a \`null\` value deletes the key |
+| Variables | \`env(name)\`, \`setEnv(name, value)\` |
+| Files | \`readFile\`, \`writeFile\`, \`readdirFile\`, \`statFile\`, \`moveFile\`, \`renameFile\`, \`unlinkFile\`, \`mkdirFile\`, \`findFiles\`, \`grepFiles\` |
+| Other tools | \`queueTool(name, args)\`, \`invokeTool(name, args)\` |
+| Live events | \`emit(event, data)\` |
+| User | \`user()\` returns the thread's user or \`null\` |
+| Subagents | \`children\`, \`getChildThread(reference)\`, \`getParentThread()\`, \`notifyParent()\`, \`setStatus()\` |
+| Session | \`stopSession()\`, \`execution\` |
+| Sandbox | \`runCode(source, options)\` |
+| Logs | \`log({ name, message, data })\` adds a row to the thread's logs |
 
-Sandboxed coding code must not use ambient network globals. For HTTP inside \`coding_run\`, import \`{ fetch }\` from \`"fetch"\`; the bridge supports \`fetch(url, init)\` with methods, headers, and bodies, and returns a Response-like object with \`text()\`, \`json()\`, \`arrayBuffer()\`, and \`headers.get()\`. The sandboxed coding prompt includes \`fetch_url\` for reading known external public http(s) pages as Markdown. Use the \`coding_run\` fetch bridge instead for custom methods, headers, request bodies, or checks against thread public file/API endpoint URLs returned by \`get_public_url\`.
+\`getMessages()\` returns \`{ messages, total, hasMore }\`, newest first. Pass \`{ order: 'asc' }\` for oldest first, and \`limit\` and \`offset\` to page.
 
-Sandboxed coding agents should verify runtime behavior as they work. \`coding_validate_typescript\` is useful but incomplete; call helper exports with \`coding_run\`, probe pages and endpoints with \`coding_run\` plus the fetch bridge, inspect status/body, and clean up disposable side-effecting test data when practical.
+## Tools without arguments, and session tools
 
-## Tool Without Arguments
+A tool bound as an agent side's \`sessionStop\` ends the session when the model calls it. The binding reads the result text from one of the tool's arguments, so the tool itself can be small:
 
 \`\`\`typescript
+// agents/tools/close_conversation.ts
+import { defineTool } from '@standardagents/builder';
+import { z } from 'zod';
+
 export default defineTool({
-  description: 'Get current server time',
-  execute: async (state) => {
-    return {
-      status: 'success',
-      result: new Date().toISOString(),
-    };
+  description: 'Close the conversation once the customer confirms the issue is resolved.',
+  args: z.object({
+    summary: z.string().describe('One sentence that says how the issue was resolved'),
+  }),
+  execute: async (state, args) => {
+    await state.setValue('resolution', args.summary);
+    return { status: 'success', result: 'Conversation closed.' };
   },
 });
 \`\`\`
 
-## Error Handling
-
-Return errors gracefully instead of throwing:
-
 \`\`\`typescript
+// agents/tools/approve_draft.ts
+import { defineTool } from '@standardagents/builder';
+import { z } from 'zod';
+
 export default defineTool({
-  description: 'Fetch user data',
-  args: z.object({ userId: z.string() }),
-  execute: async (state, args) => {
-    try {
-      const user = await fetchUser(args.userId);
-      return { status: 'success', result: JSON.stringify(user) };
-    } catch (error) {
-      return {
-        status: 'error',
-        error: \`Failed to fetch user: \${error.message}\`,
-      };
-    }
+  description: 'Approve the draft and finish. Call this only when the draft is ready to send.',
+  args: z.object({
+    final_text: z.string().describe('The approved reply, complete and ready to send'),
+  }),
+  execute: async () => {
+    return { status: 'success', result: 'Draft approved.' };
   },
 });
 \`\`\`
 
-## Queueing Additional Tools
-
-Queue another tool to run after the current one:
-
 \`\`\`typescript
-import { queueTool } from '@standardagents/builder';
+// agents/tools/current_time.ts
+import { defineTool } from '@standardagents/builder';
 
 export default defineTool({
-  description: 'Create order and send confirmation',
-  args: z.object({ items: z.array(z.string()) }),
-  execute: async (state, args) => {
-    const order = await createOrder(args.items);
-
-    // Queue email tool to run next
-    queueTool(state, 'send_confirmation_email', {
-      orderId: order.id,
-      email: state.thread.metadata.userEmail,
-    });
-
-    return { status: 'success', result: JSON.stringify(order) };
+  description: 'Get the current date and time in UTC as an ISO 8601 string.',
+  execute: async () => {
+    return { status: 'success', result: new Date().toISOString() };
   },
 });
 \`\`\`
 
-## Injecting Messages
+To end a session from code instead of a binding, call \`await state.stopSession({ result: '...' })\` inside \`execute\`.
+
+## Running another tool
 
-Add messages without triggering re-execution:
+\`state.queueTool(name, args)\` runs another tool after the current one finishes. \`state.invokeTool(name, args)\` runs it now and returns its result.
 
 \`\`\`typescript
-import { injectMessage } from '@standardagents/builder';
+// agents/tools/escalate_to_manager.ts
+import { defineTool } from '@standardagents/builder';
+import { z } from 'zod';
 
 export default defineTool({
-  description: 'Log audit event',
-  args: z.object({ event: z.string() }),
+  description: 'Escalate the conversation to a manager. Opens a ticket and records the escalation.',
+  args: z.object({
+    reason: z.string().describe('Why a manager is needed'),
+  }),
   execute: async (state, args) => {
-    await injectMessage(state, {
+    const ticket = await state.invokeTool('create_ticket', {
+      subject: 'Manager escalation',
+      details: args.reason,
+    });
+    if (ticket.status === 'error') {
+      return ticket;
+    }
+
+    await state.injectMessage({
       role: 'system',
-      content: \`[AUDIT] \${args.event}\`,
+      content: \`Escalated to a manager: \${args.reason}\`,
+      silent: true,
     });
-    return { status: 'success', result: 'Logged' };
+
+    return { status: 'success', result: ticket.result ?? 'Escalated.' };
   },
 });
 \`\`\`
 
-## Stopping Sessions
+\`injectMessage\` adds a message to the thread without starting a turn. \`silent: true\` keeps it out of the chat view.
 
-\`state.execution.stop()\` stops the current execution loop. To terminally end the active agent session, including blocking subagent runs that expect a session boundary, use \`state.stopSession()\`:
+## Files and attachments
 
-\`\`\`typescript
-await state.stopSession({
-  result: 'Waiting for clarification',
-  notifyParent: 'Please clarify the request',
-  status: 'waiting for clarification',
-});
-\`\`\`
+Each thread has its own file system. A tool can write a file there and attach files to its result.
 
-\`notifyParent\` queues a silent message to the parent when one exists; \`status\` is ignored without a parent registry entry. Omit \`notifyParent\` and \`status\` when stopping should not send a parent message or update child status.
+\`\`\`typescript
+// agents/tools/export_transcript.ts
+import { defineTool } from '@standardagents/builder';
 
-## Variables and Env
+export default defineTool({
+  description: 'Save the conversation so far as a text file in the thread and return its path.',
+  execute: async (state) => {
+    const { messages } = await state.getMessages({ order: 'asc', limit: 200 });
+    const transcript = messages
+      .filter((message) => typeof message.content === 'string' && message.content.length > 0)
+      .map((message) => \`\${message.role}: \${message.content}\`)
+      .join('\\n');
 
-Tools can declare variable requirements with \`variables\`, including \`required\` and \`description\` metadata:
+    const path = '/exports/transcript.txt';
+    await state.writeFile(path, transcript, 'text/plain');
 
-\`\`\`typescript
-export default defineTool({
-  description: 'Search uploaded documents',
-  args: z.object({ query: z.string() }),
-  execute: async (state, args) => {
-    const vectorStoreId = await state.env('VECTOR_STORE_ID');
-    const results = await searchVectorStore(vectorStoreId, args.query);
-    return { status: 'success', result: JSON.stringify(results) };
+    return { status: 'success', result: JSON.stringify({ path }) };
   },
-  variables: [
-    {
-      name: 'VECTOR_STORE_ID',
-      type: 'text',
-      required: true,
-      scoped: false,
-      description: 'OpenAI Vector Store ID',
-    },
-  ],
 });
 \`\`\`
 
-Use \`scoped: true\` for per-instance values that should not inherit from parent thread env (for example per-account OAuth tokens on subagents).
+## Variables
+
+Declare the variables a tool reads in \`variables\`, so the project records what the tool needs. Read a value with \`await state.env('NAME')\`.
+
+Set \`scoped: true\` for a value that belongs to one thread and must not be inherited from a parent thread, such as a per-account token given to a subagent.
+
+Values come from, in order: the thread, the agent's \`env\`, the prompt's \`env\`, the user, and the project's variables. Put secrets in \`.dev.vars\` locally and in the project's platform settings when deployed.
 
-## Returning Attachments
+## Sandboxed code
 
-Tools can return file attachments (e.g., generated images):
+Use \`state.runCode()\` to run JavaScript or TypeScript that a model or a user wrote. Never use \`eval\` or \`new Function\`. The sandbox has no network, file, or thread access. Pass in only the functions the code may call.
 
 \`\`\`typescript
+// agents/tools/calculate.ts
+import { defineTool } from '@standardagents/builder';
+import { z } from 'zod';
+
 export default defineTool({
-  description: 'Generate a chart from data',
-  args: z.object({ data: z.array(z.number()) }),
+  description: 'Evaluate a JavaScript arithmetic expression such as "(19.99 * 3) * 1.08" and return the number.',
+  args: z.object({
+    expression: z.string().describe('A JavaScript expression that evaluates to a number'),
+  }),
   execute: async (state, args) => {
-    const chartImage = await generateChart(args.data);
-    return {
-      status: 'success',
-      result: 'Chart generated successfully',
-      attachments: [{
-        name: 'chart.png',
-        mimeType: 'image/png',
-        data: chartImage.base64,
-        width: 800,
-        height: 600,
-      }],
-    };
+    const run = await state.runCode(\`export function main() { return (\${args.expression}); }\`, {
+      execute: { fn: 'main', args: [] },
+    });
+
+    if (run.status !== 'success') {
+      return { status: 'error', error: run.error?.message ?? 'The expression could not be evaluated.' };
+    }
+    return { status: 'success', result: String(run.result) };
   },
 });
 \`\`\`
 
-## Best Practices
-
-- **Write clear descriptions** - LLMs decide tool usage based on descriptions
-- **Describe all parameters** with \`.describe()\` in Zod schemas
-- **Handle errors gracefully** - return error status, don't throw
-- **Use snake_case** for file names (\`search_knowledge_base.ts\`)
-- **Keep tools focused** - one task per tool
-- **Use \`state.rootState\`** when queueing from sub-prompts
+## Practices
 
-## Supported Zod Types
-
-- Primitives: \`string\`, \`number\`, \`boolean\`, \`null\`
-- Enums: \`z.enum(['a', 'b', 'c'])\`
-- Arrays: \`z.array(z.string())\`
-- Objects: \`z.object({ ... })\`
-- Optional: \`z.string().optional()\`
-- Default: \`z.number().default(10)\`
-- Nullable: \`z.string().nullable()\`
+- Write the description for the model: what the tool does, when to call it, and what it returns.
+- Keep one job per tool.
+- Research a third-party API from its current documentation before you write a tool for it.
+- Check \`state\` before you add a dependency. Files, key-value storage, scheduling, and user data are built in.
+- Never put a secret in a tool file. Read it with \`state.env()\`.
 
 ## Documentation
 
@@ -1585,522 +1343,404 @@ Full reference: https://docs.standardagentbuilder.com/api-reference/define/tool
 `;
 
 // src/docs/hooks.ts
-var HOOKS_AGENTS_MD = `# Lifecycle Hooks
-
-Hooks intercept and modify agent execution at specific lifecycle points.
-
-## Available Hooks
-
-| Hook | Signature | Purpose |
-|------|-----------|---------|
-| \`after_thread_created\` | \`(state: ThreadState) => void\` | Initialize a newly created thread before execution |
-| \`after_subagent_created\` | \`(state: ThreadState, childState: ThreadState) => void\` | Run parent-side logic after a child thread is created |
-| \`after_system_message\` | \`(state: ThreadState, systemMessage: string) => string \\| null \\| undefined\` | Modify the rendered system message before the history snapshot |
-| \`filter_messages\` | \`(state: ThreadState, messages: Message[]) => Message[]\` | Build the request context from one stable history snapshot per model request (only the newest window when the prompt sets \`historyLimit\`) |
-| \`prefilter_llm_history\` | \`(state: ThreadState, messages: LLMMessage[]) => LLMMessage[]\` | Modify transformed provider messages before dispatch |
-| \`before_create_message\` | \`(state: ThreadState, message: Message) => Message\` | Modify message before database insert |
-| \`after_create_message\` | \`(state: ThreadState, message: Message) => void\` | Run logic after message created |
-| \`before_update_message\` | \`(state: ThreadState, id: string, updates: Record) => Record\` | Modify updates for a persisted message before its update |
-| \`after_update_message\` | \`(state: ThreadState, message: Message) => void\` | Run logic after message updated |
-| \`before_store_tool_result\` | \`(state: ThreadState, toolCall: HookToolCall, result: HookToolResult) => HookToolResult\` | Modify tool result before storage |
-| \`after_tool_call_success\` | \`(state: ThreadState, toolCall: HookToolCall, result: HookToolResult) => HookToolResult \\| null\` | Process successful tool execution |
-| \`after_tool_call_failure\` | \`(state: ThreadState, toolCall: HookToolCall, result: HookToolResult) => HookToolResult \\| null\` | Process failed tool execution |
-| \`user_client_attached\` | \`(user: UserState, client: { id, kind? }) => void\` | User-scope: a socket attached to the user event stream |
-| \`user_client_detached\` | \`(user: UserState, client: { id, kind? }) => void\` | User-scope: a socket detached |
-| \`user_value_changed\` | \`(user: UserState, key: string) => void\` | User-scope: a durable user value changed (any writer) |
-| \`tool_call_started\` | \`(state: ThreadState, toolCall: HookToolCall, progress?: string) => void\` | Observe a tool call when it starts streaming (before it runs) |
-| \`tool_call_done\` | \`(state: ThreadState, toolCall: HookToolCall, result: HookToolResult) => void\` | Observe a tool call after it finishes (success or failure) |
-
-User-scope hooks receive \`UserState\`. All thread hooks receive \`ThreadState\`
-first and \`HookExecutionContext\` last. The context source is prompt, agent, or
-child provenance; child provenance includes \`relationshipName\`, resolved
-\`agentName\`, and optional package signature.
-
-Packed thread hooks receive a \`ThreadState\` in their owning package namespace.
-Every hook can use \`state.loadPrompt('own')\` to load a package-local prompt.
-This includes \`before_create_message\`.
-
-## Creating a Hook
-
-Each hook file exports a default \`defineHook\` call with three properties:
+var HOOKS_AGENTS_MD = `# Lifecycle hooks
+
+A hook is a function the runtime calls at a fixed point in a thread's life: before a message is stored, before a model request is sent, after a tool runs. Use hooks for behavior that cuts across prompts, such as trimming history, redacting data, and logging.
+
+## Defining a hook
+
+Each file exports one hook. \`hook\` is the point it runs at, \`id\` is its name, and \`execute\` is the function. The file name can be anything; \`id\` is what agents and prompts refer to. \`id\` must be \`snake_case\` and unique in the project.
 
 \`\`\`typescript
+// agents/hooks/limit_history.ts
 import { defineHook } from '@standardagents/builder';
 
 export default defineHook({
-  hook: 'filter_messages',       // Hook type
-  id: 'limit_recent_messages',   // Unique ID (snake_case)
+  hook: 'filter_messages',
+  id: 'limit_history',
   execute: async (state, messages) => {
-    return messages.slice(-20);
-  }
+    return messages.slice(-40);
+  },
 });
 \`\`\`
 
-## Hook Scoping
+A hook does nothing until an agent or a prompt lists its \`id\`:
+
+\`\`\`text
+defineAgent({  name: 'support_agent',     hooks: ['log_tool_use'],   ... })
+definePrompt({ name: 'customer_support',  hooks: ['limit_history'],  ... })
+\`\`\`
+
+- A prompt's \`hooks\` replace the agent's \`hooks\` while that prompt runs.
+- A prompt with no \`hooks\` uses the agent's.
+- Work that happens outside a prompt, such as creating the thread, uses the agent's.
 
-Hooks are scoped to **prompts** or **agents** via their ID:
+## Hook points
 
-\`\`\`typescript
-// In a prompt definition
-definePrompt({
-  name: 'customer_support',
-  hooks: ['limit_recent_messages', 'redact_pii'],
-  // ...
-});
+Hooks that change data return the new value.
 
-// In an agent definition
-defineAgent({
-  name: 'support_agent',
-  hooks: ['log_all_messages'],
-  // ...
-});
-\`\`\`
+| Hook | Arguments after \`state\` | Returns | Runs |
+|------|-------------------------|---------|------|
+| \`after_system_message\` | \`systemMessage: string\` | \`string\`, or nothing to keep it | After the system instructions are built for a request |
+| \`filter_messages\` | \`messages: Message[]\` | \`Message[]\` | Once per model request, on the stored history |
+| \`prefilter_llm_history\` | \`messages: LLMMessage[]\` | \`LLMMessage[]\` | Just before the request is sent, on provider-format messages |
+| \`before_create_message\` | \`message: Message\` | \`Message\` | Before a message is stored |
+| \`before_update_message\` | \`id: string, updates\` | \`updates\` | Before a stored message is changed |
+| \`before_store_tool_result\` | \`toolCall, result\` | \`result\` | Before a tool result is stored |
+| \`after_tool_call_success\` | \`toolCall, result\` | \`result\`, or \`null\` to drop the call | After a tool succeeds |
+| \`after_tool_call_failure\` | \`toolCall, result\` | \`result\`, or \`null\` to drop the call | After a tool fails |
 
-- **Prompt hooks** take precedence over agent hooks
-- If a prompt defines hooks, only those run (agent hooks are skipped)
-- If no prompt hooks are defined, agent hooks run as fallback
-- Enabled direct children contribute their declared \`parentHooks\`
-- Ordering is child \`before_parent\`, prompt-or-agent base, child \`after_parent\`
-- Child requirements load from the child's package and run on the parent state
-- Disabled optional children contribute nothing; hidden enabled children still do
-- Installing alone is inert; adding the child relationship activates its disclosed hooks
-- Hooks are filtered by type at runtime
-- At-rest operations have no active prompt and use agent-level hooks
-
-## History and the Request Context
-
-Each provider request runs \`after_system_message\`, takes one stable persisted-history
-snapshot, runs \`filter_messages\` exactly once, transforms the result, and then runs
-\`prefilter_llm_history\`. These request-context hooks do not replace
-\`state.execution.messageHistory\`. Messages injected by \`after_system_message\` enter
-the current snapshot. Messages injected by either request-context hook enter the
-following snapshot. Silent messages remain eligible unless a request-context hook removes
-them.
-
-When the active prompt sets \`historyLimit\` (N), the snapshot and
-\`state.execution.messageHistory\` hold only the newest top-level rows: at least N
-and fewer than 2N, the cut moving N at a time. A hook looking for an older marker
-(a compaction summary, a task header) may not see it; stored history is untouched.
-
-## Create-Message Lifecycle
-
-\`before_create_message\` and \`after_create_message\` run for runtime insertion
-paths, including \`injectMessage()\` (active and at rest), agent-handoff user
-messages, and generated-asset path messages. A \`before_create_message\` hook
-that throws during \`injectMessage()\` rejects the injection and nothing is
-persisted. Other runtime insertions log the failure and keep the last good
-message.
-
-## File Naming
-
-Hook files can use **any name** \u2014 the hook type and ID are defined inside the file:
+Hooks that observe return nothing.
 
-\`\`\`
-agents/hooks/
-\u251C\u2500\u2500 my_filter.ts              # Could contain any hook type
-\u251C\u2500\u2500 redact_sensitive_data.ts
-\u251C\u2500\u2500 log_tool_usage.ts
-\u2514\u2500\u2500 add_metadata.ts
-\`\`\`
+| Hook | Arguments after \`state\` | Runs |
+|------|-------------------------|------|
+| \`after_thread_created\` | none | When a thread is created, before its first turn |
+| \`after_subagent_created\` | \`childState\` | In the parent, after a subagent thread is created |
+| \`after_create_message\` | \`message: Message\` | After a message is stored |
+| \`after_update_message\` | \`message: Message\` | After a stored message is changed |
+| \`tool_call_started\` | \`toolCall, progress?\` | When the model starts a tool call |
+| \`tool_call_done\` | \`toolCall, result\` | After a tool call finishes |
+
+Every hook receives a final \`context\` argument that says whether the prompt, the agent, or a composed child agent listed it.
+
+\`toolCall\` is \`{ id, type: 'function', function: { name, arguments } }\`, where \`arguments\` is a JSON string. \`result\` is \`{ status, result?, error?, attachments? }\`.
 
 ## Examples
 
-### Filter Messages (Limit Context)
+Redact data before it reaches the model:
 
 \`\`\`typescript
+// agents/hooks/redact_card_numbers.ts
 import { defineHook } from '@standardagents/builder';
 
+const CARD_NUMBER = /\\b(?:\\d[ -]?){13,16}\\b/g;
+
 export default defineHook({
-  hook: 'filter_messages',
-  id: 'limit_to_20',
+  hook: 'prefilter_llm_history',
+  id: 'redact_card_numbers',
   execute: async (state, messages) => {
-    return messages.slice(-20);
-  }
+    return messages.map((message) =>
+      typeof message.content === 'string'
+        ? { ...message, content: message.content.replace(CARD_NUMBER, '[card number removed]') }
+        : message,
+    );
+  },
 });
 \`\`\`
 
-### Prefilter LLM History (Redact Content)
+Log every tool call. This hook returns \`result\` unchanged:
 
 \`\`\`typescript
+// agents/hooks/log_tool_use.ts
 import { defineHook } from '@standardagents/builder';
 
 export default defineHook({
-  hook: 'prefilter_llm_history',
-  id: 'redact_pii',
-  execute: async (state, messages) => {
-    return messages.map(msg => ({
-      ...msg,
-      content: typeof msg.content === 'string'
-        ? msg.content.replace(/\\b\\d{4}-\\d{4}-\\d{4}-\\d{4}\\b/g, '[REDACTED]')
-        : msg.content,
-    }));
-  }
+  hook: 'after_tool_call_success',
+  id: 'log_tool_use',
+  execute: async (state, toolCall, result) => {
+    console.log(\`[\${state.threadId}] \${toolCall.function.name} succeeded\`);
+    return result;
+  },
 });
 \`\`\`
 
-### Before Create Message (Add Metadata)
+In \`after_tool_call_success\` and \`after_tool_call_failure\`, returning \`null\` removes the tool call and its result from the history. A hook that only observes must return the \`result\` it was given.
+
+Replace a failed result with a fallback the model can use:
 
 \`\`\`typescript
+// agents/hooks/knowledge_base_fallback.ts
 import { defineHook } from '@standardagents/builder';
 
 export default defineHook({
-  hook: 'before_create_message',
-  id: 'add_version_metadata',
-  execute: async (state, message) => {
-    if (message.role === 'user' && message.content) {
-      return { ...message, content: \`[v1.0] \${message.content}\` };
+  hook: 'after_tool_call_failure',
+  id: 'knowledge_base_fallback',
+  execute: async (state, toolCall, result) => {
+    if (toolCall.function.name !== 'search_knowledge_base') {
+      return result;
     }
-    return message;
-  }
+    return {
+      status: 'success',
+      result: JSON.stringify({ articles: [], note: 'The knowledge base is unavailable. Open a ticket instead.' }),
+    };
+  },
 });
 \`\`\`
 
-### Before Store Tool Result (Sanitize)
+Shorten large tool results before they are stored:
 
 \`\`\`typescript
+// agents/hooks/truncate_tool_results.ts
 import { defineHook } from '@standardagents/builder';
 
+const MAX_LENGTH = 8000;
+
 export default defineHook({
   hook: 'before_store_tool_result',
-  id: 'sanitize_results',
-  execute: async (state, toolCall, toolResult) => {
-    // toolCall: { id, type: 'function', function: { name, arguments } }
-    // toolResult: { status, result?, error?, stack?, attachments? }
-    if (toolResult.result) {
-      return { ...toolResult, result: toolResult.result.replace(/secret/gi, '[REDACTED]') };
+  id: 'truncate_tool_results',
+  execute: async (state, toolCall, result) => {
+    if (!result.result || result.result.length <= MAX_LENGTH) {
+      return result;
     }
-    return toolResult;
-  }
+    return { ...result, result: \`\${result.result.slice(0, MAX_LENGTH)}\\n[truncated]\` };
+  },
 });
 \`\`\`
 
-### After Tool Call Success (Logging)
-
-> Warning: In \`after_tool_call_success\` / \`after_tool_call_failure\`,
-> returning \`null\` does NOT mean "keep the original result" \u2014 it tells the
-> runtime to **REMOVE the tool call from history and skip storing the result**
-> (the assistant tool-call message is deleted). A side-effect-only hook MUST
-> return the \`result\` it received.
+Set up a new thread:
 
 \`\`\`typescript
+// agents/hooks/record_thread_start.ts
 import { defineHook } from '@standardagents/builder';
 
 export default defineHook({
-  hook: 'after_tool_call_success',
-  id: 'log_tool_success',
-  execute: async (state, toolCall, result) => {
-    console.log(\`Tool \${toolCall.function.name} succeeded\`);
-    return result;  // ALWAYS return the result \u2014 null would DELETE the tool call
-  }
+  hook: 'after_thread_created',
+  id: 'record_thread_start',
+  execute: async (state) => {
+    await state.setValue('started_at', new Date().toISOString());
+  },
 });
 \`\`\`
 
-### After Tool Call Failure (Recovery)
+## How a request is built
+
+For each model request the runtime:
+
+1. Builds the system instructions and runs \`after_system_message\`.
+2. Takes one snapshot of the stored history.
+3. Runs \`filter_messages\` once on that snapshot.
+4. Converts the result to the provider's format and runs \`prefilter_llm_history\`.
+
+These hooks shape what the model sees. They do not change the stored history. With \`historyLimit\` set on the prompt, the snapshot holds only the newest messages, so a hook cannot see older ones.
+
+## Errors
+
+A hook that throws is logged and skipped, and the data it was given is used unchanged. One exception lets a hook stop a turn on purpose: a \`prefilter_llm_history\` hook can throw an error with \`block: true\`. No model request is sent, and the error message is shown as the assistant's reply.
 
 \`\`\`typescript
+// agents/hooks/enforce_message_limit.ts
 import { defineHook } from '@standardagents/builder';
 
+const MAX_MESSAGES = 200;
+
 export default defineHook({
-  hook: 'after_tool_call_failure',
-  id: 'weather_fallback',
-  execute: async (state, toolCall, result) => {
-    if (toolCall.function.name === 'fetch_weather') {
-      return {
-        status: 'success',
-        result: JSON.stringify({ temp: 'unavailable', fallback: true }),
-      };
+  hook: 'prefilter_llm_history',
+  id: 'enforce_message_limit',
+  execute: async (state, messages) => {
+    const { total } = await state.getMessages({ limit: 1 });
+    if (total > MAX_MESSAGES) {
+      throw Object.assign(new Error('This conversation has reached its limit. Start a new one.'), { block: true });
     }
-    return result;  // keep the original error \u2014 null would DELETE the tool call
-  }
+    return messages;
+  },
 });
 \`\`\`
 
-## Hook Categories
-
-**Transformation hooks** (return modified data):
-- \`after_system_message\` (return replacement string, or null/undefined for no change)
-- \`filter_messages\`
-- \`prefilter_llm_history\`
-- \`before_create_message\`
-- \`before_update_message\`
-- \`before_store_tool_result\`
-- \`after_tool_call_success\` (return the \u2014 possibly modified \u2014 result; \`null\` REMOVES the tool call from history)
-- \`after_tool_call_failure\` (return the \u2014 possibly modified \u2014 result; \`null\` REMOVES the tool call from history)
-
-**Event hooks** (side effects only):
-- \`after_thread_created\`
-- \`after_subagent_created\`
-- \`after_create_message\`
-- \`after_update_message\`
-
-## Best Practices
-
-- **Keep hooks fast** - target <100ms execution
-- **Wrap in try-catch** - hooks continue on error (original data preserved)
-- **Use unique IDs** - hook IDs must be snake_case and unique across the project
-- **Scope appropriately** - assign hooks to prompts or agents that need them
-- **Document purpose** with clear comments
-- **Use for cross-cutting concerns** - logging, redaction, enrichment
+\`before_create_message\` is the other exception: when it throws during \`state.injectMessage()\`, the message is not stored.
 
-## Documentation
+## User hooks
 
-Full reference: https://docs.standardagentbuilder.com/api-reference/define/hook
+Three hooks run for a user instead of a thread. They receive a \`UserState\` (see \`agents/users/AGENTS.md\`), run for every user, and are not listed on an agent or prompt.
 
-## Blocking a step from a hook
+| Hook | Arguments | Runs |
+|------|-----------|------|
+| \`user_client_attached\` | \`user, client\` | A client connects to the user's event stream |
+| \`user_client_detached\` | \`user, client\` | A client disconnects |
+| \`user_value_changed\` | \`user, key\` | One of the user's durable values changes |
 
-Hook failures are normally non-fatal (logged and ignored). A
-\`prefilter_llm_history\` hook may deliberately BLOCK the step \u2014 the session
-stops with a visible assistant message BEFORE any LLM request \u2014 by throwing an
-error that carries \`block: true\`:
+## Practices
 
-\`\`\`typescript
-throw Object.assign(new Error('Thread limit reached'), { block: true });
-\`\`\`
+- Keep hooks fast. Request hooks run before every model request.
+- Return the value you were given when you have nothing to change.
+- Use a hook for behavior shared across prompts. Put behavior that belongs to one tool in that tool.
 
-Use this for entitlement/policy gates (e.g. per-user concurrency leases).
+## Documentation
+
+Full reference: https://docs.standardagentbuilder.com/api-reference/define/hook
 `;
 
 // src/docs/api.ts
-var API_AGENTS_MD = `# Thread-Specific API Endpoints
+var API_AGENTS_MD = `# Thread endpoints
 
-Define custom API endpoints that operate on specific threads with access to the thread's ThreadState.
+A thread endpoint is an HTTP route that runs against one thread. Each file in this directory becomes a route under \`/api/threads/:threadId/\`, and receives that thread's \`ThreadState\`. Use endpoints to give your own front end or service access to a thread's data.
 
-Unmatched thread endpoint paths return JSON with HTTP 404.
-A method without a matching endpoint route also returns HTTP 404.
+## Routing
 
-## File-Based Routing
+The file path sets the route. A suffix before \`.ts\` sets the method; a file without one answers \`GET\`.
 
-| File Pattern | HTTP Method | Route |
-|--------------|-------------|-------|
-| \`name.ts\` | GET | \`/api/threads/:threadId/name\` |
-| \`name.get.ts\` | GET | \`/api/threads/:threadId/name\` |
-| \`name.post.ts\` | POST | \`/api/threads/:threadId/name\` |
-| \`name.put.ts\` | PUT | \`/api/threads/:threadId/name\` |
-| \`name.delete.ts\` | DELETE | \`/api/threads/:threadId/name\` |
-| \`index.ts\` | GET | \`/api/threads/:threadId\` |
-| \`nested/route.ts\` | GET | \`/api/threads/:threadId/nested/route\` |
-| \`items/[id].ts\` | GET | \`/api/threads/:threadId/items/:id\` |
+| File | Method | Route |
+|------|--------|-------|
+| \`summary.ts\` | GET | \`/api/threads/:threadId/summary\` |
+| \`summary.get.ts\` | GET | \`/api/threads/:threadId/summary\` |
+| \`notes.post.ts\` | POST | \`/api/threads/:threadId/notes\` |
+| \`notes/[id].put.ts\` | PUT | \`/api/threads/:threadId/notes/:id\` |
+| \`notes/[id].delete.ts\` | DELETE | \`/api/threads/:threadId/notes/:id\` |
 | \`files/[*].ts\` | GET | \`/api/threads/:threadId/files/*\` |
 
-Files without a method suffix default to GET. Method suffixes are case-insensitive and support \`.get.ts\`, \`.post.ts\`, \`.put.ts\`, \`.patch.ts\`, and \`.delete.ts\`.
+- Suffixes are \`.get\`, \`.post\`, \`.put\`, \`.patch\`, and \`.delete\`.
+- \`[name]\` matches one path segment and arrives as \`params.name\`.
+- \`[*]\` matches the rest of the path, slashes included, and arrives as \`params['*']\`.
+- A fixed route wins over \`[name]\`, and \`[name]\` wins over \`[*]\`.
+- A path or method with no matching file returns HTTP 404 as JSON.
 
-Dynamic segments use \`[name]\` and are passed to the handler as \`params.name\`. Catch-all segments use \`[*]\` and are passed as \`params['*']\`; the catch-all value may contain \`/\` for nested paths. Static routes match before dynamic routes, and dynamic routes match before catch-all routes.
+## Defining an endpoint
 
-## Basic Example
+Import \`defineThreadEndpoint\` from \`@standardagents/spec\`.
 
 \`\`\`typescript
-// agents/api/status.get.ts -> GET /api/threads/:threadId/status
+// agents/api/summary.get.ts
 import { defineThreadEndpoint } from '@standardagents/spec';
 
-export default defineThreadEndpoint(async (req, state, params) => {
-  const { messages, total } = await state.getMessages();
+export default defineThreadEndpoint(async (req, state) => {
+  const { messages, total } = await state.getMessages({ limit: 5 });
+
   return Response.json({
     threadId: state.threadId,
+    agent: state.agentId,
     messageCount: total,
-    status: 'active',
-    params,
+    latest: messages.map((message) => ({ role: message.role, content: message.content })),
   });
 });
 \`\`\`
 
-## Handler Parameters
+The function receives:
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| \`req\` | \`Request\` | The incoming HTTP request |
-| \`state\` | \`ThreadState\` | Thread state with messages, identity, \`arguments\`, file system, \`runCode\`, etc. |
-| \`params\` | \`Record<string, string>\` | Route parameters captured from \`[name]\` and \`[*]\` path segments |
-| \`auth\` | \`ThreadEndpointAuth\` | The request's authentication context: \`caller\` (the authenticated identity, or \`null\` for anonymous requests) and \`threadAccess\` (whether the caller passes the runtime's access policy for this thread) |
+| \`req\` | \`Request\` | The HTTP request |
+| \`state\` | \`ThreadState\` | The thread. See \`agents/tools/AGENTS.md\` for its members |
+| \`params\` | \`Record<string, string>\` | Values from \`[name]\` and \`[*]\` segments |
+| \`auth\` | \`{ caller, threadAccess }\` | Who is calling, and whether they may access this thread |
 
-## Access Levels
+The thread is at rest while an endpoint runs, so \`state.execution\` is \`null\` and \`state.stopSession()\` is not available.
 
-Endpoints are \`authenticated\` by default: the runtime authenticates the
-request and enforces thread access before your handler runs, and \`auth.caller\`
-is always present. Declare \`{ access: 'public' }\` to accept anonymous
-requests \u2014 the runtime still resolves \`auth.caller\` when credentials are
-presented, so one endpoint can serve both audiences:
+## Reading a request body
 
 \`\`\`typescript
-// agents/api/shared/[*].ts -> GET /api/threads/:threadId/shared/<path>
+// agents/api/notes.post.ts
 import { defineThreadEndpoint } from '@standardagents/spec';
+import { z } from 'zod';
 
-export default defineThreadEndpoint(
-  async (req, state, params, auth) => {
-    if (!auth.threadAccess && !isShared(params['*'])) {
-      return new Response(null, { status: 404 });
-    }
-    // serve the file...
-  },
-  { access: 'public' }
-);
-\`\`\`
-
-A public endpoint is reachable by anyone who has the URL \u2014 treat it like an
-internet-facing route: validate the path, reject early, and never echo
-private state to anonymous callers.
-
-Note: \`state.execution\` is always \`null\` in endpoints since the thread is at rest. In thread endpoints, \`runCode\` forwards functions in imports, globals, and execution arguments as callable proxies. Call \`run.terminate(reason)\` to stop the sandbox. A caller disconnect also stops the run. When \`report\` is supplied, the host receives reports during the run and \`run.reports\` updates as reports arrive. \`state.emit(event, data)\` broadcasts a custom WebSocket event from endpoints as well as active executions; use it as an invalidation hint after persisting durable state, not as a replacement for reconnect recovery.
-
-## ThreadState Methods
-
-\`getMessages()\` returns messages newest first by default. Set \`order: 'asc'\` for oldest first.
-\`getMessage(id)\` finds persisted messages at any depth. It also finds pending messages from the message list. It returns \`null\` for unknown IDs.
-\`updateMessage(id, updates)\` updates a persisted message. It returns the updated \`Message\`.
-Updates to missing or pending messages fail before update hooks run.
-Message results include \`reasoning_content\`, \`reasoning_details\`, \`prompt\`, and available subagent fields: \`subagent_id\`, \`subagent_name\`, \`subagent_title\`, \`subagent_description\`, \`subagent_status\`, \`subagent_relationship\`, \`subagent_blocking\`, \`subagent_thread_name\`, and \`subagent_spawn_group_id\`.
-
-Access thread data through the state object:
-
-\`\`\`typescript
-import { defineThreadEndpoint } from '@standardagents/spec';
+const NoteInput = z.object({
+  text: z.string().min(1).max(2000),
+});
 
 export default defineThreadEndpoint(async (req, state) => {
-  // Thread identity
-  console.log('Thread ID:', state.threadId);
-  console.log('Agent ID:', state.agentId);
-  console.log('User ID:', state.userId);
-  console.log('Arguments:', state.arguments);
-
-  // Message operations
-  const { messages, total, hasMore } = await state.getMessages({
-    limit: 100,
-    offset: 0,
-    order: 'desc',
-  });
-
-  // Thread env (thread scope + active descendants)
-  const approvalGate = await state.env('TOPDOWN_APPROVAL_GATE');
-  await state.setEnv('TOPDOWN_APPROVAL_GATE', approvalGate || 'open');
-
-  // Durable per-thread JSON values
-  const exports = (await state.getValue<number>('export_count')) ?? 0;
-  await state.setValue('export_count', exports + 1);
-  state.emit('export_count_changed', { count: exports + 1 });
+  const input = NoteInput.safeParse(await req.json().catch(() => null));
+  if (!input.success) {
+    return Response.json({ error: 'Send a JSON body with a "text" string.' }, { status: 400 });
+  }
 
-  // File system operations
-  const files = await state.findFiles('**/*.json');
-  const data = await state.readFile('/data/config.json');
+  const note = { id: crypto.randomUUID(), text: input.data.text, createdAt: new Date().toISOString() };
 
-  // Resource loading
-  const agent = await state.loadAgent('my-agent');
-  const prompt = await state.loadPrompt('my-prompt');
+  await state.setValue(\`note:\${note.id}\`, note);
+  state.emit('notes_changed', { id: note.id });
 
-  return Response.json({ messages, total });
+  return Response.json(note, { status: 201 });
 });
 \`\`\`
 
-\`state.loadModel\`, \`state.loadPrompt\`, and \`state.loadAgent\` enforce package
-visibility. Global code can load unpacked definitions and packed entry agents.
-Packed code can load its own definitions and other packages' entry agents.
-A packed model cannot fall back to a host model with the same short name.
-A refused load returns the same not-found error as a missing definition.
+Each note has its own key. Requests to a thread endpoint can run at the same time, and \`getValue()\` followed by \`setValue()\` is two separate steps. An endpoint that read one shared list, changed it, and wrote it back could overwrite a note that another request had just added. Give each record its own key, as above, so no request rewrites another's data.
+
+\`state.emit()\` sends a live event to clients connected to the thread. Events are not stored. A client that reconnects must read the data again.
 
-## POST with Request Body
+## Route parameters
 
 \`\`\`typescript
-// agents/api/export.post.ts -> POST /api/threads/:threadId/export
+// agents/api/notes/[id].delete.ts
 import { defineThreadEndpoint } from '@standardagents/spec';
 
-export default defineThreadEndpoint(async (req, state) => {
-  const body = await req.json();
-  const { format = 'json' } = body;
-
-  const { messages } = await state.getMessages({ order: 'asc' });
-
-  if (format === 'csv') {
-    const csv = messages.map(m => \`\${m.role},\${m.content}\`).join('\\n');
-    return new Response(csv, {
-      headers: { 'Content-Type': 'text/csv' },
-    });
+export default defineThreadEndpoint(async (req, state, params) => {
+  const key = \`note:\${params.id}\`;
+  if ((await state.getValue(key)) === null) {
+    return Response.json({ error: 'No note has that ID.' }, { status: 404 });
   }
 
-  return Response.json(messages);
+  await state.setValue(key, null);
+  state.emit('notes_changed', { id: params.id });
+
+  return new Response(null, { status: 204 });
 });
 \`\`\`
 
-## Nested Routes
+Setting a value to \`null\` deletes its key.
 
-Create directories for nested routes:
+## Access
 
-\`\`\`
-agents/api/
-\u251C\u2500\u2500 status.get.ts           -> GET /api/threads/:threadId/status
-\u251C\u2500\u2500 export.post.ts          -> POST /api/threads/:threadId/export
-\u2514\u2500\u2500 messages/
-    \u251C\u2500\u2500 count.ts            -> GET /api/threads/:threadId/messages/count
-    \u251C\u2500\u2500 [id].ts             -> GET /api/threads/:threadId/messages/:id
-    \u2514\u2500\u2500 [*].ts              -> GET /api/threads/:threadId/messages/*
-\`\`\`
+An endpoint requires an authenticated caller who may access the thread. The runtime checks both before your function runs, and \`auth.caller\` is always set.
 
-## Error Handling
-
-AgentBuilder returns JSON for every failed request under \`/api/\`.
-The response preserves the HTTP status.
-The body uses \`{ "error": { "code": "internal_error", "message": "..." }, "requestId": "..." }\`.
-The \`X-Request-ID\` header matches \`requestId\`.
-Failed responses use \`Cache-Control: no-store\`.
-
-An uncaught exception returns HTTP 500 with code \`internal_error\`.
-The server log contains the exception and request ID.
-The response message omits exception details.
-Authentication infrastructure failures return HTTP 503 with code \`auth_unavailable\`.
-Platform network failures, unexpected HTTP statuses, and invalid payloads return HTTP 502 with code \`platform_unreachable\`.
-Check \`PLATFORM_ENDPOINT\` and platform availability after that error.
-An explicit platform credential or membership denial uses code \`platform_auth_rejected\` during local bootstrap.
-Unknown API paths return HTTP 404 with code \`not_found\`.
-
-Read \`error.message\` to display a failure.
-Include \`requestId\` in a support report.
-Returned legacy JSON errors retain their extra fields and response headers.
-The router converts their \`error\` field to the structured envelope.
-A legacy string error with a separate message retains its code in the envelope.
-Its separate message becomes the envelope message.
-WebSocket upgrades and successful responses retain their existing behavior.
-This error contract is an AgentBuilder extension.
-
-Handlers can return domain errors with an appropriate HTTP status:
+Pass \`{ access: 'public' }\` to accept requests with no credentials. \`auth.caller\` is then \`null\` for an anonymous request, and \`auth.threadAccess\` says whether a signed-in caller may access the thread.
 
 \`\`\`typescript
-return Response.json({ error: 'Invalid JSON body' }, { status: 400 });
+// agents/api/files/[*].ts
+import { defineThreadEndpoint } from '@standardagents/spec';
+
+export default defineThreadEndpoint(
+  async (req, state, params, auth) => {
+    const path = \`/\${params['*'] ?? ''}\`;
+    const isShared = path.startsWith('/public/') && !path.includes('..');
+    if (!auth.threadAccess && !isShared) {
+      return new Response(null, { status: 404 });
+    }
+
+    const [data, stat] = await Promise.all([state.readFile(path), state.statFile(path)]);
+    if (!data || !stat) {
+      return new Response(null, { status: 404 });
+    }
+
+    return new Response(data, {
+      headers: {
+        'Content-Type': stat.mimeType,
+        'Content-Disposition': 'attachment',
+        'X-Content-Type-Options': 'nosniff',
+      },
+    });
+  },
+  { access: 'public' },
+);
 \`\`\`
 
-Let unexpected exceptions reach the runtime boundary.
+Anyone with the URL can call a public endpoint. Validate the path, and never return private thread data to an anonymous caller.
 
-## File System Operations
+Serve thread files as downloads, as this example does. Endpoints share an origin with the builder UI and its APIs. An HTML or SVG file shown inline would run its scripts with the access of whoever opened the link. \`Content-Disposition: attachment\` makes the browser save the file, and \`X-Content-Type-Options: nosniff\` stops it from guessing a different type.
 
-\`\`\`typescript
-import { defineThreadEndpoint } from '@standardagents/spec';
+## Thread files
 
-export default defineThreadEndpoint(async (req, state) => {
-  // Read files
-  const content = await state.readFile('/data/file.txt');
+Each thread has its own file system, reached through \`state\`:
+
+| Method | Does |
+|--------|------|
+| \`readFile(path)\` | Returns the file's bytes as an \`ArrayBuffer\`, or \`null\` |
+| \`writeFile(path, data, mimeType)\` | Creates or replaces a file |
+| \`statFile(path)\` | Returns the file's details, or \`null\` |
+| \`readdirFile(path)\` | Returns \`{ entries }\` for a directory |
+| \`moveFile(from, to)\` / \`renameFile(path, newName)\` | Moves or renames. Does not overwrite |
+| \`unlinkFile(path)\` | Deletes a file |
+| \`findFiles(pattern)\` | Returns \`{ paths }\` matching a glob such as \`**/*.json\` |
+| \`grepFiles(pattern)\` | Searches file contents |
 
-  // Write files
-  await state.writeFile('/output/result.json', JSON.stringify(data), 'application/json');
+## Errors
 
-  // List directory
-  const { entries } = await state.readdirFile('/data');
+Return an error as JSON with the right status:
 
-  // Move or rename files and directories (does not overwrite an existing destination)
-  await state.moveFile('/data/file.txt', '/archive/file.txt');
-  await state.renameFile('/output/result.json', 'final.json');
+\`\`\`text
+return Response.json({ error: 'Send a JSON body with a "text" string.' }, { status: 400 });
+\`\`\`
 
-  // Search files
-  const matches = await state.grepFiles('pattern');
-  const paths = await state.findFiles('**/*.ts');
+The runtime rewrites every failed \`/api/\` response into one shape, and adds a request ID:
 
-  return Response.json({ success: true });
-});
+\`\`\`text
+{ "error": { "code": "internal_error", "message": "..." }, "requestId": "..." }
 \`\`\`
 
-## Best Practices
+Let unexpected exceptions throw. The caller receives HTTP 500 with code \`internal_error\` and no exception details; the dev server terminal and the deployed project's logs hold the exception and the same request ID.
 
-- **Keep handlers fast** - endpoints are in the request path
-- **Paginate large queries** - use limit/offset for messages
-- **Validate input data** - check request body before processing
-- **Use descriptive file names** - \`export.post.ts\` not \`ep1.ts\`
-- **Return proper status codes** - 200, 400, 404, 500
-- **Import from spec** - use \`@standardagents/spec\` for \`defineThreadEndpoint\`
+## Practices
+
+- Validate request bodies before you use them.
+- Page large reads with \`limit\` and \`offset\`.
+- Name files for what they do: \`export.post.ts\`, not \`ep1.ts\`.
+- Keep endpoints quick. Start long work with \`state.queueMessage()\` and let the agent do it.
 
 ## Documentation
 
@@ -2108,133 +1748,250 @@ Full reference: https://docs.standardagentbuilder.com/core-concepts/api
 `;
 
 // src/docs/users.ts
-var USERS_AGENTS_MD = `# User Endpoints
+var USERS_AGENTS_MD = `# User endpoints
 
-Define user-scoped API endpoints \u2014 HTTP handlers that operate on a USER
-(durable cross-thread state) rather than a single thread. They execute inside
-the per-user hub with a serialization guarantee: at most one user endpoint
-runs at a time per user, and each observes all prior completed writes. That
-makes this directory the home for quotas, leases, counters, registries, and
-any other user-level logic where lost updates matter.
+A user endpoint is an HTTP route that runs for one user instead of one thread. Each file in this directory becomes a route under \`/api/users/me/\`. Use user endpoints for data that spans a user's threads: preferences, quotas, counters, and registries.
 
-Specification: https://standardagentspec.com/0.2.0/specification/users
+For one user, only one user endpoint runs at a time, and each run sees every write made by the runs before it. That makes this the safe place to check a limit and then update it.
 
-## File-Based Routing
+## Routing
 
-| File Pattern | HTTP Method | Route |
-|--------------|-------------|-------|
-| \`name.ts\` | GET | \`/api/users/me/name\` |
-| \`name.post.ts\` | POST | \`/api/users/me/name\` |
-| \`pkg/name.post.ts\` | POST | \`/api/users/me/pkg/name\` |
+Routing follows the same rules as thread endpoints: the path sets the route, a suffix sets the method, and \`[name]\` and \`[*]\` capture segments.
+
+| File | Method | Route |
+|------|--------|-------|
+| \`preferences.ts\` | GET | \`/api/users/me/preferences\` |
+| \`preferences.put.ts\` | PUT | \`/api/users/me/preferences\` |
+| \`quota/spend.post.ts\` | POST | \`/api/users/me/quota/spend\` |
 | \`items/[id].ts\` | GET | \`/api/users/me/items/:id\` |
-| \`files/[*].ts\` | GET | \`/api/users/me/files/*\` |
 
-Routing rules match thread endpoints (method suffixes, nested directories,
-\`[param]\`, \`[*]\`). Root your endpoints in a directory named for your
-package so installed packages coexist. Administrators can address any user's
-endpoints at \`/api/users/:id/...\`. The \`:id\` is the instance user id; an
-administrator who knows only an email resolves it with
-\`GET /api/users/lookup?email=<email>\` (\`{ users: [{ id, username, email, source }] }\`).
+\`me\` is the signed-in caller. An administrator can call the same endpoints for another user at \`/api/users/:id/...\`.
+
+## Defining a user endpoint
 
-## Basic Example
+Import \`defineUserEndpoint\` from \`@standardagents/spec\`. The function receives the request, a \`UserState\`, and the route parameters.
 
 \`\`\`typescript
-// agents/users/quota.post.ts \u2192 POST /api/users/me/quota
+// agents/users/quota/spend.post.ts
 import { defineUserEndpoint } from '@standardagents/spec';
+import { z } from 'zod';
+
+const SpendInput = z.object({
+  amount: z.number().int().positive(),
+});
+
+const DAILY_LIMIT = 100;
 
-export default defineUserEndpoint(async (req, user, params) => {
-  const used = (await user.getValue<number>('quota.used')) ?? 0;
-  const limit = Number(await user.getValue('quota.limit')) || 0;
-  const { amount } = await req.json();
-  if (used + amount > limit) {
-    return Response.json({ ok: false, used, limit }, { status: 429 });
+export default defineUserEndpoint(async (req, user) => {
+  const input = SpendInput.safeParse(await req.json().catch(() => null));
+  if (!input.success) {
+    return Response.json({ error: 'Send a JSON body with a positive integer "amount".' }, { status: 400 });
   }
-  await user.setValue('quota.used', used + amount);
-  user.emit('quota_changed', { used: used + amount, limit });
-  return Response.json({ ok: true });
+
+  const key = \`quota.\${new Date().toISOString().slice(0, 10)}\`;
+  const used = (await user.getValue<number>(key)) ?? 0;
+  if (used + input.data.amount > DAILY_LIMIT) {
+    return Response.json({ ok: false, used, limit: DAILY_LIMIT }, { status: 429 });
+  }
+
+  await user.setValue(key, used + input.data.amount);
+  user.emit('quota_changed', { used: used + input.data.amount, limit: DAILY_LIMIT });
+
+  return Response.json({ ok: true, used: used + input.data.amount, limit: DAILY_LIMIT });
 });
 \`\`\`
 
 ## UserState
 
-Handlers receive a \`UserState\`: \`userId\`, \`identity()\`, durable values
-(\`getValue\`/\`setValue\`/\`listValues\`), \`env()\`, \`emit()\` (broadcast on
-the user event stream at \`/api/users/me/stream\`), \`listThreads()\`,
-\`fetch(grant, url, init)\` (privileged fetch through a credential grant), and
-\`thread(threadId)\` (raise one of the user's threads at rest).
-
-\`user.identity()\` returns a \`UserIdentity\`. Its \`username\` and \`role\` fields may be absent or null.
-
-## User Rooms
-
-A \`users/pkg/room.ts\` file may export \`defineUserRoom\` to handle hub frames
-under the same per-user serialization as user endpoints. It is not HTTP-routed.
-\`user.clients()\` lists admitted connections; \`user.send(clientId, frame)\`
-targets one admitted client. Automatic admission preserves reconnect behavior.
-
-For application proofs beyond the user's transport authentication, declare
-\`admission: 'explicit'\`. Pending sockets cannot displace an admitted client or
-receive its targeted traffic, broadcasts or wake requests. Require both
-\`user.roomAttachments\` and \`connection.attachmentId\`; fail closed if absent.
-Use \`user.roomAttachments.send(connection.attachmentId, frame)\` for challenges
-and replies. After verifying the application's proof, call
-\`user.roomAttachments.admit(connection.attachmentId)\`; false means the socket
-is gone. Reject a failed proof with
-\`user.roomAttachments.close(connection.attachmentId, 4003, "Proof rejected")\`;
-this closes that socket and reports its detach. Never use a client id or timestamp as the physical attachment identity.
-
-In explicit mode, \`onPresence\` reports every physical attach/detach, including
-pending and superseded sockets, without reconnect grace. Discard challenges on
-detach and application restart. Runtime hibernation preserves attachment ids
-and admission; reconnect uses a new id, and restored legacy sockets start pending.
-The runtime supplies admission mechanics; your room owns authentication policy.
-
-## Application Roles
-
-Read \`(await user.identity()).roles ?? []\` to authorize application operations.
-Hosted roles are assigned in Platform \u2192 project Settings \u2192 Users and pushed
-to the instance. They are separate from the \`admin\`/\`user\`/\`api\` access
-level and built-in permissions. Role strings are case-sensitive; their meaning
-belongs to your application. A \`:*\` suffix does not match anything implicitly.
+| Member | Does |
+|--------|------|
+| \`userId\` | The user's ID |
+| \`identity()\` | Returns the user's profile: \`id\`, \`username\`, \`email\`, \`role\`, \`roles\` |
+| \`getValue(key)\` / \`setValue(key, value)\` | Durable JSON values for this user. A \`null\` value deletes the key |
+| \`listValues({ prefix, limit, offset })\` | Lists the user's values |
+| \`env(name)\` | Reads a variable |
+| \`emit(event, data)\` | Sends a live event to the user's connected clients |
+| \`listThreads({ agentId, limit, offset })\` | Lists the user's threads |
+| \`thread(threadId)\` | Returns the \`ThreadState\` of one of the user's threads |
+
+Do not store credentials in user values. They are plain JSON.
+
+## Calling a user endpoint from a thread
+
+Tools, hooks, handlers, and thread endpoints reach the user through \`state.user()\`. \`call()\` runs a user endpoint by its path under \`agents/users/\`, with the same one-at-a-time guarantee.
 
 \`\`\`typescript
-const identity = await user.identity();
-const roles = identity.roles ?? [];
-if (!roles.includes('reports:read')) {
-  return Response.json({ error: 'Forbidden' }, { status: 403 });
-}
-\`\`\`
+// agents/tools/spend_quota.ts
+import { defineTool } from '@standardagents/builder';
+import { z } from 'zod';
 
-Check roles in each request or execution that performs a protected operation.
-Identity is a snapshot within that execution; pushed role changes take effect
-on the next request or execution. Missing roles grant no access. Never trust
-roles supplied in a request body or user-writable KV.
+export default defineTool({
+  description: 'Spend units of the user\\'s daily quota before doing metered work. Fails when the quota is used up.',
+  args: z.object({
+    amount: z.number().int().positive().describe('How many units to spend'),
+  }),
+  execute: async (state, args) => {
+    const user = await state.user();
+    if (!user) {
+      return { status: 'error', error: 'This thread has no user.', error_code: 'no_user' };
+    }
 
-## Caller Channels
+    const response = await user.call('quota/spend', { amount: args.amount });
+    if (!response.ok) {
+      return { status: 'error', error: 'The daily quota is used up.', error_code: 'quota_exceeded' };
+    }
+    return { status: 'success', result: await response.text() };
+  },
+});
+\`\`\`
 
-Handlers can distinguish who invoked them via the
-\`X-Standard-Agents-Caller\` request header, which the runtime stamps and
-un-forgeably overwrites on public routes: \`user\` (the user's own HTTP
-request), \`admin\` (administrative addressing), or \`thread\` (a
-runtime-internal \`state.user().call()\`). Gate enforcement-critical
-mutations (quotas, leases) on the \`thread\` channel.
+A user endpoint can tell how it was called from the \`X-Standard-Agents-Caller\` request header, which the runtime sets and callers cannot forge: \`user\` for the user's own HTTP request, \`admin\` for an administrator, and \`thread\` for a call from \`state.user().call()\`. Check for \`thread\` in an endpoint that only your agents should be able to change.
 
-## Reaching the User Scope from Threads
+## Roles
 
-Tools, hooks, and thread endpoints call user endpoints through the thread's
-user handle:
+A user's application roles are strings assigned in the project's user settings on the platform. Their meaning is up to you. Read them from the identity and check them in every request that needs one:
 
 \`\`\`typescript
-const user = await state.user();
-await user?.call('quota', { amount: 1 }); // serialized, atomic
+// agents/users/reports.ts
+import { defineUserEndpoint } from '@standardagents/spec';
+
+export default defineUserEndpoint(async (req, user) => {
+  const identity = await user.identity();
+  const roles = identity.roles ?? [];
+  if (!roles.includes('reports:read')) {
+    return Response.json({ error: 'Forbidden' }, { status: 403 });
+  }
+
+  const threads = await user.listThreads({ limit: 20 });
+  return Response.json({ threads });
+});
 \`\`\`
 
-## Live Events
+Roles are matched exactly; a suffix such as \`:*\` has no special meaning. A user with no roles gets no access. Never read roles from a request body or from user values.
+
+## Live events
+
+A client can open a WebSocket to \`/api/users/me/stream\` and receive every \`user.emit()\` as \`{ "event": string, "data": unknown }\`. Events are not stored. Read the durable values again after connecting or reconnecting.
+
+## Documentation
+
+Specification: https://standardagentspec.com/0.2.0/specification/users
+`;
+
+// src/starter.ts
+var STARTER_SPECIFICATION_VERSION = "0.2.0";
+var LOW_COST_MODEL = `import { defineModel } from '@standardagents/builder';
+import { novita } from '@standardagents/novita';
+
+export default defineModel({
+  name: 'low_cost',
+  provider: novita,
+  model: 'deepseek/deepseek-v4.1-flash-1017',
+});
+`;
+var GUIDE_PROMPT = `import { definePrompt } from '@standardagents/builder';
+
+export default definePrompt({
+  name: 'guide',
+  toolDescription: 'Answer questions about building agents in this project and about the Standard Agent Specification',
+  model: 'low_cost',
+  prompt: \`You are the guide in a new Standard Agents Builder project. You answer questions about building agents with Standard Agents Builder and about the Standard Agent Specification.
+
+You have one tool, read_docs. It reads a page from the two documentation sites:
+
+- Builder documentation. Its index is https://docs.standardagentbuilder.com/llms.txt
+- The Standard Agent Specification. Its index is https://standardagentspec.org/llms.txt
+
+Each index lists a Markdown URL for every page.
+
+How to answer:
+
+1. For a question about the builder or the specification, read the index of the site that covers it, unless you already read it in this conversation. Then read the pages that cover the question.
+2. Take every URL from an index or from a page you have read. Do not build a URL from memory.
+3. Answer from what the pages say. If the pages do not cover the question, say that and name the pages you read. Do not fill the gap from memory.
+4. Answer for version ${STARTER_SPECIFICATION_VERSION} of the specification, whose pages have /${STARTER_SPECIFICATION_VERSION}/ in their URL, unless the user names another version.
+5. Keep the answer short. Show a complete code example when it helps. End with the URLs of the pages you used.
+
+You cannot read or change the files in this project. When the user wants something built, say which files to create and what goes in them, and suggest they give that to their coding agent. The AGENTS.md file in the project root explains the project to a coding agent.
+
+For a greeting or a question about yourself, reply without reading anything. Say what you can answer and offer these example questions: "How do I add a tool to a prompt?", "What is the difference between a prompt and an agent?", and "How do subagents work in the specification?"\`,
+  tools: ['read_docs'],
+  includeChat: true,
+  includePastTools: true,
+});
+`;
+var READ_DOCS_TOOL = `import { defineTool } from '@standardagents/builder';
+import { z } from 'zod';
+
+// The only sites this tool reads. A URL on any other host is refused before a request is made.
+const SITES = ['docs.standardagentbuilder.com', 'standardagentspec.org'];
+// About 15,000 tokens. Every page listed in the two indexes is shorter than this.
+const MAX_CHARACTERS = 60_000;
+
+export default defineTool({
+  description:
+    'Read one page of the Standard Agents Builder documentation or the Standard Agent Specification. Returns the page as Markdown. Start with an index: https://docs.standardagentbuilder.com/llms.txt or https://standardagentspec.org/llms.txt.',
+  args: z.object({
+    url: z.string().describe('The https URL of an index or of a Markdown page that an index lists'),
+  }),
+  execute: async (_state, args) => {
+    let url: URL;
+    try {
+      url = new URL(args.url);
+    } catch {
+      return { status: 'error', error: 'That is not a URL.', error_code: 'not_allowed' };
+    }
+    if (url.protocol !== 'https:' || !SITES.includes(url.hostname) || url.username || url.password || url.port) {
+      return {
+        status: 'error',
+        error: \`This tool reads only https pages on \${SITES.join(' and ')}.\`,
+        error_code: 'not_allowed',
+      };
+    }
+
+    const response = await fetch(url, { headers: { accept: 'text/markdown, text/plain' } });
+    const type = response.headers.get('content-type') ?? '';
+    // An unknown path can come back as an HTML page with status 200.
+    if (response.status === 404 || (response.ok && !/^text\\/(markdown|plain)\\b/.test(type))) {
+      return {
+        status: 'error',
+        error: \`No documentation page at \${url.href}. Take the URL from an index.\`,
+        error_code: 'not_found',
+      };
+    }
+    if (!response.ok) {
+      return {
+        status: 'error',
+        error: \`The documentation site returned HTTP \${response.status}.\`,
+        error_code: 'upstream_error',
+      };
+    }
+
+    const text = await response.text();
+    if (text.length <= MAX_CHARACTERS) return { status: 'success', result: text };
+    return {
+      status: 'success',
+      result: \`\${text.slice(0, MAX_CHARACTERS)}\\n\\n[Truncated: the page is \${text.length} characters long. Read a more specific page instead.]\`,
+    };
+  },
+});
+`;
+var GUIDE_AGENT = `import { defineAgent } from '@standardagents/builder';
 
-Clients subscribe to \`GET /api/users/me/stream\` (WebSocket) and receive every
-\`emit()\` as \`{ "event": string, "data": unknown }\`. The stream is live-only:
-re-read durable state on connect and reconnect.
+export default defineAgent({
+  name: 'guide_agent',
+  title: 'Guide',
+  description: 'Answers questions about building agents in this project and about the Standard Agent Specification.',
+  sideA: { label: 'Guide', prompt: 'guide', maxSteps: 12 },
+  sideB: { label: 'You', human: true },
+});
 `;
+var STARTER_AGENT_FILES = [
+  { path: "agents/models/low_cost.ts", content: LOW_COST_MODEL, label: "model" },
+  { path: "agents/tools/read_docs.ts", content: READ_DOCS_TOOL, label: "documentation tool" },
+  { path: "agents/prompts/guide.ts", content: GUIDE_PROMPT, label: "prompt" },
+  { path: "agents/agents/guide_agent.ts", content: GUIDE_AGENT, label: "agent" }
+];
 
 // src/index.ts
 var FIRST_PARTY_PROVIDER_PACKAGES = [
@@ -2258,7 +2015,7 @@ var APPROVED_DEPENDENCY_BUILD_SCRIPTS = [
   "sharp",
   "workerd"
 ];
-var AGENTBUILDER_TEMPLATE_VERSION = "0.45.1";
+var AGENTBUILDER_TEMPLATE_VERSION = "0.45.3";
 var DEFAULT_TEMPLATE_VERSIONS = {
   standardAgents: `^${AGENTBUILDER_TEMPLATE_VERSION}`,
   sip: "^1.0.1",
@@ -2314,7 +2071,7 @@ function renderPackageJson(options) {
     private: true,
     type: "module",
     scripts: {
-      dev: "vite --host 0.0.0.0 --port 5173",
+      dev: "vite --host 127.0.0.1 --port 5173",
       build: options.includeBuildScript ? "vite build" : "echo 'Standard Agents projects build and deploy on the platform. Push your commit (git push or agents deploy) to trigger a build.' && exit 1",
       typecheck: "tsc --noEmit"
     },
@@ -2400,8 +2157,9 @@ function renderDevVarsExample() {
 # Local data encryption key. Generate with: openssl rand -hex 32
 ENCRYPTION_KEY=
 
-# Optional local admin password for development access.
-SUPER_ADMIN_PASSWORD=password
+# Local password sign-in for projects without a Standard Agents account link.
+# Leave it unset for a platform-linked project. Use a long random value.
+SUPER_ADMIN_PASSWORD=
 
 # Platform connection. The CLI writes real values to .dev.vars for platform-created projects.
 STANDARD_AGENTS_API_KEY=
@@ -2430,9 +2188,33 @@ function renderTemplateMetadata(options) {
   }, null, 2)}
 `;
 }
+var AGENT_DOCS = [
+  { directory: ".", content: ROOT_AGENTS_MD, label: "project" },
+  { directory: "agents/agents", content: AGENT_DEFINITIONS_AGENTS_MD, label: "agent" },
+  { directory: "agents/prompts", content: PROMPTS_AGENTS_MD, label: "prompt" },
+  { directory: "agents/models", content: MODELS_AGENTS_MD, label: "model" },
+  { directory: "agents/providers", content: PROVIDERS_AGENTS_MD, label: "provider" },
+  { directory: "agents/tools", content: TOOLS_AGENTS_MD, label: "tool" },
+  { directory: "agents/hooks", content: HOOKS_AGENTS_MD, label: "hook" },
+  { directory: "agents/handlers", content: HANDLERS_AGENTS_MD, label: "handler" },
+  { directory: "agents/api", content: API_AGENTS_MD, label: "thread endpoint" },
+  { directory: "agents/users", content: USERS_AGENTS_MD, label: "user endpoint" }
+];
+function renderAgentDocs() {
+  return AGENT_DOCS.flatMap(({ directory, content, label }) => {
+    const prefix = directory === "." ? "" : `${directory}/`;
+    return [
+      file(`${prefix}AGENTS.md`, content, `Add ${label} docs`),
+      symlink(`${prefix}CLAUDE.md`, "AGENTS.md", `Add Claude ${label} docs symlink`)
+    ];
+  });
+}
+function renderStarterAgent() {
+  return STARTER_AGENT_FILES.map(({ path, content, label }) => file(path, content, `Add starter ${label}`));
+}
 function renderAgentBuilderSupportFiles(options) {
   return [
-    file("package.json", renderPackageJson(options), "Add local AgentBuilder package manifest")
+    file("package.json", renderPackageJson(options), "Add local Standard Agents Builder package manifest")
   ];
 }
 function renderAgentBuilderProject(options) {
@@ -2454,24 +2236,8 @@ function renderAgentBuilderProject(options) {
     file("pnpm-workspace.yaml", renderPnpmWorkspaceYaml(), "Add pnpm settings"),
     file("tsconfig.json", renderTsConfig(), "Add TypeScript config"),
     file("vite.config.ts", renderViteConfig(), "Add Vite config"),
-    file("agents/agents/AGENTS.md", AGENT_DEFINITIONS_AGENTS_MD, "Add agent docs"),
-    symlink("agents/agents/CLAUDE.md", "AGENTS.md", "Add Claude agent docs symlink"),
-    file("agents/prompts/AGENTS.md", PROMPTS_AGENTS_MD, "Add prompt docs"),
-    symlink("agents/prompts/CLAUDE.md", "AGENTS.md", "Add Claude prompt docs symlink"),
-    file("agents/handlers/AGENTS.md", HANDLERS_AGENTS_MD, "Add handler docs"),
-    symlink("agents/handlers/CLAUDE.md", "AGENTS.md", "Add Claude handler docs symlink"),
-    file("agents/models/AGENTS.md", MODELS_AGENTS_MD, "Add model docs"),
-    symlink("agents/models/CLAUDE.md", "AGENTS.md", "Add Claude model docs symlink"),
-    file("agents/providers/AGENTS.md", PROVIDERS_AGENTS_MD, "Add provider docs"),
-    symlink("agents/providers/CLAUDE.md", "AGENTS.md", "Add Claude provider docs symlink"),
-    file("agents/tools/AGENTS.md", TOOLS_AGENTS_MD, "Add tool docs"),
-    symlink("agents/tools/CLAUDE.md", "AGENTS.md", "Add Claude tool docs symlink"),
-    file("agents/hooks/AGENTS.md", HOOKS_AGENTS_MD, "Add hook docs"),
-    symlink("agents/hooks/CLAUDE.md", "AGENTS.md", "Add Claude hook docs symlink"),
-    file("agents/api/AGENTS.md", API_AGENTS_MD, "Add API docs"),
-    symlink("agents/api/CLAUDE.md", "AGENTS.md", "Add Claude API docs symlink"),
-    file("agents/users/AGENTS.md", USERS_AGENTS_MD, "Add user endpoint docs"),
-    symlink("agents/users/CLAUDE.md", "AGENTS.md", "Add Claude user endpoint docs symlink")
+    ...renderAgentDocs(),
+    ...renderStarterAgent()
   ];
   if (options.includeTemplateMetadata) {
     files.push(file(".standardagents/template.json", renderTemplateMetadata(options), "Add Standard Agents template metadata"));
@@ -2482,6 +2248,7 @@ export {
   AGENTBUILDER_TEMPLATE_VERSION,
   AGENT_DEFINITIONS_AGENTS_MD as AGENTS_CLAUDE_MD,
   AGENT_DEFINITIONS_AGENTS_MD,
+  AGENT_DOCS,
   API_AGENTS_MD,
   API_AGENTS_MD as API_CLAUDE_MD,
   APPROVED_DEPENDENCY_BUILD_SCRIPTS,
@@ -2499,6 +2266,8 @@ export {
   PROVIDERS_AGENTS_MD as PROVIDERS_CLAUDE_MD,
   ROOT_AGENTS_MD,
   ROOT_AGENTS_MD as ROOT_CLAUDE_MD,
+  STARTER_AGENT_FILES,
+  STARTER_SPECIFICATION_VERSION,
   TOOLS_AGENTS_MD,
   TOOLS_AGENTS_MD as TOOLS_CLAUDE_MD,
   USERS_AGENTS_MD,