final audit of ADK docs

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>

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) |