loki-mode 7.12.0 → 7.13.0

package/autonomy/lib/wiki_index.py

@@ -0,0 +1,258 @@
+"""wiki_index.py -- dependency-free codebase index for the R5 auto-wiki.
+
+Builds a line-anchored chunk index over a project's source files and provides
+deterministic token-overlap retrieval. This is the grounding substrate for
+cited answers: every chunk carries the REAL repo-relative file path and the
+REAL start/end line numbers it came from, so a citation can always be checked
+against the filesystem.
+
+Reuse note: the token-overlap scoring (`_tokenize` + overlap weighting) is
+ported from memory/knowledge_graph.py (OrganizationKnowledgeGraph), which scores
+memory patterns the same way. knowledge_graph.py is NOT a code index (it
+aggregates .loki/memory/semantic patterns), so the code scanning/chunking here
+is new. retrieval.py is a memory retriever, not a code indexer, so it is not
+reused for code retrieval.
+
+No third-party dependencies. CI-safe (no Docker, no network, no provider).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+
+# Source extensions we index. Kept broad but excludes lockfiles/binaries.
+SOURCE_EXTS = {
+    ".py", ".js", ".ts", ".tsx", ".jsx", ".mjs", ".cjs",
+    ".rs", ".go", ".rb", ".java", ".kt", ".kts", ".c", ".cc", ".cpp",
+    ".h", ".hpp", ".cs", ".php", ".swift", ".sh", ".bash", ".sql",
+    ".vue", ".svelte", ".scala", ".clj", ".ex", ".exs", ".lua", ".r",
+}
+
+# Directories never worth indexing.
+SKIP_DIRS = {
+    "node_modules", ".git", "vendor", "__pycache__", "dist", "build",
+    ".next", "target", ".venv", "venv", "coverage", ".loki", ".cache",
+    "out", ".turbo", ".pytest_cache", ".mypy_cache",
+}
+
+CHUNK_LINES = 60  # lines per chunk; overlap-free, line-anchored.
+MAX_FILES = 800   # safety cap so huge repos stay cheap.
+MAX_FILE_BYTES = 400_000  # skip very large generated/minified files.
+
+# Tokenizer ported from memory/knowledge_graph.py:_tokenize / _STOPWORDS.
+_STOPWORDS = {
+    "the", "a", "an", "to", "for", "of", "and", "or", "with", "without",
+    "is", "are", "be", "up", "on", "in", "by", "not", "this", "that",
+    "from", "as", "at", "it", "if", "do", "we", "my", "our", "how",
+    "def", "self", "return", "import", "const", "let", "var", "function",
+}
+
+
+def _tokenize(text):
+    """Lowercase, split on non-alphanumerics, drop stopwords + short tokens.
+
+    Ported from knowledge_graph.OrganizationKnowledgeGraph._tokenize so wiki
+    retrieval scores text the same way memory-pattern retrieval does.
+    """
+    toks = re.split(r"[^a-z0-9_]+", str(text or "").lower())
+    return {t for t in toks if len(t) > 2 and t not in _STOPWORDS}
+
+
+def _git_tracked_files(root):
+    """Return git-tracked file paths (repo-relative), or None if not a repo."""
+    try:
+        out = subprocess.run(
+            ["git", "-C", str(root), "ls-files"],
+            capture_output=True, text=True, timeout=30,
+        )
+        if out.returncode != 0:
+            return None
+        files = [line.strip() for line in out.stdout.splitlines() if line.strip()]
+        return files or None
+    except (OSError, subprocess.SubprocessError):
+        return None
+
+
+def _walk_files(root):
+    """Filtered filesystem walk fallback (when not a git repo)."""
+    root = Path(root)
+    results = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        for fn in filenames:
+            rel = os.path.relpath(os.path.join(dirpath, fn), root)
+            results.append(rel)
+    return results
+
+
+def list_source_files(root):
+    """Return a sorted list of repo-relative source files under root.
+
+    Prefers git ls-files (respects .gitignore), falls back to a filtered walk.
+    """
+    root = Path(root)
+    candidates = _git_tracked_files(root)
+    if candidates is None:
+        candidates = _walk_files(root)
+
+    sources = []
+    for rel in candidates:
+        # Skip anything inside a skip dir (git tracked files can include them
+        # if they were committed; we still exclude noise dirs).
+        parts = set(Path(rel).parts)
+        if parts & SKIP_DIRS:
+            continue
+        ext = os.path.splitext(rel)[1].lower()
+        if ext not in SOURCE_EXTS:
+            continue
+        abs_path = root / rel
+        try:
+            if not abs_path.is_file():
+                continue
+            if abs_path.stat().st_size > MAX_FILE_BYTES:
+                continue
+        except OSError:
+            continue
+        sources.append(rel)
+    sources.sort()
+    return sources[:MAX_FILES]
+
+
+def _read_lines(abs_path):
+    try:
+        with open(abs_path, "r", encoding="utf-8", errors="replace") as f:
+            return f.read().splitlines()
+    except OSError:
+        return []
+
+
+def build_index(root):
+    """Build a line-anchored chunk index over the project's source files.
+
+    Returns a dict:
+      {
+        "root": <abs root>,
+        "files": [<repo-relative paths>],
+        "chunks": [
+          {"id": int, "file": <rel>, "start_line": int, "end_line": int,
+           "text": <chunk text>},
+          ...
+        ],
+      }
+    Paths are ALWAYS repo-relative (no PII, no absolute paths leak).
+    Line numbers are 1-based and inclusive.
+    """
+    root = Path(root).resolve()
+    files = list_source_files(root)
+    chunks = []
+    cid = 0
+    for rel in files:
+        lines = _read_lines(root / rel)
+        if not lines:
+            continue
+        for start in range(0, len(lines), CHUNK_LINES):
+            block = lines[start:start + CHUNK_LINES]
+            if not any(line.strip() for line in block):
+                continue  # skip all-blank chunks
+            chunks.append({
+                "id": cid,
+                "file": rel,
+                "start_line": start + 1,
+                "end_line": start + len(block),
+                "text": "\n".join(block),
+            })
+            cid += 1
+    return {"root": str(root), "files": files, "chunks": chunks}
+
+
+def retrieve(index, query, k=6):
+    """Deterministic top-K chunk retrieval by token overlap.
+
+    Scoring mirrors knowledge_graph.query_patterns: token overlap between the
+    query and the chunk text, plus a small bonus when the query substring
+    appears verbatim and when query tokens appear in the file path (so
+    "how does the cli dispatch" surfaces cli.* files). No LLM, no network.
+    Ties broken by chunk id for stable, reproducible ordering.
+    """
+    qtokens = _tokenize(query)
+    qlower = str(query or "").lower()
+    scored = []
+    for ch in index.get("chunks", []):
+        text = ch.get("text", "")
+        score = 0
+        overlap = qtokens & _tokenize(text)
+        score += 3 * len(overlap)
+        # Path tokens (file/dir names are strong signals).
+        path_overlap = qtokens & _tokenize(ch.get("file", ""))
+        score += 2 * len(path_overlap)
+        # Verbatim substring bonus.
+        if qlower and len(qlower) > 3 and qlower in text.lower():
+            score += 4
+        if score > 0:
+            scored.append((score, ch["id"], ch))
+    # Highest score first; stable tiebreak on id.
+    scored.sort(key=lambda t: (-t[0], t[1]))
+    return [ch for _, _, ch in scored[:k]]
+
+
+def compute_signature(root):
+    """Cheap-incremental signature over git HEAD + per-file content hashes.
+
+    Same idea as the proof/docs manifest: a deterministic hash that changes
+    iff the indexed source set changes. Used to skip regeneration when the
+    codebase is unchanged.
+    """
+    root = Path(root).resolve()
+    h = hashlib.sha256()
+    # git HEAD (if available) makes the signature cheap to invalidate on commit.
+    try:
+        head = subprocess.run(
+            ["git", "-C", str(root), "rev-parse", "HEAD"],
+            capture_output=True, text=True, timeout=15,
+        )
+        if head.returncode == 0:
+            h.update(b"head:" + head.stdout.strip().encode())
+    except (OSError, subprocess.SubprocessError):
+        pass
+    for rel in list_source_files(root):
+        try:
+            data = (root / rel).read_bytes()
+        except OSError:
+            continue
+        h.update(rel.encode("utf-8"))
+        h.update(hashlib.sha256(data).digest())
+    return h.hexdigest()
+
+
+def extract_definitions(root, rel, limit=12):
+    """Return real def/class/function lines for a file, for code-derived citations.
+
+    Returns a list of {"name": str, "line": int} where line is 1-based and
+    points at a real definition in the file. Language-agnostic via a small set
+    of regexes; only emits matches that actually exist in the file.
+    """
+    lines = _read_lines(Path(root) / rel)
+    patterns = [
+        re.compile(r"^\s*def\s+([A-Za-z_][A-Za-z0-9_]*)"),
+        re.compile(r"^\s*class\s+([A-Za-z_][A-Za-z0-9_]*)"),
+        re.compile(r"^\s*(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)"),
+        re.compile(r"^\s*(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?\("),
+        re.compile(r"^\s*(?:pub\s+)?fn\s+([A-Za-z_][A-Za-z0-9_]*)"),
+        re.compile(r"^\s*func\s+(?:\([^)]*\)\s*)?([A-Za-z_][A-Za-z0-9_]*)"),
+        re.compile(r"^\s*([A-Za-z_][A-Za-z0-9_]*)\s*\(\)\s*\{"),  # bash funcs
+    ]
+    defs = []
+    for i, line in enumerate(lines, start=1):
+        for pat in patterns:
+            m = pat.match(line)
+            if m:
+                defs.append({"name": m.group(1), "line": i})
+                break
+        if len(defs) >= limit:
+            break
+    return defs

package/autonomy/lib/wiki_llm.py

@@ -0,0 +1,140 @@
+"""wiki_llm.py -- stub-aware LLM invocation + citation validation for R5 wiki.
+
+Keeps every paid-call and grounding-guarantee concern in one place so the
+generator and the ask script behave identically.
+
+LLM stub contract (CI-safe, zero paid calls in tests):
+  LOKI_WIKI_LLM_STUB unset       -> call the real provider (claude -p / codex / ...)
+                                    via the same mechanism loki docs uses; if no
+                                    provider is on PATH, return None (callers then
+                                    fall back to extractive/template output).
+  LOKI_WIKI_LLM_STUB=<file path> -> read the completion from that file.
+  LOKI_WIKI_LLM_STUB=<other>     -> use the value literally as the completion.
+
+No third-party dependencies.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from pathlib import Path
+
+
+def invoke_llm(prompt, timeout=120):
+    """Return the LLM completion string, or None if unavailable.
+
+    Honors LOKI_WIKI_LLM_STUB for CI. Otherwise shells out to the configured
+    provider, mirroring loki docs `_docs_invoke_provider`.
+    """
+    stub = os.environ.get("LOKI_WIKI_LLM_STUB")
+    if stub is not None:
+        # A path to a file with the canned completion, else the literal value.
+        if os.path.sep in stub or stub.endswith(".txt"):
+            p = Path(stub)
+            if p.is_file():
+                try:
+                    return p.read_text(encoding="utf-8", errors="replace")
+                except OSError:
+                    return ""
+        return stub
+
+    provider = os.environ.get("LOKI_PROVIDER", "claude")
+    state_provider = Path(".loki/state/provider")
+    if state_provider.is_file():
+        try:
+            provider = state_provider.read_text().strip() or provider
+        except OSError:
+            pass
+
+    # Resolve a timeout wrapper if present (matches the bash docs helper).
+    timeout_cmd = None
+    for cand in ("timeout", "gtimeout"):
+        if _which(cand):
+            timeout_cmd = cand
+            break
+
+    cmds = {
+        "claude": ["claude", "-p", prompt],
+        "codex": ["codex", "exec", "--full-auto", prompt],
+        "cline": ["cline", "-y", prompt],
+        "aider": ["aider", "--message", prompt, "--yes-always", "--no-auto-commits"],
+    }
+    base = cmds.get(provider)
+    if base is None or not _which(base[0]):
+        return None
+    cmd = ([timeout_cmd, str(timeout)] + base) if timeout_cmd else base
+    try:
+        out = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=timeout + 10,
+            stdin=subprocess.DEVNULL,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if out.returncode != 0 and not out.stdout.strip():
+        return None
+    return out.stdout
+
+
+def _which(name):
+    for d in os.environ.get("PATH", "").split(os.pathsep):
+        cand = os.path.join(d, name)
+        if os.path.isfile(cand) and os.access(cand, os.X_OK):
+            return cand
+    return None
+
+
+_CITE_RE = re.compile(r"\[(\d+)\]")
+
+
+def map_and_validate_citations(answer_text, chunks, root):
+    """Map [n] indices in answer_text to real {file,line} citations.
+
+    chunks: the numbered chunk list shown to the LLM. chunks[n-1] is the chunk
+    referenced by [n] (1-based). A citation is kept only if:
+      - the index is in range (it references a chunk we actually supplied), and
+      - the file exists on disk AND start_line <= file length.
+    This makes a fabricated citation structurally impossible to survive.
+
+    Returns (clean_text, citations) where citations is a de-duplicated list of
+    {"file": rel, "line": int} in first-appearance order, and clean_text has the
+    [n] markers rewritten to [file:line] for human-readable output.
+    """
+    root = Path(root)
+    citations = []
+    seen = set()
+
+    def _resolve(idx):
+        if idx < 1 or idx > len(chunks):
+            return None
+        ch = chunks[idx - 1]
+        rel = ch.get("file")
+        line = int(ch.get("start_line", 1))
+        abs_path = root / rel
+        try:
+            if not abs_path.is_file():
+                return None
+            with open(abs_path, "r", encoding="utf-8", errors="replace") as f:
+                nlines = sum(1 for _ in f)
+        except OSError:
+            return None
+        if line < 1 or line > max(nlines, 1):
+            return None
+        return {"file": rel, "line": line}
+
+    def _sub(m):
+        idx = int(m.group(1))
+        cite = _resolve(idx)
+        if cite is None:
+            return ""  # drop a bogus/non-resolving citation marker
+        key = (cite["file"], cite["line"])
+        if key not in seen:
+            seen.add(key)
+            citations.append(cite)
+        return "[%s:%d]" % (cite["file"], cite["line"])
+
+    clean = _CITE_RE.sub(_sub, answer_text or "")
+    # Collapse any double spaces left by dropped markers.
+    clean = re.sub(r"[ \t]{2,}", " ", clean)
+    return clean, citations

package/autonomy/loki

@@ -13205,6 +13205,9 @@ main() {
         docs)
             cmd_docs "$@"
             ;;
+        wiki)
+            cmd_wiki "$@"
+            ;;
         magic)
             cmd_magic "$@"
             ;;
@@ -22633,6 +22636,124 @@ run_debate(
     log_info "Debate complete"
 }
 
+# =============================================================================
+# loki wiki -- auto-generated, cited per-project codebase wiki + Q&A (R5).
+#
+# Loki's answer to Devin DeepWiki: a persistent, queryable wiki built from the
+# codebase, where every section cites the real source files it came from, plus
+# a grounded `ask` that returns cited answers (file:line). Heavy work lives in
+# the Python core (autonomy/lib/wiki-generator.py, wiki-ask.py, wiki_index.py);
+# this is a thin dispatcher, mirroring how cmd_proof delegates to the proof
+# generator. Generation is incremental (skips when the codebase is unchanged).
+# =============================================================================
+cmd_wiki() {
+    local subcmd="${1:-}"
+    shift 2>/dev/null || true
+
+    local lib_dir="${_LOKI_SCRIPT_DIR}/lib"
+
+    case "$subcmd" in
+        generate) _wiki_generate "$lib_dir" "$@" ;;
+        show)     _wiki_show "$@" ;;
+        ask)      _wiki_ask "$lib_dir" "$@" ;;
+        --help|-h|help|"")
+            echo -e "${BOLD}loki wiki${NC} - Auto-generated, cited codebase wiki + Q&A"
+            echo ""
+            echo "Usage: loki wiki <command> [options]"
+            echo ""
+            echo "Commands:"
+            echo "  generate [path] [--force]   Build/refresh the cited wiki in .loki/wiki/"
+            echo "  show [section]              Print the wiki (or one section: architecture|modules|data-flow)"
+            echo "  ask \"<question>\"           Cited answer grounded in the codebase (file:line)"
+            echo ""
+            echo "Each wiki section cites the real source files it was built from."
+            echo "Generation is incremental: it skips when the codebase is unchanged."
+            echo ""
+            echo "Examples:"
+            echo "  loki wiki generate                     # build wiki for current project"
+            echo "  loki wiki show architecture            # show one section"
+            echo "  loki wiki ask \"how does the cli dispatch commands\""
+            return 0
+            ;;
+        *)
+            log_error "Unknown wiki command: $subcmd"
+            echo "Run 'loki wiki --help' for usage."
+            return 1
+            ;;
+    esac
+}
+
+_wiki_generate() {
+    local lib_dir="$1"; shift
+    if ! command -v python3 >/dev/null 2>&1; then
+        log_error "python3 is required for 'loki wiki generate'"
+        return 1
+    fi
+    python3 "$lib_dir/wiki-generator.py" "$@"
+}
+
+_wiki_show() {
+    local section=""
+    local target="."
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --help|-h)
+                echo "Usage: loki wiki show [section]"
+                echo "Sections: architecture, modules, data-flow"
+                return 0
+                ;;
+            -*) log_error "Unknown option: $1"; return 1 ;;
+            *) section="$1"; shift ;;
+        esac
+    done
+    local wiki_dir="$target/.loki/wiki"
+    if [ ! -d "$wiki_dir" ]; then
+        log_error "No wiki found. Run 'loki wiki generate' first."
+        return 1
+    fi
+    if [ -n "$section" ]; then
+        local f="$wiki_dir/${section}.md"
+        if [ ! -f "$f" ]; then
+            log_error "No such section: $section (try: architecture, modules, data-flow)"
+            return 1
+        fi
+        cat "$f"
+    else
+        if [ -f "$wiki_dir/index.md" ]; then
+            cat "$wiki_dir/index.md"
+        else
+            log_error "Wiki index not found. Run 'loki wiki generate'."
+            return 1
+        fi
+    fi
+}
+
+_wiki_ask() {
+    local lib_dir="$1"; shift
+    local question=""
+    local extra=()
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --help|-h)
+                echo "Usage: loki wiki ask \"<question>\" [--json] [--k N]"
+                return 0
+                ;;
+            --json|--quiet) extra+=("$1"); shift ;;
+            --k) extra+=("--k" "${2:-6}"); shift 2 ;;
+            *) if [ -z "$question" ]; then question="$1"; else question="$question $1"; fi; shift ;;
+        esac
+    done
+    if [ -z "$question" ]; then
+        log_error "Provide a question: loki wiki ask \"how does X work\""
+        return 1
+    fi
+    if ! command -v python3 >/dev/null 2>&1; then
+        log_error "python3 is required for 'loki wiki ask'"
+        return 1
+    fi
+    python3 "$lib_dir/wiki-ask.py" --question "$question" "${extra[@]}"
+}
+
 cmd_magic() {
     local subcmd="${1:-help}"
     shift 2>/dev/null || true

package/bin/loki

@@ -116,7 +116,7 @@ fi
 # Two-token routes (provider show/list, memory list/index) match on the first
 # token only; the Bun dispatcher handles subcommand routing internally.
 case "${1:-}" in
-    version|--version|-v|status|stats|doctor|provider|memory|rollback|internal|kpis|proof)
+    version|--version|-v|status|stats|doctor|provider|memory|rollback|internal|kpis|proof|wiki)
         # v7.5.2: rollback added (wires loki-ts/src/commands/rollback.ts).
         # v7.5.3: internal added for autonomy/run.sh phase1-hooks calls.
         # v7.5.28: kpis added (Phase K MVP: read-only KPI snapshot).

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "7.12.0"
+__version__ = "7.13.0"
 
 # Expose the control app for easy import
 try:

package/dashboard/server.py

@@ -7507,6 +7507,114 @@ async def get_proof_html(run_id: str):
     return FileResponse(str(index_html), media_type="text/html")
 
 
+# ---------------------------------------------------------------------------
+# R5: Auto-wiki + cited codebase Q&A (Loki's DeepWiki).
+#
+# Surfaces the per-project wiki generated by autonomy/lib/wiki-generator.py
+# (stored under <project>/.loki/wiki/) and the grounded `ask` flow
+# (autonomy/lib/wiki-ask.py). Citations are file:line and always point at real
+# code -- the generator/ask scripts validate every citation against the
+# filesystem before emitting it, so the dashboard never shows a fabricated one.
+#
+# The section param is traversal-safe, mirroring _safe_proof_run_dir: only the
+# known section ids are accepted, so no arbitrary path can be read.
+# ---------------------------------------------------------------------------
+_WIKI_SECTIONS = {"architecture", "modules", "data-flow"}
+
+
+def _wiki_dir() -> _Path:
+    return _get_loki_dir() / "wiki"
+
+
+def _project_root() -> _Path:
+    """Resolve the active project root (.loki's parent)."""
+    return _get_loki_dir().parent
+
+
+@app.get("/api/wiki", dependencies=[Depends(auth.require_scope("read"))])
+async def get_wiki():
+    """Return the wiki manifest + section list for the active project."""
+    wiki_dir = _wiki_dir()
+    wiki_json = wiki_dir / "wiki.json"
+    if not wiki_json.is_file():
+        return {"generated": False, "sections": [],
+                "message": "No wiki generated. Run 'loki wiki generate'."}
+    data = _safe_json_read(wiki_json, default=None)
+    if not isinstance(data, dict):
+        raise HTTPException(status_code=500, detail="wiki.json unreadable")
+    manifest = _safe_json_read(wiki_dir / "wiki-manifest.json", default={}) or {}
+    sections = [
+        {"id": s.get("id"), "title": s.get("title"),
+         "citation_count": len(s.get("citations") or [])}
+        for s in data.get("sections", [])
+        if isinstance(s, dict)
+    ]
+    return {
+        "generated": True,
+        "project": data.get("project"),
+        "generated_at": data.get("generated_at"),
+        "file_count": data.get("file_count"),
+        "signature": manifest.get("signature"),
+        "sections": sections,
+    }
+
+
+@app.get("/api/wiki/{section}", dependencies=[Depends(auth.require_scope("read"))])
+async def get_wiki_section(section: str):
+    """Return one wiki section (body + validated file:line citations)."""
+    if section not in _WIKI_SECTIONS:
+        raise HTTPException(status_code=400, detail=f"unknown section: {section}")
+    wiki_json = _wiki_dir() / "wiki.json"
+    if not wiki_json.is_file():
+        raise HTTPException(status_code=404, detail="wiki not generated")
+    data = _safe_json_read(wiki_json, default=None)
+    if not isinstance(data, dict):
+        raise HTTPException(status_code=500, detail="wiki.json unreadable")
+    for s in data.get("sections", []):
+        if isinstance(s, dict) and s.get("id") == section:
+            return JSONResponse(content=s)
+    raise HTTPException(status_code=404, detail=f"section not found: {section}")
+
+
+class WikiAskRequest(BaseModel):
+    question: str = Field(..., min_length=1, max_length=2000)
+    k: int = Field(default=6, ge=1, le=20)
+
+
+@app.post("/api/wiki/ask", dependencies=[Depends(auth.require_scope("read"))])
+async def post_wiki_ask(req: WikiAskRequest):
+    """Grounded, cited codebase Q&A.
+
+    Shells out to autonomy/lib/wiki-ask.py (the single source of truth for the
+    grounding + citation-validation contract) and returns its JSON. Every
+    citation in the response resolves to a real file:line.
+    """
+    project_root = _project_root()
+    repo_root = _Path(__file__).resolve().parent.parent
+    ask_script = repo_root / "autonomy" / "lib" / "wiki-ask.py"
+    if not ask_script.is_file():
+        raise HTTPException(status_code=503, detail="wiki-ask backend missing")
+    try:
+        proc = subprocess.run(
+            ["python3", str(ask_script), "--root", str(project_root),
+             "--question", req.question, "--k", str(req.k), "--json"],
+            capture_output=True, text=True, timeout=180,
+            cwd=str(project_root),
+        )
+    except (OSError, subprocess.SubprocessError) as e:
+        raise HTTPException(status_code=503, detail=f"wiki ask failed: {e}")
+    if proc.returncode == 3:
+        return {"question": req.question, "answer": "",
+                "citations": [], "note": "no relevant code found"}
+    if proc.returncode != 0:
+        raise HTTPException(status_code=500,
+                            detail=(proc.stderr or "wiki ask error").strip())
+    try:
+        return JSONResponse(content=json.loads(proc.stdout))
+    except json.JSONDecodeError:
+        raise HTTPException(status_code=500, detail="wiki ask returned bad JSON")
+
+
 # ---------------------------------------------------------------------------
 # SPA catch-all: serve index.html for any path not matched by API routes
 # or static asset mounts.  This lets the dashboard UI handle client-side routing.