diff --git a/.vale/styles/config/vocabularies/botpress-vocab/accept.txt b/.vale/styles/config/vocabularies/botpress-vocab/accept.txt
index 4cc21a34..1fbd272c 100644
--- a/.vale/styles/config/vocabularies/botpress-vocab/accept.txt
+++ b/.vale/styles/config/vocabularies/botpress-vocab/accept.txt
@@ -55,4 +55,11 @@ Airtable
 Persat
 Mintlify
 Sharepoint
-Chatwoot
\ No newline at end of file
+Chatwoot
+[Ee]vals?
+[Ee]val
+ADK
+gitignored
+stdout
+helpdesk
+Kommo
\ No newline at end of file
diff --git a/adk/ai-native/skills.mdx b/adk/ai-native/skills.mdx
index 5379036f..1d5af5f8 100644
--- a/adk/ai-native/skills.mdx
+++ b/adk/ai-native/skills.mdx
@@ -32,12 +32,12 @@ Or install as a Claude Code plugin:
 
 | Skill | What it teaches | Use when |
 |-------|----------------|----------|
-| **adk** | Core ADK framework: actions, tools, workflows, conversations, tables, knowledge, triggers, Zai, configuration | Building any feature with the ADK |
-| **adk-debugger** | Trace reading, log analysis, common failure diagnosis, the debug loop | Bot isn't responding, tools failing, workflows stuck, LLM issues |
-| **adk-evals** | Eval file format, all assertion types, CLI usage, per-primitive testing patterns | Writing and running automated tests |
-| **adk-frontend** | Authentication, type generation, client setup, calling bot actions from React/Next.js | Building a frontend that connects to your bot |
-| **adk-integrations** | Discovery, adding, configuring, and using integrations end-to-end | Connecting Slack, WhatsApp, Linear, or any integration |
-| **adk-docs** | Documentation standards, creation, review, and maintenance | Writing or updating docs for your bot |
+| **`adk`** | Core ADK framework: actions, tools, workflows, conversations, tables, knowledge, triggers, Zai, configuration | Building any feature with the ADK |
+| **`adk-debugger`** | Trace reading, log analysis, common failure diagnosis, the debug loop | Bot isn't responding, tools failing, workflows stuck, LLM issues |
+| **`adk-evals`** | Eval file format, all assertion types, CLI usage, per-primitive testing patterns | Writing and running automated tests |
+| **`adk-frontend`** | Authentication, type generation, client setup, calling bot actions from React/Next.js | Building a frontend that connects to your bot |
+| **`adk-integrations`** | Discovery, adding, configuring, and using integrations end-to-end | Connecting Slack, WhatsApp, Linear, or any integration |
+| **`adk-docs`** | Documentation standards, creation, review, and maintenance | Writing or updating docs for your bot |
 
 ## Slash commands
 
diff --git a/adk/cli-reference.mdx b/adk/cli-reference.mdx
index a9987052..66f8a8a0 100644
--- a/adk/cli-reference.mdx
+++ b/adk/cli-reference.mdx
@@ -14,7 +14,7 @@ These flags work with every command:
 | `--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) |
+| `--profile <profile>` | Credentials profile to use (overrides the `ADK_PROFILE` environment variable and the current profile) |
 
 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`.
 
@@ -32,7 +32,7 @@ These commands manage an agent project from scaffold to deploy:
 | `adk status` | Show project status, integrations, and server state |
 | `adk link` | Link local agent to a workspace and bot |
 
-### adk init
+### `adk init`
 
 Scaffold a new agent project. Pass a name, or omit it to be prompted:
 
@@ -49,7 +49,7 @@ adk init --list-templates
 | `--skip-link` | Skip the linking step |
 | `--list-templates` | List available templates and exit |
 
-### adk dev
+### `adk dev`
 
 Start the dev server with hot reload:
 
@@ -67,7 +67,7 @@ adk dev --port 3000 --port-console 3001
 | `-v, --verbose` | Show additional details | |
 | `--non-interactive` | Emit structured NDJSON events to stdout | |
 
-### adk deploy
+### `adk deploy`
 
 Deploy the built agent to Botpress Cloud:
 
@@ -81,7 +81,7 @@ adk deploy -y
 | `-e, --env <environment>` | Deployment environment | `production` |
 | `-y, --yes` | Auto-approve preflight changes | |
 
-### adk link
+### `adk link`
 
 Link the local agent to a workspace and bot. Writes to `agent.json`, or to `agent.local.json` with `--local`:
 
@@ -112,7 +112,7 @@ These commands add, inspect, and manage the integrations your agent depends on:
 | `adk list` | List installed integrations |
 | `adk info <name>` | Show detailed integration info |
 
-### adk add
+### `adk add`
 
 Add an integration or interface to your agent. Accepts a name, `workspace/name`, or a specific version:
 
@@ -129,7 +129,7 @@ adk add webchat --alias custom-webchat
 |------|-------------|
 | `--alias <alias>` | Custom alias for the resource |
 
-### adk search
+### `adk search`
 
 Search the Botpress Hub for integrations:
 
@@ -142,7 +142,7 @@ adk search slack --limit 5
 |------|-------------|---------|
 | `--limit <number>` | Max results to return | `20` |
 
-### adk list
+### `adk list`
 
 List integrations in your project, or all available ones on the Hub:
 
@@ -156,7 +156,7 @@ adk list --available
 | `--available` | List all available integrations (not just installed) | |
 | `--limit <n>` | Max results | `50` |
 
-### adk info
+### `adk info`
 
 Show details for a specific integration. Filter by a single facet or show the full spec:
 
@@ -199,7 +199,7 @@ These commands let you send messages to your agent and run eval suites:
 | `adk evals [name]` | Run eval suites |
 | `adk evals runs [runId]` | List or show eval run history |
 
-### adk chat
+### `adk chat`
 
 Open an interactive chat, or send a single message with `--single`. Requires `adk dev` to be running:
 
@@ -215,7 +215,7 @@ adk chat --single "Follow up" --conversation-id <id>
 | `--conversation-id <id>` | Continue a conversation | |
 | `--timeout <duration>` | Max wait duration | `60s` |
 
-### adk evals
+### `adk evals`
 
 Run eval suites. With no arguments, runs all evals; pass a name to run just one:
 
@@ -235,7 +235,7 @@ adk evals -v
 | `-v, --verbose` | Show full details for all evals | |
 | `--server <url>` | Dev server URL | `http://localhost:3001` |
 
-### adk evals runs
+### `adk evals runs`
 
 List past eval runs, or show the details of a specific one:
 
@@ -261,7 +261,7 @@ These commands discover and run workflows against the local dev server:
 | `adk workflows inspect <name>` | Inspect a workflow schema and metadata |
 | `adk workflows run <name> [payload]` | Run a workflow |
 
-### adk workflows run
+### `adk workflows run`
 
 Run a workflow with a JSON payload. Add `--wait` to block until it finishes:
 
@@ -285,7 +285,7 @@ These commands help you inspect what your agent is doing:
 | `adk traces [tokens...]` | Query trace data |
 | `adk run <script> [args...]` | Run a TypeScript script with the ADK runtime |
 
-### adk logs
+### `adk logs`
 
 Query logs from `.adk/logs/`. Pass filter tokens as positional arguments, or stream with `--follow`:
 
@@ -310,7 +310,7 @@ adk logs --follow limit=10
 | `-f, --follow` | Stream logs in real time |
 | `--summary` | Emit a single JSON summary (requires `--format json`) |
 
-### adk traces
+### `adk traces`
 
 Query trace data from the local store. Filter tokens narrow by workflow, action, trigger, or drill into a specific trace:
 
@@ -341,7 +341,7 @@ adk traces --follow
 | `-f, --follow` | Stream new traces |
 | `--include-llm` | Include LLM instructions and code in drill-in mode |
 
-### adk run
+### `adk run`
 
 Run a TypeScript script with the full ADK runtime, so you can import actions, Zai, and tables directly:
 
@@ -364,7 +364,7 @@ Sync local knowledge base content with Botpress:
 |---------|-------------|
 | `adk kb sync` | Synchronize knowledge bases with Botpress |
 
-### adk kb sync
+### `adk kb sync`
 
 Push local KB sources to the dev or prod bot. Use `--dry-run` to preview changes first:
 
@@ -394,7 +394,7 @@ Manage static files your agent serves or references:
 | `adk assets status` | Show asset sync status |
 | `adk assets pull` | Download remote assets to local directory |
 
-### adk assets sync
+### `adk assets sync`
 
 Upload local assets to remote storage. Use `--dry-run` to see what would change:
 
@@ -411,7 +411,7 @@ adk assets sync --force -y
 | `--bail-on-failure` | Stop on first error |
 | `--force` | Force re-upload all files |
 
-### adk assets list
+### `adk assets list`
 
 List asset files. By default shows both local and remote; filter with `--local` or `--remote`:
 
@@ -435,7 +435,7 @@ These commands integrate the ADK with AI coding tools:
 | `adk mcp` | Start the MCP server |
 | `adk mcp:init` | Generate MCP configuration files |
 
-### adk mcp
+### `adk mcp`
 
 Start the MCP server so tools like Claude Code, Cursor, or VS Code can talk to your running dev server:
 
@@ -449,7 +449,7 @@ adk mcp --port 3001
 | `--cwd <path>` | Working directory for MCP operations | |
 | `--port <port>` | UI server port to connect to | `3001` |
 
-### adk mcp:init
+### `adk mcp:init`
 
 Generate MCP configuration files for supported AI assistants:
 
@@ -479,7 +479,7 @@ These commands manage your Botpress credentials and the CLI itself:
 | `adk telemetry` | Manage telemetry preferences |
 | `adk theme` | Manage CLI theme (dark/light) |
 
-### adk login
+### `adk login`
 
 Authenticate with your Botpress account. Pass `--token` to skip the browser flow:
 
@@ -495,7 +495,7 @@ adk login --profile staging
 | `--profile <profile>` | Profile name to save credentials under | |
 | `--api-url <url>` | Botpress API URL | `https://api.botpress.cloud` |
 
-### adk self-upgrade
+### `adk self-upgrade`
 
 Upgrade the ADK CLI. Pass a tag (`beta`, `next`) or an explicit version:
 
@@ -505,7 +505,7 @@ adk self-upgrade beta
 adk self-upgrade 1.18.0
 ```
 
-### adk telemetry
+### `adk telemetry`
 
 View or change telemetry preferences. With no flags, prints the current status:
 
@@ -521,7 +521,7 @@ adk telemetry --disable
 | `--enable` | Enable telemetry |
 | `--disable` | Disable telemetry |
 
-### adk theme
+### `adk theme`
 
 Switch the CLI theme between dark and light:
 
diff --git a/adk/conversations/custom-components.mdx b/adk/conversations/custom-components.mdx
index 1b6bbc08..7767a58c 100644
--- a/adk/conversations/custom-components.mdx
+++ b/adk/conversations/custom-components.mdx
@@ -1,11 +1,11 @@
 ---
 title: Use custom components
-description: Build and render custom React UI inside webchat.
+description: Build and render custom React UI inside Webchat.
 ---
 
-Custom components let you render your own React UI inside webchat. Instead of being limited to text, images, and carousels, you can build any visual element and have either your code or the LLM send it to users.
+Custom components let you render your own React UI inside [Webchat](/webchat/get-started/introduction). Instead of being limited to text, images, and carousels, you can build any visual element and have either your code or the LLM send it to users.
 
-There are two ways to use them:
+There are two ways to use custom components:
 
 1. **Direct send** - your handler explicitly sends the component
 2. **LLM-driven** - the LLM decides when to render the component during `execute()`
@@ -66,11 +66,12 @@ export const TicketCardComponent = new CustomComponent(component)
 
 The component is now discoverable by `adk dev` and `adk deploy`. The component name is derived from the React function name (`TicketCard` in this case).
 
-## Sending components directly
+
+## Sending components manually
 
 Send a custom component like any other message:
 
-```typescript
+```typescript highlight={7-18}
 import { Conversation } from "@botpress/runtime"
 import { TicketCardComponent } from "../components/TicketCard"
 
@@ -101,10 +102,9 @@ To let the LLM decide when to render your component, add LLM metadata and list i
 
 ### Add LLM metadata
 
-The second argument to `CustomComponent` tells the LLM what the component does:
+The `description` field tells the LLM what the component does:
 
-```typescript
-// src/components/TicketCard.ts
+```typescript title="TicketCard.ts" highlight={5-6}
 import { CustomComponent, z } from "@botpress/runtime"
 import component from "./TicketCard.bp.tsx"
 
@@ -129,9 +129,11 @@ export const TicketCardComponent = new CustomComponent(component, {
 | `props` | Yes | Zod schema defining the component's props. Use `.describe()` on each field. |
 | `exampleValues` | Yes | Array of example prop objects. Converted to JSX examples in the LLM prompt. |
 
-### List it in the conversation
+### Provide the component to the LLM
 
-```typescript
+To provide the component to your agent's LLM, pass it into the `execute()` function's `components` field:
+
+```typescript highlight={6}
 import { Conversation } from "@botpress/runtime"
 import { TicketCardComponent } from "../components/TicketCard"
 
@@ -149,7 +151,9 @@ export default new Conversation({
 
 The LLM now knows about `<TicketCard>` and will render it when appropriate during `execute()`.
 
-If you list a component in `components` that was created without LLM metadata, the Conversation constructor throws immediately.
+<Note>
+If you list a component in `components` that was created without LLM metadata, the `Conversation` constructor throws immediately.
+</Note>
 
 ## Combining both approaches
 
@@ -184,11 +188,11 @@ export default new Conversation({
 
 ## Build pipeline
 
-During `adk dev` and `adk deploy`, custom components go through this pipeline:
+During `adk dev` and `adk deploy`, custom components go through the following pipeline:
 
 1. **Discover** - scans `src/` for `.ts` files that export `CustomComponent` instances
 2. **Resolve** - finds the `.bp.tsx` import in each wrapper
-3. **Bundle** - esbuild bundles the `.bp.tsx` into standalone ESM (`react` and `react-dom` are externalized)
+3. **Bundle** - `esbuild` bundles the `.bp.tsx` into standalone ESM (`react` and `react-dom` are externalized)
 4. **Upload** - the bundle is uploaded to Botpress as a public file
 5. **Wire** - the component URL is injected so `conversation.send()` works
 
@@ -205,7 +209,7 @@ During `adk dev`, the file watcher rebuilds only changed components incrementall
 
 ## Limitations
 
-- **Webchat only.** Custom components only render in the Botpress webchat widget. Other channels don't support them.
+- **Webchat only.** Custom components only render in Webchat. Other channels don't support them.
 - **No global stylesheets.** You can import `.css` files in your component, but your project's global styles are not available.
 - **React 18.** React 19 features are not available.
 - **No server-side rendering.** Components are client-rendered in the browser.
@@ -215,8 +219,8 @@ During `adk dev`, the file watcher rebuilds only changed components incrementall
 | Problem | Cause | Fix |
 |---------|-------|-----|
 | `Component "X" not deployed. Run "adk deploy".` | Component URL not set | Re-run `adk dev` to build and upload |
-| Component doesn't appear in webchat | Wrapper doesn't export a `CustomComponent` | Check the `.ts` file imports the `.bp.tsx` and exports `new CustomComponent(...)` |
+| Component doesn't appear in Webchat | Wrapper doesn't export a `CustomComponent` | Check the `.ts` file imports the `.bp.tsx` and exports `new CustomComponent(...)` |
 | LLM never uses the component | Missing metadata or not in `components` array | Add `{ description, props, exampleValues }` and list in `components` |
 | 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` |
+| TypeScript errors on `.bp.tsx` | Missing `tsconfig` settings | Add `"jsx": "react"`, `"allowImportingTsExtensions": true`, and `"noEmit": true` |
diff --git a/adk/conversations/lifecycle.mdx b/adk/conversations/lifecycle.mdx
index 99c156df..93ca4c68 100644
--- a/adk/conversations/lifecycle.mdx
+++ b/adk/conversations/lifecycle.mdx
@@ -9,7 +9,7 @@ Lifecycle management adds idle nudges and session expiration to your conversatio
 
 Add a `lifecycle` prop to your conversation:
 
-```typescript
+```typescript highlight={10-13}
 import { Conversation } from "@botpress/runtime"
 import { z } from "@botpress/sdk"
 
@@ -77,7 +77,7 @@ A session is a single period of activity within a conversation. One conversation
 | `lastActivityAt` | `string` | ISO timestamp of the last user message. |
 | `nudgeCount` | `number` | How many nudges have fired in this session. Resets on new activity and on session renewal. |
 
-Access it via `conversation.session`:
+You can access the current session via `conversation.session`:
 
 ```typescript
 const session = props.conversation.session
@@ -87,7 +87,7 @@ if (session) {
 }
 ```
 
-The session object is read-only. It returns `undefined` for conversations without lifecycle configured.
+The `session` object is read-only. It returns `undefined` for conversations without lifecycle configured.
 
 ## What happens when a conversation expires
 
@@ -112,7 +112,7 @@ Lifecycle durations use `ms`-compatible strings:
 | `'24h'` | 24 hours |
 | `'2d'` | 2 days |
 
-Durations are validated at construction time. Invalid or non-positive values throw immediately.
+Durations are validated at construction time. Invalid or non-positive values throw an error immediately.
 
 ## Common patterns
 
diff --git a/adk/conversations/messages.mdx b/adk/conversations/messages.mdx
index 174dc1b7..9f84ad70 100644
--- a/adk/conversations/messages.mdx
+++ b/adk/conversations/messages.mdx
@@ -16,7 +16,7 @@ await conversation.send({
 
 ## Message types
 
-The available message types depend on the channel. For webchat, the following types are supported:
+The available message types depend on which channel your agent is deployed on. For [Webchat](/webchat/get-started/introduction), the following types are supported:
 
 | Type | Payload | Description |
 |------|---------|-------------|
@@ -35,7 +35,7 @@ The available message types depend on the channel. For webchat, the following ty
 | `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.
+Other channels (Slack, WhatsApp, Telegram) may support different message types. When you specify a channel on your conversation, TypeScript will only allow the message types that channel supports.
 
 ## Examples
 
@@ -129,7 +129,9 @@ conversation.tags.priority = "high"
 conversation.tags.category = "billing"
 ```
 
-Tags must be declared in `agent.config.ts` under `conversation.tags`. See [Agent Configuration](/adk/setup/configuration#tags).
+<Note>
+Tags must be declared in `agent.config.ts` under `conversation.tags`. Check out our guide to [configuration your agent](/adk/setup/configuration#tags) for more information.
+</Note>
 
 ## Loading a conversation by ID
 
diff --git a/adk/conversations/state.mdx b/adk/conversations/state.mdx
index 3b1a7b02..5d7747a5 100644
--- a/adk/conversations/state.mdx
+++ b/adk/conversations/state.mdx
@@ -1,5 +1,5 @@
 ---
-title: Manage states
+title: Manage state
 description: Store and reuse data across conversations, users, and the entire bot.
 ---
 
@@ -17,9 +17,9 @@ State lets your agent persist data between handler calls. The ADK provides three
 
 ### Bot and user state
 
-Define these in `agent.config.ts`:
+Define bot and user state in `agent.config.ts`:
 
-```typescript
+```typescript highlight={6-10, 12-18}
 import { z, defineConfig } from "@botpress/runtime"
 
 export default defineConfig({
@@ -45,9 +45,9 @@ Use `.default()` to set initial values and `.describe()` to document what each f
 
 ### Conversation state
 
-Defined on each conversation using the `state` prop:
+Define conversation state on a `Conversation` using the `state` prop:
 
-```typescript
+```typescript highlight={5-8}
 import { Conversation, z } from "@botpress/runtime"
 
 export default new Conversation({
@@ -68,11 +68,11 @@ export default new Conversation({
 
 ## Reading and writing state
 
-State changes are saved automatically. You don't need to call a save method.
+State objects are mutable and can be modified directly. Your changes are saved automatically—you don't need to call a save method.
 
-### Bot state
+## Bot state
 
-Available anywhere in your agent (conversations, actions, tools, workflows):
+You can access bot state anywhere in your agent (conversations, actions, tools, workflows):
 
 ```typescript
 import { bot } from "@botpress/runtime"
@@ -83,7 +83,7 @@ bot.state.ticketCounter = counter + 1
 
 ### User state
 
-Available anywhere the current user context exists:
+You can access user state anywhere the current user context exists:
 
 ```typescript
 import { user } from "@botpress/runtime"
@@ -94,7 +94,7 @@ user.state.visitCount = (user.state.visitCount || 0) + 1
 
 ### Conversation state
 
-Accessed via the `state` parameter in the handler:
+You can access conversation state via the `state` parameter in the conversation handler:
 
 ```typescript
 handler: async ({ state, execute }) => {
@@ -151,7 +151,7 @@ export default new Conversation({
 
 ## Tags
 
-Tags are string key-value pairs you can attach to bots, users, conversations, messages, and workflows. They are useful for categorization, filtering, and querying.
+Tags are string key-value pairs you can attach to bots, users, conversations, messages, and workflows. They're useful for categorization, filtering, and querying.
 
 ### Defining tags
 
@@ -190,7 +190,7 @@ bot.tags.environment = "production"
 user.tags.role = "admin"
 ```
 
-Conversation tags are accessed via the conversation instance:
+You can access conversation tags via the `conversation` instance:
 
 ```typescript
 handler: async ({ conversation }) => {
diff --git a/adk/data/knowledge.mdx b/adk/data/knowledge.mdx
index 3c493dec..33f3b871 100644
--- a/adk/data/knowledge.mdx
+++ b/adk/data/knowledge.mdx
@@ -135,7 +135,7 @@ const FileSource = DataSource.Directory.fromPath("./src/knowledge/docs", {
 
 ## Search a knowledge base directly
 
-To search a KB outside of `execute()`, call `search()` on the instance. Useful for custom retrieval, suggested-articles UIs, or populating context manually:
+To search a KB outside of `execute()`, call `search()` on the instance. Useful for custom retrieval, suggested-articles user interfaces, or populating context manually:
 
 ```typescript
 const result = await ProductDocs.search("how do I reset my password?", {
diff --git a/adk/data/tables.mdx b/adk/data/tables.mdx
index a74dfeeb..cf0bd816 100644
--- a/adk/data/tables.mdx
+++ b/adk/data/tables.mdx
@@ -3,7 +3,7 @@ title: Tables
 description: Define and query structured data storage.
 ---
 
-Tables provide typed, structured storage for your agent. You define a schema using `z` from `@botpress/runtime`, and the ADK syncs it with Botpress Cloud on deploy. Tables are accessible from conversations, workflows, actions, tools, and triggers.
+Tables provide typed, structured storage for your agent. You define a schema using `z` from `@botpress/runtime`, and the ADK syncs it with Botpress on deploy. Tables are accessible from conversations, workflows, actions, tools, and triggers.
 
 ## Creating a table
 
@@ -26,9 +26,7 @@ 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.
+The `description` field 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 when calling [`.upsertRows()`](#upsert-rows) so you don't have to pass it on every call.
 
 <Frame>
   <img alt="Tables page in dev console" className="block dark:hidden" src="../assets/tables-console.png" />
@@ -37,15 +35,17 @@ The dev console under **Tables** is the primary way to manage table data. You ca
 
 ### Naming rules
 
-- Must start with a letter, underscore, or `$`
-- 35 characters or less
-- Only letters, numbers, and underscores
+Table names:
+
+- Must with a letter, underscore, or `$`
+- Must be 35 characters or less
+- Must contain only letters, numbers, and underscores
 - Must end with `Table`
 - Cannot be a UUID
 
 ### Searchable columns
 
-Mark columns as searchable to enable semantic search:
+You can mark columns as searchable to enable semantic search:
 
 ```typescript
 export default new Table({
@@ -61,9 +61,9 @@ 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`:
+A computed column is derived from other columns. Set `computed: true`, pass the columns it depends on into `dependencies`, and return its value from `value`:
 
-```typescript
+```typescript highlight={7,9-10}
 export default new Table({
   name: "OrderTable",
   columns: {
@@ -79,7 +79,7 @@ export default new Table({
 })
 ```
 
-Computed columns recalculate whenever their dependencies change. When you write to the table, pass `waitComputed: true` to block until the recalculation finishes:
+Computed columns recalculate whenever their dependencies change. When you write to the table, you can pass `waitComputed: true` to block any further modifications to the table until the recalculation finishes:
 
 ```typescript
 await OrderTable.createRows({
@@ -88,9 +88,19 @@ await OrderTable.createRows({
 })
 ```
 
+## Managing table data
+
+You can manage your table data in the dev console under **Data > Tables**. Here, you can:
+
+- View the sync state between your code and Botpress' servers
+- Add/update/delete rows
+- Filter and sort
+- Export to CSV
+- Copy data between development and production environments
+
 ## CRUD operations
 
-Import your table and use the typed instance methods.
+To perform operations on your table within your agent's code, import the table and use the typed instance methods.
 
 ### Create rows
 
@@ -129,7 +139,7 @@ await OrderTable.updateRows({
 
 ### Upsert rows
 
-Insert or update based on a key column. If you set `keyColumn` on the table, you can omit it here:
+Insert or update based on a key column:
 
 ```typescript
 const { inserted, updated } = await OrderTable.upsertRows({
@@ -138,21 +148,31 @@ const { inserted, updated } = await OrderTable.upsertRows({
 })
 ```
 
-If `keyColumn` is omitted on both the table and the call, it defaults to `id`.
+If you [set `keyColumn` on the table](#creating-a-table), you can omit it here.
+
+<Note>
+If `keyColumn` is omitted on both the table defintion and the `upsertRows` call, it defaults to `id`.
+</Note>
 
 ### Delete rows
 
-```typescript
+<CodeGroup>
+```typescript Delete rows by name
 await OrderTable.deleteRows({ status: "cancelled" })
+```
 
+```typescript Delete rows by ID
 await OrderTable.deleteRowIds([1, 2, 3])
+```
 
+```typescript Delete all rows
 await OrderTable.deleteAllRows()
 ```
+</CodeGroup>
 
 ## Filtering
 
-Use operators for advanced queries:
+When calling `findRows()`, you can pass in filters for specific rows. These can use [MongoDB-style operators](https://www.mongodb.com/docs/manual/reference/mql/query-predicates/) for advanced queries:
 
 ```typescript
 const { rows } = await OrderTable.findRows({
@@ -181,7 +201,7 @@ const { rows } = await OrderTable.findRows({
 
 ### Logical operators
 
-Combine filters with `$and`, `$or`, and `$not`:
+You can combine filters with `$and`, `$or`, and `$not`:
 
 ```typescript
 const { rows } = await OrderTable.findRows({
@@ -196,7 +216,7 @@ const { rows } = await OrderTable.findRows({
 
 ## Semantic search
 
-Search across `searchable` columns using natural language:
+You can search across [`searchable` columns](#searchable-columns) using natural language:
 
 ```typescript
 const { rows } = await TicketTable.findRows({
@@ -217,23 +237,40 @@ const { rows } = await TicketTable.findRows({
 
 ## Aggregation
 
-Group and aggregate data:
+Aggregation groups rows by one or more columns and computes summary statistics for other columns. This transforms your table data into summary reports.
+
+Pass a `group` object to `findRows()` where each key is a column name and the value is either a single operation or an array of operations:
 
 ```typescript
 const { rows } = await OrderTable.findRows({
   group: {
-    status: "key",
-    total: ["sum", "avg", "count"],
+    status: "key",              // Group by status
+    total: ["sum", "avg"],      // Sum and average the total column
+    id: "count",                // Count rows in each group
   },
 })
 ```
 
-| Operation | Applies to | Description |
-|-----------|-----------|-------------|
-| `key` | All types | Group by this value |
-| `count` | All types | Count of rows |
-| `sum` | Numbers | Sum of values |
-| `avg` | Numbers | Average of values |
-| `max` | Numbers, strings, dates | Maximum value |
-| `min` | Numbers, strings, dates | Minimum value |
-| `unique` | All types | Array of unique values |
+The returned rows have different fields based on your group configuration. The field names combine the column name (in `camelCase`) with the operation:
+
+```typescript
+// For the group config above, each row in the result contains:
+{
+  statusKey: "pending",     // The grouping value
+  totalSum: 1500.00,        // Sum of totals in this group
+  totalAvg: 125.00,         // Average of totals in this group
+  idCount: 12,              // Number of rows in this group
+}
+```
+
+Operations vary by column type:
+
+| Operation | Available for | Returns | Description |
+|-----------|---------------|---------|-------------|
+| `key` | All types | Same as column | Groups rows by this value |
+| `count` | All types | `number` | Number of rows in the group |
+| `sum` | Numbers | `number` | Sum of values |
+| `avg` | Numbers | `number` | Average of values |
+| `max` | Numbers, strings, dates | Same as column | Maximum value |
+| `min` | Numbers, strings, dates | Same as column | Minimum value |
+| `unique` | All types | Array | Array of unique values |
diff --git a/adk/external/actions.mdx b/adk/external/actions.mdx
index 1fd99e0c..3eb0237b 100644
--- a/adk/external/actions.mdx
+++ b/adk/external/actions.mdx
@@ -1,9 +1,9 @@
 ---
 title: Create actions
-description: Create reusable functions callable from anywhere in your agent or from external systems.
+description: Create reusable functions that can be called from anywhere in your agent or from external systems.
 ---
 
-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.
+Actions are reusable functions that hold shared business logic. You can call them from your agent's code (via [conversations](#from-a-conversation), [workflows](#from-a-workflow), [triggers](#from-a-trigger), [tools](@from-a-tool), or  other actions). You can also [call them over HTTP](#calling-from-external-systems) from external systems.
 
 ## Creating an action
 
@@ -50,7 +50,7 @@ Browse and test actions from the dev console:
 
 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
+```typescript highlight={3}
 export default new Action({
   name: "fetchExchangeRate",
   cached: true,
@@ -63,11 +63,11 @@ export default new Action({
 })
 ```
 
-Useful for actions that are pure, expensive, and called repeatedly with the same inputs.
+This is useful for actions that are pure, perform an expensive calculation, and are 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.
+Import `actions` from `@botpress/runtime` and call any action by name. The action's input and output are fully typed.
 
 ### From a conversation
 
@@ -135,9 +135,12 @@ export default new Trigger({
 
 ## As a tool
 
-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()`:
+While actions are just functions that can be called from anywhere, [tools](/adk/conversations/tools) only exist inside `execute()` and are called by the LLM. If you want the LLM to have access to a certain action:
 
-```typescript
+1. Convert it to a tool with `.asTool()`
+2. Pass it into the `tools` field:
+
+```typescript highlight={8}
 import { Conversation, actions } from "@botpress/runtime"
 
 export default new Conversation({
@@ -151,7 +154,7 @@ export default new Conversation({
 })
 ```
 
-You can override the description for the tool:
+You should always provide a detailed description that helps the LLM decide when to use a tool. When converting an action to a tool, you can override its description by passing a string into the`description` field:
 
 ```typescript
 actions.calculateTotal.asTool({ description: "Calculate the total price with tax for the user's cart" })
@@ -170,7 +173,7 @@ await actions.slack.addReaction({ name: "thumbsup", channel, timestamp })
 
 ## Calling from external systems
 
-Actions are exposed via the Botpress Runtime API. External services can call your agent's actions over HTTP:
+Actions are exposed via the Botpress [Runtime API](/api-reference/runtime-api/getting-started)'s [`callAction`](/api-reference/runtime-api/openapi/endpoints/post-v1chatactions) endpoint. External services can call your agent's actions over HTTP:
 
 ```bash
 curl -X POST https://api.botpress.cloud/v1/chat/actions \
@@ -187,5 +190,3 @@ curl -X POST https://api.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.
diff --git a/adk/external/triggers.mdx b/adk/external/triggers.mdx
index 683e2c41..e1218bf1 100644
--- a/adk/external/triggers.mdx
+++ b/adk/external/triggers.mdx
@@ -23,9 +23,13 @@ export default new Trigger({
 
 The `events` array lists which events this trigger subscribes to. The handler runs when any of the listed events fire.
 
+<Note>
 Trigger names must be at least 3 characters and contain only alphanumeric characters and underscores.
+</Note>
 
-Browse your triggers from the dev console:
+## Viewing triggers in the dev console
+
+You can browse your triggers from the dev console at **Components > Triggers**:
 
 <Frame>
   <img alt="Triggers page in dev console" className="block dark:hidden" src="../assets/triggers-console.png" />
@@ -49,7 +53,7 @@ To make API calls from a trigger, pull the client from the runtime context: `con
 
 A trigger can subscribe to multiple events and handle each differently:
 
-```typescript
+```typescript highlight={4-8}
 export default new Trigger({
   name: "onLinearIssue",
   description: "Handle Linear issue events",
@@ -74,8 +78,7 @@ export default new Trigger({
 
 Triggers can subscribe to custom events you define in `agent.config.ts`:
 
-```typescript
-// agent.config.ts
+```typescript title="agent.config.ts"
 export default defineConfig({
   events: {
     orderPlaced: {
@@ -89,8 +92,7 @@ export default defineConfig({
 })
 ```
 
-```typescript
-// src/triggers/on-order.ts
+```typescript title="src/triggers/on-order.ts"
 import { Trigger } from "@botpress/runtime"
 
 export default new Trigger({
@@ -107,7 +109,7 @@ export default new Trigger({
 
 Triggers can call actions for reusable logic:
 
-```typescript
+```typescript highlight={8-10}
 import { Trigger, actions } from "@botpress/runtime"
 
 export default new Trigger({
diff --git a/adk/introduction.mdx b/adk/introduction.mdx
index e39cd62a..2a26831b 100644
--- a/adk/introduction.mdx
+++ b/adk/introduction.mdx
@@ -3,7 +3,9 @@ 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.
+The Agent Development Kit (ADK) is a **CLI tool and development framework for building AI agents on Botpress**. It provides a streamlined development experience with TypeScript support, hot reloading, and type-safe APIs for creating AI applications.
+
+You write conversations, workflows, tools, and actions as code. Botpress handles hosting, scaling, and channel delivery.
 
 <Frame>
   <img alt="Botpress ADK" className="block dark:hidden" src="./assets/welcome.png" />
diff --git a/adk/quickstart.mdx b/adk/quickstart.mdx
index ce47e0fc..8fd306d9 100644
--- a/adk/quickstart.mdx
+++ b/adk/quickstart.mdx
@@ -10,7 +10,7 @@ By the end of this guide, you'll have a working AI agent that responds to messag
 
   * 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)
+  * A supported package manager — [bun](https://bun.sh), [pnpm](https://pnpm.io), [yarn](https://yarnpkg.com) or [npm](https://www.npmjs.com)
 </Info>
 
 ## Installation
@@ -65,6 +65,8 @@ cd my-agent
 
 ## Test your agent
 
+Now, you’re ready to test your agent.
+
 ### Start the development server
 
 Start the development server with hot reloading:
@@ -95,6 +97,22 @@ Go to the **Chat** page and send a message to test your agent:
 
 The dev server watches your files and rebuilds on every change.
 
+### Chat in the terminal
+
+Alternatively, open a new terminal window and start a conversation with your agent from the command line:
+
+```bash
+adk chat
+```
+
+```txt
+Botpress Chat
+Type "exit" or press ESC key to quit
+👤 Hey!
+🤖 Hello! How can I assist you today?
+>>
+```
+
 ## Deploy your agent
 
 When you're ready to go live:
diff --git a/adk/setup/configuration.mdx b/adk/setup/configuration.mdx
index 42859280..5124f44d 100644
--- a/adk/setup/configuration.mdx
+++ b/adk/setup/configuration.mdx
@@ -5,19 +5,52 @@ description: Understand your project structure and how to configure your agent.
 
 ## Project structure
 
-After running `adk init`, these are the core files and folders of an ADK project:
-
-| Path | Purpose |
-|------|---------|
-| `agent.config.ts` | Agent configuration: models, state, dependencies, secrets |
-| `src/conversations/` | Message handlers for user interactions |
-| `src/workflows/` | Long-running background processes |
-| `src/actions/` | Reusable logic callable from anywhere |
-| `src/tools/` | Functions the AI model can call |
-| `src/tables/` | Database table schemas |
-| `src/knowledge/` | RAG knowledge base sources |
-| `src/triggers/` | Event-based handlers |
-| `evals/` | Automated conversation tests |
+Here's a breakdown of the key files in your project after running `adk init`:
+
+<Tree>
+  <Tree.Folder name="src" defaultOpen>
+    <Tree.Folder name="actions">
+      <Tree.File name="index.ts" />
+    </Tree.Folder>
+
+    <Tree.Folder name="conversations">
+      <Tree.File name="index.ts" />
+    </Tree.Folder>
+
+    <Tree.Folder name="evals">
+      <Tree.File name="index.ts" />
+    </Tree.Folder>
+
+    <Tree.Folder name="knowledge">
+      <Tree.File name="index.ts" />
+    </Tree.Folder>
+
+    <Tree.Folder name="tables">
+      <Tree.File name="index.ts" />
+    </Tree.Folder>
+
+    <Tree.Folder name="triggers">
+      <Tree.File name="index.ts" />
+    </Tree.Folder>
+
+    <Tree.Folder name="workflows">
+      <Tree.File name="index.ts" />
+    </Tree.Folder>
+  </Tree.Folder>
+
+  <Tree.File name=".mcp.json" />
+
+  <Tree.File name="agent.config.ts" />
+
+  <Tree.File name="agent.json" />
+
+  <Tree.File name="agent.local.json" />
+
+  <Tree.File name="AGENTS.md" />
+
+  <Tree.File name="CLAUDE.md" />
+
+</Tree>
 
 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.
 
diff --git a/adk/setup/environment.mdx b/adk/setup/environment.mdx
index 14f2d329..8e3e8ebe 100644
--- a/adk/setup/environment.mdx
+++ b/adk/setup/environment.mdx
@@ -56,15 +56,8 @@ adk secret:set OPENAI_KEY "sk-prod-..." --prod
 
 Development and production values are stored in separate buckets inside `.adk/secrets.json`. Setting a development value never touches production values, and vice versa.
 
-You can also add, edit, and delete secrets from the dev console. 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>
-
 <Tip>
-  For the full `adk secret` command set, see the [CLI reference](/adk/cli-reference#adk-secret).
+  Check out the [CLI reference](fix-before-merge) for full documentation of the `adk secret` command.
 </Tip>
 
 ### Using secrets at runtime
@@ -89,6 +82,15 @@ The `secrets` import is a typed proxy over environment variables. Required secre
   Secrets are read-only at runtime. Attempting to reassign the value of a secret will throw an error.
 </Note>
 
+### Managing secrets in the dev console
+
+You can also manage secrets from the dev console under **Settings > Secrets**. The UI lets you add, edit, and delete secrets for both development and production 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>
+
 ### Naming rules
 
 Secret keys must be `SCREAMING_SNAKE_CASE`:
@@ -149,6 +151,15 @@ const retries = configuration.maxRetries
 
 Configuration is read-only. Attempting to set a value at runtime throws an error.
 
+### 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>
+
 ## Preflight checks
 
 Run `adk check` to validate your project without starting the dev server:
diff --git a/adk/setup/integrations.mdx b/adk/setup/integrations.mdx
index 67543db1..75374d0f 100644
--- a/adk/setup/integrations.mdx
+++ b/adk/setup/integrations.mdx
@@ -23,9 +23,9 @@ Most integrations need configuration (API keys, tokens, webhook URLs) before the
   <img alt="Integration configuration in dev console" className="hidden dark:block" src="../assets/integration-config-console-dark.png" />
 </Frame>
 
-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.
+Integration configuration is stored directly on Botpress' servers, 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.
+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
 
diff --git a/adk/testing/evals.mdx b/adk/testing/evals.mdx
index 8be8d392..94163c0d 100644
--- a/adk/testing/evals.mdx
+++ b/adk/testing/evals.mdx
@@ -100,7 +100,7 @@ Assert on which tools the agent called:
 | Assertion | Description |
 |-----------|-------------|
 | `{ called: "toolName" }` | Tool was called |
-| `{ called: "toolName", params: { key: { equals: "value" } } }` | Tool was called with matching params |
+| `{ called: "toolName", params: { key: { equals: "value" } } }` | Tool was called with matching parameters |
 | `{ not_called: "toolName" }` | Tool was not called |
 | `{ call_order: ["tool1", "tool2"] }` | Tools were called in this order |
 
diff --git a/adk/testing/scripts.mdx b/adk/testing/scripts.mdx
index 82b686da..128de6cc 100644
--- a/adk/testing/scripts.mdx
+++ b/adk/testing/scripts.mdx
@@ -43,7 +43,7 @@ The runner looks for exports in this order:
 
 ## Arguments
 
-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:
+Extra arguments after the script path are passed to your function. Positional arguments pass through directly; put flag-like arguments (anything starting with `-`) after a `--` separator so Commander doesn't try to parse them:
 
 ```bash
 adk run scripts/process.ts order-123
@@ -69,5 +69,5 @@ adk run scripts/migrate.ts --prod
 - **Seed data** into tables for development or testing
 - **Run migrations** to update table schemas or transform data
 - **Generate reports** by querying tables and knowledge bases
-- **Maintenance tasks** like cleaning up old data or reindexing
+- **Maintenance tasks** like cleaning up old data or re-indexing
 - **Test actions** by calling them directly outside a conversation
diff --git a/adk/workflows/request-notify.mdx b/adk/workflows/request-notify.mdx
index 56cc7ed1..34ca4356 100644
--- a/adk/workflows/request-notify.mdx
+++ b/adk/workflows/request-notify.mdx
@@ -7,13 +7,13 @@ Workflows run in the background, but sometimes they need input from the user or
 
 ## Requests
 
-A request pauses the workflow and asks the conversation for data. The workflow defines what it needs, the conversation handler collects it from the user and sends it back.
+A request pauses the workflow and asks the conversation for data. The workflow defines what it needs, the conversation handler collects it from the user and sends it back to the workflow.
 
 ### Define requests in the workflow
 
 Declare the request schemas in the workflow definition:
 
-```typescript
+```typescript highlight={5-14}
 import { Workflow, z } from "@botpress/runtime"
 
 export default new Workflow({
@@ -40,7 +40,7 @@ export default new Workflow({
 })
 ```
 
-`step.request()` pauses the workflow and sends a `workflow_request` event to the conversation. The second argument is a human-readable message describing what's needed.
+`step.request()` pauses the workflow and sends a `workflow_request` event to the conversation. The first argument is the name of the data being requested, and the second argument is a natural language prompt for that data.
 
 ### Handle requests in the conversation
 
@@ -163,12 +163,4 @@ if (props.type === "workflow_callback") {
   }
   return
 }
-```
-
-## Summary
-
-| Mechanism | Direction | Pauses workflow? | Handler type |
-|-----------|-----------|-----------------|--------------|
-| `step.request()` | Workflow asks conversation | Yes | `workflow_request` |
-| `step.notify()` | Workflow tells conversation | No | `workflow_notify` |
-| Callback | Workflow completes | N/A | `workflow_callback` |
+```
\ No newline at end of file
diff --git a/adk/workflows/steps.mdx b/adk/workflows/steps.mdx
index f43b068b..628e7bd5 100644
--- a/adk/workflows/steps.mdx
+++ b/adk/workflows/steps.mdx
@@ -43,7 +43,7 @@ const data = await step("fetch-data", async ({ attempt }) => {
 }, { maxAttempts: 10 })
 ```
 
-If a step exhausts all retries, it throws. This fails the entire workflow unless you catch it:
+If a step exhausts all retries, it throws an error. This fails the entire workflow unless you catch it:
 
 ```typescript
 try {
@@ -65,11 +65,11 @@ await step.sleep("wait-5-min", 5 * 60 * 1000)
 await step.sleepUntil("wait-until-noon", new Date("2025-01-15T12:00:00Z"))
 ```
 
-The workflow is suspended during sleep. No compute is used.
+The workflow is suspended during sleep, and no further compute is used.
 
 ## Progress
 
-Record a checkpoint without running any work. Useful for observability when you want to mark milestones in a long handler:
+Use `.progress()` to record a checkpoint without running any work. This is useful for observability when you want to mark milestones in a long handler:
 
 ```typescript
 await step.progress("Started import")
@@ -81,17 +81,15 @@ await step.progress("Finished")
 
 ## Listen
 
-Pause the workflow and set its status to `"listening"`, waiting to be resumed by an external event:
+Use `.listen()` to suspend the workflow and set its status to `"listening"`. The workflow then waits to be resumed by an external event. You can specify this event by passing its name in as an argument:
 
 ```typescript
 await step.listen("wait-for-payment")
 ```
 
-The workflow suspends at this point and uses no compute until it is resumed.
-
 ## Fail and abort
 
-Stop execution explicitly:
+Use `.fail()` or `.abort()` to stop execution explicitly:
 
 ```typescript
 // Mark as failed with a message
@@ -103,7 +101,7 @@ step.abort()
 
 ## Child workflows
 
-Start another workflow and wait for it to complete:
+You can start another workflow and wait for it to complete:
 
 ```typescript
 import ProcessingWorkflow from "../workflows/processing"
@@ -124,7 +122,7 @@ const result = await step.waitForWorkflow("wait-for-child", childWorkflow.id)
 
 ## Parallel processing
 
-### map
+### `map`
 
 Process an array of items in parallel and collect results:
 
@@ -137,7 +135,7 @@ const results = await step.map(
 )
 ```
 
-### forEach
+### `forEach`
 
 Process items in parallel without collecting results:
 
@@ -150,7 +148,7 @@ await step.forEach(
 )
 ```
 
-### batch
+### `batch`
 
 Process items in sequential batches:
 
diff --git a/adk/zai/classify.mdx b/adk/zai/classify.mdx
index 62e7b263..51e5a63b 100644
--- a/adk/zai/classify.mdx
+++ b/adk/zai/classify.mdx
@@ -17,7 +17,7 @@ const isSpam = await adk.zai.check(emailBody, "is this spam?")
 // true
 ```
 
-Call `.result()` for the boolean plus the LLM's reasoning:
+Call `.result()` for the Boolean plus the LLM's reasoning:
 
 ```typescript
 const { output } = await adk.zai.check(emailBody, "is this spam?").result()
@@ -27,7 +27,7 @@ const { output } = await adk.zai.check(emailBody, "is this spam?").result()
 
 ## Label content
 
-`zai.label()` applies multiple boolean labels to content:
+`zai.label()` applies multiple Boolean labels to content:
 
 ```typescript
 const result = await adk.zai.label(emailBody, {
diff --git a/adk/zai/overview.mdx b/adk/zai/overview.mdx
index fb74f2ee..7a74b999 100644
--- a/adk/zai/overview.mdx
+++ b/adk/zai/overview.mdx
@@ -18,7 +18,7 @@ const zai = adk.zai
 | Method | What it does | Page |
 |--------|-------------|------|
 | `extract()` | Pull structured data from unstructured text | [Extract structured data](/adk/zai/extract) |
-| `check()` | Verify a boolean condition | [Classify, validate and filter](/adk/zai/classify) |
+| `check()` | Verify a Boolean condition | [Classify, validate and filter](/adk/zai/classify) |
 | `label()` | Categorize content with multiple labels | [Classify, validate and filter](/adk/zai/classify) |
 | `filter()` | Filter an array by a condition | [Classify, validate and filter](/adk/zai/classify) |
 | `sort()` | Sort items using natural language criteria | [Classify, validate and filter](/adk/zai/classify) |
diff --git a/docs.json b/docs.json
index 0baae3c0..f3812580 100644
--- a/docs.json
+++ b/docs.json
@@ -152,7 +152,7 @@
                 ]
               },
               {
-                "group": "AI Native Development",
+                "group": "AI-native Development",
                 "pages": [
                   "/adk/ai-native/skills"
                 ]
@@ -725,6 +725,58 @@
     {
       "source": "/webchat/interact/dropdown-menus",
       "destination": "/studio/guides/how-to/dropdown-menus"
+    },
+    {
+      "source": "/adk/concepts/actions",
+      "destination": "/adk/external/actions"
+    },
+    {
+      "source": "/adk/concepts/triggers",
+      "destination": "/adk/external/triggers"
+    },
+    {
+      "source": "/adk/concepts/conversations",
+      "destination": "/adk/conversations/setup"
+    },
+    {
+      "source": "/adk/concepts/knowledge",
+      "destination": "/adk/data/knowledge"
+    },
+    {
+      "source": "/adk/concepts/tables",
+      "destination": "/adk/data/tables"
+    },
+    {
+      "source": "/adk/concepts/state",
+      "destination": "/adk/conversations/state"
+    },
+    {
+      "source": "/adk/concepts/tools",
+      "destination": "/adk/conversations/tools"
+    },
+    {
+      "source": "/adk/concepts/workflows",
+      "destination": "/adk/workflows/create"
+    },
+    {
+      "source": "/adk/concepts/configuration",
+      "destination": "/adk/setup/configuration"
+    },
+    {
+      "source": "/adk/managing-integrations",
+      "destination": "/adk/setup/integrations"
+    },
+    {
+      "source": "/adk/project-structure",
+      "destination": "/adk/setup/configuration"
+    },
+    {
+      "source": "/adk/runtime",
+      "destination": "/adk/setup/configuration"
+    },
+    {
+      "source": "/adk/zai/reference",
+      "destination": "/adk/zai/overview"
     }
   ],
   "integrations": {