diff --git a/adk/advanced/hitl.mdx b/adk/advanced/hitl.mdx
index a67867c1..afce21d5 100644
--- a/adk/advanced/hitl.mdx
+++ b/adk/advanced/hitl.mdx
@@ -7,11 +7,11 @@ description: Escalate conversations to live human agents.
   This covers the HITL integration and plugin, which connects your agent to external helpdesk platforms (Zendesk, Intercom, etc.). This is separate from integrating your ADK agent with [Botpress Desk](/desk/introduction).
 </Info>
 
-HITL (Human-in-the-Loop) lets your agent hand off a conversation to a live human agent. This is powered by two dependencies working together: the **HITL integration** (provides the transport to a helpdesk or agent platform) and the **HITL plugin** (provides the actions your code calls).
+HITL (Human-in-the-Loop) lets your agent hand off a conversation to a live human agent. It's powered by two dependencies working together: the **HITL integration** (the transport to a helpdesk or agent platform) and the **HITL plugin** (the actions your code calls).
 
-## Setup
+## Add HITL to your agent
 
-Add both the integration and plugin to `agent.config.ts`:
+Add both the integration and the plugin to `agent.config.ts`. The plugin's `dependencies` block points at the integration by alias:
 
 ```typescript
 import { defineConfig } from "@botpress/runtime"
@@ -26,9 +26,9 @@ export default defineConfig({
 
   dependencies: {
     integrations: {
-      chat: { version: "chat@0.7.3", enabled: true },
-      webchat: { version: "webchat@0.3.0", enabled: true },
-      hitl: { version: "hitl@2.0.2", enabled: true },
+      chat: "chat@1.0.0",
+      webchat: "webchat@0.3.0",
+      hitl: "hitl@2.0.2",
     },
 
     plugins: {
@@ -46,44 +46,13 @@ export default defineConfig({
 })
 ```
 
-### How the plugin wiring works
+`integrationAlias` must match a key in `dependencies.integrations`. The ADK validates this at build time, so a typo here fails fast. `integrationInterfaceAlias` tells the plugin which interface entity the integration implements (`hitlSession` for the generic HITL integration, `hitlTicket` for Zendesk, and so on).
 
-The `plugins` block connects the plugin to the integration:
+The HITL plugin also accepts a top-level `config` object for plugin-wide behavior. See the HITL plugin's Hub listing for the full set of fields.
 
-```typescript
-plugins: {
-  hitl: {
-    version: "hitl@1.3.0",
-    dependencies: {
-      hitl: {
-        integrationAlias: "hitl",           // Must match a key in dependencies.integrations
-        integrationInterfaceAlias: "hitl<hitlSession>",
-      },
-    },
-  },
-},
-```
-
-`integrationAlias` tells the plugin which installed integration to use. It must match a key in `dependencies.integrations`. The ADK validates this at build time.
-
-### Optional plugin config
-
-```typescript
-plugins: {
-  hitl: {
-    version: "hitl@1.3.0",
-    config: {
-      flowOnHitlStopped: false,
-      useHumanAgentInfo: false,
-    },
-    dependencies: { /* ... */ },
-  },
-},
-```
+## Start a handoff
 
-## Starting a handoff
-
-Import `plugins` from `@botpress/runtime` and call `startHitl`. All inputs are fully typed.
+Import `plugins` from `@botpress/runtime` and call `startHitl` from a conversation handler. All inputs are typed against the plugin:
 
 ```typescript
 import { Conversation, plugins } from "@botpress/runtime"
@@ -113,14 +82,34 @@ export default new Conversation({
 })
 ```
 
-## Using a different provider
+The fields passed to `startHitl`:
+
+| Field | Description |
+|-------|-------------|
+| `title` | Short label shown to the human agent when the ticket opens |
+| `description` | Longer context the human agent sees alongside the conversation |
+| `conversationId` | The conversation to hand off (use `conversation.id` from the handler) |
+| `userId` | The user initiating the handoff |
+| `configurationOverrides` | Optional per-handoff overrides of the plugin config |
+
+Common override fields:
+
+| Field | Description |
+|-------|-------------|
+| `onHitlHandoffMessage` | Message sent to the user when the handoff begins |
+| `userHitlCloseCommand` | Message text the user can send to close the session |
+| `agentAssignedTimeoutSeconds` | How long to wait for a human agent to pick up before timing out |
+
+For the full set of override fields, see the HITL plugin's Hub listing.
 
-The HITL plugin works with any integration that implements the HITL interface. To use Zendesk instead of the generic HITL integration, swap the integration and update the alias:
+## Use a different provider
+
+The HITL plugin works with any integration that implements the HITL interface. To swap the generic HITL integration for Zendesk, change the integration and update the alias. `hitlTicket` replaces `hitlSession` because Zendesk implements the interface with tickets instead of sessions:
 
 ```typescript
 dependencies: {
   integrations: {
-    zendesk: { version: "zendesk@1.0.0", enabled: true },
+    zendesk: "zendesk@1.0.0",
   },
   plugins: {
     hitl: {
@@ -136,22 +125,16 @@ dependencies: {
 },
 ```
 
-The plugin doesn't care about the specific provider, only that it implements the HITL interface.
+Your application code doesn't change. `plugins.hitl.actions.startHitl` works the same regardless of which integration is wired underneath.
 
 ## Deploy and test
 
+Run `adk deploy` to push the agent to Botpress Cloud. See the [CLI reference](/adk/cli-reference#adk-deploy) for all deploy flags:
+
 ```bash
 adk deploy
 ```
 
 <Warning>
-  HITL does not work in dev mode because conversations don't exist on the dev bot. You must deploy and test on the production bot.
+  HITL only works against a deployed bot. `adk dev` downloads the plugin into `bp_modules/` and generates types, but handoffs need the integration's real connection to your helpdesk, which is configured on the production bot.
 </Warning>
-
-When you run `adk dev`, the ADK downloads the plugin, installs it into `bp_modules/`, and generates TypeScript types. But testing the actual handoff requires a deployed bot.
-
----
-
-<Card title="CLI Reference" icon="terminal" href="/adk/cli-reference">
-  All commands and flags available with the ADK CLI.
-</Card>
diff --git a/adk/ai-native/skills.mdx b/adk/ai-native/skills.mdx
index 57e96b8b..5379036f 100644
--- a/adk/ai-native/skills.mdx
+++ b/adk/ai-native/skills.mdx
@@ -3,19 +3,19 @@ title: Skills
 description: Give AI coding assistants deep ADK knowledge with installable skills.
 ---
 
-Skills are packaged instructions and documentation that teach AI coding assistants how to build with the ADK. When installed, your assistant (Claude Code, Cursor, Codex) automatically uses them when you ask it to build features, debug issues, write evals, or connect integrations.
-
-Skills are packaged with every new ADK project. When you run `adk init`, skills are installed automatically alongside your dependencies.
+Skills are packaged instructions and documentation that teach AI coding assistants how to build with the ADK. When installed, assistants like Claude Code, Cursor, and Codex use them automatically when you ask them to build features, debug issues, write evals, or connect integrations. `adk init` installs them for you alongside your dependencies, so most projects get them out of the box.
 
 ## Manual installation
 
-If you need to install skills in an existing project or reinstall them:
+If you need to install skills in an existing project or reinstall them, run the same command `adk init` runs:
 
 ```bash
-npx skills add botpress/skills -s '*' -a claude-code codex -y
+npx skills add botpress/skills -s '*' -a codex claude-code -y
 ```
 
-Install a single skill:
+Use `bunx` instead of `npx` if your project has a `bun.lockb`.
+
+To install a single skill instead of all of them:
 
 ```bash
 npx skills add botpress/skills --skill adk
@@ -58,15 +58,17 @@ Skills come with slash commands for Claude Code. Type the command instead of des
 
 ## MCP server
 
-The ADK also includes an MCP (Model Context Protocol) server that gives assistants live access to your running project. It provides tools for querying traces, searching integrations, sending test messages, and starting workflows.
+Skills are the recommended way to give AI assistants ADK knowledge. The ADK also ships an MCP (Model Context Protocol) server that gives assistants live access to your running project, kept here for reference.
 
-Generate the MCP configuration:
+Generate the MCP configuration files:
 
 ```bash
 adk mcp:init --all
 ```
 
-This creates config files for Claude Code (`.mcp.json`), VS Code (`.vscode/mcp.json`), and Cursor (`.cursor/mcp.json`).
+This writes config for Claude Code (`.mcp.json`), VS Code (`.vscode/mcp.json`), and Cursor (`.cursor/mcp.json`). See [`adk mcp:init`](/adk/cli-reference#adk-mcpinit) for all flags.
+
+The server exposes these tools:
 
 | Tool | What it does |
 |------|-------------|
@@ -79,9 +81,4 @@ This creates config files for Claude Code (`.mcp.json`), VS Code (`.vscode/mcp.j
 | `adk_get_dev_logs` | Get dev server logs and errors |
 | `adk_list_workflows` | List available workflows |
 | `adk_start_workflow` | Start a workflow or get its input schema |
-
----
-
-<Card title="Human-in-the-loop" icon="user" href="/adk/advanced/hitl">
-  Escalate conversations to live human agents.
-</Card>
+| `adk_init_project` | Scaffold a new ADK project (only available outside an ADK project) |
diff --git a/adk/assets/actions-console-dark.png b/adk/assets/actions-console-dark.png
index 97584ea7..9f18cb44 100644
Binary files a/adk/assets/actions-console-dark.png and b/adk/assets/actions-console-dark.png differ
diff --git a/adk/assets/actions-console.png b/adk/assets/actions-console.png
index 97584ea7..925251ae 100644
Binary files a/adk/assets/actions-console.png and b/adk/assets/actions-console.png differ
diff --git a/adk/assets/agent-steps-dark.png b/adk/assets/agent-steps-dark.png
index 97584ea7..fee4fde3 100644
Binary files a/adk/assets/agent-steps-dark.png and b/adk/assets/agent-steps-dark.png differ
diff --git a/adk/assets/agent-steps.png b/adk/assets/agent-steps.png
index 97584ea7..470ab5a0 100644
Binary files a/adk/assets/agent-steps.png and b/adk/assets/agent-steps.png differ
diff --git a/adk/assets/config-variables-console-dark.png b/adk/assets/config-variables-console-dark.png
index 97584ea7..844d3307 100644
Binary files a/adk/assets/config-variables-console-dark.png and b/adk/assets/config-variables-console-dark.png differ
diff --git a/adk/assets/config-variables-console.png b/adk/assets/config-variables-console.png
index 97584ea7..f9685757 100644
Binary files a/adk/assets/config-variables-console.png and b/adk/assets/config-variables-console.png differ
diff --git a/adk/assets/environment-selector-dark.png b/adk/assets/environment-selector-dark.png
index 97584ea7..90ae5e50 100644
Binary files a/adk/assets/environment-selector-dark.png and b/adk/assets/environment-selector-dark.png differ
diff --git a/adk/assets/environment-selector.png b/adk/assets/environment-selector.png
index 97584ea7..93326e38 100644
Binary files a/adk/assets/environment-selector.png and b/adk/assets/environment-selector.png differ
diff --git a/adk/assets/evals-console-dark.png b/adk/assets/evals-console-dark.png
index 97584ea7..eef06434 100644
Binary files a/adk/assets/evals-console-dark.png and b/adk/assets/evals-console-dark.png differ
diff --git a/adk/assets/evals-console.png b/adk/assets/evals-console.png
index 97584ea7..a366230c 100644
Binary files a/adk/assets/evals-console.png and b/adk/assets/evals-console.png differ
diff --git a/adk/assets/integration-config-console-dark.png b/adk/assets/integration-config-console-dark.png
index 97584ea7..4103b9f1 100644
Binary files a/adk/assets/integration-config-console-dark.png and b/adk/assets/integration-config-console-dark.png differ
diff --git a/adk/assets/integration-config-console.png b/adk/assets/integration-config-console.png
index 97584ea7..72d598a6 100644
Binary files a/adk/assets/integration-config-console.png and b/adk/assets/integration-config-console.png differ
diff --git a/adk/assets/integrations-console-dark.png b/adk/assets/integrations-console-dark.png
index 97584ea7..9de8bc06 100644
Binary files a/adk/assets/integrations-console-dark.png and b/adk/assets/integrations-console-dark.png differ
diff --git a/adk/assets/integrations-console.png b/adk/assets/integrations-console.png
index 97584ea7..6fa808f3 100644
Binary files a/adk/assets/integrations-console.png and b/adk/assets/integrations-console.png differ
diff --git a/adk/assets/knowledge-console-dark.png b/adk/assets/knowledge-console-dark.png
index 97584ea7..843b0106 100644
Binary files a/adk/assets/knowledge-console-dark.png and b/adk/assets/knowledge-console-dark.png differ
diff --git a/adk/assets/knowledge-console.png b/adk/assets/knowledge-console.png
index 97584ea7..bd53f5e5 100644
Binary files a/adk/assets/knowledge-console.png and b/adk/assets/knowledge-console.png differ
diff --git a/adk/assets/logs-view-dark.png b/adk/assets/logs-view-dark.png
index 97584ea7..b1f6bf14 100644
Binary files a/adk/assets/logs-view-dark.png and b/adk/assets/logs-view-dark.png differ
diff --git a/adk/assets/logs-view.png b/adk/assets/logs-view.png
index 97584ea7..81b890da 100644
Binary files a/adk/assets/logs-view.png and b/adk/assets/logs-view.png differ
diff --git a/adk/assets/quickstart-dark.png b/adk/assets/quickstart-dark.png
index a4a3ea05..f0de5b90 100644
Binary files a/adk/assets/quickstart-dark.png and b/adk/assets/quickstart-dark.png differ
diff --git a/adk/assets/quickstart.png b/adk/assets/quickstart.png
index 97584ea7..51b67ffe 100644
Binary files a/adk/assets/quickstart.png and b/adk/assets/quickstart.png differ
diff --git a/adk/assets/secrets-console-dark.png b/adk/assets/secrets-console-dark.png
index 97584ea7..0198132d 100644
Binary files a/adk/assets/secrets-console-dark.png and b/adk/assets/secrets-console-dark.png differ
diff --git a/adk/assets/secrets-console.png b/adk/assets/secrets-console.png
index 97584ea7..b3b45b40 100644
Binary files a/adk/assets/secrets-console.png and b/adk/assets/secrets-console.png differ
diff --git a/adk/assets/tables-console-dark.png b/adk/assets/tables-console-dark.png
index 97584ea7..49fa1074 100644
Binary files a/adk/assets/tables-console-dark.png and b/adk/assets/tables-console-dark.png differ
diff --git a/adk/assets/tables-console.png b/adk/assets/tables-console.png
index 97584ea7..b3cbcdc8 100644
Binary files a/adk/assets/tables-console.png and b/adk/assets/tables-console.png differ
diff --git a/adk/assets/traces-view-dark.png b/adk/assets/traces-view-dark.png
index 97584ea7..ee698cc2 100644
Binary files a/adk/assets/traces-view-dark.png and b/adk/assets/traces-view-dark.png differ
diff --git a/adk/assets/traces-view.png b/adk/assets/traces-view.png
index 97584ea7..4874a360 100644
Binary files a/adk/assets/traces-view.png and b/adk/assets/traces-view.png differ
diff --git a/adk/assets/triggers-console-dark.png b/adk/assets/triggers-console-dark.png
index 97584ea7..d09b6b3e 100644
Binary files a/adk/assets/triggers-console-dark.png and b/adk/assets/triggers-console-dark.png differ
diff --git a/adk/assets/triggers-console.png b/adk/assets/triggers-console.png
index 97584ea7..4694af91 100644
Binary files a/adk/assets/triggers-console.png and b/adk/assets/triggers-console.png differ
diff --git a/adk/assets/welcome-dark.png b/adk/assets/welcome-dark.png
index eca93562..bc5ed623 100644
Binary files a/adk/assets/welcome-dark.png and b/adk/assets/welcome-dark.png differ
diff --git a/adk/assets/welcome.png b/adk/assets/welcome.png
index e5fe372e..8b0741ad 100644
Binary files a/adk/assets/welcome.png and b/adk/assets/welcome.png differ
diff --git a/adk/assets/workflows-console-dark.png b/adk/assets/workflows-console-dark.png
index 97584ea7..745b137a 100644
Binary files a/adk/assets/workflows-console-dark.png and b/adk/assets/workflows-console-dark.png differ
diff --git a/adk/assets/workflows-console.png b/adk/assets/workflows-console.png
index 97584ea7..196d0948 100644
Binary files a/adk/assets/workflows-console.png and b/adk/assets/workflows-console.png differ
diff --git a/adk/cli-reference.mdx b/adk/cli-reference.mdx
index 9cb2af21..a9987052 100644
--- a/adk/cli-reference.mdx
+++ b/adk/cli-reference.mdx
@@ -1,20 +1,27 @@
 ---
-title: CLI Reference
+title: CLI reference
 description: All commands and flags available with the ADK CLI.
 ---
 
+The `adk` CLI is how you scaffold, run, deploy, and debug ADK agents. Run `adk --help` for the top-level command list, or `adk <command> --help` for flags on a specific command.
+
 ## Global flags
 
+These flags work with every command:
+
 | Flag | Description |
 |------|-------------|
 | `--help`, `-h` | Show help information |
 | `--version`, `-V` | Show version number |
 | `--no-cache` | Disable caching for integration lookups |
+| `--profile <profile>` | Credentials profile to use (overrides the `ADK_PROFILE` env var and the current profile) |
 
-All commands support `--format json` for machine-readable output unless noted otherwise.
+Most commands also accept `--format json` for machine-readable output. The following commands don't: `dev`, `login`, `profiles list`, `profiles set`, `upgrade`, `remove`, `self-upgrade`, `telemetry`, `theme`, `mcp`, `mcp:init`, `run`, `assets pull`.
 
 ## Project
 
+These commands manage an agent project from scaffold to deploy:
+
 | Command | Description |
 |---------|-------------|
 | `adk init [name]` | Initialize a new project |
@@ -27,6 +34,8 @@ All commands support `--format json` for machine-readable output unless noted ot
 
 ### adk init
 
+Scaffold a new agent project. Pass a name, or omit it to be prompted:
+
 ```bash
 adk init my-agent
 adk init my-agent --template hello-world
@@ -35,13 +44,15 @@ adk init --list-templates
 
 | Flag | Description |
 |------|-------------|
-| `-t, --template <template>` | Template to use |
-| `-y, --yes` | Skip prompts, use defaults |
+| `-t, --template <template>` | Template to use (default: `blank`) |
+| `-y, --yes`, `--defaults` | Skip prompts, use defaults |
 | `--skip-link` | Skip the linking step |
 | `--list-templates` | List available templates and exit |
 
 ### adk dev
 
+Start the dev server with hot reload:
+
 ```bash
 adk dev
 adk dev --port 3000 --port-console 3001
@@ -51,13 +62,15 @@ adk dev --port 3000 --port-console 3001
 |------|-------------|---------|
 | `-p, --port <port>` | Bot server port | `3000` |
 | `--port-console <port>` | Dev console port | `3001` |
-| `--otlp` | Enable OTLP export to external collector | |
-| `--port-otlp <port>` | OTLP collector endpoint port | `4318` |
+| `--otlp` | Enable OTLP export to external collector (port `4318`) | |
+| `--port-otlp <port>` | Override the OTLP collector endpoint port | |
 | `-v, --verbose` | Show additional details | |
 | `--non-interactive` | Emit structured NDJSON events to stdout | |
 
 ### adk deploy
 
+Deploy the built agent to Botpress Cloud:
+
 ```bash
 adk deploy
 adk deploy -y
@@ -70,6 +83,8 @@ adk deploy -y
 
 ### adk link
 
+Link the local agent to a workspace and bot. Writes to `agent.json`, or to `agent.local.json` with `--local`:
+
 ```bash
 adk link
 adk link --workspace wkspace_123 --bot bot_456
@@ -81,22 +96,26 @@ adk link --workspace wkspace_123 --bot bot_456
 | `--bot <id>` | Bot ID to link to |
 | `--dev <id>` | Dev bot ID |
 | `--api-url <url>` | Botpress API URL |
-| `-f, --force` | Overwrite existing agent.json |
-| `--local` | Write to gitignored agent.local.json |
+| `-f, --force` | Overwrite existing `agent.json` |
+| `--local` | Write to gitignored `agent.local.json` (for multi-dev workflows) |
 
 ## Integrations
 
+These commands add, inspect, and manage the integrations your agent depends on:
+
 | Command | Description |
 |---------|-------------|
-| `adk add <resource>` | Add an integration or interface |
-| `adk remove [resource]` | Remove an integration, interface, or plugin |
-| `adk upgrade [integration]` | Upgrade integration(s) to latest version |
+| `adk add <resource>` | Add an integration or interface (aliases: `i`, `install`) |
+| `adk remove [resource]` | Remove an integration, interface, or plugin (alias: `rm`) |
+| `adk upgrade [integration]` | Upgrade integration(s) to latest version (alias: `up`) |
 | `adk search <query>` | Search the Botpress Hub |
 | `adk list` | List installed integrations |
 | `adk info <name>` | Show detailed integration info |
 
 ### adk add
 
+Add an integration or interface to your agent. Accepts a name, `workspace/name`, or a specific version:
+
 ```bash
 adk add webchat
 adk add slack@latest
@@ -110,22 +129,37 @@ adk add webchat --alias custom-webchat
 |------|-------------|
 | `--alias <alias>` | Custom alias for the resource |
 
-Aliases: `i`, `install`
+### adk search
+
+Search the Botpress Hub for integrations:
+
+```bash
+adk search crm
+adk search slack --limit 5
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--limit <number>` | Max results to return | `20` |
 
 ### adk list
 
+List integrations in your project, or all available ones on the Hub:
+
 ```bash
 adk list
 adk list --available
 ```
 
-| Flag | Description |
-|------|-------------|
-| `--available` | List all available integrations (not just installed) |
-| `--limit <n>` | Max results (default: 50) |
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--available` | List all available integrations (not just installed) | |
+| `--limit <n>` | Max results | `50` |
 
 ### adk info
 
+Show details for a specific integration. Filter by a single facet or show the full spec:
+
 ```bash
 adk info slack
 adk info slack --actions
@@ -141,6 +175,8 @@ adk info slack --full
 
 ## Configuration
 
+These commands manage config values and secrets:
+
 | Command | Description |
 |---------|-------------|
 | `adk config` | Validate and fill missing config values interactively |
@@ -151,10 +187,12 @@ adk info slack --full
 | `adk secret:delete <key>` | Delete a secret |
 | `adk models` | List available LLM models |
 
-All configuration and secret commands accept `--prod` to target the production environment.
+All configuration and secret commands accept `--prod` to target the production environment instead of dev.
 
 ## Chat and testing
 
+These commands let you send messages to your agent and run eval suites:
+
 | Command | Description |
 |---------|-------------|
 | `adk chat` | Interactive chat with your agent |
@@ -163,6 +201,8 @@ All configuration and secret commands accept `--prod` to target the production e
 
 ### adk chat
 
+Open an interactive chat, or send a single message with `--single`. Requires `adk dev` to be running:
+
 ```bash
 adk chat
 adk chat --single "What's the status of order 12345?"
@@ -175,10 +215,10 @@ adk chat --single "Follow up" --conversation-id <id>
 | `--conversation-id <id>` | Continue a conversation | |
 | `--timeout <duration>` | Max wait duration | `60s` |
 
-Requires `adk dev` to be running.
-
 ### adk evals
 
+Run eval suites. With no arguments, runs all evals; pass a name to run just one:
+
 ```bash
 adk evals
 adk evals greeting
@@ -187,30 +227,34 @@ adk evals --type regression
 adk evals -v
 ```
 
-| Flag | Description |
-|------|-------------|
-| `--tag <tag>` | Run only evals with this tag |
-| `--type <type>` | Run only `capability` or `regression` evals |
-| `--judge-model <model>` | Model for llm_judge assertions |
-| `-v, --verbose` | Show full details for all evals |
-| `--server <url>` | Dev server URL (default: http://localhost:3001) |
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--tag <tag>` | Run only evals with this tag | |
+| `--type <type>` | Run only `capability` or `regression` evals | |
+| `--judge-model <model>` | Model for `llm_judge` assertions | |
+| `-v, --verbose` | Show full details for all evals | |
+| `--server <url>` | Dev server URL | `http://localhost:3001` |
 
 ### adk evals runs
 
+List past eval runs, or show the details of a specific one:
+
 ```bash
 adk evals runs
 adk evals runs --latest
 adk evals runs <run-id> -v
 ```
 
-| Flag | Description |
-|------|-------------|
-| `--latest` | Show the latest run |
-| `--limit <n>` | Max runs to list (default: 10) |
-| `-v, --verbose` | Show full details |
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--latest` | Show the latest run | |
+| `--limit <n>` | Max runs to list | `10` |
+| `-v, --verbose` | Show full details | |
 
 ## Workflows
 
+These commands discover and run workflows against the local dev server:
+
 | Command | Description |
 |---------|-------------|
 | `adk workflows` | List all discovered workflows |
@@ -219,6 +263,8 @@ adk evals runs <run-id> -v
 
 ### adk workflows run
 
+Run a workflow with a JSON payload. Add `--wait` to block until it finishes:
+
 ```bash
 adk workflows run onboarding '{"userId":"123"}'
 adk workflows run onboarding '{"userId":"123"}' --wait --timeout 30s
@@ -227,10 +273,12 @@ adk workflows run onboarding '{"userId":"123"}' --wait --timeout 30s
 | Flag | Description |
 |------|-------------|
 | `--wait` | Wait for the workflow to finish |
-| `--timeout <duration>` | Max wait duration (implies --wait) |
+| `--timeout <duration>` | Max wait duration (implies `--wait`) |
 
 ## Debugging
 
+These commands help you inspect what your agent is doing:
+
 | Command | Description |
 |---------|-------------|
 | `adk logs [tokens...]` | Query dev server logs |
@@ -239,6 +287,8 @@ adk workflows run onboarding '{"userId":"123"}' --wait --timeout 30s
 
 ### adk logs
 
+Query logs from `.adk/logs/`. Pass filter tokens as positional arguments, or stream with `--follow`:
+
 ```bash
 adk logs
 adk logs error
@@ -252,8 +302,8 @@ adk logs --follow limit=10
 | `error` | Show errors only |
 | `warning` | Show errors + warnings |
 | `info` | Show errors + warnings + info |
-| `since=<duration>` | Only entries newer than duration (e.g. 30s, 5m, 1h) |
-| `limit=<n>` | Max entries to show (default: 50) |
+| `since=<duration>` | Only entries newer than duration (e.g. `30s`, `5m`, `1h`) |
+| `limit=<n>` | Max entries to show (default: `50`) |
 
 | Flag | Description |
 |------|-------------|
@@ -262,6 +312,8 @@ adk logs --follow limit=10
 
 ### adk traces
 
+Query trace data from the local store. Filter tokens narrow by workflow, action, trigger, or drill into a specific trace:
+
 ```bash
 adk traces
 adk traces error
@@ -282,7 +334,7 @@ adk traces --follow
 | `trace=<id>` | Drill into a specific trace |
 | `since=<duration>` | Only traces newer than duration |
 | `until=<duration>` | Only traces older than duration |
-| `limit=<n>` | Max traces to show (default: 20) |
+| `limit=<n>` | Max traces to show (default: `20`) |
 
 | Flag | Description |
 |------|-------------|
@@ -291,6 +343,8 @@ adk traces --follow
 
 ### adk run
 
+Run a TypeScript script with the full ADK runtime, so you can import actions, Zai, and tables directly:
+
 ```bash
 adk run scripts/migrate.ts
 adk run scripts/seed.ts --prod
@@ -300,14 +354,20 @@ adk run scripts/process.ts arg1 arg2
 | Flag | Description |
 |------|-------------|
 | `-f, --force` | Force regeneration of the bot project |
-| `--prod` | Use production bot |
+| `--prod` | Use production bot (default: dev) |
+
+## Knowledge bases
 
-## Knowledge
+Sync local knowledge base content with Botpress:
 
 | Command | Description |
 |---------|-------------|
 | `adk kb sync` | Synchronize knowledge bases with Botpress |
 
+### adk kb sync
+
+Push local KB sources to the dev or prod bot. Use `--dry-run` to preview changes first:
+
 ```bash
 adk kb sync --dev
 adk kb sync --prod
@@ -325,6 +385,8 @@ adk kb sync --dry-run
 
 ## Assets
 
+Manage static files your agent serves or references:
+
 | Command | Description |
 |---------|-------------|
 | `adk assets sync` | Synchronize assets with remote storage |
@@ -334,6 +396,14 @@ adk kb sync --dry-run
 
 ### adk assets sync
 
+Upload local assets to remote storage. Use `--dry-run` to see what would change:
+
+```bash
+adk assets sync
+adk assets sync --dry-run
+adk assets sync --force -y
+```
+
 | Flag | Description |
 |------|-------------|
 | `--dry-run` | Preview changes without applying |
@@ -343,6 +413,14 @@ adk kb sync --dry-run
 
 ### adk assets list
 
+List asset files. By default shows both local and remote; filter with `--local` or `--remote`:
+
+```bash
+adk assets list
+adk assets list --local
+adk assets list --remote
+```
+
 | Flag | Description |
 |------|-------------|
 | `--local` | Show only local assets |
@@ -350,13 +428,31 @@ adk kb sync --dry-run
 
 ## AI assistants
 
+These commands integrate the ADK with AI coding tools:
+
 | Command | Description |
 |---------|-------------|
 | `adk mcp` | Start the MCP server |
 | `adk mcp:init` | Generate MCP configuration files |
 
+### adk mcp
+
+Start the MCP server so tools like Claude Code, Cursor, or VS Code can talk to your running dev server:
+
+```bash
+adk mcp
+adk mcp --port 3001
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--cwd <path>` | Working directory for MCP operations | |
+| `--port <port>` | UI server port to connect to | `3001` |
+
 ### adk mcp:init
 
+Generate MCP configuration files for supported AI assistants:
+
 ```bash
 adk mcp:init --all
 adk mcp:init --tool claude-code
@@ -372,29 +468,68 @@ adk mcp:init --tool vscode cursor
 
 ## Account
 
+These commands manage your Botpress credentials and the CLI itself:
+
 | Command | Description |
 |---------|-------------|
 | `adk login` | Authenticate with Botpress |
 | `adk profiles list` | List authentication profiles |
 | `adk profiles set [profile]` | Switch to a different profile |
-| `adk self-upgrade [tag]` | Upgrade ADK CLI to latest (or specific) version |
+| `adk self-upgrade [tag]` | Upgrade ADK CLI to latest (or specific) version (alias: `self-update`) |
 | `adk telemetry` | Manage telemetry preferences |
 | `adk theme` | Manage CLI theme (dark/light) |
 
 ### adk login
 
-| Flag | Description |
-|------|-------------|
-| `--token <token>` | Botpress API token |
-| `--profile <profile>` | Profile name to save credentials under |
-| `--api-url <url>` | Botpress API URL |
+Authenticate with your Botpress account. Pass `--token` to skip the browser flow:
+
+```bash
+adk login
+adk login --token <token>
+adk login --profile staging
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--token <token>` | Botpress API token | |
+| `--profile <profile>` | Profile name to save credentials under | |
+| `--api-url <url>` | Botpress API URL | `https://api.botpress.cloud` |
 
 ### adk self-upgrade
 
+Upgrade the ADK CLI. Pass a tag (`beta`, `next`) or an explicit version:
+
 ```bash
 adk self-upgrade
 adk self-upgrade beta
 adk self-upgrade 1.18.0
 ```
 
-Aliases: `self-update`
+### adk telemetry
+
+View or change telemetry preferences. With no flags, prints the current status:
+
+```bash
+adk telemetry
+adk telemetry --enable
+adk telemetry --disable
+```
+
+| Flag | Description |
+|------|-------------|
+| `--status` | Show telemetry status |
+| `--enable` | Enable telemetry |
+| `--disable` | Disable telemetry |
+
+### adk theme
+
+Switch the CLI theme between dark and light:
+
+```bash
+adk theme --set dark
+adk theme --set light
+```
+
+| Flag | Description |
+|------|-------------|
+| `--set <theme>` | Set theme (`dark` or `light`) |
diff --git a/adk/conversations/ai-execution.mdx b/adk/conversations/ai-execution.mdx
index 9c990173..19c9c8cf 100644
--- a/adk/conversations/ai-execution.mdx
+++ b/adk/conversations/ai-execution.mdx
@@ -1,15 +1,21 @@
 ---
 title: Run AI agents in a conversation
-description: Use execute() to hand messages to the AI model.
+description: Use `execute()` to hand messages to the AI model.
 ---
 
-`execute()` is the primary way your agent responds to users. It starts an AI loop that iterates until the model reaches a conclusion. On each iteration, the model can read the conversation, call tools, and generate code. The loop ends when the model sends a message to the user (and waits for a reply), triggers an exit, or hits the iteration limit (default 10, configurable).
+The `execute()` function is the primary way your agent responds to users. It starts an AI loop that iterates until the model reaches a conclusion. On each iteration, the model can read the conversation, call tools, and generate code.
 
-The `await` resolves once the loop finishes. Under the hood, `execute()` is powered by [llmz](https://github.com/botpress/botpress/tree/master/packages/llmz).
+The loop ends when the model sends a message to the user (and waits for a reply), triggers an exit, or hits the iteration limit (which defaults to 10 and is configurable).
+
+The `await` resolves once the loop finishes.
+
+<Note>
+Under the hood, `execute()` is powered by [LLMz](https://github.com/botpress/botpress/tree/master/packages/llmz).
+</Note>
 
 ## Basic usage
 
-```typescript
+```typescript highlight={4-6}
 export default new Conversation({
   channel: "webchat.channel",
   handler: async ({ execute }) => {
@@ -24,13 +30,15 @@ The model reads the full conversation transcript, follows your instructions, and
 
 ## Instructions
 
-Instructions tell the model how to behave. They can be a static string or a function that returns a string:
+Pass instructions into the `instructions` field to tell the model how to behave. They can be a static string or a function that returns a string:
 
-```typescript
+```typescript highlight={3, 8-13}
+// String
 await execute({
   instructions: "You are a helpful assistant that speaks formally.",
 })
 
+// Function that returns a string
 await execute({
   instructions: () => {
     const hour = new Date().getHours()
@@ -45,25 +53,29 @@ Instructions are evaluated fresh on each execution. Use a function when you need
 
 ## Knowledge
 
-Attach knowledge bases to give the model access to your documents:
+Pass knowledge bases into the `knowledge` field to give the model access to your documents:
 
-```typescript
+```typescript highlight={6}
 import { DocsKB } from "../knowledge/docs"
-import { FAQKB } from "../knowledge/faq"
+import { FaqKB } from "../knowledge/faq"
 
 await execute({
   instructions: "Answer questions using the documentation.",
-  knowledge: [DocsKB, FAQKB],
+  knowledge: [DocsKB, FaqKB],
 })
 ```
 
-The model automatically searches the knowledge bases when it needs information. Results include citations that trace back to the source documents. See [Knowledge bases](/adk/data/knowledge) for how to define them.
+The model automatically searches the knowledge bases when it needs information. Results include citations that trace back to the source documents.
+
+<Tip>
+  For more information on defining knowledge bases, check out the [Knowledge base documentation](/adk/data/knowledge).
+</Tip>
 
 ## Tools
 
-Give the model functions it can call:
+Give the model functions it can call by passing them into the `tools` field:
 
-```typescript
+```typescript highlight={6}
 import { getWeather } from "../tools/weather"
 import { createTicket } from "../tools/ticket"
 
@@ -77,7 +89,7 @@ The model decides when to call a tool based on the conversation. For a full guid
 
 ## Exits
 
-Exits let the model end execution with a structured result:
+Pass in `exits` to let the model end execution with a structured result:
 
 ```typescript
 import { Autonomous, z } from "@botpress/runtime"
@@ -104,7 +116,7 @@ if (result.exit?.name === "handoffToHuman") {
 
 ## Model override
 
-Override the default model for a specific execution:
+You can override the default model for a specific execution:
 
 ```typescript
 await execute({
@@ -126,6 +138,8 @@ The default model is set in `agent.config.ts` under `defaultModels.autonomous`.
 
 ## Temperature and reasoning
 
+To control the model's temperature and reasoning effort, use the `temperature` and `reasoningEffort` props:
+
 ```typescript
 await execute({
   instructions: "You are a helpful assistant.",
@@ -150,7 +164,22 @@ await execute({
 })
 ```
 
-Defaults to 10, clamped between 1 and 100.
+The number of iterations defaults to 10 and is clamped between 1 and 100.
+
+## Cancellation
+
+Pass an `AbortSignal` to cancel execution mid-loop. Useful when the caller needs to bail out (e.g. a timeout or the user navigating away):
+
+```typescript
+const controller = new AbortController()
+
+setTimeout(() => controller.abort(), 30_000)
+
+await execute({
+  instructions: "You are a helpful assistant.",
+  signal: controller.signal,
+})
+```
 
 ## Mode
 
@@ -164,7 +193,7 @@ await execute({
 })
 ```
 
-In worker mode, the model processes without sending messages to the conversation.
+In worker mode, the model executes without sending messages to the conversation.
 
 ## Hooks
 
@@ -212,17 +241,9 @@ await execute({
 
 ## Debugging execution
 
-The dev console **Traces** view shows you exactly what happened during execution: which tools were called, what the model generated, how many iterations it took, and any errors.
+To see exactly what happened during an execution (which tools were called, what the model generated, how many iterations it took, and any errors), see [Debug with logs and traces](/adk/testing/debugging).
 
 <Frame>
   <img alt="Traces view in dev console" className="block dark:hidden" src="../assets/traces-view.png" />
   <img alt="Traces view in dev console" className="hidden dark:block" src="../assets/traces-view-dark.png" />
 </Frame>
-
----
-
-Next, learn how to define tools the AI model can call.
-
-<Card title="Define Tools" icon="wrench" href="/adk/conversations/tools">
-  Give the AI functions it can call during execution.
-</Card>
diff --git a/adk/conversations/custom-components.mdx b/adk/conversations/custom-components.mdx
index e3586939..1b6bbc08 100644
--- a/adk/conversations/custom-components.mdx
+++ b/adk/conversations/custom-components.mdx
@@ -220,11 +220,3 @@ During `adk dev`, the file watcher rebuilds only changed components incrementall
 | Styles look wrong | Using CSS classes | Switch to inline styles |
 | A prop is `undefined` | Reserved prop name (e.g., `status`) | Rename to something specific (e.g., `ticketStatus`) |
 | TypeScript errors on `.bp.tsx` | Missing tsconfig settings | Add `"jsx": "react"`, `"allowImportingTsExtensions": true`, and `"noEmit": true` |
-
----
-
-Next, learn how to manage conversation sessions with nudges and expiration.
-
-<Card title="Manage conversation lifecycle" icon="timer" href="/adk/conversations/lifecycle">
-  Nudges, expiration, and session management.
-</Card>
diff --git a/adk/conversations/lifecycle.mdx b/adk/conversations/lifecycle.mdx
index 4cffc766..99c156df 100644
--- a/adk/conversations/lifecycle.mdx
+++ b/adk/conversations/lifecycle.mdx
@@ -52,7 +52,7 @@ export default new Conversation({
 
 A nudge is an automated reminder sent when the user has been silent for a configured duration. Nudges are:
 
-- **Configurable** - you set when the first one fires (`after`), how often to repeat (`interval`), and when to stop (`max`)
+- **Configurable** - you set when the first one fires (`after`), how often to repeat (`interval`, defaults to `after` if omitted), and when to stop (`max`, unlimited if omitted)
 - **Auto-resetting** - any user message resets the nudge timer
 - **Handler-controlled** - the framework decides when to nudge, you decide what to say
 - **Workflow-aware** - nudges are automatically suppressed while a workflow is running
@@ -193,11 +193,3 @@ lifecycle: {
 - **Session data survives expiration.** `session.number` persists. Only user state and transcript are cleared.
 - **No behavior change without opt-in.** Conversations without `lifecycle` work exactly as before.
 - **Lifecycle events are invisible to the LLM.** Nudge and expire events are not added to the transcript. Only your handler's `send()` calls appear in the conversation history.
-
----
-
-Next, learn how to persist data across conversations with state.
-
-<Card title="Manage states" icon="database" href="/adk/conversations/state">
-  Conversation, bot, and user state.
-</Card>
diff --git a/adk/conversations/messages.mdx b/adk/conversations/messages.mdx
index 2f9dbe9b..174dc1b7 100644
--- a/adk/conversations/messages.mdx
+++ b/adk/conversations/messages.mdx
@@ -32,7 +32,8 @@ The available message types depend on the channel. For webchat, the following ty
 | `choice` | `{ text, options, disableFreeText? }` | Quick reply buttons |
 | `dropdown` | `{ text, options, disableFreeText? }` | Dropdown select menu |
 | `bloc` | `{ items }` | A group of mixed message types sent together |
-| `custom` | `{ url, name, data? }` | Custom rendered component (see [Use custom components](/adk/conversations/custom-components)) |
+| `custom` | `{ url, name, data? }` | Raw custom message referencing a bundled component by URL |
+| `customComponent` | `{ component, props }` | Send a [custom component](/adk/conversations/custom-components) directly. The runtime rewrites this into a `custom` message under the hood, so you get type-checked props instead of a raw URL |
 
 Other channels (Slack, WhatsApp, Telegram) support different subsets. When you specify a channel on your conversation, TypeScript will only allow the message types that channel supports.
 
@@ -166,11 +167,3 @@ handler: async ({ execute, conversation, type }) => {
 ```
 
 Direct sends and AI-generated messages appear in the same conversation.
-
----
-
-Next, learn how to render custom React components in webchat.
-
-<Card title="Use custom components" icon="component" href="/adk/conversations/custom-components">
-  Build and render React UI inside webchat.
-</Card>
diff --git a/adk/conversations/setup.mdx b/adk/conversations/setup.mdx
index 38f0c1a9..27a0c698 100644
--- a/adk/conversations/setup.mdx
+++ b/adk/conversations/setup.mdx
@@ -24,29 +24,56 @@ export default new Conversation({
 
 This is the simplest possible conversation. It matches all channels and hands every message to the AI model with a system instruction.
 
-You can test your conversation using the **Chat** page in the dev console. This requires the webchat integration. If it's not installed, the Chat page will prompt you to add it.
+You can test your conversation using the **Chat** page in the dev console. This requires the webchat integration, so install it first with `adk add webchat`.
 
 <Frame>
-  <img alt="Chat page in dev console" className="block dark:hidden" src="../assets/conversations-chat.png" />
-  <img alt="Chat page in dev console" className="hidden dark:block" src="../assets/conversations-chat-dark.png" />
+  <img alt="Chat page in dev console" className="block dark:hidden" src="../assets/agent-steps.png" />
+  <img alt="Chat page in dev console" className="hidden dark:block" src="../assets/agent-steps-dark.png" />
 </Frame>
 
 ## Channel matching
 
 The `channel` field determines which integration channels this conversation handles:
 
-```typescript
-// Match all channels
-channel: "*"
-
-// Match a specific channel
-channel: "webchat.channel"
-
-// Match multiple channels
-channel: ["webchat.channel", "chat.channel"]
-```
-
-When you use `"*"`, the handler runs for any channel but `message` and `event` are typed as `unknown`. Specifying a channel gives you strict types on message payloads, event payloads, and the conversation instance:
+<CodeGroup>
+  ```ts All channels highlight={2} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
+  export default new Conversation({
+    channel: "*",
+    handler: async ({ execute }) => {
+      await execute({
+        instructions: "You are a helpful assistant.",
+      });
+    },
+  });
+  ```
+
+  ```ts Specific channel highlight={2} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
+  export default new Conversation({
+    channel: "webchat.channel",
+    handler: async ({ execute }) => {
+      await execute({
+        instructions: "You are a helpful assistant.",
+      });
+    },
+  });
+  ```
+
+  ```ts Array of channels highlight={2-5} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
+  export default new Conversation({
+    channel: [
+      "chat.channel",
+      "webchat.channel"
+    ],
+    handler: async ({ execute }) => {
+      await execute({
+        instructions: "You are a helpful assistant.",
+      });
+    },
+  });
+  ```
+</CodeGroup>
+
+When you use `"*"`, the handler runs for any channel, but `message` and `event` are typed as `unknown`. Specifying a channel gives you strict types on message payloads, event payloads, and the conversation instance:
 
 ```typescript
 // channel: "*" — message.payload is unknown
@@ -165,7 +192,7 @@ Events use the format `"integration:eventName"` for integration events, or just
 
 Each conversation can declare its own state schema, separate from the bot and user state in `agent.config.ts`:
 
-```typescript
+```typescript highlight={3-6}
 export default new Conversation({
   channel: "webchat.channel",
   state: z.object({
@@ -182,12 +209,8 @@ export default new Conversation({
 })
 ```
 
-Conversation state is automatically persisted between handler calls. For more on state scopes (conversation vs bot vs user), see [Manage states](/adk/conversations/state).
-
----
-
-Next, learn how to run the AI model inside a conversation.
+Conversation state is automatically persisted between handler calls.
 
-<Card title="Run AI agents in a conversation" icon="sparkles" href="/adk/conversations/ai-execution">
-  Use execute() to hand messages to the AI model.
-</Card>
+<Tip>
+For more information about state scopes (conversation vs. bot vs. user), check out our guide on [managing states](/adk/conversations/state).
+</Tip>
diff --git a/adk/conversations/state.mdx b/adk/conversations/state.mdx
index 75841f99..3b1a7b02 100644
--- a/adk/conversations/state.mdx
+++ b/adk/conversations/state.mdx
@@ -215,11 +215,3 @@ import { bot, user } from "@botpress/runtime"
 const botId = bot.id
 const userId = user.id
 ```
-
----
-
-That wraps up the conversations section. Next, learn how to build workflows for long-running background processes.
-
-<Card title="Create workflows" icon="workflow" href="/adk/workflows/create">
-  Multi-step background processes that run independently.
-</Card>
diff --git a/adk/conversations/tools.mdx b/adk/conversations/tools.mdx
index 0c80be82..8fdcd9fa 100644
--- a/adk/conversations/tools.mdx
+++ b/adk/conversations/tools.mdx
@@ -1,5 +1,5 @@
 ---
-title: Define Tools
+title: Define tools
 description: Give the AI model functions it can call during execution.
 ---
 
@@ -39,7 +39,7 @@ The `input` and `output` schemas use Zod. Use `.describe()` on each field so the
 
 Pass tools to `execute()` via the `tools` array:
 
-```typescript
+```typescript highlight={10}
 import { Conversation } from "@botpress/runtime"
 import getWeather from "../tools/weather"
 import createTicket from "../tools/ticket"
@@ -61,7 +61,7 @@ The model decides which tools to call based on the conversation. It can call mul
 
 You can define tools directly inside a handler without creating a separate file:
 
-```typescript
+```typescript highlight={6-15, 19}
 import { Autonomous, z, Conversation } from "@botpress/runtime"
 
 export default new Conversation({
@@ -86,7 +86,7 @@ export default new Conversation({
 })
 ```
 
-This is useful for tools that are only relevant to a single conversation.
+This is useful for tools that are only relevant to a single type of conversation.
 
 ## Writing good descriptions
 
@@ -115,7 +115,7 @@ Tools can throw signals to influence the AI loop without returning a normal resu
 
 ### ThinkSignal
 
-Throws context back into the model's reasoning without producing a tool output. Useful when a tool finds no results and you want the model to try a different approach:
+A `ThinkSignal` throws context back into the model's reasoning without producing a tool output. This is useful when a tool finds no results and you want the model to try a different approach:
 
 ```typescript
 import { Autonomous } from "@botpress/runtime"
@@ -136,9 +136,11 @@ handler: async ({ query }) => {
 
 ## Actions as tools
 
-Actions are reusable functions that can be called from anywhere in your agent (conversations, workflows, other actions, or external API clients). Unlike standalone tools, which only exist inside `execute()`, actions are shared primitives. You can convert any action into a tool:
+Actions are reusable functions that can be called from anywhere in your agent—conversations, workflows, other actions, or external API clients. Tools only work inside `execute()`, where the AI model decides when to call them based on the conversation.
 
-```typescript
+You can convert any action into a tool by calling its `asTool()` method and passing it into `tools`:
+
+```typescript highlight={8}
 import { Conversation, actions } from "@botpress/runtime"
 
 export default new Conversation({
@@ -152,13 +154,15 @@ export default new Conversation({
 })
 ```
 
-See [Build Actions](/adk/external/actions) for how to define actions.
+<Tip>
+  Check out our guide on [building actions](/adk/external/actions) for more information.
+</Tip>
 
 ## Workflows as tools
 
 Workflows are long-running background processes that can span multiple steps and run independently of the conversation. Converting a workflow to a tool lets the model kick one off:
 
-```typescript
+```typescript highlight={9}
 import { Conversation } from "@botpress/runtime"
 import orderWorkflow from "../workflows/order"
 
@@ -173,13 +177,15 @@ export default new Conversation({
 })
 ```
 
-See [Create workflows](/adk/workflows/create) for how to define workflows.
+<Tip>
+  Check out our guide on [creating workflows](/adk/workflows/create) for more information.
+</Tip>
 
 ## Calling actions from tools
 
 Tools can call actions for reusable logic:
 
-```typescript
+```typescript highlight={8}
 import { Autonomous, actions, z } from "@botpress/runtime"
 
 export default new Autonomous.Tool({
@@ -192,11 +198,3 @@ export default new Autonomous.Tool({
   },
 })
 ```
-
----
-
-Next, learn how to send messages and content directly from your handler.
-
-<Card title="Send messages and content" icon="message-circle" href="/adk/conversations/messages">
-  Send text, images, carousels, and more.
-</Card>
diff --git a/adk/data/knowledge.mdx b/adk/data/knowledge.mdx
index cc07acb7..3c493dec 100644
--- a/adk/data/knowledge.mdx
+++ b/adk/data/knowledge.mdx
@@ -3,9 +3,9 @@ title: Knowledge bases
 description: Give your agent access to documents, websites, and files via RAG.
 ---
 
-Knowledge bases let your agent answer questions based on your documents, websites, and files. When you pass a knowledge base to `execute()`, the AI model automatically searches it for relevant content and includes citations in its responses.
+Knowledge bases give your agent searchable access to documents, websites, and files. Pass one to `execute()` and the model searches it automatically, with citations.
 
-## Creating a knowledge base
+## Create a knowledge base
 
 Create a file in `src/knowledge/`:
 
@@ -21,15 +21,39 @@ export default new Knowledge({
 })
 ```
 
-The dev console under **Knowledge** lets you browse your knowledge bases, see indexing status per source, view individual files, and trigger syncs manually. To test that your knowledge base returns the right results, use the **RAG Search** view in the dev console. It lets you run queries against your knowledge bases and see the matched passages, scores, and source documents.
+When multiple KBs are passed to `execute()`, the LLM reads each one's `description` to pick which to search. Keep descriptions short and specific.
+
+Browse your knowledge bases, inspect indexing status, and view individual files from the dev console:
 
 <Frame>
   <img alt="Knowledge page in dev console" className="block dark:hidden" src="../assets/knowledge-console.png" />
   <img alt="Knowledge page in dev console" className="hidden dark:block" src="../assets/knowledge-console-dark.png" />
 </Frame>
 
+## Use it in a conversation
+
+Pass knowledge bases to `execute()` via the `knowledge` array. The model searches them automatically when it needs information, and includes citations back to the source documents:
+
+```typescript
+import { Conversation } from "@botpress/runtime"
+import ProductDocs from "../knowledge/product-docs"
+import FAQ from "../knowledge/faq"
+
+export default new Conversation({
+  channel: "webchat.channel",
+  handler: async ({ execute }) => {
+    await execute({
+      instructions: "Answer questions using the documentation. Cite your sources.",
+      knowledge: [ProductDocs, FAQ],
+    })
+  },
+})
+```
+
 ## Data sources
 
+A knowledge base indexes one or more data sources. The ADK ships two types: websites and local directories.
+
 ### Website from sitemap
 
 Index all pages in a sitemap:
@@ -84,17 +108,19 @@ const DocsSource = DataSource.Website.fromUrls([
 
 ### Website source options
 
+All four website factories accept the same options:
+
 | Option | Type | Description |
 |--------|------|-------------|
 | `id` | `string` | Optional unique identifier for the source |
 | `filter` | `(ctx) => boolean` | Filter function receiving `{ url, lastmod?, changefreq?, priority? }` |
-| `fetch` | `string \| function` | Fetch strategy: `"node:fetch"` (default), `"integration:browser"`, or custom function |
-| `maxPages` | `number` | Maximum pages to index (1-50000, default: 50000) |
-| `maxDepth` | `number` | Maximum sitemap depth (1-20, default: 20) |
+| `fetch` | `string \| function` | Fetch strategy: `"node:fetch"` (default), `"integration:browser"`, or a custom function |
+| `maxPages` | `number` | Maximum pages to index (1–50000, default: 50000) |
+| `maxDepth` | `number` | Maximum sitemap depth (1–20, default: 20) |
 
 ### Directory
 
-Use a directory as a data source:
+Index files from a local directory:
 
 ```typescript
 const FileSource = DataSource.Directory.fromPath("./src/knowledge/docs", {
@@ -102,31 +128,28 @@ const FileSource = DataSource.Directory.fromPath("./src/knowledge/docs", {
 })
 ```
 
-## Using knowledge in conversations
+| Option | Type | Description |
+|--------|------|-------------|
+| `id` | `string` | Optional unique identifier for the source |
+| `filter` | `(filePath: string) => boolean` | Decide which files to include by path |
 
-Pass knowledge bases to `execute()` via the `knowledge` array:
+## Search a knowledge base directly
 
-```typescript
-import { Conversation } from "@botpress/runtime"
-import ProductDocs from "../knowledge/product-docs"
-import FAQ from "../knowledge/faq"
+To search a KB outside of `execute()`, call `search()` on the instance. Useful for custom retrieval, suggested-articles UIs, or populating context manually:
 
-export default new Conversation({
-  channel: "webchat.channel",
-  handler: async ({ execute }) => {
-    await execute({
-      instructions: "Answer questions using the documentation. Cite your sources.",
-      knowledge: [ProductDocs, FAQ],
-    })
-  },
+```typescript
+const result = await ProductDocs.search("how do I reset my password?", {
+  limit: 5,
 })
-```
 
-The AI model searches the knowledge bases automatically when it needs information. Results include citations that trace back to the source documents.
+for (const passage of result.passages) {
+  console.log(passage.content, passage.metadata)
+}
+```
 
-## Refreshing knowledge
+## Refresh a knowledge base
 
-Knowledge bases are indexed during `adk dev` and `adk deploy`. To re-index on a schedule, use a workflow:
+Knowledge bases index during `adk dev` and `adk deploy`. To re-index on a schedule, use a workflow:
 
 ```typescript
 import { Workflow } from "@botpress/runtime"
@@ -152,11 +175,3 @@ Refresh a single source within a knowledge base:
 ```typescript
 await ProductDocs.refreshSource("my-source-id", { force: true })
 ```
-
----
-
-Next, learn how to test your agent with evals.
-
-<Card title="Write and run evals" icon="flask-conical" href="/adk/testing/evals">
-  Automated conversation tests for your agent.
-</Card>
diff --git a/adk/data/tables.mdx b/adk/data/tables.mdx
index 3009ccb5..a74dfeeb 100644
--- a/adk/data/tables.mdx
+++ b/adk/data/tables.mdx
@@ -14,6 +14,8 @@ import { Table, z } from "@botpress/runtime"
 
 export default new Table({
   name: "OrderTable",
+  description: "Customer orders",
+  keyColumn: "userId",
   columns: {
     userId: z.string(),
     items: z.array(z.string()),
@@ -24,6 +26,8 @@ export default new Table({
 })
 ```
 
+`description` is optional but useful when the table gets surfaced to the LLM (via Zai or knowledge). `keyColumn` is optional too; it sets the default key used by `upsertRows` so you don't have to pass it on every call.
+
 The dev console under **Tables** is the primary way to manage table data. You can see the sync state between your code and Botpress Cloud, add/update/delete rows, filter and sort, export to CSV, and copy data between dev and prod environments.
 
 <Frame>
@@ -55,6 +59,35 @@ export default new Table({
 })
 ```
 
+### Computed columns
+
+A computed column is derived from other columns. Set `computed: true`, declare the columns it depends on, and return its value from `value`:
+
+```typescript
+export default new Table({
+  name: "OrderTable",
+  columns: {
+    quantity: z.number(),
+    unitPrice: z.number(),
+    total: {
+      computed: true,
+      schema: z.number(),
+      dependencies: ["quantity", "unitPrice"],
+      value: (row) => row.quantity * row.unitPrice,
+    },
+  },
+})
+```
+
+Computed columns recalculate whenever their dependencies change. When you write to the table, pass `waitComputed: true` to block until the recalculation finishes:
+
+```typescript
+await OrderTable.createRows({
+  rows: [{ quantity: 3, unitPrice: 20 }],
+  waitComputed: true,
+})
+```
+
 ## CRUD operations
 
 Import your table and use the typed instance methods.
@@ -96,7 +129,7 @@ await OrderTable.updateRows({
 
 ### Upsert rows
 
-Insert or update based on a key column:
+Insert or update based on a key column. If you set `keyColumn` on the table, you can omit it here:
 
 ```typescript
 const { inserted, updated } = await OrderTable.upsertRows({
@@ -105,6 +138,8 @@ const { inserted, updated } = await OrderTable.upsertRows({
 })
 ```
 
+If `keyColumn` is omitted on both the table and the call, it defaults to `id`.
+
 ### Delete rows
 
 ```typescript
@@ -142,6 +177,7 @@ const { rows } = await OrderTable.findRows({
 | `$nin` | Not in array |
 | `$exists` | Field exists |
 | `$regex` | Regex match |
+| `$options` | Regex flags: `"i"` for case-insensitive, `"c"` for case-sensitive |
 
 ### Logical operators
 
@@ -201,11 +237,3 @@ const { rows } = await OrderTable.findRows({
 | `max` | Numbers, strings, dates | Maximum value |
 | `min` | Numbers, strings, dates | Minimum value |
 | `unique` | All types | Array of unique values |
-
----
-
-Next, learn how to give your agent access to documents and websites.
-
-<Card title="Knowledge bases" icon="book-open" href="/adk/data/knowledge">
-  RAG-powered document retrieval for your agent.
-</Card>
diff --git a/adk/external/actions.mdx b/adk/external/actions.mdx
index 86ed1833..1fd99e0c 100644
--- a/adk/external/actions.mdx
+++ b/adk/external/actions.mdx
@@ -3,9 +3,7 @@ title: Create actions
 description: Create reusable functions callable from anywhere in your agent or from external systems.
 ---
 
-Actions are reusable functions that can be called from conversations, workflows, tools, triggers, other actions, and external API clients. They encapsulate shared business logic in one place.
-
-The difference between an action and a tool: tools only exist inside `execute()` and are called by the AI model. Actions are called by your code from anywhere, and are also exposed via the Botpress API to external systems. You can convert an action into a tool with `.asTool()` when you want the AI to use it too.
+Actions are reusable functions that hold shared business logic. Call them from your own code (conversations, workflows, triggers, other actions) or over HTTP from external systems.
 
 ## Creating an action
 
@@ -39,6 +37,34 @@ export default new Action({
 })
 ```
 
+Action names must be alphanumeric with no underscores, dashes, or spaces (e.g. `calculateTotal`, not `calculate_total`).
+
+Browse and test actions from the dev console:
+
+<Frame>
+  <img alt="Actions page in dev console" className="block dark:hidden" src="../assets/actions-console.png" />
+  <img alt="Actions page in dev console" className="hidden dark:block" src="../assets/actions-console-dark.png" />
+</Frame>
+
+### Caching results
+
+Set `cached: true` to cache an action's output by its input. Subsequent calls with the same input return the cached result instead of re-running the handler:
+
+```typescript
+export default new Action({
+  name: "fetchExchangeRate",
+  cached: true,
+  input: z.object({ from: z.string(), to: z.string() }),
+  output: z.object({ rate: z.number() }),
+  handler: async ({ input }) => {
+    const rate = await fetchRate(input.from, input.to)
+    return { rate }
+  },
+})
+```
+
+Useful for actions that are pure, expensive, and called repeatedly with the same inputs.
+
 ## Calling actions
 
 Import `actions` from `@botpress/runtime` and call any action by name. Input and output are fully typed.
@@ -109,7 +135,7 @@ export default new Trigger({
 
 ## As a tool
 
-Convert an action into a tool so the AI model can call it during `execute()`:
+Tools only exist inside `execute()` and are called by the AI model. If you want the AI to use an action too, convert it with `.asTool()`:
 
 ```typescript
 import { Conversation, actions } from "@botpress/runtime"
@@ -147,8 +173,9 @@ await actions.slack.addReaction({ name: "thumbsup", channel, timestamp })
 Actions are exposed via the Botpress Runtime API. External services can call your agent's actions over HTTP:
 
 ```bash
-curl -X POST https://chat.botpress.cloud/v1/chat/actions \
+curl -X POST https://api.botpress.cloud/v1/chat/actions \
   -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_PAT" \
   -H "x-bot-id: YOUR_BOT_ID" \
   -d '{
     "type": "calculateTotal",
@@ -162,20 +189,3 @@ curl -X POST https://chat.botpress.cloud/v1/chat/actions \
 This makes actions the bridge between your agent and external systems. A backend service, a webhook handler, or another application can trigger your agent's logic without going through a conversation.
 
 See the [Runtime API reference](/api-reference/runtime-api/openapi/callAction) for full details.
-
-## Dev console
-
-You can browse and test actions in the dev console under **Actions**.
-
-<Frame>
-  <img alt="Actions page in dev console" className="block dark:hidden" src="../assets/actions-console.png" />
-  <img alt="Actions page in dev console" className="hidden dark:block" src="../assets/actions-console-dark.png" />
-</Frame>
-
----
-
-Next, learn how to react to external events with triggers.
-
-<Card title="Set up triggers" icon="zap" href="/adk/external/triggers">
-  Subscribe to integration and custom events.
-</Card>
diff --git a/adk/external/triggers.mdx b/adk/external/triggers.mdx
index 662f38ed..683e2c41 100644
--- a/adk/external/triggers.mdx
+++ b/adk/external/triggers.mdx
@@ -25,17 +25,25 @@ The `events` array lists which events this trigger subscribes to. The handler ru
 
 Trigger names must be at least 3 characters and contain only alphanumeric characters and underscores.
 
+Browse your triggers from the dev console:
+
+<Frame>
+  <img alt="Triggers page in dev console" className="block dark:hidden" src="../assets/triggers-console.png" />
+  <img alt="Triggers page in dev console" className="hidden dark:block" src="../assets/triggers-console-dark.png" />
+</Frame>
+
 ## Event format
 
 Events use the format `"integration:eventName"` for integration events, or just the event name for custom events defined in `agent.config.ts`.
 
-The handler receives:
+The handler receives a single `event` parameter:
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `event.type` | `string` | The event type that fired |
 | `event.payload` | `object` | Event-specific data |
-| `client` | `object` | Botpress client for API calls |
+
+To make API calls from a trigger, pull the client from the runtime context: `const client = context.get("client")`.
 
 ## Multiple events
 
@@ -115,19 +123,3 @@ export default new Trigger({
 })
 ```
 
-## Dev console
-
-You can browse triggers in the dev console under **Triggers**.
-
-<Frame>
-  <img alt="Triggers page in dev console" className="block dark:hidden" src="../assets/triggers-console.png" />
-  <img alt="Triggers page in dev console" className="hidden dark:block" src="../assets/triggers-console-dark.png" />
-</Frame>
-
----
-
-Next, learn how to store and query structured data.
-
-<Card title="Tables" icon="database" href="/adk/data/tables">
-  Define and query database tables.
-</Card>
diff --git a/adk/get-started/quickstart.mdx b/adk/get-started/quickstart.mdx
deleted file mode 100644
index af09ae04..00000000
--- a/adk/get-started/quickstart.mdx
+++ /dev/null
@@ -1,94 +0,0 @@
----
-title: Quickstart
-description: This guide walks you through installing the ADK and creating your first agent project.
----
-
-By the end of this guide, you'll have a working AI agent that responds to messages on webchat. It takes about 5 minutes.
-
-<Info>
-  You'll need [Node.js](https://nodejs.org/) 22.0.0 or higher and a [Botpress account](https://sso.botpress.cloud).
-</Info>
-
-## Install the ADK CLI
-
-<Tabs>
-  <Tab title="macOS & Linux">
-    ```bash
-    curl -fsSL https://github.com/botpress/adk/releases/latest/download/install.sh | bash
-    ```
-  </Tab>
-  <Tab title="Windows (PowerShell)">
-    ```powershell
-    powershell -c "irm https://github.com/botpress/adk/releases/latest/download/install.ps1 | iex"
-    ```
-  </Tab>
-</Tabs>
-
-Open a new terminal, then verify the installation:
-
-```bash
-adk --version
-```
-
-Log in to your Botpress account:
-
-```bash
-adk login
-```
-
-A browser window opens for sign-in. Once complete, the CLI stores your credentials locally.
-
-## Create your agent
-
-```bash
-adk init my-agent
-```
-
-The wizard walks you through three steps:
-
-1. **Select a template.** Pick `hello-world`. This creates a simple agent that responds to webchat messages using an AI model.
-2. **Select a package manager.** We recommend [bun](https://bun.sh) for the fastest experience. npm, pnpm, and yarn also work. If you only have one installed, this step is skipped.
-3. **Link to Botpress.** Select the workspace you want to deploy to. The CLI creates a bot in that workspace and connects your project to it.
-
-The CLI then installs dependencies and sets up your project. When it's done:
-
-```bash
-cd my-agent
-```
-
-## Start the dev server
-
-```bash
-adk dev
-```
-
-This builds your agent, deploys it to a development bot on Botpress Cloud, and starts the dev console (default port 3001). Press `space` in the terminal to open it in your browser.
-
-The dev console is your local control panel for building and debugging. You can chat with your agent, browse its components (actions, workflows, triggers), manage data (tables, knowledge bases, files), run evals, inspect traces and logs, and configure integrations.
-
-Go to the **Chat** page and send a message. Your agent responds.
-
-<Frame>
-  <img alt="ADK dev console" className="block dark:hidden" src="../assets/quickstart.png" />
-  <img alt="ADK dev console" className="hidden dark:block" src="../assets/quickstart-dark.png" />
-</Frame>
-
-The dev server watches your files and rebuilds on every change.
-
-## Deploy to Botpress Cloud
-
-When you're ready to go live:
-
-```bash
-adk deploy
-```
-
-This builds your agent for production, runs preflight checks (integration changes, config diffs), syncs your knowledge bases and tables, and uploads everything to Botpress Cloud. The CLI walks you through any changes that need approval before deploying.
-
-Once deployed, your agent is live in the workspace you linked during `adk init`.
-
-Next, learn what's in the project you just created and how to configure it.
-
-<Card title="Agent configuration" icon="gear" href="/adk/setup/configuration">
-  Project structure, models, state, and dependencies.
-</Card>
diff --git a/adk/get-started/welcome.mdx b/adk/introduction.mdx
similarity index 63%
rename from adk/get-started/welcome.mdx
rename to adk/introduction.mdx
index 528cc02a..e39cd62a 100644
--- a/adk/get-started/welcome.mdx
+++ b/adk/introduction.mdx
@@ -1,16 +1,15 @@
 ---
-title: Botpress ADK
-sidebarTitle: Welcome
-description: The Botpress Agent Development Kit (ADK) is a developer-first TypeScript framework for building AI agents on the Botpress Platform.
+title: Introduction to the ADK
+description: TypeScript framework for building AI agents on Botpress.
 ---
 
+The Agent Development Kit (ADK) is a **CLI tool and development framework for building AI agents on Botpress**. Write your agent as TypeScript: conversations, workflows, tools, and actions all live as code, with hot reload and type-safe APIs. Botpress handles hosting, scaling, and channel delivery.
+
 <Frame>
-  <img alt="Botpress ADK" className="block dark:hidden" src="../assets/welcome.png" />
-  <img alt="Botpress ADK" className="hidden dark:block" src="../assets/welcome-dark.png" />
+  <img alt="Botpress ADK" className="block dark:hidden" src="./assets/welcome.png" />
+  <img alt="Botpress ADK" className="hidden dark:block" src="./assets/welcome-dark.png" />
 </Frame>
 
-The ADK is a TypeScript framework for building AI agents that run on the Botpress Platform. You write conversations, workflows, tools, and actions as code. The platform handles hosting, scaling, and channel delivery.
-
 ## What you can build
 
 - **Customer support agents** that resolve tickets, look up orders, and escalate to humans
@@ -39,14 +38,15 @@ Your agent is organized around a few core primitives:
 | **Tables** | Structured data storage |
 | **Knowledge** | RAG-powered document retrieval |
 | **Triggers** | React to external events |
+| **Custom components** | Render custom React UI in webchat |
 | **Evals** | Automated conversation tests |
 
-Each primitive lives in its own file under `src/`. The ADK discovers them automatically, no manual registration.
+Each primitive lives in its own file. The ADK discovers them automatically, no manual registration.
 
 ## Start here
 
 <CardGroup cols={2}>
-  <Card title="Quickstart" icon="rocket" href="/adk/get-started/quickstart">
+  <Card title="Quickstart" icon="rocket" href="/adk/quickstart">
     Install the ADK and deploy your first agent in minutes.
   </Card>
   <Card title="What's new" icon="newspaper" href="/changelog">
diff --git a/adk/quickstart.mdx b/adk/quickstart.mdx
new file mode 100644
index 00000000..ce47e0fc
--- /dev/null
+++ b/adk/quickstart.mdx
@@ -0,0 +1,120 @@
+---
+title: Quickstart
+description: Install the ADK and create your first agent project.
+---
+
+By the end of this guide, you'll have a working AI agent that responds to messages on Webchat. It takes about 5 minutes.
+
+<Info>
+  You will need:
+
+  * A [Botpress account](https://sso.botpress.cloud)
+  * [Node.js](https://nodejs.org/en) (v22.0.0 or higher)
+  * A supported package manager: [bun](https://bun.sh), [pnpm](https://pnpm.io), [yarn](https://yarnpkg.com), or [npm](https://www.npmjs.com)
+</Info>
+
+## Installation
+
+Install the ADK CLI globally:
+
+<CodeGroup>
+  ```bash macOS & Linux theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
+  curl -fsSL https://github.com/botpress/adk/releases/latest/download/install.sh | bash
+  ```
+
+  ```powershell Windows (PowerShell) theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
+  powershell -c "irm https://github.com/botpress/adk/releases/latest/download/install.ps1 | iex"
+  ```
+</CodeGroup>
+
+Then, verify the installation:
+
+```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
+adk --version
+```
+
+Log in to your Botpress account:
+
+```bash
+adk login
+```
+
+This will open a browser window for authentication. Once complete, the CLI stores your credentials locally.
+
+## Create your agent
+
+Initialize a new agent project:
+
+```bash
+adk init my-agent
+```
+
+The wizard walks you through three steps:
+
+1. **Select a template**: Pick `hello-world`. This creates a simple agent that responds to webchat messages using an AI model.
+2. **Select a package manager**: We recommend [bun](https://bun.sh) for the fastest experience. npm, pnpm, and yarn also work. If you only have one installed, this step is skipped.
+3. **Link to Botpress**: Select the workspace you want to deploy to. The CLI creates a bot in that workspace and connects your project to it.
+
+The CLI then automatically installs dependencies and sets up your project in the `my-agent` directory.
+
+Navigate into your project:
+
+```bash
+cd my-agent
+```
+
+## Test your agent
+
+### Start the development server
+
+Start the development server with hot reloading:
+
+```bash
+adk dev
+```
+
+This builds your agent, deploys it to a development bot on Botpress, and starts the dev console at [`http://localhost:3001/`](http://localhost:3001/). Press <kbd>space</kbd> in the terminal to open it in your browser.
+
+### View in the dev console
+
+The dev console is your local control panel for building and debugging. Within the dev console, you can:
+
+- Chat with your agent
+- Browse its components (actions, workflows, triggers)
+- Manage data (tables, knowledge bases, files)
+- Run evals
+- Inspect traces and logs
+- Configure integrations
+
+Go to the **Chat** page and send a message to test your agent:
+
+<Frame>
+  <img alt="ADK dev console" className="block dark:hidden" src="./assets/quickstart.png" />
+  <img alt="ADK dev console" className="hidden dark:block" src="./assets/quickstart-dark.png" />
+</Frame>
+
+The dev server watches your files and rebuilds on every change.
+
+## Deploy your agent
+
+When you're ready to go live:
+
+```bash
+adk deploy
+```
+
+This builds your agent for production, runs preflight checks (integration changes, config diffs), syncs your knowledge bases and tables, and uploads everything to Botpress. The CLI walks you through any changes that need approval before deploying.
+
+Once deployed, your agent is live in the workspace you linked during `adk init`.
+
+<Check>
+  You deployed your first agent using the ADK!
+</Check>
+
+---
+
+Next, learn what's in the project you just created and how to configure it:
+
+<Card title="Agent configuration" icon="settings" href="/adk/setup/configuration">
+  Project structure, models, state, and dependencies.
+</Card>
diff --git a/adk/setup/configuration.mdx b/adk/setup/configuration.mdx
index c88a4ae5..42859280 100644
--- a/adk/setup/configuration.mdx
+++ b/adk/setup/configuration.mdx
@@ -1,11 +1,11 @@
 ---
-title: Agent Configuration
+title: Configuration
 description: Understand your project structure and how to configure your agent.
 ---
 
 ## Project structure
 
-After running `adk init`, your project contains:
+After running `adk init`, these are the core files and folders of an ADK project:
 
 | Path | Purpose |
 |------|---------|
@@ -17,17 +17,17 @@ After running `adk init`, your project contains:
 | `src/tables/` | Database table schemas |
 | `src/knowledge/` | RAG knowledge base sources |
 | `src/triggers/` | Event-based handlers |
-| `src/evals/` | Automated conversation tests |
-| `package.json` | Node.js dependencies |
-| `tsconfig.json` | TypeScript settings |
+| `evals/` | Automated conversation tests |
 
 The ADK scans `src/` and discovers primitives automatically. Each file exports a primitive (a `Conversation`, `Workflow`, `Action`, etc.) and the framework registers it at build time.
 
-## agent.config.ts
+## `agent.config.ts`
 
-Everything about your agent is configured here using `defineConfig`. This is the hello-world template config with all available fields shown:
+Everything about your agent is configured in `agent.config.ts` by calling `defineConfig` and passing in a configuration object.
 
-```typescript
+Here's the `hello-world` template default configuration with all available fields shown:
+
+```typescript expandable
 import { z, defineConfig } from "@botpress/runtime"
 
 export default defineConfig({
@@ -93,7 +93,7 @@ defaultModels: {
 | `autonomous` | `execute()` calls in conversations and workflows |
 | `zai` | Zai operations like `zai.extract()`, `zai.check()`, `zai.text()` |
 
-If you don't set `defaultModels`, the ADK defaults to `openai:gpt-4.1-2025-04-14` for autonomous and `openai:gpt-4.1-mini-2025-04-14` for zai.
+If you don't set `defaultModels`, the ADK defaults to `openai:gpt-4.1-mini-2025-04-14` for autonomous and `openai:gpt-4.1-2025-04-14` for zai.
 
 You can pass an array of models for fallback. If the first model fails, the next one is tried:
 
@@ -116,14 +116,14 @@ await execute({
 
 ### State
 
-State lets your agent persist data. There are two scopes:
+The `state` field lets you define schemas for data that your agent can persist across a certain scope. There are two available scopes:
 
 | Scope | Persists across | Use for |
 |-------|----------------|---------|
 | `bot` | All conversations and users | Global counters, shared config |
 | `user` | All conversations for a given user | Preferences, profile data |
 
-Define schemas with Zod. The ADK generates TypeScript types from them, so state access is fully typed:
+You can define schemas for state using Zod. The ADK generates TypeScript types from them, so state access is fully typed:
 
 ```typescript
 bot: {
@@ -139,11 +139,13 @@ user: {
 },
 ```
 
-For reading and writing state at runtime, see [Manage states](/adk/conversations/state).
+<Tip>
+  For more information about reading and writing state at runtime, check out our guide to [managing states](/adk/conversations/state).
+</Tip>
 
 ### Tags
 
-Tags are metadata you can attach to bots, users, conversations, messages, and workflows:
+The `tags` field lets you define metadata that you can attach to bots, users, conversations, messages, and workflows:
 
 ```typescript
 bot: {
@@ -162,7 +164,7 @@ Tags are useful for filtering and organizing data in the Botpress platform.
 
 ### Secrets
 
-Secrets store sensitive values like API keys. They are declared here, but values are managed separately per environment and never committed to git:
+The `secrets` field lets you store sensitive values, like API keys or tokens. They are declared here, but values are managed separately per environment and never committed to version control:
 
 ```typescript
 secrets: {
@@ -171,11 +173,13 @@ secrets: {
 },
 ```
 
-For the full secrets workflow, see [Environment Setup](/adk/setup/environment).
+<Tip>
+For more information about using secrets, check out our guide on [setting up your environment](/adk/setup/environment#secrets).
+</Tip>
 
 ### Configuration
 
-Configuration defines static, deploy-time settings. Unlike state, these are read-only at runtime:
+The `configuration` field defines static, deploy-time settings. Unlike state, these are read-only at runtime:
 
 ```typescript
 configuration: {
@@ -186,7 +190,9 @@ configuration: {
 },
 ```
 
-For managing configuration values across environments, see [Environment Setup](/adk/setup/environment).
+<Tip>
+  For managing configuration values across environments, check out our guide to [setting up your environment](/adk/setup/environment#configuration).
+</Tip>
 
 ### Dependencies
 
@@ -208,11 +214,13 @@ dependencies: {
 },
 ```
 
-For finding, configuring, and managing integrations, see [Integrations](/adk/setup/integrations).
+<Tip>
+For more information about finding, configuring, and managing integrations, check out our [integrations guide](/adk/setup/integrations).
+</Tip>
 
 ### Custom events
 
-Define events your agent can emit and subscribe to:
+The `events` field lets you define custom events your agent can emit and subscribe to:
 
 ```typescript
 events: {
@@ -226,15 +234,15 @@ events: {
 },
 ```
 
-Triggers and conversations can listen for custom events. See [Set up triggers](/adk/external/triggers).
+You can then listen for these events within triggers and conversations. For more information, check out our guide on [setting up triggers](/adk/external/triggers).
 
 ### Evals
 
-Configure how automated tests run:
+The `evals` field lets you configure how your agent's automated tests run:
 
 ```typescript
 evals: {
-  idleTimeout: 30,
+  idleTimeout: 15000,
   judgePassThreshold: 3,
   judgeModel: "openai:gpt-4o",
 },
@@ -242,16 +250,10 @@ evals: {
 
 | Field | Description |
 |-------|-------------|
-| `idleTimeout` | Seconds to wait for idle eval conversations |
+| `idleTimeout` | Milliseconds to wait for the agent to respond before timing out |
 | `judgePassThreshold` | Pass threshold for LLM judge assertions (1-5) |
 | `judgeModel` | Model used for LLM judge assertions |
 
-For writing and running evals, see [Write and run evals](/adk/testing/evals).
-
----
-
-Next, learn how to manage secrets and configuration values across dev and production environments.
-
-<Card title="Environment Setup" icon="lock" href="/adk/setup/environment">
-  Secrets, configuration values, and dev vs prod environments.
-</Card>
+<Tip>
+  For more information, check out our full guide to [writing and running evals](/adk/testing/evals).
+</Tip>
diff --git a/adk/setup/environment.mdx b/adk/setup/environment.mdx
index f5800033..14f2d329 100644
--- a/adk/setup/environment.mdx
+++ b/adk/setup/environment.mdx
@@ -1,11 +1,15 @@
 ---
-title: Environment Setup
-description: Manage secrets, configuration values, and dev vs prod environments.
+title: Environment setup
+description: Manage secrets, configuration values, and development/production environments.
 ---
 
 The ADK separates development and production into two environments. Secrets and configuration values are stored per environment, so your dev API keys never touch production.
 
-You can switch between environments in the dev console using the environment selector in the top bar. This controls which environment's secrets, configuration, and data you see and edit. You can also toggle it with `Cmd+Shift+E` (Mac) or `Ctrl+Shift+E` (Windows/Linux).
+You can switch between environments in the dev console using the environment toggle in the upper-right corner. This controls which environment's secrets, configuration, and data you view/edit.
+
+<Tip>
+You can also toggle between environments with <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>E</kbd> (Mac) or <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>E</kbd> (Windows/Linux).
+</Tip>
 
 <Frame>
   <img alt="Environment selector in dev console" className="block dark:hidden" src="../assets/environment-selector.png" />
@@ -16,7 +20,7 @@ You can switch between environments in the dev console using the environment sel
 
 Your project has three files that manage environment state:
 
-| File | Contains | Committed to git |
+| File | Contains | Committed to version control |
 |------|----------|-----------------|
 | `agent.json` | Production bot ID, workspace ID, API URL | Yes |
 | `agent.local.json` | Development bot ID | No (gitignored) |
@@ -39,29 +43,34 @@ secrets: {
 },
 ```
 
-Required secrets (the default) are enforced at deploy time. `adk dev` warns if they're unset but doesn't block. Optional secrets never block.
+Required secrets (the default) are enforced at deploy time. `adk dev` warns you if they're unset, but doesn't block the dev server from starting. Optional secrets never block deployment.
 
 ### Setting values
 
+You can set values using `adk secret:set` command:
+
 ```bash
 adk secret:set OPENAI_KEY "sk-..."
 adk secret:set OPENAI_KEY "sk-prod-..." --prod
 ```
 
-Dev and prod values are stored in separate buckets inside `.adk/secrets.json`. Setting a dev value never touches prod, and vice versa.
+Development and production values are stored in separate buckets inside `.adk/secrets.json`. Setting a development value never touches production values, and vice versa.
 
-### CLI reference
+You can also add, edit, and delete secrets from the dev console. Schema changes (adding or removing declarations) write back to `agent.config.ts`:
 
-| Command | What it does |
-|---------|-------------|
-| `adk secret` | List all declared secrets and their set/unset status |
-| `adk secret:set KEY VALUE` | Set a secret for dev |
-| `adk secret:set KEY VALUE --prod` | Set a secret for prod |
-| `adk secret:delete KEY` | Delete a secret from dev |
-| `adk secret:delete KEY --prod` | Delete a secret from prod |
+<Frame>
+  <img alt="Secrets management in dev console" className="block dark:hidden" src="../assets/secrets-console.png" />
+  <img alt="Secrets management in dev console" className="hidden dark:block" src="../assets/secrets-console-dark.png" />
+</Frame>
+
+<Tip>
+  For the full `adk secret` command set, see the [CLI reference](/adk/cli-reference#adk-secret).
+</Tip>
 
 ### Using secrets at runtime
 
+To use secrets at runtime, just import `secrets` from `@botpress/runtime` and reference them directly:
+
 ```typescript
 import { secrets } from "@botpress/runtime"
 
@@ -74,16 +83,11 @@ if (secrets.SENTRY_DSN) {
 }
 ```
 
-The `secrets` import is a typed proxy over environment variables. Required secrets are typed as `string`, optional ones as `string | undefined`. It's read-only. Assigning to `secrets.X` throws.
-
-### Managing secrets in the dev console
+The `secrets` import is a typed proxy over environment variables. Required secrets are typed as `string`, optional ones as `string | undefined`.
 
-You can also manage secrets from the dev console under **Settings > Secrets**. The UI lets you add, edit, and delete secrets for both dev and prod environments. Schema changes (adding or removing declarations) write back to `agent.config.ts`.
-
-<Frame>
-  <img alt="Secrets management in dev console" className="block dark:hidden" src="../assets/secrets-console.png" />
-  <img alt="Secrets management in dev console" className="hidden dark:block" src="../assets/secrets-console-dark.png" />
-</Frame>
+<Note>
+  Secrets are read-only at runtime. Attempting to reassign the value of a secret will throw an error.
+</Note>
 
 ### Naming rules
 
@@ -94,23 +98,15 @@ Secret keys must be `SCREAMING_SNAKE_CASE`:
 - No trailing underscore
 - Cannot start with `SECRET_`, `BP_`, or `BOTPRESS_` (reserved)
 
-| Key | Valid | Why |
-|-----|-------|-----|
-| `MY_API_KEY` | Yes | |
-| `DB_PASSWORD` | Yes | |
-| `A1` | Yes | Minimum 2 chars, starts with letter |
-| `A` | No | Too short |
-| `my_key` | No | Must start with uppercase |
-| `SECRET_FOO` | No | Reserved prefix |
-| `BP_TOKEN` | No | Reserved prefix |
-
 ### How secrets flow to production
 
-Dev secret saves restart the running bot immediately. Prod secret saves only write the local file. Prod values reach Botpress Cloud on the next `adk deploy`.
+**Development secrets**: If you're running your agent with `adk dev` and save changes to your development secrets via the dev console, your agent will immediately restart using the new values.
+
+**Production secrets**: If you save changes to your production secrets via the dev console, the changes will only write to `agent.config.ts`. The new values will take effect on your production agent the next time you run `adk deploy`.
 
 ## Configuration
 
-Configuration defines static, deploy-time settings for your agent. Unlike secrets, configuration values are not sensitive. Unlike state, they are read-only at runtime.
+The `configuration` object in `agent.config.ts` defines static, deploy-time settings for your agent. Unlike secrets, configuration values are not sensitive. Unlike state, they are read-only at runtime.
 
 ### Declaring a schema
 
@@ -135,6 +131,13 @@ adk config:set supportEmail "help@mycompany.com" --prod  # Set a prod value
 adk config:get supportEmail                        # Read a value
 ```
 
+Configuration values can also be managed from the dev console:
+
+<Frame>
+  <img alt="Config variables in dev console" className="block dark:hidden" src="../assets/config-variables-console.png" />
+  <img alt="Config variables in dev console" className="hidden dark:block" src="../assets/config-variables-console-dark.png" />
+</Frame>
+
 ### Using configuration at runtime
 
 ```typescript
@@ -144,16 +147,7 @@ const email = configuration.supportEmail
 const retries = configuration.maxRetries
 ```
 
-Configuration is read-only. Attempting to set a value at runtime throws.
-
-### Dev console
-
-Configuration values can also be managed from the dev console under **Settings > Config Variables**.
-
-<Frame>
-  <img alt="Config variables in dev console" className="block dark:hidden" src="../assets/config-variables-console.png" />
-  <img alt="Config variables in dev console" className="hidden dark:block" src="../assets/config-variables-console-dark.png" />
-</Frame>
+Configuration is read-only. Attempting to set a value at runtime throws an error.
 
 ## Preflight checks
 
@@ -170,11 +164,3 @@ This checks:
 - Generated type assets
 
 Preflight checks also run automatically during `adk dev` and `adk deploy`.
-
----
-
-Next, learn how to connect your agent to channels and external services.
-
-<Card title="Integrations" icon="puzzle-piece" href="/adk/setup/integrations">
-  Find, add, and configure integrations.
-</Card>
diff --git a/adk/setup/integrations.mdx b/adk/setup/integrations.mdx
index de6688ea..67543db1 100644
--- a/adk/setup/integrations.mdx
+++ b/adk/setup/integrations.mdx
@@ -3,11 +3,11 @@ title: Integrations
 description: Connect your agent to channels and external services.
 ---
 
-Integrations connect your agent to the outside world. They provide channels (webchat, Slack, WhatsApp) and external services (Gmail, Linear, Stripe).
+Integrations connect your agent to the outside world. They provide channels (Webchat, Slack, WhatsApp) and external services (Gmail, Linear, Stripe).
 
-## Browsing and managing integrations
+## Adding integrations
 
-The dev console has a built-in integration hub under **Integrations**. From here you can browse available integrations, add them to your project, configure settings, and enable or disable them.
+The dev console has a built-in integration hub. Browse the full catalog and install any integration straight into your project, no CLI needed:
 
 <Frame>
   <img alt="Integrations page in dev console" className="block dark:hidden" src="../assets/integrations-console.png" />
@@ -16,26 +16,35 @@ The dev console has a built-in integration hub under **Integrations**. From here
 
 ## Configuring integrations
 
-Many integrations require configuration (API keys, tokens, webhook URLs). After adding an integration, configure it from the **Integrations** page in the dev console.
+Most integrations need configuration (API keys, tokens, webhook URLs) before they can run. Open an installed integration in the dev console to fill in its settings:
 
 <Frame>
   <img alt="Integration configuration in dev console" className="block dark:hidden" src="../assets/integration-config-console.png" />
   <img alt="Integration configuration in dev console" className="hidden dark:block" src="../assets/integration-config-console-dark.png" />
 </Frame>
 
-Integration configuration is stored directly on Botpress Cloud, not in your project files. Your dev bot and prod bot each have their own configuration, so you can use different API keys or settings per environment. This is separate from agent secrets, which your code reads directly.
+Integration configuration is stored on Botpress Cloud, not in your local project files. This differs from your agent's secrets, which your code reads directly.
+
+Your development bot and production bot each have their own configuration, so you can use different API keys or settings per environment.
 
 ## Enabling and disabling
 
-Integrations can be enabled or disabled from the dev console or in `agent.config.ts`:
+Integrations are active by default when you use the string shorthand form:
 
 ```typescript
 dependencies: {
   integrations: {
-    webchat: {
-      version: "webchat@latest",
-      enabled: true,
-    },
+    webchat: "webchat@latest",
+  },
+},
+```
+
+To disable one without removing it, switch that integration to the object form and set `enabled: false`:
+
+```typescript
+dependencies: {
+  integrations: {
+    webchat: "webchat@latest",
     slack: {
       version: "slack@latest",
       enabled: false,
@@ -44,9 +53,9 @@ dependencies: {
 },
 ```
 
-Disabled integrations are still part of your project (types are generated, code can reference them) but they won't be active when your agent runs.
+Disabled integrations are still part of your project (types are generated, code can reference them) but they won't be active when your agent runs. You can also toggle this from the dev console.
 
-## CLI
+## Managing integrations using the CLI
 
 You can also manage integrations from the command line:
 
@@ -60,10 +69,16 @@ You can also manage integrations from the command line:
 | `adk upgrade <name>` | Update an integration to a newer version |
 | `adk remove <name>` | Remove an integration from your project |
 
-Integrations are added disabled by default. Enable and configure them in the dev console.
+Newly added integrations are disabled by default. You can enable and configure them in the dev console.
+
+<Note>
+  For full documentation on managing integrations via the command line, check out the [CLI reference](/adk/cli-reference).
+</Note>
 
 ## Integration versions
 
+Here's the syntax for referencing integration versions:
+
 | Format | Example | Behavior |
 |--------|---------|----------|
 | `name@latest` | `webchat@latest` | Resolves to the newest version |
@@ -71,11 +86,3 @@ Integrations are added disabled by default. Enable and configure them in the dev
 | `workspace/name@version` | `my-workspace/custom@1.0.0` | Uses a workspace-specific integration |
 
 Use `@latest` during development. Pin to specific versions for production deployments.
-
----
-
-With your agent configured and connected to integrations, you're ready to start building. Next, learn how to handle user messages.
-
-<Card title="Set up conversations" icon="messages" href="/adk/conversations/setup">
-  Handle messages across channels.
-</Card>
diff --git a/adk/testing/agent-steps.mdx b/adk/testing/agent-steps.mdx
index 9843c4d8..5f598f96 100644
--- a/adk/testing/agent-steps.mdx
+++ b/adk/testing/agent-steps.mdx
@@ -1,5 +1,5 @@
 ---
-title: Agent Steps
+title: Agent steps
 description: See what your agent did during each conversation turn in real time.
 ---
 
@@ -37,11 +37,3 @@ Agent Steps is the fastest way to debug during development. Use it when:
 ## Traces link
 
 Each turn in Agent Steps links to its full trace in the **Traces** view. Click the trace link to see the complete span timeline with detailed telemetry. See [Debug with logs and traces](/adk/testing/debugging) for more on the Traces view.
-
----
-
-Next, learn about the full debugging toolkit.
-
-<Card title="Debug with logs and traces" icon="activity" href="/adk/testing/debugging">
-  Inspect traces, spans, and logs.
-</Card>
diff --git a/adk/testing/debugging.mdx b/adk/testing/debugging.mdx
index 82d50bd9..c4f937cf 100644
--- a/adk/testing/debugging.mdx
+++ b/adk/testing/debugging.mdx
@@ -43,16 +43,11 @@ You can also read logs from the command line:
 ```bash
 adk logs                         # Show recent logs
 adk logs --follow                # Stream logs in real time
-adk logs error                   # Filter by level
-adk logs "webhook"               # Filter by content
+adk logs error                   # Errors only
+adk logs warning since=1h        # Warnings and errors from the last hour
+adk logs limit=100               # Last 100 entries
 ```
 
-Logs are stored in `.adk/logs/` while the dev server is running.
-
----
+The positional filter tokens are `error` / `warning` / `info` (cumulative level), `since=<duration>`, and `limit=<n>`. See the [CLI reference](/adk/cli-reference#adk-logs) for all flags.
 
-Next, learn how to run scripts with access to your agent's runtime context.
-
-<Card title="Run scripts" icon="terminal" href="/adk/testing/scripts">
-  Execute one-off scripts with full runtime access.
-</Card>
+Logs are stored in `.adk/logs/` while the dev server is running.
diff --git a/adk/testing/evals.mdx b/adk/testing/evals.mdx
index ce1114df..8be8d392 100644
--- a/adk/testing/evals.mdx
+++ b/adk/testing/evals.mdx
@@ -5,12 +5,12 @@ description: Automated conversation tests for your agent.
 
 Evals are automated tests that simulate conversations with your agent and assert on the results. You write a conversation script with expected behaviors, and the eval runner plays it against your running agent and reports pass/fail.
 
-## Creating an eval
+## Create an eval
 
-Create `.eval.ts` files in `src/evals/`:
+Create `.eval.ts` files in the `evals/` directory at your agent root:
 
 ```typescript
-import { Eval } from "@botpress/runtime"
+import { Eval } from "@botpress/adk"
 
 export default new Eval({
   name: "greeting",
@@ -28,64 +28,83 @@ export default new Eval({
 })
 ```
 
-Each file can export one or more `Eval` instances (default or named exports).
+Each file can export one or more `Eval` instances as the default export or named exports.
 
 ## Conversation turns
 
-An eval defines a sequence of turns. Each turn sends a user message and optionally asserts on the response:
+An eval's `conversation` is a sequence of turns. Each turn can send a user message, fire an event, or assert the agent stays silent, plus optionally assert on what happens.
+
+Send user messages:
 
 ```typescript
 conversation: [
   {
     user: "What's the weather in Paris?",
     assert: {
-      response: [
-        { contains: "Paris" },
-      ],
-      tools: [
-        { called: "getWeather", params: { city: { equals: "Paris" } } },
-      ],
+      response: [{ contains: "Paris" }],
+      tools: [{ called: "getWeather", params: { city: { equals: "Paris" } } }],
     },
   },
   {
     user: "And in London?",
     assert: {
-      response: [
-        { contains: "London" },
-      ],
+      response: [{ contains: "London" }],
     },
   },
 ]
 ```
 
+Fire an event instead of a message:
+
+```typescript
+{
+  event: {
+    type: "order.placed",
+    payload: { orderId: "ord-123", total: 49.99 },
+  },
+  assert: {
+    response: [{ contains: "order" }],
+  },
+}
+```
+
+Assert the agent doesn't respond:
+
+```typescript
+{
+  user: "ok thanks",
+  expectSilence: true,
+}
+```
+
 ## Assertions
 
-### Response assertions
+Each turn's `assert` block can hold any combination of the assertion types below.
+
+### Response
 
-Assert on the text content of the agent's response:
+Assert on the text of the agent's reply:
 
 | Assertion | Description |
 |-----------|-------------|
 | `{ contains: "text" }` | Response includes this string |
 | `{ not_contains: "text" }` | Response does not include this string |
 | `{ matches: "regex" }` | Response matches this regex pattern |
-| `{ llm_judge: "criteria" }` | An LLM evaluates whether the response meets the criteria |
 | `{ similar_to: "text" }` | Response is semantically similar to this text |
+| `{ llm_judge: "criteria" }` | An LLM evaluates whether the response meets the criteria (see [LLM judge](#llm-judge)) |
 
-### Tool assertions
+### Tools
 
-Assert on which tools were called:
+Assert on which tools the agent called:
 
 | Assertion | Description |
 |-----------|-------------|
 | `{ called: "toolName" }` | Tool was called |
-| `{ called: "toolName", params: { key: { equals: "value" } } }` | Tool was called with specific params |
+| `{ called: "toolName", params: { key: { equals: "value" } } }` | Tool was called with matching params |
 | `{ not_called: "toolName" }` | Tool was not called |
 | `{ call_order: ["tool1", "tool2"] }` | Tools were called in this order |
 
-### Param operators
-
-Use these within `params` to match tool call arguments:
+Use these operators inside `params` to match tool arguments:
 
 | Operator | Example |
 |----------|---------|
@@ -98,7 +117,7 @@ Use these within `params` to match tool call arguments:
 | `{ gte: 10 }` | Greater than or equal |
 | `{ lte: 100 }` | Less than or equal |
 
-### State assertions
+### State
 
 Assert on state changes after a turn:
 
@@ -111,7 +130,7 @@ assert: {
 }
 ```
 
-### Table assertions
+### Tables
 
 Assert on table data:
 
@@ -124,7 +143,7 @@ assert: {
 }
 ```
 
-### Workflow assertions
+### Workflows
 
 Assert on workflow state:
 
@@ -137,7 +156,7 @@ assert: {
 }
 ```
 
-### Timing assertions
+### Timing
 
 Assert on response time:
 
@@ -149,9 +168,9 @@ assert: {
 }
 ```
 
-## LLM judge
+### LLM judge
 
-Use an LLM to evaluate responses against natural language criteria:
+Use `llm_judge` when the right answer isn't a fixed string. You describe what a good response looks like in plain English, and an LLM scores the agent's reply against it. It's the right choice for subjective checks like tone, intent, or whether the agent understood the user:
 
 ```typescript
 assert: {
@@ -162,33 +181,18 @@ assert: {
 }
 ```
 
-Configure the judge model and pass threshold in `agent.config.ts`:
-
-```typescript
-evals: {
-  judgeModel: "openai:gpt-4o",
-  judgePassThreshold: 3,
-},
-```
+Configure the judge model and pass threshold under [Configure eval behavior](#configure-eval-behavior).
 
-Or override per-eval:
+## Setup and outcome
 
-```typescript
-export default new Eval({
-  name: "quality-check",
-  options: {
-    judgePassThreshold: 4,
-  },
-  conversation: [/* ... */],
-})
-```
+`setup` runs before the first turn. `outcome` runs after the last.
 
-## Setup
+### Setup
 
 Seed state or trigger a workflow before the conversation starts:
 
 ```typescript
-export default new Eval({
+new Eval({
   name: "returning-user",
   setup: {
     state: {
@@ -207,7 +211,7 @@ export default new Eval({
 })
 ```
 
-Trigger a workflow:
+Trigger a workflow instead of (or in addition to) seeding state:
 
 ```typescript
 setup: {
@@ -218,12 +222,12 @@ setup: {
 },
 ```
 
-## Outcome assertions
+### Outcome
 
-Assert on state after the entire conversation completes:
+Assert on state, tables, or workflows after the entire conversation completes. Outcome assertions use the same shapes as turn assertions:
 
 ```typescript
-export default new Eval({
+new Eval({
   name: "full-flow",
   conversation: [
     { user: "Create a ticket for VPN issues" },
@@ -240,29 +244,82 @@ export default new Eval({
 })
 ```
 
-## Tags and types
+## Configure eval behavior
 
-Organize evals with tags and types:
+Set defaults for all evals in `agent.config.ts`:
 
 ```typescript
-export default new Eval({
+evals: {
+  judgeModel: "openai:gpt-4o",
+  judgePassThreshold: 3,
+  idleTimeout: 15000,
+},
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `judgeModel` | `string` | Model for `llm_judge` assertions. Defaults to `"fast"` |
+| `judgePassThreshold` | `number` (1–5) | Minimum score for `llm_judge` to pass. Defaults to `3` |
+| `idleTimeout` | `number` (ms) | How long to wait for the agent to respond. Defaults to `15000` |
+
+Override `judgePassThreshold` or `idleTimeout` on a specific eval:
+
+```typescript
+new Eval({
+  name: "quality-check",
+  options: {
+    judgePassThreshold: 4,
+    idleTimeout: 30000,
+  },
+  conversation: [/* ... */],
+})
+```
+
+## Organize evals
+
+Evals have two organizing fields that pair with CLI filters: `tags` and `type`.
+
+**Tags** are free-form labels. Use them to group evals you want to run together (smoke tests, critical paths, slow suites):
+
+```typescript
+new Eval({
   name: "greeting",
   tags: ["smoke", "core"],
-  type: "capability",
   conversation: [/* ... */],
 })
 ```
 
-Types are `"capability"` (tests a feature) or `"regression"` (prevents a known bug from returning).
+```bash
+adk evals --tag smoke    # Run only evals tagged "smoke"
+```
+
+**Type** marks what the eval is for:
+
+- `capability`: tests that a feature works as designed
+- `regression`: reproduces a past bug so it doesn't come back
+
+```typescript
+new Eval({
+  name: "fix-for-ticket-priority-bug",
+  type: "regression",
+  conversation: [/* ... */],
+})
+```
+
+```bash
+adk evals --type regression    # Run only regression evals
+```
+
+## Run evals
 
-## Running evals
+From the CLI:
 
 ```bash
 adk evals                        # Run all evals
 adk evals greeting               # Run a specific eval by name
 adk evals --tag smoke            # Run evals with a specific tag
 adk evals --type regression      # Run only regression evals
-adk evals -v                     # Verbose output (show all details, not just failures)
+adk evals -v                     # Show full details, not just failures
 ```
 
 View past runs:
@@ -279,11 +336,3 @@ You can also run and view evals from the dev console under **Evals**.
   <img alt="Evals page in dev console" className="block dark:hidden" src="../assets/evals-console.png" />
   <img alt="Evals page in dev console" className="hidden dark:block" src="../assets/evals-console-dark.png" />
 </Frame>
-
----
-
-Next, learn how to debug conversations in real time.
-
-<Card title="Agent Steps" icon="list-tree" href="/adk/testing/agent-steps">
-  See what your agent did during each conversation turn.
-</Card>
diff --git a/adk/testing/scripts.mdx b/adk/testing/scripts.mdx
index 40e7c9f3..82b686da 100644
--- a/adk/testing/scripts.mdx
+++ b/adk/testing/scripts.mdx
@@ -43,16 +43,16 @@ The runner looks for exports in this order:
 
 ## Arguments
 
-Extra arguments after the script path are passed to your function:
+Extra arguments after the script path are passed to your function. Positional args pass through directly; put flag-like args (anything starting with `-`) after a `--` separator so Commander doesn't try to parse them:
 
 ```bash
-adk run scripts/process.ts order-123 --verbose
+adk run scripts/process.ts order-123
+adk run scripts/process.ts -- --limit 100 --verbose
 ```
 
 ```typescript
-export default async function (orderId: string, flag: string) {
-  console.log(orderId)  // "order-123"
-  console.log(flag)     // "--verbose"
+export default async function (...args: string[]) {
+  console.log(args)  // ["order-123"] or ["--limit", "100", "--verbose"]
 }
 ```
 
@@ -71,11 +71,3 @@ adk run scripts/migrate.ts --prod
 - **Generate reports** by querying tables and knowledge bases
 - **Maintenance tasks** like cleaning up old data or reindexing
 - **Test actions** by calling them directly outside a conversation
-
----
-
-That wraps up testing and debugging. Next, explore the Zai utilities for structured LLM operations.
-
-<Card title="Introduction to Zai" icon="sparkles" href="/adk/zai/overview">
-  Extract data, generate text, classify, and more.
-</Card>
diff --git a/adk/workflows/create.mdx b/adk/workflows/create.mdx
index 3f6f0dbc..e0c00f08 100644
--- a/adk/workflows/create.mdx
+++ b/adk/workflows/create.mdx
@@ -40,6 +40,33 @@ export default new Workflow({
 
 The `input` and `output` schemas define what the workflow accepts and returns. Both use Zod.
 
+View running and completed workflows, their status, input, output, and run history from the dev console:
+
+<Frame>
+  <img alt="Workflows page in dev console" className="block dark:hidden" src="../assets/workflows-console.png" />
+  <img alt="Workflows page in dev console" className="hidden dark:block" src="../assets/workflows-console-dark.png" />
+</Frame>
+
+### Persistent state
+
+Add a `state` schema to carry data across the workflow's steps and retries. State is persisted between executions:
+
+```typescript
+export default new Workflow({
+  name: "import-job",
+  state: z.object({
+    processed: z.number().default(0),
+    lastId: z.string().optional(),
+  }),
+  handler: async ({ state, step }) => {
+    await step("process-batch", async () => {
+      state.processed += 100
+      state.lastId = "batch-end"
+    })
+  },
+})
+```
+
 ## Starting a workflow
 
 ### Programmatically
@@ -112,7 +139,7 @@ const instance = await ProcessOrderWorkflow.getOrCreate({
 })
 ```
 
-If a workflow with the same key and one of the specified statuses already exists, it returns the existing instance instead of creating a new one.
+If a workflow with the same key and one of the specified statuses already exists, it returns the existing instance instead of creating a new one. `statuses` defaults to `["pending", "in_progress", "listening", "paused"]` if you don't pass it.
 
 ## Loading a workflow by ID
 
@@ -155,6 +182,32 @@ export default new Workflow({
 })
 ```
 
+### Fail from inside the handler
+
+Mark the workflow as failed with a reason. This throws immediately and interrupts the handler:
+
+```typescript
+handler: async ({ input, workflow }) => {
+  if (!input.orderId) {
+    workflow.fail("Missing order ID")
+  }
+}
+```
+
+### Run autonomous execute
+
+Run the AI model inside the workflow, same as in conversations:
+
+```typescript
+handler: async ({ workflow, step }) => {
+  await step("classify", async () => {
+    return await workflow.execute({
+      instructions: "Classify this ticket as 'bug' or 'feature'.",
+    })
+  })
+}
+```
+
 ## Timeout
 
 Workflows time out after 5 minutes by default. Use the `timeout` prop to change this:
@@ -181,21 +234,4 @@ For workflows that need to run longer than 5 minutes, use [steps](/adk/workflows
 | `client` | `object` | Botpress client for API calls |
 | `execute` | `function` | Run the AI model (same as in conversations) |
 | `signal` | `AbortSignal` | Indicates when the workflow should stop |
-| `workflow` | `object` | Current workflow instance (id, name, tags, cancel, complete, setTimeout) |
-
-## Dev console
-
-You can view running and completed workflows in the dev console under **Workflows**. The Workflows page shows status, input, output, and run history.
-
-<Frame>
-  <img alt="Workflows page in dev console" className="block dark:hidden" src="../assets/workflows-console.png" />
-  <img alt="Workflows page in dev console" className="hidden dark:block" src="../assets/workflows-console-dark.png" />
-</Frame>
-
----
-
-Next, learn about step methods for controlling workflow execution.
-
-<Card title="Use workflow steps" icon="list-checks" href="/adk/workflows/steps">
-  Persistence, retries, sleep, parallel processing, and more.
-</Card>
+| `workflow` | `object` | Current workflow instance (id, name, tags, `cancel`, `complete`, `fail`, `setTimeout`, `execute`) |
diff --git a/adk/workflows/request-notify.mdx b/adk/workflows/request-notify.mdx
index 3d12f2a5..56cc7ed1 100644
--- a/adk/workflows/request-notify.mdx
+++ b/adk/workflows/request-notify.mdx
@@ -52,17 +52,19 @@ export default new Conversation({
   handler: async (props) => {
     if (props.type === "workflow_request") {
       if (props.request.type === "order-workflow:orderId") {
-        await props.request.workflow.provide("orderId", {
-          orderId: "ORD-12345",
-        })
+        await props.request.workflow.provide(
+          "orderId",
+          { orderId: "ORD-12345" },
+          props.request.step
+        )
       }
 
       if (props.request.type === "order-workflow:shippingAddress") {
-        await props.request.workflow.provide("shippingAddress", {
-          street: "123 Main St",
-          city: "Springfield",
-          zip: "62701",
-        })
+        await props.request.workflow.provide(
+          "shippingAddress",
+          { street: "123 Main St", city: "Springfield", zip: "62701" },
+          props.request.step
+        )
       }
       return
     }
@@ -72,7 +74,7 @@ export default new Conversation({
 })
 ```
 
-The `request.type` is formatted as `"workflowName:requestName"`. Use `request.workflow.provide()` to send the data back. The workflow resumes once the data is provided.
+The `request.type` is formatted as `"workflowName:requestName"`. Use `request.workflow.provide()` to send the data back, passing `request.step` as the third argument so the workflow knows exactly which pending step to resume. Omitting it works when only one step is pending for that request, but throws an error if multiple are pending. The workflow resumes once the data is provided.
 
 ### Let the AI handle requests
 
@@ -170,11 +172,3 @@ if (props.type === "workflow_callback") {
 | `step.request()` | Workflow asks conversation | Yes | `workflow_request` |
 | `step.notify()` | Workflow tells conversation | No | `workflow_notify` |
 | Callback | Workflow completes | N/A | `workflow_callback` |
-
----
-
-That wraps up workflows. Next, learn how to expose logic to external callers.
-
-<Card title="Create actions" icon="zap" href="/adk/external/actions">
-  Reusable functions callable from anywhere, including external systems.
-</Card>
diff --git a/adk/workflows/steps.mdx b/adk/workflows/steps.mdx
index ba16b5f6..f43b068b 100644
--- a/adk/workflows/steps.mdx
+++ b/adk/workflows/steps.mdx
@@ -28,7 +28,7 @@ export default new Workflow({
 })
 ```
 
-Each step name must be unique within the workflow. If two steps share a name, the second one reuses the first step's cached output instead of running.
+Step names should be unique. If the same name runs twice, the second call returns the first one's cached result instead of running.
 
 Steps can be nested. A parent step completes when all its sub-steps complete.
 
@@ -57,7 +57,7 @@ try {
 
 ## Sleep
 
-Pause the workflow for a duration or until a specific time:
+Pause the workflow for a duration (in milliseconds) or until a specific time:
 
 ```typescript
 await step.sleep("wait-5-min", 5 * 60 * 1000)
@@ -67,6 +67,18 @@ await step.sleepUntil("wait-until-noon", new Date("2025-01-15T12:00:00Z"))
 
 The workflow is suspended during sleep. No compute is used.
 
+## Progress
+
+Record a checkpoint without running any work. Useful for observability when you want to mark milestones in a long handler:
+
+```typescript
+await step.progress("Started import")
+// ...
+await step.progress("Halfway done")
+// ...
+await step.progress("Finished")
+```
+
 ## Listen
 
 Pause the workflow and set its status to `"listening"`, waiting to be resumed by an external event:
@@ -150,11 +162,3 @@ await step.batch(
   { batchSize: 100 }
 )
 ```
-
----
-
-Next, learn how workflows can exchange data with conversations.
-
-<Card title="Request and notify from workflows" icon="arrow-right-left" href="/adk/workflows/request-notify">
-  Ask conversations for input and send progress updates.
-</Card>
diff --git a/adk/zai/classify.mdx b/adk/zai/classify.mdx
index 15921e19..62e7b263 100644
--- a/adk/zai/classify.mdx
+++ b/adk/zai/classify.mdx
@@ -7,15 +7,22 @@ Zai provides methods for classifying, validating, and organizing data using an L
 
 ## Check a condition
 
-`zai.check()` verifies a boolean condition against input:
+`zai.check()` asks the LLM a yes/no question about some input and returns `true` or `false`:
 
 ```typescript
 import { adk } from "@botpress/runtime"
 
-const { output } = await adk.zai.check(emailBody, "is spam").result()
-const { value, explanation } = output
-// value: true/false
-// explanation: "The email contains..."
+const emailBody = "Click here for a FREE iPhone! Limited time only!!!"
+const isSpam = await adk.zai.check(emailBody, "is this spam?")
+// true
+```
+
+Call `.result()` for the boolean plus the LLM's reasoning:
+
+```typescript
+const { output } = await adk.zai.check(emailBody, "is this spam?").result()
+// output.value       → true
+// output.explanation → "The message uses urgency tactics and promises free rewards..."
 ```
 
 ## Label content
@@ -64,7 +71,7 @@ const prioritized = await adk.zai.sort(tasks, "by urgency and impact, most urgen
 
 ## Rate items
 
-`zai.rate()` scores items on a 1-5 scale:
+`zai.rate()` scores items on a 1-5 scale. Pass a string for a single criterion:
 
 ```typescript
 const reviews = [
@@ -77,9 +84,25 @@ const ratings = await adk.zai.rate(reviews, "Rate the sentiment")
 // [5, 3, 1]
 ```
 
+Pass an object to score each item across multiple criteria. Each result includes a `total`:
+
+```typescript
+const essays = ["... first essay ...", "... second essay ..."]
+
+const ratings = await adk.zai.rate(essays, {
+  grammar: "Rate the grammar and spelling",
+  clarity: "Rate how clear and well-organized the writing is",
+  argumentation: "Rate the strength of arguments and evidence",
+})
+// [
+//   { grammar: 4, clarity: 5, argumentation: 3, total: 12 },
+//   { grammar: 3, clarity: 4, argumentation: 4, total: 11 },
+// ]
+```
+
 ## Group items
 
-`zai.group()` categorizes items into groups:
+`zai.group()` categorizes items into groups. With just `instructions`, it discovers groups on its own:
 
 ```typescript
 const messages = [
@@ -95,10 +118,30 @@ const groups = await adk.zai.group(messages, {
 // { "Login Issues": [...], "Shipping Questions": [...], "Technical Errors": [...] }
 ```
 
----
+To force items into predefined categories, pass `initialGroups`:
+
+```typescript
+const articles = [
+  "How to build a React app",
+  "Python machine learning tutorial",
+  "Understanding Docker containers",
+]
 
-Next, explore AI-native development patterns.
+const groups = await adk.zai.group(articles, {
+  instructions: "Categorize by technology",
+  initialGroups: [
+    { id: "frontend", label: "Frontend Development" },
+    { id: "backend", label: "Backend Development" },
+    { id: "ml", label: "Machine Learning" },
+  ],
+})
+```
 
-<Card title="Skills" icon="puzzle-piece" href="/adk/ai-native/skills">
-  Give AI coding assistants deep ADK knowledge.
-</Card>
+| Option | Type | Description |
+|--------|------|-------------|
+| `instructions` | `string` | How to group the items |
+| `initialGroups` | `Array<{id, label}>` | Predefined categories to use instead of discovering them |
+| `maxGroups` | `number` | Upper limit on groups. Smaller groups merge at the end until within the limit |
+| `minElements` | `number` | Minimum items per group. Groups below the threshold have their elements redistributed |
+| `tokensPerElement` | `number` | Max tokens per item |
+| `chunkLength` | `number` | Max tokens per chunk for large inputs |
diff --git a/adk/zai/extract.mdx b/adk/zai/extract.mdx
index ef6556bf..7ba4b2ce 100644
--- a/adk/zai/extract.mdx
+++ b/adk/zai/extract.mdx
@@ -78,9 +78,3 @@ export default new Workflow({
   },
 })
 ```
-
----
-
-<Card title="Generate text and summaries" icon="text" href="/adk/zai/generate">
-  Generate, rewrite, summarize, and answer with citations.
-</Card>
diff --git a/adk/zai/generate.mdx b/adk/zai/generate.mdx
index 00edca00..e17dacfe 100644
--- a/adk/zai/generate.mdx
+++ b/adk/zai/generate.mdx
@@ -34,9 +34,14 @@ const formal = await adk.zai.rewrite(
 // "The meeting has been scheduled for tomorrow at 3:00 PM."
 ```
 
+| Option | Type | Description |
+|--------|------|-------------|
+| `length` | `number` | Max tokens to generate |
+| `examples` | `Array<{input, output, instructions?}>` | Few-shot examples to guide the rewriting |
+
 ## Summarize
 
-`zai.summarize()` condenses long content:
+`zai.summarize()` condenses long content. It handles documents from a few paragraphs up to entire books by chunking and merging automatically:
 
 ```typescript
 const summary = await adk.zai.summarize(longArticle, {
@@ -49,27 +54,39 @@ const summary = await adk.zai.summarize(longArticle, {
 |--------|------|-------------|
 | `length` | `number` | Target summary length in tokens |
 | `prompt` | `string` | Instructions for what to focus on |
+| `format` | `string` | How to format the output (e.g. "bullet points with clear sections") |
+| `intermediateFactor` | `number` | How many times longer intermediate summaries are than the final length (used for very large documents) |
+| `maxIterations` | `number` | Max refinement passes |
+| `sliding` | `{ window, overlap }` | Override the default chunk size and overlap |
 
 ## Answer with citations
 
-`zai.answer()` answers questions from a set of documents and provides source citations:
+`zai.answer()` answers a question from a set of documents and tells you which documents backed the answer. It doesn't always return a direct answer: if the question is ambiguous, off-topic, or the documents don't cover it, the result carries that information instead.
 
 ```typescript
-const documents = [
-  "Botpress was founded in 2016.",
-  "The company is based in Quebec, Canada.",
-  "Botpress provides an AI agent platform.",
+const faq = [
+  "Orders ship within 2 business days. Standard shipping takes 3-5 business days; expedited takes 1-2.",
+  "Returns are accepted within 30 days of delivery. Items must be unused and in original packaging.",
+  "Our warranty covers manufacturing defects for 1 year from purchase. Wear and tear is not covered.",
 ]
 
-const result = await adk.zai.answer(documents, "When was Botpress founded?")
+const result = await adk.zai.answer(faq, "How long do I have to return something?")
 
 if (result.type === "answer") {
-  console.log(result.answer)    // "Botpress was founded in 2016."
-  console.log(result.citations) // Array of citation references
+  console.log(result.answer)     // "Returns are accepted within 30 days of delivery..."
+  console.log(result.citations)  // Points back to the returns policy entry
 }
 ```
 
-The result `type` is `"answer"` when the question can be answered from the documents, or another value when it cannot.
+Branch on `result.type` to handle the other cases (ambiguous questions, off-topic, etc.):
+
+| Type | Fields | When it's returned |
+|------|--------|-------------------|
+| `answer` | `answer`, `citations` | The documents support a clear answer |
+| `ambiguous` | `ambiguity`, `follow_up`, `answers` | The question has multiple valid interpretations |
+| `out_of_topic` | `reason` | The question isn't covered by the documents' topic |
+| `invalid_question` | `reason` | The question is malformed or nonsensical |
+| `missing_knowledge` | `reason` | The topic is relevant but the documents don't cover it |
 
 ## Patch files
 
@@ -87,9 +104,3 @@ const patched = await adk.zai.patch(
   "Add JSDoc comments to all exported functions"
 )
 ```
-
----
-
-<Card title="Classify, validate and filter" icon="tags" href="/adk/zai/classify">
-  Check conditions, label content, filter, sort, rate, and group.
-</Card>
diff --git a/adk/zai/overview.mdx b/adk/zai/overview.mdx
index c26e75ea..fb74f2ee 100644
--- a/adk/zai/overview.mdx
+++ b/adk/zai/overview.mdx
@@ -1,6 +1,5 @@
 ---
 title: Introduction to Zai
-sidebarTitle: Introduction to Zai
 description: Type-safe LLM utilities for common AI operations.
 ---
 
@@ -62,8 +61,16 @@ defaultModels: {
 
 You can also change the model from the dev console under **Settings > LLM Config**.
 
----
-
-<Card title="Extract structured data" icon="braces" href="/adk/zai/extract">
-  Pull typed data from unstructured text.
-</Card>
+## Method categories
+
+<CardGroup cols={3}>
+  <Card title="Extract structured data" icon="braces" href="/adk/zai/extract">
+    Pull typed data from unstructured text.
+  </Card>
+  <Card title="Generate text and summaries" icon="sparkles" href="/adk/zai/generate">
+    Generate, rewrite, summarize, and answer with citations.
+  </Card>
+  <Card title="Classify, validate and filter" icon="tags" href="/adk/zai/classify">
+    Check conditions, label content, filter, sort, rate, and group.
+  </Card>
+</CardGroup>
diff --git a/docs.json b/docs.json
index d5f4849a..0baae3c0 100644
--- a/docs.json
+++ b/docs.json
@@ -89,17 +89,10 @@
             "group": "ADK",
             "tag": "Beta",
             "pages": [
-              {
-                "group": "Get Started",
-                "expanded": true,
-                "pages": [
-                  "/adk/get-started/welcome",
-                  "/adk/get-started/quickstart"
-                ]
-              },
+                "/adk/introduction",
+                "/adk/quickstart",
               {
                 "group": "Setting up your agent",
-                "expanded": true,
                 "pages": [
                   "/adk/setup/configuration",
                   "/adk/setup/environment",
@@ -108,7 +101,6 @@
               },
               {
                 "group": "Handling conversations",
-                "expanded": true,
                 "pages": [
                   "/adk/conversations/setup",
                   "/adk/conversations/ai-execution",
@@ -121,7 +113,6 @@
               },
               {
                 "group": "Handling longform logic",
-                "expanded": true,
                 "pages": [
                   "/adk/workflows/create",
                   "/adk/workflows/steps",
@@ -130,7 +121,6 @@
               },
               {
                 "group": "Actions and triggers",
-                "expanded": true,
                 "pages": [
                   "/adk/external/actions",
                   "/adk/external/triggers"
@@ -138,7 +128,6 @@
               },
               {
                 "group": "Working with data",
-                "expanded": true,
                 "pages": [
                   "/adk/data/tables",
                   "/adk/data/knowledge"
@@ -146,7 +135,6 @@
               },
               {
                 "group": "Testing and debugging",
-                "expanded": true,
                 "pages": [
                   "/adk/testing/evals",
                   "/adk/testing/agent-steps",
@@ -156,7 +144,6 @@
               },
               {
                 "group": "LLM Utilities",
-                "expanded": true,
                 "pages": [
                   "/adk/zai/overview",
                   "/adk/zai/extract",
@@ -166,21 +153,18 @@
               },
               {
                 "group": "AI Native Development",
-                "expanded": true,
                 "pages": [
                   "/adk/ai-native/skills"
                 ]
               },
               {
                 "group": "Advanced",
-                "expanded": true,
                 "pages": [
                   "/adk/advanced/hitl"
                 ]
               },
               {
                 "group": "CLI",
-                "expanded": true,
                 "pages": [
                   "/adk/cli-reference"
                 ]
diff --git a/index.mdx b/index.mdx
index 7e0e10b4..ccd30726 100644
--- a/index.mdx
+++ b/index.mdx
@@ -39,7 +39,7 @@ import { IntegrationsCard } from '/home-components/IntegrationsCard.jsx'
       title="ADK"
       img='/homepage-assets/adk.jpg'
       cta="Get started"
-      href="/adk/get-started/welcome"
+      href="/adk/introduction"
     >
       TypeScript library for building AI agents from code <Badge color="blue">Beta</Badge>
     </Card>