loki-mode 7.30.0 → 7.32.0

package/autonomy/loki

@@ -132,8 +132,12 @@ find_skill_dir() {
     return 1
 }
 
-# Use || true to prevent set -e from exiting before error message
-SKILL_DIR=$(find_skill_dir) || true
+# Use || true to prevent set -e from exiting before error message.
+# Honor a pre-set SKILL_DIR (test harnesses point it at a fixture); fall back to
+# auto-detection when unset. No production code exports SKILL_DIR into a child
+# loki invocation (children receive LOKI_SKILL_DIR instead), so this only changes
+# behavior when a caller deliberately exports SKILL_DIR.
+SKILL_DIR="${SKILL_DIR:-$(find_skill_dir)}" || true
 if [ -z "$SKILL_DIR" ]; then
     # Check if installation exists but is incomplete (missing run.sh)
     _check_dir1="$HOME/.claude/skills/loki-mode"
@@ -324,6 +328,105 @@ emit_event() {
     fi
 }
 
+# --- CLI consolidation (Phase A): deprecated-alias back-compat contract -------
+# An old command token continues to dispatch and forward 1:1 to its canonical
+# command. It prints exactly ONE pointer line to STDERR and never touches
+# machine-readable stdout. The deprecation line is suppressed whenever an
+# explicit machine-output flag (--json, -q, --quiet) is present in the args, so
+# callers that capture combined 2>&1 (and JSON consumers) see a clean stream.
+# It is ALSO suppressed for the positional machine-output formats of forwarded
+# commands (json|csv|timeline as the first arg, e.g. `loki export json`), since
+# those formats emit a pure machine-readable stream that a combined 2>&1 capture
+# would otherwise dirty with the note line. The human-readable `markdown` format
+# is intentionally NOT suppressed.
+# Non-TTY stdout is intentionally NOT a suppression trigger (some callers pipe
+# stdout but read stderr).
+#
+# Usage:
+#   _deprecated_alias <old> <new> "$@"   # emit pointer + telemetry (suppressed
+#                                        # under --json/-q/--quiet); then the
+#                                        # caller forwards to the canonical cmd.
+# Reference implementation: the run->start deprecation (cmd_run / v6.84.0).
+_deprecated_alias_should_suppress() {
+    # Returns 0 (suppress) when a machine-output flag is present anywhere in
+    # "$@", OR when the FIRST arg is a positional machine-output format
+    # (json|csv|timeline) used by forwarded commands like `loki export json`.
+    # The positional check is first-arg-only so we never suppress on an
+    # incidental later token; markdown (human-readable) is deliberately excluded.
+    case "${1:-}" in
+        json|csv|timeline) return 0 ;;
+    esac
+    local a
+    for a in "$@"; do
+        case "$a" in
+            --json|-q|--quiet) return 0 ;;
+        esac
+    done
+    return 1
+}
+
+_deprecated_alias() {
+    local old="$1"; shift
+    local new="$1"; shift
+    # "$@" is now the user-supplied argv for the alias invocation.
+    if _deprecated_alias_should_suppress "$@"; then
+        return 0
+    fi
+    echo "note: 'loki ${old}' is now 'loki ${new}'. The old form still works." >&2
+    # Reuse the existing cli_command_deprecated telemetry event (from=/to=).
+    # IMPORTANT: a forwarding alias must add no side effect the canonical command
+    # lacks. events/emit.sh creates "$LOKI_DIR/events/pending" as a side effect,
+    # which would make a no-session directory suddenly contain .loki and flip the
+    # exit code of downstream guards (e.g. cmd_share's "No .loki/ directory"
+    # check). It also removes a bash-vs-bun race for read-only reporters
+    # (cmd_stats sees .loki appear vs Bun seeing it absent). So we only emit
+    # telemetry when .loki already exists; the stderr pointer line is always
+    # printed (modulo the machine-output suppression above). The matching Bun
+    # helper (loki-ts/src/util/deprecated_alias.ts) emits no telemetry, so the
+    # two routes are side-effect consistent.
+    if [ -d "${LOKI_DIR:-.loki}" ]; then
+        emit_event cli_command_deprecated cli alias \
+            "from=${old}" \
+            "to=${new}" \
+            "argv=${*:-}"
+    fi
+}
+
+# CLI consolidation (Phase B): kpis is a Bun-only command (Phase K, v7.5.28+).
+# It ships in the Bun runtime (loki-ts) and reuses the canonical cost arithmetic
+# in loki-ts/src/runner/budget.ts (PRICING map + calculateCostFromRecords, the
+# cost single-source-of-truth). It is deliberately NOT reimplemented in bash:
+# a bash port would duplicate that arithmetic and risk drift. On the bash route
+# (LOKI_LEGACY_BASH=1, or a machine without Bun) both the canonical
+# `report kpis` and the deprecated `kpis` alias print this honest requirement
+# message rather than the generic "Unknown command" (which would contradict
+# `loki help` listing kpis). --json yields a structured {"available": false}
+# payload so a machine consumer is not handed prose. Exits 1.
+# Usage: _kpis_bash_unavailable "$@"   (the alias arm prints the pointer first)
+# --json is honored FLAG-ANYWHERE (not just as $1): a machine consumer that
+# passes the suppression flags first -- e.g. `kpis --quiet --json` or `report
+# kpis -q --json` -- must still get the structured {"available": false} payload
+# on stdout, not prose. This mirrors _deprecated_alias_should_suppress, which
+# also scans all of "$@". Exit 1 either way (the bash route never produces KPIs).
+# Copy points at the CANONICAL `loki report kpis` (the deprecated `loki kpis`
+# alias prints its own pointer first, at the alias arm).
+_kpis_bash_unavailable() {
+    local _ka _want_json=""
+    for _ka in "$@"; do
+        if [ "$_ka" = "--json" ]; then
+            _want_json=1
+            break
+        fi
+    done
+    if [ -n "$_want_json" ]; then
+        printf '{"available": false, "reason": "loki report kpis requires the Bun runtime; it is not implemented on the bash (LOKI_LEGACY_BASH) route"}\n'
+    else
+        echo "loki report kpis requires the Bun runtime and is not available on the bash route." >&2
+        echo "Remove LOKI_LEGACY_BASH=1 (or install Bun: https://bun.sh) to use 'loki report kpis'." >&2
+    fi
+    exit 1
+}
+
 # Emit learning signal (non-blocking) - SYN-018
 # Usage: emit_learning_signal <signal_type> [options]
 # Signal types: user_preference, error_pattern, success_pattern, tool_efficiency, workflow_pattern
@@ -523,6 +626,12 @@ PYEOF
 # Show help
 show_help() {
     local version=$(get_version)
+    # Strip color when stdout is not a TTY (piped/redirected) so captured help
+    # output is clean, matching the bare-loki welcome path. Local overrides only.
+    local BOLD="$BOLD" NC="$NC"
+    if [ ! -t 1 ]; then
+        BOLD=''; NC=''
+    fi
     echo -e "${BOLD}Loki Mode v$version${NC}"
     echo ""
     echo "Usage: loki <command> [options]"
@@ -534,82 +643,63 @@ show_help() {
     echo "  loki start ./prd.md       Build from a spec (PRD file, GitHub issue, or no arg)"
     echo "  Docs: https://github.com/asklokesh/loki-mode  |  Report a problem: loki crash"
     echo ""
+    # CLI consolidation (Phase A): the front page presents ~17 canonical
+    # workflow-oriented entries grouped by section. Deprecated alias names
+    # (stats, metrics, cost, trust-metrics, serve, open, otel, cp, wt, rc, ...)
+    # do NOT appear here; they live in the collapsed footer below and in
+    # `loki help aliases`. The full long-tail surface is still dispatchable and
+    # documented per-command via `loki <command> --help`.
     echo "Commands:"
-    echo "  start [PRD|ISSUE] Start Loki Mode (PRD file, issue ref, or no arg)"
-    echo "  run <issue>      (deprecated) Alias for 'loki start <issue-ref>'"
-    echo "  quick \"task\"     Quick single-task mode (lightweight, 3 iterations max)"
-    echo "  monitor [path]   Monitor Docker Compose services with auto-fix (v6.67.0)"
-    echo "  demo             Build a sample todo app end to end (real run)"
+    echo ""
+    echo "Build:"
+    echo "  start [SPEC]     Start a build (PRD file, GitHub issue, or no arg)"
+    echo "  plan <PRD-file>  Dry-run analysis: complexity, cost, execution plan"
+    echo "  grill [SPEC]     Devil's-advocate spec interrogation before you build"
+    echo "  spec [cmd]       Living spec: lock|status|sync (drift detection)"
     echo "  quickstart [idea]  Guided first build: setup, idea, template, plan, go"
-    echo "  init [name]      Project scaffolding with 21 PRD templates"
-    echo "  issue <url|num>  (deprecated) Use 'loki start <issue-ref>' instead"
-    echo "  watch [prd]      Auto-rerun on PRD file changes (v6.33.0)"
-    echo "  export <format>  Export session data: json|markdown|csv|timeline (v6.0.0)"
+    echo ""
+    echo "Session:"
+    echo "  status [--json]  Show current status (--json for machine-readable)"
     echo "  stop             Stop execution immediately"
-    echo "  cleanup          Kill orphaned processes from crashed sessions"
     echo "  pause            Pause after current session"
     echo "  resume           Resume paused execution"
-    echo "  status [--json]  Show current status (--json for machine-readable)"
-    echo "  stats [flags]    Session statistics (--json, --efficiency)"
-    echo "  kpis [--json]    Accuracy + efficiency KPIs (v7.5.28+) [Phase K]"
-    echo "  logs             Show recent log output"
-    echo "  dashboard [cmd]  Dashboard server (start|stop|status|url|open)"
-    echo "  web [cmd]        Web app UI (start|stop|status) -- serves web-app/dist/"
-    echo "  preview          Open the running app Loki built (alias: open)"
-    echo "  provider [cmd]   Manage AI provider (show|set|list|info)"
-    echo "  serve            Start dashboard/API server (alias for api start)"
-    echo "  api [cmd]        Dashboard/API server (start|stop|status)"
-    echo "  sandbox [cmd]    Docker sandbox (start|stop|status|logs|shell|build)"
-    echo "  notify [cmd]     Send notifications (test|slack|discord|webhook|status)"
-    echo "  telemetry [cmd]  OpenTelemetry management (status|enable|disable|stop|start)"
-    echo "  import           Import GitHub issues as tasks"
-    echo "  github [cmd]     GitHub integration (sync|export|pr|status)"
-    echo "  config [cmd]     Manage configuration (show|init|edit|path|set|get)"
-    echo "  completions [bash|zsh]  Output shell completion scripts"
-    echo "  memory [cmd]     Cross-project learnings (list|show|search|stats)"
-    echo "  compound [cmd]   Knowledge compounding (list|show|search|run|stats)"
-    echo "  council [cmd]    Completion council (status|verdicts|convergence|force-review|report)"
-    echo "  checkpoint|cp    Save/restore session checkpoints"
-    echo "  projects         Multi-project registry management"
-    echo "  audit [cmd]      Agent audit log and quality scanning (log|scan)"
-    echo "  heal <path>      Legacy system healing (archaeology, stabilize, modernize)"
-    echo "  verify [base]    Deterministic PR verification (Autonomi Verify MVP; CI-gate exit codes)"
-    echo "  spec [cmd]       Living spec: keep the spec true (lock|status|sync; drift detection, CI-gate exit codes)"
-    echo "  grill [spec]     Interrogate a spec with the hardest questions before you build it (Devil's Advocate)"
-    echo "  review [opts]    Standalone code review with quality gates (diff, staged, PR, files)"
-    echo "  optimize         Optimize prompts based on session history"
-    echo "  enterprise       Enterprise feature management (tokens, OIDC)"
-    echo "  metrics [opts]   Session productivity report (--json, --last N, --save, --share)"
-    echo "  cost [opts]      Transparent cost view: per-run/project spend + budget (--json, --last N)"
-    echo "  trust [--json]   Visible trust trajectory: council/gate pass-rate + interventions over runs [R4]"
-    echo "  trust-metrics    Trust-layer metrics: evidence-block rate, gate distribution, council split, cost/verified (--json)"
-    echo "  dogfood          Show self-development statistics"
-    echo "  secrets [cmd]    API key status and validation (status|validate)"
-    echo "  reset [target]   Reset session state (all|retries|failed)"
+    echo "  cleanup          Kill orphaned processes from crashed sessions"
+    echo ""
+    echo "Verify / trust:"
+    echo "  verify [base]    Deterministic PR verification (CI-gate exit codes)"
+    echo "  review [opts]    Standalone code review with quality gates"
+    echo "  trust [cmd]      Visible trust trajectory; 'trust detail' for metrics"
+    echo ""
+    echo "Observe:"
+    echo "  dashboard [cmd]  Operations UI server (start|stop|status|url|open)"
+    echo "  mcp              Launch the MCP server (Model Context Protocol, stdio)"
+    echo ""
+    echo "Report:"
+    echo "  report [cmd]     Reporting: session|metrics|cost|export|share|dogfood"
+    echo ""
+    echo "Knowledge:"
+    echo "  analyze [cmd]    Codebase intelligence: explain|onboard|code|context"
+    echo "  memory [cmd]     Cross-project learnings (list|show|search|stats|compound)"
+    echo ""
+    echo "Modernize:"
+    echo "  modernize [cmd]  Legacy modernization: heal|migrate"
+    echo ""
+    echo "Config:"
+    echo "  config [cmd]     Manage configuration + provider (show|set|get|provider)"
     echo "  doctor [--json]  Check system prerequisites and skill symlinks"
-    echo "  setup-skill      Create skill symlinks for all providers"
-    echo "  self-update      Upgrade loki via current manager (use --to bun|npm|brew to switch)"
-    echo "  watchdog [cmd]   Process health monitoring (status|help)"
-    echo "  worktree [cmd]   Parallel worktree management (list|merge|clean|status)"
-    echo "  agent [cmd]      Agent type dispatch (list|info|run|start|review)"
-    echo "  remote [PRD]     Start remote session (connect from phone/browser, Claude Pro/Max)"
-  echo "  trigger          Event-driven autonomous execution (schedules, webhooks)"
-    echo "  failover [cmd]   Cross-provider auto-failover (status|--enable|--test|--chain)"
-    echo "  onboard [path]   Analyze a repo and generate CLAUDE.md (structure, conventions, commands)"
-    echo '  explain [path]   Analyze any codebase and explain its architecture in plain English'
-    echo "  docs [cmd]       Generate, update, check project documentation"
-    echo "  magic [cmd]      Spec-driven component generation (MagicModules + MoMoA)"
-    echo "  plan <PRD>       Dry-run PRD analysis: complexity, cost, and execution plan"
-    echo "  ci [opts]        CI/CD quality gate integration (--pr, --report, --github-comment)"
-    echo "  test [opts]      AI-powered test generation (--file, --dir, --changed, --dry-run)"
-    echo "  context [cmd]    Context window management (show|files|tools|add|clear)"
-    echo "  code [cmd]       Codebase intelligence (overview|symbols|deps|hotspots|diff|search)"
-    echo "  report [opts]    Session report generator (--format text|markdown|html, --output)"
-    echo "  share [opts]     Share session report as GitHub Gist (--private, --format)"
-    echo "  proof [cmd]      Inspect/share proof-of-run artifacts (list|show|open|share)"
-    echo "  bench [cmd]      Head-to-head benchmark harness (run|vs|list|verify|report)"
+    echo ""
     echo "  version          Show version"
-    echo "  help             Show this help"
+    echo "  help             Show this help ('loki help aliases' for old names)"
+    echo ""
+    echo "More commands (init, watch, demo, web, api, logs, github,"
+    echo "import, council, proof, audit, agent, template, magic, docs, wiki, ci,"
+    echo "test, bench, secrets, telemetry, crash, worktree, failover, monitor,"
+    echo "remote, ...) are dispatchable and documented via"
+    echo "'loki <command> --help'."
+    echo ""
+    echo "Aliases (deprecated): older command names still work; they print a"
+    echo "one-line pointer to stderr and never alter --json output. See the full"
+    echo "list with 'loki help aliases'."
     echo ""
     echo "Options for 'start':"
     echo "  --provider NAME  AI provider: claude (default), codex, cline, aider"
@@ -655,11 +745,11 @@ show_help() {
     echo ""
     echo "  # Session ops + observability"
     echo "  loki status [--json]          # Current status"
-    echo "  loki stats --efficiency       # Token + cost stats"
-    echo "  loki kpis [--json]            # Accuracy + efficiency KPI snapshot"
+    echo "  loki report session --efficiency   # Token + cost stats"
+    echo "  loki report kpis [--json]     # Accuracy + efficiency KPI snapshot"
     echo "  loki doctor [--json]          # System prereq + skill symlinks"
     echo "  loki logs                     # Tail recent log output"
-    echo "  loki export json|markdown|csv|timeline   # Export session"
+    echo "  loki report export json|markdown|csv|timeline   # Export session"
     echo "  loki assets export team.tgz   # Export shareable team assets (redacted)"
     echo "  loki cleanup                  # Kill orphaned processes"
     echo ""
@@ -694,6 +784,56 @@ show_help() {
     echo "  See: $RUN_SH (header comments) for full list."
 }
 
+# CLI consolidation (Phase A): `loki help aliases` subview. Lists every
+# deprecated alias and its canonical command for users with scripts. The old
+# forms continue to work (they print a one-line stderr pointer and never alter
+# --json output); they are supported through at least two MAJOR versions and
+# considered for removal no earlier than vN+2.0.0.
+show_help_aliases() {
+    # Strip color when stdout is not a TTY (piped/redirected), matching the
+    # bare-loki welcome path and show_help. Local overrides only.
+    local BOLD="$BOLD" NC="$NC"
+    if [ ! -t 1 ]; then
+        BOLD=''; NC=''
+    fi
+    echo -e "${BOLD}Loki Mode -- deprecated command aliases${NC}"
+    echo ""
+    echo "These older command names still work. Each forwards 1:1 to its"
+    echo "canonical command, prints exactly one pointer line to stderr, and"
+    echo "never alters --json output (the pointer is suppressed under --json,"
+    echo "-q, and --quiet). They are supported through at least two MAJOR"
+    echo "versions; removal no earlier than vN+2.0.0."
+    echo ""
+    echo "  Old command        Canonical command"
+    echo "  -----------        -----------------"
+    echo "  run <issue>        start <issue>"
+    echo "  serve              api start"
+    echo "  open               preview"
+    echo "  otel               telemetry"
+    echo "  cp                 checkpoint"
+    echo "  wt                 worktree"
+    echo "  rc                 remote"
+    echo "  stats              report session"
+    echo "  metrics            report metrics"
+    echo "  cost               report cost"
+    echo "  export             report export"
+    echo "  share              report share"
+    echo "  dogfood            report dogfood"
+    echo "  kpis               report kpis"
+    echo "  trust-metrics      trust detail"
+    echo "  compound           memory compound"
+    echo "  explain            analyze explain"
+    echo "  onboard            analyze onboard"
+    echo "  code               analyze code"
+    echo "  context            analyze context"
+    echo "  ctx                analyze context"
+    echo "  heal               modernize heal"
+    echo "  migrate            modernize migrate"
+    echo ""
+    echo "More groupings (ui, new, admin) land in later Phase B slices."
+    echo "See internal/CLI-CONSOLIDATION-DESIGN.md for the full migration plan."
+}
+
 # Tight newcomer landing for the bare `loki` invocation (no args).
 # v7.28.x UX: the full 70-command table lives in `loki help`; a no-args run
 # now shows only a calm ~12-line orientation so the "what do I do first"
@@ -5349,17 +5489,28 @@ cmd_run() {
                 break
             fi
         done
-        if [ "$_show_warn" = "true" ]; then
-            echo -e "${YELLOW}Notice: 'loki run' is deprecated. Use 'loki start <issue-ref>' instead.${NC}" >&2
-            echo -e "${DIM}  All features (--worktree, --pr, --ship, --dry-run) work on 'loki start'.${NC}" >&2
-            echo "" >&2
+        # CLI consolidation (Phase A): align the run->start notice with the
+        # standardized one-line alias contract (stderr-only, suppressed under
+        # --json/-q/--quiet, contains "is now 'loki start'"). The word
+        # "deprecated" is kept so existing run/start unification tests still
+        # match. Telemetry reuses the cli_command_deprecated event.
+        if [ "$_show_warn" = "true" ] && ! _deprecated_alias_should_suppress "$@"; then
+            echo "note: 'loki run' is now 'loki start <issue-ref>' (run is deprecated). The old form still works." >&2
             # Emit telemetry event so we can measure adoption of the unified command.
             # Signature: emit_event <type> <source> <action> [key=value ...]
-            emit_event cli_command_deprecated cli run_to_start \
-                "old_command=run" \
-                "new_command=start" \
-                "version=6.84.0" \
-                "argv=${*:-}"
+            # No-side-effect alias contract (matches _deprecated_alias at :371):
+            # events/emit.sh creates "$LOKI_DIR/events/pending" as a side effect,
+            # which would make a clean directory suddenly contain .loki and flip
+            # downstream guards (cmd_share's "No .loki/" check, bash-vs-bun read
+            # divergence). Only emit when .loki already exists; the stderr pointer
+            # is always printed (modulo machine-output suppression above).
+            if [ -d "${LOKI_DIR:-.loki}" ]; then
+                emit_event cli_command_deprecated cli run_to_start \
+                    "from=run" \
+                    "to=start" \
+                    "version=6.84.0" \
+                    "argv=${*:-}"
+            fi
         fi
     fi
 
@@ -10476,17 +10627,29 @@ cmd_dogfood() {
         return 0
     fi
 
-    local stats_script="$SKILL_DIR/scripts/dogfood-stats.sh"
-    if [ ! -f "$stats_script" ]; then
-        echo -e "${RED}Error: dogfood-stats.sh not found${NC}"
-        exit 1
-    fi
-
     local json_flag=""
     if [[ "${1:-}" == "--json" ]]; then
         json_flag="--json"
     fi
 
+    # Honest degradation: scripts/dogfood-stats.sh is a development-only helper
+    # that is NOT shipped in the npm tarball (package.json `files` omits
+    # scripts/). On a packaged install it is absent, so report that plainly
+    # rather than a bare "not found" that reads like a bug. Message goes to
+    # STDERR so a --json caller's stdout stays clean; --json gets a structured
+    # degraded payload on stdout so consumers do not choke on prose.
+    local stats_script="$SKILL_DIR/scripts/dogfood-stats.sh"
+    if [ ! -f "$stats_script" ]; then
+        if [ -n "$json_flag" ]; then
+            printf '{"available": false, "reason": "dogfood-stats.sh is a dev-only helper not shipped in the published package"}\n'
+        else
+            echo "loki report dogfood: self-development stats are unavailable in this install." >&2
+            echo "The dogfood-stats.sh helper is a development-only script and is not" >&2
+            echo "shipped in the published package. Run it from a loki-mode source checkout." >&2
+        fi
+        return 0
+    fi
+
     bash "$stats_script" $json_flag
 }
 
@@ -11725,6 +11888,37 @@ cmd_heal_help() {
     echo "  loki heal --friction-map ./legacy-app          # View friction map"
 }
 
+# CLI consolidation (Phase B, design item 6): the 'modernize' noun groups the
+# legacy-modernization surface (heal/migrate) under one entry. It is a THIN
+# dispatcher: each arm forwards verbatim to the existing cmd_* handler (no
+# handler logic moves; heal and migrate keep their separate phase vocabularies
+# and state). The two top-level tokens remain deprecated forwarding aliases.
+cmd_modernize() {
+    local subcommand="${1:-help}"
+    case "$subcommand" in
+        heal)     shift; cmd_heal "$@";    return $? ;;
+        migrate)  shift; cmd_migrate "$@"; return $? ;;
+        --help|-h|help)
+            echo -e "${BOLD}loki modernize${NC} - Legacy system modernization"
+            echo ""
+            echo "Usage: loki modernize <subcommand> [args]"
+            echo ""
+            echo "Subcommands (grouped modernization surface):"
+            echo "  heal <path>      Legacy system healing in phases (was: loki heal)"
+            echo "  migrate <path>   Codebase migration in phases (was: loki migrate)"
+            echo ""
+            echo "Run 'loki modernize <subcommand> --help' for each. The old"
+            echo "top-level names still work; see 'loki help aliases'."
+            return 0
+            ;;
+        *)
+            echo -e "${RED}Unknown modernize command: $subcommand${NC}" >&2
+            echo "Run 'loki modernize --help' for usage." >&2
+            return 1
+            ;;
+    esac
+}
+
 cmd_heal() {
     local codebase_path=""
     local phase="${LOKI_HEAL_PHASE:-archaeology}"
@@ -13061,6 +13255,200 @@ show_verbose = sys.argv[3] == 'true'
 session_model_env = (os.environ.get('LOKI_SESSION_MODEL', 'sonnet') or 'sonnet').strip().lower()
 legacy_tier_switching = (os.environ.get('LOKI_LEGACY_TIER_SWITCHING', 'false') or 'false').strip().lower() == 'true'
 
+# Model-honesty contract: the estimator must quote the model the runner will
+# actually invoke, and name the lever that selected it. The runner honors only
+# two session-level levers (LOKI_MODEL was estimator-only and is removed):
+#   1. A pending mid-flight override file (.loki/state/model-override) -- the
+#      most specific, just-requested intent; it wins.
+#   2. LOKI_SESSION_MODEL (the session pin the runner reads at run.sh:12309).
+# Canonical normalization is shared with run.sh + the dashboard: trim +
+# lowercase + EXACT allowlist match. A value with interior whitespace (fab le)
+# is rejected everywhere, so the three readers agree.
+def _loki_norm_alias(raw):
+    raw = (raw or '').strip().lower()
+    return raw if raw in ('haiku', 'sonnet', 'opus', 'fable') else ''
+
+# Session-pin normalization is BROADER than the override-file allowlist above.
+# run.sh's session-pin case (run.sh:12331) accepts the four model aliases AND
+# the three raw tier names (planning|development|fast) -- documented at
+# skills/model-selection.md:8 -- mapping each through resolve_model_for_tier.
+# The OVERRIDE file path (_loki_norm_alias) stays narrow because that value is
+# fed straight to 'claude --model', where tier names are not valid. The session
+# pin is a tier route, so tier names ARE valid pins. This normalizer mirrors
+# run.sh's trim+lowercase (interior whitespace preserved, so 'fab le' stays junk
+# and falls through to the default tier exactly like the runner's '*' arm).
+def _loki_norm_session_pin(raw):
+    raw = (raw or '').strip().lower()
+    return raw if raw in (
+        'haiku', 'sonnet', 'opus', 'fable',
+        'planning', 'development', 'fast',
+    ) else ''
+
+# session_model_env starts from LOKI_SESSION_MODEL; track the lever that set it
+# so the provenance line names the real source (never a false attribution).
+_session_model_source = 'LOKI_SESSION_MODEL'
+session_model_env = _loki_norm_session_pin(os.environ.get('LOKI_SESSION_MODEL', '')) or 'sonnet'
+
+_fable_override = ''
+try:
+    _ov_path = os.path.join('.loki', 'state', 'model-override')
+    if os.path.isfile(_ov_path):
+        with open(_ov_path) as _ovf:
+            _fable_override = _loki_norm_alias(_ovf.read())
+except Exception:
+    _fable_override = ''
+if _fable_override:
+    session_model_env = _fable_override
+    _session_model_source = '.loki/state/model-override'
+
+# Architect opt-in (LOKI_FABLE_ARCHITECT=1): the runner routes ONLY the first
+# (architecture) iteration to fable. Disclose that here so the quote is not
+# blind to the lever (it would otherwise under-quote by one fable iteration).
+# Suppressed when an explicit planning-model override or a fable session/override
+# already applies. The maxTier clamp below still caps the disclosed cost.
+_fable_architect = (
+    (os.environ.get('LOKI_FABLE_ARCHITECT', '0') or '0').strip() == '1'
+    and not os.environ.get('LOKI_CLAUDE_MODEL_PLANNING')
+    and not os.environ.get('LOKI_MODEL_PLANNING')
+    and session_model_env != 'fable'
+    and not (os.environ.get('LOKI_LEGACY_TIER_SWITCHING', 'false') or 'false').strip().lower() == 'true'
+)
+
+# Apply the SAME LOKI_MAX_TIER ceiling the runner applies, so the quoted model
+# (and the architect disclosure) never exceed the operator cost cap.
+#
+# SYNC: This resolves the clamp result through the SAME provider config the runner
+# uses, a byte-faithful port of providers/claude.sh loki_apply_max_tier_clamp plus
+# the PROVIDER_MODEL_FAST / PROVIDER_MODEL_DEVELOPMENT resolution chains
+# (claude.sh:55-67, :318). The same port also lives in the dashboard
+# (dashboard/server.py _provider_model_fast / _provider_model_development /
+# _clamp_to_max_tier). All three readers MUST agree; the agreement is locked by
+# the parity test in tests/test-model-override.sh (resolver parity matrix) and the
+# cross-route tests in test-plan-command.sh. If you change resolution here, change
+# it in claude.sh AND dashboard/server.py, and re-run those tests. The 'or' chains
+# mirror bash ':-' empty-string-fallthrough; allow_haiku uses an exact 'true'
+# match to mirror bash [ \"\$x\" = \"true\" ]. PROVIDER_MODEL_DEVELOPMENT is opus
+# by default; PROVIDER_MODEL_FAST is sonnet by default (haiku when ALLOW_HAIKU).
+_allow_haiku = (os.environ.get('LOKI_ALLOW_HAIKU', 'false') or 'false') == 'true'
+def _provider_model_fast():
+    return (os.environ.get('LOKI_CLAUDE_MODEL_FAST')
+            or os.environ.get('LOKI_MODEL_FAST')
+            or ('haiku' if _allow_haiku else 'sonnet'))
+def _provider_model_development():
+    return (os.environ.get('LOKI_CLAUDE_MODEL_DEVELOPMENT')
+            or os.environ.get('LOKI_MODEL_DEVELOPMENT')
+            or ('sonnet' if _allow_haiku else 'opus'))
+def _provider_model_planning():
+    # claude.sh:65 -> LOKI_CLAUDE_MODEL_PLANNING > LOKI_MODEL_PLANNING > opus.
+    # CLAUDE_DEFAULT_PLANNING is always opus (LOKI_ALLOW_HAIKU only lowers the
+    # development and fast defaults, not planning).
+    return (os.environ.get('LOKI_CLAUDE_MODEL_PLANNING')
+            or os.environ.get('LOKI_MODEL_PLANNING')
+            or 'opus')
+_max_tier = (os.environ.get('LOKI_MAX_TIER', '') or '').strip().lower()
+def _loki_clamp_alias(alias):
+    if not _max_tier:
+        return alias
+    if _max_tier == 'haiku':
+        return _provider_model_fast()
+    if _max_tier == 'sonnet':
+        # alias passed as both model and tier (override-path convention): the
+        # runner's sonnet arm reduces to 'downgrade iff alias==fable'.
+        return _provider_model_development() if alias == 'fable' else alias
+    if _max_tier == 'opus':
+        return 'opus' if alias == 'fable' else alias
+    return alias
+
+# Session-pin tier route (the runner's NO-OVERRIDE path). When there is no
+# mid-flight override file, the runner does NOT feed the session alias straight
+# to --model. It maps the alias to an abstract TIER (run.sh:12331 -- opus->
+# planning, sonnet->development, haiku->fast, fable->fable) and resolves that
+# tier through resolve_model_for_tier (claude.sh:353), which reads
+# PROVIDER_MODEL_PLANNING/DEVELOPMENT/FAST and then applies
+# loki_apply_max_tier_clamp(model, REAL_tier). This DIFFERS from the override-
+# path clamp _loki_clamp_alias above: a 'sonnet' SESSION pin dispatches OPUS
+# (development tier -> PROVIDER_MODEL_DEVELOPMENT=opus on stock config), whereas
+# a 'sonnet' OVERRIDE file dispatches sonnet (alias fed straight to --model).
+# Quoting the alias name on the default session path was the task-568 gap (it
+# understated cost ~1.7x: Sonnet quote vs Opus dispatch). The estimator must
+# quote the model the runner actually dispatches.
+#
+# SYNC: byte-faithful with run.sh's session-pin case + claude.sh
+# resolve_model_for_tier + loki_apply_max_tier_clamp. The same resolver lives in
+# the dashboard (dashboard/server.py _resolve_session_pin). Locked by the
+# session-pin parity matrix and the no-cap stock cross-route cases in
+# tests/test-model-override.sh.
+def _resolve_session_pin(alias):
+    # alias -> abstract tier (run.sh:12331). Unknown -> development (the runner's
+    # '*' arm passes CURRENT_TIER through to resolve_model_for_tier, whose '*'
+    # default is PROVIDER_MODEL_DEVELOPMENT, i.e. the development tier).
+    _pin_tier = {
+        'opus': 'planning',
+        'sonnet': 'development',
+        'haiku': 'fast',
+        'fable': 'fable',
+        # Raw tier-name pins (run.sh:12336 passthrough arm) map to their own
+        # tier, NOT through the alias table. So pin=fast -> fast tier ->
+        # PROVIDER_MODEL_FAST (sonnet stock / haiku ALLOW_HAIKU), matching the
+        # runner's dispatch instead of collapsing onto development.
+        'planning': 'planning',
+        'development': 'development',
+        'fast': 'fast',
+    }.get(alias, 'development')
+    # tier -> model (claude.sh resolve_model_for_tier explicit arms).
+    if _pin_tier == 'planning':
+        _m = _provider_model_planning()
+    elif _pin_tier == 'fast':
+        _m = _provider_model_fast()
+    elif _pin_tier == 'fable':
+        _m = 'fable'
+    else:  # development (and the '*' fallthrough)
+        _m = _provider_model_development()
+    # Apply the shared LOKI_MAX_TIER clamp with the REAL tier and resolved model
+    # (loki_apply_max_tier_clamp(model, tier)), NOT the alias==alias override
+    # convention. This is the one place where the two paths legitimately diverge
+    # (e.g. opus pin + sonnet cap + ALLOW_HAIKU: tier route -> sonnet, because the
+    # planning tier downgrades to PROVIDER_MODEL_DEVELOPMENT=sonnet).
+    if not _max_tier:
+        return _m
+    if _max_tier == 'haiku':
+        return _provider_model_fast()
+    if _max_tier == 'sonnet':
+        if _pin_tier in ('planning', 'fable') or _m == 'fable':
+            return _provider_model_development()
+        return _m
+    if _max_tier == 'opus':
+        return 'opus' if _m == 'fable' else _m
+    return _m
+# Resolve the model the runner will ACTUALLY dispatch for the pinned session,
+# choosing the correct route:
+#   - OVERRIDE file present: the runner feeds the alias straight to --model via
+#     loki_apply_max_tier_clamp(alias, alias). Use _loki_clamp_alias (the
+#     override-path clamp). A 'sonnet' override dispatches sonnet.
+#   - No override (session pin): the runner maps alias -> tier ->
+#     resolve_model_for_tier -> clamp(model, real_tier). Use _resolve_session_pin.
+#     A 'sonnet' session pin dispatches OPUS (development tier).
+# This is the task-568 fix: price the actually-dispatched model on BOTH routes.
+_is_override = (_session_model_source == '.loki/state/model-override')
+if _is_override:
+    _dispatched_model = _loki_clamp_alias(session_model_env)
+else:
+    _dispatched_model = _resolve_session_pin(session_model_env)
+
+# Keep session_model_env (the alias) for token-volume tier mapping and provenance,
+# but record when the cost ceiling actually changed the dispatched model so the
+# provenance line is honest about the clamp.
+if _max_tier and _dispatched_model != session_model_env:
+    _session_model_source = 'LOKI_MAX_TIER (clamped)'
+# Clear the architect-fable disclosure when the ceiling would clamp the architect
+# iteration too. This is INDEPENDENT of whether the session model itself changed:
+# e.g. an opus pin under a sonnet cap leaves the session model opus (no change),
+# but the iter-0 fable architect tier still clamps down to development. Nesting
+# this under the session-changed branch would over-quote a Fable iteration the
+# runner actually dispatches as opus (estimator-vs-runner divergence).
+if _max_tier and _fable_architect and _loki_clamp_alias('fable') != 'fable':
+    _fable_architect = False
+
 # v7.29.0: Honor LOKI_COMPLEXITY -- the SAME env var the runner honors at
 # run.sh:920 -- so a forced-tier run (e.g. 'loki demo' / 'loki start --simple'
 # which export LOKI_COMPLEXITY=simple) quotes the tier it will actually run,
@@ -13075,15 +13463,31 @@ forced_complexity = {'standard': 'moderate'}.get(_forced_complexity_raw, _forced
 if forced_complexity not in ('simple', 'moderate', 'complex', 'enterprise'):
     forced_complexity = ''
 
-# Map session model name to tier key used in tokens_per_tier below.
-# Unknown models fall through to 'development' (Sonnet) as a safe default.
+# Map session model name to tier key used in tokens_per_tier below. This keys the
+# token VOLUME per iteration off the work tier the session pin selects (e.g. a
+# sonnet pin = the development tier = 80k/15k tokens). It does NOT decide the
+# priced model: that is _dispatched_model, the model the runner actually invokes.
+# Unknown models fall through to 'development' as a safe default.
 _session_tier_map = {
+    'fable': 'advisor',
     'opus': 'planning',
     'sonnet': 'development',
     'haiku': 'fast',
+    # Raw tier-name pins key off their own work tier directly (they ARE tier
+    # names), mirroring run.sh's session-pin passthrough arm.
+    'planning': 'planning',
+    'development': 'development',
+    'fast': 'fast',
 }
 session_tier = _session_tier_map.get(session_model_env, 'development')
 
+# Pricing-table key (Fable/Opus/Sonnet/Haiku) for the model the runner dispatches.
+# The loop below uses tokens_per_tier[tier] for token VOLUME but prices by this
+# model, so the quote reflects the actually-dispatched model on every route.
+_PRICED_MODEL_KEY = {'fable': 'Fable', 'opus': 'Opus', 'sonnet': 'Sonnet', 'haiku': 'Haiku'}
+def _priced_model_for(alias):
+    return _PRICED_MODEL_KEY.get((alias or '').strip().lower(), 'Opus')
+
 # Colors (disabled for JSON mode)
 if show_json:
     RED = GREEN = YELLOW = BLUE = CYAN = BOLD = DIM = NC = ''
@@ -13256,16 +13660,25 @@ estimated_iterations = (min_iter + max_iter) // 2
 # RARV cycle: 4 iterations per cycle (plan, develop, develop, test)
 # Tokens estimated per iteration step
 tokens_per_tier = {
+    'advisor': {'input': 50000, 'output': 8000, 'model': 'Fable'},
     'planning': {'input': 50000, 'output': 8000, 'model': 'Opus'},
     'development': {'input': 80000, 'output': 15000, 'model': 'Sonnet'},
     'fast': {'input': 30000, 'output': 5000, 'model': 'Haiku'},
 }
 
-# Pricing per 1M tokens
+# Pricing per 1M tokens. Fable 5 is the top-tier advisory model at exactly 2x
+# Opus per token (published \$10/\$50 in/out vs Opus \$5/\$25). The Opus row was
+# corrected from a stale \$15/\$75 to the real Opus 4.8 \$5/\$25, and the Haiku
+# row from a stale \$0.25/\$1.25 (Haiku 3.5) to the published Claude Haiku 4.5
+# price of \$1/\$5 (anthropic.com/news/claude-haiku-4-5), so all four rows now
+# match the three canonical model-keyed tables (run.sh pricing.json, run.sh
+# check_budget_limit, dashboard _DEFAULT_PRICING) and a fable-forced quote
+# honestly shows MORE than Opus, not less.
 pricing = {
-    'Opus':   {'input': 15.00, 'output': 75.00},
+    'Fable':  {'input': 10.00, 'output': 50.00},
+    'Opus':   {'input': 5.00, 'output': 25.00},
     'Sonnet': {'input': 3.00, 'output': 15.00},
-    'Haiku':  {'input': 0.25, 'output': 1.25},
+    'Haiku':  {'input': 1.00, 'output': 5.00},
 }
 
 # Build per-iteration plan
@@ -13273,8 +13686,8 @@ iteration_plan = []
 total_input_tokens = 0
 total_output_tokens = 0
 total_cost = 0.0
-tier_totals = {'Opus': 0.0, 'Sonnet': 0.0, 'Haiku': 0.0}
-tier_iterations = {'Opus': 0, 'Sonnet': 0, 'Haiku': 0}
+tier_totals = {'Fable': 0.0, 'Opus': 0.0, 'Sonnet': 0.0, 'Haiku': 0.0}
+tier_iterations = {'Fable': 0, 'Opus': 0, 'Sonnet': 0, 'Haiku': 0}
 
 for i in range(estimated_iterations):
     rarv_step = i % 4
@@ -13300,9 +13713,26 @@ for i in range(estimated_iterations):
         # MUST use the same tier for all iterations to avoid quoting a
         # cost higher than the user will actually pay.
         tier = session_tier
+        # Architect opt-in: the runner routes ONLY the first iteration to fable
+        # (the architecture pass). Mirror that here so the quote is not blind to
+        # the lever: iteration 0 -> advisor (fable), the rest -> session tier.
+        if _fable_architect and i == 0:
+            tier = 'advisor'
 
     info = tokens_per_tier[tier]
-    model = info['model']
+    # Token VOLUME comes from the work tier (info), but the priced MODEL is the
+    # model the runner actually dispatches. In legacy rotation the per-tier model
+    # IS the dispatched model. In session-pinned mode (the default) the runner
+    # resolves the pin through provider config (_dispatched_model): a sonnet pin
+    # dispatches opus, so we price Opus, not the tier's static 'Sonnet' label.
+    # The fable-architect iteration 0 genuinely dispatches fable (already cap-
+    # cleared above when it would clamp), so it keeps the advisor tier's Fable.
+    if legacy_tier_switching:
+        model = info['model']
+    elif _fable_architect and i == 0:
+        model = info['model']  # advisor tier -> Fable
+    else:
+        model = _priced_model_for(_dispatched_model)
     inp = info['input']
     out = info['output']
 
@@ -13476,6 +13906,7 @@ for reason in complexity_reasons:
 print(f'\n{CYAN}Estimated Iterations{NC}')
 print(f'  Count: {BOLD}{estimated_iterations}{NC} (range: {min_iter}-{max_iter})')
 print(f'  RARV cycles: {cycle_count} (4 iterations per cycle)')
+fable_n = tier_iterations.get('Fable', 0)
 opus_n = tier_iterations.get('Opus', 0)
 sonnet_n = tier_iterations.get('Sonnet', 0)
 haiku_n = tier_iterations.get('Haiku', 0)
@@ -13485,6 +13916,8 @@ if legacy_tier_switching:
 else:
     # Session-pinned: exactly one tier has all iterations.
     pinned_parts = []
+    if fable_n > 0:
+        pinned_parts.append(f'Fable x{fable_n}')
     if opus_n > 0:
         pinned_parts.append(f'Opus x{opus_n}')
     if sonnet_n > 0:
@@ -13492,7 +13925,20 @@ else:
     if haiku_n > 0:
         pinned_parts.append(f'Haiku x{haiku_n}')
     print('  Model distribution: ' + (' | '.join(pinned_parts) if pinned_parts else '(none)'))
-    print(f'  {DIM}(pinned via LOKI_SESSION_MODEL={session_model_env}; set LOKI_LEGACY_TIER_SWITCHING=true to rotate){NC}')
+    # Provenance: name the lever that actually selected the pinned model, never a
+    # false attribution. _session_model_source is the real source (env, override
+    # file, or maxTier clamp) tracked at selection time. When the session pin is a
+    # tier alias that resolves to a DIFFERENT dispatched model (the default: a
+    # 'sonnet' pin -> development tier -> opus), show the resolution so the
+    # distribution above (Opus x4) is legible against the pin name (sonnet).
+    if (not _is_override) and _dispatched_model != session_model_env:
+        print(f'  {DIM}(pinned via {_session_model_source}={session_model_env} -> {session_tier} tier -> {_dispatched_model}; set LOKI_LEGACY_TIER_SWITCHING=true to rotate){NC}')
+    else:
+        print(f'  {DIM}(pinned via {_session_model_source}={session_model_env}; set LOKI_LEGACY_TIER_SWITCHING=true to rotate){NC}')
+    if _fable_architect:
+        print(f'  {DIM}(+ 1 architecture iteration on Fable via LOKI_FABLE_ARCHITECT=1){NC}')
+    if fable_n > 0:
+        print(f'  {YELLOW}Fable 5 is the top-tier advisory model priced at 2x Opus ({chr(36)}10/{chr(36)}50 per MTok).{NC}')
 
 # Tokens
 total_tok = total_input_tokens + total_output_tokens
@@ -13505,7 +13951,7 @@ print(f'  Total:  {total_tok:>12,} tokens')
 ds = chr(36)  # dollar sign
 print(f'\n{CYAN}Cost Estimate{NC}')
 print(f'  {BOLD}Total: {ds}{total_cost:.2f}{NC}')
-for model in ['Opus', 'Sonnet', 'Haiku']:
+for model in ['Fable', 'Opus', 'Sonnet', 'Haiku']:
     # v6.81.1: suppress zero-cost tiers (e.g. session-pinned runs). Keeps
     # the breakdown focused on models actually used. Legacy mode still
     # shows all three because each tier has non-zero iterations.
@@ -13590,7 +14036,7 @@ cmd_plan() {
                 echo ""
                 echo "Environment Variables:"
                 echo "  LOKI_SESSION_MODEL            Pin cost estimate to a single tier"
-                echo "                                (opus|sonnet|haiku, default: sonnet)"
+                echo "                                (opus|sonnet|haiku|fable, default: sonnet)"
                 echo "  LOKI_LEGACY_TIER_SWITCHING    Set to 'true' to restore the legacy"
                 echo "                                Opus/Sonnet/Haiku per-iteration rotation"
                 echo ""
@@ -13724,7 +14170,12 @@ main() {
             cmd_status "$@"
             ;;
         stats)
-            cmd_stats "$@"
+            # CLI consolidation (Phase A): 'stats' is a deprecated alias of
+            # 'report session'. On the Bun route this arm is never reached
+            # (stats is Bun-native); the matching deprecation lives in
+            # loki-ts/src/commands/stats.ts so both routes behave identically.
+            _deprecated_alias stats "report session" "$@"
+            cmd_report session "$@"
             ;;
         dashboard)
             cmd_dashboard "$@"
@@ -13732,13 +14183,24 @@ main() {
         web)
             cmd_web "$@"
             ;;
-        preview|open)
+        preview)
+            cmd_preview "$@"
+            ;;
+        open)
+            # CLI consolidation (Phase A): 'open' is a deprecated alias of 'preview'.
+            _deprecated_alias open preview "$@"
             cmd_preview "$@"
             ;;
         logs)
             cmd_logs "$@"
             ;;
         serve)
+            # CLI consolidation (Phase A): 'serve' is a deprecated alias of
+            # 'api start'. Emit the pointer BEFORE the --help short-circuit so it
+            # fires on every form (including 'serve --help'), consistent with the
+            # other short aliases and testable without binding a TCP port.
+            # Suppressed under --json/-q/--quiet by the helper.
+            _deprecated_alias serve "api start" "$@"
             # v7.6.2 B-12 fix: 'serve --help' previously routed to 'cmd_api start --help'
             # which started the dashboard as a side effect instead of printing help.
             case "${1:-}" in
@@ -13784,7 +14246,9 @@ main() {
             cmd_watch "$@"
             ;;
         export)
-            cmd_export "$@"
+            # CLI consolidation (Phase A): 'export' -> 'report export'.
+            _deprecated_alias export "report export" "$@"
+            cmd_report export "$@"
             ;;
         assets)
             cmd_assets "$@"
@@ -13802,9 +14266,13 @@ main() {
             cmd_memory "$@"
             ;;
         compound)
-            cmd_compound "$@"
+            # CLI consolidation (Phase B): 'compound' -> 'memory compound'.
+            _deprecated_alias compound "memory compound" "$@"
+            cmd_memory compound "$@"
             ;;
         checkpoint|cp)
+            # CLI consolidation (Phase A): 'cp' is a deprecated alias of 'checkpoint'.
+            [ "$command" = "cp" ] && _deprecated_alias cp checkpoint "$@"
             cmd_checkpoint "$@"
             ;;
         rollback)
@@ -13814,7 +14282,9 @@ main() {
             cmd_council "$@"
             ;;
         dogfood)
-            cmd_dogfood "$@"
+            # CLI consolidation (Phase A): 'dogfood' -> 'report dogfood'.
+            _deprecated_alias dogfood "report dogfood" "$@"
+            cmd_report dogfood "$@"
             ;;
         projects)
             cmd_projects "$@"
@@ -13853,8 +14323,13 @@ main() {
         optimize)
             cmd_optimize "$@"
             ;;
+        modernize)
+            cmd_modernize "$@"
+            ;;
         heal)
-            cmd_heal "$@"
+            # CLI consolidation (Phase B): 'heal' -> 'modernize heal'.
+            _deprecated_alias heal "modernize heal" "$@"
+            cmd_modernize heal "$@"
             ;;
         verify)
             cmd_verify "$@"
@@ -13869,12 +14344,16 @@ main() {
             cmd_mcp "$@"
             ;;
         migrate)
-            cmd_migrate "$@"
+            # CLI consolidation (Phase B): 'migrate' -> 'modernize migrate'.
+            _deprecated_alias migrate "modernize migrate" "$@"
+            cmd_modernize migrate "$@"
             ;;
         cluster)
             cmd_cluster "$@"
             ;;
         worktree|wt)
+            # CLI consolidation (Phase A): 'wt' is a deprecated alias of 'worktree'.
+            [ "$command" = "wt" ] && _deprecated_alias wt worktree "$@"
             cmd_worktree "$@"
             ;;
         agent)
@@ -13887,24 +14366,34 @@ main() {
             cmd_state "$@"
             ;;
         metrics)
-            cmd_metrics "$@"
+            # CLI consolidation (Phase A): 'metrics' -> 'report metrics'.
+            _deprecated_alias metrics "report metrics" "$@"
+            cmd_report metrics "$@"
             ;;
         cost)
-            cmd_cost "$@"
+            # CLI consolidation (Phase A): 'cost' -> 'report cost'.
+            _deprecated_alias cost "report cost" "$@"
+            cmd_report cost "$@"
             ;;
         trust)
             cmd_trust "$@"
             ;;
         trust-metrics)
-            cmd_trust_metrics "$@"
+            # CLI consolidation (Phase A): 'trust-metrics' -> 'trust detail'.
+            _deprecated_alias trust-metrics "trust detail" "$@"
+            cmd_trust detail "$@"
             ;;
         syslog)
             cmd_syslog "$@"
             ;;
         telemetry|otel)
+            # CLI consolidation (Phase A): 'otel' is a deprecated alias of 'telemetry'.
+            [ "$command" = "otel" ] && _deprecated_alias otel telemetry "$@"
             cmd_telemetry "$@"
             ;;
         remote|rc)
+            # CLI consolidation (Phase A): 'rc' is a deprecated alias of 'remote'.
+            [ "$command" = "rc" ] && _deprecated_alias rc remote "$@"
             cmd_remote "$@"
             ;;
         trigger)
@@ -13916,11 +14405,18 @@ main() {
         failover)
             cmd_failover "$@"
             ;;
+        analyze)
+            cmd_analyze "$@"
+            ;;
         onboard)
-            cmd_onboard "$@"
+            # CLI consolidation (Phase B): 'onboard' -> 'analyze onboard'.
+            _deprecated_alias onboard "analyze onboard" "$@"
+            cmd_analyze onboard "$@"
             ;;
         explain)
-            cmd_explain "$@"
+            # CLI consolidation (Phase B): 'explain' -> 'analyze explain'.
+            _deprecated_alias explain "analyze explain" "$@"
+            cmd_analyze explain "$@"
             ;;
         docs)
             cmd_docs "$@"
@@ -13944,7 +14440,9 @@ main() {
             cmd_crash "$@"
             ;;
         share)
-            cmd_share "$@"
+            # CLI consolidation (Phase A): 'share' -> 'report share'.
+            _deprecated_alias share "report share" "$@"
+            cmd_report share "$@"
             ;;
         proof)
             cmd_proof "$@"
@@ -13953,10 +14451,15 @@ main() {
             cmd_bench "$@"
             ;;
         context|ctx)
-            cmd_context "$@"
+            # CLI consolidation (Phase B): 'context' (and short alias 'ctx')
+            # -> 'analyze context'.
+            _deprecated_alias "$command" "analyze context" "$@"
+            cmd_analyze context "$@"
             ;;
         code)
-            cmd_code "$@"
+            # CLI consolidation (Phase B): 'code' -> 'analyze code'.
+            _deprecated_alias code "analyze code" "$@"
+            cmd_analyze code "$@"
             ;;
         version|--version|-v)
             cmd_version "$@"
@@ -13964,8 +14467,24 @@ main() {
 	completions)
             cmd_completions "$@"
             ;;
+        kpis)
+            # CLI consolidation (Phase B): `kpis` is a deprecated alias of the
+            # canonical `report kpis`. Emit the one-line pointer (suppressed
+            # under --json/-q/--quiet by _deprecated_alias), then print the
+            # honest Bun-requirement message via the shared helper. On a machine
+            # WITH Bun, bin/loki routes `kpis` to the Bun runtime before this arm
+            # is ever reached; this arm is the LOKI_LEGACY_BASH / no-Bun path.
+            _deprecated_alias kpis "report kpis" "$@"
+            _kpis_bash_unavailable "$@"
+            ;;
         help|--help|-h)
-            show_help
+            # CLI consolidation (Phase A): `loki help aliases` prints the full
+            # deprecated-alias table; bare help prints the grouped front page.
+            if [ "${1:-}" = "aliases" ]; then
+                show_help_aliases
+            else
+                show_help
+            fi
             ;;
         *)
             echo -e "${RED}Unknown command: $command${NC}"
@@ -16281,6 +16800,7 @@ except Exception as e:
             echo "  export [file]     Export to JSON file"
             echo "  dedupe            Remove duplicate entries"
             echo "  clear [type]      Clear learnings (all or specific type)"
+            echo "  compound [cmd]    Compound-solutions knowledge store (was: loki compound)"
             echo ""
             echo "Memory System Commands:"
             echo "  index [rebuild]   Show or rebuild the memory index layer"
@@ -16648,9 +17168,24 @@ print('removed')
 "
             ;;
 
+        compound)
+            # CLI consolidation (Phase B, design item 7): 'compound' is folded
+            # under the 'memory' noun as 'memory compound'. This arm forwards to
+            # the existing cmd_compound handler unchanged (no handler logic
+            # moves). The top-level 'compound' token stays a deprecated
+            # forwarding alias for back-compat. cmd_memory does not shift before
+            # the case, so $@ here is still 'compound <args>'; drop the leading
+            # 'compound' token, then forward the rest verbatim.
+            shift 2>/dev/null || true
+            cmd_compound "$@"
+            ;;
+
         *)
-            echo -e "${RED}Unknown memory command: $subcommand${NC}"
-            echo "Run 'loki memory help' for usage."
+            # Error-channel parity with the consolidated noun family (analyze,
+            # modernize): unknown-subcommand diagnostics go to STDERR so a scripted
+            # consumer capturing stdout is not handed error text. Exit 1 unchanged.
+            echo -e "${RED}Unknown memory command: $subcommand${NC}" >&2
+            echo "Run 'loki memory help' for usage." >&2
             exit 1
             ;;
     esac
@@ -16901,13 +17436,13 @@ COMPOUND_RUN_SCRIPT
             ;;
 
         help|--help|-h)
-            echo -e "${BOLD}loki compound${NC} - Knowledge compounding system"
+            echo -e "${BOLD}loki memory compound${NC} - Knowledge compounding system"
             echo ""
             echo "Extracts structured solutions from cross-project learnings."
             echo "Solutions are stored as markdown files with YAML frontmatter"
             echo "at ~/.loki/solutions/{category}/ and fed back into future planning."
             echo ""
-            echo "Usage: loki compound <command>"
+            echo "Usage: loki memory compound <command>   (alias: loki compound)"
             echo ""
             echo "Commands:"
             echo "  list              List all solutions by category"
@@ -19100,6 +19635,31 @@ cmd_syslog() {
 # dashboard endpoint, and the tests all agree. Honest: with <2 runs it prints
 # "not enough history yet", never a fabricated trend.
 cmd_trust() {
+    # CLI consolidation (Phase A): `trust detail` is the grouped form of the
+    # trust-metrics breakdown. It forwards 1:1 to cmd_trust_metrics (no handler
+    # logic moves). The bare `loki trust` remains the trajectory view. The
+    # deprecation pointer for the old `trust-metrics` name is emitted at the
+    # alias dispatch arm (main()), never here, so `trust detail` stays clean.
+    #
+    # Flag-anywhere: `detail` is accepted in any position (`trust detail`,
+    # `trust --json detail`, `trust detail --json`) so the bash route matches the
+    # bin/loki routing (which forwards on `detail` anywhere) and both routes
+    # behave byte-identically for the same input. The `detail` token is stripped
+    # and the remaining args (e.g. --json) forward to cmd_trust_metrics.
+    local _trust_detail=0
+    local _trust_rest=()
+    local _ta
+    for _ta in "$@"; do
+        if [ "$_ta" = "detail" ]; then
+            _trust_detail=1
+        else
+            _trust_rest+=("$_ta")
+        fi
+    done
+    if [ "$_trust_detail" -eq 1 ]; then
+        cmd_trust_metrics ${_trust_rest[@]+"${_trust_rest[@]}"}
+        return $?
+    fi
     local pass_args=()
     while [[ $# -gt 0 ]]; do
         case "$1" in
@@ -19123,7 +19683,9 @@ cmd_trust() {
                 exit 0
                 ;;
             --json) pass_args+=("--json"); shift ;;
-            *) echo -e "${RED}Unknown option: $1${NC}"; echo "Run 'loki trust --help' for usage."; exit 1 ;;
+            # Errors go to STDERR (not stdout) so a --json consumer's stdout
+            # stays clean, matching the Bun route (trust.ts writes to stderr).
+            *) echo -e "${RED}Unknown option: $1${NC}" >&2; echo "Run 'loki trust --help' for usage." >&2; exit 1 ;;
         esac
     done
 
@@ -19951,6 +20513,41 @@ METRICS_SCRIPT
     fi
 }
 
+# CLI consolidation (Phase B, design item 8): the 'analyze' noun groups the
+# repo-intelligence surface (explain/onboard/code/context) under one entry. It
+# is a THIN dispatcher: every arm forwards verbatim to the existing cmd_*
+# handler (no handler logic moves). The four top-level tokens remain deprecated
+# forwarding aliases for back-compat.
+cmd_analyze() {
+    local subcommand="${1:-help}"
+    case "$subcommand" in
+        explain)  shift; cmd_explain "$@"; return $? ;;
+        onboard)  shift; cmd_onboard "$@"; return $? ;;
+        code)     shift; cmd_code "$@";    return $? ;;
+        context)  shift; cmd_context "$@"; return $? ;;
+        --help|-h|help)
+            echo -e "${BOLD}loki analyze${NC} - Project knowledge and codebase intelligence"
+            echo ""
+            echo "Usage: loki analyze <subcommand> [args]"
+            echo ""
+            echo "Subcommands (grouped knowledge surface):"
+            echo "  explain [path]   Explain a codebase architecture in prose (was: loki explain)"
+            echo "  onboard [path]   Analyze a repo and generate CLAUDE.md (was: loki onboard)"
+            echo "  code [query]     Codebase intelligence queries (was: loki code)"
+            echo "  context [cmd]    Context-window management (was: loki context)"
+            echo ""
+            echo "Run 'loki analyze <subcommand> --help' for each. The old top-level"
+            echo "names still work; see 'loki help aliases'."
+            return 0
+            ;;
+        *)
+            echo -e "${RED}Unknown analyze command: $subcommand${NC}" >&2
+            echo "Run 'loki analyze --help' for usage." >&2
+            return 1
+            ;;
+    esac
+}
+
 # Context window management (inspired by Kiro CLI /context command)
 # Shows token usage breakdown and context window utilization
 cmd_context() {
@@ -25917,7 +26514,73 @@ _test_gen_bats() {
 }
 
 # Session report generator (v6.27.0)
+# CLI consolidation (Phase A): `report` noun dispatcher.
+# Groups the read-only reporting cluster under one noun:
+#   report session  -> cmd_stats       (session statistics)
+#   report metrics  -> cmd_metrics     (productivity report)
+#   report cost     -> cmd_cost        (cost + budget view)
+#   report export   -> cmd_export      (session data export)
+#   report share    -> cmd_share       (share report as Gist)
+#   report dogfood  -> cmd_dogfood     (self-development stats)
+# Any other first token (including a flag like --format, or no token) falls
+# through to the legacy session-report generator (cmd_report_legacy) so that the
+# pre-existing `loki report [--format ...]` surface is byte-for-byte unchanged.
+# No handler logic moves in Phase A: each subcommand calls the existing bare
+# cmd_* function so the canonical `report <sub>` output is identical to the
+# legacy top-level command. The deprecation pointer for the old top-level names
+# is emitted at the alias dispatch arm (main()), never here, so `report <sub>`
+# stays clean.
 cmd_report() {
+    # CLI consolidation (Phase B): `report kpis` is the canonical KPI snapshot
+    # entry. kpis is Bun-only; on a machine WITH Bun, bin/loki two-token-routes
+    # `report kpis` (flag-anywhere) to the Bun runtime before this function is
+    # reached. This is the bash-route (LOKI_LEGACY_BASH / no-Bun) path: print
+    # the honest requirement message, NO deprecation pointer (this IS the
+    # canonical form), exit 1. `kpis` is the report subcommand ONLY when it is the
+    # FIRST non-flag token after `report` (so `report kpis --json` and `report
+    # --json kpis` both route here, mirroring the bin/loki + Bun cli.ts routing),
+    # NOT when it appears anywhere. A `kpis` token that is a positional VALUE of a
+    # different report subcommand -- e.g. `report export json kpis`, where `kpis`
+    # is the export OUTPUT FILENAME -- must NOT be hijacked; it falls through to
+    # the export arm below and behaves exactly as on main (v7.31.0): exit 0, file
+    # `kpis` created. Only the subcommand token is stripped before forwarding to
+    # the helper; flags (e.g. --json) are passed through so it still emits the
+    # structured machine payload.
+    local _report_first_sub="" _kpis_args=() _dropped_kpis=""
+    local _a
+    for _a in "$@"; do
+        case "$_a" in
+            -*) _kpis_args+=("$_a") ;;
+            *)
+                if [ -z "$_report_first_sub" ]; then
+                    _report_first_sub="$_a"
+                    # Drop only the subcommand token itself, once.
+                    if [ "$_a" = "kpis" ]; then
+                        _dropped_kpis=1
+                        continue
+                    fi
+                fi
+                _kpis_args+=("$_a")
+                ;;
+        esac
+    done
+    if [ -n "$_dropped_kpis" ]; then
+        # ${arr[@]:-} guards the empty-array expansion under `set -u` on the
+        # bare `report kpis` case (no extra flags) for older bash (3.2/4.2).
+        _kpis_bash_unavailable "${_kpis_args[@]:-}"
+    fi
+    case "${1:-}" in
+        session)  shift; cmd_stats "$@";   return $? ;;
+        metrics)  shift; cmd_metrics "$@"; return $? ;;
+        cost)     shift; cmd_cost "$@";    return $? ;;
+        export)   shift; cmd_export "$@";  return $? ;;
+        share)    shift; cmd_share "$@";   return $? ;;
+        dogfood)  shift; cmd_dogfood "$@"; return $? ;;
+    esac
+    cmd_report_legacy "$@"
+}
+
+cmd_report_legacy() {
     local session_id=""
     local format="text"
     local output_file=""
@@ -25930,10 +26593,23 @@ cmd_report() {
             --help|-h)
                 echo -e "${BOLD}loki report${NC} - Session report generator (v6.27.0)"
                 echo ""
-                echo "Usage: loki report [options]"
+                echo "Usage: loki report [subcommand] [options]"
                 echo ""
                 echo "Generates a readable session report from .loki/ data."
                 echo ""
+                echo "Subcommands (grouped reporting surface, v7.31):"
+                echo "  session     Session statistics (was: loki stats)"
+                echo "  metrics     Efficiency/reward metrics (was: loki metrics)"
+                echo "  cost        Token cost breakdown (was: loki cost)"
+                echo "  kpis        Accuracy + efficiency KPI snapshot (was: loki kpis; Bun runtime only)"
+                echo "  export      Export session data (was: loki export) [json|markdown|csv|timeline]"
+                echo "  share       Share session assets (was: loki share)"
+                echo "  dogfood     Self-development stats (was: loki dogfood)"
+                echo "  (Run 'loki report <subcommand> --help' for each. The old"
+                echo "   top-level names still work; see 'loki help aliases'.)"
+                echo ""
+                echo "With no subcommand, generates the legacy session report below."
+                echo ""
                 echo "Options:"
                 echo "  --session <id>       Report for specific session (default: latest)"
                 echo "  --format <fmt>       Output format: text, markdown, html (default: text)"
@@ -25962,7 +26638,7 @@ cmd_report() {
             --include-gates) include_gates=true; shift ;;
             --include-agents) include_agents=true; shift ;;
             --include-timeline) include_timeline=true; shift ;;
-            *) echo -e "${RED}Unknown option: $1${NC}"; echo "Run 'loki report --help' for usage."; exit 1 ;;
+            *) echo -e "${RED}Unknown option: $1${NC}" >&2; echo "Run 'loki report --help' for usage." >&2; exit 1 ;;  # stderr for noun-family error-channel parity (analyze/modernize)
         esac
     done