loki-mode 7.82.0 → 7.83.1

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.82.0
+# Loki Mode v7.83.1
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -406,4 +406,4 @@ See `CHANGELOG.md` entries [7.5.7], [7.5.8], [7.5.13] for the per-fix list and r
 
 ---
 
-**v7.82.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**
+**v7.83.1 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-7.82.0
+7.83.1

package/autonomy/loki

@@ -265,6 +265,30 @@ _loki_new_session_exec() {
     fi
 }
 
+# Actionable PRD-not-found exit. Both PRD-path existence guards in cmd_start route
+# through here so they cannot drift: the user always learns the two recoveries
+# (fix the path, or drop the arg to auto-generate from the codebase). If a sibling
+# .md file looks like a near-miss of the bad path, surface it honestly as a hint.
+# Prints to stderr and exits 1. Honest: only suggests a "did you mean" when a real
+# .md sibling exists; never fabricates a path.
+_prd_not_found_die() {
+    local bad_path="$1"
+    echo -e "${RED}Error: PRD file not found: $bad_path${NC}" >&2
+    echo -e "${YELLOW}Hint: provide a path to an existing .md/.json/.txt/.yaml/.yml file, or run 'loki start' with no args to analyze the current directory.${NC}" >&2
+    # Best-effort near-miss suggestion: if a .md file sits in the same directory
+    # as the bad path, point at it. Read-only; silent when nothing matches.
+    local dir base suggestion
+    dir="$(dirname "$bad_path" 2>/dev/null)" || dir="."
+    base="$(basename "$bad_path" 2>/dev/null)"
+    if [ -d "$dir" ] && [ -n "$base" ]; then
+        suggestion="$(ls -1 "$dir"/*.md 2>/dev/null | head -1)"
+        if [ -n "$suggestion" ]; then
+            echo -e "${YELLOW}Did you mean: $suggestion ?${NC}" >&2
+        fi
+    fi
+    exit 1
+}
+
 # Anonymous usage telemetry
 PROJECT_DIR="$SKILL_DIR"
 _TELEMETRY_SCRIPT="$SKILL_DIR/autonomy/telemetry.sh"
@@ -714,6 +738,7 @@ show_help() {
     echo ""
     echo "Session:"
     echo "  status [--json]  Show current status (--json for machine-readable)"
+    echo "  next             Run the right next step for you (resume / ship / why)"
     echo "  stop             Stop execution immediately"
     echo "  pause            Pause after current session"
     echo "  resume           Resume paused execution"
@@ -745,7 +770,7 @@ show_help() {
     echo "  version          Show version"
     echo "  help             Show this help ('loki help aliases' for old names)"
     echo ""
-    echo "More commands (grill, spec, deploy, cleanup, init, watch, demo, web, api,"
+    echo "More commands (ship, grill, spec, deploy, cleanup, init, watch, demo, web, api,"
     echo "logs, github, import, council, proof, audit, compliance, agent, template,"
     echo "magic, docs, wiki, ci, test, bench, secrets, telemetry, crash, worktree,"
     echo "failover, monitor, remote, ...) are dispatchable and documented via"
@@ -909,6 +934,7 @@ show_landing() {
     echo -e "First time here? ${CYAN}loki doctor${NC} checks your setup (an AI provider CLI is required)."
     echo ""
     echo "Get started:"
+    echo -e "  ${CYAN}loki quickstart${NC}       Guided first build from your idea (no PRD needed)"
     echo -e "  ${CYAN}loki start ./prd.md${NC}   Build from a spec (PRD file, GitHub issue, or no arg)"
     echo -e "  ${CYAN}loki demo${NC}             Build a sample todo app end to end (real run)"
     echo -e "  ${CYAN}loki dashboard start${NC}  Start the live run monitor (then: loki dashboard open)"
@@ -1686,9 +1712,7 @@ cmd_start() {
         case "$prd_file" in
             *.md|*.json|*.txt|*.yaml|*.yml)
                 if [ ! -f "$prd_file" ]; then
-                    echo "Error: PRD file not found: $prd_file" >&2
-                    echo "Hint: provide a path to an existing .md/.json/.txt/.yaml/.yml file, or run 'loki start' with no args to analyze the current directory." >&2
-                    exit 1
+                    _prd_not_found_die "$prd_file"
                 fi
                 ;;
         esac
@@ -1711,8 +1735,7 @@ cmd_start() {
         case "$prd_file" in
             *.md|*.json|*.txt|*.yaml|*.yml)
                 if [ ! -f "$prd_file" ]; then
-                    echo -e "${RED}Error: PRD file not found: $prd_file${NC}" >&2
-                    exit 1
+                    _prd_not_found_die "$prd_file"
                 fi
                 ;;
         esac
@@ -2013,7 +2036,13 @@ cmd_start() {
         fi
         if [ -n "$_existing_pid" ] && kill -0 "$_existing_pid" 2>/dev/null; then
             echo -e "${RED}Error: another loki instance is running (pid $_existing_pid).${NC}" >&2
-            echo -e "${YELLOW}Run 'loki stop' first, then retry 'loki start'.${NC}" >&2
+            # 'loki stop' is folder-scoped by default (v7.7.30), so it only stops a
+            # run in THIS directory. If the live instance is in another project,
+            # 'loki stop' here reports "No active session" and the user is stuck in
+            # a start-says-running / stop-says-clean loop. Point at the global stop
+            # and at 'loki status' to find the live run.
+            echo -e "${YELLOW}Run 'loki stop' here, or 'loki stop --all' if it is running in another project.${NC}" >&2
+            echo -e "${YELLOW}See 'loki status' for the live run, then retry 'loki start'.${NC}" >&2
             exit 1
         fi
         # PID is stale (file present but process gone). Log + remove + continue.
@@ -2954,6 +2983,386 @@ cmd_resume() {
     fi
 }
 
+# Resolve the terminal-run status from the same already-captured artifacts that
+# cmd_why reads (no new state, no spend). Echoes a single token: the resolved
+# status string (e.g. council_approved, paused, max_iterations_reached), or the
+# literal "none" when no run exists here yet. Used by cmd_next so its status->
+# action mapping reads exactly the same state cmd_why does (no drift).
+# Read-only; never fabricates.
+_loki_resolve_run_status() {
+    local loki_dir="${LOKI_DIR:-.loki}"
+    local state_file="$loki_dir/autonomy-state.json"
+    if [ -n "${LOKI_SESSION_ID:-}" ] && [ -f "$loki_dir/sessions/${LOKI_SESSION_ID}/autonomy-state.json" ]; then
+        state_file="$loki_dir/sessions/${LOKI_SESSION_ID}/autonomy-state.json"
+    fi
+    local completion_file="$loki_dir/state/completion.json"
+
+    if [ ! -f "$state_file" ] && [ ! -f "$completion_file" ]; then
+        printf '%s\n' "none"
+        return 0
+    fi
+
+    _LOKI_NA_STATE="$state_file" _LOKI_NA_COMPLETION="$completion_file" python3 - <<'NASTATUS'
+import json, os
+def load(p):
+    try:
+        with open(p) as f: return json.load(f)
+    except Exception: return {}
+state = load(os.environ.get("_LOKI_NA_STATE", ""))
+comp = load(os.environ.get("_LOKI_NA_COMPLETION", ""))
+# Mirror cmd_why's COMP_OUTCOME_ALIASES so a completion-only state (a rotated or
+# crashed run with no live status, only completion.json's outcome) resolves to
+# the canonical status loki next's action map keys on. Without this, an outcome
+# of "complete"/"max_iterations" drifted to the default "loki status" instead of
+# "loki ship"/"loki resume".
+COMP_OUTCOME_ALIASES = {
+    "complete": "council_approved",
+    "max_iterations": "max_iterations_reached",
+    "intervention": "paused",
+}
+status = state.get("status")
+if not status:
+    raw_outcome = comp.get("outcome") or ""
+    status = COMP_OUTCOME_ALIASES.get(raw_outcome, raw_outcome) or "unknown"
+print(status)
+NASTATUS
+}
+
+# Map a resolved status to the single concrete next-action SENTENCE (the same
+# wording cmd_why prints under "What to do"). Echoes the action string. Kept in
+# lockstep with cmd_why's GUIDE map so why and next agree.
+_loki_next_action() {
+    local status="${1:-unknown}"
+    case "$status" in
+        council_approved)
+            echo "Review the diff and open a PR (loki ship, or git push + gh pr create)." ;;
+        council_force_approved)
+            echo "Review the diff carefully before merging -- convergence was not unanimous." ;;
+        completion_promise_fulfilled)
+            echo "Verify the promised outcome, then review and PR (loki ship)." ;;
+        max_iterations_reached)
+            echo "Raise LOKI_MAX_ITERATIONS (or narrow the spec), then resume (loki resume)." ;;
+        max_retries_exceeded)
+            echo "Read .loki/logs for the recurring error, fix the root cause, then re-run (loki why)." ;;
+        failed)
+            echo "Read the failure (loki why), fix it, then re-run." ;;
+        policy_blocked)
+            echo "Review the blocking finding (loki why); address it or use the documented override." ;;
+        budget_exceeded)
+            echo "Raise LOKI_BUDGET_LIMIT or accept the partial result, then resume (loki resume)." ;;
+        paused)
+            echo "Resume with: loki resume." ;;
+        interrupted)
+            echo "Resume with: loki resume." ;;
+        stopped)
+            echo "Start a new build (loki start), or resume if you meant to continue." ;;
+        force_stopped)
+            echo "Start a new build, or investigate why a force-stop was needed (loki why)." ;;
+        running)
+            echo "A build looks active (or crashed mid-run); check loki status." ;;
+        none)
+            echo "Run a build first: loki start <spec>." ;;
+        *)
+            echo "Check loki status and loki why for detail." ;;
+    esac
+}
+
+# loki next -- one command that runs the right next step for you.
+# Reads the SAME already-captured state as cmd_why (no new state, no spend),
+# resolves the terminal status, and proposes the single mapped next step, then
+# runs it on confirmation. Default on a TTY is confirm-then-run; --yes runs it
+# without asking; --dry-run and any non-TTY context only PRINT (honest: never
+# auto-acts in CI / when piped). Strictly additive: reuses cmd_resume, cmd_ship,
+# cmd_why, and cmd_status; never touches the build path.
+cmd_next() {
+    local assume_yes=false
+    local dry_run=false
+    case "${1:-}" in
+        --help|-h|help)
+            echo -e "${BOLD}Loki Mode -- run the right next step for you${NC}"
+            echo ""
+            echo "Usage: loki next [--yes] [--dry-run]"
+            echo ""
+            echo "Reads the last build's recorded outcome (the same state 'loki why'"
+            echo "reads -- no new run, no cost) and carries you forward by running the"
+            echo "single mapped next step: resume a paused/interrupted run, finish a"
+            echo "council-approved build (loki ship), or route a failure to 'loki why'."
+            echo ""
+            echo "Default on a terminal: it shows the proposed step and asks before"
+            echo "running it. Non-interactive (piped/CI) it only prints the step;"
+            echo "it never acts on its own there."
+            echo ""
+            echo "Options:"
+            echo "  --yes        Run the proposed step without asking"
+            echo "  --dry-run    Print the proposed step only; do not run it"
+            echo "  --help, -h   Show this help and exit"
+            return 0
+            ;;
+        --yes|-y) assume_yes=true ;;
+        --dry-run) dry_run=true ;;
+        "") : ;;
+        *) echo -e "${RED}Unknown flag: $1${NC}" >&2; echo "Usage: loki next [--yes] [--dry-run]" >&2; return 1 ;;
+    esac
+    # Allow a second flag (e.g. --dry-run --yes order-agnostic).
+    case "${2:-}" in
+        --yes|-y) assume_yes=true ;;
+        --dry-run) dry_run=true ;;
+    esac
+
+    local status
+    status="$(_loki_resolve_run_status)"
+    if [ "$status" = "none" ]; then
+        echo "loki next: no run found here yet." >&2
+        echo "Run a build first: loki start <spec>" >&2
+        return 1
+    fi
+
+    local action_text
+    action_text="$(_loki_next_action "$status")"
+
+    # Map the status to the concrete callable that carries the user forward.
+    # action_cmd is a human label; the case below dispatches to the real function.
+    local action_cmd=""
+    case "$status" in
+        paused|interrupted)                              action_cmd="loki resume" ;;
+        council_approved|council_force_approved|completion_promise_fulfilled)
+                                                         action_cmd="loki ship" ;;
+        max_iterations_reached|budget_exceeded)          action_cmd="loki resume" ;;
+        failed|max_retries_exceeded|policy_blocked|force_stopped)
+                                                         action_cmd="loki why" ;;
+        *)                                               action_cmd="loki status" ;;
+    esac
+
+    echo -e "${BOLD}Loki: next${NC}"
+    echo "  Last outcome : $status"
+    echo "  Next step    : $action_text"
+    echo "  Will run     : $action_cmd"
+    echo ""
+
+    # Honesty gate: only ACT on an interactive terminal with consent, or with
+    # --yes. --dry-run and non-TTY always print-only.
+    if [ "$dry_run" = true ]; then
+        echo "(dry-run: not running. Run '$action_cmd' yourself, or 'loki next --yes'.)"
+        return 0
+    fi
+    if [ "$assume_yes" != true ]; then
+        if [ ! -t 0 ] || [ ! -t 1 ]; then
+            echo "(non-interactive: not running. Run '$action_cmd', or 'loki next --yes'.)"
+            return 0
+        fi
+        local reply=""
+        printf "Run '%s' now? [y/N] " "$action_cmd"
+        read -r reply || reply=""
+        case "$reply" in
+            y|Y|yes|YES) : ;;
+            *) echo "Skipped. Run '$action_cmd' when ready."; return 0 ;;
+        esac
+    fi
+
+    # Dispatch to the real command. For budget/iteration caps, print the env-var
+    # guidance first (the resume alone will not lift the cap), then resume.
+    case "$status" in
+        max_iterations_reached)
+            echo "Note: raise the cap first if you want more iterations, e.g.:"
+            echo "  LOKI_MAX_ITERATIONS=<n> loki resume"
+            echo ""
+            ;;
+        budget_exceeded)
+            echo "Note: raise the budget first if you want to continue, e.g.:"
+            echo "  LOKI_BUDGET_LIMIT=<usd> loki resume"
+            echo ""
+            ;;
+    esac
+    case "$action_cmd" in
+        "loki resume")  cmd_resume ;;
+        "loki ship")    cmd_ship ;;
+        "loki why")     cmd_why ;;
+        *)              cmd_status ;;
+    esac
+    return $?
+}
+
+# loki ship -- the build is done, now get it out (review + PR advice in one flow).
+# Composes existing surfaces only: optionally opens the running app (--preview),
+# runs the SAME diff quality gates as cmd_review, and on a clean-enough result
+# prints the exact branch-aware PR command via the shared print_pr_advice (the
+# same advisory cmd_deploy uses). PRINT-ONLY for shipping: it NEVER pushes and
+# NEVER deploys; it prints (and clipboards, as the advisory already does) the
+# git push + PR command for YOU to run. If review finds HIGH/CRITICAL it stops
+# and points at the findings instead of advising a PR.
+cmd_ship() {
+    local do_preview=false
+    local review_args=()
+    # Tracks whether the caller passed an explicit scope flag (--staged, --since,
+    # ...). Passthrough flags like --yes/--severity do NOT set this, so they do
+    # not suppress the clean-loki-branch auto-scoping below.
+    local ship_explicit_scope=false
+    while [ $# -gt 0 ]; do
+        case "${1:-}" in
+            --help|-h|help)
+                echo -e "${BOLD}Loki Mode -- finish the build: review, then PR advice (print-only)${NC}"
+                echo ""
+                echo "Usage: loki ship [--preview] [--yes] [review options]"
+                echo ""
+                echo "Runs the natural finish line in one command:"
+                echo "  1. (with --preview) opens the app Loki built and started locally"
+                echo "  2. runs 'loki review' on your uncommitted/branch diff (the same"
+                echo "     quality gates)"
+                echo "  3. on a clean-enough result, PRINTS the exact branch-aware"
+                echo "     git push + pull-request command for YOU to run"
+                echo ""
+                echo "It is advisory only for shipping: it NEVER runs 'git push', NEVER"
+                echo "creates a PR, and NEVER deploys. You run the printed command."
+                echo "If review finds HIGH or CRITICAL findings it stops and points you"
+                echo "at the findings instead of advising a PR (exit code 1)."
+                echo ""
+                echo "Options:"
+                echo "  --preview    Open the running local app first (loki preview)"
+                echo "  --yes, -y    Pass through to review (skip its confirmation prompt)"
+                echo "  --help, -h   Show this help and exit"
+                echo ""
+                echo "Any other options are passed through to 'loki review'"
+                echo "(e.g. --staged, --since <commit>, --severity high)."
+                return 0
+                ;;
+            --preview) do_preview=true ;;
+            # Only a known set of NON-scope passthrough flags are exempt from
+            # "explicit scope". Everything else the caller passes -- an explicit
+            # scope flag (--staged/--since/...), a positional <file-or-dir>, or any
+            # other review flag that narrows WHAT is reviewed -- counts as explicit
+            # scope, so we do NOT override it with the clean-branch auto-scoping
+            # below. This is the safe default: passthrough-that-changes-scope must
+            # win over our auto-scope. The exempt list is only flags that never
+            # change scope: --yes/-y (skip prompt), --severity (threshold).
+            # (Without this, `loki ship somefile.py` on a clean loki branch would
+            # get --since base injected and review the whole range, not the file.)
+            --yes|-y|--severity=*)
+                review_args+=("$1") ;;
+            # --severity in its DOCUMENTED two-token form (`--severity high`) takes
+            # a VALUE in the next arg. Consume both here so the value does not fall
+            # to the catch-all and wrongly mark explicit scope (which would skip the
+            # clean-branch auto-scoping and re-introduce the empty-diff false-clean
+            # bug). --severity sets a threshold, not a scope, so neither token is
+            # explicit scope.
+            --severity)
+                review_args+=("$1")
+                if [ "$#" -ge 2 ] && [ "${2#-}" = "$2" ]; then
+                    review_args+=("$2"); shift
+                fi
+                ;;
+            *) review_args+=("$1"); ship_explicit_scope=true ;;
+        esac
+        shift
+    done
+
+    # 1. Optional preview of the running local app. Only when an app-runner state
+    #    file exists, so we never imply an app is running when it is not.
+    if [ "$do_preview" = true ]; then
+        local loki_dir="${LOKI_DIR:-.loki}"
+        if [ -f "$loki_dir/state/app-runner.json" ] || [ -f "$loki_dir/app-runner.json" ]; then
+            echo -e "${BOLD}Opening the running app...${NC}"
+            cmd_preview || true
+            echo ""
+        else
+            echo "(no running app detected; skipping preview. Start one with loki start.)"
+            echo ""
+        fi
+    fi
+
+    # 2. Run the SAME diff quality gates as cmd_review. Capture its documented
+    #    exit code (0 clean, 1 HIGH, 2 CRITICAL). set -e safe: capture via || rc=$?.
+    #
+    #    Scope correction: cmd_review defaults to the UNCOMMITTED diff, but run.sh
+    #    auto-commits the session's work to the loki/session-* branch, so by the
+    #    time `loki ship` runs the tree is usually CLEAN -- which would make review
+    #    see an empty diff and falsely report "clean" before advising a PR (the
+    #    safety gate would be a no-op exactly when it matters). When the caller
+    #    gave no explicit scope AND we are on a loki/* branch with a clean tree,
+    #    default the scope to the branch-vs-base RANGE (the work being shipped),
+    #    resolved the same way the PR advice below resolves it.
+    local _ship_dir="."
+    if [ "$ship_explicit_scope" = false ]; then
+        local _ship_head="" _ship_base="" _ship_dirty=""
+        _ship_head="$(git -C "$_ship_dir" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")"
+        # Untracked files (e.g. a gitignored .loki/) do not count as "dirty" --
+        # what matters is whether the shippable TRACKED work is already committed.
+        _ship_dirty="$(git -C "$_ship_dir" status --porcelain --untracked-files=no 2>/dev/null)"
+        case "$_ship_head" in
+            loki/*)
+                if [ -z "$_ship_dirty" ]; then
+                    if [ -s "$_ship_dir/.loki/state/base-branch.txt" ]; then
+                        _ship_base="$(head -n1 "$_ship_dir/.loki/state/base-branch.txt" 2>/dev/null || echo "")"
+                    fi
+                    if [ -z "$_ship_base" ]; then
+                        local _ship_oh=""
+                        _ship_oh="$(git -C "$_ship_dir" symbolic-ref refs/remotes/origin/HEAD 2>/dev/null || echo "")"
+                        [ -n "$_ship_oh" ] && _ship_base="${_ship_oh##*/}"
+                    fi
+                    if [ -n "$_ship_base" ] && git -C "$_ship_dir" rev-parse --verify --quiet "$_ship_base" >/dev/null 2>&1; then
+                        review_args+=("--since" "$_ship_base")
+                        echo -e "${DIM}Clean working tree on $_ship_head; reviewing the branch range vs $_ship_base.${NC}"
+                    fi
+                fi
+                ;;
+        esac
+    fi
+    echo -e "${BOLD}Running quality gates on the diff (loki review)...${NC}"
+    echo ""
+    local rc=0
+    cmd_review "${review_args[@]}" || rc=$?
+
+    if [ "$rc" -ge 1 ]; then
+        echo ""
+        if [ "$rc" -ge 2 ]; then
+            echo -e "${RED}Review found CRITICAL findings. Not advising a PR yet.${NC}" >&2
+        else
+            echo -e "${YELLOW}Review found HIGH findings. Not advising a PR yet.${NC}" >&2
+        fi
+        echo "Fix the findings above (or run 'loki review' for the full report), then 'loki ship' again." >&2
+        return 1
+    fi
+
+    # 3. Clean enough: print the branch-aware PR command (the SAME advisory
+    #    cmd_deploy uses). Derive base/head exactly as cmd_deploy does.
+    echo ""
+    echo -e "${GREEN}Review is clean (no HIGH or CRITICAL findings).${NC}"
+    echo ""
+    local dir="."
+    local head="" base=""
+    head="$(git -C "$dir" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")"
+    [ -n "$head" ] || head="HEAD"
+    case "$head" in
+        loki/*)
+            if [ -s "$dir/.loki/state/base-branch.txt" ]; then
+                base="$(head -n1 "$dir/.loki/state/base-branch.txt" 2>/dev/null || echo "")"
+            fi
+            ;;
+    esac
+    if [ -z "$base" ]; then
+        local origin_head=""
+        origin_head="$(git -C "$dir" symbolic-ref refs/remotes/origin/HEAD 2>/dev/null || echo "")"
+        if [ -n "$origin_head" ]; then
+            base="${origin_head##*/}"
+        fi
+    fi
+
+    if declare -F print_pr_advice >/dev/null 2>&1; then
+        if [ -n "$base" ]; then
+            print_pr_advice "$base" "$head" "$dir"
+        else
+            echo "Could not determine the PR base branch automatically; set it manually:"
+            print_pr_advice "manually-set-base" "$head" "$dir"
+        fi
+    else
+        echo "To open a pull request:"
+        echo "  git push -u origin ${head}"
+        echo "  Open a pull request for ${head} (set the base branch manually)."
+    fi
+    echo ""
+    echo -e "${DIM}Loki does not push or deploy for you; run the command above when ready.${NC}"
+    return 0
+}
+
 # loki why -- actionable failure/outcome diagnosis (B5).
 # Reads the already-captured run artifacts (no new state): the terminal run state
 # (.loki/<autonomy-state>.json: status, lastExitCode, iterationCount), the durable
@@ -3284,6 +3693,43 @@ cmd_status() {
         fi
     fi
 
+    # v7.82: surface the single most valuable, most shareable fact -- where the
+    # built app is running -- when the app runner reports a live app. Display-only
+    # read of .loki/app-runner/state.json (same shape build_completion_summary
+    # reads); silent when no app is running. The --json path (cmd_status_json) is
+    # untouched, so machine output stays byte-identical.
+    if [ -f "$LOKI_DIR/app-runner/state.json" ]; then
+        local app_url
+        app_url=$(_LOKI_APP_STATE="$LOKI_DIR/app-runner/state.json" python3 -c "
+import json, os
+try:
+    d = json.load(open(os.environ['_LOKI_APP_STATE']))
+    print(d.get('url', '') if d.get('status') == 'running' else '')
+except Exception:
+    print('')" 2>/dev/null)
+        if [ -n "$app_url" ]; then
+            echo ""
+            echo -e "${GREEN}App running:${NC} ${BOLD}${app_url}${NC}  ${DIM}- open it to try it${NC}"
+        fi
+    fi
+
+    # v7.82: completion-aware one-liner. When a finished run left a completion
+    # record, show its outcome and point at \`loki why\` for the full story. Reads
+    # the persisted completion.json (no recompute); silent when absent.
+    if [ -f "$LOKI_DIR/state/completion.json" ]; then
+        local last_outcome
+        last_outcome=$(_LOKI_CJ="$LOKI_DIR/state/completion.json" python3 -c "
+import json, os
+try:
+    d = json.load(open(os.environ['_LOKI_CJ']))
+    print(d.get('outcome', '') or '')
+except Exception:
+    print('')" 2>/dev/null)
+        if [ -n "$last_outcome" ]; then
+            echo -e "${DIM}Last run: ${last_outcome} - run 'loki why' for details${NC}"
+        fi
+    fi
+
     echo ""
     echo -e "${DIM}  Tip: loki analyze context show   - detailed token breakdown${NC}"
     echo -e "${DIM}  Tip: loki analyze code overview  - codebase intelligence${NC}"
@@ -4866,7 +5312,7 @@ cmd_welcome_terminal() {
     echo -e "  ${CYAN}Cross-project memory${NC}     Lessons compound, so agents stop repeating mistakes."
     echo -e "  ${CYAN}Provider-agnostic${NC}        Claude, Codex, Cline, or Aider. Your keys, your infra."
     echo ""
-    echo -e "  Quick start:  ${BOLD}loki start ./prd.md${NC}"
+    echo -e "  Quick start:  ${BOLD}loki quickstart${NC} (from your idea) or ${BOLD}loki start ./prd.md${NC} (from a spec)"
     echo -e "  Docs:         ${BOLD}https://www.autonomi.dev/docs${NC}"
     echo ""
     if _loki_welcome_analytics_on; then
@@ -9524,11 +9970,17 @@ cmd_doctor() {
         return 1
     elif [ "$warn_count" -gt 0 ]; then
         echo -e "${YELLOW}All required checks passed with some warnings.${NC}"
-        return 0
     else
         echo -e "${GREEN}All checks passed. System is ready for Loki Mode.${NC}"
-        return 0
     fi
+    # Setup verified (no required check failed): hand the user straight to a
+    # first build with a copy-paste command, so they never dead-end here. Gated
+    # on fail_count==0 above, so a failing setup is never told to build. The
+    # --json path returns long before this code, so machine output is untouched.
+    echo ""
+    echo "Next: loki quickstart (guided first build from your idea, no PRD needed)"
+    echo "      or loki demo (builds a sample todo app end to end) or loki start ./prd.md"
+    return 0
 }
 
 # JSON output for loki doctor --json
@@ -15750,6 +16202,9 @@ main() {
         why)
             cmd_why "$@"
             ;;
+        next)
+            cmd_next "$@"
+            ;;
         stats)
             # CLI consolidation (Phase A): 'stats' is a deprecated alias of
             # 'report session'. On the Bun route this arm is never reached
@@ -15773,6 +16228,9 @@ main() {
         deploy)
             cmd_deploy "$@"
             ;;
+        ship)
+            cmd_ship "$@"
+            ;;
         open)
             # CLI consolidation (Phase A): 'open' is a deprecated alias of 'preview'.
             _deprecated_alias open preview "$@"
@@ -23474,12 +23932,15 @@ _code_diff() {
 # Output shell completion scripts
 cmd_completions() {
     local shell="${1:-bash}"
+    # Consume the subcommand so the install arm can read an optional shell
+    # override as its own positional ($1). bash/zsh raw-output arms ignore $@.
+    shift 2>/dev/null || true
     local skill_dir
-    
+
     # Find the skill directory (where autonomy/loki is located)
     skill_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
     local completions_dir="$skill_dir/completions"
-    
+
     case "$shell" in
         bash)
             if [ -f "$completions_dir/loki.bash" ]; then
@@ -23497,24 +23958,77 @@ cmd_completions() {
                 exit 1
             fi
             ;;
+        install)
+            # One-command install: detect the current shell, append a single
+            # guarded line to the right rc file exactly once (idempotent via a
+            # sentinel comment), then tell the user how to activate it. This
+            # replaces the error-prone manual recipe with something that just
+            # works after one command.
+            local detected target_shell rc_file
+            detected="$(basename "${SHELL:-}" 2>/dev/null)"
+            # Allow an explicit override: loki completions install bash|zsh
+            target_shell="${1:-$detected}"
+            case "$target_shell" in
+                bash)
+                    rc_file="${HOME}/.bashrc"
+                    ;;
+                zsh)
+                    rc_file="${HOME}/.zshrc"
+                    ;;
+                *)
+                    echo -e "${RED}Could not detect a supported shell (got: ${target_shell:-unknown}).${NC}" >&2
+                    echo "Specify one explicitly: loki completions install bash | loki completions install zsh" >&2
+                    exit 1
+                    ;;
+            esac
+            local sentinel="# loki-mode completions"
+            if [ -f "$rc_file" ] && grep -qF "$sentinel" "$rc_file" 2>/dev/null; then
+                echo "Loki completions already installed in ${rc_file} (no change)."
+                echo "Activate now with: source ${rc_file}"
+                return 0
+            fi
+            # Append the sentinel plus a single eval line that re-loads the
+            # completion script at shell start. eval (not redirect) is the
+            # correct persistent form: it sources the script into the
+            # interactive shell each time the rc file runs.
+            {
+                printf '\n%s\n' "$sentinel"
+                printf '%s\n' "eval \"\$(loki completions ${target_shell})\""
+            } >> "$rc_file" || {
+                echo -e "${RED}Failed to write to ${rc_file}.${NC}" >&2
+                exit 1
+            }
+            echo "Installed Loki ${target_shell} completions into ${rc_file}."
+            echo "Activate now with: source ${rc_file}  (or restart your shell)"
+            return 0
+            ;;
         *)
             echo -e "${BOLD}Loki Shell Completions${NC}"
             echo ""
             echo "Output shell completion scripts for bash or zsh."
             echo ""
             echo "Usage: loki completions <shell>"
+            echo "       loki completions install [bash|zsh]"
             echo ""
             echo "Shells:"
-            echo "  bash    Bash completion script"
-            echo "  zsh     Zsh completion script"
+            echo "  bash       Bash completion script"
+            echo "  zsh        Zsh completion script"
+            echo "  install    Auto-install completions into your shell rc file"
             echo ""
             echo "Installation:"
             echo ""
-            echo "Bash:"
-            echo "  eval \"\$(loki completions bash)\" >> ~/.bashrc"
+            echo "  One command (recommended):"
+            echo "    loki completions install"
+            echo ""
+            echo "  Manual (persistent), Bash:"
+            echo "    echo 'eval \"\$(loki completions bash)\"' >> ~/.bashrc"
+            echo "  Manual (persistent), Zsh:"
+            echo "    echo 'eval \"\$(loki completions zsh)\"' >> ~/.zshrc"
             echo ""
-            echo "Zsh:"
-            echo "  eval \"\$(loki completions zsh)\" >> ~/.zshrc"
+            echo "  Session only (current shell), Bash:"
+            echo "    eval \"\$(loki completions bash)\""
+            echo "  Session only (current shell), Zsh:"
+            echo "    eval \"\$(loki completions zsh)\""
             echo ""
             exit 1
             ;;

package/autonomy/run.sh

@@ -2674,34 +2674,35 @@ except Exception:
     fi
 
     # ---- Durable human-readable file: .loki/COMPLETION.txt --------------------
+    # Presentation-only receipt: a single fixed-width label column, the live-app
+    # URL elevated right under the outcome headline, and a consistent rule line.
+    # Stays pure ASCII (no emoji, no dashes, no color codes) so it pastes cleanly
+    # into a PR description or a chat. Same facts and values as before.
     {
         echo "Loki Mode run summary"
         echo "====================="
         echo ""
-        echo "Outcome:   $outcome_label"
-        echo "Branch:    $branch"
-        echo "Files changed: $files_changed (+$insertions / -$deletions)"
-        echo "Finished:  $ts"
-        echo ""
-        if [ -n "$delegate_branch" ]; then
-            echo "Delegate branch: $delegate_branch"
-        fi
-        if [ -n "$pr_url" ]; then
-            echo "Pull request: $pr_url"
-        elif [ "$outcome" = "complete" ]; then
-            echo "Pull request: not opened (set LOKI_DELEGATE_PR=1 to open one)"
-        fi
-        echo ""
+        printf '%-14s %s\n' "Outcome:" "$outcome_label"
         if [ -n "$live_app_url" ]; then
             # Compute the dashboard scheme the same way start_dashboard does
             # (url_scheme is local to that function, not visible here).
             local _dash_scheme="http"
             [ -n "${LOKI_TLS_CERT:-}" ] && [ -n "${LOKI_TLS_KEY:-}" ] && _dash_scheme="https"
-            echo "Your app is live at: $live_app_url  (served locally on this machine)"
-            echo "  Dashboard: ${_dash_scheme}://127.0.0.1:${DASHBOARD_PORT:-57374}/  (App Runner -> Live App)"
-            echo ""
+            printf '%-14s %s\n' "Live app:" "$live_app_url  (served locally on this machine)"
+            printf '%-14s %s\n' "Dashboard:" "${_dash_scheme}://127.0.0.1:${DASHBOARD_PORT:-57374}/  (App Runner -> Live App)"
+        fi
+        printf '%-14s %s\n' "Branch:" "$branch"
+        printf '%-14s %s\n' "Files:" "$files_changed (+$insertions / -$deletions)"
+        printf '%-14s %s\n' "Finished:" "$ts"
+        if [ -n "$delegate_branch" ]; then
+            printf '%-14s %s\n' "Delegate:" "$delegate_branch"
+        fi
+        if [ -n "$pr_url" ]; then
+            printf '%-14s %s\n' "Pull request:" "$pr_url"
+        elif [ "$outcome" = "complete" ]; then
+            printf '%-14s %s\n' "Pull request:" "not opened (set LOKI_DELEGATE_PR=1 to open one)"
         fi
-        echo "Tasks: pending=$pending in_progress=$in_progress completed=$completed failed=$failed"
+        printf '%-14s %s\n' "Tasks:" "pending=$pending in_progress=$in_progress completed=$completed failed=$failed"
         echo ""
         if [ -n "$evidence_inconclusive_line" ]; then
             echo "$evidence_inconclusive_line"
@@ -2901,10 +2902,130 @@ emit_completion_summary() {
     local outcome="${1:-complete}"
     local urgency="${2:-normal}"
     build_completion_summary "$outcome"
+    # Render the screenshot-worthy completion card inline on a foreground TTY run,
+    # AFTER the durable files are written. The card re-reads the persisted
+    # completion.json (never recomputes) so it can never diverge from the file.
+    print_completion_card
     send_notification "${_LOKI_SUMMARY_TITLE:-Run finished}" "${_LOKI_SUMMARY_BODY:-}" "$urgency"
     return 0
 }
 
+#===============================================================================
+# print_completion_card  (visible-delight completion card)
+#
+# Display-only. Renders a boxed summary card to the interactive TTY at the close
+# of a foreground run: outcome, branch, files changed (+ins/-del), the live-app
+# URL with a "try it" line when an app is running, the copy-pasteable review
+# command, and the recorded-assumptions count. This is the single most
+# screenshot-worthy moment of a run, which was previously only written to a file.
+#
+# It reads ONLY from the already-persisted .loki/state/completion.json (written
+# by build_completion_summary just before this is called) and the app-runner
+# state, so the card and the durable file are guaranteed identical. Nothing is
+# computed or written here.
+#
+# Gate (same shape as the HUD at the colors block): interactive stdout, not
+# --bg, and not opted out via LOKI_COMPLETION_CARD=0. Off-TTY / --bg / --json
+# paths emit nothing, so machine output stays byte-identical. Wrapped so any
+# internal failure still returns 0 and can never abort the completion path.
+#===============================================================================
+print_completion_card() {
+    # Gate first: emit nothing unless interactive TTY, not background, not opted out.
+    if ! { [ -t 1 ] && [ "${BACKGROUND_MODE:-false}" != "true" ] && [ "${LOKI_COMPLETION_CARD:-1}" != "0" ]; }; then
+        return 0
+    fi
+
+    local loki_dir="${TARGET_DIR:-.}/.loki"
+    local _cj="$loki_dir/state/completion.json"
+    [ -f "$_cj" ] || return 0
+
+    # Pull the fields we render straight from the persisted record. The python3
+    # call emits one field per line in a fixed order; we read them line by line
+    # so empty fields (e.g. no pr_url) keep their positions (a single delimiter
+    # split would collapse adjacent empties). Any failure leaves the card
+    # unrendered. Trailing-newline guard: NUL-free, fields are single-line.
+    local _fields
+    _fields="$(python3 -c "
+import json,sys
+try:
+    d=json.load(open(sys.argv[1]))
+except Exception:
+    sys.exit(0)
+def g(k):
+    v=d.get(k,'')
+    return '' if v is None else str(v).replace('\n',' ')
+for k in ['outcome','branch','files_changed','insertions','deletions',
+          'review_cmd','pr_url','assumptions_total','assumptions_high']:
+    print(g(k))
+" "$_cj" 2>/dev/null)" || return 0
+    [ -z "$_fields" ] && return 0
+
+    local _outcome _branch _files _ins _del _review _pr _atotal _ahigh
+    {
+        IFS= read -r _outcome
+        IFS= read -r _branch
+        IFS= read -r _files
+        IFS= read -r _ins
+        IFS= read -r _del
+        IFS= read -r _review
+        IFS= read -r _pr
+        IFS= read -r _atotal
+        IFS= read -r _ahigh
+    } <<EOF
+$_fields
+EOF
+
+    # Human outcome label (mirror build_completion_summary's mapping).
+    local _label
+    case "$_outcome" in
+        complete)        _label="Completed" ;;
+        max_iterations)  _label="Max iterations" ;;
+        stopped)         _label="Stopped" ;;
+        force_stopped)   _label="Stopped (not verified-complete)" ;;
+        failed)          _label="Failed" ;;
+        intervention)    _label="Needs input" ;;
+        *)               _label="$_outcome" ;;
+    esac
+
+    # Live app URL (best-effort), same read as build_completion_summary.
+    local _url="" _app_state="$loki_dir/app-runner/state.json"
+    if [ -f "$_app_state" ]; then
+        _url="$(python3 -c "import json,sys
+try:
+    d=json.load(open(sys.argv[1]))
+    print(d.get('url','') if d.get('status')=='running' else '')
+except Exception:
+    print('')" "$_app_state" 2>/dev/null)" || _url=""
+    fi
+
+    # Box width matches log_header (66 inner columns). Render lines that fit;
+    # this is decoration, so over-wide content is simply not boxed-truncated
+    # (the durable file carries the full text).
+    echo ""
+    echo -e "${GREEN}+================================================================+${NC}"
+    echo -e "${GREEN}|${NC} ${BOLD}Loki Mode: ${_label}${NC}"
+    echo -e "${GREEN}|${NC}"
+    if [ -n "$_url" ]; then
+        echo -e "${GREEN}|${NC} ${BOLD}${CYAN}Your app is live at ${_url}${NC}  ${DIM}- open it to try it${NC}"
+        echo -e "${GREEN}|${NC}"
+    fi
+    echo -e "${GREEN}|${NC} Branch: ${BOLD}${_branch}${NC}"
+    echo -e "${GREEN}|${NC} Files:  ${BOLD}${_files}${NC} changed  ${GREEN}+${_ins}${NC} / ${RED}-${_del}${NC}"
+    case "$_atotal" in ''|0) : ;; *)
+        echo -e "${GREEN}|${NC} Spec assumptions recorded: ${BOLD}${_atotal}${NC} (${_ahigh} high) ${DIM}see .loki/assumptions/ledger.md${NC}"
+        ;;
+    esac
+    if [ -n "$_pr" ]; then
+        echo -e "${GREEN}|${NC} Pull request: ${_pr}"
+    fi
+    echo -e "${GREEN}|${NC}"
+    echo -e "${GREEN}|${NC} ${DIM}Review the work:${NC}"
+    echo -e "${GREEN}|${NC}   ${_review}"
+    echo -e "${GREEN}+================================================================+${NC}"
+    echo ""
+    return 0
+}
+
 #===============================================================================
 # on_run_complete  (Slice 3: opt-in local git output on success)
 #
@@ -16593,6 +16714,35 @@ main() {
         exit 1
     fi
 
+    # v7.82: one-line "Building:" headline under the start banner so the opening
+    # frame reflects the user's own intent (their PRD / brief / this codebase),
+    # not a generic banner. Display-only, derived from already-resolved values:
+    # PRD basename for a file, the recorded brief text for a brief run, or fixed
+    # text for a no-arg in-repo run. Truncated to one tidy line. Gated to an
+    # interactive TTY, not --bg, and opt-out via LOKI_START_HEADLINE=0, so the
+    # off-TTY / background path is byte-identical (no output). Best-effort; a
+    # failure here must never affect parsing or the build flow.
+    if [ -t 1 ] && [ "${BACKGROUND_MODE:-false}" != "true" ] && [ "${LOKI_START_HEADLINE:-1}" != "0" ]; then
+        local _headline=""
+        if [ -n "$PRD_PATH" ]; then
+            _headline="$(basename "$PRD_PATH" 2>/dev/null || echo "$PRD_PATH")"
+        elif [ -f ".loki/state/brief.txt" ]; then
+            # Recorded one-line brief (written by cmd_start). Collapse to a single
+            # line and truncate to ~60 chars so the banner stays clean.
+            local _brief
+            _brief="$(tr '\n' ' ' < .loki/state/brief.txt 2>/dev/null | sed 's/  */ /g; s/^ //; s/ $//')"
+            if [ -n "$_brief" ]; then
+                if [ "${#_brief}" -gt 60 ]; then
+                    _brief="${_brief:0:57}..."
+                fi
+                _headline="\"$_brief\""
+            fi
+        fi
+        [ -z "$_headline" ] && _headline="analyzing this codebase"
+        echo -e "  ${BOLD}${CYAN}Building: ${_headline}${NC}"
+        echo ""
+    fi
+
     # Handle background mode
     if [ "$BACKGROUND_MODE" = "true" ]; then
         # Initialize .loki directory first

package/completions/_loki

@@ -11,7 +11,7 @@ function _loki {
     case $state in
         (args)
             case $line[1] in
-                start)
+                start|quick)
                     _loki_start
                     ;;
                 council)
@@ -101,7 +101,7 @@ function _loki {
                         '1:subcommand:(list show open share)'
                     ;;
                 completions)
-                    _arguments '1:shell:(bash zsh)'
+                    _arguments '1:shell:(bash zsh install)'
                     ;;
                 monitor)
                     _directories
@@ -122,6 +122,7 @@ function _loki_commands {
     commands=(
         'start:Start Loki Mode'
         'quick:Quick single-task mode'
+        'quickstart:Guided first build from your idea'
         'monitor:Monitor Docker Compose services with auto-fix'
         'demo:Interactive 60-second demo'
         'init:Interactive PRD builder'
@@ -129,11 +130,16 @@ function _loki_commands {
         'pause:Pause execution'
         'resume:Resume execution'
         'status:Show status'
+        'next:Run the right next step for the current build'
+        'ship:Finish the build (gates + PR advice) in one command'
+        'why:Explain why the last run did what it did'
         'dashboard:Dashboard commands'
+        'web:Start the web app surface'
         'logs:View session logs'
         'serve:Start API server'
         'api:API server commands'
         'sandbox:Docker sandbox commands'
+        'docker:Run Loki in a Docker container'
         'notify:Notification commands'
         'import:Import GitHub issues'
         'issue:GitHub issue commands'
@@ -153,6 +159,8 @@ function _loki_commands {
         'metrics:Session productivity report'
         'share:Share session report as GitHub Gist'
         'proof:Inspect/share proof-of-run artifacts'
+        'preview:Preview the locally-running app'
+        'deploy:Deploy the built product (CI/CD-aware)'
         'context:Context window management'
         'ctx:Context window management (alias)'
         'code:Codebase intelligence'
@@ -234,7 +242,17 @@ function _loki_start {
         '-y[Skip confirmation prompts]' \
         '--budget[Cost budget limit in USD]:amount:' \
         '--max-iterations[Max iterations]:number:' \
-        '*:PRD File:_files'
+        '*:spec file:_loki_spec_files'
+}
+
+# Bias spec completion toward the file shapes Loki accepts (.md/.json/.txt/
+# .yaml/.yml), while still offering directories so the user can navigate into a
+# subfolder. Mirrors the bash completion. Makes the most-common command
+# tab-driven and typo-proof, cutting "PRD file not found" mistakes.
+function _loki_spec_files {
+    _alternative \
+        'specs:spec file:_files -g "*.(md|json|txt|yaml|yml)"' \
+        'dirs:directory:_files -/'
 }
 
 function _loki_council {

package/completions/loki.bash

@@ -5,7 +5,7 @@ _loki_completion() {
     _init_completion || return
 
     # Main subcommands (must match autonomy/loki main case statement)
-    local main_commands="start quick monitor demo init stop pause resume status dashboard web serve api sandbox notify import github issue config provider reset memory compound checkpoint council dogfood projects enterprise secrets doctor watchdog audit metrics syslog onboard share proof explain plan report cost kpis stats test ci watch telemetry agent context ctx code run export review optimize heal modernize migrate cluster worktree wt trigger failover remote deploy docker mcp magic assets analyze compliance crash open otel preview quickstart rc rollback self-update sentrux setup-skill spec state template trust trust-metrics ultracode update verify voice why wiki bench cleanup logs grill docs cp version completions help"
+    local main_commands="start quick monitor demo init stop pause resume status next ship dashboard web serve api sandbox notify import github issue config provider reset memory compound checkpoint council dogfood projects enterprise secrets doctor watchdog audit metrics syslog onboard share proof explain plan report cost kpis stats test ci watch telemetry agent context ctx code run export review optimize heal modernize migrate cluster worktree wt trigger failover remote deploy docker mcp magic assets analyze compliance crash open otel preview quickstart rc rollback self-update sentrux setup-skill spec state template trust trust-metrics ultracode update verify voice why wiki bench cleanup logs grill docs cp version completions help"
 
     # 1. If we are on the first argument (subcommand)
     if [[ $cword -eq 1 ]]; then
@@ -15,7 +15,7 @@ _loki_completion() {
 
     # 2. Handle subcommands and their specific flags/args
     case "${words[1]}" in
-        start)
+        start|quick)
             # If the previous word was --provider, show provider names
             if [[ "$prev" == "--provider" ]]; then
                 # Active providers (loki rejects gemini since v7.5.18; cline/aider
@@ -32,8 +32,23 @@ _loki_completion() {
                 return 0
             fi
 
-            # Otherwise, default to file completion (for PRD files)
-            COMPREPLY=( $(compgen -f -- "$cur") )
+            # Bias toward the spec-shaped files Loki actually accepts
+            # (.md/.json/.txt/.yaml/.yml), plus directories so the user can still
+            # navigate into a subfolder. This makes the most-common command
+            # tab-driven and typo-proof, cutting "PRD file not found" mistakes.
+            # If the spec-filtered set is empty (no specs here), fall back to
+            # generic file completion so nothing the user could type is lost.
+            local _specs _dirs _eg_was_set=0
+            shopt -q extglob && _eg_was_set=1
+            shopt -s extglob
+            _specs=$(compgen -f -X '!*.@(md|json|txt|yaml|yml)' -- "$cur")
+            [[ "$_eg_was_set" -eq 0 ]] && shopt -u extglob
+            _dirs=$(compgen -d -- "$cur")
+            if [[ -n "$_specs" || -n "$_dirs" ]]; then
+                COMPREPLY=( $_specs $_dirs )
+            else
+                COMPREPLY=( $(compgen -f -- "$cur") )
+            fi
             ;;
 
         council)
@@ -198,7 +213,7 @@ _loki_completion() {
             ;;
 
         completions)
-            COMPREPLY=( $(compgen -W "bash zsh" -- "$cur") )
+            COMPREPLY=( $(compgen -W "bash zsh install" -- "$cur") )
             ;;
 
         context|ctx)

package/dashboard/__init__.py

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

package/docs/INSTALLATION.md

@@ -2,7 +2,7 @@
 
 The flagship product of [Autonomi](https://www.autonomi.dev/). Loki Mode is a spec-driven autonomous builder with a built-in trust layer that takes any spec to a deployed product and verifies completion with evidence (quality gates plus a completion council), not just a "done" claim. Complete installation instructions for all platforms and use cases.
 
-**Version:** v7.82.0
+**Version:** v7.83.1
 
 ---
 
@@ -395,7 +395,7 @@ provider works inside the container. Provide auth with your Anthropic API key:
 # Run Loki Mode in Docker (Claude provider, API-key auth)
 docker run --rm -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
   -v $(pwd):/workspace -w /workspace \
-  asklokesh/loki-mode:7.82.0 start ./my-spec.md
+  asklokesh/loki-mode:7.83.1 start ./my-spec.md
 ```
 
 ##### docker compose + .env (no host install)

package/loki-ts/dist/loki.js

@@ -1,5 +1,5 @@
 // @bun
-var QQ=Object.defineProperty;var ZQ=($)=>$;function zQ($,Q){this[$]=ZQ.bind(null,Q)}var b=($,Q)=>{for(var Z in Q)QQ($,Z,{get:Q[Z],enumerable:!0,configurable:!0,set:zQ.bind(Q,Z)})};var L=($,Q)=>()=>($&&(Q=$($=0)),Q);var q$=import.meta.require;var h1={};b(h1,{lokiDir:()=>P,homeLokiDir:()=>i$,findRepoRootForVersion:()=>t$,REPO_ROOT:()=>g});import{resolve as a,dirname as r$}from"path";import{fileURLToPath as XQ}from"url";import{existsSync as R$}from"fs";import{homedir as KQ}from"os";function qQ(){let $=b1;for(let Q=0;Q<6;Q++){if(R$(a($,"VERSION"))&&R$(a($,"autonomy/run.sh")))return $;let Z=r$($);if(Z===$)break;$=Z}return a(b1,"..","..","..")}function t$($){let Q=$;for(let Z=0;Z<6;Z++){if(R$(a(Q,"VERSION"))&&R$(a(Q,"autonomy/run.sh")))return Q;let z=r$(Q);if(z===Q)break;Q=z}return a($,"..","..","..")}function P(){return process.env.LOKI_DIR??a(process.cwd(),".loki")}function i$(){return a(KQ(),".loki")}var b1,g;var C=L(()=>{b1=r$(XQ(import.meta.url));g=qQ()});import{readFileSync as VQ}from"fs";import{resolve as JQ,dirname as UQ}from"path";import{fileURLToPath as WQ}from"url";function E$(){if(Q$!==null)return Q$;let $="7.82.0";if(typeof $==="string"&&$.length>0)return Q$=$,Q$;try{let Q=UQ(WQ(import.meta.url)),Z=t$(Q);Q$=VQ(JQ(Z,"VERSION"),"utf-8").trim()}catch{Q$="unknown"}return Q$}var Q$=null;var e$=L(()=>{C()});var g1={};b(g1,{runOrThrow:()=>HQ,run:()=>F,readStreamCapped:()=>m1,commandVersion:()=>BQ,commandExists:()=>f,ShellError:()=>$1,MAX_STDOUT_BYTES:()=>v1});async function m1($,Q=v1){let Z=$.getReader(),z=new TextDecoder,X="",q=0;try{while(q<Q){let{done:K,value:U}=await Z.read();if(K)break;if(!U)continue;if(q+=U.byteLength,q>Q){let J=U.byteLength-(q-Q);X+=z.decode(U.subarray(0,J),{stream:!0});break}X+=z.decode(U,{stream:!0})}X+=z.decode()}finally{try{await Z.cancel()}catch{}Z.releaseLock()}return X}async function F($,Q={}){let Z=Bun.spawn({cmd:[...$],stdout:"pipe",stderr:"pipe",env:Q.env?{...process.env,...Q.env}:process.env,cwd:Q.cwd}),z,X;if(Q.timeoutMs&&Q.timeoutMs>0)z=setTimeout(()=>{try{Z.kill("SIGTERM")}catch{}X=setTimeout(()=>{try{Z.kill("SIGKILL")}catch{}},2000)},Q.timeoutMs);try{let[q,K,U]=await Promise.all([m1(Z.stdout),new Response(Z.stderr).text(),Z.exited]);return{stdout:q,stderr:K,exitCode:U}}finally{if(z)clearTimeout(z);if(X)clearTimeout(X)}}async function HQ($,Q={}){let Z=await F($,Q);if(Z.exitCode!==0)throw new $1(`command failed (${Z.exitCode}): ${$.join(" ")}`,Z.exitCode,Z.stdout,Z.stderr);return Z}async function f($){let Q=GQ($),Z=await F(["sh","-c",`command -v ${Q}`],{timeoutMs:5000});if(Z.exitCode===0)return Z.stdout.trim()||null;return null}function GQ($){if(!/^[A-Za-z0-9._/-]+$/.test($))throw Error(`refused to shell-escape suspect token: ${$}`);return $}async function BQ($,Q="--version"){if(!await f($))return null;let z=await F([$,Q],{timeoutMs:5000});if(z.exitCode!==0)return null;return((z.stdout||z.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var v1=16777216,$1;var d=L(()=>{$1=class $1 extends Error{message;exitCode;stdout;stderr;constructor($,Q,Z,z){super($);this.message=$;this.exitCode=Q;this.stdout=Z;this.stderr=z;this.name="ShellError"}}});function s($){return YQ?"":$}var YQ,O,S,_,_Z,I,k,h,V;var c=L(()=>{YQ=(process.env.NO_COLOR??"").length>0;O=s("\x1B[0;31m"),S=s("\x1B[0;32m"),_=s("\x1B[1;33m"),_Z=s("\x1B[0;34m"),I=s("\x1B[0;36m"),k=s("\x1B[1m"),h=s("\x1B[2m"),V=s("\x1B[0m")});import{existsSync as jQ}from"fs";async function Z$(){if(Y$!==void 0)return Y$;let $="/opt/homebrew/bin/python3.12";if(jQ($))return Y$=$,$;let Q=await f("python3.12");if(Q)return Y$=Q,Q;let Z=await f("python3");return Y$=Z,Z}async function z$($,Q={}){let Z=await Z$();if(!Z)return{stdout:"",stderr:"python3 not found",exitCode:127};return F([Z,"-c",$],Q)}var Y$;var V$=L(()=>{d()});var X0={};b(X0,{runStatus:()=>oQ});import{existsSync as y,readFileSync as U$,readdirSync as r1,statSync as t1}from"fs";import{resolve as D,basename as vQ}from"path";import{homedir as mQ}from"os";function i1($){let Q=Math.trunc($);if(Q>=1e6)return`${(Math.trunc(Q/1e6*10)/10).toFixed(1)}M`;if(Q>=1000)return`${(Math.trunc(Q/1000*10)/10).toFixed(1)}K`;return String(Q)}function e1($,Q,Z){if(Q===0)return null;let z=Math.trunc($*100/Q),X=Math.trunc($*N$/Q);if(X>N$)X=N$;let q=N$-X,K=S;if(z>=80)K=O;else if(z>=50)K=_;let U="=".repeat(Math.max(0,X))+" ".repeat(Math.max(0,q)),J=i1($),W=i1(Q);return`  ${k}${Z}${V} ${K}[${U}]${V} ${z}% (${J} / ${W})`}async function fQ(){if(await f("jq"))return!0;return process.stdout.write(`${O}Error: jq is required but not installed.${V}
+var QQ=Object.defineProperty;var ZQ=($)=>$;function zQ($,Q){this[$]=ZQ.bind(null,Q)}var b=($,Q)=>{for(var Z in Q)QQ($,Z,{get:Q[Z],enumerable:!0,configurable:!0,set:zQ.bind(Q,Z)})};var L=($,Q)=>()=>($&&(Q=$($=0)),Q);var q$=import.meta.require;var h1={};b(h1,{lokiDir:()=>P,homeLokiDir:()=>i$,findRepoRootForVersion:()=>t$,REPO_ROOT:()=>g});import{resolve as a,dirname as r$}from"path";import{fileURLToPath as XQ}from"url";import{existsSync as R$}from"fs";import{homedir as KQ}from"os";function qQ(){let $=b1;for(let Q=0;Q<6;Q++){if(R$(a($,"VERSION"))&&R$(a($,"autonomy/run.sh")))return $;let Z=r$($);if(Z===$)break;$=Z}return a(b1,"..","..","..")}function t$($){let Q=$;for(let Z=0;Z<6;Z++){if(R$(a(Q,"VERSION"))&&R$(a(Q,"autonomy/run.sh")))return Q;let z=r$(Q);if(z===Q)break;Q=z}return a($,"..","..","..")}function P(){return process.env.LOKI_DIR??a(process.cwd(),".loki")}function i$(){return a(KQ(),".loki")}var b1,g;var C=L(()=>{b1=r$(XQ(import.meta.url));g=qQ()});import{readFileSync as VQ}from"fs";import{resolve as JQ,dirname as UQ}from"path";import{fileURLToPath as WQ}from"url";function E$(){if(Q$!==null)return Q$;let $="7.83.1";if(typeof $==="string"&&$.length>0)return Q$=$,Q$;try{let Q=UQ(WQ(import.meta.url)),Z=t$(Q);Q$=VQ(JQ(Z,"VERSION"),"utf-8").trim()}catch{Q$="unknown"}return Q$}var Q$=null;var e$=L(()=>{C()});var g1={};b(g1,{runOrThrow:()=>HQ,run:()=>F,readStreamCapped:()=>m1,commandVersion:()=>BQ,commandExists:()=>f,ShellError:()=>$1,MAX_STDOUT_BYTES:()=>v1});async function m1($,Q=v1){let Z=$.getReader(),z=new TextDecoder,X="",q=0;try{while(q<Q){let{done:K,value:U}=await Z.read();if(K)break;if(!U)continue;if(q+=U.byteLength,q>Q){let J=U.byteLength-(q-Q);X+=z.decode(U.subarray(0,J),{stream:!0});break}X+=z.decode(U,{stream:!0})}X+=z.decode()}finally{try{await Z.cancel()}catch{}Z.releaseLock()}return X}async function F($,Q={}){let Z=Bun.spawn({cmd:[...$],stdout:"pipe",stderr:"pipe",env:Q.env?{...process.env,...Q.env}:process.env,cwd:Q.cwd}),z,X;if(Q.timeoutMs&&Q.timeoutMs>0)z=setTimeout(()=>{try{Z.kill("SIGTERM")}catch{}X=setTimeout(()=>{try{Z.kill("SIGKILL")}catch{}},2000)},Q.timeoutMs);try{let[q,K,U]=await Promise.all([m1(Z.stdout),new Response(Z.stderr).text(),Z.exited]);return{stdout:q,stderr:K,exitCode:U}}finally{if(z)clearTimeout(z);if(X)clearTimeout(X)}}async function HQ($,Q={}){let Z=await F($,Q);if(Z.exitCode!==0)throw new $1(`command failed (${Z.exitCode}): ${$.join(" ")}`,Z.exitCode,Z.stdout,Z.stderr);return Z}async function f($){let Q=GQ($),Z=await F(["sh","-c",`command -v ${Q}`],{timeoutMs:5000});if(Z.exitCode===0)return Z.stdout.trim()||null;return null}function GQ($){if(!/^[A-Za-z0-9._/-]+$/.test($))throw Error(`refused to shell-escape suspect token: ${$}`);return $}async function BQ($,Q="--version"){if(!await f($))return null;let z=await F([$,Q],{timeoutMs:5000});if(z.exitCode!==0)return null;return((z.stdout||z.stderr).split(/\r?\n/)[0]?.trim()??"")||null}var v1=16777216,$1;var d=L(()=>{$1=class $1 extends Error{message;exitCode;stdout;stderr;constructor($,Q,Z,z){super($);this.message=$;this.exitCode=Q;this.stdout=Z;this.stderr=z;this.name="ShellError"}}});function s($){return YQ?"":$}var YQ,O,S,_,_Z,I,k,h,V;var c=L(()=>{YQ=(process.env.NO_COLOR??"").length>0;O=s("\x1B[0;31m"),S=s("\x1B[0;32m"),_=s("\x1B[1;33m"),_Z=s("\x1B[0;34m"),I=s("\x1B[0;36m"),k=s("\x1B[1m"),h=s("\x1B[2m"),V=s("\x1B[0m")});import{existsSync as jQ}from"fs";async function Z$(){if(Y$!==void 0)return Y$;let $="/opt/homebrew/bin/python3.12";if(jQ($))return Y$=$,$;let Q=await f("python3.12");if(Q)return Y$=Q,Q;let Z=await f("python3");return Y$=Z,Z}async function z$($,Q={}){let Z=await Z$();if(!Z)return{stdout:"",stderr:"python3 not found",exitCode:127};return F([Z,"-c",$],Q)}var Y$;var V$=L(()=>{d()});var X0={};b(X0,{runStatus:()=>oQ});import{existsSync as y,readFileSync as U$,readdirSync as r1,statSync as t1}from"fs";import{resolve as D,basename as vQ}from"path";import{homedir as mQ}from"os";function i1($){let Q=Math.trunc($);if(Q>=1e6)return`${(Math.trunc(Q/1e6*10)/10).toFixed(1)}M`;if(Q>=1000)return`${(Math.trunc(Q/1000*10)/10).toFixed(1)}K`;return String(Q)}function e1($,Q,Z){if(Q===0)return null;let z=Math.trunc($*100/Q),X=Math.trunc($*N$/Q);if(X>N$)X=N$;let q=N$-X,K=S;if(z>=80)K=O;else if(z>=50)K=_;let U="=".repeat(Math.max(0,X))+" ".repeat(Math.max(0,q)),J=i1($),W=i1(Q);return`  ${k}${Z}${V} ${K}[${U}]${V} ${z}% (${J} / ${W})`}async function fQ(){if(await f("jq"))return!0;return process.stdout.write(`${O}Error: jq is required but not installed.${V}
 `),process.stdout.write(`Install with:
 `),process.stdout.write(`  brew install jq    (macOS)
 `),process.stdout.write(`  apt install jq     (Debian/Ubuntu)
@@ -410,8 +410,11 @@ Start a session with: loki start <prd>`}}let X=tQ(z);return{exitCode:0,stdout:Q?
 
 `),$.fail>0)return process.stdout.write(`${O}Some required prerequisites are missing.${V}
 `),process.stdout.write(`Install missing dependencies and run 'loki doctor' again.
-`),1;if($.warn>0)return process.stdout.write(`${_}All required checks passed with some warnings.${V}
-`),0;return process.stdout.write(`${S}All checks passed. System is ready for Loki Mode.${V}
+`),1;if($.warn>0)process.stdout.write(`${_}All required checks passed with some warnings.${V}
+`);else process.stdout.write(`${S}All checks passed. System is ready for Loki Mode.${V}
+`);return process.stdout.write(`
+`),process.stdout.write(`Next: loki quickstart (guided first build from your idea, no PRD needed)
+`),process.stdout.write(`      or loki demo (builds a sample todo app end to end) or loki start ./prd.md
 `),0}async function Y3($){let Q=!1;for(let Z of $)if(Z==="--json")Q=!0;else if(Z==="--help"||Z==="-h")return G3(),0;else return process.stderr.write(`${O}Unknown option: ${Z}${V}
 `),process.stderr.write(`Usage: loki doctor [--json]
 `),1;if(Q){let Z=await _0();return process.stdout.write(JSON.stringify(Z,null,2)+`
@@ -793,4 +796,4 @@ Set LOKI_LEGACY_BASH=1 to force the bash CLI for every command.
 `),2}default:return process.stderr.write(`Unknown command: ${Q}
 `),process.stderr.write($Q),2}}s1();process.on("SIGINT",()=>process.exit(130));process.on("SIGTERM",()=>process.exit(143));var qZ=await KZ(Bun.argv.slice(2));process.exit(qZ);
 
-//# debugId=3E8A7AD89D7DCCD164756E2164756E21
+//# debugId=8AD63677BE89399E64756E2164756E21

package/mcp/__init__.py

@@ -57,4 +57,4 @@ try:
 except ImportError:
     __all__ = ['mcp']
 
-__version__ = '7.82.0'
+__version__ = '7.83.1'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "loki-mode",
   "mcpName": "io.github.asklokesh/loki-mode",
-  "version": "7.82.0",
+  "version": "7.83.1",
   "description": "Loki Mode by Autonomi. Autonomous spec-to-product system: takes a PRD, GitHub issue, OpenAPI/JSON/YAML, or one-line brief to a deployed app via the RARV-C closure loop with 8 quality gates. Provider-agnostic (Claude Code, OpenAI Codex, Cline, Aider).",
   "keywords": [
     "agent",

package/plugins/loki-mode/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "loki-mode",
   "displayName": "Loki Mode",
-  "version": "7.82.0",
+  "version": "7.83.1",
   "description": "Autonomous spec-to-product build system with a built-in trust layer (RARV-C closure loop, 8 quality gates, completion council). Ships Loki's spec-hardening, drift-detection, and deterministic PR verification commands plus the Loki MCP server.",
   "author": {
     "name": "Autonomi",