feat: restructure and add desk

.vale.ini

@@ -6,10 +6,13 @@ IgnoredScopes = code, tt, frontmatter
 BasedOnStyles = Vale, Botpress
 Markup = true
 
-[for-developers/adk/*]
+[/adk/*]
 Botpress.workflows = NO
 Vale.Terms = NO
 
+[/desk/*]
+Botpress.workflows = NO
+
 [*]
 Botpress.button-capitalization = NO
 Botpress.chatbot = NO

README.md

@@ -17,12 +17,14 @@ To contribute, install the following software if you haven't already:
 ## Getting started
 
 1. **Clone the repository:**
+
    ```bash
    git clone https://github.com/botpress/docs.git
    cd docs
    ```
 
 2. **Install dependencies:**
+
    ```bash
    pnpm install
    ```
@@ -41,10 +43,10 @@ The Botpress documentation is built with [Mintlify](https://mintlify.com/). Here
 docs/
 ├── docs.json              # Mintlify configuration & navigation
 ├── home.mdx               # Homepage content
-├── learn/                 # Learning materials and guides
+├── studio/                # Documentation for Botpress Studio
 ├── integrations/          # Integration documentation
 ├── webchat/              # Webchat-specific docs
-├── for-developers/       # Developer-focused content
+├── adk/                   # Documentation for the Botpress Agent Development Kit (ADK)
 ├── api-reference/        # API documentation
 ├── snippets/             # Reusable content snippets
 ├── changelog.mdx         # Product changelog
@@ -56,10 +58,10 @@ docs/
 
 ### MDX
 
-All documentation is written in MDX (Markdown with JSX components). You can find full list of supported components in the [Mintlify documentation](https://mintlify.com/docs/text). 
+All documentation is written in MDX (Markdown with JSX components). You can find full list of supported components in the [Mintlify documentation](https://mintlify.com/docs/text).
 
 > [!NOTE]
-> 
+>
 > If you're using VS Code or Cursor, we recommend also installing the official Mintlify extension. This will enable autocomplete for most Mintlify components.
 
 ### Images
@@ -110,15 +112,15 @@ If you're working on documentation for an integration:
    ```zsh
    pnpm run update-integrations
    ```
-   
+
    This will fetch the most up-to-date information for any integrations modified on the current branch.
 
 > [!TIP]
 >
 > You can also update a single integration:
 >
 > ```zsh
-> pnpm run update-integrations <integration-name> 
+> pnpm run update-integrations <integration-name>
 > ```
 >
 > or update all integrations at once:
@@ -139,7 +141,6 @@ This check also runs on every pull request in the repository.
 
 ## Development workflow
 
-
 ### Make a change
 
 1. Fork the repository
@@ -149,7 +150,7 @@ This check also runs on every pull request in the repository.
 5. Validate writing style with `make check-writing` (if Vale is installed)
 6. Check for broken links using `mint broken-links`
 7. Submit a pull request with a clear description of your changes
-   
+
 ### Raise an issue
 
 Use this repository for specific documentation-related issues only. Report any product bugs (or general documentation feedback) via [Discord](https://discord.gg/botpress).
@@ -158,4 +159,4 @@ Use this repository for specific documentation-related issues only. Report any p
 
 Join the conversation on our [Discord](https://discord.gg/botpress) server for any other questions related to Botpress—we'd love to hear from you.
 
-Thank you for helping us improve the Botpress documentation!
+Thank you for helping us improve the Botpress documentation!

for-developers/adk/concepts/actions.mdx → adk/concepts/actions.mdx

@@ -97,7 +97,7 @@ export default new Autonomous.Tool({
 
 ### 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:
+You can provide an action to your agent as a [tool](/adk/concepts/tools) using the `asTool` method:
 
 ```ts highlight={1,8}
 import { Conversation, actions } from "@botpress/runtime";
@@ -115,7 +115,7 @@ export default new Conversation({
 
 ## Integration actions
 
-When you [install an integration](/for-developers/adk/managing-integrations), its actions become available anywhere in your agent's source:
+When you [install an integration](/adk/managing-integrations), its actions become available anywhere in your agent's source:
 
 ```ts highlight={1, 12-14}
 import { Trigger, actions } from "@botpress/runtime";

for-developers/adk/concepts/tools.mdx → adk/concepts/tools.mdx

@@ -73,7 +73,7 @@ export default new Conversation({
 
 ## Converting actions to tools
 
-You can convert [actions](/for-developers/adk/concepts/actions) to tools using the `asTool()` method:
+You can convert [actions](/adk/concepts/actions) to tools using the `asTool()` method:
 
 ```typescript highlight={1, 8}
 import { Conversation, actions } from "@botpress/runtime";
@@ -91,7 +91,7 @@ export default new Conversation({
 
 ## Converting workflows to tools
 
-You can convert [workflows](/for-developers/adk/concepts/workflows) to tools using the `asTool()` method:
+You can convert [workflows](/adk/concepts/workflows) to tools using the `asTool()` method:
 
 ```typescript highlight={2, 9}
 import { Conversation } from "@botpress/runtime";

for-developers/adk/concepts/workflows/overview.mdx → adk/concepts/workflows/overview.mdx

@@ -3,7 +3,7 @@ title: Workflows
 sidebarTitle: Overview
 ---
 
-Workflows are long-running processes that handle complex, multi-step operations or scheduled tasks. Unlike [conversations](/for-developers/adk/concepts/conversations), workflows can run independently on a schedule or be triggered by events.
+Workflows are long-running processes that handle complex, multi-step operations or scheduled tasks. Unlike [conversations](/adk/concepts/conversations), workflows can run independently on a schedule or be triggered by events.
 
 <Note>
   While workflows in the ADK are similar in concept to [Workflows](/studio/concepts/workflows) in Botpress Studio, they behave differently and shouldn't be treated as equivalent.
@@ -78,13 +78,13 @@ Steps are *persisted*—if a workflow is interrupted, it can resume from the las
 
 The `step` object also provides many additional methods for workflow control:
 
-<Card title="Step reference" icon="list-check" href="/for-developers/adk/concepts/workflows/steps">
+<Card title="Step reference" icon="list-check" href="/adk/concepts/workflows/steps">
   Learn about all available step methods
 </Card>
 
 ### Handling failing steps
 
-If a step (or a [step method](/for-developers/adk/concepts/workflows/steps#methods)) fails, it'll throw a rejected promise. This will fail not only the current step, but the *entire workflow*.
+If a step (or a [step method](/adk/concepts/workflows/steps#methods)) fails, it'll throw a rejected promise. This will fail not only the current step, but the *entire workflow*.
 
 To avoid this, make sure you catch errors gracefully:
 

for-developers/adk/concepts/workflows/steps.mdx → adk/concepts/workflows/steps.mdx

@@ -1,4 +1,4 @@
-This page contains a full reference for the [`step` function](/for-developers/adk/concepts/workflows/overview#steps).
+This page contains a full reference for the [`step` function](/adk/concepts/workflows/overview#steps).
 
 ```typescript
 const data = await step("fetch-data", async () => {

adk/introduction.mdx

@@ -0,0 +1,75 @@
+<Panel>
+  <ResponseExample>
+    ```ts Basic agent
+    import { Conversation } from "@botpress/runtime";
+
+    export default new Conversation({
+      channel: "*",
+      handler: async ({ execute, message }) => {
+        await execute({
+          instructions: "You are a helpful assistant.",
+        });
+      },
+    });
+    ```
+
+    ```ts Agent with knowledge
+    import { Conversation } from "@botpress/runtime";
+    import { WebsiteKB } from "../knowledge/docs";
+
+    export default new Conversation({
+      channel: "*",
+      handler: async ({ execute, message }) => {
+        await execute({
+          instructions: "You are a helpful assistant.",
+          knowledge: [WebsiteKB]
+        });
+      },
+    });
+    ```
+  </ResponseExample>
+</Panel>
+
+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 conversational AI applications.
+
+## Get started
+
+<CardGroup>
+  <Card
+    title="Quickstart"
+    icon="download"
+    href="/adk/quickstart"
+    cta="Install the CLI"
+    horizontal
+  >
+    Build your first agent in minutes
+  </Card>
+  <Card title="Project structure" horizontal icon="folder" href="/adk/project-structure">
+    Learn how an ADK project is organized
+  </Card>
+</CardGroup>
+
+## What is the ADK?
+
+The ADK is a framework that allows developers to build Botpress agents from code. It provides:
+
+- **Project scaffolding**: Quickly initialize new agent projects with templates
+- **Type-safe development**: Automatic TypeScript type generation for integrations, interfaces, and more
+- **Development workflow**: Hot reloading development server with live updates
+- **Build and deploy**: Compile and deploy agents to Botpress Cloud
+- **Integration management**: Add, update, and manage integrations from the Botpress Hub
+
+## When to use the ADK
+
+The ADK is ideal for:
+
+- Developers who prefer code-based workflows
+- Teams using version control and CI/CD pipelines
+- Projects requiring custom logic and integrations
+- Developers who need TypeScript type safety
+
+<Tip>
+For most users, we recommend Botpress Studio. The ADK is best suited for developers who need more control or integration with development workflows.
+</Tip>

for-developers/adk/project-structure.mdx → adk/project-structure.mdx

@@ -1,24 +1,36 @@
-import { Files, File, Folder } from '/snippets/folder-component.jsx';
-
 ADK projects follow a consistent structure that organizes your agent's code, configuration, and dependencies.
 
 ## Directory structure
 
-<Files>
-  <Folder name="src" defaultOpen>
-    <Folder name="conversations" />
-    <Folder name="workflows" />
-    <Folder name="actions" />
-    <Folder name="tools" />
-    <Folder name="tables" />
-    <Folder name="triggers" />
-    <Folder name="knowledge" />
-  </Folder>
-  <File name="agent.config.ts" />
-  <File name="agent.json" />
-  <File name="package.json" />
-  <File name="tsconfig.json" />
-</Files>
+<Tree>
+  <Tree.Folder name="src" defaultOpen>
+    <Tree.Folder name="conversations">
+      <Tree.File name="index.ts" />
+    </Tree.Folder>
+    <Tree.Folder name="workflows">
+     <Tree.File name="index.ts" />
+    </Tree.Folder>
+    <Tree.Folder name="actions">
+      <Tree.File name="index.ts" />
+    </Tree.Folder>
+    <Tree.Folder name="tools">
+      <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="knowledge">
+      <Tree.File name="index.ts" />
+    </Tree.Folder>
+  </Tree.Folder>
+  <Tree.File name="agent.config.ts" />
+  <Tree.File name="agent.json" />
+  <Tree.File name="package.json" />
+  <Tree.File name="tsconfig.json" />
+</Tree>
 
 ## Configuration files
 
@@ -352,10 +364,10 @@ Don't edit files in the `.botpress` directory manually. They are automatically g
 ## Next steps
 
 <CardGroup Cols={2}>
-  <Card title="Conversations" horizontal icon="message-square" href="/for-developers/adk/concepts/conversations">
+  <Card title="Conversations" horizontal icon="message-square" href="/adk/concepts/conversations">
     Learn about conversation handlers
   </Card>
-  <Card title="Workflows" horizontal icon="workflow" href="/for-developers/adk/concepts/workflows">
+  <Card title="Workflows" horizontal icon="workflow" href="/adk/concepts/workflows">
     Create long-running processes
   </Card>
 </CardGroup>

for-developers/adk/getting-started.mdx → adk/quickstart.mdx

@@ -127,7 +127,7 @@ Type "exit" or press ESC key to quit
 
 ### View the ADK console
 
-Visit [`http://localhost:3001/`](http://localhost:3001/) to access the interactive ADK console. This gives you an intuitive, visual breakdown of your agent project and lets you [configure its integration's settings](/for-developers/adk/managing-integrations#integration-configuration).
+Visit [`http://localhost:3001/`](http://localhost:3001/) to access the interactive ADK console. This gives you an intuitive, visual breakdown of your agent project and lets you [configure its integration's settings](/adk/managing-integrations#integration-configuration).
 
 ## Build your agent
 
@@ -177,10 +177,10 @@ This uploads your agent to your Botpress workspace and makes it available for us
 ## Next steps
 
 <CardGroup Cols={2}>
-  <Card title="Project Structure" horizontal icon="folder" href="/for-developers/adk/project-structure">
+  <Card title="Project Structure" horizontal icon="folder" href="/adk/project-structure">
     Learn about ADK project organization
   </Card>
-  <Card title="Conversations" horizontal icon="message-square" href="/for-developers/adk/concepts/conversations">
+  <Card title="Conversations" horizontal icon="message-square" href="/adk/concepts/conversations">
     Create your first conversation handler
   </Card>
 </CardGroup>