loki-mode 7.11.0 → 7.13.0

package/autonomy/loki

@@ -739,6 +739,17 @@ detect_arg_type() {
         return 0
     fi
 
+    # R7 (zero-config first run): a one-line brief. An arg that contains
+    # whitespace and matched none of the file/issue/path patterns above is a
+    # natural-language brief (e.g. "build a todo app"), NOT a PRD path. This is
+    # additive: a single-token arg with no whitespace still falls through to
+    # "unknown" (PRD-path back-compat) below. The `--brief` flag is the
+    # deterministic escape hatch for the rare single-word brief.
+    if [[ "$arg" == *[[:space:]]* ]]; then
+        echo "brief"
+        return 0
+    fi
+
     # Fallback: unknown. Caller treats as PRD for backward compat.
     echo "unknown"
 }
@@ -752,6 +763,7 @@ cmd_start() {
     local args=()
     local prd_file=""
     local provider=""
+    local brief_text=""           # R7: explicit one-line brief (--brief "...")
     local bmad_project_path=""
     local openspec_change_path=""
     local mirofish_url=""
@@ -784,6 +796,8 @@ cmd_start() {
                 echo "  PRD mode    - path ending in .md/.json/.txt/.yaml -> build from PRD"
                 echo "  ISSUE mode  - GitHub/GitLab/Jira/Azure DevOps URL, owner/repo#N,"
                 echo "                PROJ-123, #123, or bare number -> generate PRD from issue"
+                echo "  BRIEF mode  - a quoted one-line description (with spaces) -> fast"
+                echo "                zero-config first run; visible artifact + proof quickly"
                 echo "  no input    - analyze current directory, auto-generate PRD"
                 echo ""
                 echo "Arguments:"
@@ -793,6 +807,7 @@ cmd_start() {
                 echo "Explicit mode flags (override auto-detection):"
                 echo "  --prd FILE            Force PRD mode with FILE"
                 echo "  --issue URL|NUM       Force issue mode with URL or number"
+                echo "  --brief \"TEXT\"        Force zero-config brief mode (fast first run)"
                 echo ""
                 echo "Options:"
                 echo "  --provider NAME       AI provider: claude (default), codex, cline, aider"
@@ -816,6 +831,7 @@ cmd_start() {
                 echo "  --mirofish-bg         Run MiroFish pipeline in background"
                 echo "  --no-mirofish         Disable MiroFish even if env var is set"
                 echo "  --no-plan             Skip auto-shown PRD analysis at startup"
+                echo "  --brief \"TEXT\"        Zero-config fast first run from a one-line brief"
                 echo "  --yes, -y             Skip confirmation prompts (auto-confirm)"
                 echo ""
                 echo "Issue-mode options (only used when input is an ISSUE-REF):"
@@ -836,6 +852,8 @@ cmd_start() {
                 echo ""
                 echo "Examples:"
                 echo "  loki start                              # Interactive, analyze current dir"
+                echo "  loki start \"build a todo app\"           # BRIEF mode (zero-config fast run)"
+                echo "  loki start --brief \"snake\"              # BRIEF mode (single-word escape hatch)"
                 echo "  loki start ./prd.md                     # PRD mode"
                 echo "  loki start https://github.com/o/r/issues/42  # ISSUE mode (GitHub)"
                 echo "  loki start 123                          # ISSUE mode (current repo GitHub issue)"
@@ -1065,6 +1083,22 @@ cmd_start() {
                 no_plan=true
                 shift
                 ;;
+            --brief)
+                # R7: explicit one-line brief (escape hatch for single-word
+                # briefs that detect_arg_type would otherwise treat as a PRD
+                # path). Forces the zero-config first-run brief sub-path.
+                if [[ -n "${2:-}" ]] && [[ "${2:-}" != --* ]]; then
+                    brief_text="$2"
+                    shift 2
+                else
+                    echo -e "${RED}--brief requires a one-line description (e.g., --brief \"build a todo app\")${NC}"
+                    exit 1
+                fi
+                ;;
+            --brief=*)
+                brief_text="${1#*=}"
+                shift
+                ;;
             --budget)
                 if [[ -n "${2:-}" ]]; then
                     if ! echo "$2" | grep -qE '^[0-9]+(\.[0-9]+)?$'; then
@@ -1184,12 +1218,21 @@ cmd_start() {
     done
 
     # v6.84.0: Unified dispatch based on explicit flags or auto-detection
-    # Precedence: --issue > --prd > positional auto-detect > LOKI_PRD_FILE env
+    # Precedence: --brief > --issue > --prd > positional auto-detect >
+    #             LOKI_PRD_FILE env
     local detected_type=""
-    if [ -n "$explicit_mode" ]; then
+    if [ -n "$brief_text" ]; then
+        # R7: explicit --brief always forces the zero-config brief sub-path.
+        detected_type="brief"
+    elif [ -n "$explicit_mode" ]; then
         detected_type="$explicit_mode"
     elif [ -n "$positional_arg" ]; then
         detected_type=$(detect_arg_type "$positional_arg")
+        # R7: a positional one-line brief (whitespace, not a file/issue) maps to
+        # the brief sub-path; capture the text from the positional arg.
+        if [ "$detected_type" = "brief" ]; then
+            brief_text="$positional_arg"
+        fi
     elif [ -n "${LOKI_PRD_FILE:-}" ]; then
         detected_type="prd"
         prd_file="$LOKI_PRD_FILE"
@@ -1229,6 +1272,51 @@ cmd_start() {
         return $?
     fi
 
+    # R7 (zero-config first run): BRIEF mode. The user gave a one-line brief
+    # (`loki start "build a todo app"` or `loki start --brief "..."`). Synthesize
+    # a forward-looking PRD, switch to the lightweight TTFV profile (honest fast:
+    # capped iterations, council off, simple tier, heavy phases off), and mark
+    # LOKI_TTFV=1 so run.sh prints the "what next / go deeper" framing at the
+    # end. Then fall through to the normal flow, which appends prd_file to args
+    # and execs run.sh. This is additive -- nothing here changes the PRD/issue
+    # paths above.
+    if [ "$detected_type" = "brief" ]; then
+        local version
+        version=$(get_version)
+        local _ttfv_max_iter="${LOKI_MAX_ITERATIONS:-3}"
+        mkdir -p "$LOKI_DIR" 2>/dev/null || true
+        local brief_prd="$LOKI_DIR/brief-prd-$$.md"
+        synthesize_brief_prd "$brief_prd" "$brief_text"
+        prd_file="$brief_prd"
+
+        # Apply the shared lightweight profile and flag the TTFV first-run path.
+        # The signal value ("brief") drives the end-of-run wording in run.sh so
+        # the message matches what actually ran (lightweight, council off).
+        set_ttfv_lightweight_profile "$_ttfv_max_iter"
+        export LOKI_TTFV=brief
+        # Skip the heavy auto-plan analysis -- the brief path is the fast path,
+        # and we already printed the upfront framing below.
+        no_plan=true
+
+        echo -e "${BOLD}Loki Mode v$version - Zero-config first run${NC}"
+        echo ""
+        echo -e "${CYAN}Brief:${NC} $brief_text"
+        echo -e "${DIM}Fast first pass: $_ttfv_max_iter iterations max, council off, simple tier.${NC}"
+        echo -e "${DIM}You will get a runnable artifact and a proof-of-run quickly.${NC}"
+        echo -e "${DIM}Go deeper later with: loki start (full RARV-C depth).${NC}"
+        echo -e "${GREEN}Brief PRD written${NC} to $brief_prd"
+        echo ""
+    fi
+
+    # R7: existing-repo no-arg path also gets the TTFV "what next" framing at the
+    # end of the run. Execution here is UNCHANGED (full-depth no-PRD codebase
+    # analysis + generated-PRD-reuse); we only add accurate end-of-run framing.
+    # The signal value ("repo") drives the full-depth wording in run.sh so the
+    # message does not falsely claim a lightweight pass.
+    if [ "$detected_type" = "empty" ] && [ -z "${LOKI_TTFV:-}" ]; then
+        export LOKI_TTFV=repo
+    fi
+
     # PRD mode: positional arg is the PRD file (if not already set via --prd)
     if [ "$detected_type" = "prd" ] && [ -z "$prd_file" ]; then
         prd_file="$positional_arg"
@@ -8847,6 +8935,65 @@ cmd_demo() {
     return $start_exit
 }
 
+# R7 (zero-config first run): set the lightweight TTFV execution profile.
+# Shared by `cmd_quick` and the `loki start "<brief>"` brief sub-path so the
+# fast first pass means the same thing in both: capped iterations, completion
+# council off, simple complexity tier, heavy phases off. This is HONEST fast --
+# it genuinely shortens the path to first visible value; it does not fake
+# progress. Depth is opt-in via a plain `loki start` re-run.
+# Usage: set_ttfv_lightweight_profile [max_iter]
+set_ttfv_lightweight_profile() {
+    local max_iter="${1:-${LOKI_MAX_ITERATIONS:-3}}"
+    export LOKI_MAX_ITERATIONS="$max_iter"
+    export LOKI_COMPLEXITY=simple
+    export LOKI_COUNCIL_ENABLED=false
+    export LOKI_PHASE_CODE_REVIEW=false
+    export LOKI_PHASE_PERFORMANCE=false
+    export LOKI_PHASE_ACCESSIBILITY=false
+    export LOKI_PHASE_REGRESSION=false
+    export LOKI_PHASE_UAT=false
+    export LOKI_PHASE_WEB_RESEARCH=false
+}
+
+# R7: synthesize a forward-looking PRD from a one-line brief. Writes to a
+# unique path (caller-provided) and echoes nothing -- the file is the output.
+# Kept DISTINCT from .loki/generated-prd.md (codebase-analysis artifact) so it
+# never pollutes the v7.8.1 generated-PRD-reuse signature logic. The brief text
+# is the project intent; the rest is a minimal scaffold the agent fills in.
+# Usage: synthesize_brief_prd <output_file> <brief_text>
+synthesize_brief_prd() {
+    local out_file="$1"
+    local brief_text="$2"
+    local out_dir
+    out_dir="$(dirname "$out_file")"
+    mkdir -p "$out_dir" 2>/dev/null || true
+    cat > "$out_file" << BRIEFEOF
+# Project Brief
+
+## Overview
+$brief_text
+
+## Requirements
+- Build the smallest working version of the above that a user can see and run.
+- Prefer a runnable artifact (a page, a CLI, an API endpoint) over scaffolding.
+- Follow conventional structure for the chosen stack; keep dependencies minimal.
+- Write a short README describing how to run it.
+
+## Success Criteria
+- A user can run the result and observe the core behavior described above.
+- No errors on a clean start; the happy path works end to end.
+
+## Constraints
+- This is a fast first pass (zero-config first run). Keep scope tight.
+- Do not over-engineer; depth and hardening come on a later full run.
+- No emojis, no em dashes in code, comments, or docs.
+
+---
+
+**Mode:** Brief (zero-config first run, lightweight first pass)
+BRIEFEOF
+}
+
 # Quick mode - lightweight single-task execution
 cmd_quick() {
     # v7.6.3 B-11 fix: --help previously fell through to provider invocation
@@ -8934,16 +9081,9 @@ QPRDEOF
     echo -e "${GREEN}Quick PRD generated${NC} at $quick_prd"
     echo ""
 
-    # Set lightweight execution environment
-    export LOKI_MAX_ITERATIONS="$max_iter"
-    export LOKI_COMPLEXITY=simple
-    export LOKI_COUNCIL_ENABLED=false
-    export LOKI_PHASE_CODE_REVIEW=false
-    export LOKI_PHASE_PERFORMANCE=false
-    export LOKI_PHASE_ACCESSIBILITY=false
-    export LOKI_PHASE_REGRESSION=false
-    export LOKI_PHASE_UAT=false
-    export LOKI_PHASE_WEB_RESEARCH=false
+    # Set lightweight execution environment (shared TTFV profile -- see
+    # set_ttfv_lightweight_profile; same profile the R7 brief sub-path uses).
+    set_ttfv_lightweight_profile "$max_iter"
 
     # Record start for efficiency tracking
     record_session_start
@@ -13065,6 +13205,9 @@ main() {
         docs)
             cmd_docs "$@"
             ;;
+        wiki)
+            cmd_wiki "$@"
+            ;;
         magic)
             cmd_magic "$@"
             ;;
@@ -22493,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/autonomy/run.sh

@@ -4121,6 +4121,69 @@ generate_proof_of_run() {
     return 0
 }
 
+# print_ttfv_next_steps: R7 zero-config first-run "what next / go deeper"
+# message. The wording MUST match what actually ran, so it branches on the mode:
+#   - brief: a one-line brief ran on the lightweight profile (council off,
+#            simple tier, capped iterations). Proof contains diffs, cost, time
+#            (council verdicts are absent because the council was disabled).
+#   - repo:  a no-arg in-repo run analyzed the codebase and ran at full depth
+#            (council on). Proof contains diffs, cost, time, and council
+#            verdicts.
+# This function only prints; the caller owns the TTY gate. Never fails the run.
+# Usage: print_ttfv_next_steps <mode> <result>
+print_ttfv_next_steps() {
+    local mode="${1:-}"
+    local result="${2:-0}"
+    local loki_dir="${TARGET_DIR:-.}/.loki"
+    local proofs_dir="$loki_dir/proofs"
+
+    echo ""
+    echo "============================================================"
+    if [ "$result" = "0" ]; then
+        echo "  First pass complete. Here is what you have:"
+    else
+        echo "  First pass ended early. Here is what was produced:"
+    fi
+    echo "============================================================"
+    echo ""
+    echo "  What I did:"
+    if [ "$mode" = "brief" ]; then
+        echo "    - Worked from your one-line brief on a fast, lightweight first"
+        echo "      pass (council off, simple tier, capped iterations)."
+        echo "    - Generated a proof-of-run (diffs, cost, time)."
+    else
+        echo "    - Analyzed your codebase and generated a PRD, then ran a full"
+        echo "      first pass (council on, full RARV-C depth)."
+        echo "    - Generated a proof-of-run (diffs, cost, time, council verdicts)."
+    fi
+    echo ""
+    echo "  See the visible artifact (proof-of-run):"
+    if [ -d "$proofs_dir" ]; then
+        local latest
+        latest=$(ls -1t "$proofs_dir" 2>/dev/null | head -1)
+        if [ -n "$latest" ]; then
+            echo "    loki proof open $latest"
+            echo "    (or open $proofs_dir/$latest/index.html)"
+        else
+            echo "    loki proof list"
+        fi
+    else
+        echo "    loki proof list"
+    fi
+    echo ""
+    if [ "$mode" = "brief" ]; then
+        echo "  Go deeper (full RARV-C depth, council-gated):"
+        echo "    loki start                 # continue / harden this project"
+        echo "    loki start ./prd.md        # build from a full PRD"
+    else
+        echo "  Next steps:"
+        echo "    loki start ./prd.md        # build from a full PRD"
+        echo "    loki start \"<one line>\"    # fast first pass from a brief"
+    fi
+    echo ""
+    return 0
+}
+
 track_iteration_complete() {
     local iteration="$1"
     local exit_code="${2:-0}"
@@ -13335,6 +13398,15 @@ main() {
         generate_proof_of_run "$result" || true
     fi
 
+    # R7 (zero-config first run): "what next / go deeper" framing. Only when the
+    # CLI flagged this as a TTFV first run and stdout is a TTY, so it stays
+    # silent in CI / pipes and never fires for normal PRD runs. The wording
+    # branches on the mode (brief = lightweight first pass; repo = full-depth
+    # codebase analysis) so the message always matches what actually ran.
+    if [ -n "${LOKI_TTFV:-}" ] && [ -t 1 ]; then
+        print_ttfv_next_steps "${LOKI_TTFV}" "$result" || true
+    fi
+
     # Create PR from agent branch if branch protection was enabled
     create_session_pr
     audit_agent_action "session_stop" "Session ended" "result=$result,iterations=$ITERATION_COUNT"

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.11.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.