feat(adk): add docs

docs.json

@@ -415,6 +415,29 @@
                 "group": "Get Started",
                 "pages": ["for-developers/introduction"]
               },
+              {
+                "group": "ADK",
+                "tag": "BETA",
+                "pages": [
+                  "for-developers/adk/overview",
+                  "for-developers/adk/getting-started",
+                  "for-developers/adk/project-structure",
+                  {
+                    "group": "Concepts",
+                    "pages": [
+                      "for-developers/adk/concepts/conversations",
+                      "for-developers/adk/concepts/workflows",
+                      "for-developers/adk/concepts/actions",
+                      "for-developers/adk/concepts/tables",
+                      "for-developers/adk/concepts/triggers",
+                      "for-developers/adk/concepts/knowledge"
+                    ]
+                  },
+                  "for-developers/adk/managing-integrations",
+                  "for-developers/adk/console",
+                  "for-developers/adk/cli-reference"
+                ]
+              },
               {
                 "group": "SDK",
                 "pages": [

for-developers/adk/cli-reference.mdx

@@ -0,0 +1,194 @@
+---
+title: CLI reference
+description: All commands and flags available with the ADK CLI.
+---
+
+The ADK CLI provides commands for creating, developing, building, and deploying Botpress agents.
+
+## Global flags
+
+These flags are available for all commands:
+
+| Flag | Alias | Description |
+|------|-------|-------------|
+| `--verbose` | `-v` | Enable verbose logging |
+| `--help` | `-h` | Show help information |
+
+## Commands
+
+### `adk init`
+
+Initialize a new ADK agent project.
+
+**Usage:**
+```bash
+adk init my-agent
+adk init my-agent --template hello-world
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `project-name` | Name of the project directory to create |
+
+**Flags:**
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--template` | Template to use: `blank` or `hello-world` | `blank` |
+| `--package-manager` | Package manager: `npm`, `pnpm`, `yarn`, or `bun` | `bun` |
+
+---
+
+### `adk dev`
+
+Start the development server with hot reloading.
+
+**Usage:**
+```bash
+adk dev
+```
+
+**Flags:**
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--port` | Port for the development server | `3000` |
+| `--source-map` | Generate source maps for debugging | `true` |
+
+**Description:**
+
+The `dev` command:
+1. Generates TypeScript types for your integrations
+2. Builds your agent
+3. Starts a local development server
+4. Watches for file changes and automatically rebuilds
+
+You'll be prompted to authenticate with Botpress Cloud if you haven't already.
+
+---
+
+### `adk build`
+
+Build your agent for production.
+
+**Usage:**
+```bash
+adk build
+```
+
+**Flags:**
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--source-map` | Generate source maps | `true` |
+
+**Description:**
+
+Compiles your agent and creates an optimized build in the `.botpress/dist` directory. The build includes:
+- Compiled TypeScript code
+- Bundled dependencies
+- Generated type definitions
+- Source maps (if enabled)
+
+---
+
+### `adk deploy`
+
+Deploy your agent to Botpress Cloud.
+
+**Usage:**
+```bash
+adk deploy
+```
+
+**Flags:**
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--bot-id` | Bot ID to deploy to (creates new bot if not provided) | |
+| `--no-build` | Skip the build step | `false` |
+
+**Description:**
+
+Deploys your agent to your Botpress workspace. If no `--bot-id` is provided, a new bot will be created. The command will:
+1. Build your agent (unless `--no-build` is specified)
+2. Upload the built agent to Botpress Cloud
+3. Make your agent available for use
+
+---
+
+### `adk add`
+
+Add an integration to your agent project.
+
+**Usage:**
+```bash
+adk add webchat
+adk add slack@latest
+adk add my-workspace/[email protected]
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `integration` | Integration name with optional version (e.g., `webchat@latest` or `[email protected]`) |
+
+**Description:**
+
+Adds an integration to your `dependencies.json` file and generates TypeScript types for it. The integration is automatically enabled by default.
+
+**Examples:**
+
+- `adk add webchat` - Add latest webchat integration
+- `adk add [email protected]` - Add specific version of Slack integration
+- `adk add my-workspace/custom@latest` - Add integration from a specific workspace
+
+---
+
+### `adk chat`
+
+Chat with your deployed bot directly from the CLI.
+
+**Usage:**
+```bash
+adk chat my-bot-id
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `bot-id` | Bot ID to chat with |
+
+**Description:**
+
+Opens an interactive chat session with your deployed bot. Useful for testing your agent's responses.
+
+---
+
+## Project scripts
+
+The ADK also provides npm scripts that you can use in your `package.json`:
+
+```json
+{
+  "scripts": {
+    "dev": "adk dev",
+    "build": "adk build",
+    "deploy": "adk deploy"
+  }
+}
+```
+
+Run these with your package manager:
+
+```bash
+npm run dev
+bun run dev
+pnpm dev
+yarn dev
+```
+

for-developers/adk/concepts/actions.mdx

@@ -0,0 +1,149 @@
+---
+title: Actions
+---
+
+Actions are callable functions that can be invoked by workflows, conversations, or other actions. They encapsulate reusable logic and can be called from anywhere in your agent.
+
+## Creating an action
+
+Create an action in `src/actions/`:
+
+```typescript
+import { Action, z } from "@botpress/runtime";
+
+export default new Action({
+  name: "myAction",
+  input: z.object({}), // Input schema
+  output: z.object({}), // Output schema
+  handler: async ({}) => {
+    // Function logic
+    return {}
+  },
+});
+```
+
+## Action input and output
+
+Define input and output schemas using TypeScript types or Zod schemas:
+
+```typescript highlight={3-11}
+export default new Action({
+  name: "calculateTotal",
+  input: z.object({
+    items: z.array(z.object({
+      price: z.number(),
+      quantity: z.number(),
+    })),
+  }),
+  output: z.object({
+    total: z.number()
+  }),
+  handler: async (input) => {
+    const total = input.items.reduce(
+      (sum, item) => sum + item.price * item.quantity,
+      0
+    );
+    return { total };
+  },
+});
+```
+
+## Calling actions
+
+Actions can be called from anywhere in your agent's source. Just import `actions` and call them directly:
+
+<CodeGroup>
+
+```ts From a workflow highlight={1, 6}
+import { Workflow, actions } from "@botpress/runtime";
+
+export default new Workflow({
+  name: "someWorkflow",
+  handler: async ({}) => {
+    const result = await actions.doSomething();
+      // Other logic
+  },
+});
+```
+
+```ts From a trigger highlight={1, 9}
+import { Trigger, actions } from "@botpress/runtime";
+
+export default new Trigger({
+  name: "webchatConversationStarted",
+  events: [
+    "webchat:conversationStarted",
+  ],
+  handler: async ({ event }) => {
+    const result = await actions.doSomething()
+    // Other logic
+  },
+});
+```
+
+```ts From a tool highlight={1,6}
+import { Autonomous, actions } from "@botpress/runtime"
+
+export default new Autonomous.Tool({
+    name: "someTool",
+    handler: async () => {
+        const result = await actions.doSomething()
+    }
+    // Other logic
+})
+```
+
+</CodeGroup>
+
+### As a tool in a conversation
+
+You can provide an action to your agent as a [tool](/for-developers/adk/concepts/tools) using the `asTool` method:
+
+```ts highlight={1,8}
+import { Conversation, actions } from "@botpress/runtime";
+
+export default new Conversation({
+  channel: "*",
+  handler: async ({ execute }) => {
+    await execute({
+      instructions: "You are a helpful assistant.",
+      tools: [actions.calculateTotal.asTool()]
+    });
+  },
+});
+```
+
+## Integration actions
+
+When you [install an integration](/for-developers/adk/managing-integrations), its actions become available anywhere in your agent's source:
+
+```ts highlight={1, 12-14}
+import { Trigger, actions } from "@botpress/runtime";
+
+export default new Trigger({
+  name: "webchatConversationStarted",
+  events: [
+    "webchat:conversationStarted",
+  ],
+  handler: async ({ event }) => {
+    let conversationId = event.conversationId
+
+    if (conversationId) {
+      await actions.webchat.showWebchat({
+        conversationId
+      })
+    }
+
+  },
+});
+```
+
+## Best practices
+
+- Keep actions focused on a single responsibility
+- Use actions for reusable logic that's needed across multiple parts of your agent
+
+<Tip>
+Actions are ideal for business logic that doesn't need to be part of the conversational flow. They can be tested independently and reused across different parts of your agent.
+</Tip>
+