# Agents Orchestrator — Documentation

Multi-project AI agent dashboard with terminal, SSH, and multi-provider session management.
Built with Tauri 2.x (Rust) + Svelte 5 + Claude Agent SDK.

> **Source of truth.** Before making changes, consult these docs. After making changes, update them.

## Quick Navigation

| Audience | Start Here |
|----------|-----------|
| New users | [Getting Started](getting-started/quickstart.md) |
| Contributors | [Dual-Repo Workflow](contributing/dual-repo-workflow.md), [Testing](contributing/testing.md) |
| Pro customers | [Pro Edition](pro/README.md), [Marketplace](pro/marketplace/README.md) |
| Plugin developers | [Plugin Development Guide](plugins/guide-developing.md) |

## Documentation Map

### Getting Started

- [Quickstart](getting-started/quickstart.md) — install, build, first agent session

### Architecture

- [System Overview](architecture/overview.md) — components, data flow, IPC patterns
- [Data Model](architecture/data-model.md) — SQLite schemas, layout, keyboard shortcuts
- [Decisions](architecture/decisions.md) — architecture decision log with rationale
- [Phases](architecture/phases.md) — v2 implementation phases (P1-7 + multi-machine A-D)
- [Research Findings](architecture/findings.md) — SDK, performance, coupling analysis

### Agents & Orchestration

- [Orchestration](agents/orchestration.md) — btmsg, bttask, 4 management roles, wake scheduler, session anchors
- [btmsg Reference](agents/ref-btmsg.md) — inter-agent messaging CLI and database schema
- [bttask Reference](agents/ref-bttask.md) — kanban task board CLI and operations

### Providers

- [Provider Reference](providers/ref-providers.md) — Claude, Codex, Ollama, Aider: models, capabilities, routing

### Sidecar

- [Sidecar Architecture](sidecar/architecture.md) — runners, NDJSON protocol, crash recovery, env stripping

### Multi-Machine

- [Relay Architecture](multi-machine/relay.md) — WebSocket server, TLS, SPKI pinning, reconnection

### Production Hardening

- [Hardening](production/hardening.md) — sidecar supervisor, Landlock sandbox, WAL checkpoint, TLS relay
- [Features](production/features.md) — FTS5 search, plugin sandbox, secrets, notifications, audit, error classification

### Configuration

- [Settings Reference](config/ref-settings.md) — env vars, config files, databases, themes, per-project settings

### Plugins

- [Plugin Development Guide](plugins/guide-developing.md) — Web Worker sandbox API, manifest, publishing, examples

### Contributing

- [Dual-Repo Workflow](contributing/dual-repo-workflow.md) — community vs commercial repos, sync, leak prevention
- [Testing](contributing/testing.md) — E2E fixtures, test mode, LLM judge, CI integration

### Pro Edition (Commercial)

- [Pro Overview](pro/README.md) — feature list, plugin architecture, IPC pattern
- [Analytics Dashboard](pro/features/analytics.md) — cost/token/model tracking over time
- [Cost Intelligence](pro/features/cost-intelligence.md) — budget governor, smart model router
- [Knowledge Base](pro/features/knowledge-base.md) — persistent memory, codebase symbol graph
- [Git Integration](pro/features/git-integration.md) — context injection, branch policy
- [Marketplace](pro/marketplace/README.md) — 13 plugins (8 free + 5 paid), catalog, install/update

### Release History

- [Release Notes](release-notes.md) — v3.0 features, breaking changes, requirements

### Progress Logs

- [v3 Progress](progress/v3.md) — session-by-session development log
- [v2 Progress](progress/v2.md)
- [v2 Archive](progress/v2-archive.md)

---

## Key Directories

| Path | Purpose |
|------|---------|
| `src-tauri/src/` | Rust backend: commands, SQLite, btmsg, bttask, search, secrets, plugins |
| `agor-core/` | Shared Rust crate: PtyManager, SidecarManager, EventSink, Landlock sandbox |
| `agor-relay/` | Standalone relay binary for remote machine support |
| `agor-pro/` | Commercial plugin crate (Pro edition features) |
| `src/lib/` | Svelte 5 frontend: components, stores, adapters, utils, providers |
| `src/lib/commercial/` | Pro edition Svelte components and IPC bridge |
| `sidecar/` | Agent sidecar runners (Claude, Codex, Ollama, Aider) — ESM bundles |
| `tests/e2e/` | WebDriverIO E2E tests, fixtures, LLM judge |
| `tests/commercial/` | Pro edition tests (excluded from community builds) |
| `scripts/` | Build scripts, plugin scaffolding, test runner |
| `.githooks/` | Pre-push leak prevention hook |

## Reading Order for New Contributors

1. [Getting Started](getting-started/quickstart.md) — build and run
2. [System Overview](architecture/overview.md) — how the pieces fit
3. [Decisions](architecture/decisions.md) — why things are built this way
4. [Sidecar Architecture](sidecar/architecture.md) — how agent sessions run
5. [Orchestration](agents/orchestration.md) — multi-agent coordination
6. [Testing](contributing/testing.md) — how to test changes
7. [Dual-Repo Workflow](contributing/dual-repo-workflow.md) — how to contribute