@drafthq/draft 2.8.3 → 3.1.5

package/integrations/agents/AGENTS.md

@@ -31,7 +31,7 @@ When `draft/` exists in the project, always consider:
 | Command | Purpose |
 |---------|---------|
 | `draft` | Show overview and available commands |
-| `draft init` | Initialize project (run once) |
+| `draft init [refresh] [--graph-only] [--module-only]` | Initialize project context + code-graph memory; scope-aware (root or sub-module) |
 | `draft new-track <description>` | Create feature/bug track |
 | `draft implement` | Execute tasks from plan |
 | `draft review [--track <id>]` | Three-stage code review |
@@ -57,7 +57,6 @@ When `draft/` exists in the project, always consider:
 | `draft status` | Show progress overview |
 | `draft revert` | Git-aware rollback |
 | `draft change <description>` | Handle mid-track requirement changes |
-| `draft index [--init-missing]` | Aggregate monorepo service contexts |
 | `draft tour` | Interactive onboarding tour |
 | `draft impact` | Telemetry and analytics insights |
 | `draft assist-review` | Assist human reviewers with architectural risk audit |
@@ -124,7 +123,7 @@ Recognize and use these throughout plan.md:
 
 ## Init Command
 
-When user says "init draft" or "draft init [refresh]":
+When user says "init draft", "build the code graph", or "draft init [refresh] [--graph-only] [--module-only]":
 
 Initialize a Draft project for Context-Driven Development.
 
@@ -173,7 +172,7 @@ Initialize a Draft project for Context-Driven Development.
 
 ## Graph Fidelity & Diagram-First Priority (MANDATORY)
 
-The knowledge graph in `draft/graph/` (architecture.json with packages, languages, routes, and fan-in/out; hotspots.jsonl) is the **deterministic structural ground truth** for the system's actual architecture.
+The knowledge graph — served live by the local `codebase-memory-mcp` engine (packages, languages, routes, fan-in/out, hotspots) and queried via the `graph-*.sh` wrappers — is the **deterministic structural ground truth** for the system's actual architecture. Draft is engine-only: `draft/graph/` holds only the `schema.yaml` gate marker; all graph data comes from live queries.
 
 **You are running inside a powerful agentic coding environment** (Cursor, Claude Code, Copilot, Windsurf, etc.) that maintains its own rich, continuously updated index of the entire codebase. **Use that indexed knowledge aggressively** in addition to the explicit graph data and direct source reads. Your environment's index often captures higher-level intent, naming patterns, cross-file workflows, and architectural signals that the static graph may not fully express yet. Combine both sources:
 - Graph = authoritative modules, edges, public surfaces, hotspots, call relationships.
@@ -314,18 +313,24 @@ synced_to_commit: "a1b2c3d4e5f6789012345678901234567890abcd"
 
 Check for arguments:
 - `refresh`: Update existing context without full re-init
-- `index`: Route to `draft index`
+- `--graph-only`: Build/refresh only the code-graph knowledge memory (no markdown) — see the fast path below
+- `--module-only`: When run in a sub-module, do not touch the root graph (the module→root link is marked `pending`)
 - `discover`: Route to `draft discover`
 
+> `draft init` is the **single entry point** for building context — there is no separate `index` command. Init is scope-aware (root vs sub-module); see **Scope Detection** below.
+
 ### Route Explicit Modes Before Initialization
 
 If the user explicitly invoked a specialist mode, route directly:
 
-- `draft init index` → follow `draft index`
 - `draft init discover` → follow `draft discover`
 
 Explicit mode always wins. Do not perform standard initialization if an explicit mode is requested.
 
+### `--graph-only` Fast Path
+
+If `--graph-only` is present, run **Step 1.4** (scope-aware, root-first graph build via `graph-init.sh`) and **STOP** — generate no `architecture.md` or other markdown. This is the fast path to (re)build the whole-repo code-graph knowledge memory; in a sub-module it also ensures the root spine exists and writes the module→root link. This path is allowed even when `draft/` already exists (it refreshes the graph in place — no `draft.tmp/` staging, no overwrite prompt).
+
 ### Standard Init Check
 
 ```bash
@@ -357,16 +362,16 @@ mv draft.tmp/ draft/
 
 > **Forced re-init:** If `draft/` exists and the user explicitly requests a fresh init (not refresh), confirm with user before removing the existing `draft/` directory.
 
-### Monorepo Detection
+### Scope Detection (root vs sub-module)
+
+`draft init` is the single entry point and is **scope-aware** — it works the same whether run at the repository root or inside a sub-module. The root-first graph behavior is handled mechanically by `graph-init.sh` in Step 1.4; you do not detect the monorepo shape by hand.
 
-Check for monorepo indicators:
-- Multiple `package.json` / `go.mod` / `Cargo.toml` in child directories
-- `lerna.json`, `pnpm-workspace.yaml`, `nx.json`, or `turbo.json` at root
-- `packages/`, `apps/`, `services/` directories with independent manifests
+Resolve **ROOT** = nearest ancestor (above the current dir) containing `draft/` → else the git toplevel → else the current dir. Then:
 
-If monorepo detected:
-- Announce: "Detected monorepo structure. Consider using `draft init index` at root level to aggregate service context, or run `draft init` within individual service directories."
-- Ask user to confirm: initialize here (single service) or abort (use draft init index instead)
+- **Root init** (current dir IS root): the graph step builds the whole-repo spine. The generated markdown is a **sparse, high-level system map** that links *down* to each module's context — a large root must not carry deep per-module prose. (See "Root vs Module Markdown" below.)
+- **Module init** (current dir is BELOW root): the graph step ensures the root spine exists first (building it if missing), builds the module snapshot, and writes `draft/graph/root-link.json` (module→root). The generated markdown is the **detailed** module reference produced by the standard deep analysis in this skill.
+
+Use `--module-only` to skip touching the root (the link is marked `pending` and resolves when root init later runs). With no git and no ancestor `draft/`, init treats the current dir as root (module-local, no traversal).
 
 ### Migration Detection
 
@@ -599,20 +604,25 @@ If **Greenfield**: skip to Step 2 (Product Definition).
 
 **CRITICAL ORDERING**: Phase 0 (this step) MUST complete before writing any section of architecture.md. The graph provides: (a) exhaustive module list, (b) hotspot-ranked module priority, (c) authoritative proto API surface, (d) mermaid diagrams ready for slot injection, (e) codebase tier for .ai-context.md budget.
 
-### 1. Build the graph snapshot
+### 1. Build the graph (scope-aware, root-first)
 
-The knowledge-graph engine is `codebase-memory-mcp`, resolved by `scripts/tools/_lib.sh:find_memory_bin` (`DRAFT_MEMORY_BIN` > PATH > `~/.cache/draft/bin` > vendored `bin/<arch>/`). `draft install` fetches it (skip with `--no-graph`); install manually with `scripts/fetch-memory-engine.sh`. Set `DRAFT_MEMORY_DISABLE=1` to opt out.
+The knowledge-graph engine `codebase-memory-mcp` is Draft's **default** capability tier — deterministic call/dependency traversal beats grep/glob. It is normally already installed by `draft install`; `graph-init.sh` fetches it as a fallback when missing (blocking — download/index time is accepted, never gated on cost). Resolution: `scripts/tools/_lib.sh:find_memory_bin` (`DRAFT_MEMORY_BIN` > PATH > `~/.cache/draft/bin` > vendored `bin/<arch>/`). Set `DRAFT_MEMORY_DISABLE=1` to opt out.
 
-One command resolves the engine, indexes the repo, and writes the committed snapshot under `draft/graph/`:
+One command resolves ROOT, ensures the engine, builds the whole-repo spine, and — in a sub-module — builds the module snapshot and writes the `root-link.json` pointer:
 
 ```bash
-if scripts/tools/graph-snapshot.sh --repo .; then
-    echo "Graph snapshot written to draft/graph/ (schema.yaml, architecture.json, hotspots.jsonl, *.mermaid)."
+# Add --module-only to skip touching the root (link marked "pending").
+if scripts/tools/graph-init.sh --scope .; then
+    echo "Graph memory ready under draft/graph/ (the root spine is the structural source of truth)."
 else
-    echo "Graph engine unavailable — skipping automated graph analysis. Downstream skills degrade gracefully."
+    echo "Graph engine unavailable — proceeding with degraded manual discovery. Downstream skills degrade gracefully."
 fi
 ```
 
+- **Root init** writes `<root>/draft/graph/schema.yaml` — the committed gate marker. Draft is engine-only: graph data is served live by the engine, never committed.
+- **Module init** also writes `draft/graph/root-link.json` (module→root); follow `root_graph` for cross-module understanding. The root spine is rebuilt first so the link is live.
+- Only `schema.yaml` (and `root-link.json` in a module) is committed. The engine's `~/.cache` index is the live structural store — never commit it; it rebuilds deterministically from source.
+
 Optionally record which engine was selected (usage-report contract):
 
 ```bash
@@ -621,15 +631,20 @@ scripts/tools/verify-graph-binary.sh --repo . --json 2>/dev/null || true
 
 See `core/shared/graph-query.md` and `bin/README.md` for the query contract and engine resolution.
 
-If the snapshot succeeds, `draft/graph/` is populated and later steps consume the always-load artifacts + injection slots.
+If indexing succeeds, `draft/graph/schema.yaml` is written and later steps query the engine live for structure + populate the injection slots.
+
+### 2. If indexing succeeds, query the engine for structural context
 
-### 2. If graph build succeeds, load the always-load artifacts
+Pull the architecture view once and reuse it across phases:
 
-Read these files to get structural context for all subsequent phases:
-- `draft/graph/schema.yaml` — module count, file count, edge count, language stats per module
-- `draft/graph/architecture.json` — module list (`.packages`) with fan-in/out
-- `draft/graph/architecture.json` `.routes` — detected service endpoints
-- `draft/graph/hotspots.jsonl` — all complexity hotspots (files ranked by lines + fanIn * 50)
+```bash
+ARCH=$(scripts/tools/graph-arch.sh --repo .)
+```
+
+- `$ARCH | jq '.packages'` — module list with fan-in/out
+- `$ARCH | jq '.routes'` — detected service endpoints
+- `$ARCH | jq '.languages, .node_labels, .layers, .boundaries'` — language mix, node shape, layering
+- `scripts/tools/hotspot-rank.sh --repo . --top 20` — complexity/fan-in hotspots (live)
 
 ### 3. Use graph data to accelerate Step 1.5
 
@@ -643,10 +658,10 @@ Read these files to get structural context for all subsequent phases:
 ### 4. Compute codebase tier and module priority
 
 **Step 1.4.5 — Compute Codebase Tier:**
-Read `draft/graph/schema.yaml`. Extract:
-- `M = stats.modules`
-- `F = stats.go_functions + stats.py_functions`
-- `P = stats.proto_rpcs`
+From the live `$ARCH` (above), extract:
+- `M = $ARCH | jq '.packages | length'` (modules)
+- `F = $ARCH | jq '[.node_labels[] | select(.label=="Function" or .label=="Method") | .count] | add // 0'` (functions+methods)
+- `P = $ARCH | jq '.routes | length'` (routes / RPCs)
 
 Apply tier table:
 
@@ -661,8 +676,8 @@ Apply tier table:
 Hold tier in memory. This governs: architecture.md length minimum, .ai-context.md budget, and module deep-dive depth.
 
 **Step 1.4.6 — Build Module Priority List:**
-From `draft/graph/hotspots.jsonl`: count hotspot files per module (group by `module` field).
-From `draft/graph/architecture.json` `.packages[]`: read `fan_in` per module.
+From `scripts/tools/hotspot-rank.sh --repo .`: count hotspot symbols per module.
+From `$ARCH | jq '.packages[]'`: read `fan_in` per module.
 Rank modules by: `(hotspot_count × 2) + fan_in_count`.
 Top-ranked modules drive Section 6 deep-dive ordering and depth. Modules ranked zero on both: summary treatment only.
 Hold ranked list in memory — it replaces directory scanning for module discovery.
@@ -682,7 +697,7 @@ The tool emits a ready-to-inject ` ```mermaid ``` ` block (or an empty stub on e
 ```
 
 For Section 20 (hotspots slot):
-Read `draft/graph/hotspots.jsonl` (or run `scripts/tools/hotspot-rank.sh --repo . --top 10`), take the top 10 by fanIn, build a markdown table:
+Run `scripts/tools/hotspot-rank.sh --repo . --top 10`, take the top 10 by fanIn, build a markdown table:
 ```
 <!-- GRAPH:hotspots:START -->
 | Symbol | fanIn |
@@ -741,7 +756,7 @@ Perform a **one-time, exhaustive analysis** of the existing codebase. This is NO
 
 If the codebase is large (200+ files), focus on the module boundaries but still enumerate exhaustively within each module.
 
-> **Large codebase guardrail:** If the codebase exceeds 500 source files, limit Section 7 deep dives to the top 20 most-imported modules and summarize others in a table. Rank modules by the number of unique files that import/reference them (descending) — use `draft/graph/architecture.json` `.packages[].fan_in` if graph data is available. For dynamic languages where static import counting is impractical, rank by file count within each module directory (larger modules first). **Even for summarized modules, enumerate immediate sub-directories with file counts** (one-line per sub-dir) — this is cheap with graph data and provides essential navigation context.
+> **Large codebase guardrail:** If the codebase exceeds 500 source files, limit Section 7 deep dives to the top 20 most-imported modules and summarize others in a table. Rank modules by the number of unique files that import/reference them (descending) — use the engine's `.packages[].fan_in` (`get_architecture`, captured as `$ARCH` in Step 1.4.2) if the engine is available. For dynamic languages where static import counting is impractical, rank by file count within each module directory (larger modules first). **Even for summarized modules, enumerate immediate sub-directories with file counts** (one-line per sub-dir) — this is cheap with graph data and provides essential navigation context.
 
 ### Parallel Analysis Protocol (Tiers 3–5)
 
@@ -768,16 +783,16 @@ For tier 3+, readers run simultaneously; wall clock = slowest reader, not the su
 
 #### Phase 0: Graph Data (already done in Step 1.4)
 
-The graph binary has already run. Use its output throughout this protocol:
-- `draft.tmp/graph/schema.yaml` — module list, file counts, tier metrics
-- `draft.tmp/graph/architecture.json` — `.packages[].fan_in` per module (for grouping)
-- `draft.tmp/graph/hotspots.jsonl` — top hotspot files per module (feed to readers)
+The engine is already indexed. Query it live throughout this protocol (reuse `$ARCH` from Step 1.4.2):
+- `$ARCH | jq '.packages'` — module list with `.fan_in`/`.fan_out` (for grouping)
+- `$ARCH | jq '.languages, .node_labels'` — file/symbol counts, tier metrics
+- `scripts/tools/hotspot-rank.sh --repo .` — top hotspot symbols per module (feed to readers)
 
 #### Phase 1: Spawn Parallel Module Readers
 
 **Step 1: Group modules.**
 
-From `draft.tmp/graph/architecture.json` `.packages[]`, extract all module names and their `fan_in` counts.
+From `$ARCH | jq '.packages[]'`, extract all module names and their `fan_in` counts.
 Apply dependency-aware grouping (see `core/shared/parallel-analysis.md`).
 Use the modules-per-agent count from the tier table above (4 for tier 4/5; all modules in one agent for tier 1):
 - Assign highest fan-in modules to separate readers (tier 3+)
@@ -793,7 +808,7 @@ Hotspot files:
   execution/engine.go (847 lines, fanIn=12)
   execution/router.go (412 lines, fanIn=8)
   fill_processor/handler.go (623 lines, fanIn=5)
-Module edges (from architecture.json .packages fan-in/out):
+Module edges (from $ARCH .packages fan-in/out):
   execution → [risk, data, services]
   fill_processor → [execution, persistence]
 ```
@@ -898,7 +913,7 @@ If any reader agent fails to produce valid JSON after one retry:
 When the Agent tool is unavailable or reader agents fail after retry, write `draft/architecture.md` using the **10-section graph-primary structure** (checklist above + `core/templates/architecture.md`). Do not use legacy 28-section or Pass 1/2/3 volume protocols.
 
 1. Use the ranked module list from Step 1.4.6 (graph-first — do not re-scan by directory if Phase 0 succeeded).
-2. For each top module (up to 20 by fan-in), read `draft/graph/modules/{name}.jsonl`, hotspot files, and 3–5 key sources; embed graph blocks and at least one workflow/state diagram per significant module inside §4–§8 as appropriate.
+2. For each top module (up to 20 by fan-in), query the engine for its symbols/callers (`scripts/tools/graph-callers.sh`, `graph-impact.sh`, or `$ARCH | jq '.packages[] | select(.name=="<m>")'`), read the hotspot files and 3–5 key sources; embed graph blocks and at least one workflow/state diagram per significant module inside §4–§8 as appropriate.
 3. Always include §9 Graph Coverage Gaps and §10 Relationship when the Context Audit requires them.
 4. Run Completion Verification (defined later in this skill) before condensation. Fidelity, provenance, and gap honesty block completion — not line counts.
 
@@ -1021,11 +1036,11 @@ Follow these steps in order. The specific files to look for depend on the langua
 
 #### Phase 1: Discovery (Broad Scan)
 
-1. **Map the directory tree**: Recursively list the project to understand the file layout. Note subdirectory groupings. (If Step 1.4 graph analysis succeeded, use `draft.tmp/graph/schema.yaml` module list instead — it is exhaustive and includes file counts.)
+1. **Map the directory tree**: Recursively list the project to understand the file layout. Note subdirectory groupings. (If Step 1.4 graph analysis succeeded, use the engine's `$ARCH | jq '.packages, .file_tree'` instead — it is exhaustive and includes file counts.)
 
 2. **Read build / dependency files**: These reveal the module structure, dependencies, and targets. (See language guide above for which files.)
 
-3. **Read API definition files**: These define the module's data model and service interfaces. (See language guide above for which files. If Step 1.4 succeeded, `draft.tmp/graph/architecture.json` `.routes` already has all detected service endpoints.)
+3. **Read API definition files**: These define the module's data model and service interfaces. (See language guide above for which files. If Step 1.4 succeeded, the engine's `$ARCH | jq '.routes'` already has all detected service endpoints.)
 
 4. **Read interface / type definition files**: Class declarations, interface definitions, and type annotations reveal the public API and design intent.
 
@@ -1129,11 +1144,19 @@ The document is:
 
 **Full details, per-section guidance, provenance rules, and examples** live in:
 - `core/templates/architecture.md` (the source of truth for the 10 sections + Generation Contract)
-- `docs/research/proposed-graph-backed-architecture-template.md` (design rationale and fidelity rules)
 - `references/architecture-spec.md` (deprecated legacy notes — **10-section template wins on any conflict**)
 
 There is no legacy 28-section structure and no volume targets. The template itself is the contract.
 
+### Root vs Module Markdown (scope asymmetry)
+
+The depth of generated markdown depends on the scope resolved in **Scope Detection**:
+
+- **Module init** (current dir below root): generate the **full, detailed** 10-section `architecture.md` for the module subtree — the standard deep analysis described in this skill. This is where engineering depth lives.
+- **Root init** (current dir IS root, monorepo): generate a **sparse, high-level system map**, not deep per-module prose. The root `architecture.md` covers: system overview + Graph Health Dashboard (from the whole-repo spine), the module catalog with one-line responsibilities and links *down* to each module's `draft/.ai-context.md`, cross-module dependency topology (from `draft/graph/`), shared infrastructure, and system-wide invariants. Defer module internals to the module docs — a large root must not duplicate them. If a module has not been initialized, link it as "not yet initialized — run `draft init` there."
+
+The graph is symmetric (root spine + per-module snapshots, linked); only the **prose** is asymmetric. Both consume `draft/graph/`.
+
 **After completing analysis AND passing verification**, write to `draft/architecture.md`. This is the PRIMARY output. Then run the Condensation Subroutine.
 
 ## .ai-context.md Specification
@@ -1709,6 +1732,7 @@ Create `draft/tracks.md` with metadata header:
 
 ```markdown
 ---
+type: TrackIndex
 project: "{PROJECT_NAME}"
 module: "root"
 generated_by: "draft:init"
@@ -1754,6 +1778,38 @@ For **brownfield** projects, run `draft learn` (no arguments — full codebase s
 
 ## Completion
 
+**Finalize the context index:** After all `draft/` files are written, author (or refresh)
+`draft/index.md` — a plain, navigable index over the context bundle. No OKF framing, no
+special frontmatter; it is a human- and agent-readable table of contents.
+
+Write `draft/index.md` with this structure (omit rows whose files were not generated):
+
+```md
+# <project> — Draft Context
+
+Start here. This indexes the Draft context for this repo.
+
+## Context
+- [Architecture](architecture.md) — module map, dependencies, hotspots (graph-grounded)
+- [Product](product.md) — what this system does and for whom
+- [Tech Stack](tech-stack.md) — languages, frameworks, infra
+- [Workflow](workflow.md) — how work flows through the repo
+- [Guardrails](guardrails.md) — learned conventions and anti-patterns
+- [AI Context Map](.ai-context.md) — condensed orientation for agents
+- [AI Profile](.ai-profile.md) — repo profile + tiering
+
+## Tracks
+- [Track Index](tracks.md) — active, completed, and archived tracks
+
+## Knowledge graph
+- Engine-only (`codebase-memory-mcp`). Structural data is queried live via the
+  `graph-*.sh` wrappers; `draft/graph/schema.yaml` is the gate marker. There is no
+  committed graph mirror to browse.
+```
+
+Keep one-line descriptions accurate to what each file actually contains. This index is
+the single committed entry point to the `draft/` bundle.
+
 **Finalize run memory:** Update `draft/.state/run-memory.json`:
 - `status`: `"completed"`
 - `completed_at`: current ISO timestamp
@@ -1763,6 +1819,7 @@ For **Brownfield** projects, announce:
 "Draft initialized successfully with comprehensive analysis!
 
 Created:
+- draft/index.md (plain docs index — navigable table of contents for the draft/ bundle)
 - draft/.ai-profile.md (20-50 lines — ultra-compact always-injected profile, Tier 0)
 - draft/.ai-context.md (200-400 lines — token-optimized AI context, self-contained, Tier 1)
 - draft/architecture.md (comprehensive human-readable engineering reference, Tier 2)
@@ -1797,6 +1854,7 @@ For **Greenfield** projects, announce:
 "Draft initialized successfully!
 
 Created:
+- draft/index.md (plain docs index — navigable table of contents for the draft/ bundle)
 - draft/product.md
 - draft/tech-stack.md
 - draft/workflow.md
@@ -2067,14 +2125,14 @@ Write the `GRAPH:module-deps` injection slot into architecture.md:
 
 If graph build succeeded (Step 1.4.7 completed), write the populated slot content using the diagram from Step 1.4.7. If filtered (>30 modules), include the filter note. Dashed edges indicate circular dependencies.
 
-If graph binary was not found: write the slot with placeholder body so draft:index can populate it later:
+If graph binary was not found: write the slot with placeholder body so draft:init --graph-only can populate it later:
 ```
 <!-- GRAPH:module-deps:START -->
-[Graph data unavailable — run draft:index to populate after graph binary is installed]
+[Graph data unavailable — run draft:init --graph-only to populate after graph binary is installed]
 <!-- GRAPH:module-deps:END -->
 ```
 
-The slot markers MUST always be written — they are required for draft:index refresh to function.
+The slot markers MUST always be written — they are required for draft:init --graph-only refresh to function.
 
 #### 4.2 Process Lifecycle (or Usage Lifecycle for libraries)
 
@@ -2181,13 +2239,13 @@ Only when material: authentication/authorization checkpoints, distributed transa
 
 **Core rule:** The graph is the source of truth for structure. LLM synthesis exists only to interpret the graph into actionable design understanding — primarily via one accurate workflow or state diagram per module — plus tiny supporting notes. The previous volume-oriented deep-dive expectations are superseded.
 
-For each module in `draft/graph/architecture.json` (`.packages[]`), produce a subsection whose **primary content** is the deterministic graph block followed by one synthesized behavioral diagram. Every module gets a slot; do not sample. The block's fan-in/out and node counts come from `.packages[]`; public API and key call edges come from live per-package queries (`scripts/tools/graph-callers.sh`, `graph-impact.sh`) and `hotspots.jsonl`.
+For each module returned by `scripts/tools/graph-arch.sh --repo . | jq '.packages[]'`, produce a subsection whose **primary content** is the deterministic graph block followed by one synthesized behavioral diagram. Every module gets a slot; do not sample. The block's fan-in/out and node counts come from `.packages[]`; public API and key call edges come from live per-package queries (`scripts/tools/graph-callers.sh`, `graph-impact.sh`) and `scripts/tools/hotspot-rank.sh --repo .`.
 
 #### 7.{N} {module-name}
 
 <!-- GRAPH:module-deep/{module-name}:START -->
 <!-- Rendered deterministic block: package name, node count, public API list, fan-in/fan-out (from
-     architecture.json .packages), hotspot fan-in (from hotspots.jsonl), key call edges (from
+     get_architecture .packages), hotspot fan-in (from hotspot-rank.sh), key call edges (from
      graph-callers.sh/graph-impact.sh), entry points if known. No LLM prose inside fence. -->
 <!-- GRAPH:module-deep/{module-name}:END -->
 
@@ -2206,7 +2264,7 @@ Synthesize a single, accurate Mermaid diagram (`stateDiagram-v2`, `sequenceDiagr
 
 #### Sub-Module Guidance (when graph justifies recursion)
 
-When a module has clear internal structure visible in `draft/graph/architecture.json` (`.packages` fan-in/out) or live per-package queries:
+When a module has clear internal structure visible in live engine query `get_architecture .packages` (fan-in/out) or live per-package queries:
 - Create `##### 7.X.Y {Parent}/{Child}` subsections only for children that have their own meaningful public surface or high internal fan-in.
 - Each sub-module subsection follows the same compact pattern: graph facts + **one mandatory workflow/state diagram** + ≤60 words Design Notes.
 - Do not descend further unless the child itself shows additional clear boundaries in the graph data.
@@ -2268,7 +2326,7 @@ Regardless of tier, any directory whose name contains `ops`, `handlers`, `execut
 | ... | (enumerate ALL — no sampling, no "and others") | | | |
 ```
 
-Use `draft/graph/modules/{module}.jsonl` to get the complete file list with line counts. Use `draft/graph/hotspots.jsonl` to flag high-complexity operations.
+Use `scripts/tools/graph-callers.sh --symbol <module>` or `scripts/tools/graph-arch.sh --repo .` to get the complete file list. Use `scripts/tools/hotspot-rank.sh --repo .` to flag high-complexity operations.
 
 #### Example: Full Sub-Module Treatment for `icebox/` (917 files)
 
@@ -2315,7 +2373,7 @@ stateDiagram-v2
 After writing Section 7, run these checks before proceeding. **If any check fails, STOP and fix.**
 
 **Check 1 — Graph block present and faithful for every module:**
-Every top-level module from `draft/graph/architecture.json` (`.packages`) has its `<!-- GRAPH:module-deep/...:START --> ... <!-- GRAPH:module-deep/...:END -->` fence rendered verbatim. No LLM prose inside the fence. No modules missing.
+Every top-level module from the live engine (`get_architecture .packages`) has its `<!-- GRAPH:module-deep/...:START --> ... <!-- GRAPH:module-deep/...:END -->` fence rendered verbatim. No LLM prose inside the fence. No modules missing.
 
 **Check 2 — One mandatory workflow/state diagram per module:**
 Every `#### 7.X` (and every `##### 7.X.Y` that the graph justified) contains exactly one high-signal `Primary Workflow / State` Mermaid diagram (`stateDiagram-v2`, `sequenceDiagram`, or clear `flowchart`). The diagram must reflect facts from the module's graph record (entry points, public symbols, call targets). Generic placeholder diagrams fail this check.
@@ -2419,12 +2477,13 @@ Include architecturally significant implementations (high fan-in, core extension
 |---|-----------|-------------|-------|-------------|
 | 1 | ArchiveFilesOp | `icebox/master/ops/archive_files_op.cc` | 2100 | Archives files to cloud vault |
 | 2 | CancelJobOp | `icebox/master/ops/cancel_job_op.cc` | 450 | Cancels running archive job |
-| (enumerate ALL — use graph hotspots.jsonl and per-module JSONL for file list and line counts) |
+| (enumerate ALL — use hotspot-rank.sh and graph-callers.sh / get_architecture for file list and line counts) |
 ```
 
-> **MANDATORY (graph data)**: Read `draft/graph/modules/{module}.jsonl` to get the complete file
-> list with line counts. Filter for files in operation sub-directories (paths containing `/ops/`,
-> `/handlers/`, `/executors/`, `/workers/`). Use `draft/graph/hotspots.jsonl` to flag
+> **MANDATORY (graph data)**: Query `scripts/tools/graph-arch.sh --repo .` or
+> `scripts/tools/graph-callers.sh --symbol <module>` to get the complete file list with line counts.
+> Filter for files in operation sub-directories (paths containing `/ops/`,
+> `/handlers/`, `/executors/`, `/workers/`). Use `scripts/tools/hotspot-rank.sh --repo .` to flag
 > high-complexity operations (high line count or fanIn). Do NOT skip this step — incomplete
 > catalogs cause AI agents to reinvent existing functionality.
 
@@ -2984,11 +3043,11 @@ If graph build succeeded and proto files exist (Step 1.4.7 completed), write the
 If graph binary was not found or no proto files exist, write the slot with placeholder:
 ```
 <!-- GRAPH:proto-map:START -->
-[Graph data unavailable — run draft:index to populate after graph binary is installed]
+[Graph data unavailable — run draft:init --graph-only to populate after graph binary is installed]
 <!-- GRAPH:proto-map:END -->
 ```
 
-The slot markers MUST always be written — they are required for draft:index refresh to function.
+The slot markers MUST always be written — they are required for draft:init --graph-only refresh to function.
 
 ---
 
@@ -3115,11 +3174,11 @@ Fix: Add actual payload descriptions on arrows, `alt`/`opt` blocks for condition
 
 **FAILURE 3 — Empty Appendices:**
 Detection: Appendix B, C, or D tables have fewer than 10 data rows.
-Fix: Cross-reference ALL data sources (Appendix B), ALL implementation outputs (Appendix C), and add 2-3 detailed sequence diagrams to Appendix D. Use graph data (`architecture.json` `.packages`/`.routes`) to enumerate exhaustively.
+Fix: Cross-reference ALL data sources (Appendix B), ALL implementation outputs (Appendix C), and add 2-3 detailed sequence diagrams to Appendix D. Use live engine queries (`get_architecture .packages`/`.routes`) to enumerate exhaustively.
 
 **FAILURE 4 — Missing Sub-Modules:**
 Detection: A module with 100+ source files (check graph data) has no Sub-Module Structure table.
-Fix: Read `draft/graph/modules/{name}.jsonl`, group files by immediate sub-directory, and generate the table with file counts and one-line role descriptions per sub-directory.
+Fix: Query `scripts/tools/graph-arch.sh --repo .` or `scripts/tools/graph-callers.sh --symbol <name>`, group results by immediate sub-directory, and generate the table with file counts and one-line role descriptions per sub-directory.
 
 **FAILURE 4b — Shallow Sub-Module Treatment:**
 Detection: Large sub-modules (50+ files) listed only as table rows with no dedicated deep-dive subsection. Or ops/handler directories have no operation catalog.
@@ -3166,859 +3225,11 @@ Run this checklist before writing architecture.md:
 
 ---
 
-## Index Command
-
-When user says "index services" or "draft index [--init-missing]":
-
-You are building a federated knowledge index for a monorepo with multiple services.
-
-## Red Flags - STOP if you're:
-
-- Running at a non-root directory in a monorepo
-- Indexing services that haven't been initialized with `draft init`
-- Overwriting root-level context without confirming with the user
-- Aggregating without verifying each service's draft/ directory exists
-- Skipping dependency mapping between services
-
-**Aggregate from initialized services only. Verify before overwriting.**
-
----
-
-## Standard File Metadata
-
-**ALL generated files MUST include the standard YAML frontmatter.** This enables refresh tracking, sync verification, and traceability.
-
-### Project Metadata File (single source of truth)
-
-Before writing any file, update `draft/metadata.json` with current git state. This is the single source of truth for `synced_to_commit` and all `git.*` fields for every project-level artifact. Do NOT embed git fields in per-file frontmatter.
-
-Use the `--project-metadata` flag (preferred):
-
-```bash
-DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
-[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$HOME/.cursor/plugins/local/draft/scripts/tools"
-[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
-bash "$DRAFT_TOOLS/git-metadata.sh" --project-metadata \
-    --project "$PROJECT" --generated-by "draft:index"
-```
-
-### Per-File Metadata Template
-
-Insert this **stable** YAML frontmatter at the top of every generated file (`service-index.md`, `dependency-graph.md`, `tech-matrix.md`, `draft-index-bughunt-summary.md`):
-
-```yaml
----
-project: "{PROJECT_NAME}"
-module: "root"
-generated_by: "draft:index"
-generated_at: "{ISO_TIMESTAMP}"
----
-```
-
-> **Note**: `generated_by` uses `draft:command` format (not `draft command`) for cross-platform compatibility.
-
----
-
-## Pre-Check
-
-```bash
-ls draft/ 2>/dev/null
-```
-
-**If `draft/` does NOT exist at root:**
-- Announce: "Root draft/ directory not found. Run `draft init` at monorepo root first to create base context, then run `draft index` to aggregate service knowledge."
-- Stop here.
-
-**If `draft/` exists:** Continue to lockfile check.
-
-## Lockfile Check
-
-Before proceeding, check for a stale lock:
-
-```bash
-ls draft/.index-lock 2>/dev/null
-```
-
-- **If `draft/.index-lock` exists and is less than 10 minutes old:** Warn: "Previous indexing may be incomplete. Remove `draft/.index-lock` to proceed." Stop here.
-- **If `draft/.index-lock` exists and is older than 10 minutes:** Remove it and continue.
-- **If no lock exists:** Continue.
-
-Create `draft/.index-lock` with the current timestamp before starting:
-
-```bash
-date -u +"%Y-%m-%dT%H:%M:%SZ" > draft/.index-lock
-```
-
-**On completion (Step 9) or fatal error, remove the lock:**
-
-```bash
-rm -f draft/.index-lock
-```
-
-## Step 1: Parse Arguments
-
-Check for optional arguments:
-- `--init-missing`: Also initialize services that don't have `draft/` directories
-- `bughunt [dir1 dir2 ...]`: Run bug hunt across subdirectories with `draft/` folders
-  - If no directories specified: auto-discover all subdirectories with `draft/`
-  - If directories specified: run bughunt only in those subdirectories (skip if no `draft/`)
-  - Generate summary report at: `draft/bughunt-summary.md`
-
-**If `bughunt` argument detected:** Skip to Step 1A (Bughunt Mode) instead of continuing to Step 2.
-
-## Step 1A: Bughunt Mode
-
-This mode runs `draft bughunt` across multiple subdirectories and aggregates results.
-
-### 1A.1: Determine Target Directories
-
-**If directories explicitly specified** (e.g., `bughunt dir1 dir2 dir3`):
-- Use provided directory list as targets
-- Verify each directory exists
-- Check each directory for `draft/` subdirectory
-- Warn and skip any directory without `draft/`
-
-**If no directories specified** (e.g., just `bughunt`):
-- Auto-discover all immediate child directories (depth=1)
-- Filter for directories containing `draft/` subdirectory
-- Exclude patterns: `node_modules/`, `vendor/`, `.git/`, `draft/`, `.*`
-
-```bash
-# Example auto-discovery
-for dir in */; do
-  if [ -d "$dir/draft" ]; then
-    echo "$dir"
-  fi
-done
-```
-
-**Output:**
-```
-Target directories for bughunt:
-  - services/auth/
-  - services/billing/
-  - services/notifications/
-```
-
-### 1A.2: Execute Bughunt Per Directory
-
-For each target directory:
-
-1. **Set working directory** to `<target-dir>` for the bughunt scope. The AI agent should invoke `draft bughunt` with the target directory as the scope path, rather than using `cd`:
-   ```
-   draft bughunt
-   → (scope prompt) → "Specific paths"
-   → (paths prompt) → <target-dir>
-   ```
-
-2. **Announce:**
-   ```
-   Running bughunt in <target-dir>...
-   ```
-
-3. **Let `draft bughunt` run its full workflow:**
-   - Report will be generated at `<target-dir>/draft/bughunt-report-<timestamp>.md`
-   - Capture exit status (success/failure)
-
-4. **Record results:**
-   - Directory path
-   - Total bugs found (by severity)
-   - Report location
-   - Any errors encountered
-
-**Note:** Run bughunts sequentially, not in parallel, to avoid context conflicts.
-
-### 1A.3: Parse Individual Reports
-
-After all bughunts complete, read each generated report:
-
-```bash
-# For each target directory
-cat <dir>/draft/bughunt-report-latest.md
-```
-
-Extract from each report:
-- Branch and commit (from header)
-- Summary table (bug counts by severity)
-- Critical/High issue count
-- Total issues count
-
-### 1A.4: Generate Aggregate Summary Report
-
-Create `draft/bughunt-summary.md`:
-
-```markdown
-# Draft Index: Bughunt Summary
-
-**Date:** YYYY-MM-DD HH:MM
-**Mode:** [Auto-discovery | Explicit directories]
-**Directories Scanned:** N
-
-## Overview
-
-| Directory | Critical | High | Medium | Low | Total | Report |
-|-----------|----------|------|--------|-----|-------|--------|
-| services/auth/ | 0 | 2 | 5 | 3 | 10 | [→](services/auth/draft/bughunt-report.md) |
-| services/billing/ | 1 | 1 | 2 | 1 | 5 | [→](services/billing/draft/bughunt-report.md) |
-| services/notifications/ | 0 | 0 | 1 | 2 | 3 | [→](services/notifications/draft/bughunt-report.md) |
-
-**Grand Total:** X Critical, Y High, Z Medium, W Low
-
-## Directories With Critical Issues
-
-| Directory | Count | Details |
-|-----------|-------|---------|
-| services/billing/ | 1 | [→](services/billing/draft/bughunt-report.md#critical-issues) |
-
-## Directories With No Issues
-
-- services/api-gateway/
-- services/user-service/
-
-## Skipped Directories
-
-| Directory | Reason |
-|-----------|--------|
-| services/legacy-tools/ | No draft/ directory found |
-| services/experiments/ | No draft/ directory found |
-
-## Next Steps
-
-1. **Prioritize Critical Issues:** Review directories with Critical bugs first
-2. **Review Individual Reports:** Click links above to see detailed findings
-3. **Track Fixes:** Use `draft new-track` to create implementation tracks for fixes
-4. **Re-run After Fixes:** Run `draft index bughunt` again to verify
-
----
-
-*Generated by `draft index bughunt` command*
-```
-
-### 1A.5: Completion Report
-
-```
----
-              DRAFT INDEX BUGHUNT COMPLETE
----
-Scanned: N directories
-Completed: X successful
-Skipped: Y (no draft/)
-Failed: Z errors
-
-Grand Total Bugs:
-  Critical: W
-  High: X
-  Medium: Y
-  Low: Z
-
-Summary Report: draft/bughunt-summary.md
-
-Directories requiring immediate attention:
-  - services/billing/ (1 CRITICAL)
-  - services/auth/ (2 HIGH)
-
----
-```
-
-**STOP HERE** if bughunt mode. Do not continue to Step 2 (normal indexing flow).
-
-## Step 2: Discover Services (Depth=1 Only)
-
-Scan immediate child directories for service markers. Do NOT recurse beyond depth=1.
-
-**Service detection markers (any of these):**
-- `package.json` (Node.js)
-- `go.mod` (Go)
-- `Cargo.toml` (Rust)
-- `pom.xml` or `build.gradle` (Java)
-- `pyproject.toml` or `requirements.txt` (Python)
-- `Dockerfile` (containerized service)
-- `src/` directory with code files
-
-**Exclude patterns:**
-- `node_modules/`
-- `vendor/`
-- `.git/`
-- `draft/` (the root draft directory itself)
-- Any directory starting with `.`
-
-```bash
-# Example discovery (adapt to actual structure)
-ls -d */ | head -50
-```
-
-**Output:** List of detected service directories.
-
-## Step 3: Categorize Services
-
-For each detected service directory, check for `draft/` subdirectory:
-
-```bash
-# For each service
-ls <service>/draft/ 2>/dev/null
-```
-
-Categorize into:
-- **Initialized:** Has `draft/` with context files
-- **Uninitialized:** No `draft/` directory
-
-Report:
-```
-Scanning immediate child directories...
-
-Detected X service directories:
-  ✓ Y initialized (draft/ found)
-  ○ Z uninitialized
-
-Initialized services:
-  - services/auth/
-  - services/billing/
-  - ...
-
-Uninitialized services:
-  - services/legacy-reports/
-  - services/admin-tools/
-  - ...
-```
-
-## Step 4: Handle Uninitialized Services
-
-**If `init-missing` argument is present:**
-1. For each uninitialized service, prompt:
-   ```
-   Initialize <service-name>/? [y/n/all/skip-rest]
-   ```
-2. If user selects:
-   - `y`: Run `draft init` in that directory
-   - `n`: Skip this service
-   - `all`: Initialize all remaining without prompting
-   - `skip-rest`: Skip all remaining uninitialized services
-
-**If `init-missing` argument is NOT present:**
-- Just report uninitialized services and continue
-- Suggest: "Run `draft index --init-missing` to initialize these services"
-
-## Step 5: Aggregate Context from Initialized Services
-
-For each initialized service, read and extract:
-
-### 5.1 From `<service>/draft/product.md`:
-- Service name
-- First paragraph of Vision (summary)
-- Target users (list)
-- Core features (list)
-
-### 5.2 From `<service>/draft/.ai-context.md` (or legacy `<service>/draft/architecture.md`):
-- Key Takeaway paragraph (from `## System Overview`)
-- External dependencies (from `## External Dependencies`)
-- Exposed APIs or entry points (from `## Entry Points`)
-- Dependencies on other services (look for references to sibling service names)
-- Critical invariants summary (from `## Critical Invariants`, if available)
-
-### 5.3 From `<service>/draft/tech-stack.md`:
-- Primary language/framework
-- Database
-- Key dependencies
-
-### 5.4 Create/Update `<service>/draft/manifest.json`:
-```json
-{
-  "name": "<service-name>",
-  "type": "service",
-  "summary": "<first line of product vision>",
-  "primaryTech": "<main language/framework>",
-  "dependencies": ["<other-service-names>", "<external-deps>"],
-  "dependents": [],
-  "team": "<if found in docs>",
-  "initialized": "<date>",
-  "lastIndexed": "<current-date>"
-}
-```
-
-## Step 6: Detect Inter-Service Dependencies
-
-Analyze extracted data to build dependency graph:
-
-1. Look for service name references in each service's architecture.md
-2. Look for API client imports or service URLs in tech-stack.md
-3. Look for mentions in product.md that reference other services
-4. **Graph-enriched detection** (if individual services have `draft/graph/` directories):
-   - Read each service's `draft/graph/architecture.json` `.routes` to map which service defines vs consumes which endpoints
-   - Cross-reference proto consumers with proto producers to build precise inter-service dependency edges
-   - Read `draft/graph/architecture.json` (`.packages`) per service for internal module structure
-   - This provides deterministic, code-level dependency data that supplements the heuristic name-matching above
-
-Build a dependency map:
-```
-auth-service: [] # no dependencies on other services
-billing-service: [auth-service]
-api-gateway: [auth-service, billing-service]
-```
-
-### Step 6.1b: Cycle Detection
-
-**Cycle detection:** Walk the dependency graph depth-first from each service. If a cycle is detected (service A depends on B depends on ... depends on A), emit a `> WARNING: Circular dependency detected: A → B → ... → A` line in `dependency-graph.md`, mark the back-edge with `circular: true` in `manifest.json`'s dependency entry, and continue processing. Do not fail on cycles — report and proceed.
-
-### Step 6.2: Resolve Dependents (Reverse Lookup)
-
-For each service S, iterate all other services' `dependencies` arrays. If S appears in another service's dependencies, add that service to S's `dependents` array. Write the updated `manifest.json` for each service.
-
-## Step 7: Generate Root Aggregated Files
-
-### 7.1 Generate `draft/service-index.md`
-
-Use the following inline template:
-
-```markdown
-# Service Index
-
-> Auto-generated by `draft index` on <date>. Do not edit directly.
-> Re-run `draft index` to update.
-
-## Overview
-
-| Metric | Count |
-|--------|-------|
-| Total Services Detected | X |
-| Initialized | Y |
-| Uninitialized | Z |
-
-## Service Registry
-
-| Service | Status | Tech Stack | Dependencies | Team | Details |
-|---------|--------|------------|--------------|------|---------|
-| auth | ✓ | Go, Postgres | - | @auth-team | [→](../services/auth/draft/.ai-context.md) |
-| billing | ✓ | Node, Stripe | auth | @billing | [→](../services/billing/draft/.ai-context.md) |
-| legacy-reports | ○ | - | - | - | Not initialized |
-
-## Uninitialized Services
-
-The following services have not been initialized with `draft init`:
-- `services/legacy-reports/`
-- `services/admin-tools/`
-
-Run `draft index --init-missing` or initialize individually with:
-```bash
-cd services/legacy-reports && draft init
-```
-```
-
-### 7.2 Generate `draft/dependency-graph.md`
-
-```markdown
-# Service Dependency Graph
-
-> Auto-generated by `draft index` on <date>. Do not edit directly.
-
-## System Topology
-
-```mermaid
-graph LR
-    subgraph "Core Services"
-        auth[auth-service]
-        billing[billing-service]
-        users[user-service]
-    end
-
-    subgraph "Edge"
-        gateway[api-gateway]
-    end
-
-    subgraph "Background"
-        notifications[notification-service]
-        reports[report-service]
-    end
-
-    gateway --> auth
-    gateway --> billing
-    gateway --> users
-    billing --> auth
-    notifications --> users
-    reports --> billing
-```
-
-## Dependency Matrix
-
-| Service | Depends On | Depended By |
-|---------|-----------|-------------|
-| auth-service | - | billing, gateway, users |
-| billing-service | auth | gateway, reports |
-| user-service | auth | gateway, notifications |
-| api-gateway | auth, billing, users | - |
-
-## Dependency Order (Topological)
-
-1. **auth-service** (foundational - no internal dependencies)
-2. **user-service** (depends on: auth)
-3. **billing-service** (depends on: auth)
-4. **notification-service** (depends on: users)
-5. **report-service** (depends on: billing)
-6. **api-gateway** (depends on: auth, billing, users)
-
-> This ordering helps when planning cross-service changes or understanding impact.
-```
-
-### 7.3 Generate `draft/tech-matrix.md`
-
-```markdown
-# Technology Matrix
-
-> Auto-generated by `draft index` on <date>. Do not edit directly.
-
-## Common Stack (Org Standards)
-
-Technologies used by majority of services:
-
-| Technology | Usage | Services |
-|------------|-------|----------|
-| PostgreSQL | Database | auth, billing, users (85%) |
-| Redis | Caching | auth, gateway, notifications (60%) |
-| Docker | Containerization | all (100%) |
-| GitHub Actions | CI/CD | all (100%) |
-
-## Technology Distribution
-
-### Languages
-
-| Language | Services | Percentage |
-|----------|----------|------------|
-| Go | auth, users, gateway | 45% |
-| TypeScript | billing, notifications, reports | 45% |
-| Python | ml-service, analytics | 10% |
-
-### Databases
-
-| Database | Services |
-|----------|----------|
-| PostgreSQL | auth, billing, users, reports |
-| MongoDB | notifications, analytics |
-| Redis | auth, gateway (cache only) |
-
-## Variance Report
-
-Services deviating from org standards:
-
-| Service | Deviation | Reason |
-|---------|-----------|--------|
-| ml-service | Python instead of Go/TS | ML ecosystem |
-| analytics | MongoDB instead of Postgres | Time-series workload |
-```
-
-### Placeholder Detection
-
-A file is considered a placeholder if it contains the marker `<!-- AUTO-GENERATED -->` or is smaller than 100 bytes. Placeholders may be overwritten without confirmation. Non-placeholder files require user confirmation before overwriting.
-
-### 7.4 Synthesize `draft/product.md` (if not exists or is placeholder)
-
-Read all service product.md files and synthesize:
-
-```markdown
-# Product: [Org/Product Name]
-
-> Synthesized from X service contexts by `draft index` on <date>.
-> Edit this file to refine the overall product vision.
-
-## Vision
-
-[Synthesized from common themes across service visions - one paragraph describing what the overall product/platform does]
-
-## Target Users
-
-<!-- Aggregated from all services, deduplicated -->
-- **End Users**: [common user types across services]
-- **Developers**: [if developer-facing APIs exist]
-- **Operators**: [if ops/admin services exist]
-
-## Service Capabilities
-
-| Capability | Provided By | Description |
-|------------|-------------|-------------|
-| Authentication | auth-service | User identity, JWT, OAuth |
-| Payments | billing-service | Stripe integration, invoicing |
-| API Access | api-gateway | Rate limiting, routing |
-
-## Cross-Cutting Concerns
-
-<!-- Extracted from common patterns across services -->
-- **Authentication**: All services validate via auth-service
-- **Observability**: [common logging/tracing approach]
-- **Data Privacy**: [common compliance patterns]
-```
-
-### 7.5 Synthesize `draft/architecture.md` (if not exists or is placeholder)
-
-```markdown
-# Architecture: [Org/Product Name]
-
-> Synthesized from X service contexts by `draft index` on <date>.
-> This is a system-of-systems view. For service internals, see individual service contexts.
-
-## System Overview
-
-**Key Takeaway:** [One paragraph synthesizing overall system purpose from service summaries]
-
-### System Topology
-
-```mermaid
-graph TD
-    subgraph "External"
-        Users[Users/Clients]
-        ThirdParty[Third-Party Services]
-    end
-
-    subgraph "Edge Layer"
-        Gateway[API Gateway]
-        CDN[CDN/Static]
-    end
-
-    subgraph "Core Services"
-        Auth[Auth Service]
-        Billing[Billing Service]
-        Users2[User Service]
-    end
-
-    subgraph "Background"
-        Notifications[Notifications]
-        Reports[Reports]
-    end
-
-    subgraph "Data Layer"
-        Postgres[(PostgreSQL)]
-        Redis[(Redis)]
-        Queue[Message Queue]
-    end
-
-    Users --> Gateway
-    Gateway --> Auth
-    Gateway --> Billing
-    Gateway --> Users2
-    Billing --> ThirdParty
-    Auth --> Postgres
-    Billing --> Postgres
-    Notifications --> Queue
-    Reports --> Queue
-```
-
-## Service Directory
-
-| Service | Responsibility | Tech | Status | Details |
-|---------|---------------|------|--------|---------|
-| auth-service | Identity & access management | Go, Postgres | ✓ Active | [→ context](../services/auth/draft/.ai-context.md) |
-| billing-service | Payments & invoicing | Node, Stripe | ✓ Active | [→ context](../services/billing/draft/.ai-context.md) |
-
-## Shared Infrastructure
-
-<!-- Extracted from common external dependencies -->
-
-| Component | Purpose | Used By |
-|-----------|---------|---------|
-| PostgreSQL | Primary datastore | auth, billing, users |
-| Redis | Caching, sessions | auth, gateway |
-| RabbitMQ | Async messaging | notifications, reports |
-| Stripe | Payment processing | billing |
-
-## Cross-Service Patterns
-
-<!-- Extracted from common conventions -->
-
-| Pattern | Description | Services |
-|---------|-------------|----------|
-| JWT Auth | All services validate JWT via auth-service | all |
-| Event-Driven | Async events via message queue | notifications, reports |
-
-## Notes
-
-- For detailed service architecture, navigate to individual service contexts
-- This file is regenerable via `draft index`
-- Manual edits to non-synthesized sections will be preserved on re-index
-```
-
-### 7.6 Synthesize `draft/tech-stack.md` (if not exists or is placeholder)
-
-```markdown
-# Tech Stack: [Org/Product Name]
-
-> Synthesized from X service contexts by `draft index` on <date>.
-> This defines org-wide standards. Service-specific additions are in their local tech-stack.md.
-
-## Org Standards
-
-### Languages
-- **Primary**: [most common language] — [X% of services]
-- **Secondary**: [second most common] — [Y% of services]
-
-### Frameworks
-- **API**: [common API framework]
-- **Testing**: [common test framework]
-
-### Infrastructure
-- **Database**: PostgreSQL (standard), MongoDB (approved for specific use cases)
-- **Caching**: Redis
-- **Messaging**: RabbitMQ / SQS
-- **Container**: Docker
-- **Orchestration**: Kubernetes
-
-### CI/CD
-- **Platform**: GitHub Actions
-- **Registry**: [container registry]
-
-## Approved Variances
-
-| Service | Variance | Justification |
-|---------|----------|---------------|
-| ml-service | Python | ML ecosystem requirements |
-| analytics | MongoDB | Time-series workload |
-
-## Shared Libraries
-
-| Library | Purpose | Version | Used By |
-|---------|---------|---------|---------|
-| @org/auth-client | Auth service client | 2.x | billing, gateway, notifications |
-| @org/logging | Structured logging | 1.x | all services |
-```
-
-### 7.7 Synthesize `draft/.ai-context.md` (if not exists or is placeholder)
-
-After generating `draft/architecture.md`, derive a condensed `draft/.ai-context.md` using the Condensation Subroutine (as defined in `core/shared/condensation.md`). This provides a token-optimized, self-contained AI context file at the root level aggregating all service knowledge.
-
-- Read the synthesized `draft/architecture.md`
-- Condense into 200-400 lines covering: system overview, service catalog, inter-service dependencies, shared infrastructure, cross-cutting patterns, critical invariants, and entry points
-- If `draft/.ai-context.md` already exists and is not a placeholder, prompt before overwriting
-
-## Step 8: Create Root Config
-
-Create `draft/config.yaml` if not exists:
-
-```yaml
-# Draft Index Configuration
-
-# Service detection patterns (immediate children only)
-service_patterns:
-  - "package.json"
-  - "go.mod"
-  - "Cargo.toml"
-  - "pom.xml"
-  - "build.gradle"
-  - "pyproject.toml"
-  - "requirements.txt"
-  - "Dockerfile"
-
-# Directories to exclude from scanning
-exclude_patterns:
-  - "node_modules"
-  - "vendor"
-  - ".git"
-  - "draft"
-  - ".*" # Hidden directories
-
-# Re-index on these events (for CI integration)
-reindex_triggers:
-  - "service added"
-  - "service removed"
-  - "weekly"
-```
-
-## Step 8.5: Refresh Graph Injection Slots
-
-For each initialized service with both `draft/architecture.md` AND `draft/graph/schema.yaml`:
-
-**A. Read current `architecture.md` into memory.**
-
-**B. Regenerate slot content from graph JSONL:**
-- `GRAPH:module-deps` → run `scripts/tools/mermaid-from-graph.sh --repo . --diagram module-deps`
-  Parse JSON response, extract `.mermaid` string + `filtered` flag + stats
-- `GRAPH:proto-map` → run `scripts/tools/mermaid-from-graph.sh --repo . --diagram proto-map`
-  Parse JSON response, extract `.mermaid` string + stats
-- `GRAPH:hotspots` → read `draft/graph/hotspots.jsonl`, build top-10 markdown table:
-  `| File | Lines | fanIn | Score |` with one row per hotspot, ordered by score descending
-
-**C. For each slot, find `<!-- GRAPH:{id}:START -->` ... `<!-- GRAPH:{id}:END -->` markers.**
-Replace entire block (inclusive of markers) with regenerated content.
-If a marker pair is absent (legacy file): insert slot at the designated position and log:
-`"Injected GRAPH:{id} slot into architecture.md (slot was absent — legacy file upgraded)"`
-
-**D. Write updated `architecture.md` back to disk.**
-Update frontmatter: `generated_by = "draft:index"`, `generated_at = now`. Also update `draft/metadata.json` via `git-metadata.sh --project-metadata --generated-by "draft:index"` to re-anchor `synced_to_commit`.
-
-**E. Re-run Condensation Subroutine** (condensation.md) to propagate updated hotspot data into `.ai-context.md` GRAPH:HOTSPOTS and recompute tier budget. If `.ai-profile.md` exists, regenerate via Profile Generation Subroutine.
-
-**F. Report per service:**
-```
-✓ <service>: refreshed 3 graph slots (module-deps, proto-map, hotspots)
-✓ <service>: regenerated .ai-context.md (tier N, {lines} lines)
-```
-
-## Step 9: Completion Report
-
-Remove the lockfile:
-
-```bash
-rm -f draft/.index-lock
-```
-
-```
----
-                    DRAFT INDEX COMPLETE
----
-Scanned: X service directories (depth=1)
-Indexed: Y services with draft/ context
-Skipped: Z uninitialized services
-
-Generated/Updated:
-  ✓ draft/service-index.md (service registry)
-  ✓ draft/dependency-graph.md (inter-service topology)
-  ✓ draft/tech-matrix.md (technology distribution)
-  ✓ draft/product.md (synthesized product vision)
-  ✓ draft/architecture.md (system-of-systems view)
-  ✓ draft/tech-stack.md (org standards)
-  ✓ draft/config.yaml (index configuration)
-
-Service manifests updated: Y services
-
-Next steps:
-1. Review synthesized files in draft/
-2. Edit draft/product.md to refine overall vision
-3. Edit draft/architecture.md to add cross-cutting context
-4. Run draft index periodically to refresh
-
-For uninitialized services, run:
-  draft index init-missing
----
-```
-
-## Operational Notes
-
-### What This Command Does NOT Do
-
-- **No deep code analysis** — Reads only existing `draft/*.md` files
-- **No source code scanning** — That's `draft init`'s job per service
-- **No recursive scanning** — Depth=1 only, immediate children
-- **No duplication** — Root files link to service files, not copy content
-
-### When to Re-Run
-
-- After running `draft init` on a new service
-- After significant changes to service architectures
-- Weekly/monthly as part of documentation hygiene
-- Before major cross-service planning
-
-### Preserving Manual Edits
-
-When regenerating, the skill:
-1. Reads existing root files
-2. Identifies manually-added sections (not marked as auto-generated)
-3. Preserves those sections while updating auto-generated parts
-4. Sections between `<!-- MANUAL START -->` and `<!-- MANUAL END -->` are never overwritten
-
-**Graph injection slots** (`<!-- GRAPH:...:START -->` / `<!-- GRAPH:...:END -->`) are ALWAYS overwritten during refresh — they are auto-managed. Never place manual content between these markers. Use `<!-- MANUAL START -->` / `<!-- MANUAL END -->` for content you want preserved near a slot.
-
----
-
 ## Graph Command
 
 When user says "build graph", "refresh graph", or "draft graph [path]":
 
-Initialize or refresh the `draft/graph/` knowledge-graph snapshot for a repository. This is the narrow "give me a fresh structural graph" command — it does **not** generate `architecture.md`/`.ai-context.md` (that is `draft init`) and does **not** re-inject doc diagram slots (that is `draft index`).
+Initialize or refresh the `draft/graph/` knowledge-graph snapshot for a single repository. This is the narrow "give me a fresh structural graph" command — it does **not** generate `architecture.md`/`.ai-context.md` and does **not** re-inject doc diagram slots (both are `draft init`). For scope-aware, root-first graph memory across a monorepo (root spine + module→root links), use `draft init --graph-only`.
 
 ## Red Flags - STOP if you're:
 
@@ -4068,7 +3279,7 @@ echo "Engine: $ENGINE"
 
 ## Step 3: Build / refresh the snapshot
 
-One call resolves the engine, indexes the repo (incrementally on refresh), and writes the committed snapshot under `<repo>/draft/graph/` — `schema.yaml`, `architecture.json`, `hotspots.jsonl`, `module-deps.mermaid`, `proto-map.mermaid`.
+One call resolves the engine, indexes the repo (incrementally on refresh), and updates the gate marker `<repo>/draft/graph/schema.yaml` (engine metadata + point-of-index counts; `access: engine-live`). All structural graph data is queried live from the engine — no snapshot files are committed beyond `schema.yaml`.
 
 ```bash
 scripts/tools/graph-snapshot.sh --repo "$REPO_ABS"
@@ -4105,7 +3316,7 @@ Present a concise summary:
 
 Then point the user at the natural next steps:
 
-- To re-inject the refreshed diagrams/hotspot tables into `architecture.md` / `.ai-context.md`: run `draft index`.
+- To re-inject the refreshed diagrams/hotspot tables into `architecture.md` / `.ai-context.md`: run `draft init refresh` (or `draft init --graph-only` to rebuild just the graph memory).
 - For a first-time full context bootstrap (architecture + profiles): run `draft init`.
 
 ## Graceful Degradation
@@ -4972,8 +4183,8 @@ You are decomposing a project or track into modules with clear responsibilities,
 
 When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. Module identification (Step 3) and dependency mapping (Step 4) **start from the graph**:
 
-1. Load `draft/graph/architecture.json` (`.packages`) for the authoritative module list and fan-in/out.
-2. Load `draft/graph/hotspots.jsonl` to identify candidate modules to split.
+1. Query `scripts/tools/graph-arch.sh --repo .` for the authoritative module list and fan-in/out.
+2. Run `scripts/tools/hotspot-rank.sh --repo .` to identify candidate modules to split.
 3. Use `scripts/tools/graph-callers.sh`/`graph-impact.sh` on demand for symbols/callers inside a candidate module.
 4. Run `scripts/tools/cycle-detect.sh --repo .` to enumerate existing cycles before proposing new boundaries.
 
@@ -5117,10 +4328,10 @@ ls -d src/*/ lib/*/ app/*/ packages/*/ 2>/dev/null
 
 When graph data is available, the graph is the **primary** (not optional) source for module discovery — manual scanning above is reserved for the graph-miss fallback path:
 
-- **Module boundaries**: Read `draft/graph/architecture.json` (`.packages`, `.languages`) — module list with node counts and per-language file counts
+- **Module boundaries**: Query `scripts/tools/graph-arch.sh --repo .` — module list with node counts and per-language file counts
 - **Dependency edges**: Weighted inter-module dependencies with exact include counts — replaces manual import tracing
 - **Cycle detection**: Circular dependency paths already computed — use for identifying tight coupling and decomposition candidates
-- **Hotspots**: Load `draft/graph/hotspots.jsonl` — high-complexity files that may need further decomposition
+- **Hotspots**: Run `scripts/tools/hotspot-rank.sh --repo .` — high-complexity files that may need further decomposition
 - **Per-module detail**: query `scripts/tools/graph-callers.sh`/`graph-impact.sh` for symbol/call detail within modules of interest
 
 This data is deterministic and exhaustive. The manual scanning recipes above only run **after** the graph misses on the concept the user named — and the miss must be reported in the Graph Usage Report footer. See [core/shared/graph-query.md](../../core/shared/graph-query.md) §Concept-to-Files Recipe.
@@ -5576,7 +4787,7 @@ When decomposition involves breaking a monolith, choosing module boundaries, or
 
 Before printing the completion announcement, internally verify and report:
 
-1. **Graph files queried** — which JSONL files were loaded (e.g. `architecture.json, hotspots.jsonl` and tools like `cycle-detect.sh`).
+1. **Graph data queried** — which live-engine tools were invoked (e.g. `get_architecture`, `hotspot-rank.sh`, `cycle-detect.sh`).
 2. **Layer 1 files deliberately skipped** — list any `.ai-context.md` sections, `tech-stack.md`, `product.md`, `workflow.md` you skipped as irrelevant to this decomposition. Be explicit; do not silently skip.
 3. **Filesystem grep fallback justification** — for every `grep`/`find` run, state the concept it searched for and quote the graph-miss sentence.
 4. **Citation Gate audit** — scan every Citation column in the generated component table, dependencies table, and LLD class table. Report:
@@ -5750,7 +4961,7 @@ If one of these applies, route directly to the specialist workflow and stop this
    - Keep matching invariants as **active constraints** for this task — these govern code generation, not just review
    - If invariants reference lock ordering, fail-closed behavior, or data integrity rules: these are non-negotiable during implementation
 9. **Load graph context** (if `draft/graph/schema.yaml` exists):
-   - Read `draft/graph/hotspots.jsonl` — check if any files this task will modify appear as hotspots
+   - Run `scripts/tools/hotspot-rank.sh --repo .` — check if any files this task will modify appear as hotspots
    - If modifying a hotspot file (high fanIn), warn: "This task modifies {file} (fanIn={N}). Changes here affect many downstream files. Consider running a graph impact query."
    - Query `scripts/tools/graph-impact.sh`/`graph-callers.sh` for the module(s) being modified — gives file-level dependency context
    - See `core/shared/graph-query.md` for on-demand query subroutines (callers, impact)
@@ -6759,8 +5970,8 @@ You are generating a pre-deployment verification checklist customized to this pr
 When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. Use the graph to validate module boundaries before the deploy:
 
 1. For each file in the deploy diff, run `scripts/tools/graph-impact.sh --repo . --file <path>` to enumerate the modules affected — flag any module **not** declared in `hld.md` §Detailed Design as a deployment-scope miss.
-2. Run `scripts/tools/cycle-detect.sh --repo .` (and read `draft/graph/architecture.json` for the module overview) to ensure no fresh cycles were introduced after HLD sign-off.
-3. Load `draft/graph/hotspots.jsonl` — any hotspot in the diff escalates the Resiliency row of Phase 0.
+2. Run `scripts/tools/cycle-detect.sh --repo .` (and query `scripts/tools/graph-arch.sh --repo .` for the module overview) to ensure no fresh cycles were introduced after HLD sign-off.
+3. Run `scripts/tools/hotspot-rank.sh --repo .` — any hotspot in the diff escalates the Resiliency row of Phase 0.
 
 Filesystem `grep` is reserved for source-text scans (migration file names, flag-key strings). Module/impact discovery goes through the graph.
 
@@ -7069,7 +6280,7 @@ Read and follow the base procedure in `core/shared/draft-context-loading.md`.
 - **Leverage Storage Topology** — Identify data loss risks at each tier (cache eviction without writeback, event log gaps, missing archive)
 - **Leverage Consistency Boundaries** — Find bugs at eventual consistency seams (stale reads, lost events, missing reconciliation)
 - **Leverage Failure Recovery Matrix** — Verify idempotency claims, check for partial failure states without recovery paths
-- **Leverage Graph Data** (if `draft/graph/` exists) — Read `architecture.json` (`.packages`) for dependency awareness. Flag dependencies on unexpected modules. Flag code in modules involved in dependency cycles as higher risk. Use `hotspots.jsonl` to prioritize analysis of high-complexity, high-fanIn files. See `core/shared/graph-query.md`.
+- **Leverage Graph Data** (if `draft/graph/` exists) — Query `scripts/tools/graph-arch.sh --repo .` for dependency awareness. Flag dependencies on unexpected modules. Flag code in modules involved in dependency cycles as higher risk. Run `scripts/tools/hotspot-rank.sh --repo .` to prioritize analysis of high-complexity, high-fanIn files. See `core/shared/graph-query.md`.
 - **Leverage Learned Anti-Patterns** — If `draft/guardrails.md` exists, read the `## Learned Anti-Patterns` section. During the bug sweep, when a bug matches a learned anti-pattern, prefix the report entry with `[KNOWN-ANTI-PATTERN: {pattern name}]`. This distinguishes recurring documented patterns from newly discovered bugs, and signals that a systemic fix may be needed rather than a one-off patch.
 
 ### 2. Confirm Scope
@@ -7095,6 +6306,19 @@ Use track context to:
 
 If no Draft context exists, proceed with code-only analysis.
 
+## Multi-Directory Mode (monorepo)
+
+`draft bughunt` can sweep multiple sub-projects in one run — useful at a monorepo root. Trigger it with an explicit directory list (`bughunt <dir1> <dir2> ...`) or no list (auto-discover).
+
+1. **Resolve targets:**
+   - **Explicit list** → use the given directories; verify each exists; skip (with a warning) any that lack a `draft/` directory.
+   - **Auto-discover** → immediate child directories containing a `draft/` folder, excluding `node_modules/`, `vendor/`, `.git/`, `draft/`, and dotfiles.
+2. **Run sequentially** (not in parallel — avoids context conflicts): for each target, run the full single-target bug hunt below scoped to that directory. Each writes its own `<dir>/draft/bughunt-report-latest.md`.
+3. **Aggregate** into `draft/bughunt-summary.md` at the invocation root: a table of `dir | Critical | High | Medium | Low | Total | report link`, a grand total, and a "directories with Critical issues" callout.
+4. Report skipped directories (no `draft/`) and suggest running `draft init` in them first.
+
+For a single target (the common case), skip this section and proceed.
+
 ## Dimension Applicability Check
 
 Before analyzing all 14 dimensions, determine which apply to this codebase:
@@ -8080,7 +7304,7 @@ You are conducting a code review using Draft's Context-Driven Development method
 
 When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. Stage 1 (Automated Validation) **starts from the graph**:
 
-1. Run blast-radius assessment from `draft/graph/hotspots.jsonl` and `scripts/tools/graph-impact.sh` (see Stage 1).
+1. Run blast-radius assessment via `scripts/tools/hotspot-rank.sh --repo .` and `scripts/tools/graph-impact.sh` (see Stage 1).
 2. For each changed file with non-trivial diff size, run `scripts/tools/graph-impact.sh --repo . --file <path>` to obtain the affected module set deterministically.
 3. For each public symbol modified, run `scripts/tools/graph-callers.sh --repo . --symbol <name>` to enumerate downstream callers before judging breaking-change severity.
 
@@ -8439,18 +7663,18 @@ For the files changed in the diff, perform static checks using `grep` or similar
 
 - **Blast Radius Assessment** (if the `draft/graph/` snapshot exists):
    - List all changed files from the diff
-   - For each changed file, check if it appears in `hotspots.jsonl` — if yes, record its `fanIn` value
-   - Classify: files with fanIn in the top 20% of the hotspots list = **HIGH IMPACT**; top 21–50% = **MEDIUM**; below 50% or not in list = **STANDARD**
-   - For any file in a HIGH or MEDIUM module, check `architecture.json` `.packages[].fan_in` (how many modules depend on this module)
+   - For each changed file, check if it appears in `scripts/tools/hotspot-rank.sh --repo .` output — if yes, record its `fanIn` value
+   - Classify: files with fanIn in the top 20% of the hotspot output = **HIGH IMPACT**; top 21–50% = **MEDIUM**; below 50% or not in output = **STANDARD**
+   - For any file in a HIGH or MEDIUM module, query `scripts/tools/graph-arch.sh --repo . | jq '.packages[].fan_in'` (how many modules depend on this module)
    - Include a `Blast Radius` line in the Stage 1 report summary: `Blast Radius: HIGH | MEDIUM | STANDARD — <N> changed files affect high-fanIn modules: [file list]`
    - If any changed file is HIGH IMPACT: escalate Stage 3 thoroughness (check all callers of changed functions) and note this in the report header
 - **Architecture Conformance:** Search for pattern violations documented in `draft/.ai-context.md`. (e.g. `import * from 'database'` in a React component).
 - **Dead Code:** Check for newly exported functions/classes in the diff that have 0 references across the codebase.
 - **Dependency Cycles:** Trace the import chains for new imports to ensure no circular dependencies (e.g., A → B → C → A) are introduced.
-- **Graph Boundary Check** (if `draft/graph/architecture.json` exists) `[RC-013]`:
+- **Graph Boundary Check** (if `draft/graph/schema.yaml` exists) `[RC-013]`:
    - For each changed file, identify its module from the graph
    - Check if any new cross-module includes were added in the diff
-   - Verify they follow the established dependency direction from `architecture.json` package fan-in/out
+   - Verify they follow the established dependency direction from `scripts/tools/graph-arch.sh --repo .` package fan-in/out
    - Flag reverse-direction dependencies (module A now depends on module B, but only B→A existed before) as "Potential architecture violation — new dependency direction"
    - Check if changes introduce files in modules listed in graph cycles — flag as higher risk
 - **Security Scan** `[RC-001, RC-002, RC-003, RC-011]`:
@@ -9144,7 +8368,7 @@ If Jira ticket linked, sync via `core/shared/jira-sync.md`:
 
 Before printing the final verdict, internally verify and report:
 
-1. **Graph files queried** — which JSONL files were loaded (e.g. `architecture.json, hotspots.jsonl`) plus any live graph query-tool invocations (impact, callers, cycles).
+1. **Graph data queried** — which live-engine tools were invoked (e.g. `get_architecture`, `hotspot-rank.sh`, `graph-impact.sh`, `graph-callers.sh`, `cycle-detect.sh`).
 2. **Layer 1 files deliberately skipped** — list any context sections skipped as irrelevant to the diff under review.
 3. **Filesystem grep fallback justification** — for every `grep`/`find` run, state the concept it searched for. Source-text scans (string literals, regex matches in code) are exempt — they are not symbol/file discovery.
 
@@ -9472,7 +8696,6 @@ When user says "discover debug" or "draft discover <intent>" (debug, bughunt, re
 - Code quality reviews (lightweight to exhaustive to architectural)
 - Coverage analysis and test strategy design
 - Discovering and codifying project conventions
-- Monorepo indexing and context aggregation
 - Project tours, impact analysis, or reviewer assistance
 
 ## Routing Logic
@@ -9488,7 +8711,6 @@ Strong keyword and phrase matching with fallback to a menu when intent is broad
 | coverage, code coverage, test coverage report | `draft coverage` | Coverage measurement and gap report |
 | test strategy, testing plan, coverage targets, pyramid | `draft testing-strategy` | Test approach design |
 | learn patterns, discover conventions, update guardrails, anti-patterns | `draft learn` | Pattern mining + guardrail evolution |
-| index services, aggregate context, monorepo index | `draft index` | Monorepo service context aggregation |
 | tour, walkthrough, onboard me, getting started tour | `draft tour` | Guided interactive project tour |
 | blast radius, code impact, affected modules, downstream callers | `draft review` or `scripts/tools/graph-impact.sh` | Graph-derived blast-radius before merge |
 | impact, delivery telemetry, track analytics, CDD effectiveness | `draft impact` | Project-wide track delivery telemetry |
@@ -9514,7 +8736,7 @@ User: "learn the coding patterns in this repo and tighten guardrails"
 
 User: "index the monorepo so agents see all services"
 
-→ dispatches to `draft index --init-missing`
+→ Monorepo context is a foundation task, not a discover route: run `draft init` at the repo root (it builds the whole-repo code graph + a sparse root map linking each module). Running `draft init` inside a sub-module links that module up to the same root graph.
 
 ## Auto-Chains & Recommendations
 
@@ -11489,7 +10711,7 @@ You are performing a lightweight, ad-hoc code review. This is the fast alternati
 
 When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. Quick-review keeps the graph load light:
 
-1. Always check `draft/graph/hotspots.jsonl` for every changed file (Step 2 blast-radius pre-check below).
+1. Always run `scripts/tools/hotspot-rank.sh --repo .` for every changed file (Step 2 blast-radius pre-check below).
 2. If a finding spans more than one file, run `scripts/tools/graph-callers.sh --repo . --symbol <name>` to enumerate the call sites before claiming "no other usages".
 
 Filesystem `grep` is reserved for source-text scans (literal strings, regex patterns). Symbol and caller discovery go through the graph.
@@ -11546,9 +10768,9 @@ Determine the diff to review:
 3. If commit range: `git diff <range>`
 4. Default: `git diff HEAD~1..HEAD` (last commit)
 
-## Step 2: Blast Radius Pre-check (if `draft/graph/hotspots.jsonl` exists)
+## Step 2: Blast Radius Pre-check (if `draft/graph/schema.yaml` exists)
 
-Before the four-dimension review, check if any files in scope appear in `draft/graph/hotspots.jsonl`. If any file has a `fanIn` in the top 20% of the list, add this warning at the top of the review report:
+Before the four-dimension review, run `scripts/tools/hotspot-rank.sh --repo .` and check if any files in scope appear in the output. If any file has a `fanIn` in the top 20% of the list, add this warning at the top of the review report:
 
 ```
 ⚠ HIGH IMPACT: {file} is a high-fanIn hotspot (fanIn={N}). Changes here propagate to many callers — review with extra care.
@@ -11705,10 +10927,10 @@ Perform an exhaustive end-to-end lifecycle review of a service, component, or mo
 
 When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. Deep-review uses the graph to **narrow review scope** — a key 30–50% scope reduction:
 
-1. Use `scripts/tools/graph-impact.sh`/`graph-callers.sh` and `architecture.json` for the audited module's structure — do not enumerate via `find`.
+1. Use `scripts/tools/graph-impact.sh`/`graph-callers.sh` and `scripts/tools/graph-arch.sh --repo .` for the audited module's structure — do not enumerate via `find`.
 2. Run `scripts/tools/graph-impact.sh --repo . --file <each-changed-file>` per file in the diff (or per file in the module if no diff) to obtain the affected module set deterministically.
 3. Run `scripts/tools/cycle-detect.sh --repo .` and flag any cycle that includes the audited module as Architecture Resilience finding.
-4. Cross-check `draft/graph/hotspots.jsonl` to identify high-fanIn files inside the module — these get deeper inspection.
+4. Run `scripts/tools/hotspot-rank.sh --repo .` to identify high-fanIn files inside the module — these get deeper inspection.
 
 Filesystem `grep` is reserved for source-text scans (API contract strings, secret patterns, log message audits). Module enumeration and caller tracing go through the graph.
 
@@ -12226,8 +11448,8 @@ Scan the codebase to discover recurring coding patterns and update `draft/guardr
 
 When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. Use the graph to:
 
-1. Enumerate a module's symbols/files via `scripts/tools/graph-callers.sh`/`graph-impact.sh` and `architecture.json` (preferred over `find`).
-2. Prioritize hotspots from `draft/graph/hotspots.jsonl` — patterns in high-fanIn files are more impactful when learned.
+1. Enumerate a module's symbols/files via `scripts/tools/graph-callers.sh`/`graph-impact.sh` and `scripts/tools/graph-arch.sh --repo .` (preferred over `find`).
+2. Prioritize hotspots via `scripts/tools/hotspot-rank.sh --repo .` — patterns in high-fanIn files are more impactful when learned.
 3. For TS/Python/Go/C/C++, use `*-index.jsonl` to identify class/function definitions rather than re-discovering them via regex.
 
 Filesystem `find` for source discovery (Step 2.1) is permitted **as a complement** to the graph for languages not covered by indexes (e.g. Ruby, Java without ctags). Record the rationale in the Graph Usage Report.
@@ -12461,15 +11683,15 @@ git log --follow --oneline -1 -- {file_containing_pattern}
 
 ### 2.7: Graph-Aware Severity Enrichment
 
-If `draft/graph/hotspots.jsonl` exists, derive objective severity for all anti-pattern candidates based on the fanIn of files where the pattern was found.
+If `draft/graph/schema.yaml` exists (engine live), derive objective severity for all anti-pattern candidates based on the fanIn of files where the pattern was found via `scripts/tools/hotspot-rank.sh --repo .`.
 
 For each anti-pattern candidate from Step 2.2:
-1. Check if any evidence files appear in `draft/graph/hotspots.jsonl`
+1. Check if any evidence files appear in the hotspot output from `scripts/tools/hotspot-rank.sh --repo .`
 2. Take the highest fanIn value across all evidence files:
    - fanIn ≥ 10 → `graph_severity: critical` (breakage propagates to many callers)
    - fanIn 5–9 → `graph_severity: high`
    - fanIn 1–4 → `graph_severity: medium`
-   - fanIn 0 or file not in hotspots.jsonl → `graph_severity: low`
+   - fanIn 0 or file not in hotspot output → `graph_severity: low`
 3. If no graph data exists → `graph_severity: unresolved`
 
 Collect all evidence files with fanIn ≥ 5 for the `high_fanin_files` field.
@@ -13078,10 +12300,10 @@ You are conducting a structured debugging session following systematic investiga
 
 When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. During Steps 3–4 (Isolate, Diagnose):
 
-1. Locate the suspect file's module via `draft/graph/architecture.json` (`.packages`) before tracing data flow.
+1. Locate the suspect file's module via `scripts/tools/graph-arch.sh --repo .` before tracing data flow.
 2. Use `scripts/tools/graph-callers.sh --repo . --symbol <fn>` to enumerate call sites of suspect functions — not `grep`.
 3. Use `scripts/tools/graph-impact.sh --repo . --file <path>` to size the blast radius before proposing a fix.
-4. Cross-check `draft/graph/hotspots.jsonl` to know whether the file is high-fanIn (any fix needs extra caution).
+4. Run `scripts/tools/hotspot-rank.sh --repo .` to know whether the file is high-fanIn (any fix needs extra caution).
 
 Filesystem `grep` is reserved for source-text scans (literal error strings, stack-trace symbols when the graph misses). Use the fallback sentence on graph miss.
 
@@ -13129,7 +12351,7 @@ Key context for debugging:
 - `.ai-context.md` — Module boundaries, data flows, invariants (crucial for tracing)
 - `tech-stack.md` — Language-specific debugging tools and techniques
 - `guardrails.md` — Known anti-patterns that may be causing the issue
-- `draft/graph/` (MANDATORY when present) — Load `architecture.json` for dependency/module context and `hotspots.jsonl` for complexity awareness. Use `scripts/tools/graph-callers.sh --repo . --symbol <fn>` to find all callers, and `scripts/tools/graph-impact.sh --repo . --file <path>` to size blast radius before any fix. See [core/shared/graph-query.md](../../core/shared/graph-query.md).
+- `draft/graph/` (MANDATORY when present) — Query `scripts/tools/graph-arch.sh --repo .` for dependency/module context and `scripts/tools/hotspot-rank.sh --repo .` for complexity awareness. Use `scripts/tools/graph-callers.sh --repo . --symbol <fn>` to find all callers, and `scripts/tools/graph-impact.sh --repo . --file <path>` to size blast radius before any fix. See [core/shared/graph-query.md](../../core/shared/graph-query.md).
 
 ## Step 1: Parse Arguments
 
@@ -13462,8 +12684,8 @@ You are conducting a technical debt analysis to catalog, prioritize, and plan re
 
 When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. Tech-debt prioritization is fundamentally driven by graph data:
 
-1. Load `draft/graph/hotspots.jsonl` — **rank candidates by `fanIn × complexity`** to surface high-leverage debt first.
-2. Read `draft/graph/architecture.json` (`.packages`) and run `scripts/tools/cycle-detect.sh --repo .` — flag debt in modules involved in cycles as higher priority.
+1. Run `scripts/tools/hotspot-rank.sh --repo .` — **rank candidates by `fanIn × complexity`** to surface high-leverage debt first.
+2. Query `scripts/tools/graph-arch.sh --repo .` and run `scripts/tools/cycle-detect.sh --repo .` — flag debt in modules involved in cycles as higher priority.
 3. Run `scripts/tools/cycle-detect.sh --repo .` to enumerate dependency cycles — every cycle is a candidate architecture-debt entry.
 4. For each catalogued finding, run `scripts/tools/graph-impact.sh --repo . --file <path>` so the remediation plan includes blast-radius.
 
@@ -15180,7 +14402,7 @@ Draft solves this through **Context-Driven Development**: structured documents t
 - [Command Workflows](#command-workflows)
   - [draft init](#draftinit--initialize-project)
   - [draft plan](#draftplan--planning-orchestrator)
-  - [draft index](#draftindex--monorepo-service-index)
+  - [Monorepo Support (via draft init)](#monorepo-support-via-draftinit)
   - [draft new-track](#draftnew-track--create-feature-track)
   - [draft implement](#draftimplement--execute-tasks)
   - [draft status](#draftstatus--show-progress)
@@ -15555,7 +14777,7 @@ Draft auto-classifies the project:
 - **Brownfield (existing codebase):** Detected by the presence of `package.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, `src/`, or git history with commits. Draft scans the existing stack and pre-fills `tech-stack.md`.
 - **Greenfield (new project):** Empty or near-empty directory. Developer provides all context through dialogue.
 - **Mature high-context brownfield:** Projects with strong existing agent-optimized docs (CLAUDE.md, INVARIANTS.md, ADRs, etc.) now receive an early Context Quality Audit, graph fidelity declaration, and explicit Relationship/Gaps sections so the generated architecture.md acts as graph-primary overlay rather than duplicative prose.
-- **Monorepo:** Detected by `lerna.json`, `pnpm-workspace.yaml`, `nx.json`, `turbo.json`, or multiple package manifests in child directories. Suggests `draft index` instead.
+- **Monorepo:** Detected by `lerna.json`, `pnpm-workspace.yaml`, `nx.json`, `turbo.json`, or multiple package manifests in child directories. `draft init` is scope-aware — run it at the root for whole-repo context (sparse root map + the code-graph spine), or inside a sub-module to generate detailed module context that links up to the root graph. See **Monorepo Support (via draft init)** below.
 
 #### Initialization Sequence
 
@@ -15649,32 +14871,31 @@ The parent command should move planning forward rather than listing options.
 
 ---
 
-### `draft index` — Monorepo Service Index
+### Monorepo Support (via `draft init`)
 
-Aggregates Draft context from multiple services in a monorepo into unified root-level documents. Designed for organizations with multiple services, each with their own `draft/` context.
+There is no separate index command — `draft init` is the single, scope-aware entry point. The same command behaves differently by where it is run, so a monorepo needs no special tooling.
 
-#### What It Does
+#### Root init (run at the repo root)
 
-1. **Scans** immediate child directories for services (detects `package.json`, `go.mod`, `Cargo.toml`, etc.)
-2. **Reads** each service's `draft/product.md`, `draft/.ai-context.md` (or legacy `draft/architecture.md`), `draft/tech-stack.md`
-3. **Synthesizes** root-level documents:
+1. **Builds the whole-repo code-graph spine** — `graph-init.sh` indexes every file at every depth into one unified graph and writes the committed `draft/graph/` snapshot (the structural source of truth).
+2. **Generates a sparse root map** (not deep per-module prose), aggregating the children into root-level documents:
    - `draft/service-index.md` — Service registry with status, tech, and links
-   - `draft/dependency-graph.md` — Inter-service dependency topology
+   - `draft/dependency-graph.md` — Inter-service dependency topology (from the graph)
    - `draft/tech-matrix.md` — Technology distribution across services
-   - `draft/product.md` — Synthesized product vision (if not exists)
-   - `draft/.ai-context.md` — System-of-systems architecture view
-   - `draft/tech-stack.md` — Org-wide technology standards
+   - `draft/architecture.md` — High-level system map linking *down* to each module's `draft/.ai-context.md`
+   - `draft/.ai-context.md` / `draft/.ai-profile.md` — Condensed system-of-systems views
 
-#### Arguments
+#### Module init (run inside a sub-module)
 
-- `init-missing` — Run `draft init` on services that lack a `draft/` directory
-- `bughunt [dir1 dir2 ...]` — Run `draft bughunt` across subdirectories with `draft/` folders. If no directories specified, auto-discovers all subdirectories with `draft/`. Generates summary report at `draft-index-bughunt-summary.md`.
+1. **Ensures the root spine exists first** (builds it if missing), then builds the module's own `draft/graph/` snapshot.
+2. **Writes `draft/graph/root-link.json`** — a pointer up to the root graph so the module has full cross-module understanding regardless of where init ran.
+3. **Generates the detailed module reference** (full 10-section `architecture.md` for the subtree). Use `--module-only` to skip touching the root (link marked `pending`).
 
 #### When to Use
 
-- After running `draft init` on individual services
-- After adding or removing services from the monorepo
-- Periodically to refresh cross-service context
+- After cloning or adding a service — run `draft init` in it (auto-links to the root spine)
+- At the root after services change — refresh the whole-repo graph + sparse root map
+- `draft init --graph-only` to (re)build just the code-graph knowledge memory, no markdown
 
 ---
 
@@ -16554,7 +15775,7 @@ This matrix is the **single source of truth** for which Layer 0.5 files load per
 
 | Command type | Commands | Guardrails loaded |
 |---|---|---|
-| **Read-only** | `draft status`, `draft standup`, `draft tour`, `draft index`, `draft coverage` | **none** |
+| **Read-only** | `draft status`, `draft standup`, `draft tour`, `draft coverage` | **none** |
 | **Spec / Plan** | `draft new-track`, `draft decompose`, `draft adr`, `draft testing-strategy`, `draft documentation` | `design-norms.md` only (architecture-shaped rules) |
 | **Code-touching (generation)** | `draft implement`, `draft debug`, `draft change`, `draft revert` | `code-quality.md` + `security.md` + `secure-patterns.md` + `language-standards.md` (detected stack) |
 | **Review** | `draft review`, `draft quick-review`, `draft deep-review`, `draft assist-review`, `draft bughunt`, `draft tech-debt` | `review-checks.md` + `security.md` + `language-standards.md` (detected stack); deep-review also loads `code-quality.md` + `design-norms.md` |
@@ -16587,13 +15808,11 @@ If `draft/graph/schema.yaml` exists, the project has automated graph analysis da
 
 | File | Purpose | Content |
 |------|---------|---------|
-| `draft/graph/schema.yaml` | Snapshot metadata (engine, project, node/edge counts) | YAML, ~15 lines |
-| `draft/graph/architecture.json` | Node labels, edge types, languages, packages (fan-in/out), entry points, routes, hotspots | JSON |
-| `draft/graph/hotspots.jsonl` | Fan-in-ranked symbols, one object per line: `{id, name, fanIn}` | JSONL |
+| `draft/graph/schema.yaml` | Gate marker (engine + project metadata + point-of-index counts); presence gates graph use | YAML, ~15 lines |
 
-Note: `.ai-context.md` embeds a condensed graph summary (`GRAPH:MODULES`, `GRAPH:HOTSPOTS`, `GRAPH:CYCLES`) for first-pass structural ground truth. `architecture.json` is authoritative for deep structure.
+Note: `.ai-context.md` embeds a condensed graph summary (`GRAPH:MODULES`, `GRAPH:HOTSPOTS`, `GRAPH:CYCLES`) for first-pass structural ground truth. Deep structural data is queried live from the engine (see Live structural queries below).
 
-Note: The canonical embedded mermaid diagrams are in architecture.md injection slots (`<!-- GRAPH:module-deps:START/END -->`, `<!-- GRAPH:proto-map:START/END -->`), refreshed by `draft:index`. For current data, regenerate via `scripts/tools/mermaid-from-graph.sh`.
+Note: The canonical embedded mermaid diagrams are in architecture.md injection slots (`<!-- GRAPH:module-deps:START/END -->`, `<!-- GRAPH:proto-map:START/END -->`), refreshed by `draft:init`. For current data, regenerate via `scripts/tools/mermaid-from-graph.sh`.
 
 **Live structural queries** (run on demand — no per-language index files; the engine's model is unified):
 
@@ -16665,12 +15884,12 @@ Do NOT apply relevance scoring for commands that need full context (`draft init`
 | `## FILES` | Always (need file locations) |
 | `## VOCAB` | Domain-specific tasks |
 
-3. **Score graph files** (if `draft/graph/` exists) against the task concepts:
+3. **Score graph queries** (if `draft/graph/schema.yaml` exists) against the task concepts:
 
 | Graph source | Use When Task Involves... |
 |------------|--------------------------|
-| `architecture.json` | Module boundary changes, cross-module work, architecture analysis, API/route surface |
-| `hotspots.jsonl` | Performance work, refactoring, changes to high-fanIn symbols |
+| `scripts/tools/graph-arch.sh --repo .` | Module boundary changes, cross-module work, architecture analysis, API/route surface |
+| `scripts/tools/hotspot-rank.sh --repo .` | Performance work, refactoring, changes to high-fanIn symbols |
 | `scripts/tools/graph-callers.sh --symbol <name>` | Enumerating callers before a change |
 | `scripts/tools/graph-impact.sh --file <path>` / `--symbol <name>` | Tracing call paths, root cause analysis, function-level impact |
 | `scripts/tools/cycle-detect.sh` | Checking for call cycles |
@@ -17031,11 +16250,11 @@ Append under `## Learned Anti-Patterns`:
 - **Suggested fix:** [Brief description of the correct approach]
 ```
 
-`graph_severity` derivation rules (from `draft/graph/hotspots.jsonl` fanIn values):
+`graph_severity` derivation rules (from live hotspot query `scripts/tools/hotspot-rank.sh --repo .` fanIn values):
 - fanIn ≥ 10 in any evidence file → `critical`
 - fanIn 5–9 → `high`
 - fanIn 1–4 → `medium`
-- fanIn 0 or file not in hotspots.jsonl → `low`
+- fanIn 0 or file not returned by hotspot query → `low`
 - Graph data absent → `unresolved`
 
 When `graph_severity` differs from `severity`, use `graph_severity` as the enforcement priority — it is objective and graph-derived.
@@ -17093,7 +16312,7 @@ This is a self-contained, callable procedure for generating `draft/.ai-context.m
 
 Any skill that mutates `architecture.md` should execute this subroutine afterward to keep the derived context files in sync.
 
-**Called by:** `draft init`, `draft init refresh`, `draft implement`, `draft decompose`, `draft coverage`, `draft index`
+**Called by:** `draft init`, `draft init refresh`, `draft implement`, `draft decompose`, `draft coverage`
 
 ### Inputs
 
@@ -17165,16 +16384,16 @@ Transform each `architecture.md` section into machine-optimized format using thi
 
 #### Step 3.5: Generate Graph Summary Sections
 
-If `draft/graph/schema.yaml` exists, generate these sections from the snapshot (`draft/graph/architecture.json`, `draft/graph/hotspots.jsonl`) and the live query tools:
+If `draft/graph/schema.yaml` exists, generate these sections via live engine queries.
 
 **GRAPH:MODULES** (tier ≥ 2 only):
-- Read `draft/graph/architecture.json` → `.packages[]` (each has `name`, `node_count`, `fan_in`, `fan_out`)
+- Query: `scripts/tools/graph-arch.sh --repo . | jq '.packages[]'` (each has `name`, `node_count`, `fan_in`, `fan_out`)
 - Format: `{name}|{node_count} nodes|fan_in:{fan_in} fan_out:{fan_out}`
 - Order by `node_count` descending
 - Omit this section entirely for tier-1 codebases (≤5 modules) where Component Graph is sufficient
 
 **GRAPH:HOTSPOTS** (all tiers):
-- Read `draft/graph/hotspots.jsonl` (already fan-in-ranked), take top 10
+- Query: `scripts/tools/hotspot-rank.sh --repo . --top 10`; take top 10 results
 - Format: `{name}|fanIn:{fanIn}` (use `id` for disambiguation when names collide)
 - Always include regardless of tier
 
@@ -17185,20 +16404,20 @@ If `draft/graph/schema.yaml` exists, generate these sections from the snapshot (
 - Always include — absence is positive signal that the call graph is acyclic
 
 **GRAPH:MODULE-HOTSPOTS** (tier ≥ 3 only):
-- Read `draft/graph/hotspots.jsonl`; group by the package segment of each `id` (the qualified name minus the leaf symbol)
+- Query: `scripts/tools/hotspot-rank.sh --repo .`; group results by the package segment of each `id` (the qualified name minus the leaf symbol)
 - For each module: take its top 3 symbols by `fanIn`, format as indented lines under the module name
 - Format: `{module}: {name}|fanIn:{N}` with subsequent symbols indented to align
 - Order modules by their highest-fanIn symbol, descending
 - Omit modules with no hotspot entries; omit entire section for tier 1–2 (covered by global GRAPH:HOTSPOTS)
 
 **GRAPH:FAN-IN** (tier ≥ 3 only):
-- Read `architecture.json` → `.packages[]`, use the `fan_in` field per module
+- Query: `scripts/tools/graph-arch.sh --repo . | jq '.packages[]'`, use the `fan_in` field per module
 - Format: `{name}|fanIn:{fan_in}|fanOut:{fan_out}`
 - Order by `fan_in` descending; include only modules with `fan_in ≥ 2`; cap at 15 rows
 - Omit entire section for tier 1–2 (trivially small graph)
 
-**GRAPH:PROTO-MAP** (only when `architecture.json` `.routes` is non-empty):
-- Read `architecture.json` → `.routes[]` (each has `method`, `path`, `handler`)
+**GRAPH:PROTO-MAP** (only when routes are non-empty):
+- Query: `scripts/tools/graph-arch.sh --repo . | jq '.routes[]'` (each has `method`, `path`, `handler`)
 - Format: `{method} {path} → {handler}`
 - One line per route
 - Omit entire section if `.routes` is empty — do not write an empty section
@@ -17245,7 +16464,7 @@ Before writing `draft/.ai-context.md`, verify:
 - [ ] GRAPH:CYCLES present ("None ✓" or cycle list; or note if graph absent)
 - [ ] GRAPH:MODULE-HOTSPOTS present for tier ≥ 3 (or note if no hotspot data)
 - [ ] GRAPH:FAN-IN present for tier ≥ 3
-- [ ] GRAPH:PROTO-MAP present when `stats.proto_rpcs > 0` (omit entirely if no protos)
+- [ ] GRAPH:PROTO-MAP present when engine reports non-empty routes (omit entirely if no protos)
 - [ ] YAML frontmatter metadata is present at the top
 
 #### Step 7: Write Output
@@ -17629,13 +16848,13 @@ Shared procedure for querying the knowledge graph from any skill. The graph prov
 
 This is the **single source of truth** for graph lookup procedure. Consumer skills MUST reference this file rather than inlining their own lookup logic.
 
-Referenced by: `draft init`, `draft implement`, `draft bughunt`, `draft review`, `draft deep-review`, `draft quick-review`, `draft debug`, `draft decompose`, `draft new-track`, `draft tech-debt`, `draft deploy-checklist`, `draft learn`, `draft index`
+Referenced by: `draft init`, `draft implement`, `draft bughunt`, `draft review`, `draft deep-review`, `draft quick-review`, `draft debug`, `draft decompose`, `draft new-track`, `draft tech-debt`, `draft deploy-checklist`, `draft learn`, `draft graph`
 
 ## Mandatory Lookup Contract
 
 Any code-touching skill that needs to discover files, modules, symbols, callers, or blast-radius **MUST** follow this lookup order whenever `draft/graph/schema.yaml` exists:
 
-1. **Graph first** — the committed snapshot (`architecture.json`, `hotspots.jsonl`) and the live query tools (`scripts/tools/graph-callers.sh`, `graph-impact.sh`, `cycle-detect.sh`, `hotspot-rank.sh`).
+1. **Graph first** — live engine queries via the query tools (`scripts/tools/graph-callers.sh`, `graph-impact.sh`, `cycle-detect.sh`, `hotspot-rank.sh`, `mermaid-from-graph.sh`), which drive the local `codebase-memory-mcp` engine on demand. Draft is **engine-only**: there is no committed machine-readable graph to read — `draft/graph/` holds only `schema.yaml` (the gate marker).
 2. **Generated context second** — `draft/.ai-context.md`, relevant `draft/architecture.md` slices, track-level `hld.md`/`lld.md`.
 3. **Source file reads third** — narrow via tiers 1–2, then **Read** the candidate files. Reading is **not optional**: see §Ground-Truth Discipline below.
 4. **Filesystem `grep`/`find`/`rg` last** — only after an explicit graph miss.
@@ -17680,10 +16899,10 @@ A single "no" / "list" answer is a halt — fix and re-check before output.
 
 Use this recipe whenever the user names a concept, feature, or domain term ("in-memory shuffle", "auth flow", "ingest pipeline") and you need to locate the implementing files. **Run it before any filesystem search.**
 
-1. **Concept → modules** — `grep` the concept token against `draft/graph/architecture.json` (`.packages[].name`) and `draft/.ai-context.md` (module headings). Record the candidate module list.
+1. **Concept → modules** — query the engine for the package list (`scripts/tools/graph-arch.sh --repo . | jq -r '.packages[].name'`) and cross-reference `draft/.ai-context.md` (module headings). Record the candidate module list.
 2. **Concept → symbols/callers** — for a named function, run `scripts/tools/graph-callers.sh --repo . --symbol <name>` to find call sites, and `scripts/tools/graph-impact.sh --repo . --symbol <name>` for transitive dependents. These are the authoritative structural answers.
-3. **Modules → risk ranking** — cross-reference `draft/graph/hotspots.jsonl` (or `scripts/tools/hotspot-rank.sh`). High-fanIn symbols are the most likely entry points for impact.
-4. **Concept → public API** — for API-shaped concepts, consult `architecture.json` `.routes` (detected HTTP/gRPC/GraphQL routes) for matching service surface.
+3. **Modules → risk ranking** — rank with `scripts/tools/hotspot-rank.sh --repo . [--top N]`. High-fanIn symbols are the most likely entry points for impact.
+4. **Concept → public API** — for API-shaped concepts, read the engine's `.routes` (`get_architecture` output, detected HTTP/gRPC/GraphQL routes) for matching service surface.
 5. **Graph miss → grep fallback** — only if steps 1–4 return nothing relevant, emit the fallback sentence and use `grep`/`find`. Narrow the search by file extension and exclude `node_modules`, `vendor`, `dist`, `build`, `.git`.
 
 ## Graph Usage Report (Mandatory Footer)
@@ -17693,7 +16912,7 @@ Every code-touching skill output MUST end with this footer block. The lint check
 ```md
 ## Graph Usage Report
 
-- Graph files queried: <comma-separated list, e.g. `architecture.json, hotspots.jsonl` and/or query tools like `graph-callers.sh` — or `NONE` with justification below>
+- Graph files queried: <comma-separated list of query tools invoked, e.g. `graph-callers.sh, hotspot-rank.sh` — or `NONE` with justification below>
 - Modules identified via graph: <comma-separated module names, or `none`>
 - Files identified via graph: <integer count>
 - Filesystem grep fallbacks: <list of `<pattern>` searches with one-line justification each, or `none`>
@@ -17731,7 +16950,7 @@ DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
 | `bash "$DRAFT_TOOLS/cycle-detect.sh"` | `--mode cycles` | Emits `{cycles:[],source:"unavailable"}` and exits 2 |
 | `bash "$DRAFT_TOOLS/mermaid-from-graph.sh" [--diagram module-deps\|proto-map]` | `--mode mermaid` | Emits an empty mermaid block and exits 2 |
 
-Use the raw `graph` CLI directly for the lower-level modes documented below.
+For lower-level modes, call the engine directly: `codebase-memory-mcp cli <tool> '<json>'` (see the tool list in [bin/README.md](../../bin/README.md)).
 
 ## Pre-Check
 
@@ -17743,26 +16962,26 @@ ls draft/graph/schema.yaml 2>/dev/null
 
 If absent, **skip all graph operations silently**. Graph enriches analysis — it never gates it. All skills must work identically without graph data.
 
-## Engine + snapshot model
+## Engine model (engine-only)
+
+The graph is produced by the **codebase-memory-mcp** engine (a single binary; see [bin/README.md](../../bin/README.md)). Draft is **engine-only and opinionated**: the engine is the one structural source of truth, queried live. There is **no committed machine-readable mirror** of the graph — no `architecture.json`, `hotspots.jsonl`, `*.mermaid`, or `okf/`. Those were lossy, went stale on the next commit, and duplicated what the engine serves precisely on demand.
 
-The graph is produced by the **codebase-memory-mcp** engine (a single binary; see [bin/README.md](../../bin/README.md)). There are two ways skills consume it:
+The only committed file is the gate marker:
 
-1. **Live queries** (preferred when the engine is resolvable) — the shell tools under `scripts/tools/` drive the engine on demand (it auto-indexes into its own cache). No committed files required.
-2. **Committed snapshot** (`draft/graph/`) — a small, derived, PR-reviewable snapshot written by `scripts/tools/graph-snapshot.sh`. It exists for reviewability and for the Copilot/Gemini integrations, which cannot run the engine but can read committed files. Git remains the source of truth.
+| File | Role |
+|------|------|
+| `draft/graph/schema.yaml` | Engine + project metadata and point-of-index counts (provenance, not authoritative). Carries **no graph data**. Its presence is the **gate** (see Pre-Check) — it signals the engine is wired for this repo. Written by `scripts/tools/graph-snapshot.sh`. |
 
-When `draft/graph/` exists, the snapshot contains:
+All structural data is obtained live by shelling out to the engine — either through the query-tool wrappers under `scripts/tools/` or directly via `codebase-memory-mcp cli <tool> '<json>'`. The shell tools auto-index the repo into the engine's own cache on demand, so no committed files are required.
 
-| File | Load | Content |
-|------|------|---------|
-| `schema.yaml` | Always | Engine + project metadata, node/edge counts, artifact list. Its presence **gates** graph use (see Pre-Check). |
-| `architecture.json` | Always | `get_architecture(all)` output: node labels, edge types, languages, packages (with fan-in/out), entry points, routes, hotspots. |
-| `hotspots.jsonl` | Always | Fan-in-ranked symbols, one JSON object per line: `{id, name, fanIn}`. |
-| `module-deps.mermaid` | Diagram injection | File co-change coupling diagram (`FILE_CHANGES_WITH`). |
-| `proto-map.mermaid` | Diagram injection | Detected service-route diagram (`Route` nodes). |
+### How skills query (engine is the interface; jq is optional)
 
-The engine uses a **unified, language-agnostic** node model — `Function`, `Method`, `Class`, `Module`, `File`, `Folder`, `Route`, `Section`, `Variable` (language is inferred from file extension) — and edges `CALLS`, `DEFINES`, `CONTAINS_FILE`, `IMPORTS`, `HTTP_CALLS`, `FILE_CHANGES_WITH`, `SEMANTICALLY_RELATED`, `SIMILAR_TO`. There are **no** per-language index files and no `ctags-sym` fallback; that detail is served by live queries against the unified model.
+- **The engine is the query.** `codebase-memory-mcp cli <tool> '<json>'` (and the wrappers that call it) is how you ask — it takes JSON args and returns JSON. There is no other query surface.
+- **Prefer the wrappers — they resolve the engine for you.** `graph-arch.sh` (architecture view: packages/routes/layers/hotspots), `graph-callers.sh`, `hotspot-rank.sh`, `graph-impact.sh`, `cycle-detect.sh`, `mermaid-from-graph.sh` return already-shaped JSON. The engine binary is usually **not on `$PATH`** (it lives under `~/.cache/draft/bin/`); the wrappers locate it via `_lib.sh:find_memory_bin`, so a skill using a wrapper needs no resolution step.
+- **Raw `codebase-memory-mcp cli` requires resolving the binary first** (it is not on `$PATH`): `CM="${DRAFT_MEMORY_BIN:-$HOME/.cache/draft/bin/codebase-memory-mcp}"; "$CM" cli <tool> '<json>'`. Reach for this only for tools without a wrapper (`search_graph`, `search_code`, `trace_path`).
+- **`jq` is not a query tool — it only trims output.** Reach for it solely to slice a *large* response (chiefly the `get_architecture` blob) down to the field you need, for token economy. The agent can read raw JSON directly; jq is an optimization, not a requirement. Don't pipe wrapper output through jq unless you genuinely need a sub-field.
 
-**Always-load files** are compact and should be read during context loading for any task that touches code structure.
+The engine uses a **unified, language-agnostic** node model — `Function`, `Method`, `Class`, `Module`, `File`, `Folder`, `Route`, `Section`, `Variable` (language is inferred from file extension) — and edges `CALLS`, `DEFINES`, `CONTAINS_FILE`, `IMPORTS`, `HTTP_CALLS`, `FILE_CHANGES_WITH`, `SEMANTICALLY_RELATED`, `SIMILAR_TO`. Each node carries `file_path` + `start_line`/`end_line` and rich `properties` (complexity, signature, parent_class), and the engine exposes full-text (`search_code`) and semantic search — none of which a committed snapshot reproduced.
 
 ## Query Tools
 
@@ -17803,7 +17022,14 @@ Output: `{cycles[[a,b],[a,b,c]], source}` — fixed-length 2- and 3-node `CALLS`
 
 ### Modules — dependency overview
 
-Read `draft/graph/architecture.json` (`.packages` for module fan-in/out, `.node_labels`/`.edge_types` for shape, `.routes` for service surface), or regenerate it with `scripts/tools/graph-snapshot.sh --repo .`.
+Query the engine's architecture view live with the `graph-arch.sh` wrapper (it resolves the engine, indexes on demand, and auto-resolves the project):
+
+```bash
+scripts/tools/graph-arch.sh --repo . \
+  | jq '{packages, node_labels, edge_types, routes, layers, boundaries}'
+```
+
+`.packages` gives module fan-in/out, `.node_labels`/`.edge_types` the shape, `.routes` the service surface, `.layers`/`.boundaries` the dependency direction.
 
 ### Mermaid — diagram text
 
@@ -17812,15 +17038,15 @@ scripts/tools/mermaid-from-graph.sh --repo . --diagram module-deps   # co-change
 scripts/tools/mermaid-from-graph.sh --repo . --diagram proto-map     # detected routes
 ```
 
-Emits a ready-to-inject ` ```mermaid ``` ` block, or an empty stub (exit 2) when the engine is unavailable. The committed `draft/graph/*.mermaid` snapshots are written by `graph-snapshot.sh`.
+Emits a ready-to-inject ` ```mermaid ``` ` block on the fly (computed live by the engine), or an empty stub (exit 2) when the engine is unavailable. Diagrams are generated at the moment of use — they are never committed.
 
-### Building / refreshing the snapshot
+### Indexing / refreshing the gate marker
 
 ```bash
 scripts/tools/graph-snapshot.sh --repo .
 ```
 
-Writes the committed `draft/graph/` snapshot (`schema.yaml`, `architecture.json`, `hotspots.jsonl`, `*.mermaid`). Run during `draft init` and `draft index`, or whenever the reviewable graph state should be refreshed.
+Indexes the repo into the engine and writes the `draft/graph/schema.yaml` gate marker. It writes **no** graph data. Run during `draft init` and `draft graph`, or whenever the index should be refreshed.
 
 ## Finding the Engine (Resolution + Usage Report)
 
@@ -17844,24 +17070,24 @@ ENGINE_INFO="$(scripts/tools/verify-graph-binary.sh --repo . --json 2>/dev/null
 
 After successful detection, `draft/.graph-binary-report.json` contains: `detected_at`, `engine_bin`, `source` (`path` | `managed` | `bundled:<arch>` | `override`), `arch`, `status`. It is a derived artifact (safe to prune), regenerated by each graph-using command that calls the verifier.
 
-## Building the Snapshot
+## Indexing the Repo
 
-Run during `draft:init` / `draft:index`, or manually:
+Run during `draft:init` / `draft:graph`, or manually:
 
 ```bash
 scripts/tools/graph-snapshot.sh --repo .
 ```
 
-The engine indexes C/C++, Go, Python, TypeScript/JS, and more (tree-sitter, 159 languages) plus LSP-assisted resolution for the major ones, and detects HTTP/gRPC/GraphQL routes. Indexing is incremental in the engine (content-based, git-aware); the snapshot is re-derived on each run.
+The engine indexes C/C++, Go, Python, TypeScript/JS, and more (tree-sitter, 159 languages) plus LSP-assisted resolution for the major ones, and detects HTTP/gRPC/GraphQL routes. Indexing is incremental in the engine (content-based, git-aware). This refreshes the engine index and rewrites the `schema.yaml` gate marker; it produces no committed graph data.
 
 ## Graceful Degradation
 
 | Scenario | Behavior |
 |----------|----------|
-| No engine resolvable (or `DRAFT_MEMORY_DISABLE=1`) | Skip graph build in init; all skills proceed without graph data; tools emit `source: unavailable` |
+| No engine resolvable (or `DRAFT_MEMORY_DISABLE=1`) | Skip graph indexing in init; all skills proceed without graph data; tools emit `source: unavailable` |
 | Engine present but a query fails | Warn and proceed; skills work without graph data |
-| `draft/graph/` snapshot exists | Load always-load files during context loading; use live query tools as needed |
-| Stale snapshot | Still useful — structural changes are infrequent. Re-run `graph-snapshot.sh` (or init) to refresh. |
+| `draft/graph/schema.yaml` exists | Engine is wired — use live query tools as needed during the run |
+| Engine index out of date | The engine indexes incrementally (content-based, git-aware) on each query, so it self-freshens. Re-run `graph-snapshot.sh` (or init) to force a reindex and refresh the marker. |
 
 </core-file>
 
@@ -18417,7 +17643,7 @@ See [graph-query.md](graph-query.md) §Graph Usage Report (Mandatory Footer) for
 ```md
 ## Graph Usage Report
 
-- Graph files queried: <comma-separated list, e.g. `architecture.json, hotspots.jsonl` and/or query tools like `graph-callers.sh` — or `NONE` with justification below>
+- Graph files queried: <comma-separated list, e.g. `get_architecture, hotspot-rank.sh` and/or query tools like `graph-callers.sh` — or `NONE` with justification below>
 - Modules identified via graph: <comma-separated module names, or `none`>
 - Files identified via graph: <integer count>
 - Filesystem grep fallbacks: <list of `<pattern>` searches with one-line justification each, or `none`>
@@ -18466,7 +17692,7 @@ Referenced by: `draft decompose`, `draft implement`, `draft review`, `draft deep
 ## Universal Red Flags (STOP if any apply)
 
 - **Ran `grep`/`find`/`rg` for symbol or file discovery before consulting the graph** (when `draft/graph/schema.yaml` exists).
-- **Read more than 50 lines of source before consulting `draft/graph/hotspots.jsonl`** to know whether the file is a hotspot.
+- **Read more than 50 lines of source before querying hotspot rank** (`scripts/tools/hotspot-rank.sh --repo .`) to know whether the file is a hotspot.
 - **Omitted the Graph Usage Report footer** from the final output (see [graph-query.md](graph-query.md) §Mandatory Lookup Contract).
 - **Used a `grep` fallback without an explicit graph-miss statement** in the form: `Graph returned no match for <X>; falling back to grep.`
 - **Loaded full Layer 0.5 guardrails when the command type does not require them** (see selective-loading matrix in [draft-context-loading.md](draft-context-loading.md) §Layer 0.5).
@@ -18478,7 +17704,7 @@ Referenced by: `draft decompose`, `draft implement`, `draft review`, `draft deep
 These enforce [graph-query.md](graph-query.md) §Ground-Truth Discipline. Graph identifies candidates; Read confirms them. Shipping unread claims is the dominant correctness failure mode observed in Draft output.
 
 - **Wrote a `path:line` / `func()` / `symbol` reference into a deliverable without opening the file in this run.** Graph hit ≠ Read. (G1)
-- **Declared something in-scope or out-of-scope without Reading at least one file in that path.** Module names from `architecture.json` are a candidate set, not proof that the candidate contains the named cost. (G2)
+- **Declared something in-scope or out-of-scope without Reading at least one file in that path.** Module names from the live engine (`get_architecture`) are a candidate set, not proof that the candidate contains the named cost. (G2)
 - **Shipped `Citation: TBD` / `Path: TBD` / `Symbol: TBD` on a row whose Status is `Modified` or `Existing`.** TBD is reserved for `Status: New` rows with a planned path filled in. (G3)
 - **Claimed code behavior (writes / blocks / loops / fails / is the only path) from graph metadata alone.** Fan-in / fan-out / complexity scores are necessary signal, not sufficient evidence. (G4)
 - **Promoted a spec / generated an HLD or LLD / closed a review without checking that the in-scope file set covers every cost term in the problem statement.** Silent scope narrowing that excludes the named cost is the highest-impact failure class. (G5)
@@ -18488,7 +17714,7 @@ When in doubt, prefer "not yet validated against source" over an unbacked assert
 
 ## Graph-First Lookup Order (non-negotiable)
 
-1. **Graph first** — the committed snapshot (`draft/graph/architecture.json`, `draft/graph/hotspots.jsonl`) and the live query tools (`scripts/tools/graph-callers.sh`, `graph-impact.sh`, `cycle-detect.sh`, `hotspot-rank.sh`).
+1. **Graph first** — wrapper scripts (`scripts/tools/graph-arch.sh`, `graph-callers.sh`, `graph-impact.sh`, `cycle-detect.sh`, `hotspot-rank.sh`) and direct engine queries (`search_graph`, `search_code`). The gate marker `draft/graph/schema.yaml` (present = engine available) is the only committed graph file.
 2. **Generated context second** — `draft/.ai-context.md`, relevant `draft/architecture.md` slices, track-level `hld.md`/`lld.md`.
 3. **Source file reads third** — only narrowed targets identified via graph or generated context.
 4. **Filesystem `grep`/`find` last** — only after a graph miss, with the explicit fallback sentence above.
@@ -18644,6 +17870,7 @@ whose `pre_deploy_status != passing`.
 <core-file path="core/templates/guardrails.md">
 
 ---
+type: Guardrails
 project: "{PROJECT_NAME}"
 module: "root"
 generated_by: "draft:init"
@@ -19208,6 +18435,7 @@ Structured questions for track creation. **Ask ONE question at a time.** Wait fo
 <core-file path="core/templates/ai-context.md">
 
 ---
+type: ContextMap
 project: "{PROJECT_NAME}"
 module: "root"
 generated_by: "draft:init"
@@ -19257,7 +18485,7 @@ generated_at: "{ISO_TIMESTAMP}"
 ```
 
 > Include immediate sub-directories for all major modules (not just top-level).
-> Use graph data (`draft/graph/modules/*.jsonl`) for exhaustive sub-module enumeration.
+> Use live engine queries (`get_architecture .packages[]` or `graph-callers.sh`) for exhaustive sub-module enumeration.
 > Show file counts per sub-module to indicate relative size/importance.
 
 ## GRAPH:MODULES
@@ -19487,6 +18715,7 @@ interface {ServiceName} {
 <core-file path="core/templates/ai-profile.md">
 
 ---
+type: Profile
 project: "{PROJECT_NAME}"
 module: "{MODULE_NAME or 'root'}"
 generated_by: "draft:{COMMAND_NAME}"
@@ -19537,6 +18766,7 @@ generated_at: "{ISO_TIMESTAMP}"
 <core-file path="core/templates/architecture.md">
 
 ---
+type: Architecture
 project: "{PROJECT_NAME}"
 module: "root"
 generated_by: "draft:init"
@@ -19567,9 +18797,9 @@ graph:
     go: "{approximate | high}"
   stats:
     modules: "{N from schema.yaml}"
-    edges: "{total_edges from architecture.json}"
+    edges: "{total_edges from engine: get_architecture .edges}"
     hotspots: "{N}"
-  notes: "{explicit fidelity summary from architecture.json languages/packages}"
+  notes: "{explicit fidelity summary from engine: get_architecture .languages/.packages}"
 generation_notes: "{High existing context detected via audit — see §10 Relationship for deference | Standard graph-primary generation}"
 ---
 
@@ -19651,7 +18881,7 @@ Each backed by:
 
 ## 4. Module & Dependency Map (Primarily Graph-Derived)
 
-- Module dependency graph rendered from `draft/graph/architecture.json` (`.packages`) + `module-deps.mermaid`
+- Module dependency graph rendered from live engine query `scripts/tools/graph-arch.sh --repo . | jq '.packages'` + `scripts/tools/mermaid-from-graph.sh --repo . --diagram module-deps` (generated live, never committed)
 - High fan-in / fan-out modules highlighted
 - Cyclic dependencies called out
 - Cross-language boundaries (FFI, RPC, shared memory) explicitly surfaced with coverage notes
@@ -20196,6 +19426,7 @@ Use Cases:
 <core-file path="core/templates/product.md">
 
 ---
+type: Product
 project: "{PROJECT_NAME}"
 module: "root"
 generated_by: "draft:init"
@@ -20315,6 +19546,7 @@ Things explicitly out of scope for this product:
 <core-file path="core/templates/tech-stack.md">
 
 ---
+type: TechStack
 project: "{PROJECT_NAME}"
 module: "root"
 generated_by: "draft:init"
@@ -20493,6 +19725,7 @@ graph TD
 <core-file path="core/templates/workflow.md">
 
 ---
+type: Workflow
 project: "{PROJECT_NAME}"
 module: "root"
 generated_by: "draft:init"
@@ -20689,6 +19922,7 @@ If task exceeds 5 iterations:
 <core-file path="core/templates/spec.md">
 
 ---
+type: Spec
 project: "{PROJECT_NAME}"
 module: "root"
 track_id: "{TRACK_ID}"
@@ -20863,6 +20097,7 @@ approvers:
 <core-file path="core/templates/plan.md">
 
 ---
+type: Plan
 project: "{PROJECT_NAME}"
 module: "root"
 track_id: "{TRACK_ID}"
@@ -21113,7 +20348,7 @@ Portable stub. Content generalized from proven internal patterns.
 ---
 project: "{PROJECT_NAME}"
 module: "root"
-generated_by: "draft:index"
+generated_by: "draft:init"
 generated_at: "{ISO_TIMESTAMP}"
 ---
 
@@ -21127,7 +20362,7 @@ generated_at: "{ISO_TIMESTAMP}"
 | **Synced To** | `{FULL_SHA}` |
 
 > Auto-generated. Do not edit directly.
-> Re-run `draft index` to update.
+> Re-run `draft init` to update.
 
 ---
 
@@ -21154,7 +20389,7 @@ The following services have not been initialized with `draft init`:
 
 - `[path/to/service]/`
 
-Run `draft index --init-missing` or initialize individually with:
+Initialize each one by running `draft init` inside its directory — it links the module's graph up to the root spine:
 ```bash
 cd [path/to/service] && draft init
 ```
@@ -21177,7 +20412,7 @@ cd [path/to/service] && draft init
 ---
 project: "{PROJECT_NAME}"
 module: "root"
-generated_by: "draft:index"
+generated_by: "draft:init"
 generated_at: "{ISO_TIMESTAMP}"
 ---
 
@@ -21191,7 +20426,7 @@ generated_at: "{ISO_TIMESTAMP}"
 | **Synced To** | `{FULL_SHA}` |
 
 > Auto-generated. Do not edit directly.
-> Re-run `draft index` to update.
+> Re-run `draft init` to update.
 
 ---
 
@@ -21289,7 +20524,7 @@ Services depending on external systems:
 ---
 project: "{PROJECT_NAME}"
 module: "root"
-generated_by: "draft:index"
+generated_by: "draft:init"
 generated_at: "{ISO_TIMESTAMP}"
 ---
 
@@ -21303,7 +20538,7 @@ generated_at: "{ISO_TIMESTAMP}"
 | **Synced To** | `{FULL_SHA}` |
 
 > Auto-generated. Do not edit directly.
-> Re-run `draft index` to update.
+> Re-run `draft init` to update.
 
 ---
 
@@ -21399,7 +20634,7 @@ Current versions in production:
 ---
 project: "{PROJECT_NAME}"
 module: "root"
-generated_by: "draft:index"
+generated_by: "draft:init"
 generated_at: "{ISO_TIMESTAMP}"
 ---
 
@@ -21414,7 +20649,7 @@ generated_at: "{ISO_TIMESTAMP}"
 
 > Synthesized from [X] service contexts.
 > Edit this file to refine the overall product vision.
-> Re-running `draft index` will update auto-generated sections but preserve manual edits.
+> Re-running `draft init` will update auto-generated sections but preserve manual edits.
 
 ---
 
@@ -21461,7 +20696,7 @@ generated_at: "{ISO_TIMESTAMP}"
 ---
 project: "{PROJECT_NAME}"
 module: "root"
-generated_by: "draft:index"
+generated_by: "draft:init"
 generated_at: "{ISO_TIMESTAMP}"
 ---
 
@@ -21476,7 +20711,7 @@ generated_at: "{ISO_TIMESTAMP}"
 
 > Synthesized from [X] service contexts.
 > This is a **system-of-systems** view. For service internals, see individual service contexts.
-> Re-running `draft index` will update auto-generated sections but preserve manual edits.
+> Re-running `draft init` will update auto-generated sections but preserve manual edits.
 
 ---
 
@@ -21583,7 +20818,7 @@ sequenceDiagram
 ## Notes
 
 - For detailed service architecture, navigate to individual service contexts via the Details column
-- This file is regenerable via `draft index`
+- This file is regenerable via `draft init`
 - Manual edits between `<!-- MANUAL START -->` and `<!-- MANUAL END -->` are preserved
 
 </core-file>
@@ -21597,7 +20832,7 @@ sequenceDiagram
 ---
 project: "{PROJECT_NAME}"
 module: "root"
-generated_by: "draft:index"
+generated_by: "draft:init"
 generated_at: "{ISO_TIMESTAMP}"
 ---
 
@@ -21612,7 +20847,7 @@ generated_at: "{ISO_TIMESTAMP}"
 
 > Synthesized from [X] service contexts.
 > This defines **org-wide standards**. Service-specific additions are in their local tech-stack.md.
-> Re-running `draft index` will update auto-generated sections but preserve manual edits.
+> Re-running `draft init` will update auto-generated sections but preserve manual edits.
 
 ---
 
@@ -21721,6 +20956,7 @@ Org-wide conventions:
 <core-file path="core/templates/rca.md">
 
 ---
+type: RCA
 project: "{PROJECT_NAME}"
 track_id: "{TRACK_ID}"
 jira_ticket: "{JIRA_KEY}"
@@ -21895,6 +21131,7 @@ git-ignored at the track level. No HTML or PDF templates ship here.
 <core-file path="core/templates/discovery.md">
 
 ---
+type: Discovery
 project: "{PROJECT_NAME}"
 module: "root"
 track_id: "{TRACK_ID}"
@@ -21983,6 +21220,7 @@ without line numbers are exempt from drift checks (they document
 <core-file path="core/templates/hld.md">
 
 ---
+type: HLD
 project: "{PROJECT_NAME}"
 module: "root"
 track_id: "{TRACK_ID}"
@@ -22319,6 +21557,7 @@ Result stored in `metadata.json:pre_deploy_status`
 <core-file path="core/templates/lld.md">
 
 ---
+type: LLD
 project: "{PROJECT_NAME}"
 module: "root"
 track_id: "{TRACK_ID}"