Merge Adrian's ADK docs audit into final audit

Incorporates PR #461 (adrian-kahali):
- Get Started restructure: welcome -> introduction, new top-level
  quickstart, updated docs.json sidebar
- Configuration page: <Tip> blocks linking to related guides,
  expandable config snippet, cleaner prose
- Environment setup: consolidated secrets + config explanations,
  better wording
- Integrations: clearer intro, CLI section labelled
- Conversations: <CodeGroup> for channel matching, <Tip> blocks
  for cross-references
- AI execution: <Note> for LLMz reference, tighter phrasing
- Tools: highlight annotations on code blocks

Conflicts resolved in favor of keeping the audit fixes from this
branch (correct default model order, ms units for idleTimeout,
evals/ path, agent-steps screenshot, no trailing Cards, no
standalone Dev console sections, "Botpress Cloud" wording, real
CLI reference secrets table instead of placeholder link) while
taking Adrian's <Tip>/<Note> block styling and structural
improvements.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jacksonyzj

adk/conversations/ai-execution.mdx

@@ -1,15 +1,21 @@
 ---
 title: Run AI agents in a conversation
-description: Use execute() to hand messages to the AI model.
+description: Use `execute()` to hand messages to the AI model.
 ---
 
-`execute()` is the primary way your agent responds to users. It starts an AI loop that iterates until the model reaches a conclusion. On each iteration, the model can read the conversation, call tools, and generate code. The loop ends when the model sends a message to the user (and waits for a reply), triggers an exit, or hits the iteration limit (default 10, configurable).
+The `execute()` function is the primary way your agent responds to users. It starts an AI loop that iterates until the model reaches a conclusion. On each iteration, the model can read the conversation, call tools, and generate code.
 
-The `await` resolves once the loop finishes. Under the hood, `execute()` is powered by [llmz](https://github.com/botpress/botpress/tree/master/packages/llmz).
+The loop ends when the model sends a message to the user (and waits for a reply), triggers an exit, or hits the iteration limit (which defaults to 10 and is configurable).
+
+The `await` resolves once the loop finishes.
+
+<Note>
+Under the hood, `execute()` is powered by [LLMz](https://github.com/botpress/botpress/tree/master/packages/llmz).
+</Note>
 
 ## Basic usage
 
-```typescript
+```typescript highlight={4-6}
 export default new Conversation({
   channel: "webchat.channel",
   handler: async ({ execute }) => {
@@ -24,13 +30,15 @@ The model reads the full conversation transcript, follows your instructions, and
 
 ## Instructions
 
-Instructions tell the model how to behave. They can be a static string or a function that returns a string:
+Pass instructions into the `instructions` field to tell the model how to behave. They can be a static string or a function that returns a string:
 
-```typescript
+```typescript highlight={3, 8-13}
+// String
 await execute({
   instructions: "You are a helpful assistant that speaks formally.",
 })
 
+// Function that returns a string
 await execute({
   instructions: () => {
     const hour = new Date().getHours()
@@ -45,25 +53,29 @@ Instructions are evaluated fresh on each execution. Use a function when you need
 
 ## Knowledge
 
-Attach knowledge bases to give the model access to your documents:
+Pass knowledge bases into the `knowledge` field to give the model access to your documents:
 
-```typescript
+```typescript highlight={6}
 import { DocsKB } from "../knowledge/docs"
-import { FAQKB } from "../knowledge/faq"
+import { FaqKB } from "../knowledge/faq"
 
 await execute({
   instructions: "Answer questions using the documentation.",
-  knowledge: [DocsKB, FAQKB],
+  knowledge: [DocsKB, FaqKB],
 })
 ```
 
-The model automatically searches the knowledge bases when it needs information. Results include citations that trace back to the source documents. See [Knowledge bases](/adk/data/knowledge) for how to define them.
+The model automatically searches the knowledge bases when it needs information. Results include citations that trace back to the source documents.
+
+<Tip>
+  For more information on defining knowledge bases, check out the [Knowledge base documentation](/adk/data/knowledge).
+</Tip>
 
 ## Tools
 
-Give the model functions it can call:
+Give the model functions it can call by passing them into the `tools` field:
 
-```typescript
+```typescript highlight={6}
 import { getWeather } from "../tools/weather"
 import { createTicket } from "../tools/ticket"
 
@@ -77,7 +89,7 @@ The model decides when to call a tool based on the conversation. For a full guid
 
 ## Exits
 
-Exits let the model end execution with a structured result:
+Pass in `exits` to let the model end execution with a structured result:
 
 ```typescript
 import { Autonomous, z } from "@botpress/runtime"
@@ -104,7 +116,7 @@ if (result.exit?.name === "handoffToHuman") {
 
 ## Model override
 
-Override the default model for a specific execution:
+You can override the default model for a specific execution:
 
 ```typescript
 await execute({
@@ -126,6 +138,8 @@ The default model is set in `agent.config.ts` under `defaultModels.autonomous`.
 
 ## Temperature and reasoning
 
+To control the model's temperature and reasoning effort, use the `temperature` and `reasoningEffort` props:
+
 ```typescript
 await execute({
   instructions: "You are a helpful assistant.",
@@ -150,7 +164,7 @@ await execute({
 })
 ```
 
-Defaults to 10, clamped between 1 and 100.
+The number of iterations defaults to 10 and is clamped between 1 and 100.
 
 ## Cancellation
 
@@ -179,7 +193,7 @@ await execute({
 })
 ```
 
-In worker mode, the model processes without sending messages to the conversation.
+In worker mode, the model executes without sending messages to the conversation.
 
 ## Hooks
 

adk/conversations/setup.mdx

@@ -35,18 +35,45 @@ You can test your conversation using the **Chat** page in the dev console. This
 
 The `channel` field determines which integration channels this conversation handles:
 
-```typescript
-// Match all channels
-channel: "*"
-
-// Match a specific channel
-channel: "webchat.channel"
-
-// Match multiple channels
-channel: ["webchat.channel", "chat.channel"]
-```
-
-When you use `"*"`, the handler runs for any channel but `message` and `event` are typed as `unknown`. Specifying a channel gives you strict types on message payloads, event payloads, and the conversation instance:
+<CodeGroup>
+  ```ts All channels highlight={2} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
+  export default new Conversation({
+    channel: "*",
+    handler: async ({ execute }) => {
+      await execute({
+        instructions: "You are a helpful assistant.",
+      });
+    },
+  });
+  ```
+
+  ```ts Specific channel highlight={2} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
+  export default new Conversation({
+    channel: "webchat.channel",
+    handler: async ({ execute }) => {
+      await execute({
+        instructions: "You are a helpful assistant.",
+      });
+    },
+  });
+  ```
+
+  ```ts Array of channels highlight={2-5} theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
+  export default new Conversation({
+    channel: [
+      "chat.channel",
+      "webchat.channel"
+    ],
+    handler: async ({ execute }) => {
+      await execute({
+        instructions: "You are a helpful assistant.",
+      });
+    },
+  });
+  ```
+</CodeGroup>
+
+When you use `"*"`, the handler runs for any channel, but `message` and `event` are typed as `unknown`. Specifying a channel gives you strict types on message payloads, event payloads, and the conversation instance:
 
 ```typescript
 // channel: "*" — message.payload is unknown
@@ -165,7 +192,7 @@ Events use the format `"integration:eventName"` for integration events, or just
 
 Each conversation can declare its own state schema, separate from the bot and user state in `agent.config.ts`:
 
-```typescript
+```typescript highlight={3-6}
 export default new Conversation({
   channel: "webchat.channel",
   state: z.object({
@@ -182,4 +209,8 @@ export default new Conversation({
 })
 ```
 
-Conversation state is automatically persisted between handler calls. For more on state scopes (conversation vs bot vs user), see [Manage states](/adk/conversations/state).
+Conversation state is automatically persisted between handler calls.
+
+<Tip>
+For more information about state scopes (conversation vs. bot vs. user), check out our guide on [managing states](/adk/conversations/state).
+</Tip>

adk/conversations/tools.mdx

@@ -39,7 +39,7 @@ The `input` and `output` schemas use Zod. Use `.describe()` on each field so the
 
 Pass tools to `execute()` via the `tools` array:
 
-```typescript
+```typescript highlight={10}
 import { Conversation } from "@botpress/runtime"
 import getWeather from "../tools/weather"
 import createTicket from "../tools/ticket"
@@ -61,7 +61,7 @@ The model decides which tools to call based on the conversation. It can call mul
 
 You can define tools directly inside a handler without creating a separate file:
 
-```typescript
+```typescript highlight={6-15, 19}
 import { Autonomous, z, Conversation } from "@botpress/runtime"
 
 export default new Conversation({
@@ -86,7 +86,7 @@ export default new Conversation({
 })
 ```
 
-This is useful for tools that are only relevant to a single conversation.
+This is useful for tools that are only relevant to a single type of conversation.
 
 ## Writing good descriptions
 
@@ -115,7 +115,7 @@ Tools can throw signals to influence the AI loop without returning a normal resu
 
 ### ThinkSignal
 
-Throws context back into the model's reasoning without producing a tool output. Useful when a tool finds no results and you want the model to try a different approach:
+A `ThinkSignal` throws context back into the model's reasoning without producing a tool output. This is useful when a tool finds no results and you want the model to try a different approach:
 
 ```typescript
 import { Autonomous } from "@botpress/runtime"
@@ -136,9 +136,11 @@ handler: async ({ query }) => {
 
 ## Actions as tools
 
-Actions are reusable functions that can be called from anywhere in your agent (conversations, workflows, other actions, or external API clients). Unlike standalone tools, which only exist inside `execute()`, actions are shared primitives. You can convert any action into a tool:
+Actions are reusable functions that can be called from anywhere in your agent—conversations, workflows, other actions, or external API clients. Tools only work inside `execute()`, where the AI model decides when to call them based on the conversation.
 
-```typescript
+You can convert any action into a tool by calling its `asTool()` method and passing it into `tools`:
+
+```typescript highlight={8}
 import { Conversation, actions } from "@botpress/runtime"
 
 export default new Conversation({
@@ -152,13 +154,15 @@ export default new Conversation({
 })
 ```
 
-See [Build Actions](/adk/external/actions) for how to define actions.
+<Tip>
+  Check out our guide on [building actions](/adk/external/actions) for more information.
+</Tip>
 
 ## Workflows as tools
 
 Workflows are long-running background processes that can span multiple steps and run independently of the conversation. Converting a workflow to a tool lets the model kick one off:
 
-```typescript
+```typescript highlight={9}
 import { Conversation } from "@botpress/runtime"
 import orderWorkflow from "../workflows/order"
 
@@ -173,13 +177,15 @@ export default new Conversation({
 })
 ```
 
-See [Create workflows](/adk/workflows/create) for how to define workflows.
+<Tip>
+  Check out our guide on [creating workflows](/adk/workflows/create) for more information.
+</Tip>
 
 ## Calling actions from tools
 
 Tools can call actions for reusable logic:
 
-```typescript
+```typescript highlight={8}
 import { Autonomous, actions, z } from "@botpress/runtime"
 
 export default new Autonomous.Tool({