diff --git a/CHANGELOG.md b/CHANGELOG.md
index 17eb03aef..832d9fc38 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -252,3 +252,100 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   renders permission requests directly in the conversation stream for single-file
   operations. Users can allow/reject with single-key shortcuts (`a`/`A`/`r`/`R`),
   navigate with arrow keys, confirm with `Enter`, or press `v` to open the full
+  permission overlay.
+
+---
+
+## [3.1.0] — 2026-02-22
+
+### Added
+
+- **Actor YAML schema v3** (`version: "3"`): Actor configuration files now declare
+  `version: "3"` and support three actor types via the `type` field: `llm` (single
+  LLM node), `tool` (pure tool-calling node), and `graph` (multi-node LangGraph
+  workflow). The schema is validated on load with line/column error reporting.
+
+- **GRAPH-type actor compilation**: `compile_actor()` translates a `graph`-type
+  `ActorConfiguration` into a runnable LangGraph `StateGraph`. Node definitions,
+  edge routing, conditional edges, and subgraph references are all resolved during
+  compilation. Compilation errors (`ActorCompilationError`, `MissingNodeError`,
+  `SubgraphCycleError`) surface with actionable messages.
+
+- **`agents actor add --config <actor.yaml>`**: New CLI command that loads an actor
+  YAML file, validates it, compiles it, and registers it in the actor registry
+  (persisted to SQLite). Supports `--force` to overwrite an existing registration.
+
+- **Skill registry and tool lifecycle via CLI**: `agents skill add/remove/list/show`
+  and `agents tool add/remove/list/show` commands manage the skill and tool
+  registries. Skills are resolved to their tool sets at registration time; the
+  flattened tool set is persisted for fast lookup during plan execution.
+
+- **MCP adapter for external tool servers**: `agents skill add --mcp <server-url>`
+  registers a Model Context Protocol server as a skill source. The MCP adapter
+  discovers available tools from the server, wraps them in the CleverAgents tool
+  protocol, and makes them available to actors. `agents skill refresh` re-fetches
+  the tool list from all registered MCP servers.
+
+- **Validation runner with required/informational tiers**: `agents validation
+  attach/detach` binds validation rules to resources. The validation runner
+  classifies each rule as `required` or `informational`; the apply gate blocks
+  unless all `required` validations pass. `ApplyValidationSummary` aggregates
+  results and exposes `all_required_passed` for gate enforcement.
+
+- **Multi-file ChangeSet generation**: The execute phase now produces a structured
+  `ChangeSet` containing one `FileChange` per generated or modified file. The
+  ChangeSet is persisted to SQLite and used by `plan diff` and `plan apply` to
+  display and merge changes accurately across multiple files.
+
+---
+
+## [3.0.0] — 2026-02-15
+
+### Added
+
+- **`agents action create --config <action.yaml>`**: Creates and persists an action
+  record to SQLite from a YAML configuration file. Actions define the goal,
+  definition of done, invariants, and argument schema for a plan family.
+
+- **`agents resource add git-checkout`**: Registers a `git-checkout` resource in
+  the resource registry, pointing to a local git repository. Resources are the
+  target repositories that plans read from and write to.
+
+- **`agents project create` and `agents project link-resource`**: `project create`
+  creates a named project record; `link-resource` associates one or more registered
+  resources with a project so that plans executed against the project have access to
+  those repositories.
+
+- **`agents plan use`**: Creates a plan record from an action and transitions it
+  through the initial state machine states (CREATED to READY). Accepts
+  `--action`, `--project`, and `--automation-profile` flags.
+
+- **`agents plan execute <plan_id>`**: Invokes the actor-based LLM execution path.
+  The strategy actor runs the Strategize phase (producing a decision tree), then
+  the execute actor runs the Execute phase (producing a `ChangeSet` of file
+  modifications written to the git worktree sandbox).
+
+- **`agents plan diff <plan_id>`**: Displays the pending changes stored in the
+  sandbox for a plan. Shows a unified diff of all files in the `ChangeSet` against
+  the current HEAD of the target repository.
+
+- **`agents plan apply <plan_id>`**: Merges sandbox changes into the target
+  repository via `git merge` from the isolated worktree branch, then commits the
+  result. Displays a spec-aligned Apply Summary (plan ID, artifacts,
+  insertions/deletions, project, timestamp) and Sandbox Cleanup panel.
+
+- **Git worktree sandbox**: Plan execution writes LLM-generated file changes into
+  an isolated git worktree branch (`cleveragents/plan-<plan_id>`). On apply, the
+  branch is merged back into the target repository. On rollback, the worktree is
+  discarded. Non-git projects fall back to flat `shutil.copy2` copy.
+
+- **SQLite persistence with Alembic migrations**: All domain records — actions,
+  plans, resources, projects, project links, sessions, actors, skills, tools, and
+  ChangeSets — are persisted to a local SQLite database. Schema migrations are
+  managed by Alembic; the database is auto-migrated on first use.
+
+- **Pydantic v2 domain models (frozen=True)**: All domain model classes
+  (Plan, Action, Resource, Project, ChangeSet, FileChange, etc.) are
+  implemented as immutable Pydantic v2 models with model_config =
+  ConfigDict(frozen=True). Mutation is performed by creating new model instances
+  via model_copy(update={...}).
diff --git a/README.md b/README.md
index 733986eda..7cef59ce0 100644
--- a/README.md
+++ b/README.md
@@ -170,3 +170,100 @@ Set `CLEVERAGENTS_DEFAULT_PROVIDER` to pin the global provider (for example `exp
 - Built-in actors (`<provider>/<model>`) are immutable, custom actors must be named `local/<id>`, and the default actor cannot be removed. Use `--unsafe` when adding/updating configs marked unsafe; runtime only warns when invoking unsafe actors.
 - `CLEVERAGENTS_TESTING_USE_MOCK_AI=true` forces the in-repo mock provider so Behave/Robot suites never hit external APIs.
 - The full capability matrix (streaming, tool calls, JSON mode, etc.) is documented in `docs/reference/providers.md`.
+
+## Local Source-Code Workflow (v3.0.0 — v3.1.0)
+
+CleverAgents v3.0.0 introduced the **minimal local source-code workflow** — a complete
+end-to-end pipeline for using an LLM to make changes to a local git repository, with
+full isolation, review, and apply steps. v3.1.0 extended this with the **Actor Compiler**
+and full LangGraph integration.
+
+### v3.0.0 — Minimal Local Source-Code Workflow
+
+The core plan lifecycle commands let you describe a task, execute it with an LLM, review
+the proposed changes in a sandbox, and merge them into your repository:
+
+```bash
+# 1. Register the target repository as a resource
+agents resource add git-checkout \
+  --name local/my-repo \
+  --path /path/to/my-repo
+
+# 2. Create a project and link the resource
+agents project create --name local/my-project
+agents project link-resource \
+  --project local/my-project \
+  --resource local/my-repo
+
+# 3. Define the task as an action
+agents action create --config action.yaml
+
+# 4. Create a plan from the action
+agents plan use \
+  --action local/my-action \
+  --project local/my-project \
+  --automation-profile trusted
+
+# 5. Execute: LLM runs Strategize + Execute phases, writes to sandbox
+agents plan execute <plan_id>
+
+# 6. Review the proposed changes
+agents plan diff <plan_id>
+
+# 7. Merge changes into the repository
+agents plan apply <plan_id>
+```
+
+**Key v3.0.0 capabilities:**
+
+- **Git worktree sandbox** — changes are written to an isolated branch
+  (`cleveragents/plan-<id>`); `plan apply` merges via `git merge` and cleans up
+- **SQLite persistence** — all records (actions, plans, resources, projects,
+  ChangeSets) are persisted locally; Alembic manages schema migrations
+- **Pydantic v2 domain models** — all domain objects are immutable (`frozen=True`)
+  Pydantic v2 models for type safety and validation
+- **State machine transitions** — plans move through `CREATED → READY → STRATEGIZING
+  → EXECUTING → EXECUTED → APPLYING → APPLIED` with explicit lifecycle guards
+
+### v3.1.0 — Actor Compiler + Full LLM Integration
+
+v3.1.0 introduced the **Actor YAML schema v3** and the actor compiler, enabling
+multi-node LangGraph workflows to be defined declaratively and compiled at registration
+time:
+
+```bash
+# Register an actor from a YAML file
+agents actor add --config actor.yaml
+
+# Register skills (tool collections) and individual tools
+agents skill add --config skills/file-ops.yaml
+agents tool add --config tools/validate.yaml
+
+# Connect an external MCP tool server as a skill source
+agents skill add --mcp http://localhost:3000 --name local/mcp-tools
+agents skill refresh  # re-fetch tool list after server updates
+
+# Attach validation rules to resources (gates plan apply)
+agents validation attach \
+  --resource local/my-repo \
+  --validation local/run-tests \
+  --tier required
+```
+
+**Key v3.1.0 capabilities:**
+
+- **Actor YAML v3 schema** — `version: "3"` files declare `type: llm | tool | graph`;
+  `graph`-type actors compile into LangGraph `StateGraph` structures
+- **GRAPH-type actor compilation** — `compile_actor()` resolves node definitions,
+  edges, conditional routing, and subgraph references at registration time
+- **Skill registry** — skills are collections of tools; the flattened tool set is
+  persisted for fast lookup during plan execution
+- **MCP adapter** — any MCP-compatible tool server can be registered as a skill
+  source; tools are discovered automatically and wrapped in the CleverAgents protocol
+- **Validation runner** — `required` validations gate `plan apply`; `informational`
+  validations report without blocking; `ApplyValidationSummary` aggregates results
+- **Multi-file ChangeSet** — the execute phase produces a structured `ChangeSet`
+  with one `FileChange` per file; `plan diff` and `plan apply` use it for accurate
+  multi-file display and merge
+
+For the full CLI reference for these commands, see [`docs/cli.md`](docs/cli.md).
diff --git a/docs/cli.md b/docs/cli.md
new file mode 100644
index 000000000..7d7dbd7b1
--- /dev/null
+++ b/docs/cli.md
@@ -0,0 +1,574 @@
+# CLI Reference
+
+This page documents all `agents` CLI commands introduced in the
+**v3.0.0** (Minimal Local Source-Code Workflow) and **v3.1.0**
+(Actor Compiler + Full LLM Integration) milestones.
+
+For the full command tree run `agents --help` or `agents <command> --help`.
+
+---
+
+## Workflow Overview
+
+The typical end-to-end workflow introduced in v3.0.0 and extended in v3.1.0:
+
+```bash
+# 1. Register an actor (v3.1.0)
+agents actor add --config actor.yaml
+
+# 2. Register a resource (v3.0.0)
+agents resource add git-checkout --name local/my-repo --path /path/to/repo
+
+# 3. Create a project and link the resource (v3.0.0)
+agents project create --name local/my-project
+agents project link-resource --project local/my-project --resource local/my-repo
+
+# 4. Create an action (v3.0.0)
+agents action create --config action.yaml
+
+# 5. Create a plan from the action (v3.0.0)
+agents plan use --action local/my-action --project local/my-project
+
+# 6. Execute the plan (v3.0.0)
+agents plan execute <plan_id>
+
+# 7. Review the diff (v3.0.0)
+agents plan diff <plan_id>
+
+# 8. Apply the changes (v3.0.0)
+agents plan apply <plan_id>
+```
+
+---
+
+## v3.0.0 Commands
+
+### `agents action create`
+
+Creates and persists an action record to SQLite from a YAML configuration file.
+Actions define the goal, definition of done, invariants, and argument schema for
+a family of plans.
+
+```
+agents action create --config <path> [options]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--config <path>` | Path to the action YAML file *(required)* |
+| `--name <name>` | Override the action name from the YAML |
+| `--force` | Overwrite an existing action with the same name |
+
+**Example `action.yaml`:**
+
+```yaml
+name: local/add-feature
+description: "Add a new feature to the project"
+definition_of_done:
+  - "Feature is implemented and tested"
+  - "All existing tests pass"
+invariants:
+  - "Do not modify files outside src/"
+arguments:
+  feature_name:
+    type: string
+    description: "Name of the feature to add"
+    required: true
+```
+
+**Example:**
+
+```bash
+agents action create --config action.yaml
+# Action 'local/add-feature' created (ID: 01HZ...)
+```
+
+---
+
+### `agents resource add`
+
+Registers a resource in the resource registry. Resources are the target
+repositories or directories that plans read from and write to.
+
+```
+agents resource add <resource-type> [options]
+```
+
+**Supported resource types (v3.0.0):**
+
+| Type | Description |
+|------|-------------|
+| `git-checkout` | A local git repository |
+| `fs-directory` | A plain filesystem directory |
+
+**Options for `git-checkout`:**
+
+| Flag | Description |
+|------|-------------|
+| `--name <name>` | Resource name (namespaced, e.g. `local/my-repo`) *(required)* |
+| `--path <path>` | Absolute path to the git repository root *(required)* |
+| `--branch <branch>` | Branch to check out (default: current HEAD) |
+
+**Example:**
+
+```bash
+agents resource add git-checkout \
+  --name local/my-repo \
+  --path /home/user/projects/my-repo
+# Resource 'local/my-repo' registered (ID: 01HZ...)
+```
+
+---
+
+### `agents project create`
+
+Creates a named project record. Projects group resources together and provide
+the context for plan execution.
+
+```
+agents project create --name <name> [options]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--name <name>` | Project name (namespaced, e.g. `local/my-project`) *(required)* |
+| `--description <text>` | Human-readable description |
+
+**Example:**
+
+```bash
+agents project create --name local/my-project
+# Project 'local/my-project' created (ID: 01HZ...)
+```
+
+---
+
+### `agents project link-resource`
+
+Associates a registered resource with a project. Plans executed against the
+project will have access to all linked resources.
+
+```
+agents project link-resource --project <name> --resource <name> [options]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--project <name>` | Project name or ID *(required)* |
+| `--resource <name>` | Resource name or ID *(required)* |
+| `--role <role>` | Resource role within the project (e.g. `primary`, `reference`) |
+
+**Example:**
+
+```bash
+agents project link-resource \
+  --project local/my-project \
+  --resource local/my-repo
+# Resource 'local/my-repo' linked to project 'local/my-project'
+```
+
+---
+
+### `agents plan use`
+
+Creates a plan record from an action and transitions it through the initial
+state machine states (`CREATED` to `READY`). The plan is persisted to SQLite
+and assigned a ULID.
+
+```
+agents plan use --action <name> --project <name> [options]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--action <name>` | Action name or ID *(required)* |
+| `--project <name>` | Project name or ID *(required)* |
+| `--automation-profile <profile>` | Automation profile (default: `manual`). Built-in: `manual`, `review`, `supervised`, `cautious`, `trusted`, `autonomous`, `ci`, `full-auto` |
+| `--arg <key>=<value>` | Action argument value (repeatable) |
+
+**Example:**
+
+```bash
+agents plan use \
+  --action local/add-feature \
+  --project local/my-project \
+  --automation-profile trusted \
+  --arg feature_name=dark-mode
+# Plan created: 01HZABC123DEF456GHI789JKL0
+# State: READY
+```
+
+---
+
+### `agents plan execute`
+
+Invokes the actor-based LLM execution path for a plan. The strategy actor runs
+the Strategize phase (producing a decision tree), then the execute actor runs
+the Execute phase (producing a `ChangeSet` of file modifications written to the
+git worktree sandbox).
+
+```
+agents plan execute <plan_id> [options]
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<plan_id>` | ULID of the plan to execute *(required)* |
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--actor <name>` | Override the default strategy/execute actor |
+| `--dry-run` | Run the Strategize phase only; do not write files |
+
+**Example:**
+
+```bash
+agents plan execute 01HZABC123DEF456GHI789JKL0
+# Strategize: 3 decisions recorded
+# Execute: ChangeSet produced — 4 files modified
+# State: EXECUTED
+```
+
+---
+
+### `agents plan diff`
+
+Displays the pending changes stored in the sandbox for a plan. Shows a unified
+diff of all files in the `ChangeSet` against the current HEAD of the target
+repository.
+
+```
+agents plan diff <plan_id> [options]
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<plan_id>` | ULID of the plan *(required)* |
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--file <path>` | Show diff for a single file only |
+| `--stat` | Show diffstat summary instead of full diff |
+
+**Example:**
+
+```bash
+agents plan diff 01HZABC123DEF456GHI789JKL0
+# diff --git a/src/feature.py b/src/feature.py
+# --- a/src/feature.py
+# +++ b/src/feature.py
+# @@ -0,0 +1,42 @@
+# +class DarkModeFeature:
+# +    ...
+```
+
+---
+
+### `agents plan apply`
+
+Merges sandbox changes into the target repository via `git merge` from the
+isolated worktree branch, then commits the result. Displays a spec-aligned
+Apply Summary and Sandbox Cleanup panel.
+
+```
+agents plan apply <plan_id> [options]
+```
+
+**Arguments:**
+
+| Argument | Description |
+|----------|-------------|
+| `<plan_id>` | ULID of the plan *(required)* |
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--message <msg>` | Override the git commit message |
+| `--no-cleanup` | Keep the sandbox worktree after apply (for debugging) |
+
+**Example:**
+
+```bash
+agents plan apply 01HZABC123DEF456GHI789JKL0
+# Apply Summary
+#   Plan ID:    01HZABC123DEF456GHI789JKL0
+#   Artifacts:  4 files changed
+#   Insertions: +142
+#   Deletions:  -3
+#   Project:    local/my-project
+#   Timestamp:  2026-02-15 10:30:00
+# Sandbox Cleanup
+#   Worktree removed
+#   Branch deleted
+# OK  Changes applied
+```
+
+---
+
+## v3.1.0 Commands
+
+### `agents actor add`
+
+Loads an actor YAML file, validates it, compiles it (for `graph`-type actors,
+builds the LangGraph `StateGraph`), and registers it in the actor registry
+(persisted to SQLite).
+
+```
+agents actor add --config <path> [options]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--config <path>` | Path to the actor YAML file *(required)* |
+| `--force` | Overwrite an existing actor registration with the same name |
+
+**Actor YAML structure (version 3):**
+
+```yaml
+version: "3"
+name: local/my-actor
+type: graph          # llm | tool | graph
+
+entry_node: strategize
+nodes:
+  - name: strategize
+    type: llm
+    provider: openai
+    model: gpt-4o
+    skills:
+      - local/file-ops
+  - name: validate
+    type: tool
+    tool: local/validate-api-compat
+edges:
+  - from: strategize
+    to: validate
+  - from: validate
+    to: END
+```
+
+**Example:**
+
+```bash
+agents actor add --config actor.yaml
+# Actor 'local/my-actor' registered (type: graph, nodes: 2)
+```
+
+---
+
+### `agents skill add`
+
+Registers a skill in the skill registry. Skills are collections of tools that
+actors can use during plan execution. Skills can be defined locally or sourced
+from an MCP server.
+
+```
+agents skill add [--config <path>] [--mcp <url>] [options]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--config <path>` | Path to a skill YAML file |
+| `--mcp <url>` | Register an MCP server as a skill source |
+| `--name <name>` | Skill name (required when using `--mcp`) |
+| `--force` | Overwrite an existing skill registration |
+
+**Example (local skill):**
+
+```bash
+agents skill add --config skills/file-ops.yaml
+# Skill 'local/file-ops' registered (4 tools)
+```
+
+**Example (MCP server):**
+
+```bash
+agents skill add --mcp http://localhost:3000 --name local/my-mcp-tools
+# MCP skill 'local/my-mcp-tools' registered (12 tools discovered)
+```
+
+---
+
+### `agents skill list`
+
+Lists all registered skills with their tool counts and sources.
+
+```
+agents skill list [options]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--format <fmt>` | Output format: `table` (default), `json`, `yaml` |
+
+---
+
+### `agents skill show`
+
+Shows detailed information about a registered skill, including all tools it
+provides.
+
+```
+agents skill show <name>
+```
+
+---
+
+### `agents skill remove`
+
+Removes a skill from the registry.
+
+```
+agents skill remove <name>
+```
+
+---
+
+### `agents skill refresh`
+
+Re-fetches the tool list from all registered MCP server skills. Use this after
+an MCP server has been updated to add or remove tools.
+
+```
+agents skill refresh [--name <skill-name>]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--name <name>` | Refresh a specific MCP skill only (default: refresh all MCP skills) |
+
+---
+
+### `agents tool add`
+
+Registers an individual tool in the tool registry. Tools can be Python
+callables, shell commands, or MCP tool references.
+
+```
+agents tool add --config <path> [options]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--config <path>` | Path to a tool YAML file *(required)* |
+| `--force` | Overwrite an existing tool registration |
+| `--unsafe` | Allow registration of tools marked as unsafe |
+
+---
+
+### `agents tool list`
+
+Lists all registered tools.
+
+```
+agents tool list [options]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--skill <name>` | Filter by skill |
+| `--format <fmt>` | Output format: `table` (default), `json`, `yaml` |
+
+---
+
+### `agents tool show`
+
+Shows detailed information about a registered tool.
+
+```
+agents tool show <name>
+```
+
+---
+
+### `agents tool remove`
+
+Removes a tool from the registry.
+
+```
+agents tool remove <name>
+```
+
+---
+
+### `agents validation attach`
+
+Attaches a validation rule to a resource. Validation rules are run before
+`plan apply` to gate the merge. Rules are classified as `required` (blocking)
+or `informational` (non-blocking).
+
+```
+agents validation attach --resource <name> --validation <name> [options]
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `--resource <name>` | Resource name or ID *(required)* |
+| `--validation <name>` | Validation rule name or ID *(required)* |
+| `--tier <tier>` | `required` (default) or `informational` |
+
+**Example:**
+
+```bash
+agents validation attach \
+  --resource local/my-repo \
+  --validation local/run-tests \
+  --tier required
+# Validation 'local/run-tests' attached to 'local/my-repo' (tier: required)
+```
+
+---
+
+### `agents validation detach`
+
+Removes a validation rule attachment from a resource.
+
+```
+agents validation detach --resource <name> --validation <name>
+```
+
+---
+
+## Related Documentation
+
+- [Git Worktree Sandbox](modules/git-worktree-sandbox.md) — how the sandbox
+  isolates plan changes and merges them on apply
+- [Actor System API](api/actor.md) — `ActorLoader`, `ActorRegistry`,
+  `compile_actor`, and `CompiledActor`
+- [Skills API](api/skills.md) — skill schema, protocol, registry, and MCP adapter
+- [Tool API](api/tool.md) — tool runtime, lifecycle, and registry
+- [MCP Adapter API](api/mcp.md) — Model Context Protocol adapter and client
+- [ADR-006 Plan Lifecycle](adr/ADR-006-plan-lifecycle.md)
+- [ADR-010 Actor and Agent Architecture](adr/ADR-010-actor-and-agent-architecture.md)
+- [ADR-029 Model Context Protocol Adoption](adr/ADR-029-model-context-protocol.md)
diff --git a/mkdocs.yml b/mkdocs.yml
index 48a98aa71..78eaa59c8 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -12,6 +12,7 @@ nav:
   - Specification: specification.md
   - Architecture: architecture.md
   - API Reference:
+  - CLI Reference: cli.md
     - Overview: api/index.md
     - Core Utilities: api/core.md
     - A2A Protocol: api/a2a.md