docs: restructure documentation into multilevel directory layout
New structure: docs/ split into 11 subdirectories (getting-started/, agents/, providers/, sidecar/, multi-machine/, plugins/, config/, production/, architecture/, contributing/, pro/). New files: - docs/README.md: navigation index with audience table - docs/getting-started/quickstart.md: install, build, first session - docs/config/ref-settings.md: all env vars, config files, databases - docs/architecture/overview.md: split from architecture.md (>300 lines) - docs/pro/README.md: Pro edition overview - docs/pro/features/analytics.md: analytics dashboard docs - docs/pro/features/cost-intelligence.md: budget + router docs Remaining docs being written by background agents — will be committed in follow-up when complete.
This commit is contained in:
Hibryda
parent
738574b9f0
commit
8251321dac
7 changed files with 1268 additions and 59 deletions
188
docs/getting-started/quickstart.md
Normal file
188
docs/getting-started/quickstart.md
Normal file
|
|
@ -0,0 +1,188 @@
|
|||
# Quickstart
|
||||
|
||||
Get Agents Orchestrator (agor) running locally in under 10 minutes.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Dependency | Version | Notes |
|
||||
|------------|---------|-------|
|
||||
| Node.js | 20+ | npm included |
|
||||
| Rust | 1.77+ | Install via [rustup](https://rustup.rs/) |
|
||||
| WebKit2GTK | 4.1 | Tauri 2.x rendering engine |
|
||||
| System libs | -- | See below |
|
||||
|
||||
### System libraries (Debian/Ubuntu)
|
||||
|
||||
```bash
|
||||
sudo apt install \
|
||||
libwebkit2gtk-4.1-dev \
|
||||
libgtk-3-dev \
|
||||
libappindicator3-dev \
|
||||
librsvg2-dev \
|
||||
libssl-dev \
|
||||
libsoup-3.0-dev \
|
||||
javascriptcoregtk-4.1 \
|
||||
patchelf
|
||||
```
|
||||
|
||||
### Optional dependencies
|
||||
|
||||
- **Claude Code CLI** -- Required for the Claude provider. Auto-detected at
|
||||
`~/.local/bin/claude`, `~/.claude/local/claude`, `/usr/local/bin/claude`, or
|
||||
`/usr/bin/claude`.
|
||||
- **Deno** -- Preferred sidecar runtime (faster startup). Falls back to Node.js.
|
||||
- **Ollama** -- Required for the Ollama provider. Must be running on
|
||||
`localhost:11434`.
|
||||
|
||||
## Clone and build
|
||||
|
||||
```bash
|
||||
git clone git@github.com:DexterFromLab/agent-orchestrator.git
|
||||
cd agent-orchestrator
|
||||
|
||||
npm install
|
||||
npm run tauri dev
|
||||
```
|
||||
|
||||
The dev server runs on port **9700**. Tauri opens a native window automatically.
|
||||
|
||||
### Production build
|
||||
|
||||
```bash
|
||||
npm run tauri build
|
||||
```
|
||||
|
||||
Output: `.deb` and AppImage in `src-tauri/target/release/bundle/`.
|
||||
|
||||
## Project configuration
|
||||
|
||||
Agor organizes work into **groups**, each containing one or more **projects**
|
||||
(codebases) and optional **agents** (Tier 1 management roles).
|
||||
|
||||
Configuration lives in `~/.config/agor/groups.json`. On first launch, agor
|
||||
creates a default file. You can also create it manually:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"groups": [
|
||||
{
|
||||
"id": "my-team",
|
||||
"name": "My Team",
|
||||
"projects": [
|
||||
{
|
||||
"id": "backend",
|
||||
"name": "Backend API",
|
||||
"identifier": "backend-api",
|
||||
"description": "REST API service",
|
||||
"icon": "B",
|
||||
"cwd": "/home/user/code/backend",
|
||||
"profile": "default",
|
||||
"enabled": true,
|
||||
"provider": "claude"
|
||||
},
|
||||
{
|
||||
"id": "frontend",
|
||||
"name": "Frontend App",
|
||||
"identifier": "frontend-app",
|
||||
"description": "Svelte web client",
|
||||
"icon": "F",
|
||||
"cwd": "/home/user/code/frontend",
|
||||
"profile": "default",
|
||||
"enabled": true,
|
||||
"provider": "claude",
|
||||
"model": "claude-sonnet-4-6"
|
||||
}
|
||||
],
|
||||
"agents": [
|
||||
{
|
||||
"id": "mgr-1",
|
||||
"name": "Manager",
|
||||
"role": "manager",
|
||||
"enabled": true,
|
||||
"wakeIntervalMin": 3,
|
||||
"wakeStrategy": "smart",
|
||||
"wakeThreshold": 0.5
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"activeGroupId": "my-team"
|
||||
}
|
||||
```
|
||||
|
||||
### Key fields
|
||||
|
||||
| Field | Required | Description |
|
||||
|-------|----------|-------------|
|
||||
| `id` | Yes | Unique identifier within the group |
|
||||
| `cwd` | Yes | Absolute path to the project directory |
|
||||
| `provider` | No | `claude` (default), `codex`, `ollama`, or `aider` |
|
||||
| `model` | No | Model override; falls back to provider default |
|
||||
| `profile` | No | Claude profile name from `~/.config/switcher/profiles/` |
|
||||
| `useWorktrees` | No | Enable git worktree isolation per session |
|
||||
| `sandboxEnabled` | No | Enable Landlock filesystem sandbox (Linux 5.13+) |
|
||||
| `autonomousMode` | No | `restricted` (default) or `autonomous` |
|
||||
| `anchorBudgetScale` | No | Anchor token budget: `small`, `medium`, `large`, `full` |
|
||||
| `stallThresholdMin` | No | Minutes before idle agent is marked stalled (default 15) |
|
||||
|
||||
## Creating your first agent session
|
||||
|
||||
1. Launch agor (`npm run tauri dev` or the built binary).
|
||||
2. The workspace shows your configured projects as cards in a grid.
|
||||
3. Click a project card to focus it. The **Model** tab opens by default.
|
||||
4. Type a prompt in the input area at the bottom and press Enter.
|
||||
5. Agor spawns a sidecar process, connects to the provider, and streams
|
||||
responses in real time.
|
||||
|
||||
The agent session persists across tab switches. Closing the project card stops
|
||||
the agent.
|
||||
|
||||
## Keyboard shortcuts
|
||||
|
||||
| Shortcut | Action |
|
||||
|----------|--------|
|
||||
| `Ctrl+B` | Toggle sidebar |
|
||||
| `Ctrl+,` | Open settings |
|
||||
| `Ctrl+Shift+F` | Full-text search overlay |
|
||||
| `Ctrl+K` | Command palette |
|
||||
| `Alt+1` -- `Alt+5` | Focus project 1--5 |
|
||||
| `Escape` | Close sidebar / overlay / palette |
|
||||
|
||||
## Running tests
|
||||
|
||||
```bash
|
||||
# All tests (vitest frontend + cargo backend)
|
||||
npm run test:all
|
||||
|
||||
# Frontend only
|
||||
npm run test
|
||||
|
||||
# Backend only
|
||||
npm run test:cargo
|
||||
|
||||
# E2E tests (requires built binary)
|
||||
npm run test:all:e2e
|
||||
```
|
||||
|
||||
## Directory layout
|
||||
|
||||
```
|
||||
agent-orchestrator/
|
||||
agor-core/ # Shared Rust crate (PTY, sidecar, supervisor, sandbox)
|
||||
agor-relay/ # Standalone relay binary (WebSocket server)
|
||||
src-tauri/ # Tauri app (Rust backend)
|
||||
src/ # Svelte 5 frontend
|
||||
sidecar/ # Provider runner scripts (compiled to .mjs)
|
||||
docs/ # Project documentation
|
||||
tests/e2e/ # WebDriverIO E2E tests
|
||||
```
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Configuration reference](../config/ref-settings.md) -- all env vars, config
|
||||
files, and per-project settings.
|
||||
- [Provider reference](../providers/ref-providers.md) -- Claude, Codex, Ollama,
|
||||
Aider setup.
|
||||
- [btmsg reference](../agents/ref-btmsg.md) -- inter-agent messaging.
|
||||
- [bttask reference](../agents/ref-bttask.md) -- kanban task board.
|
||||
Loading…
Add table
Add a link
Reference in a new issue