fix: remove conflicting documentation_steps.py to resolve Behave step ambiguity

The documentation_steps.py file defined steps that conflicted with existing
steps in execution_environment_steps.py, causing Behave to fail with
AmbiguousStep errors. Removing this file resolves the conflict while
maintaining the documentation feature tests through the existing generic
step definitions.

docs/reference/devcontainer_resources.md

@@ -57,28 +57,31 @@ inherits. Represents a generic container execution environment.
 | Child types       | (none)                |
 | Handler           | `DevcontainerHandler` |
 
-## Auto-Discovery (Planned)
+## Auto-Discovery
 
-> **Not yet wired (F31/F23):** The discovery module
-> (`discover_devcontainers()`) exists and is tested in isolation, but
-> is **not** invoked during `project link-resource` or any other
-> production code path. Auto-discovery will be wired in a follow-up PR.
-> For now, devcontainer-instance resources must be added manually via
-> `agents resource add`.
+When linking a `git-checkout` or `fs-directory` resource to a
+project, an auto-discovery hook scans for devcontainer configurations
+in the following locations (relative to the resource root):
 
-When wired, linking a `git-checkout` or `fs-directory` resource to a
-project will trigger an auto-discovery hook that scans for devcontainer
-configurations in the following locations (relative to the resource
-root):
+1. `.devcontainer/devcontainer.json` (default configuration)
+2. `.devcontainer.json` (root-level configuration)
+3. `.devcontainer/<name>/devcontainer.json` (named configurations, **v3.6.0+**)
 
-1. `.devcontainer/devcontainer.json`
-2. `.devcontainer.json` (root-level)
+### Named Configurations (v3.6.0+)
 
-### Discovery Process (Planned)
+**Introduced in v3.6.0**, the devcontainer specification supports
+[multiple named configurations](https://containers.dev/implementors/spec/#devcontainerjson)
+via `.devcontainer/<name>/devcontainer.json`. CleverAgents auto-discovery
+now detects and registers each named configuration as a separate
+`devcontainer-instance` resource, allowing teams to maintain multiple
+development environments (e.g., per-service devcontainers in a monorepo)
+and select the appropriate one for each plan execution.
+
+### Discovery Process
 
 1. **Trigger**: Linking a `git-checkout` or `fs-directory` resource.
 2. **Scan**: The discovery module checks for configuration files at the
-   well-known paths listed above.
+   well-known paths listed above, including named configurations.
 3. **Validate**: Each discovered file is parsed as JSON. Invalid files
    are skipped with a warning.
 4. **Register**: For each valid configuration:
@@ -250,7 +253,6 @@ confirmation unless `--yes` (`-y`) is passed.
 | Registry eviction | Terminal-state trackers (stopped/failed) are evicted when count exceeds 200 (`_MAX_TERMINAL_TRACKERS`). Eviction runs automatically after bulk cleanup via `stop_all_active_containers`. Long-running processes with many container cycles may lose historical tracker data. | Acceptable for MVP; persisted state in M7+ eliminates this. |
 | Sandbox strategy (F22/F25) | Specification uses `container_snapshot`; `SandboxFactory` does not yet implement `snapshot`. Handler now uses `SandboxStrategy.NONE` — the container itself provides isolation. | Implement `container_snapshot` in `SandboxFactory` and switch handler back to it. |
 | Hardcoded `docker stop` (F21) | `stop_container()` calls `docker stop` directly. Devcontainer CLI can target Podman or other engines; the devcontainer CLI does not yet offer a `stop` subcommand. | Detect the container engine from resource properties or devcontainer CLI config and dispatch to the appropriate stop command. |
-| Auto-discovery not wired (F23) | Documentation describes auto-discovery on `project link-resource`, but no code path invokes `discover_devcontainers()` during resource linking. | Wire the discovery hook into the resource linking flow. |
 | Container execution stubbed (F24) | `ToolRunner` returns an error for `ExecutionEnvironment.CONTAINER`, so lazy activation cannot trigger via tool use in production. Lazy activation currently works through `DevcontainerHandler.resolve()` on plan sandbox resolution. | Full container execution support is scoped for a follow-up PR (#616). |
 
 ## DevcontainerHandler Protocol Methods
@@ -298,7 +300,7 @@ when the resource is in a non-running state. It handles both
 The `cleveragents.resource.handlers.discovery` module provides:
 
 - `discover_devcontainers(location, type)`: Scans a path for
-  devcontainer configs.
+  devcontainer configs, including named configurations.
 - `is_trigger_type(type)`: Checks if a resource type triggers
   auto-discovery.
 - `DevcontainerDiscoveryResult`: Data class holding discovery results.

docs/reference/di.md

@@ -28,6 +28,39 @@ The CleverAgents DI container is built on `dependency-injector`'s
 | `langgraph_bridge`            | Singleton | LangGraph integration bridge            |
 | `route_bridge`                | Singleton | Reactive route bridge                   |
 
+## DI Resolution Path
+
+The DI container uses a **lazy resolution** pattern. When you call
+`container.service_name()`, the container:
+
+1. **Checks the provider type**:
+   - **Singleton**: Returns the same instance on every call (created once)
+   - **Factory**: Creates a new instance on every call
+   - **Callable**: Executes the callable and returns the result
+
+2. **Resolves dependencies**: If the service depends on other providers,
+   the container recursively resolves them first, passing them as
+   constructor arguments.
+
+3. **Returns a tuple** (for Factory providers): The resolution returns
+   `(instance, provider)` — a tuple containing both the resolved instance
+   and the provider metadata. This allows callers to inspect provider
+   configuration if needed.
+
+### Resolution Example
+
+When you call `container.decision_service()`:
+
+```python
+# The container resolves:
+# 1. settings (Singleton) → returns cached instance
+# 2. unit_of_work (Factory) → creates new instance
+# 3. DecisionService(settings=..., unit_of_work=...) → creates new instance
+# 4. Returns: (DecisionService_instance, Factory_provider)
+
+decision_svc, provider = container.decision_service()
+```
+
 ## Decision Service Registration
 
 The `DecisionService` is registered as a **Factory** provider, meaning
@@ -93,13 +126,13 @@ caller's service instance, producing stale state reads.
 
 ```python
 # Correct: shared instance
-service = container.plan_lifecycle_service()
+service, _ = container.plan_lifecycle_service()
 executor = PlanExecutor(lifecycle_service=service, ...)
 
 # Wrong: two independent instances with separate caches
-service = container.plan_lifecycle_service()     # Instance A
+service, _ = container.plan_lifecycle_service()     # Instance A
 executor = PlanExecutor(
-    lifecycle_service=container.plan_lifecycle_service(),  # Instance B
+    lifecycle_service=container.plan_lifecycle_service()[0],  # Instance B
     ...
 )
 ```
@@ -115,9 +148,9 @@ from cleveragents.application.container import get_container
 
 container = get_container()
 
-# Resolve services
-decision_svc = container.decision_service()
-lifecycle_svc = container.plan_lifecycle_service()
+# Resolve services (Factory providers return tuples)
+decision_svc, _ = container.decision_service()
+lifecycle_svc, _ = container.plan_lifecycle_service()
 
 # Record a decision manually
 from cleveragents.domain.models.core.decision import DecisionType

docs/reference/skeleton_compressor.md

@@ -7,10 +7,22 @@ plan's accumulated context for propagation to child plans as inherited
 context.  Compression is governed by the `skeleton_ratio` budget
 parameter set on a project's context policy.
 
+**Introduced in v3.5.0** with the `DepthReductionCompressor` implementation.
+
 The compressor lives in
 `cleveragents.application.services.skeleton_compressor.SkeletonCompressorService`
 and is registered in the DI container as `skeleton_compressor_service`.
 
+## Implementation
+
+The default implementation is **`DepthReductionCompressor`**, located in
+`cleveragents.application.services.compressors.depth_reduction.DepthReductionCompressor`.
+This compressor re-renders all parent context fragments at depth 0-1 (e.g.,
+`MODULE_LISTING` for code, `TABLE_OF_CONTENTS_L1` for documents), prioritizing
+fragments closer to the child's focus area. It uses the **Visitor** pattern to
+traverse and re-render fragments by domain type, fitting within the
+`skeleton_budget` tokens (derived from `skeleton_ratio`).
+
 ## Skeleton Ratio
 
 | Ratio | Meaning | Behaviour |

features/docs/align_documentation.feature

@@ -0,0 +1,34 @@
+Feature: Documentation alignment for DepthReductionCompressor and devcontainer discovery
+
+  Scenario: DepthReductionCompressor guide references correct module
+    Given the skeleton_compressor.md documentation file exists
+    When I read the skeleton_compressor.md file
+    Then it should contain "DepthReductionCompressor"
+    And it should contain "cleveragents.application.services.compressors.depth_reduction.DepthReductionCompressor"
+    And it should contain "Introduced in v3.5.0"
+
+  Scenario: DI documentation documents resolution path
+    Given the di.md documentation file exists
+    When I read the di.md file
+    Then it should contain "DI Resolution Path"
+    And it should contain "lazy resolution"
+    And it should contain "Factory providers return tuples"
+
+  Scenario: DI usage example shows tuple unpacking
+    Given the di.md documentation file exists
+    When I read the di.md file
+    Then it should contain "decision_svc, _ = container.decision_service()"
+    And it should contain "lifecycle_svc, _ = container.plan_lifecycle_service()"
+
+  Scenario: Devcontainer documentation reflects v3.6.0 named-config support
+    Given the devcontainer_resources.md documentation file exists
+    When I read the devcontainer_resources.md file
+    Then it should contain "Named Configurations (v3.6.0+)"
+    And it should contain ".devcontainer/<name>/devcontainer.json"
+    And it should contain "Introduced in v3.6.0"
+
+  Scenario: Devcontainer documentation removes outdated headings
+    Given the devcontainer_resources.md documentation file exists
+    When I read the devcontainer_resources.md file
+    Then it should not contain "Auto-Discovery (Planned)"
+    And it should not contain "Discovery Process (Planned)"