diff --git a/CHANGELOG.md b/CHANGELOG.md
index 46bd4bb64..5e56f4cda 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,33 +7,6 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Fixed
 
-- **Atomic `load_from_metadata` for Autonomy Guardrails** (#7504): Fixed
-  `AutonomyGuardrailService.load_from_metadata()` to validate both
-  `AutonomyGuardrails` and `GuardrailAuditTrail` models before writing either
-  to state, ensuring atomic updates. Previously, a validation failure on the
-  audit trail after guardrails were already written would leave the system in
-  an inconsistent state with partial updates. The method now uses a two-phase
-  validate-then-write approach: all model validation occurs in Phase 1, and
-  state mutations only happen in Phase 2 after all validations succeed.
-
-- **ActorRegistry.add() spec-compliant YAML support** (#4466): The registry now
-  accepts actor YAML using the spec's `actors:` map format with nested `config:`
-  blocks, in addition to the legacy top-level `provider`/`model` format. The
-  `unsafe` flag and graph descriptor from nested config are now correctly
-  preserved during registration. Multi-actor YAML (>1 entry in `actors:`/`agents:`
-  map) is now rejected by `add()` with a `ValidationError`. Nested
-  `config.options` are now correctly preserved. The `unsafe` coercion now uses
-  strict `is True or == 1` instead of `bool()` to prevent truthy non-boolean
-  YAML values (e.g. `unsafe: "no"`) from being treated as unsafe.
-
-- **UKO Runtime Layer 2 (Paradigm) Indexing** (#9351): Added missing `rdf:type
-  uko-oo:Class` triple emission in `PythonAnalyzer._extract_class()` so that
-  Python class definitions are now correctly classified at layer 2 (paradigm/OO)
-  in addition to layer 3 (technology). Added the corresponding Behave scenario
-  `Indexing a Python file populates layer 2 (paradigm)` to
-  `features/uko_runtime.feature`, completing four-layer guarantee verification
-  for the UKO runtime.
-
 - **TDD Non-AssertionError Guard Visibility** (#8294): `apply_tdd_inversion` in
   `features/environment.py` now emits its non-assertion exception guard warning to
   both the structured logger and `stderr` via a new `_warning_with_stderr` helper.
@@ -53,16 +26,6 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   crash (unhandled exception) is detected via an all-zero summary and the
   captured traceback is always surfaced.
 
-- **Bug Hunt Pool Supervisor Non-Blocking Tracking**: Updated `bug-hunt-pool-supervisor` to make the automation tracking step non-blocking. The `automation-tracking-manager` call in step 5 is now best-effort — if it does not complete within a reasonable time or fails, the supervisor skips it and continues to the next cycle. Added explicit rule 9 clarifying that tracking must never block the main loop. Core functionality (module scanning and worker dispatch) takes priority over status reporting.
-
-- **Name Validator Server-Qualified Format** (#9074): Updated actor, skill, and tool name
-  validators to accept the spec-required `[[server:]namespace/]name` format. Previously,
-  server-qualified names like `dev:freemo/custom-analysis` were incorrectly rejected.
-  Added BDD scenarios for server-qualified name acceptance and rejection. All three
-  validators (`ActorConfigSchema.validate_name`, `NAMESPACED_NAME_RE`,
-  `_TOOL_NAME_PATTERN`) now correctly support optional server prefixes while maintaining
-  backward compatibility with existing `namespace/name` names.
-
 - **Automation Profile Silent Fallback** (#8232): `_resolve_profile_for_plan` in
   `PlanLifecycleService` now raises a clear `ValidationError` when a plan's
   automation profile name is not a known built-in profile, instead of silently
@@ -97,7 +60,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   LLM-generated changes via `git merge` from an isolated worktree branch
   instead of flat `shutil.copy2`.  Displays spec-aligned Apply Summary
   (plan ID, artifacts, insertions/deletions, project, timestamp), Sandbox
-  Cleanup panel, and `✓ OK Changes applied` footer.  Non-git projects fall
+  Cleanup panel, and `OK Changes applied` footer.  Non-git projects fall
   back to the original flat file copy.
 
 - **Context Hydration Fix** (#4454): Fixed `ContextFragment` metadata types
@@ -271,7 +234,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - **SubplanExecutionService fail_fast cancellation** (#7582): Fixed a race condition where
   already-running parallel subplans were not cancelled when `fail_fast` fired. Previously,
   `Future.cancel()` only prevented queued futures from starting but had no effect on
-  in-flight futures that completed after `stop_flag` was set -- their `COMPLETE` results
+  in-flight futures that completed after `stop_flag` was set — their `COMPLETE` results
   were incorrectly included in the merge output. The fix adds a post-completion guard that
   overrides any non-`ERRORED`/non-`CANCELLED` result to `CANCELLED` when `stop_flag` is
   active, and clears the associated output to prevent it from entering the merge. Also
@@ -312,7 +275,152 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ---
 
-## [3.8.0] -- 2026-04-05
+## [3.7.0] — Unreleased (In Progress — ~42%)
+
+### Added
+
+- **TUI — MainScreen with Textual >= 1.0**: Implemented the primary `MainScreen` layout
+  with a horizontal conversation/sidebar split. The conversation takes available space
+  (flex: 1fr) and the sidebar is docked to the right (32-40 chars wide, max 45% of screen).
+  A full-width rainbow-gradient throbber (height: 1) appears at the top during actor
+  processing. Session tabs appear above the conversation when two or more sessions are open.
+  See [ADR-044](adr/ADR-044-tui-architecture-and-framework.md) and `docs/tui.md`
+  for full architecture documentation.
+
+- **TUI — Three-State Sidebar**: The sidebar cycles through hidden to visible to
+  fullscreen states via `shift+tab`. In hidden state the conversation takes full width;
+  in visible state the sidebar shows Plans and Projects panels in collapsible containers;
+  in fullscreen state the sidebar covers the entire screen for deep management operations.
+  Pressing `escape` cascades back toward the main screen from any state.
+
+- **TUI — Persona System**: Introduced the Persona abstraction (ADR-045) as a TUI-only
+  concept that bundles an actor reference, base arguments, scoped projects/plans, and
+  argument presets into a single switchable unit. Personas are stored as YAML files in
+  `~/.config/cleveragents/personas/`. The `tab` key cycles through personas; `ctrl+tab`
+  cycles through argument presets within the current persona. The PersonaBar below the
+  prompt always shows the active persona name, actor, preset, scope, and session cost.
+
+- **TUI — Reference and Command Input System**: Implemented three prompt input modes
+  (ADR-046): normal mode with `@` inline references (triggers the Reference Picker overlay
+  with fuzzy search across all projects, plans, and resources), `/` command mode (triggers
+  the Slash Command overlay with tab completion for all TUI operations), and `!` shell mode
+  (executes OS commands via subprocess with output displayed as `ShellResult` blocks).
+  Resolved `@` references are translated into CRP directives for ACMS context assembly.
+
+- **TUI — TuiMaterializer A2A Integration**: Implemented `TuiMaterializer` as a
+  `MaterializationStrategy` that maps `ElementHandle` events to Textual widgets. All
+  existing CLI command producers render in the TUI without modification. Supported mappings:
+  `PanelHandle` to `Collapsible`+`Label`, `TableHandle` to `DataTable`, `TreeHandle` to
+  `Tree`, `ProgressHandle` to `ProgressBar`/`Throbber`, `CodeHandle` to `TextArea`,
+  `DiffHandle` to custom `DiffView`, and more.
+
+- **TUI — Session Persistence**: TUI sessions are persisted to SQLite at
+  `~/.local/state/cleveragents/tui.db`. Full conversation history, session metadata, and
+  cost accumulation are stored across TUI restarts. Sessions are resumable via `ctrl+r`
+  or `/session:list`.
+
+- **TUI — Multi-Session Tabs**: Multiple concurrent sessions are supported, each with an
+  independent persona, conversation history, and A2A Task binding. `ctrl+n` creates a new
+  session; `ctrl+w` closes the current session; `ctrl+[`/`ctrl+]` navigate between tabs.
+
+- **TUI — Settings and Session Management Screens**: Added `SettingsScreen` (accessible via
+  `F2` or `/settings`) for theme selection, sidebar width, session persistence, and
+  notification configuration. Added `SessionsScreen` (accessible via `ctrl+s`) for
+  browsing, resuming, and managing all saved sessions.
+
+- **TUI — Dracula Theme and Notification System**: Default theme is Dracula (all 17+
+  Textual built-in themes supported, switchable via `/theme <name>`). The Flash bar
+  (height: 1, above the prompt) displays transient info/warning/error/success notifications.
+  Block cursor navigation in the conversation stream via `alt+up`/`alt+down`.
+
+- **TUI — Content Pruning and Safety Behaviors**: Conversation stream auto-collapses old
+  messages when the block count exceeds the configurable threshold (default: 500). Shell
+  danger detection highlights destructive command patterns before execution. Inline
+  `PermissionQuestionWidget` renders permission requests in the conversation stream for
+  single-file operations; multi-file operations push the full `PermissionsScreen`.
+
+---
+
+## [3.6.0] — Unreleased (In Progress — ~33%)
+
+### Added
+
+- **Advanced Context Strategies**: Extended the ACMS pipeline with cross-project context
+  merging, incremental context updates, semantic deduplication, adaptive tier promotion,
+  and resource-type-aware budgeting. Added new CRP directive types: `focus_path`,
+  `exclude_pattern`, `max_fragment_size`, and `semantic_group`. See
+  `docs/advanced-concepts.md` for full documentation.
+
+- **Additional LLM Backends**: Added first-class provider support for Google Gemini
+  (`google/gemini-*`), Mistral AI (`mistral/*`), Ollama local inference (`ollama/*`),
+  LM Studio (`lmstudio/*`), Azure OpenAI (`azure/*`), AWS Bedrock (`bedrock/*`), and
+  Groq (`groq/*`). All providers support a common base argument set plus provider-specific
+  extensions. Provider fallback chains allow automatic retry on rate limit or outage.
+
+- **Additional Resource Types**: Added cloud infrastructure resource types (`aws-s3-bucket`,
+  `aws-lambda-function`, `gcp-storage-bucket`, `azure-blob-container`, `terraform-workspace`,
+  `pulumi-stack`), database resource types (`postgres-schema`, `mysql-database`,
+  `sqlite-file`, `mongodb-collection`, `redis-keyspace`), and virtual resource types
+  (`virtual-aggregate`, `virtual-diff`, `virtual-search-index`, `virtual-dependency-graph`).
+
+- **ACP to A2A Module Rename**: Completed the rename of `cleveragents.acp` to
+  `cleveragents.a2a`, aligning all symbols with the adopted A2A standard (ADR-047).
+  A compatibility shim preserves backward compatibility until v4.0.0. Affected symbols:
+  `AcpClient` to `A2AClient`, `AcpMessage` to `A2AMessage`, `AcpTask` to `A2ATask`,
+  `AcpEvent` to `A2AEvent`, `acp_server_url` config key to `a2a_server_url`.
+
+- **Container Tool Execution**: Added `ContainerToolExecutor` for running tools inside
+  isolated container environments. Tools declare container requirements (image, mounts,
+  environment) in their YAML definition. Supports devcontainer integration via the
+  `devcontainer-instance` resource type (ADR-043) — when a project has
+  `.devcontainer/devcontainer.json`, CleverAgents can use it as the execution environment
+  for all tools in that project.
+
+- **Pluggable Scope Chain Resolution**: Made the scope chain resolution system extensible
+  via the `ScopeChainResolver` protocol. Built-in resolvers: `PersonaScopeResolver`,
+  `ReferenceResolver`, `DependencyGraphResolver`, `RecentlyModifiedResolver`,
+  `TestCoverageResolver`. Custom resolvers are registered via the plugin entry point system.
+
+- **Cost and Session Budgets**: Added comprehensive cost tracking (input/output tokens,
+  USD cost, model, session/plan attribution) stored in SQLite. Budget enforcement via
+  `SafetyProfile` fields (`max_cost_per_plan`, `max_total_cost`). When a budget is exceeded,
+  the plan transitions to `PAUSED` with `pause_reason = "budget_exceeded"` and is resumable
+  after the budget is increased. New CLI commands: `agents session cost`,
+  `agents plan cost <id>`.
+
+- **Safety Profiles (Full Enforcement)**: Completed safety profile enforcement (ADR-041)
+  in the plan lifecycle. Added six named built-in profiles: `strict`, `standard`,
+  `permissive`, `read-only`, `cost-capped-1usd`, `cost-capped-5usd`. Safety profiles
+  are now enforced at plan creation, execution, and apply phases.
+
+- **E2E Workflow Specification Tests**: Added a new `e2e` nox session with Robot Framework
+  and Behave test suites covering full plan lifecycle workflows, multi-project workflows,
+  provider-specific behavior, safety profile enforcement, and budget enforcement.
+
+- **Code Review Tool Examples**: Added example actors and skills for code review workflows
+  in `examples/actors/` and `examples/skills/`: `code-reviewer`, `pr-summarizer`,
+  `test-generator`, `doc-writer`, `security-scanner`, `style-checker`.
+
+- **Plugin Architecture Extensions**: Formalized the plugin architecture with entry points
+  for resource types, tool executors, scope resolvers, and LLM providers. The `PluginLoader`
+  enforces module allowlists, entry point validation, and capability declarations.
+  Added plugin development guide at `docs/development/plugin-development.md`.
+
+- **Advanced Concepts Documentation** (`docs/advanced-concepts.md`): Added comprehensive
+  documentation for all v3.6.0 features including advanced context strategies, additional
+  LLM backends, new resource types, ACP-to-A2A migration guide, container tool execution,
+  pluggable scope chain resolution, cost/session budgets, safety profiles, E2E tests,
+  code review examples, and plugin architecture extensions.
+
+- **TUI Documentation** (`docs/tui.md`): Added comprehensive documentation for the v3.7.0
+  TUI implementation covering installation, getting started, main screen layout, sidebar
+  states, persona system, reference and command input, session management, configuration,
+  key bindings, theme and styling, TuiMaterializer integration, real-time A2A event
+  subscription, content pruning, and safety behaviors.
+
+---
+
+## [3.8.0] — 2026-04-05
 
 ### Added
 
@@ -323,13 +431,15 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   `INVARIANT_VIOLATED` events.  Post-correction reconciliation runs
   via `CORRECTION_APPLIED` event subscription (best-effort).  Added
   `InvariantService` Singleton provider in the DI container.
-- **TUI -- Shell danger detection**: The TUI shell mode (`!` prefix) now detects
+- **TUI — Shell danger detection**: The TUI shell mode (`!` prefix) now detects
   dangerous command patterns before execution. A configurable pattern registry
   classifies commands by danger level (warning, critical) and surfaces a user
   warning overlay before proceeding. Patterns cover destructive filesystem
   operations, privilege escalation, network exfiltration, and more. (#1003)
 
-- **TUI -- Permission Question Widget**: A new inline `PermissionQuestionWidget`
+- **TUI — Permission Question Widget**: A new inline `PermissionQuestionWidget`
   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
+  `PermissionsScreen` for multi-file diff review. For multi-file operations,
+  `PermissionsScreen` is pushed directly (no inline widget). (#1004)
diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
index f7f84a8a7..f79bb5dd5 100644
--- a/CONTRIBUTORS.md
+++ b/CONTRIBUTORS.md
@@ -24,3 +24,4 @@ Below are some of the specific details of various contributions.
 * This project was made possible thanks to considerable donation of time, money, and resources by CleverThis, Inc.
 * HAL 9000 has contributed automated bug fixes, CLI output formatting improvements, and ongoing maintenance as part of the CleverAgents automation system.
 * HAL 9000 has contributed the file edit encoding parameter fix (PR #8258 / issue #7559).
+* HAL 9000 has contributed comprehensive milestone documentation for v3.6.0 (Advanced Concepts & Deferred Features) and v3.7.0 (TUI Implementation) (PR #9903): split into sub-documents covering context strategies, LLM backends, resource types, A2A rename, container tool execution, scope chain resolution, cost/safety budgets, E2E workflow tests, code review examples, plugin architecture, TUI layout, persona system, reference/command input, session management, configuration, and TuiMaterializer integration.
diff --git a/docs/advanced-concepts/container-tools.md b/docs/advanced-concepts/container-tools.md
new file mode 100644
index 000000000..f4a3d19d8
--- /dev/null
+++ b/docs/advanced-concepts/container-tools.md
@@ -0,0 +1,248 @@
+# Advanced Concepts: Container Tools, Scope Chain, Budgets & Safety (v3.6.0)
+
+> **Milestone:** v3.6.0 — M7: Advanced Concepts & Deferred Features
+> **Parent:** [Advanced Concepts Overview](index.md)
+
+---
+
+## Container Tool Execution
+
+v3.6.0 adds first-class support for executing tools inside containers, building on the
+container resource types introduced in ADR-039.
+
+### Overview
+
+Container tool execution allows actors to run tools in isolated container environments rather
+than directly on the host. This provides:
+
+- **Stronger isolation** — tool side effects are contained within the container
+- **Reproducible environments** — tools run in a known, versioned environment
+- **Language-agnostic tools** — tools can be written in any language supported by the container
+- **Parallel execution** — multiple containers can run simultaneously for independent tool calls
+
+### Container Tool Configuration
+
+Tools declare their container requirements in their YAML definition:
+
+```yaml
+name: my-org/python-linter
+type: container-tool
+image: "python:3.12-slim"
+command: ["python", "-m", "pylint"]
+mounts:
+  - source: "{{resource.git_dir.path}}"
+    target: "/workspace"
+    readonly: true
+environment:
+  PYTHONPATH: "/workspace/src"
+timeout: 60
+```
+
+### Execution Model
+
+Container tools follow the same `ToolRuntime` interface as host tools. The
+`ContainerToolExecutor` handles:
+
+1. **Image resolution** — pulls the image if not cached locally
+2. **Mount binding** — maps resource paths to container mount points
+3. **Execution** — runs the container with the specified command and arguments
+4. **Output capture** — streams stdout/stderr back to the `ToolResult`
+5. **Cleanup** — removes the container after execution (configurable)
+
+### Devcontainer Integration
+
+When a project has a `.devcontainer/devcontainer.json`, CleverAgents can use the devcontainer
+as the execution environment for all tools in that project. This is configured via the
+`devcontainer-instance` resource type (ADR-043):
+
+```yaml
+resources:
+  - name: dev_env
+    type: devcontainer-instance
+    devcontainer_path: ".devcontainer/devcontainer.json"
+    use_for_tools: true
+```
+
+---
+
+## Pluggable Scope Chain Resolution Extensions
+
+The scope chain resolution system determines which projects, plans, and resources are in scope
+for a given actor invocation. v3.6.0 makes this system extensible via a plugin interface.
+
+### Scope Chain Resolution Protocol
+
+The `ScopeChainResolver` interface defines a single method:
+
+```python
+class ScopeChainResolver(Protocol):
+    def resolve(
+        self,
+        base_scope: Scope,
+        context: ResolutionContext,
+    ) -> Scope:
+        """
+        Extend or modify the base scope based on the resolution context.
+
+        Args:
+            base_scope: The scope as determined by the persona and explicit @ references.
+            context: The current resolution context (session, plan, actor, prompt).
+
+        Returns:
+            The resolved scope, which may add, remove, or reorder items from base_scope.
+        """
+        ...
+```
+
+### Built-in Resolvers
+
+| Resolver | Description |
+|----------|-------------|
+| `PersonaScopeResolver` | Adds persona-scoped projects and plans (always active) |
+| `ReferenceResolver` | Adds explicitly `@`-referenced resources (always active) |
+| `DependencyGraphResolver` | Automatically includes resources that are dependencies of in-scope resources |
+| `RecentlyModifiedResolver` | Adds recently modified files from in-scope projects |
+| `TestCoverageResolver` | Adds test files that cover in-scope source files |
+
+### Custom Resolver Registration
+
+Custom resolvers are registered via the plugin system:
+
+```python
+from cleveragents.scope import ScopeChainResolver, register_resolver
+
+@register_resolver(name="my-org/git-blame-resolver", priority=50)
+class GitBlameResolver:
+    def resolve(self, base_scope, context):
+        # Add files recently modified by the current git user
+        ...
+```
+
+---
+
+## Cost and Session Budgets
+
+v3.6.0 introduces comprehensive cost tracking and budget enforcement across sessions and plans.
+
+### Cost Tracking
+
+Every LLM invocation is tracked with:
+
+- **Input tokens** and **output tokens** (provider-reported)
+- **Cost in USD** (computed from provider pricing tables, updated monthly)
+- **Model used** (for multi-provider fallback chains)
+- **Session ID** and **plan ID** for attribution
+
+Cost data is stored in the SQLite database and queryable via:
+
+```bash
+agents session cost                    # Total cost for current session
+agents session cost --all              # All sessions with costs
+agents plan cost <plan-id>             # Cost breakdown for a specific plan
+agents config get billing.total_spent  # Lifetime total
+```
+
+### Budget Configuration
+
+Budgets are configured at multiple levels (plan > action > project > global):
+
+```toml
+[billing]
+max_cost_per_session = 5.00     # USD; hard limit per session
+max_cost_per_plan = 2.00        # USD; hard limit per plan
+max_total_cost = 100.00         # USD; lifetime hard limit
+warn_at_percent = 80            # Warn when 80% of any budget is consumed
+```
+
+These settings correspond to the `SafetyProfile` fields defined in ADR-041:
+
+| Config Key | SafetyProfile Field |
+|-----------|-------------------|
+| `max_cost_per_plan` | `SafetyProfile.max_cost_per_plan` |
+| `max_total_cost` | `SafetyProfile.max_total_cost` |
+
+### Budget Enforcement
+
+When a budget limit is reached:
+
+1. The current LLM invocation is **not** started (pre-flight check)
+2. A `BudgetExceededError` is raised with the budget type, limit, and current spend
+3. The plan transitions to `PAUSED` state with `pause_reason = "budget_exceeded"`
+4. The user is notified via the CLI output or TUI notification system
+5. The user can increase the budget via `agents config set billing.max_cost_per_plan <new_limit>`
+   and resume the plan with `agents plan resume <plan-id>`
+
+---
+
+## Safety Profiles
+
+Safety profiles (ADR-041) provide fine-grained control over what actions an actor is permitted
+to take. v3.6.0 completes the safety profile implementation with full enforcement in the plan
+lifecycle.
+
+### SafetyProfile Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `require_sandbox` | `bool` | `True` | Require sandbox isolation for all file writes |
+| `require_checkpoints` | `bool` | `True` | Require checkpoints before destructive operations |
+| `allow_unsafe_tools` | `bool` | `False` | Allow tools marked as `unsafe: true` |
+| `require_human_approval` | `bool` | `False` | Require human approval before each action step |
+| `allowed_skill_categories` | `list[str]` | `[]` (all) | Restrict to specific skill categories |
+| `max_cost_per_plan` | `float or None` | `None` | Maximum cost per plan in USD |
+| `max_total_cost` | `float or None` | `None` | Maximum lifetime cost in USD |
+| `max_retries_per_step` | `int` | `3` | Maximum retries per action step (0-100) |
+
+### Built-in Safety Profiles
+
+v3.6.0 ships with named safety profiles that can be referenced by name:
+
+| Profile | Description |
+|---------|-------------|
+| `strict` | All safety flags enabled; no unsafe tools; human approval required |
+| `standard` | Sandbox and checkpoints required; unsafe tools blocked; no human approval |
+| `permissive` | Sandbox required; checkpoints optional; unsafe tools allowed |
+| `read-only` | No file writes permitted; all tools restricted to read operations |
+| `cost-capped-1usd` | Standard safety + $1.00 per-plan cost cap |
+| `cost-capped-5usd` | Standard safety + $5.00 per-plan cost cap |
+
+### Applying Safety Profiles
+
+Safety profiles can be applied at multiple levels:
+
+```bash
+# Global default
+agents config set safety.profile strict
+
+# Per-project
+agents project set-safety my-project --profile standard
+
+# Per-plan (at creation time)
+agents plan use my-action --safety-profile permissive
+```
+
+```yaml
+# action.yaml
+name: my-action
+safety_profile:
+  require_sandbox: true
+  allow_unsafe_tools: false
+  max_cost_per_plan: 2.00
+```
+
+---
+
+## Related ADRs
+
+| ADR | Title | Relevance |
+|-----|-------|-----------|
+| [ADR-039](../adr/ADR-039-container-resource-types.md) | Container Resource Types | Container tool execution |
+| [ADR-041](../adr/ADR-041-safety-profile-extraction.md) | Safety Profile Extraction | Safety profiles and cost budgets |
+| [ADR-043](../adr/ADR-043-devcontainer-integration.md) | Devcontainer Integration | Devcontainer tool execution |
+
+---
+
+*Documentation for v3.6.0 — IN PROGRESS. Features described here reflect the planned scope
+as of 2026-04-15. Some features may be adjusted as implementation progresses.*
+
+*Generated by [AUTO-DOCS-5] — CleverAgents Documentation Bot*
diff --git a/docs/advanced-concepts/e2e-tests-and-plugins.md b/docs/advanced-concepts/e2e-tests-and-plugins.md
new file mode 100644
index 000000000..7d3c35fd4
--- /dev/null
+++ b/docs/advanced-concepts/e2e-tests-and-plugins.md
@@ -0,0 +1,138 @@
+# Advanced Concepts: E2E Tests, Code Review Examples & Plugin Architecture (v3.6.0)
+
+> **Milestone:** v3.6.0 — M7: Advanced Concepts & Deferred Features
+> **Parent:** [Advanced Concepts Overview](index.md)
+
+---
+
+## End-to-End Workflow Specification Tests
+
+v3.6.0 introduces a new category of tests: **E2E workflow specification tests**. These tests
+verify complete multi-step workflows from the user's perspective, exercising the full stack
+from CLI input through plan execution to file output.
+
+### Test Categories
+
+| Category | Description | Framework |
+|----------|-------------|-----------|
+| `e2e/workflow` | Full plan lifecycle: create to strategize to execute to apply | Robot Framework |
+| `e2e/multi-project` | Workflows spanning multiple projects | Robot Framework |
+| `e2e/provider` | Provider-specific behavior (rate limits, fallback, cost tracking) | Behave |
+| `e2e/safety` | Safety profile enforcement under various conditions | Behave |
+| `e2e/budget` | Budget enforcement and plan pause/resume | Behave |
+
+### Running E2E Tests
+
+```bash
+nox -s e2e                          # Run all E2E tests
+nox -s e2e -- --tags workflow       # Run only workflow tests
+nox -s e2e -- --tags provider       # Run only provider tests
+```
+
+E2E tests require a configured LLM provider. Set `E2E_PROVIDER=anthropic` (or another
+supported provider) in your environment before running.
+
+---
+
+## Code Review Tool Examples
+
+v3.6.0 ships a set of example actors and skills specifically designed for code review
+workflows. These serve as both functional tools and reference implementations for the actor
+and skill systems.
+
+### Included Examples
+
+| Example | Location | Description |
+|---------|----------|-------------|
+| `code-reviewer` | `examples/actors/code-reviewer.yaml` | Full code review actor with diff analysis, style checking, and security scanning |
+| `pr-summarizer` | `examples/actors/pr-summarizer.yaml` | Summarizes pull request changes for review |
+| `test-generator` | `examples/actors/test-generator.yaml` | Generates BDD test scenarios from source code |
+| `doc-writer` | `examples/actors/doc-writer.yaml` | Generates and updates documentation from code |
+| `security-scanner` | `examples/skills/security-scanner.yaml` | Skill that runs security analysis tools |
+| `style-checker` | `examples/skills/style-checker.yaml` | Skill that runs linting and formatting checks |
+
+### Using the Code Reviewer
+
+```bash
+# Register the example actor
+agents actor register examples/actors/code-reviewer.yaml
+
+# Create a code review plan
+agents plan use code-review \
+  --project local/my-project \
+  --arg diff_source=git \
+  --arg base_branch=main
+```
+
+---
+
+## Plugin Architecture Extensions
+
+v3.6.0 formalizes and extends the plugin architecture, making it easier to add custom
+resource types, tool executors, scope resolvers, and LLM providers.
+
+### Plugin Entry Points
+
+Plugins are registered via Python package entry points:
+
+```toml
+# pyproject.toml
+[project.entry-points."cleveragents.plugins"]
+my-plugin = "my_package.plugin:MyPlugin"
+
+[project.entry-points."cleveragents.resource_types"]
+my-resource = "my_package.resources:MyResourceType"
+
+[project.entry-points."cleveragents.tool_executors"]
+my-executor = "my_package.executors:MyToolExecutor"
+
+[project.entry-points."cleveragents.scope_resolvers"]
+my-resolver = "my_package.resolvers:MyScopeResolver"
+
+[project.entry-points."cleveragents.providers"]
+my-provider = "my_package.providers:MyLLMProvider"
+```
+
+### Plugin Security
+
+The `PluginLoader` (hardened in v3.5.0) enforces:
+
+- **Module allowlist** — only modules from registered, trusted packages may be loaded
+- **Entry point validation** — entry point targets are parsed and validated before import
+- **Sandbox isolation** — plugins run in a restricted execution environment
+- **Capability declaration** — plugins must declare their required capabilities at registration
+
+See ADR-037 (Tool Reachability & Access Projection) for the full security model.
+
+### Plugin Development Guide
+
+A plugin development guide is available at `docs/development/plugin-development.md` (added
+in v3.6.0). It covers:
+
+1. Creating a minimal plugin package
+2. Registering resource types, tool executors, and scope resolvers
+3. Testing plugins with the CleverAgents test harness
+4. Publishing plugins to PyPI
+
+---
+
+## Related ADRs
+
+The following Architecture Decision Records are directly relevant to v3.6.0 features:
+
+| ADR | Title | Relevance |
+|-----|-------|-----------|
+| [ADR-008](../adr/ADR-008-resource-system.md) | Resource System | Foundation for additional resource types |
+| [ADR-036](../adr/ADR-036-resource-dag-operational-semantics.md) | Resource DAG Operational Semantics | DAG model for new resource types |
+| [ADR-039](../adr/ADR-039-container-resource-types.md) | Container Resource Types | Container tool execution |
+| [ADR-041](../adr/ADR-041-safety-profile-extraction.md) | Safety Profile Extraction | Safety profiles and cost budgets |
+| [ADR-042](../adr/ADR-042-resource-type-inheritance.md) | Resource Type Inheritance | Custom resource type extensions |
+| [ADR-043](../adr/ADR-043-devcontainer-integration.md) | Devcontainer Integration | Devcontainer tool execution |
+| [ADR-047](../adr/ADR-047-acp-standard-adoption.md) | A2A Standard Adoption | ACP to A2A rename |
+
+---
+
+*Documentation for v3.6.0 — IN PROGRESS. Features described here reflect the planned scope
+as of 2026-04-15. Some features may be adjusted as implementation progresses.*
+
+*Generated by [AUTO-DOCS-5] — CleverAgents Documentation Bot*
diff --git a/docs/advanced-concepts/index.md b/docs/advanced-concepts/index.md
new file mode 100644
index 000000000..6d70b87e3
--- /dev/null
+++ b/docs/advanced-concepts/index.md
@@ -0,0 +1,117 @@
+# Advanced Concepts (v3.6.0)
+
+> **Milestone:** v3.6.0 — M7: Advanced Concepts & Deferred Features
+> **Status:** In Progress (~33% complete as of 2026-04-15)
+> **Goal:** Advanced capabilities that extend beyond the core MVP without requiring the TUI (M8) or Server (M9).
+
+---
+
+## Overview
+
+v3.6.0 builds on the stable foundation established by v3.0.0–v3.5.0 to introduce advanced
+capabilities that were intentionally deferred from the MVP. These features enrich the
+CleverAgents platform for power users and production deployments: richer context strategies,
+broader LLM provider support, additional resource types, a standardized A2A protocol, container
+tool execution, extensible scope chain resolution, cost and safety budgets, end-to-end workflow
+tests, and a plugin architecture.
+
+None of these features require the TUI (v3.7.0) or the Server (v3.9.0) — they are fully
+usable from the CLI and programmatic API.
+
+**Sub-sections:**
+
+- [Context Strategies & LLM Backends](index.md) — this page
+- [Resource Types & A2A Rename](resource-types.md)
+- [Container Tools, Scope Chain, Budgets & Safety](container-tools.md)
+- [E2E Tests, Code Review Examples & Plugin Architecture](e2e-tests-and-plugins.md)
+
+---
+
+## Advanced Context Strategies
+
+The ACMS (Adaptive Context Management System) introduced in v3.4.0–v3.5.0 provides a
+four-stage pipeline: **Gather → Prioritize → Assemble → Deliver**. v3.6.0 extends this
+pipeline with advanced strategies for large-scale and multi-project workloads.
+
+### Beyond the Basic ACMS Pipeline
+
+The basic pipeline assembles context from a single project's resources using a fixed priority
+order. Advanced strategies add:
+
+| Strategy | Description |
+|----------|-------------|
+| **Cross-project context merging** | Assembles context from multiple projects simultaneously, respecting per-project budgets and cross-project relevance scores |
+| **Incremental context updates** | Sends only the diff of context changes between turns rather than re-assembling the full context on every prompt |
+| **Semantic deduplication** | Detects and removes semantically equivalent fragments before assembly, reducing token waste |
+| **Adaptive tier promotion** | Automatically promotes frequently-accessed warm/cold fragments to hot tier based on access patterns across a session |
+| **Resource-type-aware budgeting** | Allocates context budget by resource type (e.g., 40% source code, 30% tests, 20% docs, 10% config) rather than a flat priority queue |
+
+### Context Request Protocol (CRP) Extensions
+
+The CRP (defined in ADR-014) is extended with new directive types:
+
+- `focus_path` — elevates a specific file path to the highest priority tier, overriding all
+  other budget constraints
+- `exclude_pattern` — excludes files matching a glob pattern from context assembly
+- `max_fragment_size` — caps the size of any single fragment to prevent one large file from
+  consuming the entire budget
+- `semantic_group` — groups related fragments so they are either all included or all excluded
+  (prevents partial inclusion of tightly coupled files)
+
+---
+
+## Additional LLM Backends
+
+v3.6.0 adds first-class support for additional LLM providers beyond the Anthropic and OpenAI
+backends available in v3.5.0.
+
+### Supported Providers (v3.6.0 additions)
+
+| Provider | Actor Namespace | Notes |
+|----------|----------------|-------|
+| **Google Gemini** | `google/gemini-*` | Gemini 1.5 Pro and Flash; supports long-context (1M tokens) |
+| **Mistral AI** | `mistral/*` | Mistral Large, Codestral; strong code generation |
+| **Ollama (local)** | `ollama/*` | Any model served by a local Ollama instance |
+| **LM Studio** | `lmstudio/*` | OpenAI-compatible local inference |
+| **Azure OpenAI** | `azure/*` | Azure-hosted OpenAI models with enterprise auth |
+| **AWS Bedrock** | `bedrock/*` | Anthropic, Meta, and Mistral models via AWS |
+| **Groq** | `groq/*` | Ultra-fast inference for Llama and Mixtral models |
+
+### Provider Configuration
+
+All providers are configured in `~/.config/cleveragents/config.toml` under the `[providers]`
+section. Each provider supports a common set of base arguments (`temperature`, `max_tokens`,
+`thinking_effort` where applicable) plus provider-specific extensions.
+
+```toml
+[providers.google]
+api_key = "${GOOGLE_API_KEY}"
+default_model = "gemini-1.5-pro"
+
+[providers.ollama]
+base_url = "http://localhost:11434"
+default_model = "llama3.2"
+```
+
+### Provider Fallback Chains
+
+A new `provider_fallback` configuration allows defining ordered fallback chains for resilience:
+
+```toml
+[actor.default]
+provider_fallback = [
+  "anthropic/claude-4-sonnet",
+  "google/gemini-1.5-pro",
+  "ollama/llama3.2",
+]
+```
+
+When the primary provider fails (rate limit, outage, or cost budget exceeded), the system
+automatically retries with the next provider in the chain.
+
+---
+
+*Documentation for v3.6.0 — IN PROGRESS. Features described here reflect the planned scope
+as of 2026-04-15. Some features may be adjusted as implementation progresses.*
+
+*Generated by [AUTO-DOCS-5] — CleverAgents Documentation Bot*
diff --git a/docs/advanced-concepts/resource-types.md b/docs/advanced-concepts/resource-types.md
new file mode 100644
index 000000000..dab8d470e
--- /dev/null
+++ b/docs/advanced-concepts/resource-types.md
@@ -0,0 +1,112 @@
+# Advanced Concepts: Resource Types & A2A Rename (v3.6.0)
+
+> **Milestone:** v3.6.0 — M7: Advanced Concepts & Deferred Features
+> **Parent:** [Advanced Concepts Overview](index.md)
+
+---
+
+## Additional Resource Types
+
+v3.6.0 extends the resource type system (ADR-008, ADR-036, ADR-039, ADR-042) with new
+resource types for cloud infrastructure, databases, and virtual/composite resources.
+
+### Cloud Infrastructure Resources
+
+| Type | Description | Key Properties |
+|------|-------------|----------------|
+| `aws-s3-bucket` | Amazon S3 bucket | `bucket_name`, `region`, `prefix` |
+| `aws-lambda-function` | AWS Lambda function | `function_name`, `region`, `runtime` |
+| `gcp-storage-bucket` | Google Cloud Storage bucket | `bucket_name`, `project_id` |
+| `azure-blob-container` | Azure Blob Storage container | `account_name`, `container_name` |
+| `terraform-workspace` | Terraform workspace (state + config) | `workspace_dir`, `backend_type` |
+| `pulumi-stack` | Pulumi stack | `stack_name`, `project_dir` |
+
+### Database Resources
+
+| Type | Description | Key Properties |
+|------|-------------|----------------|
+| `postgres-schema` | PostgreSQL schema (tables, views, functions) | `connection_string`, `schema_name` |
+| `mysql-database` | MySQL database | `connection_string`, `database_name` |
+| `sqlite-file` | SQLite database file | `file_path` |
+| `mongodb-collection` | MongoDB collection | `connection_string`, `database`, `collection` |
+| `redis-keyspace` | Redis keyspace | `connection_string`, `key_prefix` |
+
+### Virtual Resource Types
+
+Virtual resources do not correspond to a physical storage location — they are computed
+aggregates or logical groupings:
+
+| Type | Description |
+|------|-------------|
+| `virtual-aggregate` | A named union of other resources, treated as a single context source |
+| `virtual-diff` | The diff between two resource snapshots (e.g., before/after a plan apply) |
+| `virtual-search-index` | A pre-built semantic search index over a set of resources |
+| `virtual-dependency-graph` | The dependency graph of a codebase (imports, calls, inheritance) |
+
+### Resource Type Inheritance
+
+The resource type inheritance system (ADR-042) allows custom resource types to extend built-in
+types. v3.6.0 adds the `@extends` directive in resource YAML:
+
+```yaml
+type: my-org/custom-git-repo
+extends: git-checkout
+properties:
+  ci_config_path:
+    type: string
+    default: ".github/workflows"
+  deploy_branch:
+    type: string
+    default: "main"
+```
+
+---
+
+## ACP to A2A Module Rename and Symbol Standardization
+
+v3.6.0 completes the rename of the internal `acp` module to `a2a`, aligning the codebase with
+the adopted A2A standard (ADR-047).
+
+### What Changed
+
+| Before (ACP) | After (A2A) |
+|-------------|------------|
+| `cleveragents.acp` | `cleveragents.a2a` |
+| `AcpClient` | `A2AClient` |
+| `AcpMessage` | `A2AMessage` |
+| `AcpTask` | `A2ATask` |
+| `AcpEvent` | `A2AEvent` |
+| `acp_server_url` config key | `a2a_server_url` config key |
+
+### Migration Guide
+
+Existing code that imports from `cleveragents.acp` will continue to work via a compatibility
+shim until v4.0.0. A deprecation warning is emitted on first import. To migrate:
+
+```python
+# Before
+from cleveragents.acp import AcpClient, AcpMessage
+
+# After
+from cleveragents.a2a import A2AClient, A2AMessage
+```
+
+The CLI commands are unaffected — they use the public API which was already A2A-named.
+
+---
+
+## Related ADRs
+
+| ADR | Title | Relevance |
+|-----|-------|-----------|
+| [ADR-008](../adr/ADR-008-resource-system.md) | Resource System | Foundation for additional resource types |
+| [ADR-036](../adr/ADR-036-resource-dag-operational-semantics.md) | Resource DAG Operational Semantics | DAG model for new resource types |
+| [ADR-042](../adr/ADR-042-resource-type-inheritance.md) | Resource Type Inheritance | Custom resource type extensions |
+| [ADR-047](../adr/ADR-047-acp-standard-adoption.md) | A2A Standard Adoption | ACP to A2A rename |
+
+---
+
+*Documentation for v3.6.0 — IN PROGRESS. Features described here reflect the planned scope
+as of 2026-04-15. Some features may be adjusted as implementation progresses.*
+
+*Generated by [AUTO-DOCS-5] — CleverAgents Documentation Bot*
diff --git a/docs/tui/configuration-and-integration.md b/docs/tui/configuration-and-integration.md
new file mode 100644
index 000000000..a665099b3
--- /dev/null
+++ b/docs/tui/configuration-and-integration.md
@@ -0,0 +1,209 @@
+# TUI: Configuration, Key Bindings, Theme & Integration (v3.7.0)
+
+> **Milestone:** v3.7.0 — M8: TUI Implementation
+> **Parent:** [TUI Overview](index.md)
+
+---
+
+## Configuration
+
+### Settings Screen
+
+The Settings screen (`F2` or `/settings`) provides a GUI for all TUI configuration:
+
+- **Theme** — select from 17+ Textual built-in themes (default: Dracula)
+- **Sidebar width** — configure the visible sidebar width (default: 32 chars)
+- **Session persistence** — enable/disable session history persistence
+- **Cost display** — configure cost display precision and currency
+- **Notification duration** — configure how long Flash notifications stay visible
+- **Keybindings** — view all keybindings (editing not yet supported in v3.7.0)
+
+### Configuration File
+
+TUI settings are stored in `~/.config/cleveragents/config.toml` under `[tui]`:
+
+```toml
+[tui]
+theme = "dracula"
+sidebar_width = 32
+session_db_path = "~/.local/state/cleveragents/tui.db"
+notification_duration = 3.0     # seconds
+cost_display_precision = 2      # decimal places
+```
+
+TUI state (last persona, sidebar state, window dimensions) is stored separately in
+`~/.config/cleveragents/tui-state.yaml`:
+
+```yaml
+last_persona: "feature-dev"
+last_preset: "think: high"
+last_session_id: "01HXM8C2..."
+sidebar_state: "visible"
+theme_override: null
+window_width: 180
+window_height: 50
+```
+
+---
+
+## Key Bindings
+
+### Global Bindings
+
+| Key | Action |
+|-----|--------|
+| `ctrl+q` | Quit the TUI |
+| `F1` | Open context-sensitive help panel |
+| `F2` / `ctrl+,` | Open Settings screen |
+| `ctrl+s` | Open Sessions screen |
+| `ctrl+n` | New session tab |
+| `ctrl+w` | Close current session tab |
+| `ctrl+[` | Previous session tab |
+| `ctrl+]` | Next session tab |
+
+### Conversation Bindings
+
+| Key | Action |
+|-----|--------|
+| `alt+up` | Move block cursor up |
+| `alt+down` | Move block cursor down |
+| `enter` / `space` | Expand/collapse focused block |
+| `ctrl+b` | Focus sidebar (when visible) |
+
+### Prompt Bindings
+
+| Key | Action |
+|-----|--------|
+| `tab` | Cycle to next persona |
+| `ctrl+tab` | Cycle to next argument preset |
+| `shift+tab` | Cycle sidebar state (hidden → visible → fullscreen) |
+| `shift+enter` / `ctrl+j` | Insert newline (multi-line mode) |
+| `escape` | Dismiss overlay / exit multi-line mode / navigate toward main screen |
+
+### Sidebar Bindings (when focused)
+
+| Key | Action |
+|-----|--------|
+| `up` / `down` | Navigate plan/project list |
+| `enter` | Open detail modal for selected item |
+| `escape` | Return focus to prompt |
+
+---
+
+## Theme and Styling
+
+The TUI uses Textual's CSS (TCSS) system with semantic color tokens. The default theme is
+**Dracula**. All 17+ Textual built-in themes are supported and switchable via:
+
+```bash
+/theme dracula        # Switch to Dracula theme
+/theme nord           # Switch to Nord theme
+/theme monokai        # Switch to Monokai theme
+/theme                # Show current theme
+```
+
+Or via the Settings screen (`F2`).
+
+### Throbber
+
+A rainbow gradient animated bar spans the full width of the screen at the top, visible only
+when the actor is processing. The gradient cycles through a 12-color spectrum at 15fps.
+When idle, the throbber row collapses to zero height.
+
+### Notification System
+
+The Flash bar (height: 1, above the prompt) displays transient notifications:
+
+- **Info** — blue, 3 seconds
+- **Warning** — yellow, 5 seconds
+- **Error** — red, 10 seconds (or until dismissed with `escape`)
+- **Success** — green, 3 seconds
+
+---
+
+## TuiMaterializer — Output Rendering Integration
+
+The `TuiMaterializer` bridges the existing `OutputSession` / `ElementHandle` pipeline
+(ADR-021) to Textual widgets. All existing CLI command producers render in the TUI without
+modification — the same code that renders Rich tables in the CLI renders interactive Textual
+widgets in the TUI.
+
+| ElementHandle Type | Textual Widget |
+|--------------------|----------------|
+| `PanelHandle` | `Static` container with key-value `Label` pairs in a `Collapsible` |
+| `TableHandle` | `DataTable` widget |
+| `TreeHandle` | `Tree` widget |
+| `ProgressHandle` | `ProgressBar` (determinate) or `Throbber` (indeterminate) |
+| `StatusHandle` | `Label` with semantic CSS class |
+| `CodeHandle` | Read-only `TextArea` with tree-sitter syntax highlighting |
+| `DiffHandle` | Custom `DiffView` widget (unified and side-by-side modes) |
+| `SeparatorHandle` | `Rule` widget |
+| `ActionHintHandle` | `Static` with muted text and command references |
+
+---
+
+## Real-Time A2A Event Subscription
+
+The TUI subscribes to A2A events for real-time visibility into system activity:
+
+| Event | TUI Effect |
+|-------|-----------|
+| `plan.phase_changed` | Sidebar PlansPanel: update phase indicator |
+| `plan.state_changed` | Sidebar PlansPanel: update state badge |
+| `plan.decision_made` | Sidebar PlansPanel: update depth counter |
+| `tool.invoked` | Conversation: mount ToolCall widget (pending) |
+| `tool.completed` | Conversation: update ToolCall widget (done/fail) |
+| `validation.completed` | Conversation: append validation result |
+| `plan.apply_completed` | Sidebar: update terminal state; Flash: show completion |
+| `plan.error` | Flash: show error; Sidebar: mark plan as errored |
+| `session.message` | Conversation: stream ActorResponse content |
+
+In local mode, events arrive via RxPY observables. In server mode, events arrive via A2A
+`TaskStatusUpdateEvent` / `TaskArtifactUpdateEvent` via SSE.
+
+---
+
+## Content Pruning and Safety Behaviors
+
+### Content Pruning
+
+When the conversation stream exceeds the configurable threshold (default: 500 message blocks),
+old messages are automatically collapsed (not deleted) to maintain rendering performance.
+Collapsed messages remain in the session history and can be expanded by scrolling up.
+
+Configure the pruning threshold:
+
+```toml
+[tui]
+conversation_prune_threshold = 500
+```
+
+### Safety Behaviors
+
+The TUI enforces safety behaviors from the active persona's safety profile:
+
+- **Shell danger detection** — commands matching destructive patterns are highlighted in red
+  with a confirmation overlay before execution
+- **Permission questions** — single-file tool operations render an inline `PermissionQuestionWidget`
+  in the conversation stream; multi-file operations push the full `PermissionsScreen`
+- **Cost warnings** — when session cost approaches the configured budget, a persistent warning
+  appears in the Flash bar
+- **Loading states** — the throbber and per-block loading indicators prevent user confusion
+  during long-running operations
+
+---
+
+## Related ADRs
+
+| ADR | Title | Relevance |
+|-----|-------|-----------|
+| [ADR-044](../adr/ADR-044-tui-architecture-and-framework.md) | TUI Architecture and Framework | Core TUI design decisions |
+| [ADR-021](../adr/ADR-021-cli-and-output-rendering.md) | CLI and Output Rendering | TuiMaterializer integration |
+| [ADR-026](../adr/ADR-026-agent-client-protocol.md) | Agent-to-Agent Protocol (A2A) | TUI-to-application communication |
+
+---
+
+*Documentation for v3.7.0 — IN PROGRESS. Features described here reflect the planned scope
+as of 2026-04-15. Some features may be adjusted as implementation progresses.*
+
+*Generated by [AUTO-DOCS-5] — CleverAgents Documentation Bot*
diff --git a/docs/tui/index.md b/docs/tui/index.md
new file mode 100644
index 000000000..95ab5a5fd
--- /dev/null
+++ b/docs/tui/index.md
@@ -0,0 +1,166 @@
+# Text User Interface (TUI) — v3.7.0
+
+> **Milestone:** v3.7.0 — M8: TUI Implementation
+> **Status:** In Progress (~42% complete as of 2026-04-15)
+> **Goal:** Implement the comprehensive Text User Interface using Textual >= 1.0 and all TUI-dependent features.
+>
+> **Key ADRs:** [ADR-044](../adr/ADR-044-tui-architecture-and-framework.md) (TUI Architecture),
+> [ADR-045](../adr/ADR-045-tui-persona-system.md) (Persona System),
+> [ADR-046](../adr/ADR-046-tui-reference-and-command-system.md) (Reference & Command System)
+
+---
+
+## Overview
+
+The CleverAgents TUI is a full-screen terminal application built with
+[Textual](https://textual.textualize.io/) >= 1.0. It provides a rich, keyboard-driven
+interface for interacting with actors, managing plans and projects, and monitoring real-time
+plan execution — capabilities that are impractical in the stateless CLI.
+
+The TUI is the second Presentation-layer surface in the CleverAgents multi-frontend
+architecture (CLI, **TUI**, Web, IDE Plugin, A2A Server). All five surfaces communicate
+exclusively through the A2A protocol (ADR-026) — the TUI never imports directly from the
+Domain or Infrastructure layers.
+
+**Sub-sections:**
+
+- [Overview & Main Screen Layout](index.md) — this page
+- [Sidebar States & Persona System](sidebar-and-personas.md)
+- [Reference/Command Input & Session Management](input-and-sessions.md)
+- [Configuration, Key Bindings, Theme & Integration](configuration-and-integration.md)
+
+### Installation
+
+The TUI is an optional extra to keep the base installation lightweight:
+
+```bash
+pip install cleveragents[tui]
+```
+
+### Launching the TUI
+
+```bash
+agents tui                    # Launch with default persona
+agents tui --persona feature-dev   # Launch with a specific persona
+agents tui --server https://my-server:8080  # Connect to a remote A2A server
+```
+
+---
+
+## Getting Started
+
+### First Run
+
+On first launch (no personas configured), the TUI opens to the main chat screen with a
+centered actor selection overlay:
+
+1. The overlay lists all registered actors discovered from the Actor Registry via A2A
+2. Select an actor with arrow keys + `enter`, or type `/` to search
+3. Selection creates a default persona named `"default"` with the chosen actor and
+   auto-generated argument presets
+4. The overlay dismisses and you can begin chatting immediately
+
+### Subsequent Launches
+
+The TUI restores the last active persona and session automatically. Your conversation
+history, sidebar state, and theme preference are all preserved.
+
+---
+
+## Main Screen Layout
+
+The MainScreen is the primary interface. It uses a horizontal layout with the conversation
+taking available space and the sidebar docked to the right:
+
+```
+┌──────────────────────────────────────────────────────┬──────────────────────┐
+│ Throbber (height: 1, full width, visible when busy)  │                      │
+│ SessionTabs (height: auto, visible when >= 2 sessions)│                      │
+├──────────────────────────────────────────────────────┤  SideBar             │
+│                                                      │  (dock: right)       │
+│  Conversation                                        │  (width: 32-40)      │
+│  (flex: 1fr)                                         │  (max-width: 45%)    │
+│                                                      │  ┌────────────────┐  │
+│  ┌─ ContentsGrid ─────────────────────────────────┐  │  │ PlansPanel     │  │
+│  │ Cursor │ Contents stream                       │  │  │ (collapsible)  │  │
+│  │  (1ch) │  - Welcome / UserInput / ActorResponse│  │  │                │  │
+│  │        │  - ToolCall / PlanProgress / DiffView │  │  ├────────────────┤  │
+│  │        │  - TerminalEmbed / Note / Warning     │  │  │ ProjectsPanel  │  │
+│  └────────┴───────────────────────────────────────┘  │  │ (collapsible)  │  │
+│                                                      │  │                │  │
+│  Flash (notification bar, height: 1)                 │  └────────────────┘  │
+│                                                      │                      │
+│  ┌─ Prompt ────────────────────────────────────────┐ │                      │
+│  │ ReferencePickerOverlay (overlay, triggered by @)│ │                      │
+│  │ SlashCommandOverlay (overlay, triggered by /)   │ │                      │
+│  │ ┌─ PromptContainer ─────────────────────────┐   │ │                      │
+│  │ │ [>] PromptTextArea                        │   │ │                      │
+│  │ └───────────────────────────────────────────┘   │ │                      │
+│  │ PersonaBar: name | actor | preset | cost        │ │                      │
+│  └─────────────────────────────────────────────────┘ │                      │
+├──────────────────────────────────────────────────────┴──────────────────────┤
+│ Footer: F1 Help | shift+tab Sidebar | tab Persona | ctrl+q Quit             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Conversation Stream
+
+The conversation displays a chronological stream of typed message blocks:
+
+| Block Type | Description | Source |
+|------------|-------------|--------|
+| `Welcome` | ASCII art + first-run instructions | App startup (first message only) |
+| `UserInput` | Your prompt, rendered as Markdown | User submission |
+| `ActorResponse` | Streaming Markdown with syntax-highlighted code | Actor response events |
+| `ActorThought` | Actor reasoning (italic, muted, collapsible) | Actor thinking events |
+| `ToolCall` | Expandable tool invocation with status and output | Tool execution events |
+| `PlanProgress` | Grid layout with status icons per step | Plan phase changes |
+| `DiffView` | Unified or side-by-side diff with syntax highlighting | Tool results with diffs |
+| `TerminalEmbed` | Bordered terminal output | Shell commands or tool terminal output |
+| `ShellResult` | Shell command output | User `!` shell commands |
+| `Note` | Semantic info/warning/error notifications | System notifications |
+
+The conversation uses a 2-column grid: a 1-character cursor column (left) navigable with
+`alt+up`/`alt+down`, and the content stream (right). Press `enter` or `space` on a block
+to expand/collapse it.
+
+---
+
+## Architecture Notes
+
+The TUI is implemented in `src/cleveragents/tui/` and follows the layered architecture
+(ADR-001):
+
+```
+src/cleveragents/tui/
+├── app.py                  # CleverAgentsApp root
+├── cleveragents.tcss       # Global app styles
+├── screens/                # Screen classes and TCSS
+│   ├── main.py             # MainScreen
+│   ├── sidebar_full.py     # SidebarFullScreen
+│   ├── plan_detail.py      # PlanDetailModal
+│   ├── project_detail.py   # ProjectDetailModal
+│   ├── persona_editor.py   # PersonaEditorModal
+│   ├── settings.py         # SettingsScreen
+│   ├── sessions.py         # SessionsScreen
+│   └── permissions.py      # PermissionsScreen
+├── widgets/                # Custom Textual widgets
+│   ├── conversation.py     # Conversation stream widgets
+│   ├── prompt.py           # Prompt area and overlays
+│   ├── sidebar.py          # Sidebar panels
+│   └── throbber.py         # Rainbow throbber
+├── materializer.py         # TuiMaterializer implementation
+├── persona.py              # Persona loading and management
+└── session_db.py           # SQLite session persistence
+```
+
+Import-linter rules enforce that `src/cleveragents/tui/` imports only from
+`src/cleveragents/cli/output/` (for `TuiMaterializer` integration) and A2A client
+interfaces — never from Domain or Infrastructure layers directly.
+
+---
+
+*Documentation for v3.7.0 — IN PROGRESS. Features described here reflect the planned scope
+as of 2026-04-15. Some features may be adjusted as implementation progresses.*
+
+*Generated by [AUTO-DOCS-5] — CleverAgents Documentation Bot*
diff --git a/docs/tui/input-and-sessions.md b/docs/tui/input-and-sessions.md
new file mode 100644
index 000000000..659f55d18
--- /dev/null
+++ b/docs/tui/input-and-sessions.md
@@ -0,0 +1,156 @@
+# TUI: Reference/Command Input & Session Management (v3.7.0)
+
+> **Milestone:** v3.7.0 — M8: TUI Implementation
+> **Parent:** [TUI Overview](index.md)
+
+---
+
+## Reference and Command Input
+
+The TUI prompt supports three input modes, each activated by a distinct prefix character.
+This system is defined in ADR-046.
+
+### Input Modes
+
+| First Character | Mode | Prompt Symbol | Sent To |
+|-----------------|------|---------------|---------|
+| *(any other)* | Normal | `>` | Actor via A2A |
+| `@` *(inline)* | Normal + Reference | `>` | Actor (with CRP directives) |
+| `/` | Command | `/` | TUI command processor |
+| `!` | Shell | `$` | Host OS subprocess |
+
+### @ Reference System
+
+Type `@` anywhere in a normal-mode prompt to open the **Reference Picker** overlay. This
+provides real-time fuzzy search across all registered projects, plans, and resources.
+
+```
+@project:cleveragents              # Reference an entire project
+@project:cleveragents:src/foo.py   # Reference a specific file
+@plan:01HXM8C2                     # Reference a plan by ULID
+@plan:01HXM8C2:decision/D3         # Reference a specific decision
+@handler.py                        # Fuzzy match (expands to canonical form)
+```
+
+Resolved `@` references are translated into CRP (Context Request Protocol) directives that
+direct the ACMS to prioritize the referenced resources in context assembly. They are not
+merely display annotations — they have real semantic effect on what the actor sees.
+
+#### Reference Picker Overlay
+
+```
++- Reference Picker -----------------------------------------------+
+| @hand                                                            |
+| ---------------------------------------------------------------- |
+|  PROJECT  api-service:src/auth/handler.py                        |
+|           local/api-service * Python * 245 lines                 |
+|                                                                  |
+|  PROJECT  cleveragents:git_dir/src/cli/commands/handler.py       |
+|           local/cleveragents * Python * 189 lines                |
+|                                                                  |
+|  PLAN     fix-auth-handler (01HXM8C2...)                         |
+|           Phase: Execute * Actor: claude-4-sonnet                |
+|                                                                  |
+| enter Select | tab Tree | ctrl+p Projects | ctrl+l Plans         |
++------------------------------------------------------------------+
+```
+
+Navigation: `up`/`down` to move, `enter` to select, `tab` to switch to tree browser mode,
+`escape` to dismiss.
+
+### / Command System
+
+Type `/` at the start of the prompt to open the **Slash Command** overlay with tab completion.
+Commands cover all TUI operations and mirror the CLI command set.
+
+Key command namespaces:
+
+| Namespace | Examples |
+|-----------|---------|
+| `/session:*` | `create`, `list`, `switch`, `close`, `export`, `import` |
+| `/persona:*` | `list`, `set`, `create`, `edit`, `delete`, `export`, `import` |
+| `/scope:*` | `add`, `remove`, `clear`, `show` |
+| `/plan:*` | `use`, `list`, `status`, `tree`, `execute`, `apply`, `cancel`, `diff`, `correct` |
+| `/project:*` | `list`, `create`, `show`, `delete`, `inspect` |
+| `/actor:*` | `list`, `show`, `set-default` |
+| `/resource:*` | `list`, `show`, `tree`, `inspect` |
+| `/config:*` | `list`, `get`, `set` |
+| TUI utilities | `/clear`, `/theme`, `/settings`, `/help`, `/about`, `/debug` |
+
+### ! Shell Mode
+
+Type `!` at the start of the prompt to enter shell mode. Commands execute on the host OS
+and output appears as `ShellResult` blocks in the conversation stream.
+
+```
+! git status          # Run git status
+! ls -la src/         # List directory
+! python -m pytest    # Run tests
+```
+
+Shell mode features:
+- Separate command history (navigable with `up`/`down`)
+- File/directory tab completion
+- Dangerous command detection (destructive patterns highlighted in red with confirmation)
+- Real-time output streaming for long-running commands
+- `ctrl+c` sends SIGINT to the subprocess
+
+---
+
+## Session Management
+
+Each session tab represents an independent domain `Session` (ADR-020) with its own
+conversation history, persona binding, and A2A Task.
+
+### Session Tabs
+
+Session tabs appear at the top of the screen when two or more sessions are open:
+
+| Key | Action |
+|-----|--------|
+| `ctrl+n` | Create a new session tab with the current persona |
+| `ctrl+w` | Close the current session tab (confirms if conversation exists) |
+| `ctrl+[` | Switch to the previous session tab |
+| `ctrl+]` | Switch to the next session tab |
+| `ctrl+r` | Resume a previous session from the Sessions screen |
+
+Session tab state indicators:
+- `⌛` — actor is working
+- `>` — awaiting user input
+- *(plain)* — idle
+
+### Session Persistence
+
+Sessions are persisted to SQLite at `~/.local/state/cleveragents/tui.db`. This includes:
+
+- Full conversation history (all message blocks)
+- Session metadata (persona, actor, creation time, last activity)
+- Session cost accumulation
+
+Sessions persist across TUI restarts. Use `ctrl+r` or `/session:list` to resume a previous
+session.
+
+### Sessions Screen
+
+The Sessions screen (`ctrl+s` or `/session:list`) provides a full-screen view of all sessions:
+
+- Sortable by name, date, cost, or message count
+- Search/filter by persona, actor, or keyword
+- Bulk operations: delete multiple sessions, export session history
+- Resume any session with `enter`
+
+---
+
+## Related ADRs
+
+| ADR | Title | Relevance |
+|-----|-------|-----------|
+| [ADR-046](../adr/ADR-046-tui-reference-and-command-system.md) | TUI Reference and Command System | @ references, / commands, ! shell |
+| [ADR-020](../adr/ADR-020-session-model.md) | Session Model | Session persistence and management |
+
+---
+
+*Documentation for v3.7.0 — IN PROGRESS. Features described here reflect the planned scope
+as of 2026-04-15. Some features may be adjusted as implementation progresses.*
+
+*Generated by [AUTO-DOCS-5] — CleverAgents Documentation Bot*
diff --git a/docs/tui/sidebar-and-personas.md b/docs/tui/sidebar-and-personas.md
new file mode 100644
index 000000000..f533b4b15
--- /dev/null
+++ b/docs/tui/sidebar-and-personas.md
@@ -0,0 +1,158 @@
+# TUI: Sidebar States & Persona System (v3.7.0)
+
+> **Milestone:** v3.7.0 — M8: TUI Implementation
+> **Parent:** [TUI Overview](index.md)
+
+---
+
+## Sidebar States
+
+The sidebar cycles through three states via `shift+tab`:
+
+| State | Layout | Input Focus | Content |
+|-------|--------|-------------|---------|
+| **Hidden** | Sidebar has `display: none`; conversation takes full width | Prompt retains focus | No sidebar content visible |
+| **Visible** | Sidebar docked right, 32-40 chars wide | Prompt retains focus; `ctrl+b` focuses sidebar | Plans and Projects panels in collapsible containers; read-only status |
+| **Fullscreen** | Sidebar covers entire screen | Sidebar takes input focus | Extended plan/project details, persona management, selection mode |
+
+State transitions:
+
+```
+Hidden --shift+tab--> Visible --shift+tab--> Fullscreen
+  ^                                              |
+  +-------------- escape (x1-2) ----------------+
+```
+
+In fullscreen mode, `escape` returns to visible; another `escape` returns to hidden. This
+cascading escape behavior is consistent across all TUI states — pressing `escape` always
+moves toward the main screen.
+
+### Plans Panel
+
+The Plans panel (visible and fullscreen sidebar) shows:
+
+- Active plans with their current phase and state
+- Phase indicator: `Strategize` / `Execute` / `Apply` / `Complete` / `Error`
+- State badge: `Running` / `Paused` / `Waiting` / `Complete`
+- Decision depth counter (number of decisions made)
+- Real-time updates via A2A event subscription
+
+### Projects Panel
+
+The Projects panel shows:
+
+- All registered projects with their resource counts
+- Scoped projects (from the active persona) highlighted with a pin indicator
+- Recently accessed projects sorted to the top
+
+---
+
+## Persona System
+
+Personas are TUI-only abstractions that bundle an actor, its configuration, project/plan
+scope, and argument presets into a single switchable unit. They are defined in ADR-045.
+
+### What a Persona Contains
+
+```yaml
+# ~/.config/cleveragents/personas/feature-dev.yaml
+name: "feature-dev"
+description: "Feature development with Claude on main projects"
+actor: "anthropic/claude-4-sonnet"
+color: "$primary"
+
+base_arguments:
+  thinking_effort: "medium"
+  temperature: 0.7
+  max_tokens: 16384
+
+scoped_projects:
+  - "local/cleveragents"
+  - "local/api-service"
+
+scoped_plans: []
+
+argument_presets:
+  - name: "default"
+    display: "default"
+    overrides: {}
+
+  - name: "think-more"
+    display: "think: high"
+    overrides:
+      thinking_effort: "high"
+
+  - name: "quick"
+    display: "quick"
+    overrides:
+      thinking_effort: "low"
+      max_tokens: 4096
+
+cycle_order: 1
+```
+
+### Switching Personas
+
+- **`tab`** — cycle forward through personas in the configured cycle list
+- **`/persona:set <name>`** — switch to a specific persona by name
+- **Fullscreen sidebar** — select from the full persona list
+
+When you switch personas, the PersonaBar updates immediately and subsequent prompts use the
+new persona's actor and scope. Previous conversation history is retained.
+
+### Argument Presets
+
+**`ctrl+tab`** cycles through the current persona's argument presets:
+
+```
+default --> think: high --> think: max --> quick --> default --> ...
+```
+
+The active preset's display name appears in the PersonaBar. Effective arguments are computed
+as `merge(base_arguments, active_preset.overrides)`.
+
+### PersonaBar
+
+The PersonaBar sits below the prompt input and is always visible:
+
+```
+  feature-dev | anthropic/claude-4-sonnet | think: high | 2 projects | $0.12
+```
+
+| Segment | Updates When |
+|---------|-------------|
+| Persona name | `tab` cycle |
+| Actor name | `tab` cycle |
+| Preset label | `ctrl+tab` cycle |
+| Scope indicator | Persona change or `/scope:add/remove` |
+| Session cost | After each actor response |
+
+### Managing Personas
+
+```bash
+/persona:list              # List all personas
+/persona:create            # Open PersonaEditorModal
+/persona:edit feature-dev  # Edit an existing persona
+/persona:delete old-persona # Delete a persona
+/persona:export feature-dev # Export to YAML file
+/persona:import ./shared.yaml # Import from YAML file
+```
+
+Personas are stored as YAML files in `~/.config/cleveragents/personas/` and are portable
+between machines via export/import.
+
+---
+
+## Related ADRs
+
+| ADR | Title | Relevance |
+|-----|-------|-----------|
+| [ADR-044](../adr/ADR-044-tui-architecture-and-framework.md) | TUI Architecture and Framework | Core TUI design decisions |
+| [ADR-045](../adr/ADR-045-tui-persona-system.md) | TUI Persona System | Persona data model and lifecycle |
+
+---
+
+*Documentation for v3.7.0 — IN PROGRESS. Features described here reflect the planned scope
+as of 2026-04-15. Some features may be adjusted as implementation progresses.*
+
+*Generated by [AUTO-DOCS-5] — CleverAgents Documentation Bot*
diff --git a/mkdocs.yml b/mkdocs.yml
index 48a98aa71..bc1a2d3c2 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -43,6 +43,16 @@ nav:
     - Custom Sandbox Strategy: development/custom_sandbox_strategy.md
     - Documentation Writer: development/docs-writer.md
   - Implementation Timeline: timeline.md
+  - Advanced Concepts (v3.6.0):
+    - Overview & Context Strategies: advanced-concepts/index.md
+    - Resource Types & A2A Rename: advanced-concepts/resource-types.md
+    - Container Tools, Scope Chain, Budgets & Safety: advanced-concepts/container-tools.md
+    - E2E Tests, Code Review & Plugins: advanced-concepts/e2e-tests-and-plugins.md
+  - TUI Guide (v3.7.0):
+    - Overview & Main Screen: tui/index.md
+    - Sidebar States & Persona System: tui/sidebar-and-personas.md
+    - Reference/Command Input & Sessions: tui/input-and-sessions.md
+    - Configuration, Key Bindings & Integration: tui/configuration-and-integration.md
   - FAQ: faq.md
   - Reference: reference/
   - Architecture Decision Records (ADRs):