docs: updated the graph agent diagrams to use mermaid diagrams for more easily readable diagramming in their READMEs

assets/agents/coder/README.md

@@ -10,22 +10,30 @@ implement-fix loop enforced as graph edges rather than prose.
 
 ## Workflow
 
-```
+```mermaid
-analyze_request (llm + output_schema)   plan + complexity extraction
+flowchart TD
-        ↓
+    resolve_paths{"resolve_paths<br/>script"} --> analyze_request
-route_complexity (script)               opt-out approval gate (complexity ≥ 7)
+    analyze_request["analyze_request<br/>llm + output_schema"] --> route_complexity
-        ↓
+    route_complexity{"route_complexity<br/>script"}
-gate_approval (approval, optional)
+    route_complexity -->|"complexity ≥ 7"| gate_approval
-        ↓
+    route_complexity -->|else| implement
-implement (llm + fs tools)              actual file edits
+    gate_approval{{"gate_approval<br/>approval"}}
-        ↓
+    gate_approval -->|yes| implement
-verify_build (script)
+    gate_approval -->|no| end_rejected
-        ↓
+    implement["implement<br/>llm + fs tools"] --> verify_build
-verify_tests (script)
+    verify_build{"verify_build<br/>script"}
-        ↓
+    verify_build -->|pass| verify_tests
-fix_loop_gate (script)                  back-edge to implement (bounded)
+    verify_build -->|fail| fix_loop_gate
-        ↓
+    verify_tests{"verify_tests<br/>script"}
-end_success / end_rejected / end_failure
+    verify_tests -->|pass| end_success
+    verify_tests -->|fail| fix_loop_gate
+    fix_loop_gate{"fix_loop_gate<br/>script"}
+    fix_loop_gate -->|"budget left"| implement
+    fix_loop_gate -->|"budget spent"| end_failure
+
+    end_success(["end_success<br/>CODER_COMPLETE"])
+    end_rejected(["end_rejected<br/>CODER_REJECTED"])
+    end_failure(["end_failure<br/>CODER_FAILED"])
 ```
 
 End nodes emit one of three sentinel outcomes for the caller:

assets/agents/deep-research/README.md

@@ -22,28 +22,43 @@ agent, this is the file to read alongside the
 
 ## Workflow
 
-17 nodes. `->` is the static route; a script node can also route
+17 nodes. Solid arrows are static `next` / `routes` edges declared in
-dynamically via `_next`. The `▶▶` line is a parallel super-step —
+`graph.yaml`; script nodes can also route dynamically via `_next` (shown as
-those branches run concurrently:
+labeled branches out of the diamond). Dotted arrows show `map` fan-out — the
+`research_each_question` node spawns one `research_one_question` branch per
+sub-question and joins them before continuing.
 
-```
+```mermaid
-parse_request (script)              -> bootstrap_research   (or -> ask_topic if no topic)
+flowchart TD
-ask_topic (input)                   -> bootstrap_research
+    parse_request{"parse_request<br/>script"}
-bootstrap_research (script)         -> [plan, knowledge_lookup]   ▶▶ parallel
+    parse_request -->|"topic given"| bootstrap_research
-plan (llm + output_schema)          -> research_each_question
+    parse_request -->|"no topic"| ask_topic
-knowledge_lookup (rag)              -> research_each_question
+    ask_topic[/"ask_topic<br/>input"/] --> bootstrap_research
-research_each_question (map)        -> combine_findings    (spawns one branch per question)
+    bootstrap_research{"bootstrap_research<br/>script"}
-  └─ research_one_question (llm)    (atomic; runs N×, joins at map)
+    bootstrap_research --> plan
-combine_findings (script)           -> vet_sources
+    bootstrap_research --> knowledge_lookup
-vet_sources (llm + custom tool)     -> critique
+    plan["plan<br/>llm + output_schema"] --> research_each_question
-critique (llm)                      -> reflexion_gate
+    knowledge_lookup[("knowledge_lookup<br/>rag")] --> research_each_question
-reflexion_gate (script)             -> synthesize  (or -> research_each_question: reflexion loop)
+    research_each_question[\research_each_question<br/>map/]
-synthesize (agent: report-writer)   -> verify_sources
+    research_each_question -. "spawns × N" .-> research_one_question["research_one_question<br/>llm + web tools"]
-verify_sources (script)             -> approve
+    research_each_question --> combine_findings
-approve (approval)                  -> end_accepted          ("accept")
+    combine_findings{"combine_findings<br/>script"} --> vet_sources
-                                    -> end_rejected          ("reject")
+    vet_sources["vet_sources<br/>llm + classify_source"] --> critique
-                                    -> incorporate_feedback   (any free-form answer)
+    critique["critique<br/>llm"] --> reflexion_gate
-incorporate_feedback (script)       -> research_each_question (the human-feedback loop)
+    reflexion_gate{"reflexion_gate<br/>script"}
+    reflexion_gate -->|"PASS"| synthesize
+    reflexion_gate -->|"REVISE (budget left)"| research_each_question
+    reflexion_gate -->|"REVISE (budget spent)"| synthesize
+    synthesize[["synthesize<br/>agent → report-writer"]] --> verify_sources
+    verify_sources{"verify_sources<br/>script"} --> approve
+    approve{{"approve<br/>approval"}}
+    approve -->|"accept"| end_accepted
+    approve -->|"reject"| end_rejected
+    approve -->|"other (free-form feedback)"| incorporate_feedback
+    incorporate_feedback{"incorporate_feedback<br/>script"} --> research_each_question
+
+    end_accepted(["end_accepted<br/>report"])
+    end_rejected(["end_rejected"])
 ```
 
 ### Node-type breakdown

assets/agents/librarian/README.md

@@ -10,13 +10,25 @@ library, API, or framework is involved.
 
 ## Workflow
 
+```mermaid
+flowchart TD
+    triage["triage<br/>llm"] --> search
+    triage --> search_oss
+    search["search<br/>llm + ddg-search MCP"] --> synthesize
+    search_oss["search_oss<br/>llm + personal-github MCP"] --> synthesize
+    synthesize["synthesize<br/>llm + fetch_url_via_curl"] --> final_format
+    final_format{"final_format<br/>script"} --> end_success
+
+    end_success(["end_success<br/>LIBRARIAN_COMPLETE"])
+    end_failure(["end_failure<br/>LIBRARIAN_FAILED"])
 ```
-search (llm + ddg-search)         identify 3-5 authoritative sources
+
-   ↓
+`triage` parses the prompt into language / doc-domain / query hints, then fans
-synthesize (llm + fetch_url_via_curl)   fetch, extract, cite, synthesize
+out to `search` (authoritative docs via `ddg-search`) and `search_oss`
-   ↓
+(production OSS examples via the `personal-github` MCP) in parallel. Both feed
-end_success / end_failure         LIBRARIAN_COMPLETE / LIBRARIAN_FAILED
+into `synthesize`, which fetches each URL and produces a citation-backed
-```
+findings block. `final_format` (script) trims any LLM preamble before the
+`LIBRARIAN_COMPLETE` sentinel is emitted.
 
 Iteration 1 (this) is the happy-path MVP: single search pass, single synthesis
 pass, no quality-check loop. Future iterations may add:

assets/agents/step-runner/README.md

@@ -18,32 +18,61 @@ plans/
 
 ## Workflow
 
-```
+```mermaid
-resolve_step (script)         locate plan + previous handoff, check depends_on,
+flowchart TD
-        ↓                     mark plan in-progress   [→ gate_blocked if deps unsatisfied]
+    resolve_step{"resolve_step<br/>script"}
-orient (llm, read-only)       merge handoff directives + staleness-check the plan
+    resolve_step -->|"deps satisfied"| orient
-        ↓
+    resolve_step -->|"deps unsatisfied"| gate_blocked
-route_staleness (script)      major deviation → gate_deviation (approval)
+    gate_blocked{{"gate_blocked<br/>approval"}}
-        ↓
+    gate_blocked -->|"yes"| orient
-implement (agent → coder)     coder runs its own build/test/self-review fix-loop
+    gate_blocked -->|"no"| end_blocked
-        ↓
+    orient["orient<br/>llm, read-only"] --> route_staleness
-route_coder_result (script)   COMPLETE → verify | REJECTED / FAILED → end
+    route_staleness{"route_staleness<br/>script"}
-        ↓
+    route_staleness -->|"major deviation"| gate_deviation
-verify_format_lint (script)   format BEFORE evidence, then lint
+    route_staleness -->|"else"| implement
-verify_build (script)         step-level build/typecheck
+    gate_deviation{{"gate_deviation<br/>approval"}}
-verify_tests (script)         FULL test suite
+    gate_deviation -->|"proceed"| implement
-        ↓                     [failures → fix_loop_gate, back-edge to implement]
+    gate_deviation -->|"abort"| end_rejected
-edge_case_sweep (llm)         missed edge cases; annotate downstream plans
+    gate_deviation -->|"other (user guidance)"| implement
-        ↓                     (Edge cases sections ONLY - scope changes become proposals)
+    implement[["implement<br/>agent → coder"]] --> route_coder_result
-route_sweep (script)          5+ files or architectural boundary → independent_review
+    route_coder_result{"route_coder_result<br/>script"}
-independent_review (agent)    code-reviewer; 🔴 findings loop back to implement (bounded)
+    route_coder_result -->|"CODER_COMPLETE"| verify_format_lint
-        ↓
+    route_coder_result -->|"REJECTED / FAILED"| end_failure
-write_handoff (llm)           evidence-backed handoff per handoff-protocol + NOTES.md
+    verify_format_lint{"verify_format_lint<br/>script"}
-check_handoff (script)        deterministic schema gate; marks plan status complete
+    verify_format_lint -->|"pass"| verify_build
-        ↓
+    verify_format_lint -->|"fail"| fix_loop_gate
-gate_user_review (approval)   HARD STOP - approve, or send revision comments
+    verify_build{"verify_build<br/>script"}
-        ↓                     (revisions loop through implement → verify → handoff again)
+    verify_build -->|"pass"| verify_tests
-end_success / end_blocked / end_rejected / end_failure
+    verify_build -->|"fail"| fix_loop_gate
+    verify_tests{"verify_tests<br/>script"}
+    verify_tests -->|"pass"| edge_case_sweep
+    verify_tests -->|"fail"| fix_loop_gate
+    fix_loop_gate{"fix_loop_gate<br/>script"}
+    fix_loop_gate -->|"budget left"| implement
+    fix_loop_gate -->|"budget spent"| end_failure
+    edge_case_sweep["edge_case_sweep<br/>llm"] --> route_sweep
+    route_sweep{"route_sweep<br/>script"}
+    route_sweep -->|"5+ files or boundary"| independent_review
+    route_sweep -->|"else"| write_handoff
+    independent_review[["independent_review<br/>agent → code-reviewer"]] --> route_review
+    route_review{"route_review<br/>script"}
+    route_review -->|"🔴 critical findings"| implement
+    route_review -->|"else"| write_handoff
+    write_handoff["write_handoff<br/>llm"] --> check_handoff
+    check_handoff{"check_handoff<br/>script"}
+    check_handoff -->|"schema valid"| gate_user_review
+    check_handoff -->|"one retry"| write_handoff
+    gate_user_review{{"gate_user_review<br/>approval"}}
+    gate_user_review -->|"approve"| end_success
+    gate_user_review -->|"revise"| get_revision
+    gate_user_review -->|"other (comments)"| revise_from_choice
+    get_revision[/"get_revision<br/>input"/] --> implement
+    revise_from_choice{"revise_from_choice<br/>script"} --> implement
+
+    end_success(["end_success<br/>STEP_COMPLETE"])
+    end_blocked(["end_blocked<br/>STEP_BLOCKED"])
+    end_rejected(["end_rejected<br/>STEP_REJECTED"])
+    end_failure(["end_failure<br/>STEP_FAILED"])
 ```
 
 End nodes emit sentinel outcomes for the caller: