update docs

new docs structure
Opus generated docs where possible (are they any good?)

Author: franciskafyi

docs/agent-tools.mdx

@@ -0,0 +1,149 @@
+---
+title: "Agent Tools"
+description: "Tools available to agents for interacting with codebases and external resources"
+---
+
+Agents have access to a comprehensive set of tools for interacting with codebases, performing searches, making edits, and accessing external resources. The Agent Client Protocol standardizes how these tools are described and how their usage is communicated between agents and clients.
+
+## Overview
+
+Agent tools are organized into two main categories:
+- **Read & Search Tools**: For exploring and understanding codebases
+- **Edit Tools**: For modifying files and project structure
+
+Each tool is designed with specific use cases in mind and follows consistent patterns for input and output.
+
+## Read & Search Tools
+
+### diagnostics
+
+Gets errors and warnings for either a specific file or the entire project. This tool is particularly useful after making edits to verify that changes haven't introduced new issues.
+
+**Parameters:**
+- `path` (optional) - Specific file to analyze, or omit for project-wide summary
+
+### fetch
+
+Fetches a URL and returns the content as Markdown. This tool enables agents to access documentation, API references, and other web resources.
+
+**Parameters:**
+- `url` - The URL to fetch
+
+### find_path
+
+Quickly finds files by matching glob patterns. Returns matching file paths sorted alphabetically.
+
+**Parameters:**
+- `pattern` - Glob pattern to match (e.g., `**/*.js`, `src/**/*.ts`)
+
+### grep
+
+Searches file contents across the project using regular expressions. This is the preferred tool for finding symbols, functions, or specific code patterns when you don't know the exact file location.
+
+**Parameters:**
+- `regex` - Regular expression pattern to search for
+- `include_pattern` (optional) - Glob pattern to limit search scope
+
+### list_directory
+
+Lists files and directories in a given path, providing an overview of the filesystem structure.
+
+**Parameters:**
+- `path` - Directory path to list
+
+### now
+
+Returns the current date and time in the system's timezone.
+
+### open
+
+Opens a file or URL with the default application associated with it on the user's operating system.
+
+**Parameters:**
+- `path` or `url` - Resource to open
+
+### read_file
+
+Reads the content of a specified file in the project.
+
+**Parameters:**
+- `path` - File path to read
+- `start_line` (optional) - Line to start reading from
+- `end_line` (optional) - Line to stop reading at
+
+### thinking
+
+Allows the agent to work through problems, brainstorm ideas, or plan without executing actions. This tool is useful for complex problem-solving and planning multi-step operations.
+
+**Parameters:**
+- `content` - The problem or idea to think through
+
+### web_search
+
+Searches the web for information, providing results with snippets and links from relevant web pages.
+
+**Parameters:**
+- `query` - Search query
+
+## Edit Tools
+
+### copy_path
+
+Copies a file or directory recursively in the project. This is more efficient than manually reading and writing files when duplicating content.
+
+**Parameters:**
+- `source` - Path to copy from
+- `destination` - Path to copy to
+
+### create_directory
+
+Creates a new directory at the specified path within the project, including all necessary parent directories (similar to `mkdir -p`).
+
+**Parameters:**
+- `path` - Directory path to create
+
+### create_file
+
+Creates a new file at a specified path with given text content. This is the most efficient way to create new files or completely replace existing ones.
+
+**Parameters:**
+- `path` - File path to create
+- `content` - Text content for the file
+
+### delete_path
+
+Deletes a file or directory (including contents recursively) at the specified path.
+
+**Parameters:**
+- `path` - Path to delete
+
+### edit_file
+
+Edits files by replacing specific text with new content. This tool enables precise modifications without rewriting entire files.
+
+**Parameters:**
+- `path` - File to edit
+- `old_text` - Text to replace
+- `new_text` - Replacement text
+
+### move_path
+
+Moves or renames a file or directory in the project. If the source and destination are in the same directory with different names, this performs a rename.
+
+**Parameters:**
+- `source` - Current path
+- `destination` - New path
+
+### terminal
+
+Executes shell commands and returns the combined output. Each invocation creates a new shell process.
+
+**Parameters:**
+- `command` - Shell command to execute
+- `cwd` (optional) - Working directory for the command
+
+**Important Notes:**
+- Don't use for long-running processes (servers, watchers)
+- Each invocation is a fresh shell session
+- Output is automatically displayed to the user
+

docs/architecture.mdx

@@ -0,0 +1,218 @@
+---
+title: "Architecture"
+description: "Overview of the Agent Client Protocol architecture"
+---
+
+The Agent Client Protocol defines a standard interface for communication between AI agents and client applications. The architecture is designed to be flexible, extensible, and platform-agnostic.
+
+![Agent Client Protocol Architecture](/images/architecture-diagram.png)
+
+## Design Philosophy
+
+The protocol architecture follows several key principles:
+
+### 1. **Session-Based Isolation**
+Each interaction operates within a session context, providing:
+- State isolation between different conversations
+- Clean lifecycle management
+- Resource scoping and cleanup
+
+### 2. **Tool-Centric Design**
+The protocol treats all operations as tools, creating a uniform interface for:
+- MCP server integrations (`McpToolId`)
+- Client-provided capabilities (`ClientTools`)
+- Permission-gated operations
+
+### 3. **Streaming-First Communication**
+Built for real-time interaction through:
+- Chunked message delivery (`agentMessageChunk`, `agentThoughtChunk`)
+- Progressive tool execution updates (`toolCallUpdate`)
+- Incremental plan revelations
+
+## Component Architecture
+
+### Component Boundaries
+
+1. **Client Application Layer**
+   - Manages UI/UX concerns
+   - Handles permission dialogs
+   - Provides file system access through controlled tools
+
+2. **ACP Protocol Layer**
+   - Session lifecycle management
+   - Message routing and transformation
+   - Tool orchestration
+   - Permission enforcement
+
+3. **Agent Layer**
+   - LLM integration
+   - Reasoning and planning
+   - Tool selection and execution
+   - Response generation
+
+## Key Architectural Patterns
+
+### 1. Tool Abstraction Pattern
+
+All capabilities are exposed as tools with a consistent interface:
+
+```rust
+pub struct McpToolId {
+    pub mcp_server: String,
+    pub tool_name: String,
+}
+```
+
+This abstraction enables:
+- Uniform permission handling
+- Consistent execution tracking
+- Flexible capability composition
+
+### 2. Content Polymorphism
+
+The protocol uses discriminated unions for content flexibility:
+
+```rust
+pub enum ContentBlock {
+    Text(TextContent),
+    Image(ImageContent),
+    Audio(AudioContent),
+    ResourceLink(ResourceLink),
+    // ... extensible
+}
+```
+
+Benefits:
+- Type-safe content handling
+- Forward compatibility
+- Rich media support
+
+### 3. Update Streaming Pattern
+
+Session updates follow a streaming pattern for responsive interaction:
+
+```rust
+pub enum SessionUpdate {
+    Started,
+    UserMessage(ContentBlock),
+    AgentMessageChunk(ContentBlock),
+    AgentThoughtChunk(ContentBlock),
+    ToolCall(ToolCall),
+    ToolCallUpdate(ToolCallUpdate),
+    Plan(Plan),
+}
+```
+
+This enables:
+- Real-time feedback
+- Progressive rendering
+- Interruptible operations
+
+## Implementation Considerations
+
+### State Management
+
+The protocol maintains minimal shared state:
+- **Session State**: Managed by session ID, includes configuration and context
+- **Tool State**: Tracked through tool call IDs for update correlation
+- **Permission State**: Cached permission decisions (allow/reject always)
+
+### Error Boundaries
+
+Error handling is localized to maintain system stability:
+- Tool failures don't crash sessions
+- MCP server errors are isolated
+- Network failures are recoverable
+
+### Performance Optimization
+
+Key areas for optimization:
+1. **Streaming Buffers**: Chunk size tuning for message streams
+2. **Tool Parallelization**: Concurrent tool execution where safe
+3. **Session Caching**: Reuse of MCP server connections
+4. **Content Deduplication**: Efficient handling of repeated resources
+
+## Integration Patterns
+
+### 1. MCP Server Integration
+
+```rust
+pub struct McpServerConfig {
+    pub command: PathBuf,
+    pub args: Vec<String>,
+    pub env: Option<HashMap<String, String>>,
+    pub enabled_tools: Option<Vec<String>>,
+}
+```
+
+Supports:
+- Dynamic server spawning
+- Tool whitelisting
+- Environment isolation
+
+### 2. Client Tool Mapping
+
+```rust
+pub struct ClientTools {
+    pub request_permission: Option<McpToolId>,
+    pub write_text_file: Option<McpToolId>,
+    pub read_text_file: Option<McpToolId>,
+}
+```
+
+Enables:
+- Flexible tool implementation
+- Platform-specific capabilities
+- Security boundaries
+
+### 3. Permission Flow
+
+The architecture enforces a clear permission flow:
+1. Agent requests operation
+2. Protocol checks permission cache
+3. If needed, client prompts user
+4. Decision cached based on kind (`allowAlways`, etc.)
+5. Operation proceeds or fails
+
+## Extensibility Points
+
+The architecture provides several extension mechanisms:
+
+### 1. Custom Content Types
+New `ContentBlock` variants can be added without breaking existing clients
+
+### 2. Tool Categories
+The `ToolKind` enum can be extended for new operation types
+
+### 3. Session Updates
+New `SessionUpdate` variants enable protocol evolution
+
+### 4. Annotations
+The `Annotations` type allows metadata extension without schema changes
+
+## Security Architecture
+
+### Principle of Least Privilege
+- Tools are explicitly granted through `enabled_tools`
+- File operations require specific client tool mappings
+- Permissions are granular and auditable
+
+### Isolation Boundaries
+- Sessions cannot interact with each other
+- MCP servers run in separate processes
+- File access is mediated through client tools
+
+### Trust Model
+```
+Client (Trusted) ← ACP Protocol → Agent (Sandboxed)
+                        ↓
+                  MCP Servers (Isolated)
+```
+
+## Future Considerations
+
+The architecture is designed to accommodate:
+- **Multiplexed Sessions**: Multiple agents in one session
+- **Bidirectional Tools**: Client-initiated tool calls
+- **Resource Streaming**: Large file handling without full loading
+- **Federated Permissions**: Cross-session permission sharing

docs/auth.mdx

@@ -0,0 +1,5 @@
+---
+title: "Authentication"
+description: "Learn how agents authenticate with the client"
+---
+