docs(adk): audit ADK rewrite

adk/advanced/hitl.mdx

@@ -0,0 +1,140 @@
+---
+title: Human-in-the-loop
+description: Escalate conversations to live human agents.
+---
+
+<Info>
+  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. 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).
+
+## Add HITL to your agent
+
+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"
+
+export default defineConfig({
+  name: "my-agent",
+
+  defaultModels: {
+    autonomous: "openai:gpt-4.1-mini-2025-04-14",
+    zai: "openai:gpt-4.1-mini-2025-04-14",
+  },
+
+  dependencies: {
+    integrations: {
+      chat: "chat@1.0.0",
+      webchat: "webchat@0.3.0",
+      hitl: "hitl@2.0.2",
+    },
+
+    plugins: {
+      hitl: {
+        version: "hitl@1.3.0",
+        dependencies: {
+          hitl: {
+            integrationAlias: "hitl",
+            integrationInterfaceAlias: "hitl<hitlSession>",
+          },
+        },
+      },
+    },
+  },
+})
+```
+
+`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 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.
+
+## Start a handoff
+
+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"
+
+export default new Conversation({
+  channel: ["chat.channel", "webchat.channel"],
+  handler: async ({ execute, conversation, message }) => {
+    if (message.payload.text.toLowerCase() === "/starthitl") {
+      await plugins.hitl.actions.startHitl({
+        title: "Support HITL",
+        description: "Escalate to support agent",
+        conversationId: conversation.id,
+        userId: message.userId,
+        configurationOverrides: {
+          onHitlHandoffMessage: "Escalating to support...",
+          userHitlCloseCommand: "/end",
+          agentAssignedTimeoutSeconds: 100,
+        },
+      })
+      return
+    }
+
+    await execute({
+      instructions: "You are a helpful assistant. If the user asks for a human, tell them to type /starthitl.",
+    })
+  },
+})
+```
+
+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.
+
+## 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: "zendesk@1.0.0",
+  },
+  plugins: {
+    hitl: {
+      version: "hitl@1.3.0",
+      dependencies: {
+        hitl: {
+          integrationAlias: "zendesk",
+          integrationInterfaceAlias: "hitl<hitlTicket>",
+        },
+      },
+    },
+  },
+},
+```
+
+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 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>

adk/ai-native/skills.mdx

@@ -0,0 +1,84 @@
+---
+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, 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, run the same command `adk init` runs:
+
+```bash
+npx skills add botpress/skills -s '*' -a codex claude-code -y
+```
+
+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
+```
+
+Or install as a Claude Code plugin:
+
+```
+/plugin marketplace add botpress/skills
+/plugin install adk@botpress-skills
+```
+
+## Available skills
+
+| 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 |
+
+## Slash commands
+
+Skills come with slash commands for Claude Code. Type the command instead of describing what you need:
+
+| Command | What it does |
+|---------|-------------|
+| `/adk-init` | Scaffold a new ADK project |
+| `/adk-debug` | Debug bot issues using traces, logs, and the debug loop |
+| `/adk-eval` | Write, run, or debug evals |
+| `/adk-frontend` | Build frontend apps that integrate with ADK bots |
+| `/adk-integration` | Discover, add, and configure integrations |
+| `/adk-doc-create` | Create documentation for a feature |
+| `/adk-doc-review` | Review project docs for accuracy |
+| `/adk-doc-update` | Update docs after code changes |
+| `/adk-doc-sync` | Check if docs are in sync with code |
+| `/adk-doc-search` | Search project documentation |
+
+## MCP server
+
+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 files:
+
+```bash
+adk mcp:init --all
+```
+
+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 |
+|------|-------------|
+| `adk_get_agent_info` | Get project structure and primitives |
+| `adk_search_integrations` | Search the Botpress Hub |
+| `adk_get_integration` | Get detailed integration info |
+| `adk_add_integration` | Add an integration to the project |
+| `adk_send_message` | Send a test message to the running bot |
+| `adk_query_traces` | Query trace spans for debugging |
+| `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 |
+| `adk_init_project` | Scaffold a new ADK project (only available outside an ADK project) |