Cleanup things a bit

Signed-off-by: Djordje Lukic <djordje.lukic@docker.com>

Author: rumpl

content/manuals/ai/cagent/_index.md

@@ -20,9 +20,9 @@ problems. Run these agent teams from your terminal using any LLM provider.
 
 ## Why agent teams
 
-One agent handling complex work means constant context-switching. Split the
-work across focused agents instead - each handles what it's best at. cagent
-manages the coordination.
+One agent handling complex work means constant context-switching. Split the work
+across focused agents instead - each handles what it's best at. cagent manages
+the coordination.
 
 Here's a two-agent team that debugs problems:
 
@@ -63,8 +63,11 @@ cagent is included in Docker Desktop 4.49 and later.
 For Docker Engine users or custom installations:
 
 - **Homebrew**: `brew install cagent`
-- **Pre-built binaries**: [GitHub releases](https://github.com/docker/cagent/releases)
-- **From source**: See the [cagent repository](https://github.com/docker/cagent?tab=readme-ov-file#build-from-source)
+- **Winget**: `winget install Docker.Cagent`
+- **Pre-built binaries**: [GitHub
+  releases](https://github.com/docker/cagent/releases)
+- **From source**: See the [cagent
+  repository](https://github.com/docker/cagent?tab=readme-ov-file#build-from-source)
 
 ## Get started
 
@@ -98,7 +101,8 @@ define. Each agent:
 - Uses its own model and parameters
 - Has its own context (agents don't share knowledge)
 - Can access built-in tools like todo lists, memory, and task delegation
-- Can use external tools via [MCP servers](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md)
+- Can use external tools via [MCP
+  servers](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md)
 
 The root agent delegates tasks to agents listed under `sub_agents`. Sub-agents
 can have their own sub-agents for deeper hierarchies.
@@ -124,7 +128,8 @@ agents:
 ```
 
 You can also configure model settings (like context limits), tools (including
-MCP servers), and more. See the [configuration reference](https://github.com/docker/cagent?tab=readme-ov-file#-configuration-reference)
+MCP servers), and more. See the [configuration
+reference](./reference/config.md)
 for complete details.
 
 ## Share agent teams
@@ -137,16 +142,21 @@ $ cagent push ./debugger.yaml myusername/debugger
 $ cagent pull myusername/debugger
 ```
 
-Use Docker Hub or any OCI-compatible registry. Pushing creates the repository
-if it doesn't exist yet.
+Use Docker Hub or any OCI-compatible registry. Pushing creates the repository if
+it doesn't exist yet.
 
 ## What's next
 
 - Follow the [tutorial](./tutorial.md) to build your first coding agent
 - Learn [best practices](./best-practices.md) for building effective agents
 - Integrate cagent with your [editor](./integrations/acp.md) or use agents as
   [tools in MCP clients](./integrations/mcp.md)
-- Browse example agent configurations in the [cagent repository](https://github.com/docker/cagent/tree/main/examples)
-- Use `cagent new` to generate agent teams with AI <!-- TODO: link to some page where we explain this, probably a CLI reference? -->
-- Connect agents to external tools via the [Docker MCP Gateway](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md)
-- Read the full [configuration reference](https://github.com/docker/cagent?tab=readme-ov-file#-configuration-reference) <!-- TODO: move to this site/repo -->
+- Browse example agent configurations in the [cagent
+  repository](https://github.com/docker/cagent/tree/main/examples)
+- Use `cagent new` to generate agent teams with AI <!-- TODO: link to some page
+  where we explain this, probably a CLI reference? -->
+- Connect agents to external tools via the [Docker MCP
+  Gateway](/manuals/ai/mcp-catalog-and-toolkit/mcp-gateway.md)
+- Read the full [configuration
+  reference](https://github.com/docker/cagent?tab=readme-ov-file#-configuration-reference)
+  <!-- TODO: move to this site/repo -->

content/manuals/ai/cagent/best-practices.md

@@ -13,8 +13,8 @@ practice.
 
 Shell commands that produce large output can overflow your agent's context
 window. Validation tools, test suites, and build logs often generate thousands
-of lines. If you capture this output directly, it consumes all available
-context and the agent fails.
+of lines. If you capture this output directly, it consumes all available context
+and the agent fails.
 
 The solution: redirect output to a file, then read the file. The Read tool
 automatically truncates large files to 2000 lines, and your agent can navigate
@@ -31,8 +31,8 @@ reviewer:
     - type: shell
 ```
 
-The validation output goes directly into context. If it's large, the agent
-fails with a context overflow error.
+The validation output goes directly into context. If it's large, the agent fails
+with a context overflow error.
 
 **Do this:**
 
@@ -50,26 +50,14 @@ reviewer:
     - type: shell
 ```
 
-The output goes to a file, not context. The agent reads what it needs using
-the filesystem toolset.
-
-**Important details:**
-
-- Use `>` to redirect, not `tee`. The `tee` command writes to both the file
-  and stdout, defeating the purpose.
-- Redirect both stdout and stderr with `2>&1`
-- Write to the working directory, not `/tmp` (permission issues)
-- Tell your agent that errors usually appear early in logs so it knows to read
-  from the beginning
-
-This pattern works for any command with potentially large output: test runs,
-build logs, linting tools, search results, database dumps.
+The output goes to a file, not context. The agent reads what it needs using the
+filesystem toolset.
 
 ## Structuring agent teams
 
-A single agent handling multiple responsibilities makes instructions complex
-and behavior unpredictable. Breaking work across specialized agents produces
-better results.
+A single agent handling multiple responsibilities makes instructions complex and
+behavior unpredictable. Breaking work across specialized agents produces better
+results.
 
 The coordinator pattern works well: a root agent understands the overall task
 and delegates to specialists. Each specialist focuses on one thing.
@@ -187,7 +175,7 @@ understanding and exact matching.
 ## Preserving document scope
 
 When building agents that update documentation, a common problem: the agent
-transforms minimal guides into comprehensive tutorials. It adds prerequisites,
+transforms minimal guides into tutorials. It adds prerequisites,
 troubleshooting, best practices, examples, and detailed explanations to
 everything.
 
@@ -254,6 +242,7 @@ complex reasoning needed, and Haiku is faster and cheaper.
   options
 - Check [toolsets reference](./reference/toolsets.md) to understand what tools
   agents can use
-- See [example configurations](https://github.com/docker/cagent/tree/main/examples)
-  for complete working agents
+- See [example
+  configurations](https://github.com/docker/cagent/tree/main/examples) for
+  complete working agents
 - Read the [RAG guide](./rag.md) for detailed retrieval optimization

content/manuals/ai/cagent/integrations/acp.md

@@ -1,7 +1,7 @@
 ---
-title: ACP integration
+title: ACP
 description: Configure your editor or IDE to use cagent agents as coding assistants
-keywords: [cagent, acp, editor, ide, vscode, neovim, integration]
+keywords: [cagent, acp, editor, ide, neovim, zed, integration]
 weight: 40
 ---
 
@@ -10,15 +10,15 @@ Your agent gets access to your editor's filesystem context and can read and
 modify files as you work. The editor handles file operations while cagent
 provides the AI capabilities.
 
-This guide shows you how to configure VS Code, Neovim, or Zed to run cagent
-agents. If you're looking to expose cagent agents as tools to MCP clients like
-Claude Desktop or Claude Code, see [MCP integration](./mcp.md) instead.
+This guide shows you how to configure Neovim, or Zed to run cagent agents. If
+you're looking to expose cagent agents as tools to MCP clients like Claude
+Desktop or Claude Code, see [MCP integration](./mcp.md) instead.
 
 ## How it works
 
 When you run cagent with ACP, it becomes part of your editor's environment. You
-select code, highlight a function, or reference a file - the agent sees what
-you see. No copying file paths or switching to a terminal.
+select code, highlight a function, or reference a file - the agent sees what you
+see. No copying file paths or switching to a terminal.
 
 Ask "explain this function" and the agent reads the file you're viewing. Ask it
 to "add error handling" and it edits the code right in your editor. The agent
@@ -27,9 +27,9 @@ has to navigate.
 
 The difference from running cagent in a terminal: file operations go through
 your editor instead of the agent directly accessing your filesystem. When the
-agent needs to read or write a file, it requests it from your editor. This
-keeps the agent's view of your code synchronized with yours - same working
-directory, same files, same state.
+agent needs to read or write a file, it requests it from your editor. This keeps
+the agent's view of your code synchronized with yours - same working directory,
+same files, same state.
 
 ## Prerequisites
 
@@ -39,20 +39,14 @@ Before configuring your editor, you need:
 - **Agent configuration** - A YAML file defining your agent. See the
   [tutorial](../tutorial.md) or [example
   configurations](https://github.com/docker/cagent/tree/main/examples)
-- **Editor with ACP support** - VS Code, Neovim, Zed, or any editor you can
-  configure for stdio-based tools
+- **Editor with ACP support** - Neovim, Intellij, Zed, etc.
 
 Your agents will use model provider API keys from your shell environment
 (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.). Make sure these are set before
 launching your editor.
 
 ## Editor configuration
 
-Your editor needs to know how to start cagent and communicate with it over
-stdio. Most editors support this through extension systems, configuration files,
-or plugin managers. You're telling your editor: "When I want to use an AI
-agent, run this command and talk to it."
-
 ### Zed
 
 Zed has built-in ACP support.
@@ -123,27 +117,11 @@ which has native support for cagent through a built-in adapter:
 4. Switch to the cagent adapter (keymap `ga` in the CodeCompanion buffer, by
    default).
 
-See the [CodeCompanion ACP documentation](https://codecompanion.olimorris.dev/usage/acp-protocol)
-for more information about ACP support in CodeCompanion. Note that terminal
-operations are not supported, so [toolsets](../reference/toolsets.md) like
-`shell` or `script_shell` are not usable through CodeCompanion.
-
-### VS Code
-
-VS Code [doesn't support ACP](https://github.com/microsoft/vscode/issues/265496)
-natively yet.
-
-### Other editors
-
-For other editors with ACP support, you need a way to:
-
-1. Start cagent with `cagent acp your-agent.yml --working-dir /project/path`
-2. Send prompts to its stdin
-3. Read responses from its stdout
-
-This typically requires writing a small plugin or extension for your editor, or
-using your editor's external tool integration if it supports stdio
-communication.
+See the [CodeCompanion ACP
+documentation](https://codecompanion.olimorris.dev/usage/acp-protocol) for more
+information about ACP support in CodeCompanion. Note that terminal operations
+are not supported, so [toolsets](../reference/toolsets.md) like `shell` or
+`script_shell` are not usable through CodeCompanion.
 
 ## Agent references
 
@@ -173,8 +151,8 @@ Use the same syntax in your editor configuration:
 ```
 
 Registry references enable team sharing, version management, and clean
-configuration without local file paths. See [Sharing agents](../sharing-agents.md)
-for details on using OCI registries.
+configuration without local file paths. See [Sharing
+agents](../sharing-agents.md) for details on using OCI registries.
 
 ## Testing your setup
 
@@ -191,61 +169,14 @@ If the agent starts but can't access files or perform other actions, check:
 - Agent configuration file path is absolute or relative to working directory
 - Your editor or plugin properly implements ACP protocol features
 
-## Common workflows
-
-### Explain code at cursor
-
-Select a function or code block, then ask: "Explain what this code does."
-
-The agent reads the file, analyzes the selection, and explains the
-functionality.
-
-### Add functionality
-
-Ask: "Add error handling to this function" while having a function selected.
-
-The agent reads the current code, writes improved code with error handling, and
-explains the changes.
-
-### Search the codebase
-
-For agents configured with RAG (see examples directory), ask: "Where is
-authentication implemented?"
-
-The agent searches your indexed codebase and points to relevant files and
-functions.
-
-### Multi-step refactoring
-
-Ask: "Rename this function and update all callers."
-
-The agent finds all references, makes changes across files, and reports what
-it updated.
-
-## ACP vs MCP integration
-
-Both protocols let you integrate cagent agents with other tools, but they're
-designed for different use cases:
-
-| Feature     | ACP Integration              | MCP Integration                |
-| ----------- | ---------------------------- | ------------------------------ |
-| Use case    | Embedded agents in editors   | Agents as tools in MCP clients |
-| Filesystem  | Delegated to client (editor) | Direct cagent access           |
-| Working dir | Client workspace             | Configurable per agent         |
-| Best for    | Code editing workflows       | Using agents as callable tools |
-
-Use ACP when you want agents embedded in your editor. Use MCP when you want to
-expose agents as tools to MCP clients like Claude Desktop or Claude Code.
-
-For MCP integration setup, see [MCP integration](./mcp.md).
-
 ## What's next
 
-- Review the [configuration reference](../reference/config.md) for advanced agent
-  setup
+- Review the [configuration reference](../reference/config.md) for advanced
+  agent setup
 - Explore the [toolsets reference](../reference/toolsets.md) to learn what tools
   are available
 - Add [RAG for codebase search](../rag.md) to your agent
 - Check the [CLI reference](../reference/cli.md) for all `cagent acp` options
-- Browse [example configurations](https://github.com/docker/cagent/tree/main/examples)
-  for inspiration
+- Browse [example
+  configurations](https://github.com/docker/cagent/tree/main/examples) for
+  inspiration