@drafthq/draft 3.2.1 → 3.3.0

package/scripts/tools/graph-preflight.sh

@@ -0,0 +1,259 @@
+#!/usr/bin/env bash
+# graph-preflight.sh — read-only go/no-go check before indexing a repo with the
+# Draft knowledge-graph engine (codebase-memory-mcp).
+#
+# Indexes NOTHING. Walks git metadata + engine status only. Safe to run anywhere.
+# Companion preflight for `scripts/tools/graph-init.sh` / `/draft:init --graph-only`.
+#
+# Usage:  scripts/tools/graph-preflight.sh [--json] [REPO_PATH]   (default repo: cwd)
+#         --json   emit a machine-readable report on stdout (no human output)
+# Exit:   0 = GO / GO-with-caution, 1 = NO-GO (blocking), 2 = bad invocation.
+#
+# Deliberately uses guard idioms (`|| true`, `|| echo 0`) rather than aborting:
+# the report accumulates blockers/warnings and prints a verdict even under -e.
+set -euo pipefail
+
+TOOLS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SELF_REPO="$(cd "$TOOLS_DIR/../.." && pwd)"
+# shellcheck source=_lib.sh
+source "$TOOLS_DIR/_lib.sh"
+
+usage() {
+  cat <<'EOF'
+graph-preflight.sh — read-only go/no-go check before knowledge-graph indexing.
+
+Usage:
+  scripts/tools/graph-preflight.sh [--json] [REPO_PATH]   (default repo: cwd)
+
+Flags:
+  --json   Emit a machine-readable report on stdout (no human output).
+  --help   Show this help.
+
+Indexes nothing — walks git metadata + engine status only.
+Exit codes: 0 GO / GO-with-caution, 1 NO-GO (blocking), 2 bad invocation.
+EOF
+}
+
+# --- args ---
+JSON_MODE=0
+REPO=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --json) JSON_MODE=1; shift;;
+    -h|--help) usage; exit 0;;
+    -*) echo "Unknown flag: $1" >&2; usage >&2; exit 2;;
+    *) if [[ -z "$REPO" ]]; then REPO="$1"; else echo "Unexpected arg: $1" >&2; exit 2; fi; shift;;
+  esac
+done
+REPO="${REPO:-.}"
+[[ -d "$REPO" ]] || { echo "ERROR: '$REPO' is not a directory" >&2; exit 2; }
+REPO_ABS="$(cd "$REPO" && pwd)"
+
+# --- formatting (color only on a tty, and never in --json) ---
+if [[ -t 1 && "$JSON_MODE" -eq 0 ]]; then B=$'\e[1m'; G=$'\e[32m'; Y=$'\e[33m'; R=$'\e[31m'; D=$'\e[0m'; else B=""; G=""; Y=""; R=""; D=""; fi
+hr()   { [[ "$JSON_MODE" -eq 0 ]] && printf '%s\n' "------------------------------------------------------------"; return 0; }
+sec()  { [[ "$JSON_MODE" -eq 0 ]] && { echo; printf '%s== %s ==%s\n' "$B" "$1" "$D"; }; return 0; }
+ok()   { [[ "$JSON_MODE" -eq 0 ]] && printf '  %s[ OK ]%s %s\n' "$G" "$D" "$1"; return 0; }
+info() { [[ "$JSON_MODE" -eq 0 ]] && printf '         %s\n' "$1"; return 0; }
+warn() { WARNINGS=$((WARNINGS+1)); WARN_J="${WARN_J:+$WARN_J,}\"$(json_escape "$1")\""; [[ "$JSON_MODE" -eq 0 ]] && printf '  %s[WARN]%s %s\n' "$Y" "$D" "$1"; return 0; }
+fail() { BLOCKERS=$((BLOCKERS+1)); FAIL_J="${FAIL_J:+$FAIL_J,}\"$(json_escape "$1")\""; [[ "$JSON_MODE" -eq 0 ]] && printf '  %s[FAIL]%s %s\n' "$R" "$D" "$1"; return 0; }
+
+WARNINGS=0; BLOCKERS=0; WARN_J=""; FAIL_J=""
+
+# --- helpers ---
+count_files() { { git -C "$REPO_ABS" ls-files -- "$@" 2>/dev/null || true; } | wc -l | tr -d ' '; }
+count_loc() {
+  [[ -n "$(git -C "$REPO_ABS" ls-files -- "$@" 2>/dev/null | head -1)" ]] || { echo 0; return; }
+  # cat must run from the repo root so tracked paths resolve.
+  ( cd "$REPO_ABS" && git ls-files -z -- "$@" 2>/dev/null | xargs -0 cat 2>/dev/null ) | wc -l | tr -d ' ' || true
+}
+human() { awk -v n="$1" 'BEGIN{ v=n; split("K M B",u); if(v<1000){printf "%d",v;exit}
+  for(i=1;i<=3;i++){v/=1000; if(v<1000){printf "%.1f%s",v,u[i];exit}}}'; }
+
+# --- collected fields (defaults so --json is always well-formed) ---
+IS_GIT=false; AT_ROOT=false; GIT_TOP=""; COMMIT="none"
+TRACKED=0; ALLDISK=0; TOTAL_LOC=0; CCGO_LOC=0; LANG_J=""
+VEND_J=""; ENGINE=""; VER=""; LIMIT=""; ENGINE_FOUND=false
+RAM_GB=""; FREE_GB=""
+
+hr
+[[ "$JSON_MODE" -eq 0 ]] && printf '%sDraft graph pre-flight%s — %s\n' "$B" "$D" "$REPO_ABS" || true
+hr
+
+# ============================================================
+sec "1. Git boundary"
+# ============================================================
+GIT_TOP="$(git -C "$REPO_ABS" rev-parse --show-toplevel 2>/dev/null || true)"
+if [[ -z "$GIT_TOP" ]]; then
+  fail "Not inside a git repo. The engine would raw-walk the filesystem (no .gitignore filter)."
+  info "Point this at a real git repo root, never a parent container dir."
+  GIT_OK=0
+else
+  GIT_OK=1; IS_GIT=true
+  if [[ "$GIT_TOP" != "$REPO_ABS" ]]; then
+    warn "Not at the git root. Git top is: $GIT_TOP"
+    info "Run /draft:init --graph-only at the git root for whole-repo coverage."
+  else
+    AT_ROOT=true
+    ok "Git root: $GIT_TOP"
+  fi
+  COMMIT="$(git -C "$REPO_ABS" rev-parse --short HEAD 2>/dev/null || echo none)"
+  info "HEAD: $COMMIT"
+  [[ -f "$GIT_TOP/.gitmodules" ]] && warn "Submodules present — engine indexes the superproject's tracked tree; submodule contents may need separate indexing." || true
+fi
+
+# ============================================================
+sec "2. Index scope (git-tracked = what actually gets indexed)"
+# ============================================================
+if [[ "$GIT_OK" -eq 1 ]]; then
+  TRACKED="$(count_files)"
+  ALLDISK="$({ find "$REPO_ABS" -type d -name .git -prune -o -type f -print 2>/dev/null || true; } | wc -l | tr -d ' ')"
+  ok "Git-tracked files: $TRACKED   (on disk: $ALLDISK — the difference is gitignored and SKIPPED)"
+
+  [[ "$JSON_MODE" -eq 0 ]] && { echo; printf '  %-14s %10s %12s\n' "language" "files" "lines"; printf '  %-14s %10s %12s\n' "--------" "-----" "-----"; } || true
+  declare -A GLOBS=(
+    [C/C++]='*.c *.cc *.cpp *.cxx *.h *.hpp *.hh *.hxx'
+    [Go]='*.go'
+    [Python]='*.py'
+    [TS/JS]='*.ts *.tsx *.js *.jsx *.mjs'
+    [Rust]='*.rs'
+    [Java]='*.java'
+  )
+  for lang in "C/C++" Go Python TS/JS Rust Java; do
+    # shellcheck disable=SC2086
+    read -ra g <<< "${GLOBS[$lang]}"
+    f="$(count_files "${g[@]}")"
+    [[ "$f" -eq 0 ]] && continue
+    l="$(count_loc "${g[@]}")"
+    [[ "$JSON_MODE" -eq 0 ]] && printf '  %-14s %10s %12s\n' "$lang" "$f" "$l" || true
+    LANG_J="${LANG_J:+$LANG_J,}{\"lang\":\"$(json_escape "$lang")\",\"files\":$f,\"lines\":$l}"
+    TOTAL_LOC=$((TOTAL_LOC + l))
+    [[ "$lang" == "C/C++" || "$lang" == "Go" ]] && CCGO_LOC=$((CCGO_LOC + l)) || true
+  done
+  [[ "$JSON_MODE" -eq 0 ]] && printf '  %-14s %10s %12s\n' "TOTAL" "$TRACKED" "$TOTAL_LOC" || true
+  info "Source LOC total: $(human "$TOTAL_LOC")   |   C/C++/Go: $(human "$CCGO_LOC")"
+else
+  warn "Skipped — no git repo."
+fi
+
+# ============================================================
+sec "3. Committed vendor/generated trees (these WILL be indexed)"
+# ============================================================
+if [[ "$GIT_OK" -eq 1 ]]; then
+  # Match vendor/generated *directories* (token followed by /) and protobuf-generated
+  # file suffixes — not filenames that merely contain "gen"/"generate".
+  VEND="$(git -C "$REPO_ABS" ls-files 2>/dev/null \
+    | grep -iE '(^|/)(third_party|thirdparty|vendor|external|deps|generated)/|\.pb\.(cc|h|go)$|_pb2\.py$' \
+    | sed -E 's#(^.*/(third_party|thirdparty|vendor|external|deps|generated))/.*#\1/#' \
+    | sort -u | head -40 || true)"
+  if [[ -n "$VEND" ]]; then
+    warn "Committed vendor/generated paths found — gitignore to exclude, or accept index inflation:"
+    while IFS= read -r p; do
+      [[ -z "$p" ]] && continue
+      info "$p"
+      VEND_J="${VEND_J:+$VEND_J,}\"$(json_escape "$p")\""
+    done <<< "$VEND"
+  else
+    ok "No obvious committed vendor/generated trees."
+  fi
+else
+  warn "Skipped — no git repo."
+fi
+
+# ============================================================
+sec "4. Engine availability"
+# ============================================================
+if find_memory_bin "$REPO_ABS" "$SELF_REPO"; then
+  ENGINE="$MEMORY_BIN"
+  ENGINE_FOUND=true
+  VER="$("$ENGINE" --version 2>/dev/null | head -1 || echo '?')"
+  ok "Engine: $ENGINE ($VER)"
+  LIMIT="$("$ENGINE" config list 2>/dev/null | awk '/auto_index_limit/{print $3}' || true)"
+  [[ -n "$LIMIT" ]] && info "auto_index_limit: $LIMIT (governs AUTO-index only; explicit index_repository should bypass)" || true
+  if [[ "$GIT_OK" -eq 1 && -n "${LIMIT:-}" && "$TRACKED" -gt "$LIMIT" ]]; then
+    warn "Tracked files ($TRACKED) > auto_index_limit ($LIMIT) — confirm the explicit index isn't truncated near $LIMIT."
+  fi
+else
+  ENGINE=""
+  fail "Engine 'codebase-memory-mcp' not found (checked \$DRAFT_MEMORY_BIN, PATH, ~/.cache/draft/bin/, vendored bin/<arch>/)."
+  info "Install: scripts/fetch-memory-engine.sh   (or put the binary on PATH)"
+fi
+
+# ============================================================
+sec "5. Machine headroom"
+# ============================================================
+if [[ -r /proc/meminfo ]]; then
+  RAM_GB="$(awk '/MemTotal/{printf "%d", $2/1024/1024}' /proc/meminfo)"
+  ok "Total RAM: ${RAM_GB} GB (engine self-budgets ~half)"
+elif command -v sysctl >/dev/null 2>&1; then
+  RAM_GB="$(( $(sysctl -n hw.memsize 2>/dev/null || echo 0) / 1024 / 1024 / 1024 ))"
+  ok "Total RAM: ${RAM_GB} GB"
+else
+  warn "Could not read total RAM."
+fi
+CACHE_DIR="$HOME/.cache"; mkdir -p "$CACHE_DIR" 2>/dev/null || true
+FREE_K="$(df -Pk "$CACHE_DIR" 2>/dev/null | awk 'NR==2{print $4}' || true)"
+if [[ -n "${FREE_K:-}" ]]; then
+  FREE_GB=$((FREE_K / 1024 / 1024))
+  if [[ "$FREE_GB" -lt 10 ]]; then warn "$CACHE_DIR free: ${FREE_GB} GB (low — index lives here)"; else ok "$CACHE_DIR free: ${FREE_GB} GB"; fi
+fi
+
+# ============================================================
+# Scale heuristic for first-pass time expectation.
+if [[ "$CCGO_LOC" -ge 5000000 || "$TOTAL_LOC" -ge 5000000 ]]; then
+  warn "Large codebase ($(human "$TOTAL_LOC") LOC) — expect a long first-pass index (likely hours). Run backgrounded; incremental thereafter."
+fi
+
+# --- verdict ---
+if [[ "$BLOCKERS" -gt 0 ]]; then VERDICT="NO_GO"; VEXIT=1
+elif [[ "$WARNINGS" -gt 0 ]]; then VERDICT="GO_WITH_CAUTION"; VEXIT=0
+else VERDICT="GO"; VEXIT=0
+fi
+
+# ============================================================
+# Output
+# ============================================================
+if [[ "$JSON_MODE" -eq 1 ]]; then
+  printf '{\n'
+  printf '  "repo": "%s",\n' "$(json_escape "$REPO_ABS")"
+  printf '  "is_git_repo": %s,\n' "$IS_GIT"
+  printf '  "git_root": %s,\n' "$([[ -n "$GIT_TOP" ]] && printf '"%s"' "$(json_escape "$GIT_TOP")" || printf 'null')"
+  printf '  "at_git_root": %s,\n' "$AT_ROOT"
+  printf '  "head": "%s",\n' "$(json_escape "$COMMIT")"
+  printf '  "tracked_files": %s,\n' "$TRACKED"
+  printf '  "files_on_disk": %s,\n' "$ALLDISK"
+  printf '  "languages": [%s],\n' "$LANG_J"
+  printf '  "total_source_loc": %s,\n' "$TOTAL_LOC"
+  printf '  "ccgo_loc": %s,\n' "$CCGO_LOC"
+  printf '  "committed_vendor_paths": [%s],\n' "$VEND_J"
+  printf '  "engine": {"found": %s, "path": %s, "version": %s, "auto_index_limit": %s},\n' \
+    "$ENGINE_FOUND" \
+    "$([[ -n "$ENGINE" ]] && printf '"%s"' "$(json_escape "$ENGINE")" || printf 'null')" \
+    "$([[ -n "$VER" ]] && printf '"%s"' "$(json_escape "$VER")" || printf 'null')" \
+    "${LIMIT:-null}"
+  printf '  "machine": {"ram_gb": %s, "cache_free_gb": %s},\n' "${RAM_GB:-null}" "${FREE_GB:-null}"
+  printf '  "warnings": [%s],\n' "$WARN_J"
+  printf '  "blockers": [%s],\n' "$FAIL_J"
+  printf '  "verdict": "%s",\n' "$VERDICT"
+  printf '  "exit_code": %s\n' "$VEXIT"
+  printf '}\n'
+  exit "$VEXIT"
+fi
+
+sec "Verdict"
+echo
+case "$VERDICT" in
+  NO_GO)          printf '%s NO-GO %s — %d blocker(s), %d warning(s). Resolve blockers above first.\n' "$R" "$D" "$BLOCKERS" "$WARNINGS";;
+  GO_WITH_CAUTION) printf '%s GO (with caution) %s — %d warning(s). Review them, then proceed.\n' "$Y" "$D" "$WARNINGS";;
+  GO)             printf '%s GO %s — clear to index.\n' "$G" "$D";;
+esac
+
+cat <<EOF
+
+Next step (when ready, from the git root):
+  scripts/tools/graph-init.sh --scope . --json &     # or: /draft:init --graph-only
+  ${ENGINE:-codebase-memory-mcp} cli list_projects '{}'
+  ${ENGINE:-codebase-memory-mcp} cli index_status '{"project":"<name>"}'
+EOF
+hr
+exit "$VEXIT"

package/scripts/tools/okf-render-views.sh

@@ -0,0 +1,373 @@
+#!/usr/bin/env bash
+# okf-render-views.sh — render the demoted views from an OKF taxonomy bundle.
+#
+# The wiki/ bundle is the source of truth. This produces the two derived,
+# human-facing views deterministically (so they never drift from the bundle and
+# carry zero extra maintenance):
+#   1. architecture.md  — a single linear concatenation of every concept page,
+#      frontmatter stripped, in canonical section order, with a banner + TOC.
+#      This is the onboarding "read one doc" view (demoted, not deleted).
+#   2. Concept Map       — a routing table injected between the
+#      <!-- CONCEPT-MAP:START --> / <!-- CONCEPT-MAP:END --> markers in
+#      wiki/index.md (and optionally another index-root file).
+#
+# Usage:
+#   okf-render-views.sh <BUNDLE_DIR> --arch-out <FILE> [--concept-map-into <FILE>]
+#
+# BUNDLE_DIR is the wiki/ directory. Exit 0 ok, 1 error, 2 bundle not found.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=scripts/tools/_lib.sh
+source "$SCRIPT_DIR/_lib.sh"
+
+BUNDLE=""
+ARCH_OUT=""
+WEB_OUT=""
+CMAP_INTO=()
+
+usage() {
+    cat <<'EOF'
+okf-render-views.sh — render architecture.md + Concept Map + HTML viewer from an OKF bundle.
+
+Usage:
+  okf-render-views.sh <BUNDLE_DIR> [--arch-out FILE] [--concept-map-into FILE]... [--web FILE]
+
+Flags:
+  --arch-out FILE          Write the rendered linear architecture.md here.
+  --concept-map-into FILE  Inject the Concept Map between the CONCEPT-MAP markers
+                           in FILE (repeatable: e.g. wiki/index.md and ai-context.md).
+  --web FILE               Write a self-contained, offline HTML viewer (single file:
+                           all pages inlined, built-in markdown renderer, sidebar +
+                           search). Double-click to open — no server, no internet.
+  --help                   Show this help.
+
+Requires jq (already a Draft prereq) for --web. Exit 0 ok, 1 error, 2 bundle not found.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --arch-out) ARCH_OUT="$2"; shift 2;;
+        --concept-map-into) CMAP_INTO+=("$2"); shift 2;;
+        --web) WEB_OUT="$2"; shift 2;;
+        --help|-h) usage; exit 0;;
+        -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+        *)
+            if [[ -z "$BUNDLE" ]]; then BUNDLE="$1"; else echo "Unexpected arg: $1" >&2; exit 1; fi
+            shift
+            ;;
+    esac
+done
+
+[[ -n "$BUNDLE" ]] || { usage >&2; exit 1; }
+[[ -d "$BUNDLE" ]] || { echo "ERROR: bundle directory not found: $BUNDLE" >&2; exit 2; }
+BUNDLE="${BUNDLE%/}"
+
+# Canonical section order for the linear render. Sections not present are skipped.
+SECTIONS=(overview systems features reference entrypoints)
+
+# Emit bundle-relative page paths in canonical order: for each section, its
+# index.md first, then the rest alphabetically. Pages outside these sections
+# (e.g. log.md, the bundle root index.md) are excluded from the linear view.
+ordered_pages() {
+    local sec dir f
+    for sec in "${SECTIONS[@]}"; do
+        dir="$BUNDLE/$sec"
+        [[ -d "$dir" ]] || continue
+        [[ -f "$dir/index.md" ]] && echo "$sec/index.md"
+        while IFS= read -r f; do
+            [[ "$(basename "$f")" == "index.md" ]] && continue
+            echo "$sec/${f##*/}"
+        done < <(find "$dir" -maxdepth 1 -type f -name '*.md' | sort)
+    done
+}
+
+# Strip YAML frontmatter from a page (leading --- ... --- block on line 1).
+strip_frontmatter() {
+    awk '
+        NR==1 && /^---$/ { fm=1; next }
+        fm && /^---$/ { fm=0; next }
+        !fm { print }
+    ' "$1"
+}
+
+# --- 1. Render architecture.md ---
+render_architecture() {
+    local out="$1"
+    local tmp; tmp="$(mktemp)"
+    {
+        echo "---"
+        echo "generated_by: \"draft:init (okf-render-views.sh)\""
+        echo "view: rendered"
+        echo "source_of_truth: \"wiki/\""
+        echo "---"
+        echo ""
+        echo "# Architecture (Rendered View)"
+        echo ""
+        echo "> **Generated** from the \`wiki/\` OKF bundle — do not edit by hand."
+        echo "> The bundle is the source of truth; this is the single-document linear"
+        echo "> view for onboarding. Regenerate with \`okf-render-views.sh\`."
+        echo ""
+        echo "## Contents"
+        echo ""
+        # TOC from page titles.
+        local rel title sec last_sec=""
+        while IFS= read -r rel; do
+            [[ -z "$rel" ]] && continue
+            sec="${rel%%/*}"
+            if [[ "$sec" != "$last_sec" ]]; then
+                echo "- **${sec}/**"
+                last_sec="$sec"
+            fi
+            title="$(get_yaml_field "$BUNDLE/$rel" title)"
+            [[ -n "$title" ]] || title="$rel"
+            local anchor; anchor="$(printf '%s' "$title" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-')"
+            anchor="${anchor#-}"; anchor="${anchor%-}"
+            echo "  - [${title}](#${anchor})"
+        done < <(ordered_pages)
+        echo ""
+        # Body: each page, frontmatter stripped.
+        while IFS= read -r rel; do
+            [[ -z "$rel" ]] && continue
+            echo ""
+            echo "---"
+            echo ""
+            strip_frontmatter "$BUNDLE/$rel"
+        done < <(ordered_pages)
+    } >"$tmp"
+    mv "$tmp" "$out"
+    echo "rendered architecture view → $out ($(ordered_pages | grep -c . ) pages)"
+}
+
+# --- 2. Build the Concept Map table (stdout) ---
+build_concept_map() {
+    echo "| Concept | Type | Open it when… |"
+    echo "|---------|------|---------------|"
+    local rel type title desc
+    while IFS= read -r -d '' page; do
+        rel="${page#"$BUNDLE/"}"
+        [[ "$(basename "$rel")" == "index.md" ]] && continue
+        type="$(get_yaml_field "$page" type)"
+        [[ -n "$type" ]] || continue
+        title="$(get_yaml_field "$page" title)"
+        [[ -n "$title" ]] || title="$rel"
+        # description may be a folded (>) block — take the first non-empty body line.
+        desc="$(awk '
+            NR==1&&/^---$/{fm=1;next} fm&&/^---$/{exit}
+            fm && /^description:/ { collect=1; sub(/^description:[[:space:]]*>?[[:space:]]*/,""); if($0!=""){print; exit} next }
+            fm && collect { sub(/^[[:space:]]+/,""); if($0!=""){print; exit} }
+        ' "$page")"
+        echo "| [${title}](${rel}) | ${type} | ${desc} |"
+    done < <(find "$BUNDLE" -type f -name '*.md' -print0 | sort -z)
+}
+
+# Inject the Concept Map between markers in a target file (path may be relative
+# to BUNDLE: links in the map are bundle-relative, so the target should resolve
+# them — wiki/index.md works directly; an index root above wiki/ should prefix).
+inject_concept_map() {
+    local target="$1" map="$2"
+    [[ -f "$target" ]] || { echo "WARN: concept-map target not found: $target" >&2; return 0; }
+    if ! grep -q 'CONCEPT-MAP:START' "$target" || ! grep -q 'CONCEPT-MAP:END' "$target"; then
+        echo "WARN: $target has no CONCEPT-MAP markers — skipping injection" >&2
+        return 0
+    fi
+    local tmp; tmp="$(mktemp)"
+    awk -v mapfile="$map" '
+        /<!-- CONCEPT-MAP:START -->/ { print; while ((getline line < mapfile) > 0) print line; close(mapfile); skip=1; next }
+        /<!-- CONCEPT-MAP:END -->/ { skip=0 }
+        !skip { print }
+    ' "$target" >"$tmp"
+    mv "$tmp" "$target"
+    echo "injected Concept Map → $target"
+}
+
+# --- 3. Render a self-contained offline HTML viewer (single file) ---
+# All pages are inlined as JSON; a small built-in markdown renderer draws them in
+# the browser. No server, no internet, no CDN. jq encodes page content safely
+# (and we neutralize any literal </ so embedded "</script>" can't break parsing).
+render_web() {
+    local out="$1"
+    command -v jq >/dev/null 2>&1 || { echo "ERROR: --web requires jq" >&2; return 1; }
+    local tmp; tmp="$(mktemp)"
+
+    cat >"$tmp" <<'HTML_HEAD'
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Knowledge Bundle</title>
+<style>
+  :root { --bg:#0f1115; --panel:#161a22; --ink:#d7dce5; --muted:#8a93a6; --accent:#6ea8fe; --border:#262c38; --code:#1b2030; }
+  * { box-sizing: border-box; }
+  body { margin:0; font:15px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif; color:var(--ink); background:var(--bg); }
+  #app { display:flex; min-height:100vh; }
+  #side { width:300px; flex:0 0 300px; background:var(--panel); border-right:1px solid var(--border); height:100vh; overflow:auto; position:sticky; top:0; padding:14px; }
+  #side h1 { font-size:14px; margin:0 0 10px; color:var(--muted); text-transform:uppercase; letter-spacing:.05em; }
+  #search { width:100%; padding:8px 10px; margin-bottom:12px; background:var(--code); border:1px solid var(--border); border-radius:6px; color:var(--ink); }
+  .sec { font-size:11px; text-transform:uppercase; letter-spacing:.06em; color:var(--muted); margin:14px 0 4px; }
+  .nav a { display:block; padding:4px 8px; color:var(--ink); text-decoration:none; border-radius:5px; font-size:13.5px; }
+  .nav a:hover { background:var(--code); }
+  .nav a.active { background:var(--accent); color:#0b0e14; }
+  .nav a .ty { float:right; font-size:10px; color:var(--muted); }
+  .nav a.active .ty { color:#0b0e14; }
+  #main { flex:1; max-width:900px; padding:32px 44px; }
+  #content h1,#content h2,#content h3 { line-height:1.25; }
+  #content h1 { font-size:28px; border-bottom:1px solid var(--border); padding-bottom:8px; }
+  #content a { color:var(--accent); }
+  #content code { background:var(--code); padding:2px 5px; border-radius:4px; font-size:90%; }
+  #content pre { background:var(--code); border:1px solid var(--border); border-radius:8px; padding:12px 14px; overflow:auto; }
+  #content pre code { background:none; padding:0; }
+  #content pre.mermaid-src { border-left:3px solid var(--accent); }
+  #content pre.mermaid-src::before { content:"⬡ Mermaid diagram (source)"; display:block; color:var(--muted); font-size:11px; margin-bottom:6px; }
+  #content table { border-collapse:collapse; width:100%; margin:14px 0; font-size:13.5px; }
+  #content th,#content td { border:1px solid var(--border); padding:6px 9px; text-align:left; vertical-align:top; }
+  #content th { background:var(--code); }
+  #content blockquote { border-left:3px solid var(--border); margin:12px 0; padding:2px 14px; color:var(--muted); }
+  #content hr { border:none; border-top:1px solid var(--border); margin:22px 0; }
+  .crumb { color:var(--muted); font-size:12px; margin-bottom:8px; }
+</style>
+</head>
+<body>
+<div id="app">
+  <nav id="side">
+    <h1>Knowledge Bundle</h1>
+    <input id="search" placeholder="Search…" autocomplete="off">
+    <div id="nav" class="nav"></div>
+  </nav>
+  <main id="main"><div id="content"></div></main>
+</div>
+<script>
+HTML_HEAD
+
+    # Inline page data: PAGES[rel] = {title, type, md}, plus ORDER (index first).
+    {
+        echo "const PAGES = {"
+        while IFS= read -r -d '' page; do
+            local rel title type
+            rel="${page#"$BUNDLE/"}"
+            title="$(get_yaml_field "$page" title)"; [[ -n "$title" ]] || title="$rel"
+            type="$(get_yaml_field "$page" type)"
+            printf '%s: {"title": %s, "type": %s, "md": %s},\n' \
+                "$(jq -Rn --arg v "$rel" '$v')" \
+                "$(jq -Rn --arg v "$title" '$v')" \
+                "$(jq -Rn --arg v "$type" '$v')" \
+                "$(strip_frontmatter "$page" | jq -Rs . | sed 's#</#<\\/#g')"
+        done < <(find "$BUNDLE" -type f -name '*.md' -print0 | sort -z)
+        echo "};"
+        # ORDER: bundle root index.md first, then everything else sorted.
+        echo "const ORDER = Object.keys(PAGES).sort(function(a,b){"
+        echo "  if(a==='index.md') return -1; if(b==='index.md') return 1;"
+        echo "  return a<b?-1:a>b?1:0; });"
+    } >>"$tmp"
+
+    cat >>"$tmp" <<'HTML_TAIL'
+function esc(s){return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');}
+function resolve(base, href){
+  if(/^[a-z]+:\/\//.test(href)||href[0]==='#') return href;
+  var dir = base.indexOf('/')<0 ? '' : base.replace(/\/[^/]*$/,'');
+  var parts = (dir? dir.split('/'):[]).concat(href.split('/')), out=[];
+  for(var i=0;i<parts.length;i++){ var p=parts[i];
+    if(p==='..') out.pop(); else if(p!=='.'&&p!=='') out.push(p); }
+  return out.join('/');
+}
+function inline(s, base){
+  s = s.replace(/`([^`]+)`/g, function(m,c){return '<code>'+esc(c)+'</code>';});
+  s = s.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, function(m,t,u){
+    if(/^[a-z]+:\/\//.test(u)) return '<a href="'+u+'" target="_blank" rel="noopener">'+t+'</a>';
+    var key=resolve(base,u);
+    if(PAGES[key]) return '<a href="#'+key+'" data-nav="'+key+'">'+t+'</a>';
+    return '<span title="'+esc(u)+'">'+t+'</span>';
+  });
+  s = s.replace(/\*\*([^*]+)\*\*/g,'<strong>$1</strong>');
+  s = s.replace(/(^|[^*])\*([^*\n]+)\*/g,'$1<em>$2</em>');
+  return s;
+}
+function render(md, base){
+  // Pull fenced code blocks out first so their contents aren't block-parsed.
+  var blocks=[], src=md.replace(/```(\w*)\n([\s\S]*?)```/g,function(m,lang,body){
+    var cls = lang==='mermaid' ? ' class="mermaid-src"' : '';
+    blocks.push('<pre'+cls+'><code>'+esc(body.replace(/\n$/,''))+'</code></pre>');
+    return 'BLOCK'+(blocks.length-1)+'';
+  });
+  var lines=src.split('\n'), out='', i=0, list='', tbl=[];
+  function closeList(){ if(list){ out+='</'+list+'>'; list=''; } }
+  function flushTbl(){
+    if(!tbl.length) return;
+    var rows=tbl.filter(function(r){return !/^\s*\|?[\s:|-]+\|?\s*$/.test(r);});
+    out+='<table>';
+    rows.forEach(function(r,ri){
+      var cells=r.replace(/^\||\|$/g,'').split('|');
+      out+='<tr>'+cells.map(function(c){var t=ri===0?'th':'td';return '<'+t+'>'+inline(c.trim(),base)+'</'+t+'>';}).join('')+'</tr>';
+    });
+    out+='</table>'; tbl=[];
+  }
+  for(;i<lines.length;i++){
+    var ln=lines[i];
+    if(/^\s*\|.*\|\s*$/.test(ln)){ closeList(); tbl.push(ln); continue; } else flushTbl();
+    var h=ln.match(/^(#{1,6})\s+(.*)$/);
+    if(h){ closeList(); out+='<h'+h[1].length+'>'+inline(esc(h[2]),base)+'</h'+h[1].length+'>'; continue; }
+    if(/^\s*---\s*$/.test(ln)){ closeList(); out+='<hr>'; continue; }
+    if(/^\s*>\s?/.test(ln)){ closeList(); out+='<blockquote>'+inline(esc(ln.replace(/^\s*>\s?/,'')),base)+'</blockquote>'; continue; }
+    var li=ln.match(/^\s*([-*]|\d+\.)\s+(.*)$/);
+    if(li){ var want=/^\d/.test(li[1])?'ol':'ul'; if(list!==want){ closeList(); list=want; out+='<'+want+'>'; } out+='<li>'+inline(esc(li[2]),base)+'</li>'; continue; }
+    var b=ln.match(/^BLOCK(\d+)$/);
+    if(b){ closeList(); out+=blocks[+b[1]]; continue; }
+    if(/^\s*$/.test(ln)){ closeList(); continue; }
+    closeList(); out+='<p>'+inline(esc(ln),base)+'</p>';
+  }
+  flushTbl(); closeList();
+  return out;
+}
+var navEl=document.getElementById('nav'), contentEl=document.getElementById('content');
+function section(k){ return k.indexOf('/')<0 ? '(root)' : k.split('/')[0]; }
+function buildNav(filter){
+  navEl.innerHTML=''; var lastSec=null;
+  ORDER.forEach(function(k){
+    var p=PAGES[k];
+    if(filter && (p.title+' '+p.md).toLowerCase().indexOf(filter)<0) return;
+    var sec=section(k);
+    if(sec!==lastSec){ var s=document.createElement('div'); s.className='sec'; s.textContent=sec; navEl.appendChild(s); lastSec=sec; }
+    var a=document.createElement('a'); a.href='#'+k; a.dataset.nav=k;
+    a.innerHTML=esc(p.title)+(p.type?'<span class="ty">'+esc(p.type)+'</span>':'');
+    navEl.appendChild(a);
+  });
+}
+function show(k){
+  var p=PAGES[k]; if(!p){ k=ORDER[0]; p=PAGES[k]; }
+  contentEl.innerHTML='<div class="crumb">'+esc(k)+'</div>'+render(p.md,k);
+  document.querySelectorAll('#nav a').forEach(function(a){ a.classList.toggle('active', a.dataset.nav===k); });
+  if(location.hash.slice(1)!==k) history.replaceState(null,'','#'+k);
+  contentEl.parentElement.scrollTop=0; window.scrollTo(0,0);
+}
+document.addEventListener('click',function(e){ var a=e.target.closest('[data-nav]'); if(a){ e.preventDefault(); show(a.dataset.nav); } });
+document.getElementById('search').addEventListener('input',function(e){ buildNav(e.target.value.toLowerCase().trim()); });
+window.addEventListener('hashchange',function(){ var k=decodeURIComponent(location.hash.slice(1)); if(PAGES[k]) show(k); });
+buildNav('');
+show(decodeURIComponent(location.hash.slice(1)) || ORDER[0]);
+</script>
+</body>
+</html>
+HTML_TAIL
+
+    mkdir -p "$(dirname "$out")"
+    mv "$tmp" "$out"
+    echo "rendered offline HTML viewer → $out ($(find "$BUNDLE" -type f -name '*.md' | grep -c .) pages)"
+}
+
+[[ -n "$ARCH_OUT" ]] && render_architecture "$ARCH_OUT"
+
+if [[ ${#CMAP_INTO[@]} -gt 0 ]]; then
+    MAP_TMP="$(mktemp)"
+    build_concept_map >"$MAP_TMP"
+    for tgt in "${CMAP_INTO[@]}"; do
+        inject_concept_map "$tgt" "$MAP_TMP"
+    done
+    rm -f "$MAP_TMP"
+fi
+
+[[ -n "$WEB_OUT" ]] && render_web "$WEB_OUT"
+
+[[ -n "$ARCH_OUT" || -n "$WEB_OUT" || ${#CMAP_INTO[@]} -gt 0 ]] || { echo "ERROR: nothing to do (pass --arch-out, --web, and/or --concept-map-into)" >&2; exit 1; }
+exit 0