Update documentation content and add quick-start guide

Author: Shooksie

AGENTS.md

@@ -89,21 +89,19 @@ AO now splits project-local config from scoped runtime state.
 Project-local config in `<project>/.ao/`:
 
 - `config.json`
-- `pm-config.json`
 - `workflows.yaml`
 - `workflows/*.yaml`
 
 Scoped runtime state in `~/.ao/<repo-scope>/`:
 
 - `core-state.json`
 - `resume-config.json`
+- `workflow.db`
+- `config/`
+- `daemon/`
 - `docs/`
-- `requirements/`
-- `tasks/`
-- `index/`
 - `state/`
-- `runs/`
-- `artifacts/`
+- `worktrees/`
 
 Global config in `protocol::Config::global_config_dir()`:
 

docs/.vitepress/config.mts

@@ -5,10 +5,10 @@ export default withMermaid(
   defineConfig({
     title: 'AO',
     description: 'Agent Orchestrator — orchestrate AI agent workflows from the command line',
-    base: '/ao-cli/',
+    base: '/ao/',
 
     head: [
-      ['link', { rel: 'icon', type: 'image/svg+xml', href: '/ao-cli/logo.svg' }],
+      ['link', { rel: 'icon', type: 'image/svg+xml', href: '/ao/logo.svg' }],
     ],
 
     lastUpdated: true,

docs/architecture/crate-map.md

@@ -1,55 +1,55 @@
 # Crate Map
 
-The AO workspace contains 17 crates organized into seven groups by responsibility.
+The AO workspace contains 17 crates organized by responsibility.
 
 ## Foundation
 
 | Crate | Description | Key Responsibility |
 |-------|-------------|-------------------|
-| [protocol](../../crates/protocol/README.md) | Wire protocol types shared across all crates | Defines IPC messages, configuration schemas, scoped state paths, model routing defaults, and CLI JSON envelope contracts |
-| [orchestrator-logging](../../crates/orchestrator-logging/Cargo.toml) | Shared tracing and logging utilities | Initializes tracing, writes structured JSONL logs, and manages log rotation for runtime processes |
+| [protocol](../../crates/protocol/README.md) | Shared wire and config types | IPC messages, config schemas, scoped runtime paths, CLI JSON envelopes |
 
 ## Core
 
 | Crate | Description | Key Responsibility |
 |-------|-------------|-------------------|
-| [orchestrator-core](../../crates/orchestrator-core/README.md) | Domain logic and state management | ServiceHub trait, service API implementations, workflow state machines, task dispatch policy, execution projections |
-| [orchestrator-config](../../crates/orchestrator-config/README.md) | Workflow and runtime configuration | YAML workflow parsing, workflow config compilation, variable expansion, phase plan resolution |
-| [orchestrator-store](../../crates/orchestrator-store/README.md) | Persistence primitives | Atomic JSON writes (`write_json_atomic`), `read_json_or_default`, scoped project state directories |
+| [orchestrator-core](../../crates/orchestrator-core/README.md) | Domain logic and services | `ServiceHub`, service APIs, workflow lifecycle, task and requirement state mutation |
+| [orchestrator-config](../../crates/orchestrator-config/README.md) | Workflow and runtime configuration | Workflow YAML parsing, pack loading, scaffolding, phase plan resolution |
+| [orchestrator-store](../../crates/orchestrator-store/README.md) | Persistence primitives | Atomic JSON writes, repo-scoped state directory helpers |
+| `orchestrator-logging` | Shared logging support | Structured logging helpers and runtime log plumbing |
 
 ## Runtime
 
 | Crate | Description | Key Responsibility |
 |-------|-------------|-------------------|
-| [orchestrator-daemon-runtime](../../crates/orchestrator-daemon-runtime/README.md) | Daemon tick loop and dispatch engine | Project tick execution, dispatch queue management, process manager for workflow-runner-v2 subprocesses, schedule evaluation, completion reconciliation |
-| [workflow-runner-v2](../../crates/workflow-runner-v2/Cargo.toml) | Standalone workflow execution binary | Phase execution loop, runtime contract construction, IPC client to agent-runner, phase failover classification, merge recovery |
-| [agent-runner](../../crates/agent-runner/README.md) | Standalone daemon managing LLM CLI processes | IPC server (Unix socket / TCP), token-based auth, output parsing (tool calls, artifacts, thinking blocks), environment sanitization, provider abstraction |
+| [orchestrator-daemon-runtime](../../crates/orchestrator-daemon-runtime/README.md) | Daemon scheduling runtime | Queue execution, reactive dispatch, subprocess supervision |
+| `workflow-runner-v2` | Workflow execution runtime | Phase execution, state-machine transitions, checkpoint persistence |
+| [agent-runner](../../crates/agent-runner/README.md) | Agent process runner | IPC server, AI CLI execution, output parsing |
 
 ## CLI
 
 | Crate | Description | Key Responsibility |
 |-------|-------------|-------------------|
-| [orchestrator-cli](../../crates/orchestrator-cli/README.md) | Main `ao` binary (clap-based CLI) | CLI dispatch for 22 top-level commands, JSON envelope output, MCP server (via rmcp), error classification |
+| [orchestrator-cli](../../crates/orchestrator-cli/README.md) | Main `ao` binary | Clap command surface, JSON output, MCP server, operational commands |
 
 ## Web
 
 | Crate | Description | Key Responsibility |
 |-------|-------------|-------------------|
-| [orchestrator-web-api](../../crates/orchestrator-web-api/README.md) | Web API business logic | WebApiService bridging HTTP requests to core service APIs |
-| [orchestrator-web-contracts](../../crates/orchestrator-web-contracts/README.md) | Shared web types | Request/response types shared between web-api and web-server |
-| [orchestrator-web-server](../../crates/orchestrator-web-server/README.md) | Axum web server with embedded static assets | HTTP routing, GraphQL (optional feature), static asset serving, compression |
+| [orchestrator-web-api](../../crates/orchestrator-web-api/README.md) | Web API business logic | HTTP-facing orchestration services |
+| [orchestrator-web-contracts](../../crates/orchestrator-web-contracts/README.md) | Shared web contracts | Request and response types shared between web layers |
+| [orchestrator-web-server](../../crates/orchestrator-web-server/README.md) | Axum web server | HTTP routing, embedded UI delivery, browser entrypoint |
 
 ## Integration
 
 | Crate | Description | Key Responsibility |
 |-------|-------------|-------------------|
-| [orchestrator-providers](../../crates/orchestrator-providers/README.md) | External provider integrations | Git provider abstraction, task/requirements/subject providers; optional Jira, Linear, and GitLab features behind feature flags |
-| [orchestrator-notifications](../../crates/orchestrator-notifications/README.md) | Notification delivery | Webhook-based notifications for daemon and workflow events |
-| [orchestrator-git-ops](../../crates/orchestrator-git-ops/README.md) | Git workflow operations | Branch management, merge operations, PR creation, merge conflict handling for workflow post-success actions |
+| [orchestrator-providers](../../crates/orchestrator-providers/README.md) | Provider integrations | Built-in task, requirement, subject, and git adapters |
+| [orchestrator-notifications](../../crates/orchestrator-notifications/README.md) | Notification delivery | Webhook and runtime notification support |
+| [orchestrator-git-ops](../../crates/orchestrator-git-ops/README.md) | Git automation | Branching, worktree, merge, and PR helper operations |
 
-## LLM
+## Model and Runner Adapters
 
 | Crate | Description | Key Responsibility |
 |-------|-------------|-------------------|
-| [llm-cli-wrapper](../../crates/llm-cli-wrapper/README.md) | Abstraction over AI CLI tools | Unified interface for spawning and interacting with claude, codex, gemini, opencode CLI processes |
-| [oai-runner](../../crates/oai-runner/README.md) | OpenAI-compatible streaming API client | Direct API streaming for OpenAI-compatible endpoints, MCP client integration via rmcp |
+| [llm-cli-wrapper](../../crates/llm-cli-wrapper/README.md) | AI CLI abstraction layer | Claude, Codex, Gemini, and related CLI integration |
+| [oai-runner](../../crates/oai-runner/README.md) | OpenAI-compatible runner | Streaming API execution for OpenAI-compatible endpoints |

docs/architecture/index.md

@@ -1,6 +1,6 @@
 # Architecture Overview
 
-AO is a Rust-only agent orchestrator CLI built as a 17-crate Cargo workspace. It provides a CLI, daemon, agent runner, LLM wrappers, MCP server, and web UI for orchestrating AI agent workflows.
+AO is a Rust-only agent orchestrator CLI built as a 17-crate Cargo workspace. It provides a CLI, daemon runtime, workflow runner, agent runner, MCP server, and web UI for orchestrating AI workflows.
 
 ## Crate Dependency Graph
 
@@ -16,13 +16,13 @@ graph TD
     AR[agent-runner]
     LLM[llm-cli-wrapper]
     OAI[oai-runner]
-    LOG[orchestrator-logging]
     WAPI[orchestrator-web-api]
     WCON[orchestrator-web-contracts]
     WSRV[orchestrator-web-server]
     PROV[orchestrator-providers]
     NOTIF[orchestrator-notifications]
     GIT[orchestrator-git-ops]
+    LOG[orchestrator-logging]
 
     CLI --> CORE
     CLI --> DAEMON
@@ -34,24 +34,21 @@ graph TD
     CLI --> NOTIF
     CLI --> LLM
     CLI --> PROTO
-    CLI --> LOG
 
     WSRV --> WAPI
     WSRV --> WCON
-    WSRV --> LOG
     WAPI --> CORE
     WAPI --> DAEMON
     WAPI --> WCON
     WAPI --> PROTO
-    WAPI --> LOG
 
     DAEMON --> CORE
     DAEMON --> WR
     DAEMON --> GIT
     DAEMON --> NOTIF
     DAEMON --> PROV
-    DAEMON --> PROTO
     DAEMON --> LOG
+    DAEMON --> PROTO
 
     GIT --> CORE
     GIT --> WR
@@ -60,35 +57,32 @@ graph TD
     WR --> CORE
     WR --> CONFIG
     WR --> PROTO
-    WR --> LOG
 
     CORE --> STORE
     CORE --> CONFIG
     CORE --> PROV
     CORE --> LLM
+    CORE --> LOG
     CORE --> PROTO
 
     AR --> LLM
     AR --> PROTO
-    AR --> LOG
 
     OAI --> PROTO
-    OAI --> LOG
 
     STORE --> PROTO
     CONFIG --> PROTO
     PROV --> PROTO
     NOTIF --> PROTO
     WCON --> PROTO
+    LOG --> PROTO
 ```
 
-**protocol** sits at the foundation -- every crate depends on it for shared wire types, configuration, and IPC contracts.
-
-**orchestrator-core** occupies the middle layer, providing domain logic, state management, and the ServiceHub dependency injection pattern.
+`protocol` sits at the foundation for shared types, configuration shapes, and runtime path derivation.
 
-**orchestrator-logging** centralizes tracing initialization and structured file logging for runtime binaries.
+`orchestrator-core` provides the domain services and state mutation APIs used by the CLI, web layer, and daemon.
 
-**orchestrator-cli** sits at the top as the main `ao` binary, composing all other crates into the user-facing command surface.
+`orchestrator-cli` composes the workspace into the user-facing `ao` command surface.
 
 ## Architecture Decision Records
 
@@ -101,5 +95,5 @@ graph TD
 ## Deep Dives
 
 - [Crate Map](crate-map.md) -- All 17 crates grouped by responsibility with descriptions
-- [ServiceHub Pattern](service-hub.md) -- Dependency injection via the ServiceHub trait
+- [ServiceHub Pattern](service-hub.md) -- Dependency injection via the `ServiceHub` trait
 - [llm-cli-wrapper Session Backends](llm-cli-wrapper-session-backends.md) -- Planned unified session facade for SDK-backed CLI integrations

docs/architecture/service-hub.md

@@ -1,79 +1,54 @@
 # ServiceHub Pattern
 
-The `ServiceHub` trait is AO's dependency injection mechanism. It provides a uniform interface for accessing all domain service APIs, allowing production code and tests to share the same business logic with different backing implementations.
-
-## The ServiceHub Trait
-
-Defined in `crates/orchestrator-core/src/services.rs`:
-
-```rust
-pub trait ServiceHub: Send + Sync {
-    fn daemon(&self) -> Arc<dyn DaemonServiceApi>;
-    fn projects(&self) -> Arc<dyn ProjectServiceApi>;
-    fn tasks(&self) -> Arc<dyn TaskServiceApi>;
-    fn task_provider(&self) -> Arc<dyn TaskProvider>;
-    fn subject_resolver(&self) -> Arc<dyn SubjectResolver>;
-    fn workflows(&self) -> Arc<dyn WorkflowServiceApi>;
-    fn planning(&self) -> Arc<dyn PlanningServiceApi>;
-    fn requirements_provider(&self) -> Arc<dyn RequirementsProvider>;
-    fn project_adapter(&self) -> Arc<dyn ProjectAdapter>;
-    fn review(&self) -> Arc<dyn ReviewServiceApi>;
-}
-```
-
-Each accessor returns an `Arc<dyn Trait>`, enabling shared ownership and dynamic dispatch across async boundaries.
+The `ServiceHub` trait is AO's dependency injection boundary. It gives the CLI, daemon, tests, and web layers one uniform way to access domain services.
 
-## Service API Traits
+## The Trait
 
-Each domain area is defined as an async trait:
+Defined in `crates/orchestrator-core/src/services.rs`, `ServiceHub` exposes the core service APIs:
 
-| Trait | Responsibility |
-|-------|---------------|
-| `DaemonServiceApi` | Start, stop, pause, resume, health, logs |
-| `ProjectServiceApi` | List, get, create, upsert, archive, remove projects |
-| `TaskServiceApi` | CRUD, status transitions, assignment, checklist, dependencies |
-| `WorkflowServiceApi` | Run, resume, pause, cancel, phase completion, merge conflict handling |
-| `PlanningServiceApi` | Vision drafting, requirements CRUD, execution |
-| `ReviewServiceApi` | Agent handoff requests |
+- `daemon()`
+- `projects()`
+- `tasks()`
+- `task_provider()`
+- `subject_resolver()`
+- `workflows()`
+- `planning()`
+- `requirements_provider()`
+- `project_adapter()`
+- `review()`
 
-Provider traits (`TaskProvider`, `RequirementsProvider`, `SubjectResolver`, `ProjectAdapter`, `GitProvider`) abstract external data sources so integrations (Jira, Linear, GitLab) can be swapped in via feature flags.
+Each accessor returns an `Arc<dyn Trait>` so callers can share service implementations across async boundaries.
 
-## FileServiceHub (Production)
+## Production: `FileServiceHub`
 
-`FileServiceHub` is the production implementation. It persists all state as JSON files under the scoped project directory.
+`FileServiceHub` is the production implementation.
 
-```
-~/.ao/<repo-scope>/
-  state/
-    core-state.json
-    workflow-config.compiled.json
-    agent-runtime-config.v2.json
-    state-machines.v1.json
-    ...
-  workflows/
-    <workflow-id>.json
-    ...
-```
+At startup it:
 
-Construction happens at CLI startup:
+1. resolves the project root
+2. bootstraps `.ao/` project config and the repo-scoped runtime root under `~/.ao/<repo-scope>/`
+3. loads `core-state.json`
+4. loads persisted workflows, tasks, and requirements from `workflow.db`
+5. returns a service hub backed by filesystem and SQLite state
 
-1. Resolve the project root from the current working directory (or `--project-root` flag)
-2. Bootstrap base configs (workflow config, agent runtime config) if missing
-3. Load `core-state.json` into an `Arc<RwLock<CoreState>>` for concurrent access
-4. Load workflow state from individual workflow JSON files
-5. Return the hub, ready for service API calls
+Important runtime files:
 
-File locking (`fs2::FileExt`) protects concurrent access when multiple CLI invocations or daemon ticks operate on the same project state.
+```text
+~/.ao/<repo-scope>/
+├── core-state.json
+├── resume-config.json
+├── workflow.db
+├── config/state-machines.v1.json
+├── state/
+├── daemon/
+└── worktrees/
+```
 
-## InMemoryServiceHub (Tests)
+`FileServiceHub` uses file locking around `core-state.json` mutations so concurrent CLI invocations and daemon work do not trample each other.
 
-`InMemoryServiceHub` holds all state in an `Arc<RwLock<CoreState>>` with no file I/O. This enables fast, isolated unit tests that exercise the same service logic without touching the filesystem.
+## Tests: `InMemoryServiceHub`
 
-```rust
-let hub = InMemoryServiceHub::new();
-let task = hub.tasks().create(TaskCreateInput { ... }).await?;
-assert_eq!(task.status, TaskStatus::Backlog);
-```
+`InMemoryServiceHub` keeps the same service surface but stores everything in memory. That lets tests exercise the same business logic without filesystem I/O.
 
 ## Dependency Flow
 
@@ -84,7 +59,7 @@ graph TD
     FILE["FileServiceHub"]
     MEM["InMemoryServiceHub"]
     APIS["Service API traits"]
-    STATE["CoreState"]
+    STATE["CoreState + workflow.db"]
     STORE["orchestrator-store"]
 
     CLI --> HUB
@@ -95,7 +70,7 @@ graph TD
     FILE --> STATE
     MEM --> STATE
     FILE --> STORE
-    STORE -->|"write_json_atomic"| FS["Filesystem"]
+    STORE --> FS["Filesystem"]
 ```
 
-All callers depend only on `ServiceHub` and the service API traits. The concrete implementation is chosen at the composition root (CLI main, test setup, or web server initialization).
+All higher layers depend on `ServiceHub` and the service traits, not on concrete storage details.

docs/architecture/workflow-first-cli.md

@@ -4,10 +4,10 @@
 
 AO now treats workflow dispatch as the primary execution surface.
 
-- planning commands dispatch canonical workflow refs such as `ao.vision/draft`
-  and `ao.requirement/execute`
+- workflow and requirements surfaces dispatch canonical workflow refs such as
+  `ao.task/standard` and `ao.requirement/execute`
 - task and requirement domain behavior resolves from bundled first-party packs
-  and project/local overrides
+  and project-local overrides
 - legacy `builtin/*` refs remain as compatibility aliases, not as the preferred
   operator-facing surface
 
@@ -42,8 +42,8 @@ This keeps the runtime aligned with the plugin-pack kernel design:
 
 | Command | Canonical Ref |
 |---|---|
-| `ao vision draft` | `ao.vision/draft` |
-| `ao requirements draft` | `ao.requirement/draft` |
+| `ao workflow run ao.vision/draft --title "..." --sync` | `ao.vision/draft` |
+| `ao workflow run ao.requirement/draft --title "..." --sync` | `ao.requirement/draft` |
 | `ao requirements execute --id REQ-001` | `ao.requirement/execute` |
 | `ao workflow run ao.task/standard` | `ao.task/standard` |
 

docs/concepts/how-ao-works.md

@@ -134,7 +134,7 @@ shims, but they are no longer the preferred operator-facing surface.
 
 There is no dedicated `ao vision ...` command in the current CLI. Planning
 workflows still exist as canonical refs, but they are consumed through
-`ao workflow run` or project-local workflow YAML.
+`ao workflow run <workflow_ref>` or project-local workflow YAML.
 
 ## MCP and External Runtimes
 

docs/concepts/index.md

@@ -5,10 +5,10 @@ This section explains the core ideas behind AO. Each page covers one architectur
 ## Pages
 
 - [How AO Works](./how-ao-works.md) -- Core architecture, the three-layer model, and the big picture.
-- [Workflows](./workflows.md) -- Everything is a YAML workflow: builtin, task, and custom workflows.
+- [Workflows](./workflows.md) -- Everything is a workflow: bundled refs, pack-qualified workflows, and project-local YAML.
 - [Subject Dispatch](./subject-dispatch.md) -- The universal work envelope that drives all execution.
 - [The Daemon](./daemon.md) -- The dumb scheduler: tick loop, capacity, and execution facts.
 - [Agents and Phases](./agents-and-phases.md) -- AI personas, phase execution, rework loops, and phase guards.
 - [MCP Integration](./mcp-tools.md) -- How agents use MCP tools to observe and mutate state.
-- [State Management](./state-management.md) -- The `.ao/` directory, atomic writes, and mutation policy.
+- [State Management](./state-management.md) -- The split between project-local `.ao/` config and repo-scoped runtime state.
 - [Worktree Isolation](./worktrees.md) -- Every task gets its own git worktree for safe parallel execution.