@drafthq/draft 2.8.1 → 3.0.0

package/scripts/tools/okf-check.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# okf-check.sh — validate a directory against the Open Knowledge Format v0.1 spec.
+#
+# Implements the §9 conformance criteria of OKF v0.1
+# (https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md):
+#
+#   §9.1  Every non-reserved .md file has a parseable YAML frontmatter block.
+#   §9.2  Every such frontmatter block has a non-empty `type` field.
+#   §9.3  Reserved files follow their structure when present:
+#           index.md  (§6)  — contains NO frontmatter, EXCEPT the bundle-root
+#                             index.md MAY carry frontmatter holding only
+#                             `okf_version` (§11).
+#           log.md    (§7)  — `## ` date headings MUST be ISO 8601 (YYYY-MM-DD).
+#
+# Consumers are required to be permissive, so this checker only enforces the
+# three hard rules above; everything else in the spec is soft guidance.
+#
+# Usage: scripts/tools/okf-check.sh [--dir DIR] [--quiet]
+# Exit codes: 0 conformant, 1 violations found, 2 dir missing.
+set -euo pipefail
+
+DIR="draft"
+QUIET=0
+
+usage() {
+    cat <<'EOF'
+okf-check.sh — validate a directory against Open Knowledge Format v0.1 (§9).
+
+Usage:
+  scripts/tools/okf-check.sh [--dir DIR] [--quiet]
+
+Flags:
+  --dir DIR  Bundle root to validate (default: draft).
+  --quiet    Print only the summary line, not per-file violations.
+  --help     Show this help.
+
+Exit 0 when conformant, 1 when violations are found, 2 when DIR is absent.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --dir) DIR="$2"; shift 2;;
+        --quiet) QUIET=1; shift;;
+        --help|-h) usage; exit 0;;
+        -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+        *) echo "Unexpected arg: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ -d "$DIR" ]] || { echo "ERROR: --dir '$DIR' is not a directory" >&2; exit 2; }
+DIR="${DIR%/}"
+
+# fm_scan FILE -> "STATUS|TYPE|KEYS"  (pipe-delimited; '|' is not IFS-whitespace,
+# so empty TYPE/KEYS fields survive `read` instead of collapsing).
+#   STATUS: nofm (no frontmatter) | ok (closed block) | unterminated
+#   TYPE:   value of the top-level `type:` key, if any
+#   KEYS:   comma-separated top-level frontmatter keys
+fm_scan() {
+    awk '
+        NR==1 { if ($0 != "---") { print "nofm||"; exit } ; inblock=1; next }
+        inblock && /^---[[:space:]]*$/ { print "ok|" type "|" keys; closed=1; exit }
+        inblock {
+            if (match($0, /^[A-Za-z_][A-Za-z0-9_]*:/)) {
+                k = substr($0, 1, RLENGTH-1)
+                keys = keys (keys=="" ? "" : ",") k
+                if (k == "type") {
+                    v = substr($0, RLENGTH+1)
+                    gsub(/^[ \t]+|[ \t]+$/, "", v)
+                    gsub(/^"|"$/, "", v)
+                    type = v
+                }
+            }
+            next
+        }
+        END { if (inblock && !closed) print "unterminated|" type "|" keys }
+    ' "$1"
+}
+
+violations=0
+concepts=0
+reserved=0
+
+report() { # relpath  message
+    violations=$((violations + 1))
+    [[ "$QUIET" == "1" ]] || echo "FAIL  $1: $2" >&2
+}
+
+while IFS= read -r -d '' file; do
+    rel="${file#"$DIR"/}"
+    base="$(basename "$file")"
+
+    case "$base" in
+        index.md)
+            reserved=$((reserved + 1))
+            IFS='|' read -r status _ keys < <(fm_scan "$file")
+            if [[ "$status" != "nofm" ]]; then
+                if [[ "$rel" == "index.md" ]]; then
+                    # Bundle-root index.md: frontmatter allowed, but only okf_version (§11).
+                    IFS=',' read -ra ks <<< "$keys"
+                    for k in "${ks[@]}"; do
+                        [[ -z "$k" || "$k" == "okf_version" ]] && continue
+                        report "$rel" "root index.md frontmatter may only hold 'okf_version' (§11); found '$k'"
+                    done
+                else
+                    report "$rel" "index.md must not contain frontmatter (§6)"
+                fi
+            fi
+            ;;
+        log.md)
+            reserved=$((reserved + 1))
+            while IFS= read -r h; do
+                if ! [[ "$h" =~ ^##[[:space:]]+[0-9]{4}-[0-9]{2}-[0-9]{2} ]]; then
+                    report "$rel" "log.md date heading not ISO 8601 (§7): '$h'"
+                fi
+            done < <(grep -E '^## ' "$file" 2>/dev/null || true)
+            ;;
+        *)
+            concepts=$((concepts + 1))
+            IFS='|' read -r status type _ < <(fm_scan "$file")
+            case "$status" in
+                nofm)         report "$rel" "missing YAML frontmatter block (§9.1)";;
+                unterminated) report "$rel" "unterminated frontmatter block — no closing '---' (§9.1)";;
+                ok)
+                    [[ -n "$type" ]] || report "$rel" "frontmatter missing required non-empty 'type' (§9.2)"
+                    ;;
+            esac
+            ;;
+    esac
+done < <(find "$DIR" -type f -name '*.md' -print0 | sort -z)
+
+if [[ "$violations" -eq 0 ]]; then
+    echo "OKF v0.1 conformant — $concepts concept file(s), $reserved reserved file(s), 0 violations. ($DIR)"
+    exit 0
+fi
+echo "OKF v0.1 NON-CONFORMANT — $violations violation(s) across $concepts concept + $reserved reserved file(s). ($DIR)" >&2
+exit 1

package/scripts/tools/okf-emit.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+# okf-emit.sh — emit an Open Knowledge Format (OKF) bundle from a graph snapshot.
+#
+# OKF is an open, vendor-neutral spec (Google Cloud): a directory of markdown
+# files with YAML frontmatter, one file per concept, where the file path is the
+# concept's identity and concepts cross-link with normal markdown links. The
+# only required frontmatter field is `type`. This makes Draft's knowledge graph
+# portable — consumable by any OKF reader (visualizers, catalogs, other agents).
+# https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing
+#
+# Reads a graph snapshot's architecture.json and writes a conformant bundle:
+#   index.md            type: Repository — bundle root + progressive disclosure
+#   modules/<slug>.md   type: Module     — one concept per package, cross-linked
+#
+# Degrades gracefully: with no packages/boundaries in the snapshot it still emits
+# index.md (counts, languages, hotspots) and an empty modules/ directory.
+#
+# Usage: scripts/tools/okf-emit.sh [--repo DIR] [--snapshot DIR] [--out DIR]
+# Exit codes: 0 OK, 1 invocation error, 2 snapshot/architecture.json unavailable.
+set -euo pipefail
+
+REPO="."
+SNAPSHOT=""
+OUT=""
+
+usage() {
+    cat <<'EOF'
+okf-emit.sh — emit an Open Knowledge Format (OKF) bundle from a graph snapshot.
+
+Usage:
+  scripts/tools/okf-emit.sh [--repo DIR] [--snapshot DIR] [--out DIR]
+
+Flags:
+  --repo DIR      Repository root (default: cwd).
+  --snapshot DIR  Snapshot dir holding architecture.json (default: <repo>/draft/graph).
+  --out DIR       Bundle output dir (default: <snapshot>/okf).
+  --help          Show this help.
+
+Writes index.md + modules/<slug>.md (OKF v0.1). Exit 0 on success, 2 when no
+architecture.json is available (nothing emitted).
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2;;
+        --snapshot) SNAPSHOT="$2"; shift 2;;
+        --out) OUT="$2"; shift 2;;
+        --help|-h) usage; exit 0;;
+        -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+        *) echo "Unexpected arg: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
+REPO_ABS="$(cd "$REPO" && pwd)"
+SNAP="${SNAPSHOT:-$REPO_ABS/draft/graph}"
+ARCH="$SNAP/architecture.json"
+OUT="${OUT:-$SNAP/okf}"
+
+command -v jq >/dev/null 2>&1 || { echo "jq required for OKF emit" >&2; exit 2; }
+[[ -f "$ARCH" ]] || { echo "no architecture.json at $ARCH — nothing to emit" >&2; exit 2; }
+
+# slugify a concept name into a filesystem- and link-safe identifier.
+slug() {
+    local s
+    s="$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]' \
+        | sed -e 's#[^a-z0-9]\{1,\}#-#g' -e 's#^-##' -e 's#-$##')"
+    [[ -n "$s" ]] || s="module"
+    printf '%s' "$s"
+}
+
+# escape a value for a YAML double-quoted scalar.
+yesc() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    printf '%s' "$s"
+}
+
+TS="$(date -Iseconds 2>/dev/null || date)"
+PROJECT="$(jq -r '.project // "repository"' "$ARCH")"
+TOTAL_NODES="$(jq -r '.total_nodes // 0' "$ARCH")"
+TOTAL_EDGES="$(jq -r '.total_edges // 0' "$ARCH")"
+
+PKGS="$(jq -r '.packages[]? | [.name, (.node_count//0), (.fan_in//0), (.fan_out//0)] | @tsv' "$ARCH")"
+BOUNDS="$(jq -r '.boundaries[]? | [.from, .to, (.call_count//0)] | @tsv' "$ARCH")"
+
+mkdir -p "$OUT/modules"
+
+# --- One concept file per package, cross-linked via boundaries ---
+PKG_COUNT=0
+if [[ -n "$PKGS" ]]; then
+    while IFS=$'\t' read -r name nc fi fo; do
+        [[ -n "$name" ]] || continue
+        PKG_COUNT=$((PKG_COUNT + 1))
+        s="$(slug "$name")"
+        {
+            printf -- '---\n'
+            printf 'type: Module\n'
+            printf 'title: "%s"\n' "$(yesc "$name")"
+            printf 'description: "Code module %s: %s nodes, fan-in %s, fan-out %s."\n' \
+                "$(yesc "$name")" "$nc" "$fi" "$fo"
+            printf 'tags: [module, knowledge-graph]\n'
+            printf 'timestamp: "%s"\n' "$TS"
+            printf -- '---\n\n'
+            printf '# %s\n\n' "$name"
+            printf 'Structural module derived from the knowledge graph. Nodes: %s, fan-in: %s, fan-out: %s.\n' \
+                "$nc" "$fi" "$fo"
+
+            # Depends on (outbound boundaries)
+            outs="$(awk -F'\t' -v n="$name" '$1==n && $2!="" {print $2"\t"$3}' <<< "$BOUNDS")"
+            if [[ -n "$outs" ]]; then
+                printf '\n## Depends on\n\n'
+                while IFS=$'\t' read -r to cc; do
+                    [[ -n "$to" ]] || continue
+                    printf -- '- [%s](%s.md) — %s call(s)\n' "$to" "$(slug "$to")" "$cc"
+                done <<< "$outs"
+            fi
+
+            # Depended on by (inbound boundaries)
+            ins="$(awk -F'\t' -v n="$name" '$2==n && $1!="" {print $1"\t"$3}' <<< "$BOUNDS")"
+            if [[ -n "$ins" ]]; then
+                printf '\n## Depended on by\n\n'
+                while IFS=$'\t' read -r from cc; do
+                    [[ -n "$from" ]] || continue
+                    printf -- '- [%s](%s.md) — %s call(s)\n' "$from" "$(slug "$from")" "$cc"
+                done <<< "$ins"
+            fi
+        } > "$OUT/modules/$s.md"
+    done <<< "$PKGS"
+fi
+
+# --- Bundle index.md (reserved file: no frontmatter, §6 progressive disclosure) ---
+{
+    printf '# %s\n\n' "$PROJECT"
+    printf 'Open Knowledge Format bundle generated by Draft from the codebase-memory-mcp knowledge graph. Nodes: %s, edges: %s, modules: %s.\n' \
+        "$TOTAL_NODES" "$TOTAL_EDGES" "$PKG_COUNT"
+
+    langs="$(jq -r '.languages[]? | "* \(.language) - \(.file_count) file(s)"' "$ARCH")"
+    if [[ -n "$langs" ]]; then
+        printf '\n# Languages\n\n%s\n' "$langs"
+    fi
+
+    if [[ "$PKG_COUNT" -gt 0 ]]; then
+        printf '\n# Modules\n\n'
+        while IFS=$'\t' read -r name nc fi fo; do
+            [[ -n "$name" ]] || continue
+            printf -- '* [%s](modules/%s.md) - %s nodes, fan-in %s, fan-out %s\n' \
+                "$name" "$(slug "$name")" "$nc" "$fi" "$fo"
+        done < <(printf '%s\n' "$PKGS" | sort)
+    fi
+
+    hot="$(jq -r '.hotspots[:10][]? | "* \(.name) - fan-in \(.fan_in)"' "$ARCH")"
+    if [[ -n "$hot" ]]; then
+        printf '\n# Top hotspots\n\n%s\n' "$hot"
+    fi
+} > "$OUT/index.md"
+
+echo "OKF bundle written to $OUT (modules=$PKG_COUNT)"
+exit 0

package/scripts/tools/skill-caps.conf

@@ -19,6 +19,5 @@ status       1300
 bughunt     1200
 new-track   1100
 review      1000
-index        900
 implement    900
 decompose    700

package/skills/GRAPH.md

@@ -55,7 +55,6 @@ graph TD
     subgraph "Architecture"
         decompose["/draft:decompose"]
         adr["/draft:adr"]
-        index["/draft:index"]
         tech-debt["/draft:tech-debt"]
         impact["/draft:impact"]
     end
@@ -96,7 +95,6 @@ graph TD
     init --> learn
     init --> adr
     init --> bughunt
-    init --> index
     init --> status
     init --> deep-review
     init --> debug
@@ -124,7 +122,6 @@ graph TD
     discover --> coverage
     discover --> testing-strategy
     discover --> learn
-    discover --> index
     discover --> tour
     discover --> impact
     discover --> assist-review
@@ -178,8 +175,7 @@ graph TD
     impact -.->|reads graph| new-track
     impact -.->|reads graph| implement
 
-    %% Monorepo chain
-    init -.->|per-service| index
+    %% Monorepo: init is scope-aware — root build + module→root graph link (no separate index command)
 ```
 
 ## Dependency Matrix
@@ -193,7 +189,7 @@ graph TD
 | `implement` | init, new-track | review (triggers at phase boundaries) | Modifies source code; regenerates .ai-context.md |
 | `review` | init, new-track | implement (called at phase boundaries) | review-report-latest.md |
 | `quick-review` | init | review (fast alternative) | quick-review-report.md |
-| `bughunt` | init | review (optional), index (optional), jira (optional) | bughunt-report-latest.md |
+| `bughunt` | init | review (optional), jira (optional) | bughunt-report-latest.md |
 | `deep-review` | init | -- | deep-review audit report |
 | `coverage` | init, new-track | -- | Regenerates .ai-context.md |
 | `testing-strategy` | init | coverage (informs), bughunt (informs) | testing-strategy.md |
@@ -248,7 +244,8 @@ deep-review ──→ tech-debt ──→ new-track (prioritized items)
 
 ### Monorepo Flow
 ```
-init (per-service) → index (at root) → aggregated context
+init (root)       → whole-repo code-graph spine + sparse root map
+init (sub-module) → module snapshot + root-link.json → cross-module context via the root spine
 ```
 
 ### Quality Audit Flow
@@ -280,15 +277,15 @@ init → learn → (updates guardrails.md)
 
 | Subroutine | Defined In | Called By |
 |------------|-----------|----------|
-| Condensation Subroutine (.ai-context.md regeneration) | `core/shared/condensation.md` | implement, decompose, coverage, index |
+| Condensation Subroutine (.ai-context.md regeneration) | `core/shared/condensation.md` | implement, decompose, coverage |
 | Standard File Metadata (YAML frontmatter) | `init` | All skills that generate draft/ files |
 | Three-Stage Review | `review` | implement (at phase boundaries) |
-| Signal Classification | `init` | init refresh, index (future) |
+| Signal Classification | `init` | init refresh |
 | Pattern Learning | `core/shared/pattern-learning.md` | learn, bughunt, review, deep-review (updates guardrails.md) |
 | Context Loading | `core/shared/draft-context-loading.md` | All skills requiring draft/ context |
 | Cross-Skill Dispatch | `core/shared/cross-skill-dispatch.md` | bughunt, deep-review, implement, review |
 | Jira Sync | `core/shared/jira-sync.md` | bughunt, review, implement (when ticket linked) |
-| Graph Query | `core/shared/graph-query.md` | init, implement, bughunt, review, debug, decompose, index, impact |
+| Graph Query | `core/shared/graph-query.md` | init, implement, bughunt, review, debug, decompose, impact |
 | Graph Mermaid | `scripts/tools/mermaid-from-graph.sh` | init (injects module-deps + proto-map into architecture.md) |
 
 ## Artifact Flow

package/skills/bughunt/SKILL.md

@@ -94,6 +94,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:

package/skills/discover/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: discover
-description: "Primary router for discovery, debugging, investigation, quality, and exploration workflows. Analyzes user intent and dispatches to debug, bughunt, quick-review, deep-review, coverage, testing-strategy, learn, index, tour, impact, assist-review. The recommended entry point for any 'find out', 'check', 'review', or 'investigate' request."
+description: "Primary router for discovery, debugging, investigation, quality, and exploration workflows. Analyzes user intent and dispatches to debug, bughunt, quick-review, deep-review, coverage, testing-strategy, learn, tour, impact, assist-review. The recommended entry point for any 'find out', 'check', 'review', or 'investigate' request."
 ---
 
 # Discover - Investigation & Quality Router
@@ -13,7 +13,6 @@ description: "Primary router for discovery, debugging, investigation, quality, a
 - 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
@@ -29,7 +28,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 |
@@ -55,7 +53,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
 

package/skills/draft/SKILL.md

@@ -39,7 +39,7 @@ The 5 router commands provide intent-based dispatch into the 20+ specialist comm
 | `/draft:plan` | Planning & architecture | new-track, decompose, adr, tech-debt, change |
 | `/draft:ops` | Operations & lifecycle | deploy-checklist, incident-response, standup, status, revert |
 | `/draft:docs` | Authoring | documentation |
-| `/draft:discover` | Investigation & quality | debug, bughunt, quick/deep-review, coverage, testing-strategy, learn, index, tour, impact, assist-review |
+| `/draft:discover` | Investigation & quality | debug, bughunt, quick/deep-review, coverage, testing-strategy, learn, tour, impact, assist-review |
 | `/draft:jira` | Jira integration (preview, create, review) | - |
 
 ### Specialist Commands (leaf skills, invoked via routers or directly)
@@ -74,7 +74,7 @@ These commands remain available for targeted, specialist execution outside paren
 
 #### 4. Setup & Documentation
 * `/draft` - Display this command overview and help reference
-* `/draft:index` - Aggregate multi-service context in monorepo structures
+* `/draft:init` - Single scope-aware entry point: builds the root-first code graph (`draft/graph/`) and project context; run at the repo root or inside any sub-module (monorepo context comes from running it at root)
 * `/draft:discover` - Phase 0 code-spike report (hotspots, mode flags, open questions) before spec freeze
 * `/draft:documentation` - Generate structured codebase documentation (API, Onboarding, Runbooks)
 * `/draft:tech-debt` - Audit technical debt across 6 key dimensions

package/skills/draft/intent-mapping.md

@@ -33,5 +33,6 @@ Draft commands can be invoked using natural language. If you describe your goal
 | "write docs", "create readme", "api documentation" | `/draft:documentation` | Generate professional, structured docs |
 | "preview jira", "export jira issues", "jira draft" | `/draft:jira-preview` | Generate Jira markdown export from plan |
 | "create jira", "push to jira board" | `/draft:jira-create` | Create actual Jira issues via MCP integrations |
-| "index services", "aggregate context", "monorepo setup" | `/draft:index` | Aggregate multi-service context at the root |
-| "build graph", "refresh graph", "rebuild the knowledge graph", "index this repo's structure" | `/draft:graph` | Initialize/refresh the `draft/graph/` snapshot (optionally `draft graph <path>`) |
+| "index services", "aggregate context", "monorepo setup" | `/draft:init` | Single entry point — run at the repo root to build the whole-repo code graph + sparse root map; run in a sub-module to link up to it |
+| "build the code graph", "index this repo's structure", "graph memory only" | `/draft:init --graph-only` | Scope-aware, root-first code-graph build with no markdown |
+| "build graph", "refresh graph", "rebuild the knowledge graph" | `/draft:graph` | Narrow refresh of the `draft/graph/` snapshot for one repo (optionally `draft graph <path>`) |

package/skills/graph/SKILL.md

@@ -5,7 +5,7 @@ description: Initialize or refresh the knowledge-graph snapshot for a repository
 
 # Draft Graph
 
-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:
 
@@ -55,7 +55,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 writes the committed snapshot under `<repo>/draft/graph/` — `schema.yaml`, `architecture.json`, `hotspots.jsonl`, `module-deps.mermaid`, `proto-map.mermaid`, and an Open Knowledge Format bundle under `okf/` (a portable, vendor-neutral markdown mirror of the graph — `index.md` + one cross-linked `modules/<name>.md` concept per module).
 
 ```bash
 scripts/tools/graph-snapshot.sh --repo "$REPO_ABS"
@@ -92,7 +92,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