Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

Docs Improvements (#146)

Abhishek Choudharyc6f02517acab
diff --git a/README.md b/README.md
index 176939b1d..79f31a107 100644
--- a/README.md
+++ b/README.md
@@ -1,52 +1,46 @@
# TrueForge
-**The open-source agent harness - the runtime layer that turns an LLM into a working agent.**
+**The open-source agent harness — the runtime layer that turns an LLM into a working agent.**
-TrueForge runs the agent execution loop for you - model calls, tool use, context management, and session state - and exposes the result three ways: a chat UI, an HTTP API, and a TypeScript library.
+TrueForge runs the agent execution loop for you — model calls, MCP tools, skills, sandboxing, approvals, context management, and session state — and exposes it three ways: a **chat UI**, an **HTTP API** with a TypeScript **SDK**, and an embeddable **UI SDK**.
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node.js >= 22.13](https://img.shields.io/badge/Node.js-%3E%3D22.13-green.svg)](https://nodejs.org)
-<!-- TODO: replace placeholder links below with real URLs -->
+[Documentation](https://trueforge.dev) · [Quickstart](https://trueforge.dev/quickstart) · [SDK](https://trueforge.dev/api/overview) · [API Reference](https://trueforge.dev/api-reference) · [UI SDK](https://trueforge.dev/ui-sdk)
-[Documentation](#) · [Quickstart Guide](#) · [API Reference](#) · [Community](#)
-
-![TrueForge Chat UI](./docs/assets/hero.png)
+![TrueForge Chat UI](./docs/images/hero.png)
## Why TrueForge?
-Building an agent is easy. Running one in production is not - you need streaming, session persistence, tool servers, sandboxing, approvals, and a UI. TrueForge gives you all of that out of the box:
+Building an agent is easy. Running one well is not — you need streaming, session persistence, tool servers, sandboxing, approvals, and a UI. TrueForge gives you that out of the box:
-- **Multi-turn sessions with streaming** - resumable turn streams that survive reconnects and server restarts.
-- **MCP tool servers** - connect any [Model Context Protocol](https://modelcontextprotocol.io) server, including ones that require OAuth.
-- **Any model provider** - OpenAI, Anthropic, Google Gemini, and a catalog of hosted and open-weight models, or any OpenAI-compatible endpoint - all configured from the UI or the API.
-- **Skills** - reusable instruction packs the agent loads on demand.
-- **Sandboxed code execution** - run agent-generated code in isolated sandboxes.
-- **Human-in-the-loop approvals** - pause the agent and wait for a person before sensitive tool calls.
-- **Subagents** - agents that delegate work to other agents.
-- **Chat UI, HTTP API, and TypeScript library** - use whichever surface fits your product.
+- **Initial setup from catalogs** — configure [models](https://trueforge.dev/models), [MCP servers](https://trueforge.dev/mcp-servers), [skills](https://trueforge.dev/skills), and a [sandbox](https://trueforge.dev/sandbox) once; agents pick from what you connected. Presets come from shipped YAML catalogs you can customize.
+- **Any model provider** — OpenAI, Anthropic, Google Gemini, and other catalog providers, or any OpenAI-compatible endpoint.
+- **MCP tools** — remote MCP servers with header auth or OAuth, including in-chat authorization.
+- **Skills** — git-backed `SKILL.md` instruction packs, loaded on demand in the sandbox.
+- **Sandbox as a tool** — isolated code/file execution (Daytona today; more providers planned), provisioned only when needed. Secrets stay in the harness.
+- **Human checkpoints** — tool approval, ask-user-questions, and Generative UI in chat.
+- **Context engineering** — subagents, deferred tool loading, Code Mode, large-result offloading, and compaction.
+- **Chat UI + SDK** — use the bundled UI, automate with `trueforge-sdk`, or embed `@truefoundry/trueforge-ui`.
-It scales down and up: run it as a single process backed by SQLite, or run multiple replicas backed by Postgres and Redis.
+It scales down and up: **local mode** (one process, SQLite) or **hosted mode** (Postgres + Redis, Docker Compose or Helm).
## Quick start
-### Option 1: npx (fastest)
-
-<!-- TODO: remote this note after packages are published -->
+### Local mode (npx)
-> Note: This option will be available when packages are published to NPM. Please use Option 2
-
-Requires [Node.js](https://nodejs.org) 22.13 or newer. One command, no other infrastructure - data is stored in a local SQLite file:
+Requires [Node.js](https://nodejs.org) 22.13 or newer. One command, no other infrastructure — UI and backend run locally; data is stored in SQLite:
```bash
npx @truefoundry/trueforge
```
-Then open [http://localhost:8790](http://localhost:8790), add a model provider under **Settings**, and start chatting.
+Then open [http://localhost:8790](http://localhost:8790).
-### Option 2: From source (pnpm)
+### From source (pnpm)
-Runs the standalone (SQLite) topology from a clone of this repo — no Docker, no Postgres, no Redis. Requires [Node.js](https://nodejs.org) 22.13+ and [pnpm](https://pnpm.io)
+Standalone (SQLite) topology from a clone — no Docker. Requires Node.js 22.13+ and [pnpm](https://pnpm.io):
```bash
git clone https://github.com/truefoundry/trueforge.git
@@ -55,11 +49,11 @@ cp packages/server/.env.example packages/server/.env
pnpm standalone:dev
```
-Then open [http://localhost:3000](http://localhost:3000) - Vite serves the UI with live reload and proxies API calls to the server on port 8790. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide, including the Postgres + Redis dev topology.
+Then open [http://localhost:3000](http://localhost:3000) — Vite serves the UI with live reload and proxies API calls to the server on port 8790. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide (including Postgres + Redis).
-### Option 3: Docker Compose
+### Hosted mode (Docker Compose)
-Runs the full production topology on your machine: the server (UI + API), Postgres, and Redis. Clone the repo first:
+Server (UI + API), Postgres, and Redis:
```bash
git clone https://github.com/truefoundry/trueforge.git
@@ -70,131 +64,105 @@ docker compose up --build
Then open [http://localhost:8791](http://localhost:8791).
-| Configuration | Default | Description |
-| ----------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` | `harness` (from `.env`) | Postgres credentials, read from `packages/server/.env`. |
-| `PUBLIC_BASE_URL` | `http://localhost:8791` | Public origin, used for MCP OAuth callbacks. |
-| Host ports | `8791`, `5433`, `6380` | App, Postgres, and Redis - offset so they don't clash with local dev. |
-| `OIDC_ISSUER_URL` / `OIDC_CLIENT_ID` / `OIDC_CLIENT_SECRET` | unset | Optional IdP. Unset = local admin. When set, APIs accept the ID token via cookie or `Authorization: Bearer`. |
+| Configuration | Default | Description |
+| ----------------------------------------------------- | ----------------------- | ---------------------------------------------- |
+| `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` | from `.env` | Postgres credentials (`packages/server/.env`). |
+| `PUBLIC_BASE_URL` | `http://localhost:8791` | Public origin for MCP OAuth / OIDC callbacks. |
+| Host ports | `8791`, `5433`, `6380` | App, Postgres, and Redis. |
Every environment variable is documented in [`packages/server/.env.example`](packages/server/.env.example).
-### Option 4: Kubernetes (Helm)
-
-The [`charts/truefoundry-utils`](charts/truefoundry-utils) Helm chart deploys the server in distributed mode (`STANDALONE=false`) with bundled Postgres and Redis (or point it at your own). No values are required for a basic install:
+### Hosted mode (Kubernetes)
-<!-- TODO: replace <HELM_REPO> with the published Helm repo URL -->
+The [`charts/truefoundry-utils`](charts/truefoundry-utils) Helm chart deploys hosted mode with bundled Postgres and Redis (or your own):
```bash
+# TODO: replace <HELM_REPO> with the published Helm repo URL
helm install truefoundry-utils oci://<HELM_REPO>/truefoundry-utils \
--version <x.y.z>
```
-| Configuration | Default | Description |
-| ---------------------- | ------- | ------------------------------------------------------------------------------ |
-| `server.publicBaseUrl` | `""` | Public origin for MCP OAuth / OIDC callbacks; set once you expose the service. |
-| `replicaCount` | `1` | Number of server replicas (turn cancel/streaming peers over Redis). |
-| `postgresql.enabled` | `true` | Bundle Postgres; set `false` and fill `externalPostgres.*` to bring your own. |
-| `redis.enabled` | `true` | Bundle Redis; set `false` and set `externalRedis.url` or `existingSecret`. |
-| `autoscaling.enabled` | `false` | Enable a HorizontalPodAutoscaler. |
-
-See the [chart README](charts/truefoundry-utils/README.md) for Secrets, external databases, ingress via `extraObjects`, and the full values reference.
-
-## Getting Started Walkthrough
-
-1. **Add a model provider** - Open **Settings → Models**, pick a provider from the catalog, and paste your API key.
+See the [chart README](charts/truefoundry-utils/README.md) and [Quickstart](https://trueforge.dev/quickstart) for values and details.
- ![Configure a model provider](./docs/assets/getting-started-provider.png)
+## Build your first agent
-2. **(Optional) Connect tools** - Add MCP servers, skills, and a sandbox provider under **Settings**.
+Full walkthrough: [Quickstart](https://trueforge.dev/quickstart).
- ![Connectors](./docs/assets/getting-started-connectors.png)
+1. **Setup models** — **Settings → Models**, pick a catalog provider, paste your API key.
-3. **(Optional) Configure Sandbox** - Open **Settings → Sandbox Providers** and configure Daytona.
+ ![Configure a model provider](./docs/images/quickstart-models.png)
- Sign up with [Daytona](https://app.daytona.io/) and create an API Key with permissions to write, delete snapshots and write sandboxes
+2. **Setup connectors & skills** (optional) — **Settings → Connectors** / **Skills**. Skills need a sandbox.
- ![Daytona API Key](./docs/assets/daytona-api-key.png)
+ ![Connectors](./docs/images/quickstart-connectors.png)
- Sync the sandbox image to Daytona
+3. **Setup sandbox** (optional) — **Settings → Sandbox providers**. Daytona is the only provider supported today.
- ```bash
- export DAYTONA_API_KEY="dtn_your-daytona-api-key-..."
- pnpm push-sandbox-image-to-daytona --image docker.io/truefoundrycloud/truefoundry-utils-core-sandbox:029ea5ff6438cf86b79282e087bfc17528067946 --name trueforge-sandbox-image
- ```
+ ![Sandbox](./docs/images/quickstart-sandbox.png)
- On UI, select the Daytona sandbox provider and enter your Daytona API Key and the name of the snapshot you created above
+4. **Create an agent** — pick a model, attach connectors/skills, write instructions, then **Save as agent**.
- ![Daytona Sandbox Provider](./docs/assets/getting-started-sandbox-provider.png)
+ ![Save as agent](./docs/images/quickstart-save-agent.png)
-4. **Start a session** - Create a chat and talk to your agent. Streaming, tool calls, and approvals all show up live in the UI.
+5. **Find it in the Agent Library** — open **Agents Library**, then **Try** or **Edit**. In hosted mode with login enabled, agents created by anyone are visible to everyone — see [Agent Library](https://trueforge.dev/agent-library).
- ![Chat with the agent](./docs/assets/getting-started-chat.png)
+ ![Agents Library](./docs/images/quickstart-agents-library.png)
-Interactive API docs are served by your running instance at `/api/v1/docs`. For everything else, see the [documentation](#). <!-- TODO: docs link -->
-
-## Components
-
-TrueForge is a single container image (or `npx` process) plus a database - and Redis when you run more than one replica.
+## Architecture
```mermaid
flowchart LR
- browser([Browser])
+ ui[Chat UI<br/>@truefoundry/trueforge-ui]
+ code[Your code<br/>trueforge-sdk]
subgraph server [TrueForge server]
- ui[Chat UI]
api[HTTP API]
+ loop[Agent loop]
+ api --> loop
+ end
+ db[(SQLite / Postgres)]
+ subgraph byo [Bring your own]
+ llm[Model providers]
+ mcp[MCP servers]
+ sandbox[Sandbox provider]
end
- db[(Postgres or SQLite)]
- redis[(Redis)]
- llm[Model providers]
- mcp[MCP servers]
- sandbox[Sandboxes]
-
- browser --> ui
- browser --> api
- api --> db
- api <--> redis
- api --> llm
- api --> mcp
- api --> sandbox
-```
-
-| Component | What it does |
-| --------------------- | --------------------------------------------------------------------------------------------------- |
-| **UI** | React chat interface, bundled into the server image and served on the same port as the API. |
-| **Backend** | Node.js (Hono) server: the agent execution loop, sessions, streaming, settings, and OpenAPI docs. |
-| **Postgres / SQLite** | Session and settings storage. SQLite in standalone mode; Postgres for multi-replica deployments. |
-| **Redis** | Cross-replica peering (turn cancellation and stream handoff). Only needed when running > 1 replica. |
-### Deployment modes
+ ui --> api
+ code --> api
+ loop --> db
+ loop --> llm
+ loop --> mcp
+ loop --> sandbox
+```
-| | Standalone | Multi-replica |
-| ----------- | -------------------------------- | ------------------------------------ |
-| Best for | Trying it out, single-user, edge | Production, teams, high availability |
-| Processes | One | One or more, peered over Redis |
-| Database | SQLite | Postgres |
-| Extra infra | None | Postgres + Redis |
-| How to run | `npx @truefoundry/trueforge` | Docker Compose or the Helm chart |
+| Mode | Best for | Storage | Extra infra | How to run |
+| ------ | --------------------------- | -------- | ---------------- | ---------------------------- |
+| Local | Personal use, trying it out | SQLite | None | `npx @truefoundry/trueforge` |
+| Hosted | Teams, multi-replica | Postgres | Postgres + Redis | Docker Compose or Helm |
## Documentation
-<!-- TODO: replace placeholder links with real URLs -->
-
-- [Introduction](#)
-- [Quickstart](#)
-- [Configuration reference](#)
-- [API reference](#)
-- [Deploying to Kubernetes](#)
+| Section | What you'll find |
+| -------------------------------------------------------------- | ----------------------------------------------------------------- |
+| [Introduction](https://trueforge.dev/introduction) | What an agent harness is and how TrueForge fits together |
+| [Quickstart](https://trueforge.dev/quickstart) | Run local or hosted, build your first agent |
+| [Initial Setup](https://trueforge.dev/harness/initial-setup) | Models, MCP, skills, sandbox — catalogs and overrides |
+| [Create an Agent](https://trueforge.dev/create-agent/overview) | Select resources; tool approval, questions, Generative UI |
+| [Key Features](https://trueforge.dev/key-features/overview) | Sandbox-as-tool, subagents, deferred tools, Code Mode, compaction |
+| [Benchmarking](https://trueforge.dev/benchmarking) | Cost/accuracy vs Claude Managed Agents and deepagents |
+| [Setup Login](https://trueforge.dev/authentication/overview) | Optional OIDC for shared deployments |
+| [SDK](https://trueforge.dev/api/overview) | TypeScript client: sessions, turns, events |
+| [Chat UI](https://trueforge.dev/chat-ui) | Bundled UI and embedding `@truefoundry/trueforge-ui` |
+| [API Reference](https://trueforge.dev/api-reference) | OpenAPI paths and schemas |
## Benchmarks
-We compare TrueForge against other agent frameworks (Claude Managed Agents, deepagents) on the same tasks, the same model, and the same prompt, and report accuracy alongside cost and latency. The harness, the exact prompt, the blind grader, and our results all live in [`benchmark/`](benchmark/) - and it is built to be re-run against your own dataset and models.
+We compare TrueForge against Claude Managed Agents and deepagents on the same tasks, tools, and model — same accuracy, lower cost. Reproduce it from [`benchmark/`](benchmark/). Write-up: [Benchmarking](https://trueforge.dev/benchmarking).
## Contributing
-We love contributions! Whether it's a bug report, a new feature, or a docs fix - see [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up a development environment and open a pull request. Please also read our [Code of Conduct](CODE_OF_CONDUCT.md).
+We love contributions — bug reports, features, and docs fixes. See [CONTRIBUTING.md](CONTRIBUTING.md) and our [Code of Conduct](CODE_OF_CONDUCT.md).
-To report a security vulnerability, please follow [SECURITY.md](SECURITY.md) instead of opening a public issue.
+To report a security vulnerability, follow [SECURITY.md](SECURITY.md) instead of opening a public issue.
## License
diff --git a/docs/agent-library.mdx b/docs/agent-library.mdx
new file mode 100644
index 000000000..be46eb8ec
--- /dev/null
+++ b/docs/agent-library.mdx
@@ -0,0 +1,31 @@
+---
+title: 'Agent Library'
+sidebarTitle: 'Agent Library'
+description: 'Browse, edit, and try saved agents from one place.'
+---
+
+The **Agent Library** is where saved agents live. Open it from the chat UI to search agents, edit their configuration, or start a conversation with **Try**.
+
+<Frame caption="Agents Library — search, edit, and try saved agents.">
+ <img src="/images/agents-library.png" alt="Agents Library modal listing saved agents with Edit and Try actions" />
+</Frame>
+
+From the library you can:
+
+- **Search** agents by name
+- **Edit** an agent's model, connectors, skills, and instructions
+- **Try** an agent to open a chat session with it
+
+## Visibility and access (hosted mode)
+
+In **hosted mode** with [login](/authentication/overview) enabled, TrueForge does **not** yet scope the agent library per user or team.
+
+<Warning>
+ Agents created by anyone are visible to everyone who can use the deployment. Treat the library as a shared catalog
+ for the whole instance — avoid putting secrets in agent instructions, and assume colleagues can open and try any
+ saved agent.
+</Warning>
+
+Session history remains owner-scoped (each user sees their own chats). Settings (models, connectors, skills, sandbox) remain **admin-only** when OIDC is enabled. The agent library itself is currently open to all authenticated users on that host.
+
+In **local mode** (single shared identity), there is one user, so the same shared-library model applies by definition.
diff --git a/docs/api/agent-spec.mdx b/docs/api/agent-spec.mdx
index a8c4627c8..f1a459be5 100644
--- a/docs/api/agent-spec.mdx
+++ b/docs/api/agent-spec.mdx
@@ -4,7 +4,7 @@ sidebarTitle: 'Agent Spec'
description: 'Every field on the AgentSpec — model, instructions, MCP servers, skills, and runtime config.'
---
-An `AgentSpec` is the complete definition of an agent. It is used inline when creating a session (`agent.type: "value"`) or saved as a named agent (`POST /api/v1/agents`) and referenced by id (`agent.type: "ref"`). All fields are `snake_case`.
+An `AgentSpec` is the complete definition of an agent. Pass it inline when creating a session, or save it as a named agent and reference it by name. All fields are `snake_case`.
```json A complete example
{
@@ -49,7 +49,7 @@ The only required field.
## `instructions`
-Optional string. The agent's system prompt — its role, behavior, and constraints. The harness appends its own guidance for enabled capabilities (sandbox, subagents, etc.), so keep this focused on _your_ agent. See [context engineering best practices](/context-engineering/overview#best-practices).
+Optional string. The agent's system prompt — its role, behavior, and constraints. The harness appends its own guidance for enabled capabilities (sandbox, subagents, etc.), so keep this focused on _your_ agent. See [Key Features](/key-features/overview) for how context is managed at runtime.
## `messages`
@@ -69,8 +69,8 @@ Optional array. Each entry attaches a [configured MCP server](/mcp-servers) by n
| `enable_tools` | `["@all"]` | Tools exposed to the agent: `@all`, `@read-only`, or literal tool names. |
| `disable_tools` | `[]` | Tools subtracted from the enabled set. |
| `preload_tools` | `[]` | Tools loaded eagerly into context while the rest stay deferred. |
-| `require_approval_for_tools` | `["@write", "@destructive"]` | Tools that pause for [human approval](/human-in-the-loop): `@all`, `@write`, `@destructive`, or literal names. |
-| `preload` | `false` | Load all tool schemas upfront instead of [on demand](/context-engineering/deferred-tool-loading). |
+| `require_approval_for_tools` | `["@write", "@destructive"]` | Tools that pause for [human approval](/create-agent/tool-approval): `@all`, `@write`, `@destructive`, or literal names. |
+| `preload` | `false` | Load all tool schemas upfront instead of [on demand](/key-features/deferred-tool-loading). |
The `@read-only`, `@write`, and `@destructive` selectors are resolved from the tool annotations published by the MCP server.
@@ -96,17 +96,17 @@ Runtime behavior. Every field has a default, so `config` can be omitted entirely
| -------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `iteration_limit` | `100` | Max agent-loop iterations per turn (1–1024). A safety stop for runaway loops. |
| `sandbox` | `{ "enabled": false }` | [Sandbox](/sandbox) for code execution, files, and skills. |
-| `dynamic_sub_agents` | `{ "enabled": true }` | [Subagents](/context-engineering/subagents). |
-| `context_management` | all enabled | [Compaction](/context-engineering/overview#context-compaction) and [large tool response offloading](/context-engineering/large-tool-responses). |
-| `generative_ui` | `{ "enabled": true }` | [Generative UI](/generative-ui) (OpenUI blocks). |
-| `ask_user_questions` | `{ "enabled": true }` | The [`ask_user_question`](/ask-user-questions) tool. |
+| `dynamic_sub_agents` | `{ "enabled": true }` | [Subagents](/key-features/subagents). |
+| `context_management` | all enabled | [Compaction](/key-features/overview#context-compaction) and [large tool response offloading](/key-features/large-tool-responses). |
+| `generative_ui` | `{ "enabled": true }` | [Generative UI](/create-agent/generative-ui) (OpenUI blocks). |
+| `ask_user_questions` | `{ "enabled": true }` | The [`ask_user_question`](/create-agent/ask-user-questions) tool. |
### `config.sandbox`
| Field | Default | Description |
| ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled` | `false` | Give the agent a sandbox. Required for skills and Code Mode. |
-| `file_downloads` | `true` | Allow downloading agent-produced files via the turn download endpoint. |
+| `file_downloads` | `true` | Allow clients to download files the agent produces in the sandbox. |
| `network_policy.auth_inject` | — | Up to one rule injecting git basic-auth credentials for exact hosts: `{ "type": "git", "match": { "hosts": ["github.com"] }, "auth_data": { "type": "basic", "username": "...", "password": "..." } }`. |
### `config.context_management`
diff --git a/docs/api/overview.mdx b/docs/api/overview.mdx
index 208e1fcbe..2381de265 100644
--- a/docs/api/overview.mdx
+++ b/docs/api/overview.mdx
@@ -1,10 +1,10 @@
---
-title: 'Using the API'
+title: 'SDK Overview'
sidebarTitle: 'Overview'
-description: 'Understand Agent, Session, Turn, Event, and Delta — then create sessions, run turns, and stream events over REST or the TypeScript SDK.'
+description: 'Understand Agent, Session, Turn, Event, and Delta — then drive TrueForge with the TypeScript SDK.'
---
-Everything the chat UI does goes through the HTTP API, so anything you can do in the UI you can automate. The API is served under `/api/v1`, documented interactively at `/api/v1/docs` (OpenAPI 3.1 at `/api/v1/openapi.json`). A generated TypeScript client, [`trueforge-sdk`](https://www.npmjs.com/package/trueforge-sdk), wraps the same API. For a full SDK cookbook (streaming, approvals, reconnects, threads), see [Use an agent](/api/use-agent).
+Everything the chat UI does is available programmatically. Use the TypeScript client [`trueforge-sdk`](https://www.npmjs.com/package/trueforge-sdk) to create sessions, stream turns, and handle approvals. For a full cookbook (streaming, approvals, reconnects, threads), see [Use an agent](/api/use-agent). For raw HTTP schemas and paths, use the **API Reference** tab.
## Core concepts
@@ -56,7 +56,7 @@ An **agent** is a definition, not a running process. You define it once — mode
}
```
-You can save this spec as a named agent (`POST /api/v1/agents`) and reference it by id in every session, or pass it inline when creating a session. See the [agent spec reference](/api/agent-spec) for every field.
+You can save this spec as a named agent and reference it by name in every session, or pass it inline when creating a session. See the [agent spec reference](/api/agent-spec) for every field.
### Session
@@ -102,14 +102,14 @@ flowchart LR
| **Turn 3** | Jane (or a support rep) | Approval: allow `process_refund` | Agent runs the refund and sends a confirmation. |
<Note>
- A turn can also end paused when the agent asks a clarifying question ([`tool.response_required`](/ask-user-questions))
+ A turn can also end paused when the agent asks a clarifying question ([`tool.response_required`](/create-agent/ask-user-questions))
or needs MCP OAuth ([`mcp.auth_required`](/mcp-servers#in-chat-authentication)). You resume with a new turn, just like
Turn 3 above.
</Note>
### Event
-While a turn runs, the agent emits **events** over Server-Sent Events (SSE) — one JSON object at a time. Events tell your app what the agent is doing: calling a tool, getting a result, writing a reply, or finishing.
+While a turn runs, the agent emits **events** on the SDK stream — one JSON object at a time. Events tell your app what the agent is doing: calling a tool, getting a result, writing a reply, or finishing.
**Events during Turn 1** (Jane asks for order status):
@@ -166,7 +166,7 @@ Sample payloads:
}
```
-Every event carries an `id` and a `thread_id` (`"main"` for the root agent, a generated id for [subagents](/context-engineering/subagents), or `null` for run-level events). The SSE message's `id:` field carries a per-stream **sequence number** used for [resuming after a disconnect](#non-streaming-reconnects-and-cancellation). The stream always opens with `turn.created` and closes with `turn.done`.
+Every event carries an `id` and a `thread_id` (`"main"` for the root agent, a generated id for [subagents](/key-features/subagents), or `null` for run-level events). The stream also carries a **sequence number** used for [resuming after a disconnect](/api/use-agent). The stream always opens with `turn.created` and closes with `turn.done`.
For field-level schemas of every event type, see the [turn events reference](/api/turn-events).
@@ -198,13 +198,13 @@ Deltas only exist on the live stream. When you list a turn's events afterwards (
<Note>
**Thread** is a related concept: an execution context inside a turn. The root agent runs on `thread_id: "main"`;
- [subagents](/context-engineering/subagents) get their own thread ids, announced by `thread.created` / `thread.done`
+ [subagents](/key-features/subagents) get their own thread ids, announced by `thread.created` / `thread.done`
events. Events carry `thread_id` so you can partition a single turn stream when subagents run in parallel.
</Note>
## The three turns, end to end
-Here is Jane's whole refund session against the API — solid arrows are HTTP requests you make; dashed arrows are SSE events streamed back.
+Here is Jane's whole refund session — your app opens a session, runs turns, and consumes streamed events.
{/* Mermaid source for regenerating the image below:
@@ -214,9 +214,9 @@ sequenceDiagram
participant TF as TrueForge · support-bot · main thread
Note over App,TF: Turn 1 — order status
- App->>TF: POST /api/v1/sessions (agent: support-bot)
+ App->>TF: sessions.create (agent: support-bot)
TF-->>App: { "id": "sess-7f2a9c1b" }
- App->>TF: POST /sessions/sess-7f2a9c1b/turns (user.message: "status of ORD-2031?")
+ App->>TF: createTurnStream (user.message: "status of ORD-2031?")
TF-->>App: turn.created { turn_id: "turn-001", previous_turn_id: null }
TF-->>App: mcp.initialize { mcp_servers: [orders-api] }
TF-->>App: model.message — tool call get_order({ order_id: "ORD-2031" })
@@ -225,14 +225,14 @@ sequenceDiagram
TF-->>App: turn.done { output: reply, required_actions: [] }
Note over App,TF: Turn 2 — refund request (pauses)
- App->>TF: POST /sessions/sess-7f2a9c1b/turns (user.message: "issue a full refund")
+ App->>TF: createTurnStream (user.message: "issue a full refund")
TF-->>App: turn.created { turn_id: "turn-002", previous_turn_id: "turn-001" }
TF-->>App: model.message (id: msg-b2) — tool call process_refund({ order_id, amount })
TF-->>App: tool.approval_required { tool_calls: [{ id: "call-refund-01" }] }
TF-->>App: turn.done { output: null, required_actions: [tool.approval_required] }
Note over App,TF: Turn 3 — approval resumes the run
- App->>TF: POST /sessions/sess-7f2a9c1b/turns (user.tool_approval: allow call-refund-01)
+ App->>TF: createTurnStream (user.tool_approval: allow call-refund-01)
TF-->>App: turn.created { turn_id: "turn-003", previous_turn_id: "turn-002" }
TF-->>App: tool.response { refund_id: "RF-9914", status: completed }
TF-->>App: model.message (id: msg-c3) + deltas: "Refund RF-9914 has been processed..."
@@ -241,10 +241,10 @@ sequenceDiagram
*/}
-<Frame caption="Three chained turns in one session: HTTP requests (solid) from your app and SSE events (dashed) streamed back from TrueForge, annotated with real payloads">
+<Frame caption="Three chained turns in one session: your app creates the session and turns; TrueForge streams events back">
<img
src="/images/api-sequence-diagram.png"
- alt="Sequence diagram of the support-bot session sess-7f2a9c1b across three turns. Your app calls POST /api/v1/sessions and POST /sessions/sess-7f2a9c1b/turns against the TrueForge harness running the support-bot main thread. Turn 1 (order status) streams turn.created, mcp.initialize, a get_order tool call and tool.response, model.message plus deltas, and turn.done. Turn 2 (refund request) streams a process_refund tool call, tool.approval_required, and a paused turn.done with required_actions. Turn 3 (approval) sends user.tool_approval and streams tool.response, model.message plus deltas, and a final turn.done. Each event is annotated with its JSON payload."
+ alt="Sequence diagram of the support-bot session across three turns. Turn 1 streams tool calls and a reply; Turn 2 pauses for approval; Turn 3 resumes with the approval and streams the confirmation."
/>
</Frame>
@@ -297,33 +297,11 @@ sequenceDiagram
A separate issue — Bob's shipping question, or even Jane's next problem — runs in its own session, where Turn 1 starts fresh with no refund history carried over.
-## Run it
+## Run it with the SDK
### 1. Create a session
-Pass an inline agent spec (`{ "spec": ... }`), or reference a saved agent by name (`{ "name": "..." }`):
-
-<Tabs>
-<Tab title="curl">
-
-```bash
-curl -X POST http://localhost:8790/api/v1/sessions \
- -H 'Content-Type: application/json' \
- -d '{
- "agent": {
- "spec": {
- "model": { "name": "anthropic/claude-sonnet-4-6" },
- "instructions": "You help customers with orders. Always confirm before processing refunds.",
- "mcp_servers": [
- { "name": "orders-api", "require_approval_for_tools": ["process_refund"] }
- ]
- }
- }
- }'
-```
-
-</Tab>
-<Tab title="TypeScript">
+Pass an inline agent spec, or reference a saved agent by name:
```typescript
import { TrueForge } from 'trueforge-sdk';
@@ -341,27 +319,8 @@ const { data: session } = await client.sessions.create({
});
```
-</Tab>
-</Tabs>
-
### 2. Run a turn and stream events
-<Tabs>
-<Tab title="curl">
-
-```bash
-curl -N -X POST http://localhost:8790/api/v1/sessions/sess-7f2a9c1b/turns \
- -H 'Content-Type: application/json' \
- -d '{
- "input": [
- { "type": "user.message", "content": "What is the status of order ORD-2031?" }
- ]
- }'
-```
-
-</Tab>
-<Tab title="TypeScript">
-
```typescript
const stream = await client.sessions.createTurnStream(session.id, {
input: [{ type: 'user.message', content: 'What is the status of order ORD-2031?' }],
@@ -381,22 +340,19 @@ for await (const { data: event } of stream.withMetadata()) {
See [Use an agent](/api/use-agent) for delta merging, approvals, reconnects, and more.
-</Tab>
-</Tabs>
-
-The `input` field accepts three item types:
+Turn `input` accepts three item types:
| `type` | Purpose |
| -------------------- | ------------------------------------------------------------------------------------------- |
| `user.message` | A message. `content` is a string or an array of `text` / `file` parts (files as data URIs). |
-| `user.tool_approval` | An [approval decision](/human-in-the-loop) for a paused tool call. |
-| `user.tool_response` | An [answer](/ask-user-questions) for a paused client-side tool call. |
+| `user.tool_approval` | An [approval decision](/create-agent/tool-approval) for a paused tool call. |
+| `user.tool_response` | An [answer](/create-agent/ask-user-questions) for a paused client-side tool call. |
A single turn cannot mix `user.message` items with approval or tool-response items.
### 3. Chain the next turn
-`previous_turn_id` defaults to `"auto"`, which chains to the session's last turn — you never resend history. Use `"none"` to start a fresh root turn in the same session, or pass an explicit turn id to branch from a specific point.
+Turns chain automatically to the session's last turn — you never resend history. You can also start a fresh root turn in the same session, or branch from a specific earlier turn. See [Use an agent](/api/use-agent).
### 4. Handle a pause (approvals and questions)
@@ -421,53 +377,31 @@ A single turn cannot mix `user.message` items with approval or tool-response ite
Resume with a new turn carrying the decision:
-```bash
-curl -N -X POST http://localhost:8790/api/v1/sessions/sess-7f2a9c1b/turns \
- -H 'Content-Type: application/json' \
- -d '{
- "input": [{
- "type": "user.tool_approval",
- "thread_id": "main",
- "tool_call_id": "call-refund-01",
- "approval": { "status": "allow" }
- }]
- }'
-```
+```typescript
+const resume = await client.sessions.createTurnStream(session.id, {
+ input: [
+ {
+ type: 'user.tool_approval',
+ thread_id: 'main',
+ tool_call_id: 'call-refund-01',
+ approval: { status: 'allow' },
+ },
+ ],
+});
-The same pattern applies to [`tool.response_required`](/ask-user-questions) (resume with `user.tool_response`) and [`mcp.auth_required`](/mcp-servers#in-chat-authentication) (resume after the user completes OAuth).
+for await (const { data: event } of resume) {
+ // stream confirmation…
+}
+```
-## Non-streaming, reconnects, and cancellation
+The same pattern applies to [`tool.response_required`](/create-agent/ask-user-questions) (resume with `user.tool_response`) and [`mcp.auth_required`](/mcp-servers#in-chat-authentication) (resume after the user completes OAuth).
-**Fire and poll.** Pass `"stream": false` to `POST .../turns` to get the running turn back immediately, then poll `GET .../turns/{turn_id}` until `state.status` is terminal.
+## Reconnects, cancel, and history
-**Reconnect to a live turn.** If your SSE connection drops, resume from where you left off — pass the last sequence number you saw (the SSE `id:` field) as `after_sequence_number` or a `Last-Event-Id` header:
+These are covered with SDK examples in [Use an agent](/api/use-agent):
-```text
-GET /api/v1/sessions/{session_id}/turns/{turn_id}/subscribe?after_sequence_number=N
-```
+- **Reconnect** after a dropped stream from the last sequence number you saw
+- **Cancel** a running turn on a session
+- **Replay** persisted session events (deltas already merged) to restore a conversation
-**Cancel.** `POST /api/v1/sessions/{session_id}/cancel` cancels the session's running turn. The stream ends with `turn.done` and `state.status: "cancelled"`.
-
-**Replay history.** `GET .../sessions/{session_id}/events` lists the persisted event timeline (deltas pre-merged), which is how the chat UI restores a conversation.
-
-## Endpoint summary
-
-| Method | Path | Purpose |
-| -------------- | ------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `POST` | `/api/v1/sessions` | Create a session |
-| `GET` | `/api/v1/sessions` | List sessions |
-| `GET` | `/api/v1/sessions/{id}` | Get a session |
-| `DELETE` | `/api/v1/sessions/{id}` | Delete a session and its turns/events |
-| `POST` | `/api/v1/sessions/{id}/cancel` | Cancel the running turn |
-| `GET` | `/api/v1/sessions/{id}/events` | List the session's event timeline |
-| `POST` | `/api/v1/sessions/{id}/turns` | Create and execute a turn (SSE by default) |
-| `GET` | `/api/v1/sessions/{id}/turns/{turn_id}` | Get a turn and its state |
-| `GET` | `/api/v1/sessions/{id}/turns/{turn_id}/events` | List a turn's events |
-| `GET` | `/api/v1/sessions/{id}/turns/{turn_id}/subscribe` | Reconnect to a live turn's stream |
-| `GET` | `/api/v1/sessions/{id}/turns/{turn_id}/download` | Download a sandbox file |
-| `POST` / `GET` | `/api/v1/agents` | Save / list named agents |
-| `GET` / `PUT` | `/api/v1/settings/...` | Model providers, MCP servers, skills, sandbox providers (each with a `/catalog`) |
-| `GET` | `/api/v1/models` | All models across configured providers |
-| `GET` | `/api/v1/capabilities` | Which optional capabilities are configured |
-
-The complete request/response schemas are in the interactive docs at `/api/v1/docs` on your running instance.
+For HTTP paths and OpenAPI schemas, see the **API Reference** tab.
diff --git a/docs/api/turn-events.mdx b/docs/api/turn-events.mdx
index dd5415640..ea5cc6d34 100644
--- a/docs/api/turn-events.mdx
+++ b/docs/api/turn-events.mdx
@@ -4,7 +4,7 @@ sidebarTitle: 'Turn Events'
description: 'Every event type streamed while a turn runs — lifecycle, model output, tool activity, subagent threads, and pause events.'
---
-While a turn runs, the server streams events as Server-Sent Events (SSE). Each SSE message's `data` is one JSON event; the SSE `id` field carries the per-stream **sequence number**, which you can pass back (as a `Last-Event-Id` header or the `after_sequence_number` query parameter) to the [subscribe endpoint](/api/overview#non-streaming-reconnects-and-cancellation) to resume after a disconnect.
+While a turn runs, the SDK streams events to your app. Each event is a JSON object; the stream also carries a **sequence number** you can use to [reconnect](/api/use-agent) after a disconnect without missing or double-processing events.
Every event carries:
@@ -13,9 +13,9 @@ Every event carries:
| `type` | The event type — one of the types below. |
| `id` | Unique event id (monotonic ULID — sortable by creation order). |
| `created_at` | ISO 8601 timestamp. |
-| `thread_id` | Which execution thread emitted it: `"main"` for the root agent, a generated id for [subagents](/context-engineering/subagents), or `null` for run-level events (`turn.*`, `sandbox.created`, `mcp.auth_required`). |
+| `thread_id` | Which execution thread emitted it: `"main"` for the root agent, a generated id for [subagents](/key-features/subagents), or `null` for run-level events (`turn.*`, `sandbox.created`, `mcp.auth_required`). |
-A stream always opens with `turn.created` and closes with `turn.done`. When you list persisted events afterwards (`GET .../events`), you get the same events with deltas pre-merged into their `model.message`.
+A stream always opens with `turn.created` and closes with `turn.done`. When you list persisted session events afterwards, you get the same events with deltas pre-merged into their `model.message`.
## Lifecycle events
@@ -98,7 +98,7 @@ The result of a tool the harness executed, linked to its call by `tool_call_id`:
### `tool.approval_required`
-A tool call needs [human approval](/human-in-the-loop) before it can run. The turn ends after this event; resume with a `user.tool_approval` input.
+A tool call needs [human approval](/create-agent/tool-approval) before it can run. The turn ends after this event; resume with a `user.tool_approval` input.
| Field | Description |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -106,13 +106,13 @@ A tool call needs [human approval](/human-in-the-loop) before it can run. The tu
### `tool.response_required`
-A client-side tool (e.g. [`ask_user_question`](/ask-user-questions)) needs a result from your app. Same shape as `tool.approval_required`; resume with a `user.tool_response` input.
+A client-side tool (e.g. [`ask_user_question`](/create-agent/ask-user-questions)) needs a result from your app. Same shape as `tool.approval_required`; resume with a `user.tool_response` input.
## Subagent threads
### `thread.created`
-A [subagent](/context-engineering/subagents) started. Subsequent events with this `thread_id` belong to it.
+A [subagent](/key-features/subagents) started. Subsequent events with this `thread_id` belong to it.
| Field | Description |
| ------------ | -------------------------------------------------------------------------------------- |
diff --git a/docs/api/use-agent.mdx b/docs/api/use-agent.mdx
index 8f2812014..f3b3d6cac 100644
--- a/docs/api/use-agent.mdx
+++ b/docs/api/use-agent.mdx
@@ -6,7 +6,7 @@ description: 'Run a saved agent with the TypeScript SDK — create sessions, str
This guide covers everything you need to **run** an agent with [`trueforge-sdk`](https://www.npmjs.com/package/trueforge-sdk): open a session, send turns, consume the event stream, and handle pauses, threads, and disconnects.
-For the conceptual hierarchy (Agent → Session → Turn → Event → Delta) and a short end-to-end walkthrough, see [Using the API](/api/overview). For every event field, see [Turn events](/api/turn-events).
+For the conceptual hierarchy (Agent → Session → Turn → Event → Delta) and a short end-to-end walkthrough, see [SDK Overview](/api/overview). For every event field, see [Turn events](/api/turn-events).
<Note>
Prerequisite: a named agent in the registry, or an inline [agent spec](/api/agent-spec) you pass when creating the session. The quickest path to a named agent is the [Quickstart](/quickstart) UI.
@@ -378,7 +378,7 @@ rl.close();
### Handle tool approvals
-When a tool call is configured to require [human approval](/human-in-the-loop), the agent emits a [`tool.approval_required`](/api/turn-events#tool-approval-required) event and the turn ends. Each event carries a `threadId` and the `toolCalls` awaiting a decision — a single turn can emit more than one (for example, when parallel threads each call a gated tool), so collect all of them. Resume by creating a new turn with one `user.tool_approval` item per pending tool call — allow it, or deny it with an optional reason.
+When a tool call is configured to require [human approval](/create-agent/tool-approval), the agent emits a [`tool.approval_required`](/api/turn-events#tool-approval-required) event and the turn ends. Each event carries a `threadId` and the `toolCalls` awaiting a decision — a single turn can emit more than one (for example, when parallel threads each call a gated tool), so collect all of them. Resume by creating a new turn with one `user.tool_approval` item per pending tool call — allow it, or deny it with an optional reason.
Each pending tool-call ref carries the `sourceEventId` of the [`model.message`](/api/turn-events#model-message) that emitted the tool call. Keep the same `id`-keyed [event index](#handling-event-delta-while-streaming) you build while streaming, then look up `events.get(sourceEventId)` to read the tool's name and arguments.
@@ -447,7 +447,7 @@ rl.close();
### Answer agent questions
-When the agent needs input it cannot safely assume, it can ask the user a structured question via the built-in client-side [`ask_user_question`](/ask-user-questions) tool. Since the tool runs on your side, the agent emits a [`tool.response_required`](/api/turn-events#tool-response-required) event and the turn ends. The pending tool call's `arguments` carry the `question` and its `options`. Collect the user's answer and resume by creating a new turn with one `user.tool_response` item per pending tool call.
+When the agent needs input it cannot safely assume, it can ask the user a structured question via the built-in client-side [`ask_user_question`](/create-agent/ask-user-questions) tool. Since the tool runs on your side, the agent emits a [`tool.response_required`](/api/turn-events#tool-response-required) event and the turn ends. The pending tool call's `arguments` carry the `question` and its `options`. Collect the user's answer and resume by creating a new turn with one `user.tool_response` item per pending tool call.
```typescript
import { createInterface } from 'node:readline/promises';
@@ -654,7 +654,7 @@ if (turn.state.status === 'running') {
### Handle threads
-A single turn stream interleaves events from the root agent and any [subagents](/context-engineering/subagents) that run in parallel. Every event carries a `threadId`:
+A single turn stream interleaves events from the root agent and any [subagents](/key-features/subagents) that run in parallel. Every event carries a `threadId`:
- `"main"` — the root agent.
- A unique id — a subagent thread. [`thread.created`](/api/turn-events#thread-created) and [`thread.done`](/api/turn-events#thread-done) mark subagent thread lifecycle; they are not emitted for the main thread.
diff --git a/docs/ask-user-questions.mdx b/docs/ask-user-questions.mdx
deleted file mode 100644
index 0cd688dcc..000000000
--- a/docs/ask-user-questions.mdx
+++ /dev/null
@@ -1,106 +0,0 @@
----
-title: 'Ask User Questions'
-sidebarTitle: 'Ask User Questions'
-description: 'Let the agent ask structured multiple-choice questions and pause until the user answers.'
----
-
-Agents often hit decision points where they cannot make a safe assumption — which environment to deploy to, which of three matching resources the user meant, what an ambiguous required field should be set to. Without a way to ask, the agent either guesses (and gets it wrong) or stalls with a free-form question the UI cannot render as a first-class action.
-
-Ask User Questions lets the harness pause the agent, surface a structured multiple-choice prompt to the user, and resume the run with the chosen answer. It is **enabled by default**.
-
-## How it works
-
-TrueForge registers `ask_user_question` as a **client-side tool** — the server never executes it. When the agent calls it, the harness emits `tool.response_required`, finishes the turn (with the pending question in `state.required_actions`), and waits for your application to collect the user's choice and resume with a new turn containing a `user.tool_response` input.
-
-```mermaid
-sequenceDiagram
- participant User
- participant Client
- participant Harness as TrueForge
- participant Model
-
- User->>Client: Send message
- Client->>Harness: POST /turns
- Harness->>Model: LLM call
- rect rgba(255, 237, 153, 0.45)
- Model->>Harness: Tool call: ask_user_question
- Harness-->>Client: tool.response_required (turn ends)
- end
- Client->>User: Show question + options
- User->>Client: Pick an option
- rect rgba(255, 237, 153, 0.45)
- Client->>Harness: POST /turns (user.tool_response)
- Harness->>Model: Tool response
- end
-```
-
-The user selects one of the listed options or types a free-form answer. The agent receives the response as a regular tool result and continues from where it paused. The bundled chat UI renders questions and options natively.
-
-<Frame caption="The chat UI renders the question and its options as a selectable card.">
- <img src="/images/ask-user-questions.png" alt="The chat UI showing an agent question with multiple-choice options and a Submit button" />
-</Frame>
-
-<Note>
- Only the root agent can call `ask_user_question`. [Subagents](/context-engineering/subagents) must resolve ambiguity
- from the context the root agent provides them.
-</Note>
-
-## Example
-
-A user asks the agent to _"create a new environment called `testing-1`"_, but the underlying tool requires fields the user never specified. Instead of inventing values, the agent asks:
-
-```json ask_user_question — tool call
-{
- "question": "Should this environment be a production environment?",
- "options": ["Yes — mark it as Production", "No — keep it as Non-production"]
-}
-```
-
-Once the user answers, the agent asks the next required field or proceeds to the actual tool call — turning an ambiguous request into a deterministic, auditable sequence of decisions.
-
-## Handling questions from the API
-
-The `tool.response_required` event references the pending tool call:
-
-```json
-{
- "type": "tool.response_required",
- "thread_id": "main",
- "tool_calls": [{ "id": "call-q-01", "source_event_id": "msg-a4" }]
-}
-```
-
-The question and options are in the tool call's arguments on the referenced `model.message` event (`source_event_id`). Resume with the answer:
-
-```json
-{
- "input": [
- {
- "type": "user.tool_response",
- "thread_id": "main",
- "tool_call_id": "call-q-01",
- "content": "No — keep it as Non-production"
- }
- ]
-}
-```
-
-Turns in the same session chain automatically (`previous_turn_id` defaults to `"auto"`), so the agent picks up exactly where it paused.
-
-## When to use it
-
-Use `ask_user_question` when the agent genuinely cannot proceed without a user decision and the answer comes from a small, enumerable set:
-
-- Choosing a target environment, cluster, account, or workspace
-- Disambiguating between multiple matches ("I found 3 services named `api`, which one?")
-- Resolving required tool-call fields the user did not specify (booleans, enums, modes)
-- Picking between alternative strategies before a destructive or expensive operation
-
-<Note>
- Skip it for decisions the agent can confidently infer from context, conversation history, or sensible defaults. Asking
- too often turns the agent into a form and breaks autonomy.
-</Note>
-
-## Disabling
-
-Set `config.ask_user_questions.enabled: false` on the agent. See [`config.ask_user_questions`](/api/agent-spec#config) in the agent spec reference.
diff --git a/docs/authentication/okta.mdx b/docs/authentication/okta.mdx
index 30d26bdf7..87315ba1d 100644
--- a/docs/authentication/okta.mdx
+++ b/docs/authentication/okta.mdx
@@ -1,10 +1,10 @@
---
title: 'Okta'
sidebarTitle: 'Okta'
-description: 'Configure Okta as the OIDC identity provider for TrueForge.'
+description: 'Step-by-step: configure Okta as the OIDC identity provider for TrueForge.'
---
-See [Authentication](/authentication/overview) for shared OIDC concepts, roles, and Helm patterns. This page covers Okta-specific setup.
+Use this after reading the [Setup Login overview](/authentication/overview). Below is Okta-specific setup only.
## Create the app
diff --git a/docs/authentication/overview.mdx b/docs/authentication/overview.mdx
index d6390a880..2da6ba620 100644
--- a/docs/authentication/overview.mdx
+++ b/docs/authentication/overview.mdx
@@ -1,155 +1,85 @@
---
-title: 'Authentication'
+title: 'Setup Login'
sidebarTitle: 'Overview'
-description: 'OIDC login with identity providers, admin vs user roles, Bearer tokens for the SDK, and what happens when auth is disabled.'
+description: 'Turn on OIDC login for shared deployments — or keep the no-auth default for local use.'
---
-TrueForge authentication is optional and identity-provider–driven. When OIDC is configured, every protected API call must present a valid ID token (browser cookie or `Authorization: Bearer`). When it is not, the server runs with a fixed local admin identity — useful for local mode and trusted networks, not for shared production.
+TrueForge authentication is optional. For local use you can leave it off. For a shared team deployment, turn on OIDC so people sign in with your identity provider and Settings stay admin-only.
-## Modes at a glance
+## Choose your mode
-| Mode | When | Who you are | API access |
-| ---- | ---- | ----------- | ---------- |
-| **No OIDC** | `OIDC_*` unset (or standalone / local mode) | Fixed user `trueforge-default` with role `admin` | No login required |
-| **OIDC enabled** | `OIDC_ISSUER_URL`, `OIDC_CLIENT_ID`, and `OIDC_CLIENT_SECRET` all set | Claim-mapped `userRef` + `admin` or `user` | Cookie or Bearer ID token required |
+| Mode | When to use | What users see |
+| --- | --- | --- |
+| **No login** | Local `npx`, trusted networks | No login screen; everyone is a fixed local admin |
+| **OIDC login** | Hosted / shared teams | Sign-in with your IdP; roles `admin` or `user` |
-All OIDC variables must be set together, or all left unset. Partial configuration fails startup.
+Standalone / local mode ignores OIDC even if env vars are present.
-Standalone / local mode (`STANDALONE=true`) ignores OIDC even if env vars are present.
+## Guide: leave auth off (local)
-## No auth
+1. Do **not** set `OIDC_ISSUER_URL`, `OIDC_CLIENT_ID`, or `OIDC_CLIENT_SECRET`.
+2. Run TrueForge as usual ([Quickstart](/quickstart)).
+3. Open the UI — there is no login screen. Settings and chat are available immediately.
-This is the default for local development and for hosted deploys that never set `OIDC_*`.
+Use this only on localhost or behind network controls you trust. On a public host, anyone who can reach the server gets admin Settings access under one shared identity.
-- There is **no login screen**. The UI and API treat every caller as the same identity.
-- That identity is **`trueforge-default`** with role **`admin`**.
-- Settings (model providers, MCP servers, skills, sandbox) are open to anyone who can reach the server.
-- Session ownership still uses `created_by`, but every request shares the same `userRef`, so there is no per-person isolation.
+## Guide: enable OIDC for your team
-Use this only on localhost or behind network controls you trust. For a shared team deployment, enable OIDC.
+### 1. Prepare your identity provider
-## Enabling OIDC
+Create a **confidential (Web)** OIDC app with:
-Set on the server (env, Compose `.env`, or Helm `server.extraEnv`):
+- Grant type **Authorization Code** (PKCE is also used)
+- Redirect URI: `{PUBLIC_BASE_URL}/api/v1/auth/callback`
+- Users/groups allowed to sign in
+- ID token claims for identity and admin membership (see below)
-| Variable | Required | Default | Purpose |
-| -------- | -------- | ------- | ------- |
-| `OIDC_ISSUER_URL` | yes* | — | IdP issuer (discovery at `/.well-known/openid-configuration`) |
-| `OIDC_CLIENT_ID` | yes* | — | OIDC client ID |
-| `OIDC_CLIENT_SECRET` | yes* | — | OIDC client secret (confidential / Web client) |
-| `PUBLIC_BASE_URL` | yes | — | Public origin used to build the callback URL |
-| `OIDC_USER_REFERENCE_CLAIM` | no | `sub` | Claim used as `userRef` (session ownership) |
-| `OIDC_USER_ROLE_CLAIM` | no | `groups` | Claim inspected for admin membership |
-| `OIDC_ADMIN_ROLE_VALUE` | no | `admin` | Exact string that grants `admin` (case-sensitive) |
-| `OIDC_SCOPES` | no | `openid,profile,email` | Comma-separated scopes for the authorize request |
+Public / SPA clients are not supported — TrueForge needs a client secret.
-\*Required only when enabling OIDC; otherwise leave all three unset.
+Provider-specific steps: [Okta](/authentication/okta).
-Also set `PUBLIC_BASE_URL` to the origin users and the IdP see, for example `https://trueforge.example.com` (no trailing path). In Helm that is the first-class value `server.publicBaseUrl`. The redirect URI registered with the IdP must be:
+### 2. Set server environment
-```text
-{PUBLIC_BASE_URL}/api/v1/auth/callback
-```
+Set all three OIDC variables together (partial config fails startup), plus the public origin:
-OIDC env vars are not first-class Helm values yet — pass them through `server.extraEnv` or `server.extraEnvFrom`, and keep the client secret in a Kubernetes Secret (for example via `extraObjects`).
+| Variable | Required | Purpose |
+| --- | --- | --- |
+| `PUBLIC_BASE_URL` | yes | Public origin users and the IdP see (no trailing path) |
+| `OIDC_ISSUER_URL` | yes* | IdP issuer (discovery at `/.well-known/openid-configuration`) |
+| `OIDC_CLIENT_ID` | yes* | OIDC client ID |
+| `OIDC_CLIENT_SECRET` | yes* | OIDC client secret |
+| `OIDC_USER_REFERENCE_CLAIM` | no (default `sub`) | Claim used as the user id for session ownership |
+| `OIDC_USER_ROLE_CLAIM` | no (default `groups`) | Claim inspected for admin membership |
+| `OIDC_ADMIN_ROLE_VALUE` | no (default `admin`) | Exact string that grants `admin` (case-sensitive) |
+| `OIDC_SCOPES` | no (default `openid,profile,email`) | Scopes for the authorize request |
-### How credentials are sent
+\*Required when enabling OIDC; otherwise leave all three unset.
-The UI stores the ID token in an HttpOnly `id_token` cookie after login. `POST /api/v1/auth/logout` clears that cookie (local logout only — no IdP end-session redirect). `GET /api/v1/auth/me` returns the mapped identity.
+In Helm, set `server.publicBaseUrl` and pass `OIDC_*` through `server.extraEnv` / `server.extraEnvFrom`. Keep the client secret in a Kubernetes Secret.
-Login requests the reference and role claims as **essential** in the ID token. If the IdP cannot produce them, login fails instead of silently treating the user as non-admin.
+### 3. Map admin vs user
-### API and SDK (Bearer)
+| Role | Who | What they can do |
+| --- | --- | --- |
+| **admin** | Role claim contains `OIDC_ADMIN_ROLE_VALUE` | Chat + change Settings (models, connectors, skills, sandbox) |
+| **user** | Everyone else who can sign in | Chat and use agents; Settings hidden |
-The same ID token is also accepted as:
+Session history is still owner-only — admins are not global session superusers today. The [Agent Library](/agent-library) is currently shared: agents created by anyone are visible to everyone on the instance.
-```http
-Authorization: Bearer <id_token>
-```
+### 4. Sign in and verify
-If both a Bearer token and the cookie are present, **Bearer wins**.
+1. Open the UI — you should get the IdP login.
+2. After login, confirm admins see **Settings** and non-admins do not.
+3. If someone expected admin but got user, decode their ID token and check the role claim value (exact, case-sensitive). Sign out and back in after IdP claim changes.
-TypeScript SDK example:
+### 5. Call the API with a token (optional)
-```typescript
-import { TrueForge } from "trueforge-sdk";
+The UI stores an HttpOnly cookie after login. For the [SDK](/api/overview), send the same ID token as `Authorization: Bearer <id_token>`. Obtain the token from your IdP (or reuse a browser session); there is no device/client-credentials flow yet.
-const client = new TrueForge({
- baseUrl: "https://trueforge.example.com",
- headers: {
- Authorization: `Bearer ${idToken}`,
- },
-});
-```
+Keep ID token lifetimes short at the IdP — the same JWT unlocks the API as cookie or Bearer.
-There is no first-class device/client-credentials flow yet. Callers must obtain an ID token from the IdP (or reuse one from a browser session). Refresh is the caller's responsibility.
+## Security checklist
-<Warning>
- Keep ID token lifetimes short at the IdP (minutes, not days). The same JWT unlocks the API whether it arrives as a cookie or `Authorization: Bearer`, so a long-lived token is a long-lived credential.
-</Warning>
-
-## Roles: admin vs user
-
-Every authenticated principal is mapped to:
-
-```ts
-{ userRef: string; role: "admin" | "user" }
-```
-
-- **`userRef`** — from `OIDC_USER_REFERENCE_CLAIM` (default `sub`). Used as `created_by` on sessions and for ownership checks.
-- **`role`** — `admin` if the role claim’s values **include** `OIDC_ADMIN_ROLE_VALUE` (exact, case-sensitive); otherwise `user`.
-
-The role claim may be a string or an array of strings (typical for Okta `groups`).
-
-### What each role can do
-
-| Capability | `admin` | `user` |
-| ---------- | ------- | ------ |
-| Chat, sessions, turns, agents, models list, MCP authorize (user flows) | yes | yes |
-| See / change **Settings** (`/api/v1/settings/*` — providers, connectors, skills, sandbox) | yes | no |
-| Access another user’s sessions | no | no |
-
-Admins are **not** global session superusers today: session read/update/delete is still owner-only. The UI hides Settings for non-admins.
-
-Without OIDC, `isAdmin` is always true (the fixed local identity is admin), so settings stay available.
-
-## Identity providers
-
-TrueForge speaks standard OIDC (authorization code + PKCE) against any IdP that issues ID tokens. Provider-specific setup differs; the server only needs a working issuer, confidential client, redirect URI, and the claims you map for `userRef` / admin.
-
-**Common requirements for any IdP:**
-
-- **Confidential (Web) client** with a client secret — public/SPA clients are not supported
-- Grant type **Authorization Code** (server also sends PKCE)
-- Redirect URI `{PUBLIC_BASE_URL}/api/v1/auth/callback`
-- ID token includes the reference claim and role claim you configured (requested as essential at login)
-- Users who should sign in are assigned / allowed by the IdP
-
-Provider guides:
-
-- [Okta](/authentication/okta)
-
-### Verify
-
-After login with any provider:
-
-```bash
-curl -s -H "Cookie: id_token=..." https://trueforge.example.com/api/v1/auth/me
-# or
-curl -s -H "Authorization: Bearer ..." https://trueforge.example.com/api/v1/auth/me
-```
-
-Expected shape:
-
-```json
-{ "type": "oidc-connected", "email": "[email protected]", "role": "admin" }
-```
-
-(`email` here is the mapped `userRef` from `OIDC_USER_REFERENCE_CLAIM`.)
-
-If `role` is `user` but you expect admin, decode the ID token and confirm the role claim contains exactly `OIDC_ADMIN_ROLE_VALUE`. Re-login after changing IdP claims; an old cookie will not pick up new claims.
-
-## Security notes
-
-- Prefer Kubernetes Secrets (or `extraObjects` Secret) for `OIDC_CLIENT_SECRET`; avoid committing secrets in values files when you can.
-- Disabling OIDC on a publicly reachable host effectively grants every caller admin settings access under one shared identity.
+- Prefer secrets storage for `OIDC_CLIENT_SECRET`; do not commit it.
+- Do not expose a no-OIDC deployment on the public internet.
+- Register the exact callback URL your users hit (scheme + host).
diff --git a/docs/evaluation.mdx b/docs/benchmarking.mdx
similarity index 93%
rename from docs/evaluation.mdx
rename to docs/benchmarking.mdx
index ad2fb4ebd..5ac7ca01c 100644
--- a/docs/evaluation.mdx
+++ b/docs/benchmarking.mdx
@@ -1,6 +1,6 @@
---
-title: 'Evaluation'
-sidebarTitle: 'Evaluation'
+title: 'Benchmarking'
+sidebarTitle: 'Benchmarking'
description: 'How TrueForge compares to Claude Managed Agents and deepagents on the same tasks, tools, and model — and how to reproduce it.'
---
@@ -67,7 +67,7 @@ Most of the cost in an agent run is the loop, not the final answer — every too
- **Leaner context each turn.** It drives from a compact instruction rather than heavy scaffolding; deepagents also carries planning, a virtual filesystem, and sub-agent machinery on every turn.
- **Fewer tool calls.** It planned the fewest calls of the three to reach the same result — 19 per task, versus 32 and 40.
-- **[Compaction](/context-engineering/overview) instead of replay.** It trims history and [offloads large tool responses](/context-engineering/large-tool-responses) instead of re-sending everything verbatim; deepagents re-reads its accumulated context step after step, which is how it lands at three to four times the tokens for the same task.
+- **[Compaction](/key-features/overview#context-compaction) instead of replay.** It trims history and [offloads large tool responses](/key-features/large-tool-responses) instead of re-sending everything verbatim; deepagents re-reads its accumulated context step after step, which is how it lands at three to four times the tokens for the same task.
## Reproduce it
diff --git a/docs/chat-ui.mdx b/docs/chat-ui.mdx
new file mode 100644
index 000000000..6ba05cbb4
--- /dev/null
+++ b/docs/chat-ui.mdx
@@ -0,0 +1,50 @@
+---
+title: 'Chat UI'
+sidebarTitle: 'Chat UI'
+description: 'Use the bundled TrueForge chat experience — or embed the same UI in your app with the React UI SDK.'
+---
+
+TrueForge ships a full chat UI with the server: browse agents, stream responses, approve tools, connect MCP OAuth, and manage Settings. The same experience is published as `@truefoundry/trueforge-ui` so you can embed it in your own React app.
+
+## Bundled UI
+
+When you run TrueForge ([Quickstart](/quickstart)), open the app URL (for example `http://localhost:8790`). You get:
+
+- Agent composer and [Agent Library](/agent-library)
+- Streaming chat with tool calls, approvals, and ask-user-questions
+- Settings for [models](/models), [connectors](/mcp-servers), [skills](/skills), and [sandbox](/sandbox)
+- [Generative UI](/create-agent/generative-ui) rendering out of the box
+
+<Frame caption="The bundled chat UI — streaming responses and agent steps.">
+ <img src="/images/getting-started-chat.png" alt="TrueForge chat UI with agent response and tool calls" />
+</Frame>
+
+## Embed with the UI SDK
+
+Install and render a single component against your TrueForge server (or a compatible custom server):
+
+```bash
+npm install @truefoundry/trueforge-ui
+```
+
+```tsx
+import { TrueforgeUI } from '@truefoundry/trueforge-ui';
+
+export function App() {
+ return <TrueforgeUI server={{ type: 'trueforge', baseUrl: 'http://localhost:8790' }} />;
+}
+```
+
+Interactive playground and generated snippets: [ui.trueforge.dev](https://ui.trueforge.dev/).
+
+## What you can customize
+
+| Area | Options |
+| --- | --- |
+| **Agent modes** | Chat with one agent, browse the library, or let users compose agents |
+| **Layouts** | `sidebar` (default), `drawer`, `dock`, `widget` |
+| **Themes** | Built-in Claude, ChatGPT, Gemini, TrueFoundry — or your own theme |
+| **Slots** | Override individual UI regions without forking the whole app |
+| **Server** | TrueForge server, TrueFoundry-backed, or a custom server that implements the contract |
+
+Deep dives, API reference, and advanced guides live in the **UI SDK** tab of these docs.
diff --git a/docs/create-agent/ask-user-questions.mdx b/docs/create-agent/ask-user-questions.mdx
new file mode 100644
index 000000000..972c3bbcf
--- /dev/null
+++ b/docs/create-agent/ask-user-questions.mdx
@@ -0,0 +1,33 @@
+---
+title: 'Configure Ask User Questions'
+sidebarTitle: 'Ask User Questions'
+description: 'Let the agent ask structured multiple-choice questions and pause until the user answers.'
+---
+
+Agents often hit decision points they should not guess — which environment to deploy to, which of several matches the user meant, or what an ambiguous required field should be. **Ask User Questions** pauses the agent, shows a multiple-choice prompt, and resumes with the chosen answer.
+
+It is **enabled by default**.
+
+## Configuring
+
+<Note>
+ Enabling or disabling Ask User Questions (`config.ask_user_questions`) is configured via the **API / SDK** today. The
+ chat UI already renders questions and collects answers. See the [agent spec](/api/agent-spec#config).
+</Note>
+
+## How it feels in chat
+
+The agent asks a structured question with options. The user picks one (or types a free-form answer). The agent continues from where it paused.
+
+<Frame caption="The chat UI renders the question and options as a selectable card.">
+ <img src="/images/ask-user-questions.png" alt="Chat UI showing an agent question with multiple-choice options" />
+</Frame>
+
+## When to use it
+
+- Choosing a target environment, cluster, account, or workspace
+- Disambiguating multiple matches ("I found 3 services named `api` — which one?")
+- Filling required fields the user did not specify
+- Picking a strategy before a destructive or expensive step
+
+Skip it when the agent can confidently infer the answer from context — over-asking turns the agent into a form.
diff --git a/docs/create-agent/generative-ui.mdx b/docs/create-agent/generative-ui.mdx
new file mode 100644
index 000000000..3c138df89
--- /dev/null
+++ b/docs/create-agent/generative-ui.mdx
@@ -0,0 +1,36 @@
+---
+title: 'Configure Generative UI'
+sidebarTitle: 'Generative UI'
+description: 'Let the agent respond with interactive charts, tables, cards, and forms instead of plain text.'
+---
+
+Plain text works for short answers. For dashboards, comparisons, and structured data, **Generative UI** lets the agent stream interactive components — charts, tables, cards, forms — that the chat UI renders as React.
+
+It is **enabled by default**, and the bundled chat UI renders it out of the box.
+
+## Configuring
+
+<Note>
+ Enabling or disabling Generative UI (`config.generative_ui`) is configured via the **API / SDK** today. Runtime
+ rendering in the chat UI works without extra setup when the feature is enabled. See the
+ [agent spec](/api/agent-spec#config).
+</Note>
+
+## How it works
+
+The agent embeds a small OpenUI snippet in its normal response. The client detects it and renders real components as tokens stream in — no arbitrary code execution; only registered components can appear.
+
+<Frame caption="A Generative UI dashboard with summary cards, a chart, and a table.">
+ <img src="/images/generative-ui.png" alt="Rendered Generative UI dashboard with cards, chart, and table" />
+</Frame>
+
+## When to use it
+
+| Use case | What the agent renders |
+| --- | --- |
+| Dashboards | KPI cards, charts, comparison tables |
+| Tables | Sortable logs, resources, result sets |
+| Charts | Bar, line, pie patterns faster than prose |
+| Forms | Guided inputs for the next action |
+
+Skip it for short explanations, bullet lists, or code blocks where markdown is enough.
diff --git a/docs/create-agent/overview.mdx b/docs/create-agent/overview.mdx
new file mode 100644
index 000000000..b21f38620
--- /dev/null
+++ b/docs/create-agent/overview.mdx
@@ -0,0 +1,50 @@
+---
+title: 'Create an Agent'
+sidebarTitle: 'Select resources'
+description: 'Pick a model, attach MCP servers and skills, write instructions, and save a reusable agent.'
+---
+
+After [initial setup](/harness/initial-setup), build an agent in the chat UI composer (or via the [SDK](/api/overview)).
+
+An agent is a saved combination of:
+
+1. **Model** — which LLM runs the loop
+2. **MCP servers** — which tools it can call
+3. **Skills** — which procedures it can load
+4. **Instructions** — the system prompt for this agent's role
+5. **Optional config** — sandbox, tool approvals, ask-user-questions, generative UI
+
+## In the UI
+
+1. Open TrueForge and use the composer to create or edit an agent.
+2. **Select a model** from the providers you configured under Settings → Models.
+3. **Attach connectors** (MCP servers) the agent should use. Prefer only the servers it needs.
+4. **Attach skills** if the agent should follow specialized procedures (requires [sandbox](/sandbox) enabled on the agent).
+5. Write focused **instructions** — role, audience, and behavior. Put long playbooks in skills, not the prompt.
+6. **Save** the agent so it appears in the [Agent Library](/agent-library).
+
+<Frame caption="Save a reusable agent from the composer.">
+ <img src="/images/quickstart-save-agent.png" alt="Save agent dialog in the TrueForge composer" />
+</Frame>
+
+## Selecting models, MCP servers, and skills
+
+| Resource | What you choose | Tips |
+| --- | --- | --- |
+| Model | One model from configured providers | Switch anytime without changing credentials |
+| MCP servers | Zero or more connectors by name | Smaller tool surface → better tool-call quality |
+| Skills | Zero or more registered skills by name | Enable sandbox when attaching skills |
+
+Switching the model is a one-click (or one-field) change. No new API keys in the agent definition.
+
+## Related configuration
+
+These knobs are available on the agent today primarily through the **API / SDK** (not yet fully exposed in the builder UI):
+
+| Capability | Default | Docs |
+| --- | --- | --- |
+| [Tool approval](/create-agent/tool-approval) | Write/destructive tools pause for approval | Configure which tools require confirmation |
+| [Ask User Questions](/create-agent/ask-user-questions) | Enabled | Let the agent ask structured multiple-choice questions |
+| [Generative UI](/create-agent/generative-ui) | Enabled | Let the agent render charts, tables, and cards |
+
+For the full field list, see the [agent spec](/api/agent-spec) in the SDK section.
diff --git a/docs/create-agent/tool-approval.mdx b/docs/create-agent/tool-approval.mdx
new file mode 100644
index 000000000..419bd3b5d
--- /dev/null
+++ b/docs/create-agent/tool-approval.mdx
@@ -0,0 +1,33 @@
+---
+title: 'Configure Tool Approval'
+sidebarTitle: 'Tool approval'
+description: 'Pause sensitive MCP tool calls so the user can approve or deny before they run.'
+---
+
+Some actions — deploying, deleting data, sending refunds — should not run without explicit consent. **Tool approval** (human in the loop) pauses the agent before a sensitive MCP tool call, shows the tool name and arguments, and resumes only after the user approves or denies.
+
+Safe read-only tools stay autonomous. Write and destructive tools get a checkpoint.
+
+## Configuring which tools require approval
+
+<Note>
+ Today, configuring `require_approval_for_tools` (and related enable/disable tool lists) is done via the **API / SDK**
+ when you create or update an agent. The chat UI already handles the Approve / Deny experience at runtime, but the
+ builder does not yet expose the full approval policy editor. See the [agent spec](/api/agent-spec#mcp_servers).
+</Note>
+
+Approval policy is set **per MCP server** on the agent. The default is write and destructive tools — any tool the MCP server does not mark as read-only, or marks as destructive. You can also list specific tool names, or gate every tool.
+
+## How it feels in chat
+
+When a gated tool is requested, the bundled chat UI pauses the run and shows **Approve / Deny** with the request payload. Approve to execute; deny to return a reason to the agent so it can adjust its plan.
+
+<Frame caption="The chat UI pauses on a sensitive tool call with Approve / Deny.">
+ <img src="/images/hitl.png" alt="Chat UI pausing on a tool call with Approve and Deny buttons" />
+</Frame>
+
+## When to use approvals
+
+Use them for state changes, irreversible actions, production impact, external communications, or expensive operations. Skip them for safe reads (list, fetch, search) where confirmation only adds friction.
+
+Approvals do not replace authorization — the user still needs access to the underlying tool; approval only decides whether this pending call should proceed.
diff --git a/docs/docs.json b/docs/docs.json
index 4f0626830..461463fb6 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -33,42 +33,50 @@
"groups": [
{
"group": "Getting Started",
- "pages": [
- "introduction",
- "quickstart",
- {
- "group": "Authentication",
- "pages": ["authentication/overview", "authentication/okta"]
- },
- "evaluation"
- ]
+ "pages": ["introduction", "quickstart"]
},
{
- "group": "Capabilities",
+ "group": "TrueForge Harness",
"pages": [
- "models",
- "mcp-servers",
- "skills",
- "sandbox",
{
- "group": "Context Engineering",
+ "group": "Initial Setup",
+ "pages": ["harness/initial-setup", "models", "mcp-servers", "skills", "sandbox"]
+ },
+ {
+ "group": "Create an Agent",
"pages": [
- "context-engineering/overview",
- "context-engineering/subagents",
- "context-engineering/deferred-tool-loading",
- "context-engineering/code-mode",
- "context-engineering/large-tool-responses"
+ "create-agent/overview",
+ "create-agent/tool-approval",
+ "create-agent/ask-user-questions",
+ "create-agent/generative-ui"
]
},
- "human-in-the-loop",
- "ask-user-questions",
- "generative-ui"
+ "agent-library",
+ {
+ "group": "Key Features",
+ "pages": [
+ "key-features/overview",
+ "key-features/subagents",
+ "key-features/deferred-tool-loading",
+ "key-features/code-mode",
+ "key-features/large-tool-responses"
+ ]
+ },
+ "benchmarking",
+ {
+ "group": "Setup Login",
+ "pages": ["authentication/overview", "authentication/okta"]
+ }
]
},
{
- "group": "API",
+ "group": "SDK",
"pages": ["api/overview", "api/use-agent", "api/agent-spec", "api/turn-events"]
},
+ {
+ "group": "Chat UI",
+ "pages": ["chat-ui"]
+ },
{
"group": "Project",
"pages": ["roadmap"]
diff --git a/docs/generative-ui.mdx b/docs/generative-ui.mdx
deleted file mode 100644
index 5182936cb..000000000
--- a/docs/generative-ui.mdx
+++ /dev/null
@@ -1,108 +0,0 @@
----
-title: 'Generative UI'
-sidebarTitle: 'Generative UI'
-description: 'Let the agent respond with rich, interactive components — charts, tables, cards, forms — instead of plain text.'
----
-
-Plain text and markdown work for short answers, but they fall flat the moment an agent needs to show a dashboard, compare metrics, render a sortable table, or guide a user through a form. Users end up squinting at walls of numbers when a single chart would have told the story in seconds.
-
-**Generative UI** lets your agent respond with real, interactive components — charts, tables, cards, forms, layouts — that the client renders as actual React UI. The agent decides _what_ to show; the harness ships it in a standard format your renderer turns into pixels. It is **enabled by default**, and the bundled chat UI renders it out of the box.
-
-## How it works
-
-Generative UI is **not** a separate tool call. The agent writes a small, streaming-friendly snippet inside its normal assistant message, and the client renders it on the fly as tokens arrive.
-
-Under the hood, this uses [OpenUI](https://www.openui.com/) — an open standard for agent-generated UI:
-
-- **OpenUI Lang** — a compact, streaming-first language for describing UI, far more token-efficient than equivalent JSON.
-- **Component library** — built-in charts, tables, forms, cards, and layouts, extensible with your own design system.
-- **Streaming renderer** — parses and renders UI progressively in React as the response streams in.
-- **Safe by default** — no arbitrary code execution. The agent can only emit components the renderer has registered.
-
-When `config.generative_ui.enabled` is true, the harness exposes the OpenUI authoring instructions to the agent (loaded on demand via a `get_openui_instructions` tool, so they cost no context until the agent decides to render UI). The stream uses normal [`model.message`](/api/turn-events#model-message) events and deltas — the only difference is that some message content contains an ` ```openui ` fenced block that the client extracts and renders as React components.
-
-```mermaid
-sequenceDiagram
- participant User
- participant Client
- participant Harness as TrueForge
- participant Model
-
- User->>Client: "Show me request volume by model"
- Client->>Harness: POST /turns
- Harness->>Model: LLM call (OpenUI instructions available on demand)
- Model->>Harness: Streams assistant message with an openui block
- Harness-->>Client: model.message + deltas
- Client->>Client: Detect openui fence, render with OpenUI renderer
- Client->>User: Interactive chart + table
-```
-
-## Example
-
-<Steps>
-<Step title="User" noAnchor>
- Show me a dashboard comparing request volume and error rate across my three production models.
-</Step>
-
-<Step title="Assistant" noAnchor>
- I will summarize the model traffic visually.
-
-```openui
-root = Stack([title, cards, chart, table])
-title = TextContent("Production Model Health", "large-heavy")
-cards = Stack([totalCard, errorCard], "row", "m", "stretch")
-totalCard = Card([TextContent("Total requests", "small"), TextContent("2,630", "large-heavy")])
-errorCard = Card([TextContent("Average error rate", "small"), TextContent("1.8%", "large-heavy")])
-chart = BarChart(models, [requests], "grouped", "Model", "Requests")
-table = Table([Col("Model", models), Col("Requests", requestValues, "number"), Col("Error rate", errorRates)])
-models = ["gpt-4.1", "claude-sonnet", "llama-3.1"]
-requestValues = [1240, 980, 410]
-errorRates = ["1.2%", "2.1%", "2.5%"]
-requests = Series("Requests", requestValues)
-```
-
-The highest traffic is on `gpt-4.1`, while `llama-3.1` has the highest error rate despite lower volume.
-
-</Step>
-</Steps>
-
-The renderer turns the snippet above into a full dashboard — summary cards on top, a grouped bar chart in the middle, and a sortable data table at the bottom — all real React components, not markdown.
-
-<Frame caption="The chat UI renders the OpenUI snippet as a live dashboard — summary cards, a bar chart, and a table.">
- <img src="/images/generative-ui.png" alt="A rendered Generative UI dashboard with summary cards, a grouped bar chart, and a table" />
-</Frame>
-
-## Available components
-
-The OpenUI built-in library covers the patterns most agents need:
-
-| Category | Components |
-| ---------- | --------------------------------------------- |
-| **Layout** | `Stack`, `Card`, `Tabs`, `Accordion` |
-| **Text** | `TextContent`, `Markdown` |
-| **Data** | `Table`, `Col` |
-| **Charts** | `BarChart`, `LineChart`, `PieChart`, `Series` |
-| **Input** | `TextInput`, `Select`, `Button`, `Form` |
-| **Media** | `Image`, `Link` |
-
-Building your own client? Register custom components with `defineComponent` and `createLibrary` from `@openuidev/react-lang`. The agent will only ever emit components that are registered — it cannot generate arbitrary HTML or code.
-
-## When to use it
-
-| Use case | What the agent renders |
-| ------------------- | --------------------------------------------------------------- |
-| **Dashboards** | KPI cards, charts, and tables for metrics and comparisons |
-| **Tables** | Sortable structured data — logs, resources, results to scan |
-| **Charts** | Bar, line, and pie charts that show patterns faster than prose |
-| **Cards & layouts** | Summary panels, multi-section reports, side-by-side comparisons |
-| **Forms** | Inputs, dropdowns, and selections that guide the next action |
-
-<Note>
- Skip Generative UI for simple answers where markdown is enough — a short explanation, a bullet list, a code block.
- Generative UI is also not a replacement for server-side actions: if a UI button needs to trigger a follow-up, the
- client sends that back as a normal user message in the next turn.
-</Note>
-
-## Disabling
-
-Set `config.generative_ui.enabled: false` on the agent. See [`config.generative_ui`](/api/agent-spec#config) in the agent spec reference.
diff --git a/docs/harness/initial-setup.mdx b/docs/harness/initial-setup.mdx
new file mode 100644
index 000000000..877b9328c
--- /dev/null
+++ b/docs/harness/initial-setup.mdx
@@ -0,0 +1,50 @@
+---
+title: 'Initial Setup'
+sidebarTitle: 'Overview'
+description: 'Configure models, MCP servers, skills, and a sandbox provider once — then reuse them across every agent.'
+---
+
+Before you build agents, configure the shared resources TrueForge orchestrates. You do this once in **Settings**; agents then pick from what you have connected.
+
+| Resource | Settings page | Purpose |
+| --- | --- | --- |
+| [Models](/models) | **Settings → Models** | Provider credentials and available model IDs |
+| [MCP servers](/mcp-servers) | **Settings → Connectors** | Tools and data from external systems |
+| [Skills](/skills) | **Settings → Skills** | Git-backed procedures the agent can load on demand |
+| [Sandbox](/sandbox) | **Settings → Sandbox providers** | Isolated compute for code, files, and skill execution |
+
+## What is supported out of the box
+
+Each Settings page is backed by a **shipped catalog** — a YAML file in the TrueForge server that lists presets the UI can offer:
+
+| Catalog | Source |
+| --- | --- |
+| Models | [`model-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/server/src/catalog/model-catalog.yaml) |
+| MCP servers | [`mcp-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/server/src/catalog/mcp-catalog.yaml) |
+| Skills | [`skill-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/server/src/catalog/skill-catalog.yaml) |
+| Sandbox | [`sandbox-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/server/src/catalog/sandbox-catalog.yaml) |
+
+Catalogs are discovery lists only. Choosing a preset in the UI asks you for credentials (API key, OAuth, and so on); TrueForge stores the configured resource separately. The catalog itself is never called with your secrets.
+
+You can also add entries that are **not** in a catalog — for example a custom OpenAI-compatible model endpoint, or an MCP server at any URL.
+
+## Changing what the UI offers
+
+If you self-host TrueForge and want a different preset list (add internal MCP servers, trim unused models, ship company skills), point the server at your own YAML files:
+
+| Env var | Overrides |
+| --- | --- |
+| `MODEL_CATALOG_PATH` | Model provider presets |
+| `MCP_CATALOG_PATH` | MCP server presets |
+| `SKILL_CATALOG_PATH` | Skill presets |
+| `SANDBOX_CATALOG_PATH` | Sandbox provider presets |
+
+When unset, TrueForge uses the catalogs shipped with the server.
+
+## Who can change Settings
+
+With [login / OIDC](/authentication/overview) enabled, only users with the **admin** role can open and change Settings. Everyone can still chat and use agents. Without OIDC (typical local mode), Settings are open to whoever can reach the server.
+
+## Next step
+
+Once models (and any connectors, skills, or sandbox you need) are configured, [create an agent](/create-agent/overview).
diff --git a/docs/human-in-the-loop.mdx b/docs/human-in-the-loop.mdx
deleted file mode 100644
index 9fb3a2247..000000000
--- a/docs/human-in-the-loop.mdx
+++ /dev/null
@@ -1,104 +0,0 @@
----
-title: 'Human in the Loop'
-sidebarTitle: 'Human in the Loop'
-description: 'Pause an agent before sensitive tool calls so the user can approve or deny execution.'
----
-
-Some agent actions — deploying to production, restarting a service, deleting data — should not happen without explicit user consent. Human in the Loop lets the harness pause the agent before a sensitive tool call, surface the tool name and arguments to the user, and resume only after an approval decision.
-
-This keeps the agent autonomous for safe operations while giving users a checkpoint before anything destructive or irreversible runs.
-
-## Which tools require approval
-
-Approval policy is set per MCP server on the agent spec via [`require_approval_for_tools`](/api/agent-spec#mcp_servers). The default is `["@write", "@destructive"]` — any tool that the MCP server does not mark as read-only, or marks as destructive, pauses for approval out of the box. You can also list literal tool names, or use `@all` to gate every tool.
-
-```json
-{
- "mcp_servers": [
- {
- "name": "orders-api",
- "require_approval_for_tools": ["process_refund"]
- }
- ]
-}
-```
-
-## How it works
-
-When the agent requests a tool call that requires approval, the harness does not execute the tool. Instead, it emits `tool.approval_required`, finishes the current turn (with the pending approval in `state.required_actions`), and waits. Resume by starting a new turn in the same session with a `user.tool_approval` input for each pending tool call.
-
-```mermaid
-sequenceDiagram
- participant Client
- participant Harness as TrueForge
- participant Tool
-
- Client->>Harness: POST /turns (user message)
- Harness->>Harness: Agent calls sensitive tool
- rect rgba(255, 237, 153, 0.45)
- Harness-->>Client: tool.approval_required (turn ends)
- Client->>Harness: POST /turns (user.tool_approval)
- end
- alt Allow
- Harness->>Tool: Execute
- Tool-->>Harness: Tool result
- else Deny
- Harness->>Harness: Denial becomes the tool result
- end
- Harness-->>Client: Agent continues
-```
-
-<Info>
- Subagents can also request approval. When a subagent's tool call requires approval, the harness finishes the current
- turn and emits `tool.approval_required` with that subagent's `thread_id`. Sending a `user.tool_approval` in the next
- turn resumes the subagent from where it paused.
-</Info>
-
-## Approving or denying from the API
-
-The `tool.approval_required` event references the pending tool calls:
-
-```json
-{
- "type": "tool.approval_required",
- "thread_id": "main",
- "tool_calls": [{ "id": "call-refund-01", "source_event_id": "msg-b2" }]
-}
-```
-
-Resume with a new turn whose input carries the decision:
-
-```json
-{
- "input": [
- {
- "type": "user.tool_approval",
- "thread_id": "main",
- "tool_call_id": "call-refund-01",
- "approval": { "status": "allow" }
- }
- ]
-}
-```
-
-To deny, send `{ "status": "deny", "reason": "..." }` — the agent receives the denial (and your reason) as the tool result and can adjust its plan instead of failing.
-
-The bundled chat UI handles all of this automatically: it pauses the run, shows the tool name and request payload with **Approve / Deny** buttons, and resumes on your decision.
-
-<Frame caption="The chat UI pauses on a sensitive tool call and shows the request with Approve / Deny buttons.">
- <img src="/images/hitl.png" alt="The chat UI pausing on a tool call, showing the request payload and Approve / Deny buttons" />
-</Frame>
-
-## When to use approvals
-
-Use approvals for tool calls that change state, are irreversible, or affect production — mutating data, modifying infrastructure, sending external communications, or triggering expensive operations. The `@write` / `@destructive` defaults cover this when the MCP server annotates its tools correctly.
-
-<Note>
- Skip approvals for safe read-only tools — listing resources, fetching metrics, searching docs — where confirmation
- adds friction without reducing risk. Those are excluded by default.
-</Note>
-
-<Info>
- Approvals do not replace authorization. The user still needs whatever access the underlying tool requires; approval
- only controls whether the pending tool call should proceed.
-</Info>
diff --git a/docs/images/agents-library.png b/docs/images/agents-library.png
new file mode 100644
index 000000000..14575cd3b
Binary files /dev/null and b/docs/images/agents-library.png differ
diff --git a/docs/introduction.mdx b/docs/introduction.mdx
index 6d9201df5..4bb3ef0af 100644
--- a/docs/introduction.mdx
+++ b/docs/introduction.mdx
@@ -56,8 +56,8 @@ flowchart LR
Runs the agent loop. When a user sends a message, the server:
- Plans the turn, calls the model, and executes tools — streaming every step back
-- Pauses for [human approval](/human-in-the-loop) on sensitive actions
-- Keeps context lean on long tasks with [context engineering](/context-engineering/overview)
+- Pauses for [human approval](/create-agent/tool-approval) on sensitive actions
+- Keeps context lean on long tasks with [key features](/key-features/overview) like subagents and compaction
- Persists sessions, so conversations survive reconnects and restarts
The services the loop talks to — [model providers](/models), [MCP servers](/mcp-servers), the [sandbox provider](/sandbox) — are **bring your own**: you configure them, TrueForge orchestrates them.
@@ -75,7 +75,7 @@ Everything the server does is exposed as an API, so anything you see in the UI y
- REST + Server-Sent Events, with an OpenAPI spec and interactive docs at `/api/v1/docs`
- A TypeScript SDK (`@truefoundry/trueforge-core`) to create and call agents from your own code
-See the [API overview](/api/overview).
+See the [SDK overview](/api/overview).
### Chat UI + UI SDK
@@ -83,7 +83,7 @@ A ready-made interface for the agents you create:
- Browse your agents, chat with them, and manage models, MCP servers, skills, and sandbox settings
- Bundled with the server and served on the same port — nothing extra to deploy
-- Also published as a customizable [UI SDK](/ui-sdk/index) (`@truefoundry/trueforge-ui`): theme it to your organization and launch your own Claude Desktop-like interface, backed by your TrueForge server
+- Also published as a customizable [UI SDK](/chat-ui) (`@truefoundry/trueforge-ui`): theme it to your organization and launch your own Claude Desktop-like interface, backed by your TrueForge server
## Two ways to run it
@@ -104,36 +104,26 @@ Like Claude's managed agents: one deployment the whole company uses, via Docker
- **Postgres** replaces SQLite as durable storage shared by all replicas
- **Redis** peers the replicas — it hands off turn event streams and cancellation signals, so a client can reconnect to any replica and still resume a turn running on another one
-## Capabilities
+## Explore the docs
<CardGroup cols={3}>
- <Card title="Models" icon="brain" href="/models">
- OpenAI, Anthropic, Google Gemini, and any OpenAI-compatible provider. Configure once, switch per agent.
+ <Card title="Initial Setup" icon="sliders" href="/harness/initial-setup">
+ Configure models, MCP servers, skills, and sandbox — and customize the shipped catalogs.
</Card>
- <Card title="MCP Servers" icon="plug" href="/mcp-servers">
- Connect remote MCP servers with header auth or OAuth (dynamic client registration), including in-chat authorization.
+ <Card title="Create an Agent" icon="robot" href="/create-agent/overview">
+ Select a model, attach connectors and skills, then save to the Agent Library.
</Card>
- <Card title="Skills" icon="book" href="/skills">
- Git-backed `SKILL.md` instruction packs, mounted into the sandbox and loaded on demand.
+ <Card title="Key Features" icon="layer-group" href="/key-features/overview">
+ Sandbox-as-tool, subagents, deferred tools, code mode, compaction, and human checkpoints.
</Card>
- <Card title="Sandbox" icon="cube" href="/sandbox">
- An isolated execution environment for code, files, and shell commands — provisioned only when the agent needs one.
+ <Card title="Setup Login" icon="lock" href="/authentication/overview">
+ Optional OIDC for shared deployments — admin vs user, with a local no-auth default.
</Card>
- <Card title="Context Engineering" icon="layer-group" href="/context-engineering/overview">
- Subagents, deferred tool loading, code mode, large-result offloading, and compaction — keep context lean
- automatically.
+ <Card title="SDK" icon="code" href="/api/overview">
+ HTTP API and TypeScript SDK to create sessions, stream turns, and automate agents.
</Card>
- <Card title="Authentication" icon="lock" href="/authentication/overview">
- Optional OIDC with your IdP, admin vs user roles, Bearer tokens for the SDK, and the no-auth local default.
- </Card>
- <Card title="Human in the Loop" icon="shield-check" href="/human-in-the-loop">
- Pause sensitive tool calls and require explicit user approval before execution.
- </Card>
- <Card title="Ask User Questions" icon="message-question" href="/ask-user-questions">
- Let the agent request clarification or pick between options during a run.
- </Card>
- <Card title="Generative UI" icon="sparkles" href="/generative-ui">
- Stream structured UI blocks the client can render as cards, tables, and charts.
+ <Card title="Chat UI" icon="palette" href="/chat-ui">
+ Bundled chat experience, or embed `@truefoundry/trueforge-ui` in your React app.
</Card>
</CardGroup>
@@ -143,10 +133,10 @@ Like Claude's managed agents: one deployment the whole company uses, via Docker
<Card title="Quickstart" icon="rocket" href="/quickstart">
Run TrueForge with one command, configure a model provider, and start chatting.
</Card>
- <Card title="Use the API" icon="code" href="/api/overview">
- Create sessions, stream turn events, and integrate TrueForge into your application.
+ <Card title="Benchmarking" icon="chart-line" href="/benchmarking">
+ Same tasks and model vs Claude Managed Agents and deepagents — cost and accuracy.
</Card>
- <Card title="Build with the UI SDK" icon="palette" href="/ui-sdk/index">
- Embed and customize the chat experience in your own React application.
+ <Card title="UI SDK reference" icon="book" href="/ui-sdk/index">
+ Themes, layouts, slots, and the full React component API.
</Card>
</CardGroup>
diff --git a/docs/context-engineering/code-mode.mdx b/docs/key-features/code-mode.mdx
similarity index 95%
rename from docs/context-engineering/code-mode.mdx
rename to docs/key-features/code-mode.mdx
index dcb79c5ed..44b80d87c 100644
--- a/docs/context-engineering/code-mode.mdx
+++ b/docs/key-features/code-mode.mdx
@@ -52,10 +52,10 @@ sequenceDiagram
Sandbox-->>Agent: Printed summary only
```
-Code Mode is available whenever the agent's [sandbox](/sandbox) is enabled. The agent decides at runtime whether a task is worth running in code or whether a single direct tool call is enough. Before writing a script, it can call [`get_tool_output_schema`](/context-engineering/deferred-tool-loading#how-it-works) so it knows the exact shape of a tool's response instead of guessing keys from raw JSON.
+Code Mode is available whenever the agent's [sandbox](/sandbox) is enabled. The agent decides at runtime whether a task is worth running in code or whether a single direct tool call is enough. Before writing a script, it can call [`get_tool_output_schema`](/key-features/deferred-tool-loading#how-it-works) so it knows the exact shape of a tool's response instead of guessing keys from raw JSON.
<Note>
- [Approval policies](/human-in-the-loop) still apply in Code Mode — a script that calls a tool matching
+ [Approval policies](/create-agent/tool-approval) still apply in Code Mode — a script that calls a tool matching
`require_approval_for_tools` pauses for user approval just like a direct tool call.
</Note>
diff --git a/docs/context-engineering/deferred-tool-loading.mdx b/docs/key-features/deferred-tool-loading.mdx
similarity index 98%
rename from docs/context-engineering/deferred-tool-loading.mdx
rename to docs/key-features/deferred-tool-loading.mdx
index 0c15e2ee7..e58141ecb 100644
--- a/docs/context-engineering/deferred-tool-loading.mdx
+++ b/docs/key-features/deferred-tool-loading.mdx
@@ -34,7 +34,7 @@ When `preload` is off, the harness exposes four **meta tools** instead of the in
| ------------------------ | ---------------------------------------------------------------------------------------------- |
| `list_tools` | List the tool names available on an MCP server |
| `get_tool_info` | Fetch a tool's description and input/output schema |
-| `get_tool_output_schema` | Fetch just the output schema — used before [Code Mode](/context-engineering/code-mode) scripts |
+| `get_tool_output_schema` | Fetch just the output schema — used before [Code Mode](/key-features/code-mode) scripts |
| `call_tool` | Invoke a tool on a server by name |
```mermaid
diff --git a/docs/context-engineering/large-tool-responses.mdx b/docs/key-features/large-tool-responses.mdx
similarity index 97%
rename from docs/context-engineering/large-tool-responses.mdx
rename to docs/key-features/large-tool-responses.mdx
index 750c9f016..de3ddd9d2 100644
--- a/docs/context-engineering/large-tool-responses.mdx
+++ b/docs/key-features/large-tool-responses.mdx
@@ -26,7 +26,7 @@ Two complementary thresholds govern when tool responses are written to the sandb
**Parallel tool calls returning together.** When the agent fires several tool calls in parallel, no single response may be over the per-call threshold but their _combined_ size can still flood the context window. If the combined tool-call content exceeds the total threshold (default **10,000 tokens**), the harness offloads responses one at a time — **starting with the largest** — until the total drops below the limit. The smallest responses stay inline and the largest end up on disk.
-In every case the offloaded content remains accessible — the agent can read, `grep`, or parse the saved file from the sandbox whenever it needs the original data, typically using [Code Mode](/context-engineering/code-mode) to extract just the fields it needs.
+In every case the offloaded content remains accessible — the agent can read, `grep`, or parse the saved file from the sandbox whenever it needs the original data, typically using [Code Mode](/key-features/code-mode) to extract just the fields it needs.
## Example
diff --git a/docs/context-engineering/overview.mdx b/docs/key-features/overview.mdx
similarity index 77%
rename from docs/context-engineering/overview.mdx
rename to docs/key-features/overview.mdx
index 5cdadcfc4..0a9d5ee2e 100644
--- a/docs/context-engineering/overview.mdx
+++ b/docs/key-features/overview.mdx
@@ -1,19 +1,34 @@
---
-title: 'Context Engineering'
+title: 'Key Features'
sidebarTitle: 'Overview'
-description: 'How TrueForge manages, optimizes, and constrains agent context within model limits.'
+description: 'Sandbox-as-tool, context engineering, human checkpoints, and Generative UI — how TrueForge keeps agents reliable and efficient.'
---
+TrueForge is more than model + tools. These harness features keep long agent runs accurate, cheaper, and safer.
+
+| Feature | What it does |
+| --- | --- |
+| [Sandbox as a tool](/sandbox) | Isolated code/file execution without putting secrets or the agent loop inside the sandbox |
+| [Context engineering](#what-is-context-engineering) | Progressive skills, deferred tools, subagents, offloading, Code Mode, compaction |
+| [Tool approval](/create-agent/tool-approval) | Pause before write/destructive MCP tools |
+| [Ask User Questions](/create-agent/ask-user-questions) | Structured clarification mid-run |
+| [Generative UI](/create-agent/generative-ui) | Charts, tables, and cards streamed into chat |
+| [In-chat MCP OAuth](/mcp-servers#in-chat-authentication) | Connect button when a connector needs authorization |
+
+## Sandbox as a tool
+
+Unlike harnesses that run the whole agent inside a VM, TrueForge keeps the agent loop on the server and uses the [sandbox](/sandbox) only for code, files, and shell. Secrets stay out of the sandbox; compute is provisioned only when needed. Skills and Code Mode require it.
+
## What is context engineering?
-Context engineering is the practice of providing the **right information in the right format** so an agent can reliably accomplish tasks. In TrueForge, _context_ is everything the model sees on each step — from system instructions and skills to tool definitions, conversation history, and tool results.
+Context engineering is providing the **right information in the right format** so an agent can finish the job reliably. In TrueForge, _context_ is everything the model sees on each step — instructions, [skills](/skills), [MCP](/mcp-servers) tool definitions, conversation history, and tool results.
-Getting context right has a direct impact on agent quality:
+Getting that balance wrong hurts quality:
-- **Too little context** — the agent lacks the information it needs and produces wrong or incomplete answers.
-- **Too much context** — the model overflows its context window or the signal gets buried in noise, degrading reasoning quality and increasing cost and latency.
+- **Too little context** — the agent lacks what it needs and answers poorly.
+- **Too much context** — the window fills with noise, reasoning degrades, and cost/latency climb.
-TrueForge automates the balance through a layered set of strategies. To understand them, it helps to think of context in two phases:
+TrueForge manages the balance with layered strategies. Think of context in two phases:
<CardGroup cols={2}>
<Card title="Input context" icon="upload" href="#input-context">
@@ -56,7 +71,7 @@ Input context is everything the model receives at the **start** of a run. It is
<Accordion title="MCP tool definitions" icon="plug">
Each tool definition — name, description, input schema, output schema — consumes tokens. With many MCP servers each exposing dozens of tools, the schemas alone can fill a large portion of the context window before the user types anything.
- By default (`preload: false`), each attached MCP server contributes only its `name` and `description`; individual tool schemas are discovered on demand. Turn `preload` on only for small, frequently-used servers. See [Deferred tool loading](/context-engineering/deferred-tool-loading).
+ By default (`preload: false`), each attached MCP server contributes only its `name` and `description`; individual tool schemas are discovered on demand. Turn `preload` on only for small, frequently-used servers. See [Deferred tool loading](/key-features/deferred-tool-loading).
</Accordion>
</AccordionGroup>
@@ -71,22 +86,22 @@ Runtime context is everything added to the model's context **as the run progress
| **Assistant messages** | The model's reasoning and replies on each step |
| **Tool calls** | Each tool invocation made by the agent, with its arguments |
| **Tool results** | Whatever the tool returns — JSON payloads, file contents, search results, errors |
-| **Subagent outputs** | Final results returned from delegated [subagents](/context-engineering/subagents) |
+| **Subagent outputs** | Final results returned from delegated [subagents](/key-features/subagents) |
Runtime context is where most of the **context bloat problem** happens. A single tool call returning a 50,000-token JSON payload, or a long conversation with dozens of intermediate steps, can quickly approach the model's limit. This is the part the harness actively manages.
## Managing runtime context
<CardGroup cols={2}>
- <Card title="Subagents" icon="diagram-project" href="/context-engineering/subagents">
+ <Card title="Subagents" icon="diagram-project" href="/key-features/subagents">
Delegate focused subtasks to parallel subagents, each with its own clean context. Only the final result flows back —
the intermediate tool calls never touch the main context.
</Card>
- <Card title="Large Result Offloading" icon="file-export" href="/context-engineering/large-tool-responses">
+ <Card title="Large Result Offloading" icon="file-export" href="/key-features/large-tool-responses">
When a tool returns more data than fits comfortably in context, the harness writes the full output to a sandbox file
and replaces it with a short preview and the file path.
</Card>
- <Card title="Code Mode" icon="code" href="/context-engineering/code-mode">
+ <Card title="Code Mode" icon="code" href="/key-features/code-mode">
The agent calls MCP tools from a Python script in the sandbox, processing results in code. Only the printed summary
enters context.
</Card>
diff --git a/docs/context-engineering/subagents.mdx b/docs/key-features/subagents.mdx
similarity index 97%
rename from docs/context-engineering/subagents.mdx
rename to docs/key-features/subagents.mdx
index 0c305dbf8..a9fd38c4b 100644
--- a/docs/context-engineering/subagents.mdx
+++ b/docs/key-features/subagents.mdx
@@ -65,7 +65,7 @@ flowchart LR
<Note>
- **Shared tools and sandbox** — subagents have access to the same MCP tools and sandbox environment as the root
agent. - **No user interaction** — subagents cannot ask the user questions. Only the root agent talks to the user.
- Subagent tool calls that require [approval](/human-in-the-loop) still pause for the user, though. - **No nesting** —
+ Subagent tool calls that require [approval](/create-agent/tool-approval) still pause for the user, though. - **No nesting** —
subagents cannot create other subagents. Delegation is one level deep. - **Parallel execution** — multiple subagents
run concurrently. The root agent waits for all of them before continuing.
</Note>
diff --git a/docs/mcp-servers.mdx b/docs/mcp-servers.mdx
index 0267d97f7..f77e9fef1 100644
--- a/docs/mcp-servers.mdx
+++ b/docs/mcp-servers.mdx
@@ -1,34 +1,18 @@
---
-title: 'MCP Servers'
+title: 'Setup MCP Servers'
sidebarTitle: 'MCP Servers'
-description: 'Connect remote MCP servers to give your agent tools — with header auth or OAuth, per-tool enablement, and approval policies.'
+description: 'Connect remote MCP servers from the shipped catalog or your own URL — with header auth or OAuth.'
---
MCP servers are how your agent reaches real systems: SaaS apps, internal APIs, data platforms, ticketing tools, and infrastructure controls.
-In TrueForge, MCP servers are registered once — in the UI under **Settings → Connectors** or via the settings API — and agents reference them by name. Credentials live in the server configuration, never in agent definitions.
+Register them once under **Settings → Connectors**. Agents attach servers by name. Credentials live in the connector configuration, never in agent definitions.
-## Registering an MCP server
+## Connecting a server
-An MCP server is configured with a small manifest:
+Open **Settings → Connectors**, pick a server from the catalog, complete auth if required, and save. The server is then available when you [create an agent](/create-agent/overview).
-```json
-{
- "type": "remote",
- "name": "github",
- "url": "https://api.githubcopilot.com/mcp/",
- "auth": { "type": "dcr" }
-}
-```
-
-| Field | Description |
-| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `type` | `remote` — a server reachable over HTTP. TrueForge connects via Streamable HTTP, falling back to SSE. |
-| `name` | How agents reference the server. |
-| `url` | The MCP endpoint URL. |
-| `auth` | Optional. `{ "type": "header", "headers": { ... } }` for static credentials, or `{ "type": "dcr" }` for OAuth. Omit for servers that need no auth. |
-
-Register it with `PUT /api/v1/settings/mcp-servers` (or through the UI). A catalog of popular servers is available at `GET /api/v1/settings/mcp-servers/catalog`, and you can verify connectivity with `GET /api/v1/settings/mcp-servers/{name}/tools`, which lists the server's live tools.
+You can also use **Add MCP Server** to register any remote URL that is not in the catalog.
<div style={{ position: "relative", boxSizing: "content-box", width: "100%", aspectRatio: "1.75", padding: "40px 0" }}>
<iframe
@@ -41,75 +25,49 @@ Register it with `PUT /api/v1/settings/mcp-servers` (or through the UI). A catal
/>
</div>
-### Authentication options
-
-- **No auth** — public or network-trusted servers.
-- **Header auth** (`type: "header"`) — static HTTP headers (API keys, bearer tokens) sent on every request to the server.
-- **OAuth with Dynamic Client Registration** (`type: "dcr"`) — TrueForge registers itself as an OAuth client with the server's authorization server, runs the authorization-code flow, and stores and refreshes tokens. Users never handle tokens.
-
-## In-chat authentication
-
-If a server uses OAuth and the user has not yet authorized it, the agent does not fail — the turn pauses with an `mcp.auth_required` event that carries an `auth_url` for each server that needs authorization. The chat UI renders this as a **Connect** button: the user completes the OAuth flow in a popup and continues the conversation.
-
-```mermaid
-sequenceDiagram
- participant User
- participant Client
- participant TrueForge
- participant MCP as MCP server
+## Where the connectors list comes from
- Client->>TrueForge: Start turn
- TrueForge->>MCP: Connect
- MCP-->>TrueForge: 401 — OAuth required
- TrueForge-->>Client: mcp.auth_required (auth_url)
- User->>TrueForge: Completes OAuth flow
- Client->>TrueForge: Next turn
- TrueForge->>MCP: Authenticated tool calls
-```
+The popular servers under **Settings → Connectors** come from a shipped catalog YAML:
-Set `PUBLIC_BASE_URL` on the server so OAuth callbacks resolve to the right origin.
-
-## Attaching servers to an agent
-
-Each agent lists the servers it uses, with fine-grained control over which tools are exposed and which require approval:
-
-```json
-{
- "mcp_servers": [
- {
- "name": "github",
- "enable_tools": ["@all"],
- "disable_tools": ["delete_repository"],
- "require_approval_for_tools": ["@write", "@destructive"],
- "preload": false
- }
- ]
-}
-```
+[`mcp-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/server/src/catalog/mcp-catalog.yaml)
-| Field | Default | Description |
-| ---------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `enable_tools` | `["@all"]` | Tools exposed to the agent. `@all`, `@read-only`, or literal names. |
-| `disable_tools` | `[]` | Tools removed from the enabled set. |
-| `require_approval_for_tools` | `["@write", "@destructive"]` | Tools that pause for [human approval](/human-in-the-loop). `@all`, `@write`, `@destructive`, or literal names. |
-| `preload` | `false` | Whether tool schemas are loaded into context upfront. See [Deferred tool loading](/context-engineering/deferred-tool-loading). |
-| `preload_tools` | `[]` | Specific tools to load eagerly while the rest stay deferred. |
+Each entry is a ready-made remote MCP preset (URL, logo, and default auth shape — for example Linear and Notion with OAuth, or GitHub with a header placeholder). Choosing a catalog server creates a configured connector; the catalog itself is never executed against.
-The `@read-only`, `@write`, and `@destructive` selectors are derived from the tool annotations the MCP server publishes (`readOnlyHint`, `destructiveHint`), so approval policy follows the server's own metadata.
+To change which presets appear, see [Initial Setup](/harness/initial-setup#changing-what-the-ui-offers).
-<Tip>
- Attach only the servers an agent needs, and disable tools it should never call. A smaller tool surface reduces risk
- and improves tool-call quality by minimizing irrelevant choices.
-</Tip>
+## Authentication options
-## Safety controls
-
-- Tools matching `require_approval_for_tools` pause the turn for explicit user confirmation — see [Human in the Loop](/human-in-the-loop).
-- The defaults (`@write`, `@destructive`) mean state-changing tools require approval out of the box; read-only tools run freely.
-- Approval enforcement also applies when tools are called from [Code Mode](/context-engineering/code-mode) scripts inside the sandbox.
+- **No auth** — public or network-trusted servers.
+- **Header auth** — static HTTP headers (API keys, bearer tokens) sent on every request.
+- **OAuth (Dynamic Client Registration)** — TrueForge registers as an OAuth client, runs the authorization-code flow, and stores and refreshes tokens. Users never paste tokens into the agent.
-## Keeping context lean
+Set `PUBLIC_BASE_URL` on the server so OAuth callbacks resolve to the right origin.
-Tool definitions consume context. With many servers each exposing dozens of tools, the schemas alone can fill a large share of the context window before the user types anything. By default (`preload: false`), TrueForge only puts each server's name and description in context and lets the agent discover tool schemas on demand.
+## In-chat authentication
-See [Deferred tool loading](/context-engineering/deferred-tool-loading) for the full flow.
+If a server uses OAuth and the user has not yet authorized it, the turn pauses and the chat UI shows a **Connect** button. The user completes OAuth in a popup and continues the conversation — the agent does not fail.
+
+{/* TODO: Add screenshot of in-chat MCP OAuth Connect button. */}
+<Frame caption="TODO: Screenshot — in-chat MCP authentication showing the Connect button when OAuth is required.">
+ <div
+ style={{
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ minHeight: 200,
+ border: "1px dashed #94a3b8",
+ borderRadius: 8,
+ color: "#64748b",
+ padding: 24,
+ textAlign: "center",
+ }}
+ >
+ TODO: Screenshot of in-chat MCP auth (Connect button in chat)
+ </div>
+</Frame>
+
+## Next steps
+
+- Attach MCP servers when you [create an agent](/create-agent/overview).
+- Configure which tools need [approval](/create-agent/tool-approval) (API today).
+- Keep tool schemas lean with [deferred loading](/key-features/deferred-tool-loading) in Key Features.
diff --git a/docs/models.mdx b/docs/models.mdx
index d0d144c18..ad114aa37 100644
--- a/docs/models.mdx
+++ b/docs/models.mdx
@@ -1,10 +1,10 @@
---
-title: 'Models'
+title: 'Setup Models'
sidebarTitle: 'Models'
-description: 'Configure model providers once, then reference models by name in any agent — switching models is a config change, not a code change.'
+description: 'Connect model providers from the shipped catalog or add a custom OpenAI-compatible endpoint.'
---
-TrueForge works with the major model providers and any OpenAI-compatible endpoint. Provider credentials are configured once — in the UI under **Settings → Models** or via the settings API — and agents reference models by name. Agent definitions never contain API keys.
+TrueForge works with the major model providers and any OpenAI-compatible endpoint. Configure credentials once under **Settings → Models**. Agents reference models by name — agent definitions never contain API keys.
## Supported providers
@@ -20,32 +20,9 @@ TrueForge works with the major model providers and any OpenAI-compatible endpoin
| `alibaba` | Alibaba (Qwen) |
| `custom` | Any OpenAI-compatible endpoint — self-hosted models, gateways, proxies |
-The shipped catalog (`GET /api/v1/settings/model-providers/catalog`) contains ready-to-fill templates for each provider. Use the `custom` type to connect vLLM, Ollama, a corporate gateway, or any other OpenAI-compatible API.
+## Configuring a standard provider
-<Frame caption="Adding a custom OpenAI-compatible provider (vLLM, Ollama, a gateway) with base URL, API key, and model IDs.">
- <img src="/images/add-custom-model-provider.png" alt="The Add Custom Provider dialog with name, base URL, API key, and model fields" />
-</Frame>
-
-## Configuring a provider
-
-<Tabs>
- <Tab title="UI">
- Open **Settings → Models**, pick a provider from the catalog, and paste your API key. Models from that provider become available immediately in the model selector.
- </Tab>
- <Tab title="API">
- Fetch a template from the catalog, fill in the credentials, and upsert it:
-
- ```bash
- curl http://localhost:8790/api/v1/settings/model-providers/catalog
- curl -X PUT http://localhost:8790/api/v1/settings/model-providers \
- -H 'Content-Type: application/json' \
- -d '<provider manifest from the catalog, with your API key>'
- ```
-
- List every available model across configured providers with `GET /api/v1/models`.
-
- </Tab>
-</Tabs>
+Open **Settings → Models**, pick a provider, and paste your API key. Models from that provider become available immediately in the agent model selector.
<div style={{ position: "relative", boxSizing: "content-box", width: "100%", aspectRatio: "1.75", padding: "40px 0" }}>
<iframe
@@ -58,45 +35,26 @@ The shipped catalog (`GET /api/v1/settings/model-providers/catalog`) contains re
/>
</div>
-## Referencing a model in an agent
-
-Models are addressed as `provider/model` in the agent spec:
+## Where the model list comes from
-```json
-{
- "model": {
- "name": "anthropic/claude-sonnet-4-6",
- "params": {
- "max_tokens": 4096,
- "temperature": 0.2
- }
- }
-}
-```
+The providers and models in **Settings → Models** come from a shipped catalog YAML:
-`model.params` supports `max_tokens`, `temperature`, `top_p`, `top_k`, `parallel_tool_calls`, and `reasoning_effort` — plus any extra provider-specific parameters, which are passed through as-is. See the [agent spec reference](/api/agent-spec#model).
+[`model-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/server/src/catalog/model-catalog.yaml)
-Switching models is a one-line change to the agent spec (or one click in the UI). No code edits, no new credentials.
+That file lists the standard provider presets and model IDs. When you pick a provider in the UI, you paste your API key and TrueForge stores a configured provider — the catalog itself is never called with your credentials.
-## Why model choice matters for agents
+To change which presets appear, see [Initial Setup](/harness/initial-setup#changing-what-the-ui-offers).
-Agent workloads are different from single-turn chat. They involve multiple tool calls, retries, long context, and structured outputs. Model selection directly affects:
+## Adding a custom provider
-- Reliability of tool calling and structured output
-- Latency across multi-step tasks
-- Total run cost over many turns
-- Accuracy on planning and complex reasoning
+Use the `custom` provider type for vLLM, Ollama, a corporate gateway, or any other OpenAI-compatible API. Custom providers are not in the catalog — you add them yourself with a base URL, API key, and the model IDs you want exposed.
-| Category | Best for |
-| -------------------------- | --------------------------------------------------------------- |
-| Balanced general-purpose | Most production assistants and tool-driven workflows |
-| Cost-optimized high-volume | High request volume, triage, lightweight actions |
-| High reasoning depth | Complex planning, multi-step analysis, long tool chains |
-| Open / self-hosted | Data residency, cost control, private deployment (via `custom`) |
+<Frame caption="Adding a custom OpenAI-compatible provider (vLLM, Ollama, a gateway) with base URL, API key, and model IDs.">
+ <img src="/images/add-custom-model-provider.png" alt="The Add Custom Provider dialog with name, base URL, API key, and model fields" />
+</Frame>
-<Tip>
- Start with a balanced model and a tight [agent spec](/api/agent-spec), then measure. Token usage per model call is
- reported on every `model.message` event (`usage.input_tokens`, `usage.output_tokens`, and a breakdown of where input
- tokens went), and per-turn totals appear in `turn.done` metrics — so you can see exactly what a model choice costs
- before switching.
-</Tip>
+<Note>
+ **Planned:** automatic model selection for different turns or subagents. Today each agent uses the model you
+ configure. In the future, TrueForge will be able to pick among a set of models per turn or subagent based on task
+ complexity, latency, and cost.
+</Note>
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
index 2d63e890e..d004558eb 100644
--- a/docs/quickstart.mdx
+++ b/docs/quickstart.mdx
@@ -102,7 +102,7 @@ With TrueForge open in your browser, this walkthrough takes you from an empty wo
<img src="/images/quickstart-sandbox.png" alt="The Daytona sandbox provider dialog with snapshot name, exec timeout, lifecycle intervals, and an API key field" />
</Frame>
- See the [Sandbox guide](/sandbox) for the exact API-key permissions and the image-sync command.
+ See the [Sandbox guide](/sandbox) for provider setup details.
</Step>
<Step title="Compose an agent and start chatting">
@@ -111,7 +111,7 @@ With TrueForge open in your browser, this walkthrough takes you from an empty wo
1. **Pick a model** from the selector in the composer.
2. Open the **+** menu → **Connectors** and enable the MCP server you connected.
3. In the same menu → **Skills**, enable your skill.
- 4. Send your message. Streaming, tool calls, sandbox output, and [approvals](/human-in-the-loop) all show up live.
+ 4. Send your message. Streaming, tool calls, sandbox output, and [approvals](/create-agent/tool-approval) all show up live.
<Frame caption="Pick a model, then add your connector and skill to the turn from the + menu.">
<img src="/images/quickstart-composer-connectors.png" alt="The composer with a model selected and the + menu open on the Connectors tab, a connector checked" />
@@ -130,7 +130,7 @@ With TrueForge open in your browser, this walkthrough takes you from an empty wo
</Step>
<Step title="Find it in the Agents Library">
- Open **Agents Library** from the sidebar. Your saved agent is there — click **Try** to start a fresh chat with the same setup, or **Edit** to tweak it.
+ Open **Agents Library** from the sidebar. Your saved agent is there — click **Try** to start a fresh chat with the same setup, or **Edit** to tweak it. See [Agent Library](/agent-library) for shared-visibility notes in hosted mode.
<Frame>
<img src="/images/quickstart-agents-library.png" alt="The Agents Library listing the saved github-repo-explainer agent with Edit and Try actions" />
@@ -138,38 +138,6 @@ With TrueForge open in your browser, this walkthrough takes you from an empty wo
</Step>
</Steps>
-Everything you configure in Settings is also available through the API — see the interactive docs at `/api/v1/docs`.
-
-## Call the API
-
-Every conversation in the UI is a session in the API. Create one yourself:
-
-```bash
-curl -X POST http://localhost:8790/api/v1/sessions \
- -H 'Content-Type: application/json' \
- -d '{
- "agent": {
- "type": "value",
- "agent_spec": {
- "model": { "name": "anthropic/claude-sonnet-4-6" },
- "instructions": "You are a helpful assistant."
- }
- }
- }'
-```
-
-Then start a turn and stream events over SSE:
-
-```bash
-curl -N -X POST http://localhost:8790/api/v1/sessions/{session_id}/turns \
- -H 'Content-Type: application/json' \
- -d '{
- "input": [{ "type": "user.message", "content": "Hello!" }]
- }'
-```
-
-See the [API overview](/api/overview) for the full lifecycle — turn chaining, approvals, and event handling.
-
## FAQ
<AccordionGroup>
@@ -210,16 +178,16 @@ See the [API overview](/api/overview) for the full lifecycle — turn chaining,
## Next steps
<CardGroup cols={2}>
- <Card title="Connect MCP servers" icon="plug" href="/mcp-servers">
- Give your agent tools — with per-tool enablement and approval policies.
+ <Card title="Initial Setup" icon="sliders" href="/harness/initial-setup">
+ Models, MCP servers, skills, sandbox — and how catalogs work.
</Card>
- <Card title="Enable the sandbox" icon="cube" href="/sandbox">
- Let the agent run code, work with files, and use skills.
+ <Card title="Create an Agent" icon="robot" href="/create-agent/overview">
+ Select resources and configure approvals, questions, and Generative UI.
</Card>
- <Card title="Context engineering" icon="layer-group" href="/context-engineering/overview">
- How TrueForge keeps agent context lean on long tasks.
+ <Card title="Key Features" icon="layer-group" href="/key-features/overview">
+ Subagents, deferred tools, code mode, compaction, and more.
</Card>
- <Card title="API reference" icon="code" href="/api/overview">
+ <Card title="SDK" icon="code" href="/api/overview">
Sessions, turns, events, and the agent spec.
</Card>
</CardGroup>
diff --git a/docs/sandbox.mdx b/docs/sandbox.mdx
index aeeb54479..067848ee1 100644
--- a/docs/sandbox.mdx
+++ b/docs/sandbox.mdx
@@ -1,59 +1,35 @@
---
-title: 'Sandbox'
+title: 'Setup Sandbox'
sidebarTitle: 'Sandbox'
-description: 'An isolated execution environment for code, files, and shell commands — provisioned only when the agent needs one.'
+description: 'Connect an isolated execution environment for code, files, and shell commands — provisioned only when the agent needs one.'
---
-The sandbox gives your agent a secure, isolated environment to run code, manipulate files, and execute shell commands — completely separate from the TrueForge server and your infrastructure.
-
-## Sandbox as a tool
-
-There are two architecture patterns for combining agents with sandboxes. TrueForge uses the **sandbox as tool** pattern: the agent and all orchestration logic run in the harness, and the sandbox is only used for code execution, file operations, and shell commands.
-
-```mermaid
-flowchart LR
- subgraph Harness["TrueForge server"]
- Agent[Agent loop + LLM client]
- end
- Agent <-->|"exec tool calls"| SB
- subgraph SB["Sandbox"]
- FS[Filesystem]
- Shell[Shell]
- end
-```
-
-This design has several consequences:
-
-- **Secrets stay out of the sandbox** — model API keys and MCP credentials live in the harness. Even a sandbox compromised through prompt injection has no secrets to exfiltrate.
-- **Agent state survives sandbox failures** — conversation history, context, and tool definitions live in the harness. A sandbox crash doesn't lose the agent's progress.
-- **On-demand provisioning** — a sandbox is created only when the agent actually needs one. Simple Q&A and MCP tool calls incur no sandbox cost.
-
-## Configuring a sandbox provider
-
-TrueForge delegates sandbox compute to a provider. Configure it once — in the UI under **Settings → Sandbox providers** or via `PUT /api/v1/settings/sandbox-providers`. Today the supported provider is [Daytona](https://www.daytona.io):
-
-```json
-{
- "type": "daytona",
- "snapshot_name": "your-snapshot",
- "auth": { "api_key": "..." },
- "exec_timeout_ms": 120000,
- "auto_stop_interval_in_minutes": 15,
- "auto_archive_interval_in_minutes": 10080,
- "auto_delete_interval_in_minutes": 43200
-}
-```
-
-| Field | Description |
-| ---------------------------------- | ---------------------------------------------------------------- |
-| `snapshot_name` | Daytona snapshot (base image) used when creating sandboxes. |
-| `auth.api_key` | Daytona API key. |
-| `exec_timeout_ms` | Default timeout for a single command execution. |
-| `auto_stop_interval_in_minutes` | Idle time before a running sandbox is stopped (files preserved). |
-| `auto_archive_interval_in_minutes` | Time before a stopped sandbox is archived. |
-| `auto_delete_interval_in_minutes` | Time before an archived sandbox is deleted. |
-
-A template with defaults is available at `GET /api/v1/settings/sandbox-providers/catalog`. Whether a provider is configured is reported by `GET /api/v1/capabilities`.
+The sandbox gives your agent a secure, isolated environment to run code, manipulate files, and execute shell commands — separate from the TrueForge server and your infrastructure.
+
+Skills and [Code Mode](/key-features/code-mode) require a sandbox. Configure a provider once under **Settings → Sandbox providers**, then enable the sandbox on each agent that needs it.
+
+## TrueForge's approach
+
+There are two common patterns for combining agents with sandboxes:
+
+| Pattern | Where the agent runs | Trade-off |
+| --- | --- | --- |
+| **Agent in sandbox** | Inside the sandbox image | Secrets must live in the sandbox; updates mean rebuilding images |
+| **Sandbox as tool** | Outside, on the server | Secrets stay in the harness; sandbox is only for exec/files |
+
+TrueForge uses **sandbox as tool**: the agent loop and credentials stay in the harness; the sandbox only runs code, file, and shell operations.
+
+That means:
+
+- Model and MCP credentials never enter the sandbox.
+- Conversation state survives a sandbox crash.
+- A sandbox is created only when the agent actually needs one — simple Q&A and MCP calls incur no sandbox cost.
+
+## Configuring a provider
+
+**Daytona is the only sandbox provider supported today.** Support for additional providers is planned.
+
+Open **Settings → Sandbox providers**, pick the [Daytona](https://www.daytona.io) preset from the catalog, and paste your API key.
<div style={{ position: "relative", boxSizing: "content-box", width: "100%", aspectRatio: "1.75", padding: "40px 0" }}>
<iframe
@@ -66,88 +42,31 @@ A template with defaults is available at `GET /api/v1/settings/sandbox-providers
/>
</div>
+### Where the provider list comes from
+
+Presets come from a shipped catalog YAML:
+
+[`sandbox-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/server/src/catalog/sandbox-catalog.yaml)
+
+To change which presets appear, see [Initial Setup](/harness/initial-setup#changing-what-the-ui-offers).
+
## Enabling the sandbox on an agent
-The sandbox is **off by default** per agent. Enable it in the agent spec:
-
-```json
-{
- "config": {
- "sandbox": {
- "enabled": true,
- "file_downloads": true
- }
- }
-}
-```
-
-| Field | Default | Description |
-| ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `enabled` | `false` | Give this agent a sandbox. Required for [skills](/skills) and [Code Mode](/context-engineering/code-mode). |
-| `file_downloads` | `true` | Allow users to download files the agent produces (via the turn download endpoint). |
-| `network_policy.auth_inject` | — | Optional: inject git basic-auth credentials for specific hosts, so the agent can clone private repositories without ever seeing the credentials. |
-
-```json
-{
- "config": {
- "sandbox": {
- "enabled": true,
- "network_policy": {
- "auth_inject": [
- {
- "type": "git",
- "match": { "hosts": ["github.com"] },
- "auth_data": { "type": "basic", "username": "x-access-token", "password": "<token>" }
- }
- ]
- }
- }
- }
-}
-```
-
-## On-demand provisioning
-
-Most agent tasks — answering questions, calling MCP tools, reasoning — do not require code execution. TrueForge provisions a sandbox only when the agent decides it needs one:
-
-```mermaid
-flowchart LR
- User[User message] --> Harness[Agent loop]
- Harness --> Check{Needs code execution<br/>or filesystem?}
- Check -->|No| Respond[Respond directly<br/>No sandbox cost]
- Check -->|Yes| Provision[Provision sandbox]
- Provision --> Execute[Run command in sandbox]
- Execute --> Respond2[Return result]
-```
-
-The sandbox is used when the agent needs to:
-
-- Run Python, shell, or other code
-- Write, read, or process files
-- Use [skills](/skills) (skill repositories are cloned into the sandbox)
-- Run [Code Mode](/context-engineering/code-mode) scripts that chain MCP tool calls programmatically
-- Generate downloadable artifacts (CSVs, reports, images)
-
-When a sandbox is created, the turn stream emits a [`sandbox.created`](/api/turn-events#sandbox-created) event with the `sandbox_id`.
-
-## Persistence across turns
-
-Once provisioned, the sandbox is reused across turns in the same session — files written in one turn are available in the next, and no new `sandbox.created` event is emitted. Idle sandboxes are stopped after `auto_stop_interval_in_minutes` (state preserved and restartable), then archived and eventually deleted per the provider configuration.
-
-## File downloads
-
-When the agent produces a file, clients can fetch it through the server:
-
-```text
-GET /api/v1/sessions/{session_id}/turns/{turn_id}/download?path=...
-```
-
-The bundled chat UI renders download links automatically. Set `config.sandbox.file_downloads: false` to disable this per agent. The maximum download size is controlled by the `SANDBOX_FILE_MAX_BYTES_FOR_DOWNLOAD` server environment variable (default 20 MB).
+The sandbox is **off by default** per agent. Turn it on in the agent builder when you need code execution, skills, or Code Mode. You can also set `config.sandbox.enabled` when creating agents via the [SDK](/api/agent-spec).
-## Credential safety
+Optional controls:
-Because TrueForge uses the sandbox-as-tool pattern:
+- **File downloads** — let users download files the agent produces (on by default in the chat UI).
+- **Git auth inject** — inject credentials for private git hosts so the sandbox can clone repos without the agent seeing the secret.
+
+## Lifecycle
+
+- Provisioned on demand when the agent needs code, files, skills, or Code Mode.
+- Reused across turns in the same session (files persist).
+- Stopped after idle time, then archived and eventually deleted per the provider settings.
+
+## Credential safety
-- Model and MCP credentials are used by the harness, outside the sandbox.
-- When the agent calls MCP tools from inside a [Code Mode](/context-engineering/code-mode) script, the calls are **bridged back to the harness**, which applies the stored credentials — the sandbox never holds tokens.
-- The only credentials that can enter the sandbox are ones you explicitly inject via `network_policy.auth_inject` (for cloning private git repositories).
+- Model and MCP credentials stay in the harness.
+- MCP calls from [Code Mode](/key-features/code-mode) scripts are bridged back to the harness — the sandbox never holds those tokens.
+- The only credentials that enter the sandbox are ones you explicitly inject for private git clones.
diff --git a/docs/skills.mdx b/docs/skills.mdx
index 873d3ea66..a5a333294 100644
--- a/docs/skills.mdx
+++ b/docs/skills.mdx
@@ -1,58 +1,16 @@
---
-title: 'Skills'
+title: 'Setup Skills'
sidebarTitle: 'Skills'
-description: 'Teach agents specialized procedures with git-backed SKILL.md instruction packs, loaded on demand at runtime.'
+description: 'Register git-backed SKILL.md instruction packs from the shipped catalog or your own repository.'
---
-Skills are reusable capability bundles that teach an agent how to perform specialized tasks — querying a database, triaging an alert, following an escalation playbook, or drafting release notes.
+Skills teach an agent how to perform specialized tasks — querying a database, triaging an alert, following an escalation playbook, or drafting release notes.
-In TrueForge, a skill is a **directory in a git repository** rooted at a `SKILL.md` file. You register skills once — in the UI under **Settings → Skills** or via the settings API — and attach them to agents by name.
-
-## What a skill contains
-
-A skill is a directory with a `SKILL.md` file (YAML frontmatter with `name` and `description`, plus a markdown body of instructions) and any supporting files:
-
-```text
-customer-support-skill/
-├── SKILL.md
-├── references/
-│ └── escalation-policy.md
-└── scripts/
- └── classify_ticket.py
-```
-
-The `description` is what the agent sees upfront to decide whether the skill is relevant. The full body — and the supporting files — are only read when the agent picks the skill. This **progressive disclosure** keeps context lean while giving the agent access to detailed procedures on demand.
+A skill is a **directory in a git repository** rooted at a `SKILL.md` file. Register skills once under **Settings → Skills**, then attach them by name when you [create an agent](/create-agent/overview).
## Registering a skill
-A skill manifest points at a GitHub or GitLab repository:
-
-```json
-{
- "type": "git",
- "name": "customer-support",
- "url": "https://github.com/your-org/agent-skills",
- "path": "skills/customer-support",
- "ref": "main",
- "description": "Triage and respond to customer support tickets following the escalation policy."
-}
-```
-
-| Field | Description |
-| ------------- | ------------------------------------------------------------------------------- |
-| `type` | `git` — the skill lives in a git repository. |
-| `name` | How agents reference the skill. Also the directory name inside the sandbox. |
-| `url` | HTTPS URL of a GitHub or GitLab repository. |
-| `path` | Optional path to the skill directory within the repo. Omit for the repo root. |
-| `ref` | Branch name, tag, or commit SHA. **Pin a tag or SHA for production stability.** |
-| `description` | Concise guidance for when the agent should use the skill. |
-
-Register it with `PUT /api/v1/settings/skills` (or through the UI). Starter skills are available in the catalog at `GET /api/v1/settings/skills/catalog`.
-
-<Tip>
- Because `ref` can be a branch, tag, or commit SHA, you get versioning through git itself: pin production agents to a
- tag or SHA, test changes on a branch, and roll back by changing the ref.
-</Tip>
+Open **Settings → Skills**, pick a starter skill from the catalog, or add your own GitHub/GitLab repository (URL, optional path, and ref). Pin a tag or commit SHA for production stability.
<div style={{ position: "relative", boxSizing: "content-box", width: "100%", aspectRatio: "1.75", padding: "40px 0" }}>
<iframe
@@ -65,53 +23,50 @@ Register it with `PUT /api/v1/settings/skills` (or through the UI). Starter skil
/>
</div>
-## Attaching skills to an agent
+## Where the skills list comes from
-Agents reference skills by name only:
+Starter skills under **Settings → Skills** come from a shipped catalog YAML:
-```json
-{
- "skills": [{ "name": "customer-support" }],
- "config": {
- "sandbox": { "enabled": true }
- }
-}
+[`skill-catalog.yaml`](https://github.com/truefoundry/trueforge/blob/main/packages/server/src/catalog/skill-catalog.yaml)
+
+Each entry points at a git repo (and optional path/ref) with a short description. To change which presets appear, see [Initial Setup](/harness/initial-setup#changing-what-the-ui-offers).
+
+## What a skill contains
+
+```text
+customer-support-skill/
+├── SKILL.md
+├── references/
+│ └── escalation-policy.md
+└── scripts/
+ └── classify_ticket.py
```
-<Note>
- Skills require the agent's **[sandbox](/sandbox)** to be enabled — the skill repository is cloned into the sandbox, and the agent reads `SKILL.md` and runs any bundled scripts there. Session creation rejects agents that attach skills without a sandbox (check `GET /api/v1/capabilities` to see whether a sandbox provider is configured).
+`SKILL.md` has YAML frontmatter (`name`, `description`) and a markdown body of instructions. The `description` is what the agent sees upfront; the full body and supporting files load only when the agent picks the skill (**progressive disclosure**).
-Two skills cannot share the same `name` within a single agent.
+## Runtime requirements
+<Note>
+ Skills require the agent's [sandbox](/sandbox) to be enabled. The skill repository is cloned into the sandbox, and the
+ agent reads `SKILL.md` (and can run bundled scripts) there. Two skills cannot share the same name on one agent.
</Note>
-## How skills are used at runtime
-
-1. At startup, the harness exposes each attached skill's `name` and `description` to the model.
-2. When the model decides a skill is relevant, the skill's repository is materialized in the sandbox under `/opt/tfy/skills/{name}`.
-3. The agent reads `SKILL.md`, follows its instructions, and accesses supporting files or runs bundled scripts as needed.
+At runtime:
-```mermaid
-flowchart LR
- Start[Turn starts] --> Meta[Skill name + description in context]
- Meta --> Decide{Skill relevant?}
- Decide -->|No| Skip[Skill body never enters context]
- Decide -->|Yes| Mount[Clone into sandbox at /opt/tfy/skills/name]
- Mount --> Read[Agent reads SKILL.md and follows it]
-```
+1. The harness exposes each attached skill's name and description.
+2. When the model decides a skill is relevant, the repo is materialized under `/opt/tfy/skills/{name}`.
+3. The agent follows `SKILL.md` and uses supporting files as needed.
## Skills + MCP tools
-Skills and MCP tools are complementary:
-
-- **Skills** define _how_ to handle a task — the procedure, decision logic, and formatting rules.
-- **MCP tools** provide the _actions and data_ needed to execute it.
+- **Skills** define _how_ to handle a task (procedure, decision logic, formatting).
+- **MCP tools** provide the _actions and data_ to execute it.
-Example: a "CRM follow-up" skill instructs the agent on decision logic and message tone, while MCP tools handle record lookup, ticket update, and Slack notification.
+Example: a CRM follow-up skill sets tone and escalation rules; MCP tools look up the record, update the ticket, and notify Slack.
-## Authoring guidelines
+## Authoring tips
-- Keep the `description` sharp — it is the only thing the model sees before deciding to load the skill.
-- Write `SKILL.md` like instructions to a competent new teammate: the workflow, the edge cases, the output format.
-- Move heavy reference material into supporting files the skill links to, so the agent reads them only when needed.
-- Prefer several focused skills over one sprawling skill — the agent composes them per task.
+- Keep the `description` sharp — it is the only thing the model sees before loading the skill.
+- Write `SKILL.md` like instructions to a competent teammate.
+- Put heavy reference material in supporting files the skill links to.
+- Prefer several focused skills over one sprawling pack.