update stale agent, readme file and smart defaults

Author: jier

AGENTS.md

@@ -34,10 +34,10 @@ npx --yes jscpd docsible --pattern "**/*.py"
 
 `jscpd` is informational: its current baseline is 21 clones and 1.30% duplicated lines, not a zero-threshold gate. Update the baseline only after reviewing intentional duplication.
 
-## Verified Baseline (2026-08-27)
+## Verified Baseline (2026-09-13)
 
-- `uv run pytest`: 1156 passed, 10 warnings.
-- `uv run ruff check .`: 47 findings.
-- `uv run mypy docsible`: 3 errors in 2 files.
+- `uv run pytest` passes with 1215 tests (3 xpassed).
+- `uv run ruff check .` reports no findings.
+- `uv run mypy docsible` reports no issues.
 
 Treat these results as a starting point, not permission to introduce additional failures.

README.md

@@ -62,6 +62,10 @@ Project home: https://github.com/jier/docsible
 - Preset system — four built-in presets covering personal, team, enterprise, and consulting use cases
 - Suppression system — silence false-positive recommendations with audit trail and optional expiry
 - Interactive setup wizard (`docsible init`) with optional CI/CD workflow generation
+- Source-backed `RoleExecutionGraph` — typed include/import, cross-role, notification and variable edges, each with static / dynamic / unknown resolution and a source location
+- README "Execution Routes" + "Execution Graph Summary" — role entry point, statically vs dynamically reachable and unreachable files, and dynamic boundaries, instead of filesystem-order phases
+- Collections get per-role documentation plus a collection-level complexity overview and a role index sorted by complexity
+- Machine-readable `--output-format json` exposes the complexity metrics and the serialized execution graph for CI and downstream renderers
 
 ## Installation
 
@@ -125,7 +129,8 @@ docsible scan collection . --fail-on warning --output-format json
 
 ### `--output-format json`
 
-Use `--output-format json` with `docsible analyze role` for machine-readable output:
+Use `--output-format json` with `docsible analyze role` (also supported by
+`validate role` and `document role`) for machine-readable output:
 
 ```bash
 docsible analyze role --role . --output-format json
@@ -137,13 +142,26 @@ Output schema:
 {
   "role": "my-role",
   "findings": [
-    { "severity": "WARNING", "message": "No example playbook found", "category": "documentation" }
+    { "severity": "warning", "message": "No example playbook found", "category": "documentation" }
   ],
-  "summary": { "total": 3, "critical": 0, "warning": 2, "info": 1 },
-  "truncated": false
+  "summary": { "total": 3, "shown": 3, "critical": 0, "warning": 2, "info": 1 },
+  "truncated": false,
+  "complexity": {
+    "total_tasks": 3, "task_files": 1, "handlers": 0,
+    "task_includes": 0, "conditional_tasks": 1, "error_handlers": 0,
+    "static_reachable_task_files": 1, "dynamically_reachable_task_files": 0,
+    "unreachable_task_files": 0, "dynamic_boundaries": 0, "loop_tasks": 0,
+    "notification_edges": 0, "collection_dependencies": 0
+  },
+  "execution_graph": { "role_id": "role:my-role", "nodes": ["..."], "edges": ["..."] }
 }
 ```
 
+`complexity` is derived from the `RoleExecutionGraph` (the single source of
+truth for boundary, loop, notification and reachability counts), and
+`execution_graph` is the full serialized node/edge model. `truncated` applies
+to `findings`; the graph itself is never truncated.
+
 ### Ready-to-use CI examples
 
 See [`examples/ci_pipeline/`](examples/ci_pipeline/) for complete, ready-to-use configurations:

tests/defaults/test_smart_defaults_cli.py

@@ -49,13 +49,13 @@ def test_complex_role_gets_graphs_by_default(self, complex_role_fixture, tmp_pat
         # Complex role should have visualization enabled (smart default)
         content = output_file.read_text()
 
-        # Complex roles may use either Mermaid diagrams OR execution phases
+        # Complex roles may use either Mermaid diagrams OR execution routes
         has_mermaid = "```mermaid" in content
-        has_execution_phases = "Execution Phases" in content
+        has_execution_routes = "Execution Routes" in content
         has_architecture = "Architecture Overview" in content
 
-        assert has_mermaid or (has_execution_phases and has_architecture), \
-            f"Complex role should have visualization (mermaid: {has_mermaid}, phases: {has_execution_phases}, arch: {has_architecture})"
+        assert has_mermaid or (has_execution_routes and has_architecture), \
+            f"Complex role should have visualization (mermaid: {has_mermaid}, routes: {has_execution_routes}, arch: {has_architecture})"
 
     def test_user_override_respected(self, simple_role, tmp_path):
         """User --graph flag should override smart default."""