docs(voyage): add Mermaid architecture diagrams + primitives decision-matrix

Replace the ASCII pipeline figure in README with two Mermaid diagrams —
the full pipeline (all 7 commands + 7 handover contracts) and agents per
phase — and add a "Primitives per step" decision-matrix to
docs/architecture.md, pointed to from README.

Corrects prior prose: /trekexecute spawns no sub-agents; Phase 5 swarm is
6 fixed + 2 conditional; cross-cutting = 7 hook scripts incl. Stop->OTEL.

Both diagrams validated with mermaid-cli 11.12.0 (render clean);
node --test 756/0 fail (doc-consistency pins intact).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017AkavgP4v6QT1x8aZtRa9S

README.md

@@ -604,24 +604,65 @@ Claude never pre-generates suggestions in this flow.
 
 ## The full pipeline
 
+Six commands, one pipeline — each step hands a structured artifact to the next (the seven [handover contracts](docs/HANDOVER-CONTRACTS.md)):
+
+```mermaid
+flowchart LR
+    B["/trekbrief"]
+    R["/trekresearch"]
+    P["/trekplan"]
+    X["/trekexecute"]
+    V["/trekreview"]
+    C["/trekcontinue"]
+    A["architect plugin<br/>(opt-in, not bundled)"]
+
+    B -->|"H1 · brief.md · PUBLIC"| R
+    R -->|"H2 · research/NN-*.md"| P
+    A -.->|"H3 · architecture/overview.md"| P
+    P -->|"H4 · plan.md"| X
+    X -.->|"H5 · progress.json (--resume)"| X
+    X -->|"H7 · .session-state.local.json"| C
+    C -->|"next session"| X
+    X -.->|"git diff"| V
+    V -->|"H6 · review.md (loop back)"| P
 ```
- /trekbrief   /trekresearch    /trekplan         /trekexecute
- ┌──────────────┐    ┌───────────────────┐   ┌─────────────────────┐  ┌─────────────────────┐
- │ Interview    │    │ 5 local agents    │   │ brief-reviewer      │  │ Parse plan          │
- │ ↓            │    │ 4 external agents │   │ ↓                   │  │ ↓                   │
- │ Intent/Goal  │    │ + Gemini bridge   │   │ 6-8 exploration     │  │ Detect sessions     │
- │ ↓            │    │ ↓                 │   │ agents (parallel)   │  │ ↓                   │
- │ Research     │    │ Triangulation     │   │ ↓                   │  │ Execute steps       │
- │ topics       │    │ ↓                 │   │ Opus planning       │  │ (verify + manifest  │
- │ ↓            │ → brief → → → → → → → → → → → ↓                   │→ │  + checkpoint)      │
- │ brief.md     │    │ research/*.md     │   │ plan-critic +       │  │ ↓                   │
- └──────────────┘    └───────────────────┘   │ scope-guardian      │  │ Phase 7.5 manifest  │
-                                             │ ↓                   │  │ audit + 7.6 recovery│
-                                             │ plan.md             │  │ ↓                   │
-                                             └─────────────────────┘  │ progress.json + done│
-                                                                      └─────────────────────┘
+
+Solid arrows are the forward pipeline; dashed are conditional/internal edges (`--resume`, the git-diff that feeds review, the opt-in architect input). **H1 (`brief.md`) is the only PUBLIC contract** — the single integration point for any upstream brief producer.
+
+### Agents per phase
+
+Every command orchestrates its agents inline from the main context (all sub-agents are `model: opus`-pinned). `/trekexecute` is the exception — it spawns **no** sub-agents.
+
+```mermaid
+flowchart TB
+    subgraph BR["/trekbrief"]
+        BRG["brief-reviewer (gate · ≤3 iter)"]
+    end
+    subgraph RES["/trekresearch · Phase 4 — parallel"]
+        RL["LOCAL: architecture-mapper · dependency-tracer<br/>task-finder · git-historian · convention-scanner*"]
+        RE["EXTERNAL: docs-researcher · community-researcher<br/>security-researcher* · contrarian-researcher* · gemini-bridge*"]
+    end
+    subgraph PL["/trekplan"]
+        PLG["Phase 4b · brief-reviewer (gate)"]
+        PLS["Phase 5 — parallel (6 + 2*): architecture-mapper · dependency-tracer<br/>risk-assessor · task-finder · test-strategist · git-historian<br/>convention-scanner* · research-scout*"]
+        PLC["Phase 9 — parallel · plan-critic · scope-guardian"]
+        PLG --> PLS --> PLC
+    end
+    subgraph EX["/trekexecute · no sub-agents"]
+        EXI["inline step-loop + claude -p worktrees<br/>+ Phase 7.5/7.6 manifest audit (deterministic)"]
+    end
+    subgraph RV["/trekreview"]
+        RVR["Phase 5 — parallel · code-correctness-reviewer · brief-conformance-reviewer*"]
+        RVJ["Phase 6 · review-coordinator (Judge)"]
+        RVR --> RVJ
+    end
+    BR --> RES --> PL --> EX --> RV
 ```
 
+`* = conditional`: convention-scanner / test-strategist on medium+ codebases (50+ files); research-scout for unknown external tech; security-/contrarian-researcher + gemini-bridge when a leading recommendation forms (or always at `effort=high`); brief-conformance-reviewer skipped under `--quick`.
+
+> **Which Claude Code primitive each phase uses — and the alternatives considered (Workflow substrate, delegated orchestrator, dormant synthesis-agent)** → see [docs/architecture.md §Primitives per step](docs/architecture.md#primitives-per-step-decision-matrix).
+
 All artifacts live under `.claude/projects/{YYYY-MM-DD}-{slug}/`.
 
 An opt-in upstream architect plugin (not bundled) can insert a Claude-Code-specific architecture-matching step between research and plan — `/trekplan` auto-discovers its `architecture/overview.md` output as priors when present.