@drafthq/draft 3.5.0 → 3.5.2

package/scripts/tools/_lib.sh

@@ -203,6 +203,73 @@ memory_project_for_repo() {
         | head -1
 }
 
+# Total physical RAM in MB (portable). Echoes a positive integer, or nothing.
+_total_ram_mb() {
+    if [[ -r /proc/meminfo ]]; then
+        awk '/^MemTotal:/{printf "%d", $2/1024; exit}' /proc/meminfo
+    elif command -v sysctl >/dev/null 2>&1; then   # macOS / BSD
+        local bytes; bytes="$(sysctl -n hw.memsize 2>/dev/null || true)"
+        [[ -n "$bytes" ]] && printf '%d' "$(( bytes / 1024 / 1024 ))"
+    fi
+}
+
+# Cgroup memory args for a transient scope. MemoryHigh throttles (reclaim/swap →
+# slower, never thrashes the host); MemoryMax is the hard ceiling a few % above.
+# Pure (no I/O) so it is unit-testable. Usage: _mem_bound_args <total_mb> <pct>
+_mem_bound_args() {
+    local total="$1" pct="$2"
+    printf 'MemoryHigh=%dM MemoryMax=%dM' \
+        "$(( total * pct / 100 ))" "$(( total * (pct + 5) / 100 ))"
+}
+
+# Whether this host can confine a process to a memory-bounded cgroup v2 scope.
+# Probes once (starts a throwaway scope) and caches the verdict for the process.
+_DRAFT_CGROUP_OK=""
+_can_cgroup_bound() {
+    if [[ -z "$_DRAFT_CGROUP_OK" ]]; then
+        if command -v systemd-run >/dev/null 2>&1 \
+            && [[ -e /sys/fs/cgroup/cgroup.controllers ]] \
+            && systemd-run --user --scope -q -p MemoryMax=64M -- true >/dev/null 2>&1; then
+            _DRAFT_CGROUP_OK=yes
+        else
+            _DRAFT_CGROUP_OK=no
+        fi
+    fi
+    [[ "$_DRAFT_CGROUP_OK" == yes ]]
+}
+
+# Index a repository under a memory bound. The codebase-memory-mcp engine
+# self-budgets ~50% of *physical* RAM and is not cgroup-aware, so a first index
+# of a huge repo can exhaust the host (the original 30 GB hang). On Linux we
+# confine it to a transient cgroup scope sized to DRAFT_INDEX_MEM_PCT (default
+# 25) of total RAM; CBM_WORKERS caps the engine's parallel working set so the
+# throttle has less transient pressure to absorb. Where cgroup v2 + systemd-run
+# are unavailable (e.g. macOS) the worker cap is the only bound. Never falls back
+# from a started scope to an unbounded run — a bounded OOM fails the index
+# cleanly (host stays alive) rather than re-triggering the hang.
+# Echoes the engine's JSON result on stdout (same contract as memory_cli).
+memory_index_bounded() {
+    local repo_abs="$1"
+    local json="{\"repo_path\":\"$repo_abs\"}"
+    export CBM_WORKERS="${CBM_WORKERS:-4}"
+    local total pct
+    total="$(_total_ram_mb)"
+    pct="${DRAFT_INDEX_MEM_PCT:-25}"
+    if [[ "${total:-0}" -gt 0 ]] && _can_cgroup_bound; then
+        local high_arg max_arg
+        read -r high_arg max_arg <<< "$(_mem_bound_args "$total" "$pct")"
+        if [[ -n "${DRAFT_MEMORY_DEBUG:-}" ]]; then
+            systemd-run --user --scope -q -p "$high_arg" -p "$max_arg" \
+                -- "$MEMORY_BIN" cli index_repository "$json"
+        else
+            systemd-run --user --scope -q -p "$high_arg" -p "$max_arg" \
+                -- "$MEMORY_BIN" cli index_repository "$json" 2>/dev/null
+        fi
+    else
+        memory_cli index_repository "$json"
+    fi
+}
+
 # Ensure a repository is indexed in the engine; echo its project name.
 # Indexes on demand when absent. Returns 1 if the engine is unavailable.
 memory_ensure_index() {
@@ -212,7 +279,7 @@ memory_ensure_index() {
     local proj
     proj="$(memory_project_for_repo "$repo_abs" 2>/dev/null || true)"
     if [[ -z "$proj" ]]; then
-        proj="$(memory_cli index_repository "{\"repo_path\":\"$repo_abs\"}" 2>/dev/null \
+        proj="$(memory_index_bounded "$repo_abs" \
             | jq -r '.project // empty' 2>/dev/null || true)"
     fi
     [[ -n "$proj" ]] || return 1

package/scripts/tools/okf-plan-concepts.sh

@@ -38,6 +38,7 @@ MANIFEST=""
 MIN_FAN_IN=2
 OUT=""
 JSON=0
+DEFER_BELOW_FLOOR=0
 ALLOW_DEFER=()
 
 usage() {
@@ -54,8 +55,12 @@ Flags:
   --manifest FILE    Component list (one component per line; '#' comments; blanks
                      ignored). When present it is authoritative — every entry is
                      required and the graph is not consulted.
-  --min-fan-in N     Package fan-in floor for "required" (default: 2). Packages
-                     below the floor are deferred with a reason.
+  --min-fan-in N     Fan-in threshold that types a package as a Subsystem (>=N)
+                     vs a Module (<N) and orders it first (default: 2). By default
+                     EVERY graph package is required regardless of fan-in — the
+                     floor no longer exempts anything.
+  --defer-below-floor  Restore the old behavior: packages with fan_in < --min-fan-in
+                     are deferred (not required) instead of required-as-Module.
   --allow-defer GLOB Defer (don't require) components whose name matches GLOB.
                      Repeatable. Deferred entries still appear in the plan.
   --out FILE         Write the plan JSON here (default: stdout).
@@ -72,6 +77,7 @@ while [[ $# -gt 0 ]]; do
         --scope) SCOPE="$2"; shift 2;;
         --manifest) MANIFEST="$2"; shift 2;;
         --min-fan-in) MIN_FAN_IN="$2"; shift 2;;
+        --defer-below-floor) DEFER_BELOW_FLOOR=1; shift;;
         --allow-defer) ALLOW_DEFER+=("$2"); shift 2;;
         --out) OUT="$2"; shift 2;;
         --json) JSON=1; shift;;
@@ -150,8 +156,13 @@ plan_from_graph() {
             required=false; reason="allow-defer match"; type=Module
         elif (( fan_in >= MIN_FAN_IN )); then
             required=true; reason=""; type=Subsystem
-        else
+        elif [[ $DEFER_BELOW_FLOOR -eq 1 ]]; then
+            # Opt-in legacy behavior: low-fan-in packages are exempted.
             required=false; reason="fan_in $fan_in < floor $MIN_FAN_IN"; type=Module
+        else
+            # Default: every package the graph knows about is documented. Fan-in
+            # below the floor only demotes Subsystem→Module; it never exempts.
+            required=true; reason=""; type=Module
         fi
         add_concept "$name" systems "$type" "$name" "$fan_in" "$required" "$reason"
     done < <(echo "$arch" | jq -r '.packages[]? | [.name, (.fan_in // 0)] | @tsv')

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

@@ -10,6 +10,9 @@
 #   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).
+#   3. Section indexes   — (--section-indexes) each <section>/index.md concept
+#      table rebuilt from the pages that actually exist in that directory, so its
+#      links can never dangle (no more hand-authored, link-rotting indexes).
 #
 # Usage:
 #   okf-render-views.sh <BUNDLE_DIR> --arch-out <FILE> [--concept-map-into <FILE>]
@@ -25,6 +28,7 @@ BUNDLE=""
 ARCH_OUT=""
 WEB_OUT=""
 CMAP_INTO=()
+SECTION_INDEXES=0
 COVERAGE_REPORT=""
 VALIDATED_AT=""
 
@@ -39,6 +43,10 @@ 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).
+  --section-indexes        Regenerate each section's <section>/index.md concept
+                           table (between its CONCEPT-MAP markers) from the pages
+                           that actually exist in that directory. Eliminates
+                           hand-authored, link-rotting section indexes.
   --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.
@@ -56,6 +64,7 @@ while [[ $# -gt 0 ]]; do
     case "$1" in
         --arch-out) ARCH_OUT="$2"; shift 2;;
         --concept-map-into) CMAP_INTO+=("$2"); shift 2;;
+        --section-indexes) SECTION_INDEXES=1; shift;;
         --web) WEB_OUT="$2"; shift 2;;
         --coverage-report) COVERAGE_REPORT="$2"; shift 2;;
         --validated-at) VALIDATED_AT="$2"; shift 2;;
@@ -134,7 +143,7 @@ render_architecture() {
         echo ""
         echo "# Architecture (Rendered View)"
         echo ""
-        echo "> **Generated** from the \`wiki/\` OKF bundle — do not edit by hand."
+        echo "> **Generated** from the \`wiki/\` 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 ""
@@ -192,6 +201,50 @@ build_concept_map() {
     done < <(find "$BUNDLE" -type f -name '*.md' -print0 | sort -z)
 }
 
+# First non-empty line of a page's `description` frontmatter (handles folded `>`).
+page_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} }
+    ' "$1"
+}
+
+# Build the per-section concept table (stdout) for a single section directory.
+# Links are bundle-section-relative (just the filename) so they resolve from the
+# section's own index.md. Only pages that actually exist are listed — so the
+# table can never point at a missing file.
+build_section_map() {
+    local dir="$1" f rel base type title desc
+    echo "| Concept | Type | Routing description |"
+    echo "|---------|------|---------------------|"
+    while IFS= read -r f; do
+        base="$(basename "$f")"
+        [[ "$base" == "index.md" ]] && continue
+        [[ "$base" == "coverage.md" ]] && continue
+        grep -q '<!-- okf:coverage-generated -->' "$f" 2>/dev/null && continue
+        type="$(get_yaml_field "$f" type)"
+        [[ -n "$type" ]] || continue
+        title="$(get_yaml_field "$f" title)"; [[ -n "$title" ]] || title="$base"
+        desc="$(page_desc "$f")"
+        echo "| [${title}](${base}) | ${type} | ${desc} |"
+    done < <(find "$dir" -maxdepth 1 -type f -name '*.md' | sort)
+}
+
+# Regenerate every <section>/index.md concept table from real pages.
+render_section_indexes() {
+    local sec dir idx
+    for sec in "${SECTIONS[@]}"; do
+        dir="$BUNDLE/$sec"
+        idx="$dir/index.md"
+        [[ -d "$dir" && -f "$idx" ]] || continue
+        local map_tmp; map_tmp="$(mktemp)"
+        build_section_map "$dir" >"$map_tmp"
+        inject_concept_map "$idx" "$map_tmp"
+        rm -f "$map_tmp"
+    done
+}
+
 # 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).
@@ -397,7 +450,10 @@ if [[ ${#CMAP_INTO[@]} -gt 0 ]]; then
     rm -f "$MAP_TMP"
 fi
 
+[[ $SECTION_INDEXES -eq 1 ]] && render_section_indexes
+
 [[ -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; }
+[[ -n "$ARCH_OUT" || -n "$WEB_OUT" || ${#CMAP_INTO[@]} -gt 0 || $SECTION_INDEXES -eq 1 ]] \
+    || { echo "ERROR: nothing to do (pass --arch-out, --web, --section-indexes, and/or --concept-map-into)" >&2; exit 1; }
 exit 0

package/scripts/tools/okf-validate-quality.sh

@@ -11,7 +11,8 @@
 # Pages in scope: any *.md whose frontmatter declares a frozen `type:`. Section
 # index.md pages, log.md, and the generated coverage page are excluded.
 #
-# Checks (per type): required H2 sections, min body lines, >=1 mermaid block
+# Checks (per type): required H2 sections AND real content beneath each (so a
+# present-but-empty heading fails as "shallow"), min body lines, >=1 mermaid block
 # (diagram types only), min x-grounded-paths, anti-stub patterns, unreplaced
 # template tokens, duplicate "What it is" paragraphs, and a syntax-only mermaid
 # lint (no Node, no headless browser).
@@ -88,6 +89,19 @@ grounded_count() {
 
 has_section() { grep -qE "^##[[:space:]]+$1([[:space:]]|$)" "$2"; }
 
+# Count non-blank content lines under a given H2 section (heading itself
+# excluded), stopping at the next H2. Used to fail a section that is present as a
+# heading but carries no real content — the classic "shallow" page.
+section_content_lines() {
+    local sec="$1" file="$2"
+    awk -v sec="$sec" '
+        $0 ~ "^##[[:space:]]+" sec "([[:space:]]|$)" { grab=1; next }
+        grab && /^##[[:space:]]/ { exit }
+        grab && /[^[:space:]]/ { n++ }
+        END { print n+0 }
+    ' "$file"
+}
+
 mermaid_block_count() { grep -cE '^[[:space:]]*```mermaid' "$1" || true; }
 
 # Syntax-only mermaid lint: catch the breakers that silently fail previewers
@@ -139,19 +153,22 @@ whatitis_hash() {
 ANTI_STUB='see architecture\.md|deferred to ref-docs|\bTBD\b|TODO:[[:space:]]*document|stub page|placeholder page'
 TOKEN_RE='\{[A-Z_]+\}'
 
-# Per-type policy. echoes: sections|min_lines|need_mermaid|min_grounded
+# Per-type policy. echoes: sections|min_lines|need_mermaid|min_grounded|min_section_lines
+# min_section_lines: minimum non-blank content lines required UNDER each named
+# section (0 disables the per-section depth check). This is what turns a
+# present-but-empty heading — the hallmark of a shallow page — into a failure.
 type_policy() {
     case "$1" in
         Subsystem|Module|Feature|Entrypoint)
-            echo "What it is;How it works;Used by;Blast radius;See also|25|1|2";;
+            echo "What it is;How it works;Used by;Blast radius;See also|35|1|2|2";;
         API|DataModel)
-            echo "What it is;How it works;See also|18|0|1";;
+            echo "What it is;How it works;See also|22|0|1|2";;
         Dependency)
-            echo "What it is;Used by|10|0|0";;
+            echo "What it is;Used by|12|0|0|1";;
         ADR|Runbook)
-            echo "|8|0|0";;
+            echo "|8|0|0|0";;
         *)
-            echo "|8|0|0";;
+            echo "|8|0|0|0";;
     esac
 }
 
@@ -172,13 +189,26 @@ while IFS= read -r -d '' page; do
     [[ -z "$type_val" ]] && continue   # not a concept page
     CHECKED=$((CHECKED + 1))
 
-    IFS='|' read -r sections min_lines need_mermaid min_grounded <<< "$(type_policy "$type_val")"
+    IFS='|' read -r sections min_lines need_mermaid min_grounded min_section_lines <<< "$(type_policy "$type_val")"
 
-    # Q-SEC: required sections.
+    # Q-SEC: required sections must be present. Q-SECLEN: the NARRATIVE sections
+    # ("What it is" / "How it works") must carry real prose beneath the heading —
+    # a heading with nothing under it is the classic shallow stub. List sections
+    # ("Used by", "See also", "Blast radius") are legitimately terse, so the
+    # depth bar only applies to the narrative ones.
     if [[ -n "$sections" ]]; then
         IFS=';' read -ra secs <<< "$sections"
         for s in "${secs[@]}"; do
-            has_section "$s" "$page" || fail "$rel" "Q-SEC" "missing required section '## $s'"
+            if ! has_section "$s" "$page"; then
+                fail "$rel" "Q-SEC" "missing required section '## $s'"
+            elif [[ "${min_section_lines:-0}" -gt 0 ]]; then
+                case "$s" in
+                    "What it is"|"How it works")
+                        scl="$(section_content_lines "$s" "$page")"
+                        [[ "$scl" -ge "$min_section_lines" ]] \
+                            || fail "$rel" "Q-SECLEN" "section '## $s' has $scl content lines < $min_section_lines (shallow)";;
+                esac
+            fi
         done
     fi
 

package/scripts/tools/okf-validate.sh

@@ -11,6 +11,11 @@
 #   2. Every concept page (any *.md whose frontmatter declares `type:`) carries
 #      all required OKF frontmatter keys: type, title, description, resource.
 #   3. Every declared `type` is in the frozen code-repo vocabulary (§4 of HLD).
+#   3a. Every non-meta *.md is a real concept: an empty or frontmatter-less page
+#      (a blank placeholder) fails — it would otherwise be invisible to the
+#      quality + coverage layers, which both key on `type`.
+#   3b. No page carries an unreplaced {ALL_CAPS} template token (catches leftover
+#      placeholders in hand-seeded index pages, which the quality layer skips).
 #   4. Every relative markdown cross-link ( ](path.md) ) resolves to a file that
 #      exists inside the bundle. External (http/https/mailto) and pure-anchor
 #      (#frag) links are ignored.
@@ -105,14 +110,46 @@ if [[ ! -f "$BUNDLE/index.md" ]]; then
     add_error "missing bundle root: $BUNDLE/index.md"
 fi
 
+# A page is "meta" (not a concept) if it is a section/root index, the change log,
+# or the tool-generated coverage page. Everything else MUST be a real concept —
+# an empty or frontmatter-less .md placeholder is a completeness failure, not an
+# invisible non-concept.
+is_meta_page() {
+    local base="$1" page="$2"
+    case "$base" in
+        index.md|log.md|coverage.md) return 0;;
+    esac
+    grep -q '<!-- okf:coverage-generated -->' "$page" 2>/dev/null && return 0
+    return 1
+}
+
+# Non-blank body line count (everything after the frontmatter block).
+nonblank_body_lines() {
+    awk 'NR==1&&/^---$/{fm=1;next} fm&&/^---$/{fm=0;next} !fm{print}' "$1" \
+        | grep -cE '[^[:space:]]' || true
+}
+
 # --- 2/3. Per-page frontmatter + type vocabulary ---
 while IFS= read -r -d '' page; do
     PAGE_COUNT=$((PAGE_COUNT + 1))
     rel="${page#"$BUNDLE/"}"
+    base="$(basename "$rel")"
 
-    # A page is a "concept" only if its frontmatter declares a type.
     type_val="$(get_yaml_field "$page" "type")"
-    [[ -z "$type_val" ]] && continue
+
+    # Empty / placeholder pages: a non-meta page with no type (or no body) slips
+    # past every downstream check (quality + coverage both key on `type`). Catch
+    # it here so a blank or stub file can never ship.
+    if [[ -z "$type_val" ]]; then
+        if ! is_meta_page "$base" "$page"; then
+            if [[ "$(nonblank_body_lines "$page")" -eq 0 ]]; then
+                add_error "$rel: empty page (no frontmatter type, no body) — every wiki page must be a real concept"
+            else
+                add_error "$rel: untyped page (missing frontmatter 'type:') — not a valid concept page"
+            fi
+        fi
+        continue
+    fi
     CONCEPT_COUNT=$((CONCEPT_COUNT + 1))
 
     for key in title description resource; do
@@ -124,6 +161,24 @@ while IFS= read -r -d '' page; do
     if ! is_known_type "$type_val"; then
         add_error "$rel: unknown concept type '$type_val' (frozen vocab: $OKF_TYPES)"
     fi
+
+    # A typed concept page with no body is still a stub — fail it even though the
+    # depth/anti-stub bars live in the quality layer (this layer must stand alone).
+    if [[ "$(nonblank_body_lines "$page")" -eq 0 ]]; then
+        add_error "$rel: concept page has empty body"
+    fi
+done < <(find "$BUNDLE" -type f -name '*.md' -print0 | sort -z)
+
+# --- 3b. Unreplaced template tokens (any page, including index pages) ---
+# Quality checks skip index.md pages, so a leftover {SECTION_TITLE}/{PROJECT_NAME}
+# placeholder in a hand-seeded index would otherwise survive. Match {ALL_CAPS}
+# tokens (safe: real prose almost never contains them).
+while IFS= read -r -d '' page; do
+    prel="${page#"$BUNDLE/"}"
+    if grep -qE '\{[A-Z][A-Z0-9_]+\}' "$page" 2>/dev/null; then
+        tok="$(grep -oE '\{[A-Z][A-Z0-9_]+\}' "$page" | head -1)"
+        add_error "$prel: unreplaced template token '$tok'"
+    fi
 done < <(find "$BUNDLE" -type f -name '*.md' -print0 | sort -z)
 
 # --- 4. Cross-link resolution ---

package/skills/init/SKILL.md

@@ -221,7 +221,7 @@ The tier-gated default rests on **maintainability/readability** (one navigable c
 1. `okf-plan-concepts.sh` ran and the expected/required/deferred counts were logged **before** any page was written (the concept boundary is a tool output, not an in-context guess).
 2. Every `required` entry in `concept-plan.json` has a non-stub page.
 3. `okf-validate-all.sh … --plan … --strict` exits 0 (structure + per-type quality + coverage all pass).
-4. `systems/coverage.md` was generated by tooling (verify the `<!-- okf:coverage-generated -->` marker) — no required package with `fan_in ≥ floor` is **MISSING**.
+4. `systems/coverage.md` was generated by tooling (verify the `<!-- okf:coverage-generated -->` marker) — **every** package/module the graph found is required by default (the fan-in floor only types Subsystem-vs-Module, it does not exempt), so none may be **MISSING**. Section `index.md` tables are regenerated by `okf-render-views.sh --section-indexes`, never hand-authored, so their links cannot dangle.
 5. On any failure: **do not** atomic-rename; surface `.state/validation-report.json`.
 
 > **Red flag:** writing concept pages without first running `okf-plan-concepts.sh`, or finishing generation while any `required` plan entry is unwritten, is a **completeness failure** — not a stylistic one.

package/skills/init/references/okf-emitter.md

@@ -122,17 +122,21 @@ Derive concepts from the graph, not by hand:
 ```
 1. Survey        → existing /draft:init 5-phase + graph snapshot (graph-snapshot.sh)
 2. Plan          → DETERMINISTIC. okf-plan-concepts.sh derives the expected-concept
-                   set from the graph (every package with fan_in ≥ floor → required
-                   Subsystem/Module; entrypoints → required; below-floor / allow-defer
-                   → deferred with a reason) and writes draft.tmp/.state/concept-plan.json.
+                   set from the graph. EVERY package the graph knows about is
+                   required (fan_in ≥ floor → Subsystem; below floor → Module — the
+                   floor only types/orders, it never exempts); entrypoints → required;
+                   only --allow-defer matches are deferred (with a reason). Writes
+                   draft.tmp/.state/concept-plan.json.
                      okf-plan-concepts.sh --repo . [--scope PATH] \
                        [--manifest FILE] [--min-fan-in 2] [--allow-defer GLOB]... \
                        --out draft.tmp/.state/concept-plan.json
                    This replaces the old in-context concept enumeration — the boundary
                    of the work is now a tool output, not an LLM judgment, so modules
-                   cannot be silently dropped. LOG the counts (expected/required/
-                   deferred) BEFORE writing any page. `generated_order` is topo-ish
-                   (required + high-fan-in first) so forward cross-links resolve.
+                   and sub-modules cannot be silently dropped. (Legacy fan-in
+                   exemption is opt-in via --defer-below-floor.) LOG the counts
+                   (expected/required/deferred) BEFORE writing any page.
+                   `generated_order` is topo-ish (required + high-fan-in first) so
+                   forward cross-links resolve.
 3. Generate      → iterate concept-plan.generated_order; write ONE page per REQUIRED
                    entry, grounding each from the graph:
                      x-callers        ← graph-callers.sh --symbol <c>
@@ -152,9 +156,11 @@ Derive concepts from the graph, not by hand:
                            --plan draft.tmp/.state/concept-plan.json \
                            --path-index draft.tmp/.state/path-to-concept.json \
                            --strict --report draft.tmp/.state/validation-report.json
-                   It runs, in order: okf-validate.sh (structure + reverse index),
-                   okf-validate-quality.sh (per-type anti-stub / depth / mermaid lint),
-                   okf-coverage-check.sh (every required plan entry → real page).
+                   It runs, in order: okf-validate.sh (structure + reverse index +
+                   empty/untyped-page + leftover-template-token + dangling-link checks),
+                   okf-validate-quality.sh (per-type anti-stub / depth / per-section
+                   content / mermaid lint), okf-coverage-check.sh (every required plan
+                   entry → real page).
                    ANY layer failing ⇒ exit non-zero ⇒ DO NOT atomic-rename.
                    coverage.md (systems/coverage.md) is regenerated by the coverage
                    layer; it is tool-owned (marker <!-- okf:coverage-generated -->) —
@@ -193,6 +199,7 @@ regenerated on every init/refresh so they never drift from the bundle:
 ```bash
 okf-render-views.sh draft/wiki \
   --arch-out draft/architecture.md \
+  --section-indexes \
   --concept-map-into draft/wiki/index.md \
   --concept-map-into draft/.ai-context.md \
   --web draft/wiki/web/index.html
@@ -200,6 +207,11 @@ okf-render-views.sh draft/wiki \
 
 - `--arch-out` renders the linear `architecture.md` (banner + TOC + every concept
   page in canonical section order, frontmatter stripped, Mermaid preserved).
+- `--section-indexes` rebuilds each `<section>/index.md` concept table (between its
+  `CONCEPT-MAP` markers) from the pages that actually exist in that directory. This
+  is mandatory: section indexes are NOT hand-authored — building them from real
+  files is what makes their links impossible to dangle. Never write a section
+  index "Concepts" table by hand.
 - `--concept-map-into` rebuilds the routing table between the
   `<!-- CONCEPT-MAP:START -->` / `:END` markers from each concept's `title` +
   `type` + `description` (section `index.md` pages excluded).