### Install Dependencies and Start Development Server

Source: https://github.com/athasdev/athas/blob/master/CONTRIBUTING.md

Installs project dependencies using Bun and starts the development server. Ensure you have Rust, Bun, and Node.js installed.

```bash
bun install
bun dev
```

--------------------------------

### Enter Nix Development Shell and Run Project

Source: https://github.com/athasdev/athas/blob/master/nix/README.md

Commands to enter the Nix development shell, install project dependencies using Bun, and start the development server.

```sh
nix develop
bun install --frozen-lockfile
bun dev
```

--------------------------------

### Example: Get and Use Database Pool

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Demonstrates how to retrieve a connection pool by its ID and use it if found. Ensure the connection ID exists in the manager.

```rust
let pool = manager.get_pool("prod-db").await;
if let Some(db) = pool {
    // Use pool
}
```

--------------------------------

### Start Athas Development Server

Source: https://github.com/athasdev/athas/blob/master/_autodocs/07-quick-start-guide.md

Commands to start the development server for Athas. `bun run dev` starts the frontend and backend with hot reloading, while `bun run dev:stable` uses a stable configuration.

```bash
bun run dev           # Frontend + backend (hot reload)
bun run dev:stable    # With stable config
```

--------------------------------

### Clone and Install Athas Dependencies

Source: https://github.com/athasdev/athas/blob/master/_autodocs/07-quick-start-guide.md

Clone the Athas repository, navigate into the directory, and install project dependencies using Bun. Also includes commands to build Rust crates for the Tauri backend.

```bash
git clone https://github.com/athasdev/athas.git
cd athas
bun install
cargo build  # Build Rust crates
```

--------------------------------

### FileWatcher::new Example

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Example of creating a `FileWatcher` by implementing the `FileChangeEmitter` trait and providing an instance to the constructor.

```rust
struct MyEmitter;
impl FileChangeEmitter for MyEmitter {
    fn emit_file_change(&self, event: &FileChangeEvent) {
        println!("Changed: {} ({:?})", event.path, event.event_type);
    }
}

let watcher = FileWatcher::new(Arc::new(MyEmitter));
```

--------------------------------

### Login Action Example

Source: https://github.com/athasdev/athas/blob/master/_autodocs/04-typescript-stores.md

Demonstrates how to call the login action in the auth store with email and password.

```typescript
await useAuthStore().login("user@example.com", "password");
```

--------------------------------

### Extension System Guide

Source: https://github.com/athasdev/athas/blob/master/_autodocs/README.md

A comprehensive guide for developing and distributing extensions for Athas. It covers the extension architecture, manifest format, contribution types (languages, themes, viewers, commands, keybindings), activation events, entry point API, and distribution process.

```APIDOC
## Extension System Guide

This guide details how to create and distribute extensions for the Athas code editor.

### Contents:
- **Extension Architecture**: How extensions are structured and loaded.
- **Manifest Format**: Definition of `package.json` for extensions.
- **Contribution Types**: Supported extension points including Languages, Themes, Icon Themes, Viewers, Commands, and Keybindings.
- **Activation Events**: Triggers for extension loading.
- **Extension Entry Point**: The main TypeScript API for extensions.
- **Distribution and Publishing**: Steps for packaging and sharing extensions.

### For Each Feature:
- **Manifest Definition Format**: Schema for extension manifest files.
- **Field Reference Tables**: Detailed explanations of manifest fields.
- **Example Configurations**: Illustrative examples of extension configurations.
- **Scope Reference**: For themes, detailing scope-based styling.
```

--------------------------------

### FileWatcher::watch_path Example

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Example of using `watch_path` to monitor a project directory. This function returns an error if the path does not exist or is already being watched.

```rust
watcher.watch_path("/home/user/myproject".to_string()).await?;
```

--------------------------------

### Install ACP Agent

Source: https://github.com/athasdev/athas/blob/master/_autodocs/03-tauri-commands-api.md

Invokes the `install_acp_agent` command to download and install an agent. Includes error handling for installation failures.

```typescript
try {
  const installed = await invoke<AgentConfig>("install_acp_agent", {
    agent_id: "claude-code",
  });
  console.log(`Installed: ${installed.name}`);
} catch (error) {
  console.error("Installation failed:", error);
}
```

--------------------------------

### Start ACP Agent

Source: https://github.com/athasdev/athas/blob/master/_autodocs/03-tauri-commands-api.md

Invokes the `start_acp_agent` command to launch an agent process. This example specifies the agent ID and a workspace path.

```typescript
const status = await invoke<AcpAgentStatus>("start_acp_agent", {
  agent_id: "claude-code",
  workspace_path: "/home/user/myproject",
});
```

--------------------------------

### Get JavaScript Runtime Path

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Retrieves the path to a JavaScript runtime, prioritizing Bun over Node.js. Installs the runtime if not found and `managed_root` is provided.

```rust
pub async fn get_js_runtime(managed_root: Option<&Path>) -> Result<PathBuf, RuntimeError>
```

```rust
let runtime_path = RuntimeManager::get_js_runtime(None).await?;
println!("Using: {:?}", runtime_path);
```

--------------------------------

### Example: Connect to a PostgreSQL Database

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Illustrates the process of configuring and establishing a connection to a PostgreSQL database, storing the pool in a manager, and handling the result. Ensure all configuration fields are correctly set.

```rust
let config = ConnectionConfig {
    id: "pg-prod".to_string(),
    name: "Production DB".to_string(),
    db_type: "postgres".to_string(),
    host: "db.example.com".to_string(),
    port: 5432,
    database: "myapp".to_string(),
    username: "appuser".to_string(),
    connection_string: None,
};

let result = connect_database(config, Some("secret".to_string()), &manager).await?;
println!("{}", result.message);
```

--------------------------------

### FileWatcher::watch_path Method

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Starts watching a single file or directory recursively. Emits an `Opened` event immediately upon starting to watch.

```rust
pub async fn watch_path(&path: String) -> Result<()>
```

--------------------------------

### install_acp_agent

Source: https://github.com/athasdev/athas/blob/master/_autodocs/03-tauri-commands-api.md

Downloads and installs an AI agent from the marketplace. This command handles the process of acquiring and setting up a new agent.

```APIDOC
## install_acp_agent(agent_id)

### Description
Downloads and installs an agent from the marketplace.

### Method
INVOKE

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - ID of agent to install

### Response
#### Success Response
- `AgentConfig`: The configuration of the newly installed agent.

### Throws
- `String`: If the agent is not found or installation fails.
```

--------------------------------

### Set Subscription Action Example

Source: https://github.com/athasdev/athas/blob/master/_autodocs/04-typescript-stores.md

Illustrates updating the user's subscription details in the auth store.

```typescript
useAuthStore().setSubscription({
  tier: "pro",
  expiresAt: Date.now() + 30 * 24 * 60 * 60 * 1000,
});
```

--------------------------------

### Open Buffer Example

Source: https://github.com/athasdev/athas/blob/master/_autodocs/04-typescript-stores.md

Opens a file in a new tab. Specify the file path and optionally the language. Returns the buffer ID.

```typescript
const bufferId = useEditorStore().openBuffer("/path/to/file.ts", "typescript");
```

--------------------------------

### Get Specific Runtime Path

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Fetches the path for a specified runtime type. For Bun/Node, it attempts installation if not found on PATH. For others, it checks system PATH or common directories.

```rust
pub async fn get_runtime(
    managed_root: Option<&Path>,
    runtime_type: RuntimeType,
) -> Result<PathBuf, RuntimeError>
```

```rust
let python = RuntimeManager::get_runtime(None, RuntimeType::Python).await?;
let cargo = RuntimeManager::get_runtime(None, RuntimeType::Rust).await?;
```

--------------------------------

### Get Runtime Status

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Checks the installation and availability status of a specific runtime without returning an error. Returns `NotInstalled` if the runtime is unavailable.

```rust
pub async fn get_status(
    managed_root: Option<&Path>,
    runtime_type: RuntimeType,
) -> RuntimeStatus
```

```rust
let status = RuntimeManager::get_status(None, RuntimeType::Bun).await;
if status == RuntimeStatus::NotInstalled {
    println!("Please install Bun");
}
```

--------------------------------

### get_available_agents

Source: https://github.com/athasdev/athas/blob/master/_autodocs/03-tauri-commands-api.md

Fetches a list of available AI agents, including those that are installed and can be installed. It returns configuration details for each agent.

```APIDOC
## get_available_agents()

### Description
Returns a list of available ACP agents, including installed and installable ones.

### Method
INVOKE

### Parameters
None

### Response
#### Success Response
- `Vec<AgentConfig>`: A vector of AgentConfig objects detailing available agents.

### Response Example
```typescript
interface AgentConfig {
  id: string;
  name: string;
  binary_name: string;
  binary_path?: string;
  args: string[];
  env_vars: Record<string, string>;
  icon?: string;
  description?: string;
  installed: boolean;
  install_runtime?: AgentRuntime;
  install_package?: string;
  install_download_url?: string;
  install_command?: string;
  can_install: boolean;
}

type AgentRuntime = "node" | "python" | "go" | "rust" | "binary";
```
```

--------------------------------

### Logout Action Example

Source: https://github.com/athasdev/athas/blob/master/_autodocs/04-typescript-stores.md

Shows how to invoke the logout action to clear user session data.

```typescript
useAuthStore().logout();
```

--------------------------------

### Manage Global State with Zustand and Immer

Source: https://github.com/athasdev/athas/blob/master/_autodocs/07-quick-start-guide.md

Demonstrates how to set up a global state store using Zustand with the Immer middleware for immutable state updates. Includes defining the state interface, actions, and a basic component usage example.

```typescript
import { create } from "zustand";
import { immer } from "zustand/middleware/immer";

interface MyState {
  count: number;
  text: string;
  increment: () => void;
  setText: (text: string) => void;
}

export const useMyStore = create<MyState>()(
  immer((set) => ({
    count: 0,
    text: "",

    increment: () =>
      set((state) => {
        state.count++;  // Immer makes this safe
      }),

    setText: (text) =>
      set((state) => {
        state.text = text;
      }),
  }))
);

// Usage in component
function MyComponent() {
  const count = useMyStore((state) => state.count);
  const increment = useMyStore((state) => state.increment);

  return (
    <button onClick={increment}>
      Count: {count}
    </button>
  );
}
```

--------------------------------

### InstallStatus Enum Definition

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Represents the possible states of an extension during the installation process, from downloading to completion or failure.

```rust
pub enum InstallStatus {
    Downloading,
    Extracting,
    Verifying,
    Installing,
    Completed,
    Failed { error: String },
}
```

--------------------------------

### InstallProgress Struct Definition

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Provides real-time updates on the installation progress of an extension, including its ID, current status, completion percentage, and a status message.

```rust
pub struct InstallProgress {
    pub extension_id: String,
    pub status: InstallStatus,
    pub progress: f32,  // 0.0 to 1.0
    pub message: String,
}
```

--------------------------------

### Rust Sidecar Extension Entry Point

Source: https://github.com/athasdev/athas/blob/master/_autodocs/06-extension-system.md

Example of a Rust program acting as a sidecar for an Athas extension. It continuously reads from stdin, processes input, and writes to stdout.

```rust
// sidecar/main.rs
use std::io;

fn main() {
  loop {
    let mut input = String::new();
    io::stdin().read_line(&mut input).unwrap();
    
    // Process input from Athas
    let output = process(&input);
    println!("{}", output);
  }
}
```

--------------------------------

### RuntimeManager::get_status

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Checks the installation and availability status of a specific runtime without raising errors. It returns the status directly, defaulting to NotInstalled if unavailable.

```APIDOC
## RuntimeManager::get_status

### Description
Returns installation/availability status without error. Never fails—returns `NotInstalled` if runtime unavailable.

### Method
`async fn get_status(managed_root: Option<&Path>, runtime_type: RuntimeType) -> RuntimeStatus`

### Parameters
#### Path Parameters
- `managed_root` (Option<&Path>) - Optional - Base directory for managed runtimes.
- `runtime_type` (RuntimeType) - Required - Which runtime to check.

### Returns
- `RuntimeStatus` - Status of the runtime.

### Example
```rust
let status = RuntimeManager::get_status(None, RuntimeType::Bun).await;
if status == RuntimeStatus::NotInstalled {
    println!("Please install Bun");
}
```
```

--------------------------------

### Watch Project Root for Changes

Source: https://github.com/athasdev/athas/blob/master/_autodocs/07-quick-start-guide.md

Use this function to start watching a project directory for file system changes. It utilizes the Tauri invoke API to call the `watch_project_root` command and logs the status. Ensure the Tauri event system is set up to listen for subsequent file change events.

```typescript
import { invoke } from "@tauri-apps/api/core";

async function watchProject(projectPath: string) {
  try {
    await invoke("watch_project_root", {
      path: projectPath,
    });

    console.log("Watching:", projectPath);

    // Listen to file change events
    // (Events emitted via Tauri event system)
  } catch (error) {
    console.error("Watch failed:", error);
  }
}
```

--------------------------------

### Async Action with Manual Set

Source: https://github.com/athasdev/athas/blob/master/_autodocs/04-typescript-stores.md

Provides an example of an asynchronous action within a store that fetches data and then manually updates the state using `set`.

```typescript
loadChatsFromDb: async () => {
  try {
    const chats = await loadAllChatsFromDb();
    set((state) => {
      state.chats = chats;
    });
  } catch (error) {
    console.error("Failed to load chats:", error);
  }
}
```

--------------------------------

### RuntimeManager::get_js_runtime

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Retrieves the path to a JavaScript runtime, prioritizing Bun over Node.js. It can optionally use a specified directory for managed installations.

```APIDOC
## RuntimeManager::get_js_runtime

### Description
Gets a JavaScript runtime, preferring Bun over Node.js. It can optionally use a specified directory for managed installations.

### Method
`async fn get_js_runtime(managed_root: Option<&Path>) -> Result<PathBuf, RuntimeError>`

### Parameters
#### Path Parameters
- `managed_root` (Option<&Path>) - Optional - Base directory for managed runtime installation.

### Returns
- `Result<PathBuf>` - Path to the runtime binary.

### Throws
- `RuntimeError::NotFound` - If neither Bun nor Node.js is available.

### Example
```rust
let runtime_path = RuntimeManager::get_js_runtime(None).await?;
println!("Using: {:?}", runtime_path);
```
```

--------------------------------

### TypeScript Extension Activation and Deactivation

Source: https://github.com/athasdev/athas/blob/master/_autodocs/06-extension-system.md

Example of an extension's activation and deactivation logic in TypeScript. Register commands and event listeners within the activate function.

```typescript
// extension/index.ts
import * as Athas from "@athas-dev/api";

export function activate(context: Athas.ExtensionContext) {
  // Register commands
  context.subscriptions.push(
    Athas.commands.registerCommand("extension.openSettings", () => {
      console.log("Settings opened");
    })
  );

  // Register event listeners
  context.subscriptions.push(
    Athas.editor.onDidOpenTextDocument((doc) => {
      if (doc.language === "mylang") {
        console.log("MyLang file opened:", doc.path);
      }
    })
  );
}

export function deactivate() {
  // Cleanup
}
```

--------------------------------

### Marketplace Manifest Format

Source: https://github.com/athasdev/athas/blob/master/_autodocs/06-extension-system.md

This JSON structure defines the metadata for an extension to be published in the marketplace. It includes details for installation, such as runtime, package name, download URLs for different platforms, and checksums.

```json
{
  "id": "my-language",
  "name": "My Language Support",
  "version": "1.0.0",
  "description": "...",
  "install": {
    "runtime": "node",
    "package": "@user/my-language",
    "downloadUrl": "https://github.com/.../releases/download/v1.0.0/my-language-1.0.0.tar.gz",
    "downloadUrls": {
      "darwin-arm64": "https://...",
      "darwin-x64": "https://...",
      "linux-arm64": "https://...",
      "linux-x64": "https://...",
      "win32-arm64": "https://...",
      "win32-x64": "https://..."
    },
    "checksum": "sha256:...",
    "size": 1024
  }
}
```

--------------------------------

### RuntimeManager::get_runtime

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Retrieves the path to a specific programming language runtime by its type. For Bun and Node.js, it attempts installation in a managed directory if not found. For others, it checks the system PATH.

```APIDOC
## RuntimeManager::get_runtime

### Description
Gets a specific runtime by type. For Bun/Node, attempts install in `managed_root` if not found on PATH. For Python/Go/Rust, performs system detection via PATH or common binary directories.

### Method
`async fn get_runtime(managed_root: Option<&Path>, runtime_type: RuntimeType) -> Result<PathBuf, RuntimeError>`

### Parameters
#### Path Parameters
- `managed_root` (Option<&Path>) - Optional - Base directory for managed runtimes.
- `runtime_type` (RuntimeType) - Required - Which runtime to fetch.

### Returns
- `Result<PathBuf>` - Path to the runtime binary.

### Throws
- `RuntimeError::NotFound`
- `RuntimeError::VersionTooOld`

### Example
```rust
let python = RuntimeManager::get_runtime(None, RuntimeType::Python).await?;
let cargo = RuntimeManager::get_runtime(None, RuntimeType::Rust).await?;
```
```

--------------------------------

### FileWatcher::watch_project_root

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Starts watching a directory non-recursively. This is intended for root project watching to manage event volume effectively. It returns a Result indicating success or failure.

```APIDOC
## FileWatcher::watch_project_root

### Description
Watch a directory non-recursively. Used for root project watching to avoid excessive event volume.

### Method
`pub async fn watch_project_root(&self, path: String) -> Result<()>`

### Parameters
#### Path Parameters
- **path** (`String`) - Required - Directory path

### Returns
`Result<()>`
```

--------------------------------

### FileWatcher::watch_path

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Starts watching a specified file or directory recursively. An `Opened` event is emitted immediately upon successful addition. The method returns an error if the path does not exist or is already being watched.

```APIDOC
## FileWatcher::watch_path

### Description
Watch a single file or directory recursively. Emits `Opened` event immediately.

### Method
`pub async fn watch_path(&self, path: String) -> Result<(), anyhow::Error>`

### Parameters
#### Path Parameters
- **path** (`String`) - Required - Absolute file or directory path

### Returns
`Result<()>` — Ok if path starts being watched

### Throws
Returns error if path doesn't exist or already being watched

### Request Example
```rust
watcher.watch_path("/home/user/myproject".to_string()).await?;
```
```

--------------------------------

### Cargo Build Commands for Features

Source: https://github.com/athasdev/athas/blob/master/_autodocs/08-configuration-reference.md

Demonstrates various ways to build the project using Cargo, including all features, no default features, specific features, and release builds.

```bash
# Full build
cargo build --all-features

# Minimal build
cargo build --no-default-features

# Specific features
cargo build --features "tauri-wry,sqlite"

# Release build
cargo build --release

# With optimizations
cargo build -Z build-std=core --release

```

--------------------------------

### useProjectStore

Source: https://github.com/athasdev/athas/blob/master/_autodocs/04-typescript-stores.md

Manages the current workspace or project context, including the root folder and open files.

```APIDOC
## useProjectStore

### Description
Manages the current workspace or project context, including the root folder path, open files, and recent projects.

### Actions

#### `setRootFolder(path: string) -> void`
Sets the root folder path for the current project.

**Example:**
```typescript
useProjectStore().setRootFolder("/home/user/myproject");
```

#### `addOpenFile(path: string) -> void`
Adds a file path to the list of currently open files.

**Example:**
```typescript
useProjectStore().addOpenFile("/home/user/myproject/main.ts");
```

#### `removeOpenFile(path: string) -> void`
Removes a file path from the list of currently open files.

**Example:**
```typescript
useProjectStore().removeOpenFile("/home/user/myproject/main.ts");
```

#### `addRecentProject(path: string) -> void`
Adds a project path to the list of recently opened projects.

**Example:**
```typescript
useProjectStore().addRecentProject("/home/user/myproject");
```
```

--------------------------------

### Connect and Store Database Pool

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Establishes a new database connection using provided configuration and credentials, then registers the resulting pool with the connection manager. Handles potential connection errors.

```rust
pub async fn connect_database(
    config: ConnectionConfig,
    password: Option<String>,
    manager: &ConnectionManager,
) -> Result<ConnectionResult, String>
```

--------------------------------

### ExtensionMetadata Struct Definition

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Defines the metadata associated with an installed extension, including its ID, name, version, installation timestamp, and enabled status.

```rust
pub struct ExtensionMetadata {
    pub id: String,
    pub name: String,
    pub version: String,
    pub installed_at: String,
    pub enabled: bool,
}
```

--------------------------------

### Connect to an ACP Agent as a Client

Source: https://github.com/athasdev/athas/blob/master/vendor/agent-client-protocol/README.md

Demonstrates the basic steps to connect to an existing ACP agent using the client builder. Requires a transport mechanism and handles the initialization request.

```rust
use agent_client_protocol::{Client, Agent, ConnectTo};
use agent_client_protocol::schema::{InitializeRequest, ProtocolVersion};

Client.builder()
    .name("my-client")
    .connect_with(transport, async |cx| {
        // Initialize the connection
        cx.send_request(InitializeRequest::new(ProtocolVersion::V1))
            .block_task()
            .await?;

        Ok(())
    })
    .await?;
```

--------------------------------

### Mark Buffer Dirty Example

Source: https://github.com/athasdev/athas/blob/master/_autodocs/04-typescript-stores.md

Explicitly marks a buffer as having unsaved changes.

```typescript
useEditorStore().markBufferDirty("buffer-main.ts");
```

--------------------------------

### ChatHistoryRepository::new Constructor

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Creates a new ChatHistoryRepository instance, pointing to a specified SQLite database file.

```rust
pub fn new(db_path: PathBuf) -> Self>
```

--------------------------------

### Save Buffer Example

Source: https://github.com/athasdev/athas/blob/master/_autodocs/04-typescript-stores.md

Marks a buffer as saved, removing the unsaved changes indicator.

```typescript
useEditorStore().saveBuffer("buffer-main.ts");
```

--------------------------------

### RuntimeStatus Enum Definition

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Indicates the installation status or availability of a runtime on the system or managed by Athas.

```rust
pub enum RuntimeStatus {
    NotInstalled,           // Runtime not found on system PATH
    SystemAvailable,        // Available on system PATH
    ManagedInstalled,       // Downloaded and managed by Athas
    CustomConfigured,       // Configured via user settings
}
```

--------------------------------

### Connect to a Database

Source: https://github.com/athasdev/athas/blob/master/_autodocs/03-tauri-commands-api.md

Establishes a database connection and stores the connection pool. Requires connection configuration and an optional password.

```typescript
interface ConnectionConfig {
  id: string;
  name: string;
  db_type: "postgres" | "mysql" | "mongodb" | "redis" | "sqlite" | "duckdb";
  host: string;
  port: number;
  database: string;
  username: string;
  connection_string?: string;
}

interface ConnectionResult {
  success: boolean;
  connection_id: string;
  message: string;
}

const result = await invoke<ConnectionResult>("connect_database", {
  config: {
    id: "prod-db",
    name: "Production",
    db_type: "postgres",
    host: "db.example.com",
    port: 5432,
    database: "myapp",
    username: "appuser",
  },
  password: "secret",
});
```

--------------------------------

### Define a Keybinding Contribution

Source: https://github.com/athasdev/athas/blob/master/_autodocs/06-extension-system.md

Register keyboard shortcuts for commands in your extension's manifest. This JSON defines the command to execute and the key chords for different operating systems, along with activation conditions.

```json
{
  "contributes": {
    "keybindings": [
      {
        "command": "extension.openSettings",
        "key": "ctrl+shift+p",
        "mac": "cmd+shift+p",
        "when": "!inputFocus"
      }
    ]
  }
}
```

--------------------------------

### ChatHistoryRepository::initialize Method

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Initializes the chat history database by creating necessary tables and indexes. This operation is idempotent and safe to call multiple times.

```rust
pub fn initialize(&self) -> Result<(), String>
```

--------------------------------

### Close Buffer Example

Source: https://github.com/athasdev/athas/blob/master/_autodocs/04-typescript-stores.md

Closes a specific editor buffer or tab using its buffer ID.

```typescript
useEditorStore().closeBuffer("buffer-main.ts");
```

--------------------------------

### Theme File Format for UI and Editor

Source: https://github.com/athasdev/athas/blob/master/_autodocs/06-extension-system.md

Specifies the appearance of UI elements and code syntax highlighting. Includes general settings like background and foreground colors, as well as specific styles for scopes like comments and strings.

```json
{
  "name": "My Dark Theme",
  "settings": [
    {
      "settings": {
        "background": "#1e1e1e",
        "caret": "#aeafad",
        "foreground": "#d4d4d4",
        "lineHighlight": "#ffffff0d",
        "selection": "#264f78",
        "inactiveSelection": "#264f7833"
      }
    },
    {
      "name": "Comment",
      "scope": "comment",
      "settings": {
        "foreground": "#6a9955"
      }
    },
    {
      "name": "String",
      "scope": "string",
      "settings": {
        "foreground": "#ce9178"
      }
    },
    {
      "name": "Number",
      "scope": "constant.numeric",
      "settings": {
        "foreground": "#b5cea8"
      }
    },
    {
      "name": "Keyword",
      "scope": "keyword",
      "settings": {
        "foreground": "#569cd6"
      }
    }
  ]
}
```

--------------------------------

### uninstall_acp_agent

Source: https://github.com/athasdev/athas/blob/master/_autodocs/03-tauri-commands-api.md

Removes an installed AI agent from the system. This command cleans up all files and configurations associated with the agent.

```APIDOC
## uninstall_acp_agent(agent_id)

### Description
Removes an installed agent.

### Method
INVOKE

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - ID of agent to uninstall

### Response
#### Success Response
- `AgentConfig`: The configuration of the uninstalled agent.
```

--------------------------------

### ConnectionManager::new

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Creates a new, empty connection manager instance.

```APIDOC
## ConnectionManager::new

### Description
Creates an empty connection manager.

### Method
`new()`

### Returns
`Self` - A new instance of ConnectionManager.
```

--------------------------------

### Create Empty Connection Manager

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Instantiates a new, empty connection manager. Use this to begin managing database pools.

```rust
pub fn new() -> Self
```

--------------------------------

### RuntimeError Enum Definition

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Represents various error conditions that can occur during runtime detection, installation, or management operations.

```rust
pub enum RuntimeError {
    NotFound(String),                           // Runtime name not found
    VersionTooOld { found: String, minimum: String },
    VersionCheckFailed(String),
    DownloadFailed(String),
    ExtractionFailed(String),
    IoError(std::io::Error),
    PathError(String),
    Other(String),
}
```

--------------------------------

### Connect to Database

Source: https://github.com/athasdev/athas/blob/master/_autodocs/07-quick-start-guide.md

Establishes a connection to a PostgreSQL database using provided configuration details. Requires a password for authentication. Logs connection success or failure.

```typescript
import { invoke } from "@tauri-apps/api/core";

async function setupDatabase() {
  const config: ConnectionConfig = {
    id: "my-db",
    name: "My Database",
    db_type: "postgres",
    host: "localhost",
    port: 5432,
    database: "myapp",
    username: "postgres",
  };

  try {
    const result = await invoke<ConnectionResult>("connect_database", {
      config,
      password: "secret",
    });

    if (result.success) {
      console.log("Connected:", result.connection_id);
    }
  } catch (error) {
    console.error("Connection failed:", error);
  }
}
```

--------------------------------

### LSP Language Server Definitions

Source: https://github.com/athasdev/athas/blob/master/_autodocs/08-configuration-reference.md

Defines configurations for various language servers, including commands, arguments, and initialization options. Use this to enable and customize language support.

```json
{
  "languages": {
    "typescript": {
      "enabled": true,
      "command": "typescript-language-server",
      "args": ["--stdio"],
      "initializationOptions": {
        "preferences": {
          "quotePreference": "double",
          "importModuleSpecifierPreference": "relative"
        }
      }
    },
    "rust": {
      "enabled": true,
      "command": "rust-analyzer",
      "initialization_options": {
        "checkOnSave": {
          "command": "clippy"
        }
      }
    },
    "python": {
      "enabled": true,
      "command": "pylsp",
      "args": [],
      "initializationOptions": {
        "pylsp": {
          "plugins": {
            "pycodestyle": {"enabled": true},
            "pyflakes": {"enabled": true}
          }
        }
      }
    },
    "go": {
      "enabled": true,
      "command": "gopls",
      "initializationOptions": {
        "usePlaceholders": true
      }
    }
  }
}
```

--------------------------------

### Range Interface

Source: https://github.com/athasdev/athas/blob/master/_autodocs/05-types-and-interfaces.md

Represents a text selection or a code region within an editor. Defined by a start and end Position.

```typescript
interface Range {
  start: Position;
  end: Position;
}
```

--------------------------------

### Set Cursor Position Example

Source: https://github.com/athasdev/athas/blob/master/_autodocs/04-typescript-stores.md

Updates the cursor's line and column position within a specific buffer.

```typescript
useEditorStore().setCursorPosition("buffer-main.ts", 10, 5);
```

--------------------------------

### Update Buffer Content Example

Source: https://github.com/athasdev/athas/blob/master/_autodocs/04-typescript-stores.md

Updates the content of a buffer. If the content has changed, the buffer is marked as dirty (unsaved).

```typescript
useEditorStore().updateBufferContent("buffer-main.ts", newCode);
```

--------------------------------

### Apply Startup Appearance

Source: https://github.com/athasdev/athas/blob/master/index.html

Ensures that the startup appearance settings are applied. This function should be called early in the application's startup process.

```typescript
import { ensureStartupAppearanceApplied } from "/src/features/settings/lib/appearance-bootstrap.ts";

ensureStartupAppearanceApplied();
```

--------------------------------

### Set Active Buffer Example

Source: https://github.com/athasdev/athas/blob/master/_autodocs/04-typescript-stores.md

Switches the active editor tab to a specified buffer using its buffer ID.

```typescript
useEditorStore().setActiveBuffer("buffer-main.ts");
```

--------------------------------

### AgentConfig Struct Definition

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Configuration structure for an available or installed agent, including its binary path, arguments, and environment variables.

```rust
pub struct AgentConfig {
    pub id: String,
    pub name: String,
    pub binary_name: String,
    pub binary_path: Option<PathBuf>,
    pub args: Vec<String>,
    pub env_vars: HashMap<String, String>,
    pub icon: Option<String>,
    pub description: Option<String>,
    pub installed: bool,
    pub install_runtime: Option<AgentRuntime>,
    pub install_package: Option<String>,
    pub install_download_url: Option<String>,
    pub install_command: Option<String>,
    pub can_install: bool,
}
```

--------------------------------

### Get Current Agent ID from AIChatStore

Source: https://github.com/athasdev/athas/blob/master/_autodocs/04-typescript-stores.md

Retrieves the agent ID for the current chat or the default agent for new chats.

```typescript
const agentId = useAIChatStore().getCurrentAgentId();
```

--------------------------------

### connect_database

Source: https://github.com/athasdev/athas/blob/master/_autodocs/03-tauri-commands-api.md

Establishes a database connection using the provided configuration and password, storing the connection pool for future use. It returns a result indicating success or failure along with a connection ID.

```APIDOC
## connect_database(config, password)

### Description
Establishes a database connection and stores the connection pool.

### Parameters
#### Path Parameters
- **config** (ConnectionConfig) - Required - Connection parameters.
- **password** (string | null) - Optional - Password (not persisted).

### Returns
`Result<ConnectionResult, String>`

### Example
```typescript
interface ConnectionConfig {
  id: string;
  name: string;
  db_type: "postgres" | "mysql" | "mongodb" | "redis" | "sqlite" | "duckdb";
  host: string;
  port: number;
  database: string;
  username: string;
  connection_string?: string;
}

interface ConnectionResult {
  success: boolean;
  connection_id: string;
  message: string;
}

const result = await invoke<ConnectionResult>("connect_database", {
  config: {
    id: "prod-db",
    name: "Production",
    db_type: "postgres",
    host: "db.example.com",
    port: 5432,
    database: "myapp",
    username: "appuser",
  },
  password: "secret",
});
```
```

--------------------------------

### Set Scroll Position Example

Source: https://github.com/athasdev/athas/blob/master/_autodocs/04-typescript-stores.md

Remembers the scroll position (vertical and horizontal) for a buffer, useful for restoring view when switching tabs.

```typescript
useEditorStore().setScrollPosition("buffer-main.ts", 1000, 0);
```

--------------------------------

### useSettingsStore

Source: https://github.com/athasdev/athas/blob/master/_autodocs/04-typescript-stores.md

Manages user preferences, theme, keybindings, and editor configuration. Provides actions to modify these settings.

```APIDOC
## useSettingsStore

### Description
Manages user preferences such as theme, keybindings, and editor configuration. Provides actions to modify these settings.

### Actions

#### `setTheme(theme: "light" | "dark" | "auto") -> void`
Sets the application theme.

**Example:**
```typescript
useSettingsStore().setTheme("dark");
```

#### `setEditorFontSize(size: number) -> void`
Sets the font size for the editor.

**Example:**
```typescript
useSettingsStore().setEditorFontSize(14);
```

#### `setEditorTabSize(size: number) -> void`
Sets the tab size for the editor.

**Example:**
```typescript
useSettingsStore().setEditorTabSize(2);
```

#### `setVimKeybindings(enabled: boolean) -> void`
Enables or disables Vim keybindings.

**Example:**
```typescript
useSettingsStore().setVimKeybindings(true);
```

#### `setAutoSave(enabled: boolean, delayMs?: number) -> void`
Configures the auto-save feature, optionally setting a delay.

**Example:**
```typescript
useSettingsStore().setAutoSave(true, 1000);
```
```

--------------------------------

### Get Available Agents

Source: https://github.com/athasdev/athas/blob/master/_autodocs/03-tauri-commands-api.md

Invokes the `get_available_agents` command to retrieve a list of ACP agents. It then iterates through the response to log agent details.

```typescript
const agents = await invoke<AgentConfig[]>("get_available_agents");
agents.forEach(agent => {
  console.log(`${agent.name} (${agent.id}) - Installed: ${agent.installed}`);
});
```

--------------------------------

### Monitor Bundle Size

Source: https://github.com/athasdev/athas/blob/master/_autodocs/07-quick-start-guide.md

Use this command to monitor your project's bundle size after building. It helps in identifying and reducing the size of your distributed JavaScript files.

```bash
bun run build && wc -c dist/index.js
```

--------------------------------

### File System Commands

Source: https://github.com/athasdev/athas/blob/master/_autodocs/03-tauri-commands-api.md

Commands for interacting with the local file system.

```APIDOC
## read_file(path)

### Description
Reads entire file contents.

### Parameters
#### Path Parameters
- **path** (string) - Required - Absolute file path

### Returns
Result<string, String>
```

```APIDOC
## write_file(path, contents)

### Description
Writes or overwrites file.

### Parameters
#### Path Parameters
- **path** (string) - Required - Absolute file path
- **contents** (string) - Required - File contents

### Returns
Result<void, String>
```

```APIDOC
## delete_file(path)

### Description
Deletes a file.

### Parameters
#### Path Parameters
- **path** (string) - Required - File path to delete

### Returns
Result<void, String>
```

--------------------------------

### Define Git Diff Command

Source: https://github.com/athasdev/athas/blob/master/_autodocs/03-tauri-commands-api.md

Defines a command to get the diff for a specific file or all changes in a Git repository. Returns output in unified diff format.

```rust
#[tauri::command]
fn get_git_diff(repo_path: String, file_path: Option<String>) -> Result<String, String> {
    // ... implementation details ...
    Ok("diff --git a/file.txt b/file.txt\nindex 0000000..0000000 100644\n--- a/file.txt\n+++ b/file.txt\n@@ -0,0 +1 @@\n+new file\n".to_string())
}
```

--------------------------------

### VS Code Launch Configuration for Tauri Debugging

Source: https://github.com/athasdev/athas/blob/master/_autodocs/08-configuration-reference.md

Sets up VS Code to attach to a running Tauri application or launch and debug the Rust backend.

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "attach",
      "name": "Attach Tauri",
      "port": 9333,
      "urlFilter": "http://localhost:*"
    },
    {
      "type": "lldb",
      "request": "launch",
      "name": "Debug Rust",
      "cargo": {
        "args": [
          "build",
          "--manifest-path=src-tauri/Cargo.toml",
          "--release"
        ],
        "filter": {
          "name": "athas",
          "kind": "bin"
        }
      },
      "args": []
    }
  ]
}

```

--------------------------------

### Persistence Middleware Configuration

Source: https://github.com/athasdev/athas/blob/master/_autodocs/04-typescript-stores.md

Shows how to configure the `persist` middleware to save store state to localStorage using a specified key.

```typescript
const useMyStore = create<State & Actions>()(
  persist(
    (set, get) => ({ ... }),
    { name: "my-store-key" }
  )
);

```

--------------------------------

### GitHunk Interface

Source: https://github.com/athasdev/athas/blob/master/_autodocs/05-types-and-interfaces.md

Represents a section of changes within a Git diff. It specifies the start line and number of lines in both the old and new versions, along with the changed lines.

```typescript
interface GitHunk {
  oldStart: number;
  oldLines: number;
  newStart: number;
  newLines: number;
  lines: GitDiffLine[];
}
```

--------------------------------

### start_acp_agent

Source: https://github.com/athasdev/athas/blob/master/_autodocs/03-tauri-commands-api.md

Launches a specified ACP agent process and sets up bidirectional communication. It allows for specifying a workspace path and session ID.

```APIDOC
## start_acp_agent(agent_id, workspace_path?, session_id?)

### Description
Launches an ACP agent process and establishes bidirectional communication.

### Method
INVOKE

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - ID of agent to start
- **workspace_path** (string) - Optional - Workspace root for agent context
- **session_id** (string) - Optional - Session ID to load previous state

### Response
#### Success Response
- `AcpAgentStatus`: An object indicating the status of the launched agent.

### Response Example
```typescript
interface AcpAgentStatus {
  session_id: string;
  is_running: boolean;
  capabilities: AcpAgentCapabilities;
  // ... more fields
}
```
```

--------------------------------

### Minimal package.json for Athas Extension

Source: https://github.com/athasdev/athas/blob/master/_autodocs/07-quick-start-guide.md

This is a minimal `package.json` file required for an Athas extension. It defines the extension's ID, name, version, and specifies the Athas engine version it's compatible with. It also includes contributions for a new language, linking to its configuration and file extensions.

```json
{
  "id": "my-language",
  "name": "My Language Support",
  "version": "1.0.0",
  "engines": {
    "athas": ">=0.8.0"
  },
  "contributes": {
    "languages": [
      {
        "id": "mylang",
        "extensions": [".ml"],
        "configuration": "./language-configuration.json"
      }
    ]
  }
}
```

--------------------------------

### Create a Reusable UI Button Component

Source: https://github.com/athasdev/athas/blob/master/_autodocs/07-quick-start-guide.md

Example of creating a reusable UI button component using TypeScript, Tailwind CSS, and class-variance-authority (CVA) for defining variants and sizes.

```typescript
// src/ui/button.tsx
import { cva, type VariantProps } from "class-variance-authority";
import clsx from "clsx";

const buttonVariants = cva(
  "inline-flex items-center justify-center px-4 py-2 rounded-md font-medium transition",
  {
    variants: {
      variant: {
        primary: "bg-blue-500 text-white hover:bg-blue-600",
        secondary: "bg-gray-200 text-gray-900 hover:bg-gray-300",
      },
      size: {
        sm: "text-sm px-3 py-1",
        md: "text-base px-4 py-2",
        lg: "text-lg px-6 py-3",
      },
    },
    defaultVariants: {
      variant: "primary",
      size: "md",
    },
  }
);

interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {}

export function Button({ variant, size, className, ...props }: ButtonProps) {
  return (
    <button className={clsx(buttonVariants({ variant, size }), className)} {...props} />
  );
}
```

--------------------------------

### Define File System Commands

Source: https://github.com/athasdev/athas/blob/master/_autodocs/03-tauri-commands-api.md

Defines commands for reading, writing, and deleting files. These commands require an absolute file path.

```rust
#[tauri::command]
fn read_file(path: String) -> Result<String, String> {
    std::fs::read_to_string(path).map_err(|e| e.to_string())
}

#[tauri::command]
fn write_file(path: String, contents: String) -> Result<(), String> {
    std::fs::write(path, contents).map_err(|e| e.to_string())
}

#[tauri::command]
fn delete_file(path: String) -> Result<(), String> {
    std::fs::remove_file(path).map_err(|e| e.to_string())
}
```

--------------------------------

### Extension Activation Events

Source: https://github.com/athasdev/athas/blob/master/_autodocs/06-extension-system.md

Defines the events that trigger the loading of an extension. Use sparingly for the wildcard event.

```json
{
  "activationEvents": [
    "onLanguage:mylang",
    "onCommand:extension.activate",
    "onView:myViewId",
    "onUri",
    "*"
  ]
}
```

--------------------------------

### Zustand Command Palette Store and Keybinding

Source: https://github.com/athasdev/athas/blob/master/_autodocs/07-quick-start-guide.md

Implement a Zustand store for a command palette, managing its open state and query input. Includes a useEffect hook to set up a global keyboard shortcut (Ctrl+K or Cmd+K) to open the command palette.

```typescript
const useCommandPalette = create((set) => ({
  isOpen: false,
  query: "",
  openCommandPalette: () => set({ isOpen: true, query: "" }),
  closeCommandPalette: () => set({ isOpen: false }),
  setQuery: (query) => set({ query }),
}));

useEffect(() => {
  const handleKeyDown = (e: KeyboardEvent) => {
    if ((e.ctrlKey || e.metaKey) && e.key === "k") {
      e.preventDefault();
      useCommandPalette().openCommandPalette();
    }
  };
  window.addEventListener("keydown", handleKeyDown);
  return () => window.removeEventListener("keydown", handleKeyDown);
}, []);
```

--------------------------------

### Execute Redis Command

Source: https://github.com/athasdev/athas/blob/master/_autodocs/03-tauri-commands-api.md

Invokes the `query_redis` command to execute Redis commands like GET and SET. Requires a configured Redis connection. The return type varies based on the command executed.

```typescript
type RedisResult = string | number | string[] | null;

// GET key
const value = await invoke<RedisResult>("query_redis", {
  connection_id: "redis-cache",
  command: "GET",
  args: ["user:123"],
});

// SET key value
await invoke("query_redis", {
  connection_id: "redis-cache",
  command: "SET",
  args: ["counter", "42"],
});
```

--------------------------------

### Invoke Tauri Commands from React

Source: https://github.com/athasdev/athas/blob/master/_autodocs/07-quick-start-guide.md

Example of how to use the `invoke` function from `@tauri-apps/api/core` to call backend commands within a React component. Includes basic error handling and state management for the command result.

```typescript
import { invoke } from "@tauri-apps/api/core";
import { useEffect, useState } from "react";

function MyComponent() {
  const [data, setData] = useState<DataType | null>(null);
  const [error, setError] = useState<string | null>(null);

  useEffect(() => {
    (async () => {
      try {
        const result = await invoke<DataType>("my_command", {
          param1: "value",
        });
        setData(result);
      } catch (e) {
        setError(String(e));
      }
    })();
  }, []);

  if (error) return <div>Error: {error}</div>;
  if (!data) return <div>Loading...</div>;

  return <div>{/* Render data */}</div>;
}
```

--------------------------------

### Use AI Chat Store in React Component

Source: https://github.com/athasdev/athas/blob/master/_autodocs/04-typescript-stores.md

Example of integrating the `useAIChatStore` hook into a React component to manage and update chat input state. It demonstrates selecting specific state values and update functions.

```typescript
import { useAIChatStore } from "@/features/ai/stores/ai-chat.store";

function ChatInput() {
  const input = useAIChatStore(state => state.input);
  const updateInput = useAIChatStore(state => state.updateInput);
  const currentChatId = useAIChatStore(state => state.currentChatId);

  return (
    <input
      value={input}
      onChange={(e) => updateInput(e.target.value)}
      placeholder="Ask anything..."
    />
  );
}
```

--------------------------------

### ConnectionConfig Struct Definition

Source: https://github.com/athasdev/athas/blob/master/_autodocs/02-rust-crates-reference.md

Defines the configuration parameters for establishing a database connection. Includes fields for connection ID, name, type, host, port, database name, username, and an optional custom connection string.

```rust
pub struct ConnectionConfig {
    pub id: String,                          // Unique connection identifier
    pub name: String,
    pub db_type: String,                     // "postgres", "mysql", "mongodb", "redis"
    pub host: String,
    pub port: u16,
    pub database: String,                    // Database name (not used for Redis)
    pub username: String,
    pub connection_string: Option<String>,   // For custom connection URIs
}
```

--------------------------------

### TypeScript Stores API Reference

Source: https://github.com/athasdev/athas/blob/master/_autodocs/README.md

Documents the Zustand store API for managing global application state. It covers the shape of each store, available actions with their signatures and parameter descriptions, and examples of integration within React components.

```APIDOC
## TypeScript Stores API Reference

This section outlines the Zustand stores used for global application state management.

### Stores Documented:
- **useAIChatStore**: Chat history, agent selection, message streaming
- **useEditorStore**: Open buffers, cursor position, save state
- **useSettingsStore**: User preferences, editor config, theme
- **useProjectStore**: Current workspace and open files
- **useAuthStore**: User authentication and subscription

### For Each Store:
- **State Interface**: The structure of the store's state.
- **Actions**: All available actions with their signatures and parameter descriptions.
- **Component Integration Examples**: How to use the store within React components.
```

--------------------------------

### Define Git Stage File Command

Source: https://github.com/athasdev/athas/blob/master/_autodocs/03-tauri-commands-api.md

Defines a command to stage a file, adding it to the Git index for the next commit. Requires repository and file paths.

```rust
#[tauri::command]
fn stage_file(repo_path: String, file_path: String) -> Result<(), String> {
    // ... implementation details ...
    Ok(())
}
```