docs: expand README index and v3-findings with deep research content
README.md: from 42-line index to rich documentation hub with project overview, reading order, and key directory listing. v3-findings.md: from 63 lines to comprehensive research findings covering adversarial review details, provider coupling analysis, codebase reuse, session anchor design, multi-agent design rationale, theme evolution, and performance measurements.
This commit is contained in:
Hibryda
parent
de8dd04f4b
commit
9a295c224c
2 changed files with 314 additions and 73 deletions
102
docs/README.md
102
docs/README.md
|
|
@ -6,36 +6,88 @@ order: 1
|
|||
description: "Project documentation index"
|
||||
---
|
||||
|
||||
# Documentation
|
||||
# Agent Orchestrator Documentation
|
||||
|
||||
Project documentation lives here.
|
||||
Agent Orchestrator (formerly BTerminal) is a multi-project AI agent orchestration dashboard built with Tauri 2.x, Svelte 5, and the Claude Agent SDK. It transforms a traditional terminal emulator into a mission control for running, monitoring, and coordinating multiple AI agent sessions across multiple codebases simultaneously.
|
||||
|
||||
> This directory is maintained automatically. When features are added or changed, corresponding documentation is updated.
|
||||
The application has three major version milestones:
|
||||
|
||||
## Index
|
||||
- **v1** — A single-file Python GTK3+VTE terminal emulator with Claude Code session management. Production-stable, still shipped as `bterminal`.
|
||||
- **v2** — A ground-up rewrite using Tauri 2.x (Rust backend) + Svelte 5 (frontend). Multi-pane terminal with structured agent sessions, subagent tree visualization, session persistence, multi-machine relay support, 17 themes, and comprehensive packaging.
|
||||
- **v3 (Mission Control)** — A further redesign on top of v2's codebase. Replaces the free-form pane grid with a project-group dashboard. Adds multi-agent orchestration (4 management roles), inter-agent messaging (btmsg), task boards (bttask), session anchors, health monitoring, FTS5 search, plugin system, Landlock sandboxing, secrets management, and 704 automated tests.
|
||||
|
||||
### v2 Documentation
|
||||
| Document | Description |
|
||||
|----------|-------------|
|
||||
| [task_plan.md](task_plan.md) | v2 architecture decisions, error handling, testing strategy |
|
||||
> **Important:** The `docs/` directory is the single source of truth for this project. Before making changes, consult the docs. After making changes, update the docs.
|
||||
|
||||
---
|
||||
|
||||
## Documentation Map
|
||||
|
||||
### Architecture & Design
|
||||
|
||||
| Document | What It Covers |
|
||||
|----------|---------------|
|
||||
| [architecture.md](architecture.md) | End-to-end system architecture: Rust backend, Svelte frontend, sidecar layer, data flow, IPC patterns |
|
||||
| [v3-task_plan.md](v3-task_plan.md) | v3 Mission Control architecture decisions, adversarial review, data model, component tree, layout system, 10-phase plan |
|
||||
| [task_plan.md](task_plan.md) | v2 architecture decisions, technology choices, error handling strategy, testing strategy |
|
||||
| [multi-machine.md](multi-machine.md) | Multi-machine relay architecture: bterminal-core extraction, bterminal-relay binary, RemoteManager, WebSocket protocol, reconnection |
|
||||
|
||||
### Subsystem Guides
|
||||
|
||||
| Document | What It Covers |
|
||||
|----------|---------------|
|
||||
| [sidecar.md](sidecar.md) | Sidecar process lifecycle, multi-provider runners (Claude/Codex/Ollama), env var stripping, CLI detection, NDJSON protocol |
|
||||
| [orchestration.md](orchestration.md) | Multi-agent orchestration: btmsg messaging, bttask kanban, Tier 1/2 agent roles, wake scheduler, system prompts |
|
||||
| [production.md](production.md) | Production hardening: sidecar supervisor, Landlock sandbox, FTS5 search, plugin system, secrets management, notifications, health monitoring, audit logging |
|
||||
| [provider-adapter/](provider-adapter/) | Multi-provider adapter pattern: architecture decisions, coupling analysis, implementation progress |
|
||||
|
||||
### Implementation & Progress
|
||||
|
||||
| Document | What It Covers |
|
||||
|----------|---------------|
|
||||
| [phases.md](phases.md) | v2 implementation phases (1-7 + multi-machine A-D + profiles/skills) with checklists |
|
||||
| [findings.md](findings.md) | Research findings (Agent SDK, Tauri, xterm.js, performance) |
|
||||
| [multi-machine.md](multi-machine.md) | Multi-machine support architecture (implemented, WebSocket relay, reconnection) |
|
||||
| [v3-progress.md](v3-progress.md) | v3 session-by-session progress log (All Phases 1-10 + production hardening) |
|
||||
| [progress.md](progress.md) | v2 session-by-session progress log (recent sessions) |
|
||||
| [progress-archive.md](progress-archive.md) | Archived v2 progress (2026-03-05 to 2026-03-06 early) |
|
||||
|
||||
### v3 Mission Control Documentation
|
||||
| Document | Description |
|
||||
|----------|-------------|
|
||||
| [v3-task_plan.md](v3-task_plan.md) | v3 Mission Control architecture: adversarial review, data model, component tree, layout system, 10-phase plan |
|
||||
| [v3-findings.md](v3-findings.md) | v3 adversarial review results and codebase reuse analysis |
|
||||
| [v3-progress.md](v3-progress.md) | v3 session progress log (All Phases 1-10 complete) |
|
||||
### Research & Analysis
|
||||
|
||||
### Testing
|
||||
| Document | Description |
|
||||
|----------|-------------|
|
||||
| [e2e-testing.md](e2e-testing.md) | E2E testing facility: fixtures, test mode, LLM judge, spec phases, CI |
|
||||
| Document | What It Covers |
|
||||
|----------|---------------|
|
||||
| [findings.md](findings.md) | v2 research: Claude Agent SDK, Tauri+xterm.js, terminal performance, Zellij architecture, ultrawide design patterns |
|
||||
| [v3-findings.md](v3-findings.md) | v3 research: adversarial architecture review, production hardening analysis, provider adapter coupling map, session anchor design |
|
||||
|
||||
### Progress Logs
|
||||
| Document | Description |
|
||||
|----------|-------------|
|
||||
| [progress.md](progress.md) | Session-by-session progress log (recent sessions, v2 + v3) |
|
||||
| [progress-archive.md](progress-archive.md) | Archived progress log (2026-03-05 to 2026-03-06 early) |
|
||||
### Release
|
||||
|
||||
| Document | What It Covers |
|
||||
|----------|---------------|
|
||||
| [v3-release-notes.md](v3-release-notes.md) | v3.0 release notes: feature summary, breaking changes, test coverage, known limitations |
|
||||
| [e2e-testing.md](e2e-testing.md) | E2E testing facility: WebDriverIO fixtures, test mode, LLM judge, CI integration, troubleshooting |
|
||||
|
||||
---
|
||||
|
||||
## Quick Orientation
|
||||
|
||||
If you are new to this codebase, read the documents in this order:
|
||||
|
||||
1. **[architecture.md](architecture.md)** — Understand how the pieces fit together
|
||||
2. **[v3-task_plan.md](v3-task_plan.md)** — Understand the design decisions behind v3
|
||||
3. **[sidecar.md](sidecar.md)** — Understand how agent sessions actually run
|
||||
4. **[orchestration.md](orchestration.md)** — Understand multi-agent coordination
|
||||
5. **[e2e-testing.md](e2e-testing.md)** — Understand how to test changes
|
||||
|
||||
For v2-specific context (the foundation that v3 builds on), read [task_plan.md](task_plan.md) and [findings.md](findings.md).
|
||||
|
||||
---
|
||||
|
||||
## Key Directories
|
||||
|
||||
| Path | Purpose |
|
||||
|------|---------|
|
||||
| `v2/src-tauri/src/` | Rust backend: commands, SQLite, btmsg, bttask, search, secrets, plugins |
|
||||
| `v2/bterminal-core/` | Shared Rust crate: PtyManager, SidecarManager, EventSink trait, Landlock sandbox |
|
||||
| `v2/bterminal-relay/` | Standalone relay binary for remote machine support |
|
||||
| `v2/src/lib/` | Svelte 5 frontend: components, stores, adapters, utils, providers |
|
||||
| `v2/sidecar/` | Agent sidecar runners (Claude, Codex, Ollama) — compiled to ESM bundles |
|
||||
| `v2/tests/e2e/` | WebDriverIO E2E tests, fixtures, LLM judge |
|
||||
| `ctx/` | Context manager CLI tool (SQLite-based, standalone) |
|
||||
| `consult/` | Multi-model tribunal CLI (OpenRouter, standalone Python) |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue