loki-mode 7.88.0 → 7.89.0

package/SKILL.md

@@ -3,7 +3,7 @@ name: loki-mode
 description: Autonomous spec-driven build system with a built-in trust layer. It does not call work done until it is verified (RARV-C closure loop, 8 quality gates, completion council, verified-completion evidence gate). Triggers on "Loki Mode". Takes a spec (PRD, GitHub issue, OpenAPI doc, etc.) to deployed product with minimal human intervention. Provider-agnostic. Requires --dangerously-skip-permissions flag.
 ---
 
-# Loki Mode v7.88.0
+# Loki Mode v7.89.0
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -408,4 +408,4 @@ See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.13] for the per-fix list and r
 
 ---
 
-**v7.88.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**
+**v7.89.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-7.88.0
+7.89.0

package/autonomy/crash.sh

@@ -39,10 +39,46 @@ _LOKI_CRASH_CAPTURE_PY="${_LOKI_CRASH_DIR}/lib/crash_capture.py"
 # its precedence MUST be mirrored by _is_enabled in dashboard/telemetry.py and
 # _loki_telemetry_enabled in autonomy/telemetry.sh.
 #
-# Precedence:
-#   1. Any opt-out flag present  -> OFF (hard kill, always wins)
-#   2. Else any opt-in flag present -> ON
-#   3. Else (default)            -> OFF (no egress, no local capture)
+# Precedence (MUST mirror _loki_telemetry_enabled in autonomy/telemetry.sh and
+# _is_enabled in dashboard/telemetry.py):
+#   1. Any opt-out flag present     -> OFF (hard kill, always wins)
+#   2. Else explicit opt-in present -> ON (force-on, even in CI/enterprise)
+#   3. Else enterprise/CI/air-gapped -> OFF (auto-off, safe out of the box)
+#   4. Else (individual default)    -> ON (anonymous diagnostics, disclosed once)
+
+# _loki_collection_auto_off: enterprise / CI / air-gapped / non-interactive
+# detection. Defined here too (not only telemetry.sh) because autonomy/loki sources
+# crash.sh but not telemetry.sh. Guarded so a single definition wins if both load.
+# This list MUST stay in sync with _loki_telemetry_auto_off (telemetry.sh) and
+# dashboard/telemetry.py.
+if ! declare -f _loki_collection_auto_off >/dev/null 2>&1; then
+_loki_collection_auto_off() {
+    [ "${CI:-}" = "true" ] && return 0
+    [ -n "${GITHUB_ACTIONS:-}" ] && return 0
+    [ -n "${GITLAB_CI:-}" ] && return 0
+    [ -n "${BUILDKITE:-}" ] && return 0
+    [ -n "${JENKINS_URL:-}" ] && return 0
+    [ -n "${TEAMCITY_VERSION:-}" ] && return 0
+    [ "${CONTINUOUS_INTEGRATION:-}" = "true" ] && return 0
+    [ "${LOKI_ENTERPRISE:-}" = "true" ] && return 0
+    [ "${LOKI_AIRGAP:-}" = "true" ] && return 0
+    # Non-interactive detection (council cH_r1 AC2). MUST match
+    # _loki_telemetry_auto_off (telemetry.sh) and _auto_off (dashboard/telemetry.py):
+    # trust the explicit LOKI_TTY_INTERACTIVE signal resolved once at the entry
+    # point; fall back to a live `-t` probe only when the signal is unset (isolated
+    # unit test that bypassed the entry point). A fresh `-t` probe in an
+    # FD-detached subshell would wrongly auto-off a real interactive user.
+    if [ -n "${LOKI_TTY_INTERACTIVE:-}" ]; then
+        [ "${LOKI_TTY_INTERACTIVE}" = "1" ] && return 1
+        return 0
+    fi
+    if [ ! -t 1 ] && [ ! -t 0 ]; then
+        return 0
+    fi
+    return 1
+}
+fi
+
 loki_collection_enabled() {
     local telem_lower
     telem_lower="$(printf '%s' "${LOKI_TELEMETRY:-}" | tr '[:upper:]' '[:lower:]')"
@@ -59,7 +95,7 @@ loki_collection_enabled() {
         return 1
     fi
 
-    # --- 2. Opt-in required to enable ---
+    # --- 2. Explicit opt-in forces ON (overrides the enterprise/CI auto-off) ---
     # Env: LOKI_TELEMETRY=on (case-insensitive, exact word "on").
     [ "$telem_lower" = "on" ] && return 0
     # Persistent opt-in in ~/.loki/config (written by: loki telemetry on).
@@ -67,8 +103,11 @@ loki_collection_enabled() {
         return 0
     fi
 
-    # --- 3. Default: OFF ---
-    return 1
+    # --- 3. Enterprise / CI / air-gapped: auto-off (safe out of the box) ---
+    _loki_collection_auto_off && return 1
+
+    # --- 4. Individual interactive default: ON (anonymous diagnostics) ---
+    return 0
 }
 
 # _loki_crash_python: resolve a python3 interpreter, or return 1 if absent.
@@ -156,35 +195,23 @@ loki_crash_friction() {
     return 0
 }
 
-# loki_show_disclosure_once: print the first-run disclosure exactly once.
-# Shown regardless of enabled/disabled state, before any egress. Uses the
-# DISCLOSURE_SHOWN sentinel in ~/.loki/config (do not invent a new file).
-# Safe if HOME is unwritable (best-effort).
+# loki_show_disclosure_once: intentionally a SILENT no-op.
+#
+# The verbose multi-line disclosure block was removed (it cluttered logs + the
+# run experience, and its "off by default" copy no longer matches the on-by-
+# default-for-individuals model). Disclosure now lives in two non-noisy places,
+# so on-by-default collection is still NEVER covert:
+#   1. a single line on the one-time welcome screen (cmd_welcome_terminal), shown
+#      only when diagnostics are actually on, and
+#   2. docs/PRIVACY.md (canonical), plus `loki telemetry` status/off.
+# Kept as a callable no-op so existing callers (run.sh) do not break, and still
+# records the DISCLOSURE_SHOWN sentinel for back-compat with any reader of it.
 loki_show_disclosure_once() {
     local config="${HOME}/.loki/config"
-
-    # Already shown? Never re-show.
     if [ -f "$config" ] && grep -q "^DISCLOSURE_SHOWN=true" "$config" 2>/dev/null; then
         return 0
     fi
-
-    # Disclosure copy (opt-in framing; no emojis, no em dashes).
-    {
-        echo ""
-        echo "Loki Mode anonymous diagnostics are OFF by default. Nothing is collected"
-        echo "or sent unless you opt in, so a default install sends us no telemetry"
-        echo "or diagnostics. Air-gapped and enterprise deployments are safe out of"
-        echo "the box."
-        echo "If you opt in, we send anonymous diagnostics only (os, arch, version,"
-        echo "error type, sanitized stack signatures). Never your code, prompts, paths,"
-        echo "keys, or repo names."
-        echo "See docs/PRIVACY.md. Opt in anytime with: loki telemetry on"
-        echo ""
-    } >&2
-
-    # Persist the sentinel (best-effort; never fail the caller).
     mkdir -p "${HOME}/.loki" 2>/dev/null || return 0
     echo "DISCLOSURE_SHOWN=true" >> "$config" 2>/dev/null || true
-
     return 0
 }

package/autonomy/lib/own-render.py

@@ -109,6 +109,27 @@ def _usage_section(usage_text, header):
     return "\n".join(out)
 
 
+def _strip_md_fences(text):
+    """Remove markdown code-fence lines (``` or ```lang) from a USAGE.md section
+    body. USAGE.md already wraps commands in fenced blocks; own re-wraps each
+    section in ONE fence, so leaving the inner fences in produces nested,
+    broken-rendering ``` inside ``` for the non-technical reader. We drop the
+    fence delimiter lines but keep the content + prose between them verbatim."""
+    if not text:
+        return ""
+    kept = []
+    for line in text.splitlines():
+        if line.lstrip().startswith("```"):
+            continue  # drop the fence delimiter line itself
+        kept.append(line)
+    # Re-trim blank edges left behind after removing fences.
+    while kept and not kept[0].strip():
+        kept.pop(0)
+    while kept and not kept[-1].strip():
+        kept.pop()
+    return "\n".join(kept)
+
+
 # ---------------------------------------------------------------------------
 # honesty gate (the core)
 # ---------------------------------------------------------------------------
@@ -209,6 +230,36 @@ def _run_id_when(run_id):
     return ""
 
 
+def _verdict_translation(proof):
+    """A one-sentence plain-language translation of the honesty verdict for a
+    non-technical owner. Honesty gate is sacred here:
+
+      - ready (_is_ready True)  -> a true, non-overclaiming positive line.
+      - partial ("VERIFIED ..." headline that is NOT a clean pass, e.g.
+        "VERIFIED WITH GAPS") -> "the code is there and it builds, but Loki
+        could not fully prove it works - see what is unverified below."
+      - everything else (NOT VERIFIED, missing/unknown headline) -> a plain,
+        NON-reassuring statement. NEVER softened into something comforting.
+
+    Returns '' when there is nothing safe to add (we never invent reassurance).
+    """
+    headline = str(((proof or {}).get("honesty") or {}).get("headline")
+                   or "").strip().upper()
+    if _is_ready(proof):
+        return ("In plain terms: Loki built what you asked for and checked that "
+                "it works.")
+    # Partial verification: the build produced something Loki could confirm
+    # partially, but not fully. Gated on the headline AFFIRMING verification
+    # (starts with VERIFIED) while NOT being a clean ready pass. "NOT VERIFIED"
+    # starts with "NOT" so it can never reach this branch.
+    if headline.startswith("VERIFIED"):
+        return ("In plain terms: the code is there and the build ran, but Loki "
+                "could not fully prove it works - see what is unverified below.")
+    # No affirmative verification at all. State it plainly, do not reassure.
+    return ("In plain terms: Loki could not confirm this build works. Treat it "
+            "as unfinished until the gaps below are resolved.")
+
+
 def _section_is_it_working(proof, run_id=None):
     """2. 'Is it working?' - VERBATIM honesty.headline gating.
 
@@ -226,6 +277,8 @@ def _section_is_it_working(proof, run_id=None):
         lines.append("Yes. Loki verified this build: the tests passed and the "
                      "build ran cleanly.")
         lines.append("")
+        lines.append(_verdict_translation(proof))
+        lines.append("")
         lines.append("Verdict (Loki's honest receipt): %s" % (headline or "VERIFIED"))
         lines.append("")
         lines.extend(_build_age_note(run_id))
@@ -238,6 +291,8 @@ def _section_is_it_working(proof, run_id=None):
     else:
         lines.append("Not verified. Loki did not record a verdict for this run.")
     lines.append("")
+    lines.append(_verdict_translation(proof))
+    lines.append("")
     lines.append("This means Loki is NOT telling you it is ready to ship. Here is "
                  "what was not verified:")
     lines.append("")
@@ -266,9 +321,11 @@ def _section_run_on_computer(proof, usage_text, live_url):
     if live_url:
         lines.append("It is running right now on this machine at: %s" % live_url)
         lines.append("")
-    start = _usage_section(usage_text, "Start")
-    verify = _usage_section(usage_text, "Verify")
-    install = _usage_section(usage_text, "Install")
+    # Strip USAGE.md's own ``` fences so each section is wrapped exactly once
+    # below (otherwise nested fences render broken for the non-dev reader).
+    start = _strip_md_fences(_usage_section(usage_text, "Start"))
+    verify = _strip_md_fences(_usage_section(usage_text, "Verify"))
+    install = _strip_md_fences(_usage_section(usage_text, "Install"))
     if install:
         lines.append("First, install it:")
         lines.append("")
@@ -365,8 +422,16 @@ def _section_verified(proof, run_id):
 
 
 def _section_still_to_do(proof, completion):
-    """7. 'What you still need to do or decide'."""
+    """7. 'What you still need to do or decide'.
+
+    Rendered as a numbered, ordered checklist so a non-technical owner knows
+    exactly what to handle and roughly in what order: run/try it, resolve
+    anything Loki could not verify, then open a PR (merge) and deploy. Every
+    item still maps to a real artifact value -- nothing is invented.
+    """
     lines = ["## What you still need to do or decide", ""]
+    # Action items, kept in a sensible do-this-first order:
+    #   1) review assumptions, 2) resolve unverified gaps, 3) PR/merge, 4) deploy.
     items = []
 
     # Assumptions Loki had to make where the spec was ambiguous.
@@ -416,9 +481,12 @@ def _section_still_to_do(proof, completion):
     if not str(deployment.get("deployed_url") or "").strip():
         items.append("It is not deployed yet. Use `loki deploy` when you are ready.")
 
-    for it in items:
-        lines.append("- %s" % it)
-    if not items:
+    if items:
+        lines.append("Work through these in order:")
+        lines.append("")
+        for i, it in enumerate(items, start=1):
+            lines.append("%d. %s" % (i, it))
+    else:
         lines.append("- Nothing outstanding was recorded. Read the sections above "
                      "to decide your next step.")
     return lines
@@ -461,7 +529,9 @@ def render_markdown(loki_dir):
     usage_text = _read_text(os.path.join(project_root, "USAGE.md"))
     live_url = _live_url(loki_dir)
 
-    blocks = [["# What Loki built for you", ""]]
+    blocks = [["# What Loki built for you", "",
+               "Here is what Loki built and how to take it from here, in plain "
+               "language - no code reading required."]]
     blocks.append(_section_what_you_have(proof))
     blocks.append(_section_is_it_working(proof, run_id))
     blocks.append(_section_run_on_computer(proof, usage_text, live_url))

package/autonomy/lib/proof-generator.py

@@ -550,6 +550,19 @@ def _collect_spec(loki_dir, target_dir):
     return {"source": source, "brief": brief}
 
 
+def _self_version():
+    """Read the installed Loki version from the VERSION file shipped beside this
+    generator (package layout: <root>/VERSION and <root>/autonomy/lib/<this>).
+
+    This is the most robust source: proof-generator.py always ships two dirs
+    below VERSION in every distribution channel (npm, Docker, brew), so it is
+    correct regardless of the caller's cwd or the target app dir. Returns "" when
+    the file cannot be read (never raises)."""
+    return _read_text(
+        os.path.join(_HERE, "..", "..", "VERSION")
+    ).strip()
+
+
 def _collect_meta(loki_dir, repo_root):
     orch = _read_json(
         os.path.join(loki_dir, "state", "orchestrator.json"), default={}
@@ -560,6 +573,11 @@ def _collect_meta(loki_dir, repo_root):
     version = str(orch.get("version") or "")
     if not version and repo_root:
         version = _read_text(os.path.join(repo_root, "VERSION")).strip()
+    # Final fallback: the VERSION shipped beside this generator. Robust even when
+    # repo_root resolution failed (e.g. the generator runs from outside its
+    # package tree against a user app dir that has no VERSION file).
+    if not version:
+        version = _self_version()
     return started_at, version
 
 
@@ -610,7 +628,15 @@ def _build_proof(args, loki_dir, target_dir, repo_root):
     run_id = args.run_id or os.environ.get("LOKI_SESSION_ID") or _gen_run_id()
 
     started_at, version_from_state = _collect_meta(loki_dir, repo_root)
-    loki_version = args.loki_version or version_from_state or "unknown"
+    # Treat a literal "unknown" arg as absent: the bash runtime wrapper passes
+    # --loki-version "$(get_version ... || echo unknown)", and get_version is not
+    # defined in run.sh's process, so the wrapper sends the sentinel "unknown".
+    # Letting that win would mask the version that _collect_meta resolves from
+    # orchestrator.json / repo VERSION / the VERSION shipped beside this file.
+    arg_version = (args.loki_version or "").strip()
+    if arg_version.lower() == "unknown":
+        arg_version = ""
+    loki_version = arg_version or version_from_state or "unknown"
 
     cost, model_from_eff = _collect_efficiency(loki_dir)
     provider_name = args.provider or os.environ.get("PROVIDER_NAME") or "claude"

package/autonomy/lib/wiki-generator.py

@@ -86,6 +86,180 @@ def _entry_points(root, files):
     return [c for c in candidates if c in fileset]
 
 
+def _mermaid_label(text):
+    """Return a Mermaid-safe node label string (no injection, no parse breaks).
+
+    Mermaid breaks on quotes, brackets, and a handful of metacharacters, and a
+    crafted label could otherwise smuggle node/edge syntax. We keep only a
+    conservative character set (alphanumerics, space, and a few path-safe
+    punctuation marks) and collapse everything else to a space. The result is
+    always wrapped by the caller in double quotes inside ["..."], so the empty
+    string degrades to an empty-but-valid label rather than a syntax error.
+    """
+    safe = []
+    for ch in str(text or ""):
+        if ch.isalnum() or ch in " ._/-":
+            safe.append(ch)
+        else:
+            safe.append(" ")
+    out = "".join(safe).strip()
+    # Collapse runs of whitespace so labels stay compact + deterministic.
+    out = " ".join(out.split())
+    return out or "node"
+
+
+def _classify_data_store(rel):
+    """Return a data-store label for a file that looks like a store, else None.
+
+    Heuristic + deterministic: matches well-known persistence/config surfaces
+    by path substring. Only real indexed files reach here, so any node emitted
+    is cited. Returns None when the file is not a recognizable data store.
+    """
+    low = rel.lower()
+    checks = [
+        ("schema", "Schema"),
+        ("migration", "Migrations"),
+        ("models", "Data Models"),
+        ("model.", "Data Models"),
+        ("storage", "Storage"),
+        ("database", "Database"),
+        ("/db/", "Database"),
+        ("db.", "Database"),
+        ("repository", "Repository"),
+        ("repositories", "Repository"),
+        ("dao", "Data Access"),
+        ("store.", "Store"),
+        (".sql", "SQL"),
+    ]
+    for needle, label in checks:
+        if needle in low:
+            return label
+    return None
+
+
+def _data_stores(files, limit=4):
+    """Pick recognizable data-store files from the indexed set (real files).
+
+    Deterministic: scans files in sorted order (build_index returns them
+    sorted) and returns the first `limit` matches as {file, label}.
+    """
+    stores = []
+    for rel in files:
+        label = _classify_data_store(rel)
+        if label:
+            stores.append({"file": rel, "label": label})
+        if len(stores) >= limit:
+            break
+    return stores
+
+
+def _architecture_diagram(index, modules, entries):
+    """Deterministic Mermaid flowchart: entry points -> modules -> data stores.
+
+    Every node is derived from the real codebase index (entry points, top
+    modules, data-store files) -- nothing is fabricated. Given the same index
+    the output is byte-identical (no Date, no random, fixed iteration order).
+    If the index is too sparse to draw a real graph, a minimal honest
+    single-node flowchart is returned instead of a fake one.
+    """
+    entry_nodes = list(entries[:4])
+    entry_set = set(entry_nodes)
+    # A file that is both an entry point and a top module is drawn once, as an
+    # entry point, so a node is never declared twice and no self-edge appears.
+    mod_nodes = [m["file"] for m in modules[:6] if m["file"] not in entry_set]
+    stores = _data_stores(index["files"])
+
+    # Sparse-index guard: with no entry points and no modules there is nothing
+    # real to draw. Emit a minimal honest diagram rather than inventing nodes.
+    if not entry_nodes and not mod_nodes:
+        return "flowchart TD\n    src[\"Source files\"]"
+
+    lines = ["flowchart TD"]
+    ids = {}
+    counter = 0
+
+    def node_id(key):
+        nonlocal counter
+        if key not in ids:
+            ids[key] = "n%d" % counter
+            counter += 1
+        return ids[key]
+
+    # Declare nodes in a fixed order (entries, modules, stores) so the diagram
+    # is deterministic for a given index.
+    for e in entry_nodes:
+        lines.append("    %s[\"%s\"]" % (node_id(e), _mermaid_label(e)))
+    for m in mod_nodes:
+        lines.append("    %s[\"%s\"]" % (node_id(m), _mermaid_label(m)))
+    for s in stores:
+        lines.append(
+            "    %s[(\"%s\")]" % (node_id("store:" + s["file"]), _mermaid_label(s["label"]))
+        )
+
+    # Edges: every entry point feeds every top module (a coarse but honest
+    # "entry -> module" relation), and modules feed the data stores. When there
+    # are no entry points, modules stand alone at the top.
+    sources = entry_nodes if entry_nodes else mod_nodes
+    targets = mod_nodes if entry_nodes else []
+    for src in sources:
+        for tgt in targets:
+            lines.append("    %s --> %s" % (node_id(src), node_id(tgt)))
+    if stores:
+        store_sources = mod_nodes if mod_nodes else entry_nodes
+        for src in store_sources[:3]:
+            for s in stores:
+                lines.append(
+                    "    %s --> %s" % (node_id(src), node_id("store:" + s["file"]))
+                )
+    return "\n".join(lines)
+
+
+def _data_flow_diagram(index, modules, entries):
+    """Deterministic Mermaid flowchart for the request/data path.
+
+    Models the path as: entry point -> the top modules in rank order -> data
+    store, using only real indexed files. Same index -> same diagram. Falls
+    back to a minimal honest diagram when the index is too sparse.
+    """
+    entry = entries[0] if entries else None
+    # Drop the entry file from the module chain so it is not visited twice
+    # (which would create a self-edge); the chain stays a simple acyclic path.
+    mod_chain = [m["file"] for m in modules[:4] if m["file"] != entry]
+    stores = _data_stores(index["files"], limit=1)
+
+    if not entry and not mod_chain:
+        return "flowchart LR\n    src[\"Source files\"]"
+
+    lines = ["flowchart LR"]
+    ids = {}
+    counter = 0
+
+    def node_id(key):
+        nonlocal counter
+        if key not in ids:
+            ids[key] = "f%d" % counter
+            counter += 1
+        return ids[key]
+
+    # Build an ordered chain of real nodes: entry -> modules -> store.
+    chain = []
+    if entry:
+        chain.append(("entry", entry, _mermaid_label(entry)))
+    for m in mod_chain:
+        chain.append(("mod", m, _mermaid_label(m)))
+    if stores:
+        chain.append(("store", "store:" + stores[0]["file"], _mermaid_label(stores[0]["label"])))
+
+    for kind, key, label in chain:
+        if kind == "store":
+            lines.append("    %s[(\"%s\")]" % (node_id(key), label))
+        else:
+            lines.append("    %s[\"%s\"]" % (node_id(key), label))
+    for i in range(len(chain) - 1):
+        lines.append("    %s --> %s" % (node_id(chain[i][1]), node_id(chain[i + 1][1])))
+    return "\n".join(lines)
+
+
 def _llm_prose(section, context, fallback):
     """Get prose for a section from the LLM, or use the deterministic fallback."""
     prompt = (
@@ -137,8 +311,11 @@ def _section_overview(root, index, modules, entries, context):
     for m in modules[:4]:
         line = m["defs"][0]["line"] if m["defs"] else 1
         citations.append({"file": m["file"], "line": line})
+    # Mermaid flowchart derived from the real index (entry -> modules -> stores).
+    # Raw mermaid source (no ``` wrapper); the UI wraps/renders it.
+    diagram = _architecture_diagram(index, modules, entries)
     return {"id": "architecture", "title": "Architecture Overview",
-            "body": prose, "citations": citations}
+            "body": prose, "citations": citations, "diagram": diagram}
 
 
 def _section_modules(root, modules, context):
@@ -165,7 +342,7 @@ def _section_modules(root, modules, context):
             "body": "\n".join(body_parts), "citations": citations}
 
 
-def _section_data_flow(root, index, entries, context):
+def _section_data_flow(root, index, modules, entries, context):
     fallback = (
         "Execution begins at the entry point(s) (%s) and flows through the "
         "key modules. Trace a request from the entry file into the modules it "
@@ -175,8 +352,11 @@ def _section_data_flow(root, index, entries, context):
     citations = [{"file": e, "line": 1} for e in entries[:4]]
     if not citations and index["files"]:
         citations = [{"file": index["files"][0], "line": 1}]
+    # Mermaid data-flow chain derived from the real index (entry -> modules ->
+    # store). Raw mermaid source (no ``` wrapper); the UI wraps/renders it.
+    diagram = _data_flow_diagram(index, modules, entries)
     return {"id": "data-flow", "title": "Data Flow",
-            "body": prose, "citations": citations}
+            "body": prose, "citations": citations, "diagram": diagram}
 
 
 def _validate_citations(root, citations):
@@ -203,6 +383,14 @@ def _validate_citations(root, citations):
 
 def _render_md(section):
     lines = ["## %s" % section["title"], "", section["body"], ""]
+    # Render the Mermaid diagram (when present) as a fenced mermaid block so
+    # the markdown view shows the same visual the dashboard renders.
+    diagram = section.get("diagram")
+    if diagram:
+        lines.append("```mermaid")
+        lines.append(diagram)
+        lines.append("```")
+        lines.append("")
     if section["citations"]:
         lines.append("**Sources:**")
         for c in section["citations"]:
@@ -259,7 +447,7 @@ def main(argv=None):
     sections = [
         _section_overview(root, index, modules, entries, context),
         _section_modules(root, modules, context),
-        _section_data_flow(root, index, entries, context),
+        _section_data_flow(root, index, modules, entries, context),
     ]
 
     # Enforce the grounding contract: validate every citation against disk.