graph

name	graph
description	Initialize or refresh the knowledge-graph snapshot for a repository. Ensures the codebase-memory-mcp engine is present (fetching it if needed), then builds draft/graph/ and reports engine, counts, hotspots, and cycles. Accepts an optional repo path.

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).

Red Flags - STOP if you're:

• Reporting counts without actually running graph-snapshot.sh
• Claiming the graph is built when the engine was unavailable
• Treating an engine-unavailable result as a hard failure (it degrades gracefully)
• Running against a path that isn't a directory

Build, then report what the tools actually returned.

---

Step 1: Resolve the target repo

The command takes an optional path argument: /draft:graph [path].

• No argument → use the current directory (.).
• With a path → use it as the repo root.

REPO="${1:-.}"
if [ ! -d "$REPO" ]; then
  echo "ERROR: '$REPO' is not a directory."
  exit 1
fi
REPO_ABS="$(cd "$REPO" && pwd)"
echo "Target repo: $REPO_ABS"

Step 2: Ensure the engine is present

Resolve the engine; if it is missing, fetch it once, then re-check. If it is still unavailable (e.g. offline, opted out via DRAFT_MEMORY_DISABLE), report and stop gracefully — graph features are optional everywhere in Draft.

if ! scripts/tools/verify-graph-binary.sh --repo "$REPO_ABS" --json 2>/dev/null | grep -q '"status":"ok"'; then
  echo "Graph engine not found — attempting to fetch it..."
  scripts/fetch-memory-engine.sh || true
fi

ENGINE="$(scripts/tools/verify-graph-binary.sh --repo "$REPO_ABS" --json 2>/dev/null || true)"
if ! echo "$ENGINE" | grep -q '"status":"ok"'; then
  echo "Graph engine unavailable — skipping. Install with scripts/fetch-memory-engine.sh, or unset DRAFT_MEMORY_DISABLE."
  exit 0
fi
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.

scripts/tools/graph-snapshot.sh --repo "$REPO_ABS"

If this exits non-zero, the engine became unavailable mid-run — report it and stop; do not fabricate results.

Step 4: Report

Summarize what the snapshot contains. Read draft/graph/schema.yaml for engine/version/counts, and use the live tools for a quick health view:

echo "--- Snapshot ---"
cat "$REPO_ABS/draft/graph/schema.yaml"

echo "--- Top hotspots ---"
scripts/tools/hotspot-rank.sh --repo "$REPO_ABS" --top 5

echo "--- Cycles ---"
scripts/tools/cycle-detect.sh --repo "$REPO_ABS"

echo "--- Snapshot state ---"
git -C "$REPO_ABS" rev-parse --short HEAD 2>/dev/null \
  && { git -C "$REPO_ABS" diff --quiet 2>/dev/null || echo "(working tree dirty — snapshot reflects uncommitted changes)"; }

Present a concise summary:

• Engine: version + resolution source (path / managed / bundled / override)
• Graph: node and edge counts (from schema.yaml)
• Top hotspots: the highest fan-in symbols
• Cycles: count, or None ✓
• Freshness: the commit the snapshot reflects, and whether the tree was dirty

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.
• For a first-time full context bootstrap (architecture + profiles): run /draft:init.

Graceful Degradation

Scenario	Behavior
Engine resolvable	Build snapshot, report counts/hotspots/cycles
Engine missing, fetch succeeds	Build proceeds after fetch
Engine missing, fetch fails / DRAFT_MEMORY_DISABLE=1	Report unavailable and exit 0 — no error, no partial snapshot
Path not a directory	Exit 1 with a clear message

See core/shared/graph-query.md and bin/README.md for the query contract and engine resolution.