@drafthq/draft 3.5.3 → 3.7.1

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

@@ -73,13 +73,13 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --scope) SCOPE="$2"; shift 2;;
-        --manifest) MANIFEST="$2"; shift 2;;
-        --min-fan-in) MIN_FAN_IN="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --scope) SCOPE="${2:?--scope requires a value}"; shift 2;;
+        --manifest) MANIFEST="${2:?--manifest requires a value}"; shift 2;;
+        --min-fan-in) MIN_FAN_IN="${2:?--min-fan-in requires a value}"; shift 2;;
         --defer-below-floor) DEFER_BELOW_FLOOR=1; shift;;
         --allow-defer) ALLOW_DEFER+=("$2"); shift 2;;
-        --out) OUT="$2"; shift 2;;
+        --out) OUT="${2:?--out requires a value}"; shift 2;;
         --json) JSON=1; shift;;
         --help|-h) usage; exit 0;;
         -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
@@ -111,13 +111,38 @@ is_deferred_name() {
 E_ID=(); E_TYPE=(); E_RES=(); E_FANIN=(); E_REQ=(); E_REASON=()
 SOURCE="heuristic"
 DEGRADED="false"
+DISCOVERY_META=()   # e.g. cargo, npm, go, graph, heuristic
+
+# Graph package names that are almost always tokenizer/type noise, not modules.
+is_noise_package_name() {
+    local n="$1"
+    case "$n" in
+        str|list|dict|int|bool|float|string|type|mod|Cargo|cargo|profile|int64|uint|byte|char|void|null|None|true|false|i32|i64|u32|u64|f32|f64|Option|Result|Error|Self|self)
+            return 0;;
+    esac
+    return 1
+}
+
+# True if concept_id already recorded.
+has_concept_id() {
+    local want="$1" id
+    for id in "${E_ID[@]:-}"; do
+        [[ "$id" == "$want" ]] && return 0
+    done
+    return 1
+}
 
 add_concept() {
     # name section type resource fan_in required reason
     local name="$1" section="$2" type="$3" resource="$4" fan_in="$5" required="$6" reason="$7"
     local stem; stem="$(slug "$name")"
     [[ -n "$stem" ]] || stem="component"
-    E_ID+=("$section/$stem.md")
+    local cid="$section/$stem.md"
+    # Dedupe by concept_id (cargo + graph may both see the same crate).
+    if has_concept_id "$cid"; then
+        return 0
+    fi
+    E_ID+=("$cid")
     E_TYPE+=("$type")
     E_RES+=("$resource")
     E_FANIN+=("$fan_in")
@@ -141,29 +166,195 @@ plan_from_manifest() {
     SOURCE="manifest"
 }
 
-# --- 2. Graph path ---
+# --- 2a. Language-aware workspace inventories (Cargo / npm / Go) ---
+# These produce crate/package-level concepts that graph .packages often collapse
+# or mis-label (especially Rust monorepos). Prefer path-grounded resources.
+
+plan_from_cargo_workspace() {
+    local cargo="$REPO/Cargo.toml"
+    [[ -f "$cargo" ]] || return 1
+    # Only treat as workspace if [workspace] present with members.
+    grep -qE '^\[workspace\]' "$cargo" || return 1
+    grep -qE 'members[[:space:]]*=' "$cargo" || return 1
+
+    local members=()
+    # Extract quoted paths inside the members = [ ... ] array (possibly multi-line).
+    local in_members=0 line m
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        if [[ "$line" =~ members[[:space:]]*=[[:space:]]*\[ ]]; then
+            in_members=1
+        fi
+        if [[ $in_members -eq 1 ]]; then
+            while [[ "$line" =~ \"([^\"]+)\" ]]; do
+                m="${BASH_REMATCH[1]}"
+                members+=("$m")
+                line="${line#*\"$m\"}"
+            done
+            [[ "$line" == *"]"* ]] && in_members=0
+        fi
+    done < "$cargo"
+
+    [[ ${#members[@]} -gt 0 ]] || return 1
+
+    local path name ct required reason type
+    local added=0
+    for path in "${members[@]}"; do
+        [[ -z "$path" ]] && continue
+        # Skip globs we can't expand cheaply without bash nullglob walk
+        if [[ "$path" == *"*"* ]]; then
+            local base="${path%%/\*}"
+            [[ -d "$REPO/$base" ]] || continue
+            while IFS= read -r ct; do
+                name="$(basename "$(dirname "$ct")")"
+                [[ -z "$name" ]] && continue
+                if is_deferred_name "$name"; then
+                    required=false; reason="allow-defer match"
+                else
+                    required=true; reason=""
+                fi
+                type=Module
+                # Entrypoint packaging root if only main.rs and no lib.rs (heuristic)
+                if [[ -f "$(dirname "$ct")/src/main.rs" && ! -f "$(dirname "$ct")/src/lib.rs" ]]; then
+                    type=Module
+                fi
+                add_concept "$name" systems "$type" "$(dirname "$ct" | sed "s|^$REPO/||")" 0 "$required" "$reason"
+                added=$((added+1))
+            done < <(find "$REPO/$base" -mindepth 1 -maxdepth 3 -type f -name 'Cargo.toml' 2>/dev/null | sort)
+            continue
+        fi
+        [[ -f "$REPO/$path/Cargo.toml" || -f "$REPO/$path" ]] || continue
+        local res="$path"
+        [[ -f "$REPO/$path" && "$path" == */Cargo.toml ]] && res="$(dirname "$path")"
+        name="$(basename "$res")"
+        if is_deferred_name "$name"; then
+            required=false; reason="allow-defer match"
+        else
+            required=true; reason=""
+        fi
+        add_concept "$name" systems Module "$res" 0 "$required" "$reason"
+        added=$((added+1))
+    done
+    [[ $added -gt 0 ]] || return 1
+    DISCOVERY_META+=("cargo")
+    return 0
+}
+
+plan_from_npm_workspaces() {
+    local pkg="$REPO/package.json"
+    [[ -f "$pkg" ]] || return 1
+    command -v jq >/dev/null 2>&1 || return 1
+    # workspaces may be array or { packages: [] }
+    local names
+    names="$(jq -r '
+        if .workspaces|type=="array" then .workspaces[]
+        elif .workspaces.packages|type=="array" then .workspaces.packages[]
+        else empty end
+    ' "$pkg" 2>/dev/null || true)"
+    [[ -n "$names" ]] || return 1
+    local path name required reason added=0
+    while IFS= read -r path; do
+        [[ -z "$path" || "$path" == *"*"* ]] && continue
+        name="$(basename "$path")"
+        if is_deferred_name "$name"; then
+            required=false; reason="allow-defer match"
+        else
+            required=true; reason=""
+        fi
+        add_concept "$name" systems Module "$path" 0 "$required" "$reason"
+        added=$((added+1))
+    done <<< "$names"
+    [[ $added -gt 0 ]] || return 1
+    DISCOVERY_META+=("npm")
+    return 0
+}
+
+plan_from_go_modules() {
+    # go.work use directives, else single go.mod at root, else first-level */go.mod
+    local added=0 name required reason path
+    if [[ -f "$REPO/go.work" ]]; then
+        while IFS= read -r path; do
+            path="$(printf '%s' "$path" | sed -E 's/^[[:space:]]*//')"
+            [[ -z "$path" || "$path" == //* ]] && continue
+            [[ -f "$REPO/$path/go.mod" ]] || continue
+            name="$(basename "$path")"
+            if is_deferred_name "$name"; then
+                required=false; reason="allow-defer match"
+            else
+                required=true; reason=""
+            fi
+            add_concept "$name" systems Module "$path" 0 "$required" "$reason"
+            added=$((added+1))
+        done < <(awk '/^use[[:space:]]*\(/,/^\)/ {if ($1!="use" && $1!="(" && $1!=")") print $1}
+                      /^use[[:space:]]+\./ {print $2}' "$REPO/go.work" | tr -d '"')
+    fi
+    if [[ $added -eq 0 && -f "$REPO/go.mod" ]]; then
+        name="$(basename "$REPO")"
+        add_concept "$name" systems Module "." 0 true ""
+        added=1
+    fi
+    if [[ $added -eq 0 ]]; then
+        while IFS= read -r path; do
+            name="$(basename "$(dirname "$path")")"
+            add_concept "$name" systems Module "$(dirname "$path" | sed "s|^$REPO/||")" 0 true ""
+            added=$((added+1))
+        done < <(find "$REPO" -mindepth 2 -maxdepth 3 -type f -name 'go.mod' 2>/dev/null | sort | head -50)
+    fi
+    [[ $added -gt 0 ]] || return 1
+    DISCOVERY_META+=("go")
+    return 0
+}
+
+# --- 2b. Graph path ---
 plan_from_graph() {
     local arch; arch="$(scripts_graph_arch)" || return 1
     [[ -n "$arch" ]] || return 1
     echo "$arch" | jq -e '.packages != null' >/dev/null 2>&1 || return 1
 
-    SOURCE="graph"
+    local have_lang_inventory=0
+    [[ ${#DISCOVERY_META[@]} -gt 0 ]] && have_lang_inventory=1
+
     local name fan_in type required reason
     # Packages → systems/<pkg>.md
     while IFS=$'\t' read -r name fan_in; do
         [[ -z "$name" ]] && continue
+        # Drop tokenizer noise when we already have a real inventory (cargo/npm/go).
+        if [[ $have_lang_inventory -eq 1 ]] && is_noise_package_name "$name"; then
+            continue
+        fi
+        # Even without inventory, skip pure noise names that do not map to a dir.
+        if is_noise_package_name "$name"; then
+            local mapped=0
+            for d in "$REPO/$name" "$REPO/crates/$name" "$REPO/src/$name" "$REPO/third_party/$name"; do
+                [[ -d "$d" ]] && mapped=1 && break
+            done
+            [[ $mapped -eq 0 ]] && continue
+        fi
         if is_deferred_name "$name"; then
             required=false; reason="allow-defer match"; type=Module
         elif (( fan_in >= MIN_FAN_IN )); then
             required=true; reason=""; type=Subsystem
         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
+        # When language inventory exists, graph packages that are coarse parents
+        # (e.g. codegen/) become Subsystems only if a matching directory exists.
+        if [[ $have_lang_inventory -eq 1 ]]; then
+            if [[ -d "$REPO/$name" || -d "$REPO/crates/$name" || -d "$REPO/third_party/$name" || -d "$REPO/prod/$name" ]]; then
+                type=Subsystem
+                # Prefer real path as resource when known
+                for d in "$name" "crates/$name" "third_party/$name" "prod/$name"; do
+                    if [[ -d "$REPO/$d" ]]; then
+                        add_concept "$name" systems "$type" "$d" "$fan_in" "$required" "$reason"
+                        continue 2
+                    fi
+                done
+            else
+                # Unmapped graph label with inventory present → skip (not a crate).
+                continue
+            fi
+        fi
         add_concept "$name" systems "$type" "$name" "$fan_in" "$required" "$reason"
     done < <(echo "$arch" | jq -r '.packages[]? | [.name, (.fan_in // 0)] | @tsv')
 
@@ -178,6 +369,8 @@ plan_from_graph() {
     done < <(echo "$arch" | jq -r '
         (.entry_points // [])[]? | if type=="object" then (.name // .path // empty) else . end' \
         | sort -u)
+    DISCOVERY_META+=("graph")
+    return 0
 }
 
 # graph-arch.sh wrapper that tolerates the "unavailable" sentinel.
@@ -218,13 +411,27 @@ plan_from_heuristic() {
 }
 
 # --- Drive discovery in priority order ---
+# 1. --manifest (authoritative, exclusive)
+# 2. Language inventories (Cargo / npm / Go) — can combine with graph parents
+# 3. Graph packages (filtered when inventory present)
+# 4. Heuristic top-level dirs
 if [[ -n "$MANIFEST" ]]; then
     [[ -f "$MANIFEST" ]] || { echo "ERROR: --manifest not found: $MANIFEST" >&2; exit 1; }
     plan_from_manifest
-elif plan_from_graph; then
-    :
+    DISCOVERY_META+=("manifest")
 else
-    plan_from_heuristic
+    # Language inventories first so cargo crate names win concept_ids.
+    plan_from_cargo_workspace || true
+    plan_from_npm_workspaces || true
+    plan_from_go_modules || true
+    plan_from_graph || true
+    # Last resort only: any of cargo/npm/go/graph succeeding leaves E_ID non-empty
+    # and skips this. Re-running the heuristic a second time can never add what
+    # the first pass didn't find, so there is one call site, not two.
+    if [[ ${#E_ID[@]} -eq 0 ]]; then
+        plan_from_heuristic
+        DISCOVERY_META+=("heuristic")
+    fi
 fi
 
 if [[ ${#E_ID[@]} -eq 0 ]]; then
@@ -232,6 +439,19 @@ if [[ ${#E_ID[@]} -eq 0 ]]; then
     exit 2
 fi
 
+# Compose SOURCE label from discovery meta
+if [[ ${#DISCOVERY_META[@]} -gt 0 ]]; then
+    # de-dupe meta labels
+    SOURCE="$(printf '%s\n' "${DISCOVERY_META[@]}" | awk '!s[$0]++' | paste -sd+ -)"
+    [[ -z "$SOURCE" ]] && SOURCE="heuristic"
+    # degraded only when pure heuristic with no language/graph
+    if [[ "$SOURCE" == "heuristic" ]]; then
+        DEGRADED="true"
+    else
+        DEGRADED="false"
+    fi
+fi
+
 # Required-first, then deferred; stable within group (topological-ish: high fan-in
 # subsystems first so forward cross-links resolve during generation).
 emit_plan() {
@@ -257,6 +477,14 @@ emit_plan() {
         printf '  "source": "%s",\n' "$SOURCE"
         printf '  "degraded": %s,\n' "$DEGRADED"
         printf '  "min_fan_in": %d,\n' "$MIN_FAN_IN"
+        printf '  "discovery": ['
+        local di first_d=1
+        for di in "${DISCOVERY_META[@]:-}"; do
+            [[ -z "$di" ]] && continue
+            [[ $first_d -eq 1 ]] && first_d=0 || printf ','
+            printf '"%s"' "$(json_escape "$di")"
+        done
+        printf '],\n'
         # generated_order
         printf '  "generated_order": ['
         local first=1

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

@@ -1,7 +1,7 @@
 #!/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,
+# The wiki/ bundle is the source of truth. This produces the 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,
@@ -24,6 +24,11 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=scripts/tools/_lib.sh
 source "$SCRIPT_DIR/_lib.sh"
 
+command -v python3 >/dev/null 2>&1 || {
+    echo "ERROR: python3 is required by ${0##*/} (link rewriting in rendered views)" >&2
+    exit 2
+}
+
 BUNDLE=""
 ARCH_OUT=""
 WEB_OUT=""
@@ -56,18 +61,18 @@ Flags:
                            this tool has no clock dependency).
   --help                   Show this help.
 
-Requires jq (already a Draft prereq) for --web. Exit 0 ok, 1 error, 2 bundle not found.
+Requires jq (for --web) and python3 (link rewriting). Exit 0 ok, 1 error, 2 bundle not found.
 EOF
 }
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --arch-out) ARCH_OUT="$2"; shift 2;;
+        --arch-out) ARCH_OUT="${2:?--arch-out requires a value}"; 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;;
+        --web) WEB_OUT="${2:?--web requires a value}"; shift 2;;
+        --coverage-report) COVERAGE_REPORT="${2:?--coverage-report requires a value}"; shift 2;;
+        --validated-at) VALIDATED_AT="${2:?--validated-at requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
         *)
@@ -100,6 +105,37 @@ ordered_pages() {
     done
 }
 
+# Rewrite markdown links so concatenated architecture.md (at draft/) resolves them.
+# stdin body; $1 = bundle-relative path e.g. systems/foo.md
+rewrite_body_links() {
+    local rel="${1:-}"
+    local sec="${rel%%/*}"
+    python3 -c '
+import sys, re
+sec = sys.argv[1]
+text = sys.stdin.read()
+sections = ("systems", "features", "overview", "entrypoints", "reference")
+def repl(m):
+    label, href = m.group(1), m.group(2).strip()
+    if href.startswith(("http://", "https://", "mailto:", "#", "wiki/")):
+        return m.group(0)
+    if "::" in href and not href.startswith("../"):
+        return "`" + label + "`"
+    path, _, frag = href.partition("#")
+    frag_s = "#" + frag if frag else ""
+    if path.startswith("../"):
+        rest = path[3:]
+        if rest.split("/")[0] in sections:
+            return "[%s](wiki/%s%s)" % (label, rest, frag_s)
+    if any(path.startswith(s + "/") for s in sections):
+        return "[%s](wiki/%s%s)" % (label, path, frag_s)
+    if path.endswith(".md") and "/" not in path and sec in sections:
+        return "[%s](wiki/%s/%s%s)" % (label, sec, path, frag_s)
+    return m.group(0)
+sys.stdout.write(re.sub(r"\[([^\]]*)\]\(([^)]+)\)", repl, text))
+' "$sec"
+}
+
 # Strip YAML frontmatter from a page (leading --- ... --- block on line 1).
 strip_frontmatter() {
     awk '
@@ -172,8 +208,7 @@ render_architecture() {
             fi
             title="$(page_title "$BUNDLE/$rel")"
             [[ -n "$title" ]] || title="$rel"
-            local anchor; anchor="$(printf '%s' "$title" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-')"
-            anchor="${anchor#-}"; anchor="${anchor%-}"
+            local anchor; anchor="$(gfm_slug "$title")"
             echo "  - [${title}](#${anchor})"
         done < <(ordered_pages)
         echo ""
@@ -183,10 +218,17 @@ render_architecture() {
             echo ""
             echo "---"
             echo ""
-            strip_frontmatter "$BUNDLE/$rel"
+            strip_frontmatter "$BUNDLE/$rel" | rewrite_body_links "$rel"
         done < <(ordered_pages)
     } >"$tmp"
+    apply_dest_mode "$tmp" "$out"   # mktemp is 0600; mv would strip the dest's mode
     mv "$tmp" "$out"
+    if [[ -x "$SCRIPT_DIR/okf-fix-links.sh" ]]; then
+        draft_dir="$(cd "$(dirname "$out")" && pwd)"
+        if [[ -d "$draft_dir/wiki" || "$(basename "$BUNDLE")" == "wiki" ]]; then
+            "$SCRIPT_DIR/okf-fix-links.sh" --file "$out" --wiki "$BUNDLE" --fix >/dev/null 2>&1 || true
+        fi
+    fi
     echo "rendered architecture view → $out ($(ordered_pages | grep -c . ) pages)"
 }
 
@@ -206,12 +248,7 @@ build_concept_map() {
         [[ -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")"
+        desc="$(page_desc "$page")"
         echo "| [${title}](${rel}) | ${type} | ${desc} |"
     done < <(find "$BUNDLE" -type f -name '*.md' -print0 | sort -z)
 }
@@ -276,14 +313,18 @@ inject_concept_map() {
         /<!-- CONCEPT-MAP:END -->/ { skip=0 }
         !skip { print }
     ' "$target" >"$tmp"
+    apply_dest_mode "$tmp" "$target"   # mktemp is 0600; mv would strip the dest's mode
     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).
+# the browser. No server, no internet, no CDN. jq encodes page content safely,
+# and the whole emitted data block is passed through a `</` → `<\/` filter: JSON
+# escaping does NOT stop a literal "</script>" from closing the <script> element,
+# and page titles/types/paths come from repo-derived frontmatter, so every field
+# has to be neutralized, not just the markdown body.
 render_web() {
     local out="$1"
     command -v jq >/dev/null 2>&1 || { echo "ERROR: --web requires jq" >&2; return 1; }
@@ -351,14 +392,14 @@ HTML_HEAD
                 "$(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')"
+                "$(strip_frontmatter "$page" | jq -Rs .)"
         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"
+    } | sed 's#</#<\\/#g' >>"$tmp"
 
     cat >>"$tmp" <<'HTML_TAIL'
 function esc(s){return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');}
@@ -387,7 +428,7 @@ function render(md, base){
   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)+'';
+    return 'BLOCK'+(blocks.length-1)+'';
   });
   var lines=src.split('\n'), out='', i=0, list='', tbl=[];
   function closeList(){ if(list){ out+='</'+list+'>'; list=''; } }
@@ -410,7 +451,7 @@ function render(md, base){
     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+)$/);
+    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>';
@@ -450,6 +491,7 @@ show(decodeURIComponent(location.hash.slice(1)) || ORDER[0]);
 HTML_TAIL
 
     mkdir -p "$(dirname "$out")"
+    apply_dest_mode "$tmp" "$out"   # mktemp is 0600; mv would strip the dest's mode
     mv "$tmp" "$out"
     echo "rendered offline HTML viewer → $out ($(find "$BUNDLE" -type f -name '*.md' | grep -c .) pages)"
 }

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

@@ -6,9 +6,10 @@
 # code, so a bundle that is structurally broken, full of stubs, or missing
 # required components is never promoted.
 #
-#   Layer 1  okf-validate.sh          structure (frontmatter, types, links, index)
 #   Layer 2  okf-validate-quality.sh  per-type anti-stub / depth / mermaid lint
 #   Layer 3  okf-coverage-check.sh    every required plan entry has a real page
+#                                      (may rewrite systems/coverage.md)
+#   Layer 1  okf-validate.sh          structure LAST so coverage rewrite is checked
 #
 # Usage:
 #   okf-validate-all.sh <BUNDLE_DIR> [--plan FILE] [--path-index FILE]
@@ -53,10 +54,10 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --plan) PLAN="$2"; shift 2;;
-        --path-index) PATH_INDEX="$2"; shift 2;;
+        --plan) PLAN="${2:?--plan requires a value}"; shift 2;;
+        --path-index) PATH_INDEX="${2:?--path-index requires a value}"; shift 2;;
         --strict) STRICT=1; shift;;
-        --report) REPORT="$2"; shift 2;;
+        --report) REPORT="${2:?--report requires a value}"; shift 2;;
         --json) JSON=1; shift;;
         --help|-h) usage; exit 0;;
         -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
@@ -79,16 +80,23 @@ run_layer() {
     return $rc
 }
 
-# Layer 1: structure.
+# Order matters:
+#   1) quality  — page content (does not rewrite files)
+#   2) coverage — may REGENERATE systems/coverage.md (tool-owned)
+#   3) structure — link/frontmatter check LAST so coverage rewrite cannot leave
+#                  dangling links that structure already approved.
+#
+# Historical bug: structure-before-coverage let init promote a bundle whose
+# coverage.md still had broken relative links (entrypoints/ from systems/).
+
 v1_args=("$BUNDLE")
 [[ -n "$PATH_INDEX" ]] && v1_args+=(--path-index "$PATH_INDEX")
-if run_layer structure "$SCRIPT_DIR/okf-validate.sh" "${v1_args[@]}"; then L1=pass; else L1=fail; OVERALL=1; fi
-
-# Layer 2: quality.
 q_args=("$BUNDLE"); [[ $STRICT -eq 1 ]] && q_args+=(--strict)
+
+# Layer 2: quality (run first for fast fail on stubs).
 if run_layer quality "$SCRIPT_DIR/okf-validate-quality.sh" "${q_args[@]}"; then L2=pass; else L2=fail; OVERALL=1; fi
 
-# Layer 3: coverage (only if a plan is supplied).
+# Layer 3: coverage (writes coverage.md when not --no-coverage-page).
 if [[ -n "$PLAN" ]]; then
     if run_layer coverage "$SCRIPT_DIR/okf-coverage-check.sh" --plan "$PLAN" --bundle "$BUNDLE"; then
         L3=pass
@@ -97,6 +105,9 @@ if [[ -n "$PLAN" ]]; then
     fi
 fi
 
+# Layer 1: structure LAST (after coverage page is final).
+if run_layer structure "$SCRIPT_DIR/okf-validate.sh" "${v1_args[@]}"; then L1=pass; else L1=fail; OVERALL=1; fi
+
 REPORT_JSON="$(printf '{"valid":%s,"bundle":"%s","layers":{"structure":"%s","quality":"%s","coverage":"%s"}}\n' \
     "$([[ $OVERALL -eq 0 ]] && echo true || echo false)" "$(json_escape "$BUNDLE")" "$L1" "$L2" "$L3")"
 

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

@@ -73,18 +73,23 @@ body_of() {
     awk 'NR==1&&/^---$/{fm=1;next} fm&&/^---$/{fm=0;next} !fm{print}' "$1"
 }
 
+# Body text the Q-TEMPLATE scan is allowed to see: fenced code blocks and
+# shell-style ${VAR} expansions removed. Both legitimately carry {ALL_CAPS}
+# spans that are not unreplaced placeholders (a page quoting `${HOME}` or a CI
+# snippet would otherwise fail).
+template_scan_body() {
+    body_of "$1" | awk '
+        /^[[:space:]]*```/ { fence = !fence; next }
+        !fence { gsub(/\$\{[A-Za-z_][A-Za-z0-9_]*\}/, ""); print }
+    '
+}
+
 # Count body lines after the frontmatter close (Q-LEN = "lines after frontmatter").
 body_lines() { body_of "$1" | wc -l | tr -d ' '; }
 
-# x-grounded-paths array length (entries inside [ ... ]).
+# x-grounded-paths array length — inline `[a, b]` or YAML block list (via _lib.sh).
 grounded_count() {
-    local arr
-    arr="$(grep -m1 -E '^x-grounded-paths:' "$1" 2>/dev/null || true)"
-    [[ -z "$arr" ]] && { echo 0; return; }
-    arr="${arr#*[}"; arr="${arr%]*}"
-    arr="$(printf '%s' "$arr" | tr -d ' ')"
-    [[ -z "$arr" ]] && { echo 0; return; }
-    awk -F',' '{print NF}' <<< "$arr"
+    grounded_paths_count "$1"
 }
 
 has_section() { grep -qE "^##[[:space:]]+$1([[:space:]]|$)" "$2"; }
@@ -120,7 +125,7 @@ mermaid_lint() {
         echo "unicode arrow in mermaid (use --> not →)"; return 1
     fi
     # '&' node chaining (common breaker).
-    if printf '%s' "$blocks" | grep -qE '[A-Za-z0-9_]\s*&\s*[A-Za-z0-9_]'; then
+    if printf '%s' "$blocks" | grep -qE '[A-Za-z0-9_][[:space:]]*&[[:space:]]*[A-Za-z0-9_]'; then
         echo "'&' node chaining in mermaid"; return 1
     fi
     # Reserved bareword node ids.
@@ -241,7 +246,7 @@ while IFS= read -r -d '' page; do
     fi
 
     # Q-TEMPLATE: unreplaced {TOKEN} placeholders.
-    if body_of "$page" | grep -qE "$TOKEN_RE"; then
+    if template_scan_body "$page" | grep -qE "$TOKEN_RE"; then
         fail "$rel" "Q-TEMPLATE" "unreplaced template token {PLACEHOLDER}"
     fi