@drafthq/draft 3.5.2 → 3.6.0

package/scripts/tools/graph-impact.sh

@@ -43,10 +43,10 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --file) FILE="$2"; shift 2;;
-        --symbol) SYMBOL="$2"; shift 2;;
-        --depth) DEPTH="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --file) FILE="${2:?--file requires a value}"; shift 2;;
+        --symbol) SYMBOL="${2:?--symbol requires a value}"; shift 2;;
+        --depth) DEPTH="${2:?--depth requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -56,9 +56,6 @@ done
 [[ -n "$FILE" || -n "$SYMBOL" ]] || { echo "ERROR: provide --file or --symbol" >&2; usage >&2; exit 1; }
 [[ "$DEPTH" =~ ^[0-9]+$ ]] || { echo "ERROR: --depth must be a non-negative integer" >&2; exit 1; }
 
-REPO_ABS="$(cd "$REPO" && pwd)"
-SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
-
 unavailable() {
     local t="$1" k="$2"
     jq -n --arg t "$t" --arg k "$k" '{target:$t, kind:$k, impacted:[], source:"unavailable"}' 2>/dev/null \
@@ -68,24 +65,27 @@ unavailable() {
 
 if [[ -n "$SYMBOL" ]]; then TARGET="$SYMBOL"; KIND="symbol"; else TARGET="$FILE"; KIND="file"; fi
 
-find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable "$TARGET" "$KIND"
-command -v jq >/dev/null 2>&1 || unavailable "$TARGET" "$KIND"
-
-PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || unavailable "$TARGET" "$KIND"
+graph_bootstrap "$REPO" || unavailable "$TARGET" "$KIND"
 
 if [[ -n "$SYMBOL" ]]; then
     # direction:"both" is the reliable form (the "callers" value returns empty in this engine);
-    # we read the .callers array from it.
-    RES="$(memory_cli trace_path "{\"project\":\"$PROJECT\",\"function_name\":\"$SYMBOL\",\"depth\":$DEPTH,\"direction\":\"both\"}" || echo '{}')"
-    echo "${RES:-{\}}" | jq --arg t "$TARGET" '
+    # we read the .callers array from it. Payload built with jq so a quote in
+    # --symbol can never corrupt the JSON; an engine failure is unavailable,
+    # never a fabricated empty-impact success.
+    PAYLOAD="$(jq -n --arg p "$PROJECT" --arg f "$SYMBOL" --argjson d "$DEPTH" \
+        '{project:$p, function_name:$f, depth:$d, direction:"both"}')"
+    RES="$(memory_cli trace_path "$PAYLOAD" 2>/dev/null || true)"
+    echo "$RES" | jq -e . >/dev/null 2>&1 || unavailable "$TARGET" "$KIND"
+    echo "$RES" | jq --arg t "$TARGET" '
         {target:$t, kind:"symbol",
          impacted: [ (.callers // [])[] | {name:.name, file:(.qualified_name // ""), hop:(.hop // 1)} ],
          source:"memory-graph"}'
 else
     # File impact: detect_changes maps the working-tree diff to impacted symbols.
-    RES="$(memory_cli detect_changes "{\"project\":\"$PROJECT\"}" || echo '{}')"
-    echo "${RES:-{\}}" | jq --arg t "$TARGET" '
+    PAYLOAD="$(jq -n --arg p "$PROJECT" '{project:$p}')"
+    RES="$(memory_cli detect_changes "$PAYLOAD" 2>/dev/null || true)"
+    echo "$RES" | jq -e . >/dev/null 2>&1 || unavailable "$TARGET" "$KIND"
+    echo "$RES" | jq --arg t "$TARGET" '
         {target:$t, kind:"file",
          impacted: [ (.impacted_symbols // [])[]
                      | select((.file // "") | endswith($t) or (. == $t))

package/scripts/tools/graph-init.sh

@@ -52,7 +52,7 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --scope) SCOPE="$2"; shift 2;;
+        --scope) SCOPE="${2:?--scope requires a value}"; shift 2;;
         --module-only) MODULE_ONLY=1; shift;;
         --no-fetch) NO_FETCH=1; shift;;
         --json) EMIT_JSON=1; shift;;

package/scripts/tools/graph-preflight.sh

@@ -170,7 +170,7 @@ if find_memory_bin "$REPO_ABS" "$SELF_REPO"; then
   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
+  if [[ "$GIT_OK" -eq 1 && "${LIMIT:-}" =~ ^[0-9]+$ && "$TRACKED" -gt "$LIMIT" ]]; then
     warn "Tracked files ($TRACKED) > auto_index_limit ($LIMIT) — confirm the explicit index isn't truncated near $LIMIT."
   fi
 else

package/scripts/tools/graph-query.sh

@@ -59,10 +59,10 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --cypher) CYPHER="$2"; shift 2;;
-        --tool) TOOL="$2"; shift 2;;
-        --json) TOOL_JSON="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --cypher) CYPHER="${2:?--cypher requires a value}"; shift 2;;
+        --tool) TOOL="${2:?--tool requires a value}"; shift 2;;
+        --json) TOOL_JSON="${2:?--json requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -98,16 +98,9 @@ if [[ -n "$CYPHER" ]]; then
     fi
 fi
 
-REPO_ABS="$(cd "$REPO" && pwd)"
-SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
-
 unavailable() { echo '{"source":"unavailable"}'; exit 2; }
 
-find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
-command -v jq >/dev/null 2>&1 || unavailable
-
-PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || unavailable
+graph_bootstrap "$REPO" || unavailable
 
 if [[ -n "$CYPHER" ]]; then
     RES="$(gq_run "$PROJECT" "$CYPHER" || true)"

package/scripts/tools/graph-risk.sh

@@ -42,8 +42,8 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --min-complexity) MIN_COMPLEXITY="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --min-complexity) MIN_COMPLEXITY="${2:?--min-complexity requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -52,16 +52,9 @@ done
 [[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
 [[ "$MIN_COMPLEXITY" =~ ^[0-9]+$ ]] || { echo "ERROR: --min-complexity must be a non-negative integer" >&2; exit 1; }
 
-REPO_ABS="$(cd "$REPO" && pwd)"
-SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
-
 unavailable() { echo '{"risky":[],"total":0,"source":"unavailable"}'; exit 2; }
 
-find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
-command -v jq >/dev/null 2>&1 || unavailable
-
-PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || unavailable
+graph_bootstrap "$REPO" || unavailable
 
 RES="$(gq_run "$PROJECT" "$(gq_q_risk)" || true)"
 [[ -n "$RES" ]] || unavailable

package/scripts/tools/graph-search.sh

@@ -40,9 +40,9 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --query) QUERY="$2"; shift 2;;
-        --limit) LIMIT="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --query) QUERY="${2:?--query requires a value}"; shift 2;;
+        --limit) LIMIT="${2:?--limit requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -52,20 +52,13 @@ done
 [[ -n "$QUERY" ]] || { echo "ERROR: --query is required" >&2; usage >&2; exit 1; }
 [[ "$LIMIT" =~ ^[0-9]+$ ]] || { echo "ERROR: --limit must be a non-negative integer" >&2; exit 1; }
 
-REPO_ABS="$(cd "$REPO" && pwd)"
-SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
-
 unavailable() {
     jq -n --arg q "$QUERY" '{query:$q, results:[], source:"unavailable"}' 2>/dev/null \
         || echo '{"results":[],"source":"unavailable"}'
     exit 2
 }
 
-find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
-command -v jq >/dev/null 2>&1 || unavailable
-
-PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || unavailable
+graph_bootstrap "$REPO" || unavailable
 
 ARGS="$(jq -n --arg p "$PROJECT" --arg q "$QUERY" --argjson n "$LIMIT" \
     '{project:$p, query:$q, limit:$n}')"

package/scripts/tools/graph-snapshot.sh

@@ -52,8 +52,8 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --out) OUT_DIR="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --out) OUT_DIR="${2:?--out requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -99,6 +99,11 @@ echo "$CHANGES_JSON" | jq -e . >/dev/null 2>&1 || CHANGES_JSON='{}'
 CHANGED_FILES="$(echo "$CHANGES_JSON" | jq -r '.changed_count // (.changed_files | length?) // 0' 2>/dev/null || echo 0)"
 IMPACTED="$(echo "$CHANGES_JSON" | jq -r '(.impacted_symbols | length?) // 0' 2>/dev/null || echo 0)"
 
+# YAML double-quoted scalars: escape backslashes then quotes so an unusual
+# project name or engine version string can never corrupt the marker.
+PROJECT_Y="${PROJECT//\\/\\\\}"; PROJECT_Y="${PROJECT_Y//\"/\\\"}"
+VER_Y="${VER//\\/\\\\}"; VER_Y="${VER_Y//\"/\\\"}"
+
 cat > "$OUT/schema.yaml" <<EOF
 # Draft graph gate marker — written by scripts/tools/graph-snapshot.sh
 # Draft is engine-only: this file carries NO graph data. Its presence signals that
@@ -106,8 +111,8 @@ cat > "$OUT/schema.yaml" <<EOF
 # live via the graph-*.sh wrappers (or \`codebase-memory-mcp cli <tool>\`).
 # Counts below are point-of-index provenance; the live engine is authoritative.
 engine: codebase-memory-mcp
-engine_version: "$VER"
-project: "$PROJECT"
+engine_version: "$VER_Y"
+project: "$PROJECT_Y"
 generated_at: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 indexed_nodes: $NODES
 indexed_edges: $EDGES

package/scripts/tools/graph-snippet.sh

@@ -44,8 +44,8 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --qualified|--symbol) QNAME="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --qualified|--symbol) QNAME="${2:?--qualified|--symbol requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -54,20 +54,13 @@ done
 [[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
 [[ -n "$QNAME" ]] || { echo "ERROR: --qualified is required" >&2; usage >&2; exit 1; }
 
-REPO_ABS="$(cd "$REPO" && pwd)"
-SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
-
 unavailable() {
     jq -n --arg q "$QNAME" '{qualified_name:$q, status:"unavailable", source:"unavailable"}' 2>/dev/null \
         || echo '{"status":"unavailable","source":"unavailable"}'
     exit 2
 }
 
-find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
-command -v jq >/dev/null 2>&1 || unavailable
-
-PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || unavailable
+graph_bootstrap "$REPO" || unavailable
 
 ARGS="$(jq -n --arg p "$PROJECT" --arg q "$QNAME" '{project:$p, qualified_name:$q}')"
 RES="$(memory_cli get_code_snippet "$ARGS" 2>/dev/null || true)"

package/scripts/tools/graph-tests.sh

@@ -48,8 +48,8 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --symbol) SYMBOL="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --symbol) SYMBOL="${2:?--symbol requires a value}"; shift 2;;
         --untested) UNTESTED=1; shift;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
@@ -59,9 +59,6 @@ done
 [[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
 [[ -n "$SYMBOL" || "$UNTESTED" -eq 1 ]] || { echo "ERROR: provide --symbol or --untested" >&2; usage >&2; exit 1; }
 
-REPO_ABS="$(cd "$REPO" && pwd)"
-SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
-
 unavailable() {
     if [[ "$UNTESTED" -eq 1 ]]; then
         echo '{"untested":[],"total":0,"source":"unavailable"}'
@@ -72,11 +69,7 @@ unavailable() {
     exit 2
 }
 
-find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
-command -v jq >/dev/null 2>&1 || unavailable
-
-PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || unavailable
+graph_bootstrap "$REPO" || unavailable
 
 if [[ "$UNTESTED" -eq 1 ]]; then
     EXP="$(gq_run "$PROJECT" "$(gq_q_exported)" || true)"

package/scripts/tools/graph-traces.sh

@@ -49,8 +49,8 @@ EOF
 while [[ $# -gt 0 ]]; do
     case "$1" in
         ingest) ACTION="ingest"; shift;;
-        --repo) REPO="$2"; shift 2;;
-        --file) FILE="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --file) FILE="${2:?--file requires a value}"; shift 2;;
         --experimental) EXPERIMENTAL=1; shift;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown argument: $1" >&2; usage >&2; exit 1;;
@@ -63,19 +63,12 @@ done
 [[ -n "$FILE" ]] || { echo "ERROR: --file is required" >&2; usage >&2; exit 1; }
 [[ -f "$FILE" ]] || { echo "ERROR: --file '$FILE' does not exist" >&2; exit 1; }
 
-REPO_ABS="$(cd "$REPO" && pwd)"
-SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
-
 unavailable() { echo '{"source":"unavailable"}'; exit 2; }
 
-find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
-command -v jq >/dev/null 2>&1 || unavailable
+graph_bootstrap "$REPO" || unavailable
 
 jq -e . "$FILE" >/dev/null 2>&1 || { echo "ERROR: --file is not valid JSON" >&2; exit 1; }
 
-PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || unavailable
-
 ARGS="$(jq -n --arg p "$PROJECT" --slurpfile t "$FILE" '{project:$p, traces:($t[0])}')"
 RES="$(memory_cli ingest_traces "$ARGS" 2>/dev/null || true)"
 [[ -n "$RES" ]] || unavailable

package/scripts/tools/hotspot-rank.sh

@@ -47,8 +47,8 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --top) TOP="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --top) TOP="${2:?--top requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -61,16 +61,9 @@ if [[ ! -d "$REPO" ]]; then
     exit 1
 fi
 
-REPO_ABS="$(cd "$REPO" && pwd)"
-SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
-
 unavailable() { echo '{"hotspots":[],"source":"unavailable"}'; exit 2; }
 
-find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
-command -v jq >/dev/null 2>&1 || unavailable
-
-PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || unavailable
+graph_bootstrap "$REPO" || unavailable
 
 ARCH_JSON="$(memory_cli get_architecture "{\"project\":\"$PROJECT\",\"aspects\":[\"hotspots\"]}" || true)"
 [[ -n "$ARCH_JSON" ]] || unavailable
@@ -87,7 +80,7 @@ printf '%s' "$ARCH_JSON" > "$TMP_ARCH"
 printf '%s' "$PROPS_JSON" > "$TMP_PROPS"
 
 jq -n --slurpfile arch "$TMP_ARCH" --slurpfile props "$TMP_PROPS" --argjson top "$TOP" '
-    (($props[0].rows) // []) as $prows
+    ((($props[0].rows) // []) | map(select(.[0] != null))) as $prows
     | (reduce $prows[] as $r ({};
           .[$r[0]] = {c:((($r[1]) // "0") | tonumber? // 0),
                       cog:((($r[2]) // "0") | tonumber? // 0),

package/scripts/tools/mermaid-from-graph.sh

@@ -45,8 +45,8 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --diagram) DIAGRAM="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --diagram) DIAGRAM="${2:?--diagram requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -57,9 +57,6 @@ if [[ ! -d "$REPO" ]]; then
     exit 1
 fi
 
-REPO_ABS="$(cd "$REPO" && pwd)"
-SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
-
 stub() {
     cat <<'EOF'
 ```mermaid
@@ -71,11 +68,7 @@ EOF
     exit 2
 }
 
-find_memory_bin "$REPO_ABS" "$SELF_REPO" || stub
-command -v jq >/dev/null 2>&1 || stub
-
-PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || stub
+graph_bootstrap "$REPO" || stub
 
 # module-deps: real IMPORTS edges (the auto-derived dependency graph). Self-imports
 # (src == dst) are dropped so the diagram is a true cross-file graph. Capped at 40

package/scripts/tools/migrate-track-frontmatter.sh

@@ -223,7 +223,9 @@ EOF
                 printf 'migrate: would strip ephemeral frontmatter from %s\n' "$path"
             else
                 (( BACKUP )) && cp "$path" "$path.bak"
-                local _tmp; _tmp="$(mktemp "${path}.XXXXXX")"; printf '%s' "$after" > "$_tmp" && mv -f "$_tmp" "$path"
+                # %s\n restores the EOF newline stripped by command substitution
+                # (same pattern as fix-whitespace.sh).
+                local _tmp; _tmp="$(mktemp "${path}.XXXXXX")"; printf '%s\n' "$after" > "$_tmp" && mv -f "$_tmp" "$path"
                 printf 'migrate: stripped ephemeral frontmatter from %s\n' "$path"
             fi
         fi

package/scripts/tools/okf-coverage-check.sh

@@ -57,12 +57,12 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --plan) PLAN="$2"; shift 2;;
-        --bundle) BUNDLE="$2"; shift 2;;
-        --min-stub-lines) MIN_STUB_LINES="$2"; shift 2;;
+        --plan) PLAN="${2:?--plan requires a value}"; shift 2;;
+        --bundle) BUNDLE="${2:?--bundle requires a value}"; shift 2;;
+        --min-stub-lines) MIN_STUB_LINES="${2:?--min-stub-lines requires a value}"; shift 2;;
         --no-coverage-page) WRITE_PAGE=0; shift;;
         --json) JSON=1; shift;;
-        --report) REPORT="$2"; shift 2;;
+        --report) REPORT="${2:?--report requires a value}"; 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;;
@@ -122,6 +122,17 @@ write_coverage_page() {
     mkdir -p "$BUNDLE/systems"
     local tmp; tmp="$(mktemp)"
     {
+        # OKF §9.1/§9.2: every non-reserved .md needs parseable frontmatter with a
+        # non-empty `type`. coverage.md is tool-generated and not a code concept, so
+        # it uses a descriptive (non-frozen) type; okf-validate.sh exempts it from the
+        # frozen-vocab check via is_meta_page (basename + the marker below).
+        echo "---"
+        echo "type: Report"
+        echo "title: Component Coverage"
+        echo "description: Coverage of required components by wiki pages — which are documented, stubbed, or missing."
+        echo "resource: ."
+        echo "---"
+        echo ""
         echo "<!-- okf:coverage-generated -->"
         echo "# Component Coverage"
         echo ""
@@ -130,14 +141,21 @@ write_coverage_page() {
         echo ""
         echo "| Component | Wiki page | Status | Fan-in |"
         echo "|-----------|-----------|--------|--------|"
-        local cid status fanin
+        local cid status fanin link
         while IFS=$'\t' read -r cid required reason ftype fanin; do
             [[ -z "$cid" ]] && continue
             if [[ "$required" == "true" ]]; then
                 if [[ -f "$BUNDLE/$cid" ]]; then
                     bl="$(body_lines "$BUNDLE/$cid")"
+                    # coverage.md lives in systems/; link relative to it. Concepts in
+                    # other sections (entrypoints/, reference/, …) need a ../ prefix,
+                    # otherwise the link dangles and fails structure validation.
+                    case "$cid" in
+                        systems/*) link="${cid#systems/}";;
+                        *)         link="../$cid";;
+                    esac
                     if [[ "$bl" -ge "$MIN_STUB_LINES" ]]; then
-                        echo "| \`${cid%.md}\` | [page](${cid#systems/}) | Full | ${fanin} |"
+                        echo "| \`${cid%.md}\` | [page](${link}) | Full | ${fanin} |"
                     else
                         echo "| \`${cid%.md}\` | ${cid} | **STUB (${bl} lines)** | ${fanin} |"
                     fi