loki-mode 6.30.3 → 6.32.0

package/README.md

@@ -10,7 +10,7 @@
 [![Autonomi](https://img.shields.io/badge/Autonomi-autonomi.dev-5B4EEA)](https://www.autonomi.dev/)
 [![Docker Pulls](https://img.shields.io/docker/pulls/asklokesh/loki-mode)](https://hub.docker.com/r/asklokesh/loki-mode)
 
-**Current Version: v6.30.0**
+**Current Version: v6.32.0**
 
 ### Traction
 

package/SKILL.md

@@ -3,7 +3,7 @@ name: loki-mode
 description: Multi-agent autonomous startup system. Triggers on "Loki Mode". Takes PRD to deployed product with minimal human intervention. Requires --dangerously-skip-permissions flag.
 ---
 
-# Loki Mode v6.30.0
+# Loki Mode v6.32.0
 
 **You are an autonomous agent. You make decisions. You do not ask questions. You do not stop.**
 
@@ -267,4 +267,4 @@ The following features are documented in skill modules but not yet fully automat
 | Quality gates 3-reviewer system | Implemented (v5.35.0) | 5 specialist reviewers in `skills/quality-gates.md`; execution in run.sh |
 | Benchmarks (HumanEval, SWE-bench) | Infrastructure only | Runner scripts and datasets exist in `benchmarks/`; no published results |
 
-**v6.30.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**
+**v6.32.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-6.30.3
+6.32.0

package/autonomy/loki

@@ -424,7 +424,7 @@ show_help() {
     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          Prometheus/OpenMetrics metrics from dashboard"
+    echo "  metrics [opts]   Session productivity report (--json, --last N, --save, --share)"
     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)"
@@ -438,6 +438,7 @@ show_help() {
   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 "  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)"
@@ -9549,6 +9550,9 @@ main() {
         onboard)
             cmd_onboard "$@"
             ;;
+        explain)
+            cmd_explain "$@"
+            ;;
         ci)
             cmd_ci "$@"
             ;;
@@ -13829,47 +13833,448 @@ cmd_syslog() {
 
 # Fetch and display Prometheus metrics from dashboard
 cmd_metrics() {
-    local subcommand="${1:-}"
-    local port="${LOKI_DASHBOARD_PORT:-57374}"
-    local host="127.0.0.1"
+    local show_json=false
+    local last_n=0
+    local save_file=false
+    local share_flag=false
 
-    case "$subcommand" in
-        help|--help|-h)
-            echo -e "${BOLD}loki metrics${NC} - Prometheus/OpenMetrics metrics"
-            echo ""
-            echo "Usage: loki metrics [options]"
-            echo ""
-            echo "Fetches metrics from the dashboard API in Prometheus/OpenMetrics format."
-            echo "The dashboard must be running (loki dashboard start or loki serve)."
-            echo ""
-            echo "Options:"
-            echo "  help    Show this help"
-            echo ""
-            echo "Environment:"
-            echo "  LOKI_DASHBOARD_PORT   Dashboard port (default: 57374)"
-            echo ""
-            echo "Examples:"
-            echo "  loki metrics          # Display all metrics"
-            echo "  loki metrics | grep loki_cost_usd   # Filter specific metric"
-            ;;
-        "")
-            # Fetch metrics from dashboard
-            local url="http://${host}:${port}/metrics"
-            local response
-            response=$(curl -sf "$url" 2>/dev/null) || true
-            if [ -z "$response" ]; then
-                echo -e "${RED}Error: Could not connect to dashboard at ${url}${NC}"
-                echo "Make sure the dashboard is running: loki serve"
-                exit 1
-            fi
-            echo "$response"
-            ;;
-        *)
-            echo -e "${RED}Unknown metrics command: $subcommand${NC}"
-            echo "Run 'loki metrics help' for usage."
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --help|-h)
+                echo -e "${BOLD}loki metrics${NC} - Session productivity reporter"
+                echo ""
+                echo "Usage: loki metrics [options]"
+                echo ""
+                echo "Analyzes past Loki Mode session data and generates a productivity"
+                echo "stats report showing agents deployed, iterations completed, files"
+                echo "changed, and estimated time saved."
+                echo ""
+                echo "Options:"
+                echo "  --json               Machine-readable JSON output"
+                echo "  --last N             Analyze only the last N sessions (default: all)"
+                echo "  --save               Write report to METRICS.md in project root"
+                echo "  --share              Upload report as GitHub Gist (via loki share)"
+                echo "  --help, -h           Show this help"
+                echo ""
+                echo "Subcommands:"
+                echo "  prometheus           Fetch Prometheus/OpenMetrics from dashboard"
+                echo ""
+                echo "Examples:"
+                echo "  loki metrics                   # Full productivity report"
+                echo "  loki metrics --json            # Machine-readable output"
+                echo "  loki metrics --last 5          # Last 5 sessions only"
+                echo "  loki metrics --save            # Write METRICS.md"
+                echo "  loki metrics --share           # Share as GitHub Gist"
+                echo "  loki metrics prometheus        # Prometheus metrics from dashboard"
+                exit 0
+                ;;
+            --json) show_json=true; shift ;;
+            --last) last_n="${2:-0}"; shift 2 ;;
+            --last=*) last_n="${1#*=}"; shift ;;
+            --save) save_file=true; shift ;;
+            --share) share_flag=true; shift ;;
+            prometheus)
+                # Legacy Prometheus metrics subcommand
+                shift
+                local port="${LOKI_DASHBOARD_PORT:-57374}"
+                local host="127.0.0.1"
+                local url="http://${host}:${port}/metrics"
+                local response
+                response=$(curl -sf "$url" 2>/dev/null) || true
+                if [ -z "$response" ]; then
+                    echo -e "${RED}Error: Could not connect to dashboard at ${url}${NC}"
+                    echo "Make sure the dashboard is running: loki serve"
+                    exit 1
+                fi
+                echo "$response"
+                exit 0
+                ;;
+            *) echo -e "${RED}Unknown option: $1${NC}"; echo "Run 'loki metrics --help' for usage."; exit 1 ;;
+        esac
+    done
+
+    local loki_dir="${LOKI_DIR:-.loki}"
+
+    if ! command -v python3 &>/dev/null; then
+        echo -e "${RED}python3 is required for metrics generation${NC}"
+        exit 1
+    fi
+
+    local metrics_output
+    metrics_output=$(LOKI_DIR="$loki_dir" \
+        METRICS_JSON="$show_json" \
+        METRICS_LAST_N="$last_n" \
+        METRICS_SAVE="$save_file" \
+        python3 << 'METRICS_SCRIPT'
+import json
+import os
+import sys
+import glob
+import subprocess
+from datetime import datetime
+
+loki_dir = os.environ.get("LOKI_DIR", ".loki")
+show_json = os.environ.get("METRICS_JSON", "false") == "true"
+last_n = int(os.environ.get("METRICS_LAST_N", "0"))
+save_flag = os.environ.get("METRICS_SAVE", "false") == "true"
+
+def load_json(path):
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except Exception:
+        return None
+
+def fmt_number(n):
+    return f"{n:,}"
+
+def load_queue(path):
+    data = load_json(path)
+    if isinstance(data, list):
+        return data
+    if isinstance(data, dict) and "tasks" in data:
+        return data["tasks"]
+    return []
+
+# --- Gather project name ---
+project_name = os.path.basename(os.getcwd())
+
+# --- Session data ---
+sessions_analyzed = 0
+total_iterations = 0
+total_tasks_completed = 0
+total_tasks_failed = 0
+agent_types_seen = set()
+total_duration_seconds = 0
+
+# Count sessions from checkpoints index or autonomy-state
+checkpoint_index = os.path.join(loki_dir, "state", "checkpoints", "index.jsonl")
+session_entries = []
+if os.path.isfile(checkpoint_index):
+    try:
+        with open(checkpoint_index) as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    try:
+                        session_entries.append(json.loads(line))
+                    except Exception:
+                        pass
+    except Exception:
+        pass
+
+# Orchestrator state
+orch = load_json(os.path.join(loki_dir, "state", "orchestrator.json")) or {}
+current_phase = orch.get("currentPhase", "N/A")
+orch_metrics = orch.get("metrics", {})
+tasks_completed_orch = orch_metrics.get("tasksCompleted", 0)
+tasks_failed_orch = orch_metrics.get("tasksFailed", 0)
+
+# Per-iteration efficiency files
+eff_dir = os.path.join(loki_dir, "metrics", "efficiency")
+iterations = []
+if os.path.isdir(eff_dir):
+    for path in sorted(glob.glob(os.path.join(eff_dir, "iteration-*.json"))):
+        data = load_json(path)
+        if data:
+            iterations.append(data)
+
+# Apply --last N filter
+if last_n > 0 and len(iterations) > last_n:
+    iterations = iterations[-last_n:]
+
+total_iterations = len(iterations) if iterations else max(orch.get("currentIteration", 0), 0)
+
+# Gather agent types from iterations and agents.json
+for it in iterations:
+    model = it.get("model", "")
+    if model:
+        agent_types_seen.add(model)
+    total_duration_seconds += it.get("duration_seconds", 0)
+
+agents_file = os.path.join(loki_dir, "state", "agents.json")
+agents_data = load_json(agents_file)
+if isinstance(agents_data, list):
+    for agent in agents_data:
+        atype = agent.get("agent_type", "")
+        if atype:
+            agent_types_seen.add(atype)
+
+# Queue data for task counts
+completed_tasks = load_queue(os.path.join(loki_dir, "queue", "completed.json"))
+failed_tasks = load_queue(os.path.join(loki_dir, "queue", "failed.json"))
+pending_tasks = load_queue(os.path.join(loki_dir, "queue", "pending.json"))
+in_progress_tasks = load_queue(os.path.join(loki_dir, "queue", "in-progress.json"))
+
+total_tasks_completed = len(completed_tasks) if completed_tasks else tasks_completed_orch
+total_tasks_failed = len(failed_tasks) if failed_tasks else tasks_failed_orch
+total_tasks = total_tasks_completed + total_tasks_failed + len(pending_tasks) + len(in_progress_tasks)
+success_rate = (total_tasks_completed / total_tasks * 100) if total_tasks > 0 else 0.0
+
+# Session count: count unique session directories or fall back to 1 if .loki exists
+sessions_dir = os.path.join(loki_dir, "state", "sessions")
+if os.path.isdir(sessions_dir):
+    sessions_analyzed = len([d for d in os.listdir(sessions_dir) if os.path.isdir(os.path.join(sessions_dir, d))])
+if sessions_analyzed == 0:
+    # Check autonomy-state.json retryCount as proxy for session attempts
+    auto_state = load_json(os.path.join(loki_dir, "autonomy-state.json"))
+    if auto_state:
+        sessions_analyzed = max(1, auto_state.get("retryCount", 1))
+    elif os.path.isdir(loki_dir):
+        sessions_analyzed = 1
+
+# Apply --last N to sessions
+if last_n > 0:
+    sessions_analyzed = min(sessions_analyzed, last_n)
+
+# --- Git stats ---
+lines_added = 0
+lines_removed = 0
+commits_made = 0
+files_changed_git = 0
+tests_written = 0
+
+try:
+    result = subprocess.run(
+        ["git", "log", "--shortstat", "--format="],
+        capture_output=True, text=True, timeout=10
+    )
+    if result.returncode == 0:
+        for line in result.stdout.strip().split("\n"):
+            line = line.strip()
+            if not line:
+                continue
+            parts = line.split(",")
+            for part in parts:
+                part = part.strip()
+                if "file" in part and "changed" in part:
+                    try:
+                        files_changed_git += int(part.split()[0])
+                    except (ValueError, IndexError):
+                        pass
+                elif "insertion" in part:
+                    try:
+                        lines_added += int(part.split()[0])
+                    except (ValueError, IndexError):
+                        pass
+                elif "deletion" in part:
+                    try:
+                        lines_removed += int(part.split()[0])
+                    except (ValueError, IndexError):
+                        pass
+
+    # Count commits
+    result2 = subprocess.run(
+        ["git", "rev-list", "--count", "HEAD"],
+        capture_output=True, text=True, timeout=10
+    )
+    if result2.returncode == 0:
+        commits_made = int(result2.stdout.strip())
+except Exception:
+    pass
+
+# Estimate tests written from git log (files matching test/spec patterns)
+try:
+    result3 = subprocess.run(
+        ["git", "log", "--diff-filter=A", "--name-only", "--format="],
+        capture_output=True, text=True, timeout=10
+    )
+    if result3.returncode == 0:
+        for fname in result3.stdout.strip().split("\n"):
+            fname = fname.strip().lower()
+            if any(kw in fname for kw in ["test", "spec", ".test.", ".spec.", "_test.", "_spec."]):
+                tests_written += 1
+except Exception:
+    pass
+
+# --- Token/cost data ---
+total_cost = sum(it.get("cost_usd", 0) for it in iterations)
+total_input_tokens = sum(it.get("input_tokens", 0) for it in iterations)
+total_output_tokens = sum(it.get("output_tokens", 0) for it in iterations)
+
+# Also check context tracking for cost data
+ctx_file = os.path.join(loki_dir, "context", "tracking.json")
+ctx = load_json(ctx_file)
+if ctx and total_cost == 0:
+    totals = ctx.get("totals", {})
+    total_cost = totals.get("total_cost_usd", 0)
+    total_input_tokens = totals.get("total_input", 0)
+    total_output_tokens = totals.get("total_output", 0)
+
+# --- Time saved estimate ---
+# Each Loki iteration replaces ~15min of manual work
+time_saved_hours = round(total_iterations * 15 / 60, 2)
+
+# --- Memory stats ---
+episodic_count = 0
+semantic_count = 0
+episodic_dir = os.path.join(loki_dir, "memory", "episodic")
+semantic_dir = os.path.join(loki_dir, "memory", "semantic")
+if os.path.isdir(episodic_dir):
+    for root, dirs, files in os.walk(episodic_dir):
+        episodic_count += len([f for f in files if f.endswith(".json")])
+if os.path.isdir(semantic_dir):
+    for root, dirs, files in os.walk(semantic_dir):
+        semantic_count += len([f for f in files if f.endswith(".json")])
+
+# --- Build output ---
+version = "6.32.0"
+try:
+    version_file = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "VERSION")
+    # In heredoc context, __file__ is not reliable; try relative
+    for vf in ["VERSION", "../VERSION", os.path.join(loki_dir, "..", "VERSION")]:
+        if os.path.isfile(vf):
+            with open(vf) as f:
+                version = f.read().strip()
+            break
+except Exception:
+    pass
+
+data = {
+    "project": project_name,
+    "sessions_analyzed": sessions_analyzed,
+    "agent_activity": {
+        "total_iterations": total_iterations,
+        "agent_types": len(agent_types_seen),
+        "tasks_completed": total_tasks_completed,
+        "tasks_failed": total_tasks_failed,
+        "success_rate": round(success_rate, 1)
+    },
+    "code_output": {
+        "files_changed": files_changed_git,
+        "lines_added": lines_added,
+        "lines_removed": lines_removed,
+        "commits": commits_made,
+        "tests_written": tests_written
+    },
+    "tokens": {
+        "input": total_input_tokens,
+        "output": total_output_tokens,
+        "total": total_input_tokens + total_output_tokens,
+        "cost_usd": round(total_cost, 2)
+    },
+    "time_saved": {
+        "hours": time_saved_hours,
+        "iterations": total_iterations,
+        "minutes_per_iteration": 15
+    },
+    "memory": {
+        "episodic_entries": episodic_count,
+        "semantic_patterns": semantic_count
+    },
+    "version": version
+}
+
+if show_json:
+    print(json.dumps(data, indent=2))
+else:
+    # ASCII stats card
+    lines = []
+    lines.append("")
+    lines.append("LOKI MODE PRODUCTIVITY REPORT")
+    lines.append("=" * 40)
+    lines.append(f"Project: {project_name}")
+    lines.append(f"Sessions analyzed: {sessions_analyzed}")
+    lines.append("")
+    lines.append("AGENT ACTIVITY")
+    lines.append(f"  Total iterations:    {fmt_number(total_iterations)}")
+    lines.append(f"  Agent types used:    {len(agent_types_seen)}")
+    lines.append(f"  Tasks completed:     {fmt_number(total_tasks_completed)}")
+    if total_tasks_failed > 0:
+        lines.append(f"  Tasks failed:        {fmt_number(total_tasks_failed)}")
+    if total_tasks > 0:
+        lines.append(f"  Success rate:        {success_rate:.1f}%")
+    lines.append("")
+    lines.append("CODE OUTPUT")
+    lines.append(f"  Files changed:       {fmt_number(files_changed_git)}")
+    lines.append(f"  Lines added:         {fmt_number(lines_added)}")
+    lines.append(f"  Lines removed:       {fmt_number(lines_removed)}")
+    lines.append(f"  Commits:             {fmt_number(commits_made)}")
+    lines.append(f"  Tests written:       {fmt_number(tests_written)}")
+    lines.append("")
+    if total_cost > 0 or total_input_tokens > 0:
+        lines.append("TOKEN USAGE")
+        lines.append(f"  Input tokens:        {fmt_number(total_input_tokens)}")
+        lines.append(f"  Output tokens:       {fmt_number(total_output_tokens)}")
+        lines.append(f"  Estimated cost:      ${total_cost:.2f}")
+        lines.append("")
+    lines.append("TIME SAVED")
+    lines.append(f"  Estimated:           {time_saved_hours} hours")
+    lines.append(f"  (based on {fmt_number(total_iterations)} iterations x 15min each)")
+    lines.append("")
+    if episodic_count > 0 or semantic_count > 0:
+        lines.append("MEMORY")
+        lines.append(f"  Episodic entries:    {fmt_number(episodic_count)}")
+        lines.append(f"  Semantic patterns:   {fmt_number(semantic_count)}")
+        lines.append("")
+    lines.append(f"Generated by Loki Mode v{version} | autonomi.dev")
+    lines.append("Share your stats: loki metrics --share")
+    lines.append("")
+
+    output_text = "\n".join(lines)
+    print(output_text)
+
+    # Save to METRICS.md if requested
+    if save_flag:
+        try:
+            with open("METRICS.md", "w") as f:
+                f.write("# Loki Mode Productivity Report\n\n")
+                f.write(f"Generated: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n\n")
+                f.write("```\n")
+                f.write(output_text.strip())
+                f.write("\n```\n")
+            print("Saved to METRICS.md")
+        except Exception as e:
+            print(f"Error saving METRICS.md: {e}", file=sys.stderr)
+
+METRICS_SCRIPT
+    )
+    local metrics_exit=$?
+
+    if [ $metrics_exit -ne 0 ]; then
+        echo -e "${RED}Failed to generate metrics report${NC}"
+        echo "$metrics_output"
+        exit 1
+    fi
+
+    echo "$metrics_output"
+
+    # Handle --share flag
+    if [ "$share_flag" = true ]; then
+        local tmpfile
+        tmpfile=$(mktemp "/tmp/loki-metrics-XXXXXX.md")
+        echo "$metrics_output" > "$tmpfile"
+
+        if ! command -v gh &>/dev/null; then
+            echo -e "${RED}gh CLI not found -- cannot share${NC}"
+            echo "Install: brew install gh"
+            rm -f "$tmpfile"
             exit 1
-            ;;
-    esac
+        fi
+
+        if ! gh auth status &>/dev/null 2>&1; then
+            echo -e "${RED}GitHub CLI not authenticated${NC}"
+            echo "Run 'gh auth login' to authenticate."
+            rm -f "$tmpfile"
+            exit 1
+        fi
+
+        echo "Uploading metrics report..."
+        local gist_desc="Loki Mode productivity report - ${project_name:-project} ($(date +%Y-%m-%d))"
+        local project_name
+        project_name=$(basename "$(pwd)")
+        local gist_url
+        gist_url=$(gh gist create "$tmpfile" --desc "$gist_desc" --public 2>&1)
+        local gist_exit=$?
+        rm -f "$tmpfile"
+
+        if [ $gist_exit -ne 0 ]; then
+            echo -e "${RED}Failed to create gist${NC}"
+            echo "$gist_url"
+            exit 1
+        fi
+        echo -e "${GREEN}Shared: ${gist_url}${NC}"
+    fi
 }
 
 # Output shell completion scripts
@@ -15049,6 +15454,546 @@ Generated by loki onboard (depth $depth) on $(date +%Y-%m-%d)"
     fi
 }
 
+
+# Analyze any codebase and explain its architecture in plain English (v6.31.0)
+cmd_explain() {
+    local target_path="."
+    set +e
+    local output_json=false
+    local output_brief=false
+    local output_save=false
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --json) output_json=true; shift ;;
+            --brief) output_brief=true; shift ;;
+            --save) output_save=true; shift ;;
+            --help|-h)
+                echo -e "${BOLD}loki explain${NC} - Analyze any codebase and explain its architecture"
+                echo ""
+                echo "Usage: loki explain [path] [options]"
+                echo ""
+                echo "Arguments:"
+                echo "  path              Path to repository (default: current directory)"
+                echo ""
+                echo "Options:"
+                echo "  --json            Machine-readable JSON output"
+                echo "  --brief           Condensed one-pager version"
+                echo "  --save            Write output to EXPLAIN.md in the analyzed directory"
+                echo "  --help            Show this help"
+                echo ""
+                echo "Examples:"
+                echo "  loki explain                       # Analyze current directory"
+                echo "  loki explain ~/projects/myapp      # Analyze specific repo"
+                echo "  loki explain --brief               # Condensed overview"
+                echo "  loki explain --json                # JSON output for tooling"
+                echo "  loki explain --save                # Save as EXPLAIN.md"
+                return 0
+                ;;
+            -*)
+                log_error "Unknown option: $1"
+                echo "Run 'loki explain --help' for usage."
+                return 1
+                ;;
+            *) target_path="$1"; shift ;;
+        esac
+    done
+
+    if [ ! -d "$target_path" ]; then
+        log_error "Directory not found: $target_path"
+        return 1
+    fi
+
+    target_path="$(cd "$target_path" && pwd)"
+    local project_name
+    project_name="$(basename "$target_path")"
+
+    local languages="" frameworks="" build_system="" test_framework=""
+    local entry_points="" package_manager="" project_description=""
+    local project_version="" detected_patterns="" scripts_info=""
+
+    # --- package.json (JavaScript/TypeScript) ---
+    if [ -f "$target_path/package.json" ]; then
+        languages="$languages JavaScript/TypeScript"
+        package_manager="npm"
+        [ -f "$target_path/yarn.lock" ] && package_manager="yarn"
+        [ -f "$target_path/pnpm-lock.yaml" ] && package_manager="pnpm"
+        [ -f "$target_path/bun.lockb" ] && package_manager="bun"
+
+        if command -v python3 &>/dev/null; then
+            local pkg_meta
+            pkg_meta=$(python3 -c "
+import json
+try:
+    d = json.load(open('$target_path/package.json'))
+    print(d.get('name', ''))
+    print(d.get('description', ''))
+    print(d.get('version', ''))
+    main = d.get('main', d.get('module', ''))
+    print(main)
+    s = d.get('scripts', {})
+    for k in sorted(s.keys()):
+        print(f'script:{k}:{s[k]}')
+    for dep in list(d.get('dependencies', {}).keys()):
+        print(f'dep:{dep}')
+    for dep in list(d.get('devDependencies', {}).keys()):
+        print(f'devdep:{dep}')
+except: pass
+" 2>/dev/null || true)
+            local pkg_name pkg_desc pkg_ver pkg_main
+            pkg_name=$(echo "$pkg_meta" | sed -n '1p')
+            pkg_desc=$(echo "$pkg_meta" | sed -n '2p')
+            pkg_ver=$(echo "$pkg_meta" | sed -n '3p')
+            pkg_main=$(echo "$pkg_meta" | sed -n '4p')
+            [ -n "$pkg_name" ] && project_name="$pkg_name"
+            [ -n "$pkg_desc" ] && project_description="$pkg_desc"
+            [ -n "$pkg_ver" ] && project_version="$pkg_ver"
+            [ -n "$pkg_main" ] && entry_points="$pkg_main"
+            scripts_info=$(echo "$pkg_meta" | grep '^script:' | sed 's/^script://' || true)
+            local deps_list devdeps_list all_deps
+            deps_list=$(echo "$pkg_meta" | grep '^dep:' | sed 's/^dep://' || true)
+            devdeps_list=$(echo "$pkg_meta" | grep '^devdep:' | sed 's/^devdep://' || true)
+            all_deps="$deps_list
+$devdeps_list"
+            echo "$deps_list" | grep -q '^react$' && frameworks="$frameworks React" || true
+            echo "$deps_list" | grep -q '^next$' && frameworks="$frameworks Next.js" || true
+            echo "$deps_list" | grep -q '^vue$' && frameworks="$frameworks Vue" || true
+            echo "$deps_list" | grep -q '^express$' && frameworks="$frameworks Express" || true
+            echo "$deps_list" | grep -q '^fastify$' && frameworks="$frameworks Fastify" || true
+            echo "$deps_list" | grep -q '^svelte$' && frameworks="$frameworks Svelte" || true
+            echo "$deps_list" | grep -q '^@angular/core$' && frameworks="$frameworks Angular" || true
+            echo "$deps_list" | grep -q '^hono$' && frameworks="$frameworks Hono" || true
+            echo "$deps_list" | grep -q '^astro$' && frameworks="$frameworks Astro" || true
+            echo "$deps_list" | grep -q '^nuxt$' && frameworks="$frameworks Nuxt" || true
+            echo "$deps_list" | grep -q '^remix$' && frameworks="$frameworks Remix" || true
+            echo "$deps_list" | grep -q '^electron$' && frameworks="$frameworks Electron" || true
+            echo "$all_deps" | grep -q '^tailwindcss$' && frameworks="$frameworks Tailwind" || true
+            echo "$all_deps" | grep -q '^jest$' && test_framework="$test_framework jest" || true
+            echo "$all_deps" | grep -q '^vitest$' && test_framework="$test_framework vitest" || true
+            echo "$all_deps" | grep -q '^mocha$' && test_framework="$test_framework mocha" || true
+            echo "$all_deps" | grep -q '^@playwright/test$' && test_framework="$test_framework playwright" || true
+            echo "$all_deps" | grep -q '^cypress$' && test_framework="$test_framework cypress" || true
+            echo "$all_deps" | grep -q '^webpack$' && build_system="webpack" || true
+            echo "$all_deps" | grep -q '^vite$' && build_system="vite" || true
+            echo "$all_deps" | grep -q '^esbuild$' && build_system="esbuild" || true
+            echo "$all_deps" | grep -q '^rollup$' && build_system="rollup" || true
+            echo "$all_deps" | grep -q '^turbo$' && build_system="turborepo" || true
+            echo "$all_deps" | grep -q '^prisma$' && detected_patterns="$detected_patterns ORM(Prisma)" || true
+            echo "$all_deps" | grep -q '^drizzle-orm$' && detected_patterns="$detected_patterns ORM(Drizzle)" || true
+            echo "$all_deps" | grep -q '^@trpc/server$' && detected_patterns="$detected_patterns tRPC" || true
+            echo "$all_deps" | grep -q '^graphql$' && detected_patterns="$detected_patterns GraphQL" || true
+            echo "$all_deps" | grep -q '^socket.io$' && detected_patterns="$detected_patterns WebSocket" || true
+            echo "$all_deps" | grep -q '^ws$' && detected_patterns="$detected_patterns WebSocket" || true
+            echo "$all_deps" | grep -q '^@nestjs/core$' && frameworks="$frameworks NestJS" || true
+            echo "$all_deps" | grep -q '^redis$\|^ioredis$' && detected_patterns="$detected_patterns Redis" || true
+            echo "$all_deps" | grep -q '^mongoose$' && detected_patterns="$detected_patterns MongoDB" || true
+            echo "$all_deps" | grep -q '^pg$' && detected_patterns="$detected_patterns PostgreSQL" || true
+            echo "$all_deps" | grep -q '^stripe$' && detected_patterns="$detected_patterns Stripe" || true
+        fi
+    fi
+
+    # --- Python ---
+    if [ -f "$target_path/pyproject.toml" ]; then
+        languages="$languages Python"
+        package_manager="pip"
+        grep -q '\[tool.poetry' "$target_path/pyproject.toml" 2>/dev/null && package_manager="poetry" || true
+        grep -q "django" "$target_path/pyproject.toml" 2>/dev/null && frameworks="$frameworks Django" || true
+        grep -q "flask" "$target_path/pyproject.toml" 2>/dev/null && frameworks="$frameworks Flask" || true
+        grep -q "fastapi" "$target_path/pyproject.toml" 2>/dev/null && frameworks="$frameworks FastAPI" || true
+        grep -q "sqlalchemy" "$target_path/pyproject.toml" 2>/dev/null && detected_patterns="$detected_patterns ORM(SQLAlchemy)" || true
+        grep -q "pytest" "$target_path/pyproject.toml" 2>/dev/null && test_framework="$test_framework pytest" || true
+        [ -z "$project_description" ] && project_description=$(grep '^description' "$target_path/pyproject.toml" 2>/dev/null | head -1 | sed 's/^description *= *"//;s/"$//' || true)
+        [ -z "$project_version" ] && project_version=$(grep '^version' "$target_path/pyproject.toml" 2>/dev/null | head -1 | sed 's/^version *= *"//;s/"$//' || true)
+    elif [ -f "$target_path/requirements.txt" ] || [ -f "$target_path/setup.py" ]; then
+        languages="$languages Python"
+        [ -z "$package_manager" ] && package_manager="pip"
+    fi
+
+    # --- Go ---
+    if [ -f "$target_path/go.mod" ]; then
+        languages="$languages Go"
+        package_manager="go-modules"; build_system="go"; test_framework="$test_framework go-test"
+        grep -q "gin-gonic" "$target_path/go.mod" 2>/dev/null && frameworks="$frameworks Gin" || true
+        grep -q "grpc" "$target_path/go.mod" 2>/dev/null && detected_patterns="$detected_patterns gRPC" || true
+    fi
+
+    # --- Rust ---
+    if [ -f "$target_path/Cargo.toml" ]; then
+        languages="$languages Rust"
+        package_manager="cargo"; build_system="cargo"; test_framework="$test_framework cargo-test"
+        grep -q "actix" "$target_path/Cargo.toml" 2>/dev/null && frameworks="$frameworks Actix" || true
+        grep -q "axum" "$target_path/Cargo.toml" 2>/dev/null && frameworks="$frameworks Axum" || true
+        grep -q "tokio" "$target_path/Cargo.toml" 2>/dev/null && detected_patterns="$detected_patterns Async(Tokio)" || true
+    fi
+
+    # --- Ruby ---
+    if [ -f "$target_path/Gemfile" ]; then
+        languages="$languages Ruby"; package_manager="bundler"
+        grep -q "rails" "$target_path/Gemfile" 2>/dev/null && frameworks="$frameworks Rails" || true
+        grep -q "rspec" "$target_path/Gemfile" 2>/dev/null && test_framework="$test_framework rspec" || true
+    fi
+
+    # --- Java/Kotlin ---
+    if [ -f "$target_path/pom.xml" ]; then languages="$languages Java" && build_system="maven" && package_manager="maven"; fi
+    if [ -f "$target_path/build.gradle" ] || [ -f "$target_path/build.gradle.kts" ]; then languages="$languages Java/Kotlin"; build_system="gradle"; fi
+
+    # --- C/C++ ---
+    if [ -f "$target_path/CMakeLists.txt" ]; then languages="$languages C/C++" && build_system="cmake"; fi
+    if [ -f "$target_path/Makefile" ]; then [ -z "$build_system" ] && build_system="make"; fi
+
+    # --- Shell ---
+    local shell_count
+    shell_count=$(find "$target_path" -maxdepth 2 -name "*.sh" -type f 2>/dev/null | wc -l | tr -d ' ')
+    [ "$shell_count" -gt 3 ] && languages="$languages Bash"
+
+    # --- Docker / CI ---
+    local has_docker=false
+    if [ -f "$target_path/Dockerfile" ]; then has_docker=true && detected_patterns="$detected_patterns Docker"; fi
+    [ -f "$target_path/docker-compose.yml" ] || [ -f "$target_path/docker-compose.yaml" ] && detected_patterns="$detected_patterns DockerCompose"
+
+    local ci_system=""
+    [ -d "$target_path/.github/workflows" ] && ci_system="GitHub Actions"
+    if [ -f "$target_path/.gitlab-ci.yml" ]; then ci_system="$ci_system GitLab CI"; fi
+
+    # --- Monorepo ---
+    local is_monorepo=false
+    if [ -f "$target_path/lerna.json" ]; then is_monorepo=true && detected_patterns="$detected_patterns Monorepo(Lerna)"; fi
+    if [ -f "$target_path/turbo.json" ]; then is_monorepo=true && detected_patterns="$detected_patterns Monorepo(Turborepo)"; fi
+    if [ -f "$target_path/nx.json" ]; then is_monorepo=true && detected_patterns="$detected_patterns Monorepo(Nx)"; fi
+    if [ -f "$target_path/pnpm-workspace.yaml" ]; then is_monorepo=true && detected_patterns="$detected_patterns Monorepo(pnpm)"; fi
+    if [ -f "$target_path/package.json" ] && grep -q '"workspaces"' "$target_path/package.json" 2>/dev/null; then
+        is_monorepo=true
+        echo "$detected_patterns" | grep -q "Monorepo" || detected_patterns="$detected_patterns Monorepo(npm)"
+    fi
+
+    # Deduplicate
+    languages=$(echo "$languages" | tr ' ' '\n' | sort -u | tr '\n' ' ' | sed 's/^ *//;s/ *$//')
+    frameworks=$(echo "$frameworks" | tr ' ' '\n' | sort -u | tr '\n' ' ' | sed 's/^ *//;s/ *$//')
+    test_framework=$(echo "$test_framework" | tr ' ' '\n' | sort -u | tr '\n' ' ' | sed 's/^ *//;s/ *$//')
+    detected_patterns=$(echo "$detected_patterns" | tr ' ' '\n' | sort -u | tr '\n' ' ' | sed 's/^ *//;s/ *$//')
+
+    # --- README ---
+    local readme_content="" readme_file=""
+    for f in README.md readme.md README.rst README README.txt; do
+        if [ -f "$target_path/$f" ]; then
+            readme_file="$f"
+            readme_content=$(head -80 "$target_path/$f" 2>/dev/null || true)
+            break
+        fi
+    done
+    if [ -z "$project_description" ] && [ -n "$readme_content" ]; then
+        project_description=$(echo "$readme_content" | grep -v '^#' | grep -v '^$' | grep -v '^\[' | grep -v '^!' | grep -v '^---' | head -3 | sed 's/^ *//' | tr '\n' ' ' | sed 's/  */ /g;s/^ *//;s/ *$//')
+    fi
+
+    # --- File counts ---
+    local tree_output=""
+    if command -v git &>/dev/null && [ -d "$target_path/.git" ]; then
+        tree_output=$(cd "$target_path" && git ls-files 2>/dev/null | head -500 || true)
+    else
+        tree_output=$(find "$target_path" -maxdepth 4 -type f \
+            -not -path '*/node_modules/*' -not -path '*/.git/*' \
+            -not -path '*/vendor/*' -not -path '*/__pycache__/*' \
+            -not -path '*/dist/*' -not -path '*/build/*' \
+            -not -path '*/.next/*' -not -path '*/target/*' \
+            2>/dev/null | sed "s|$target_path/||" | sort | head -500)
+    fi
+    local total_files src_count test_count doc_count config_count
+    total_files=$(echo "$tree_output" | { grep -c . || true; })
+    src_count=$(echo "$tree_output" | { grep -cE '\.(js|ts|tsx|jsx|py|rs|go|rb|java|kt|c|cpp|h|hpp|sh|swift|cs|php)$' || true; })
+    test_count=$(echo "$tree_output" | { grep -cE '(\.test\.|\.spec\.|_test\.|_spec\.|tests/|test/|__tests__/)' || true; })
+    doc_count=$(echo "$tree_output" | { grep -cE '\.(md|rst|txt)$' || true; })
+    config_count=$(echo "$tree_output" | { grep -cE '\.(json|yaml|yml|toml|cfg|ini|env)$|Dockerfile|Makefile' || true; })
+
+    local top_dirs
+    top_dirs=$(echo "$tree_output" | sed 's|/.*||' | sort | uniq -c | sort -rn | head -20)
+
+    # Detect patterns from directory structure
+    echo "$tree_output" | grep -qE '^(api|routes|controllers)/' && detected_patterns="$detected_patterns REST"
+    echo "$tree_output" | grep -qE '^(pages|app)/' && detected_patterns="$detected_patterns FileRouting"
+    echo "$tree_output" | grep -q '^components/' && detected_patterns="$detected_patterns ComponentBased" || true
+    echo "$tree_output" | grep -qE '(middleware|middlewares)/' && detected_patterns="$detected_patterns Middleware"
+    echo "$tree_output" | grep -qE '(events|listeners|handlers)/' && detected_patterns="$detected_patterns EventDriven"
+    echo "$tree_output" | grep -qE '(models|entities|schemas)/' && detected_patterns="$detected_patterns MVC"
+    echo "$tree_output" | grep -qE '(services|service)/' && detected_patterns="$detected_patterns ServiceLayer"
+    detected_patterns=$(echo "$detected_patterns" | tr ' ' '\n' | sort -u | tr '\n' ' ' | sed 's/^ *//;s/ *$//')
+
+    # --- Detect commands ---
+    local build_cmd="" run_cmd="" test_cmd="" lint_cmd=""
+    if [ -n "$scripts_info" ]; then
+        local has_build has_dev has_start has_test has_lint
+        has_build=$(echo "$scripts_info" | grep '^build:' | head -1)
+        has_dev=$(echo "$scripts_info" | grep '^dev:' | head -1)
+        has_start=$(echo "$scripts_info" | grep '^start:' | head -1)
+        has_test=$(echo "$scripts_info" | grep '^test:' | head -1)
+        has_lint=$(echo "$scripts_info" | grep '^lint:' | head -1)
+        [ -n "$has_build" ] && build_cmd="${package_manager:-npm} run build"
+        [ -n "$has_dev" ] && run_cmd="${package_manager:-npm} run dev"
+        [ -z "$run_cmd" ] && [ -n "$has_start" ] && run_cmd="${package_manager:-npm} start"
+        [ -n "$has_test" ] && test_cmd="${package_manager:-npm} test"
+        [ -n "$has_lint" ] && lint_cmd="${package_manager:-npm} run lint"
+    fi
+    if [ -f "$target_path/Cargo.toml" ]; then build_cmd="cargo build" && run_cmd="cargo run" && test_cmd="cargo test"; fi
+    if [ -f "$target_path/go.mod" ]; then build_cmd="go build ./..." && run_cmd="go run ." && test_cmd="go test ./..."; fi
+    if [ -f "$target_path/Makefile" ]; then
+        [ -z "$build_cmd" ] && build_cmd="make"
+        grep -q '^test:' "$target_path/Makefile" 2>/dev/null && [ -z "$test_cmd" ] && test_cmd="make test" || true
+    fi
+    if [ -f "$target_path/pyproject.toml" ]; then grep -q '\[tool.pytest' "$target_path/pyproject.toml" 2>/dev/null && [ -z "$test_cmd" ] && test_cmd="pytest" || true; fi
+
+    # --- Key entry point files ---
+    local major_files=""
+    for candidate in \
+        "src/index.ts" "src/index.js" "src/main.ts" "src/main.js" "src/app.ts" "src/app.js" \
+        "index.ts" "index.js" "main.ts" "main.js" "app.ts" "app.js" "server.ts" "server.js" \
+        "src/App.tsx" "src/App.jsx" "pages/index.tsx" "app/page.tsx" \
+        "main.py" "app.py" "manage.py" "src/main.py" "__main__.py" \
+        "main.go" "cmd/main.go" "src/main.rs" "src/lib.rs"; do
+        echo "$tree_output" | grep -q "^${candidate}$" && major_files="$major_files $candidate"
+    done
+    major_files=$(echo "$major_files" | sed 's/^ *//')
+
+    # --- JSON output ---
+    if [ "$output_json" = true ]; then
+        python3 -c "
+import json
+data = {
+    'project': {'name': '$project_name', 'description': '''$(echo "$project_description" | sed "s/'/\\\\'/g")''', 'version': '$project_version', 'path': '$target_path'},
+    'stack': {'languages': '${languages}'.split() if '${languages}'.strip() else [], 'frameworks': '${frameworks}'.split() if '${frameworks}'.strip() else [], 'build_system': '$build_system' or None, 'package_manager': '$package_manager' or None, 'test_framework': '${test_framework}'.split() if '${test_framework}'.strip() else [], 'ci': '${ci_system}'.strip() or None},
+    'patterns': '${detected_patterns}'.split() if '${detected_patterns}'.strip() else [],
+    'files': {'total': $total_files, 'source': $src_count, 'test': $test_count, 'docs': $doc_count, 'config': $config_count},
+    'commands': {'build': '${build_cmd}' or None, 'run': '${run_cmd}' or None, 'test': '${test_cmd}' or None, 'lint': '${lint_cmd}' or None},
+    'entry_points': '${major_files}'.split() if '${major_files}'.strip() else [],
+    'monorepo': $( [ "$is_monorepo" = true ] && echo "True" || echo "False" ),
+    'has_docker': $( [ "$has_docker" = true ] && echo "True" || echo "False" )
+}
+print(json.dumps(data, indent=2))
+" 2>/dev/null || echo '{"error": "JSON generation failed"}'
+        return 0
+    fi
+
+    # --- Text output ---
+    local output=""
+    local sep="================================================================================"
+    local sep2="--------------------------------------------------------------------------------"
+
+    if [ "$output_brief" = true ]; then
+        output="${BOLD}$project_name${NC}"
+        [ -n "$project_version" ] && output="$output (v$project_version)"
+        output="$output
+$sep2"
+        [ -n "$project_description" ] && output="$output
+$project_description
+"
+        output="$output
+${BOLD}Stack:${NC} ${languages:-unknown}"
+        [ -n "$frameworks" ] && output="$output + $frameworks"
+        [ -n "$build_system" ] && output="$output | Build: $build_system"
+        [ -n "$package_manager" ] && output="$output | Pkg: $package_manager"
+        output="$output
+${BOLD}Scope:${NC} $total_files files ($src_count source, $test_count test, $doc_count docs)"
+        [ -n "$detected_patterns" ] && output="$output
+${BOLD}Patterns:${NC} $(echo "$detected_patterns" | tr ' ' ', ')"
+        [ -n "$ci_system" ] && output="$output
+${BOLD}CI/CD:${NC} $(echo "$ci_system" | sed 's/^ *//')"
+        [ -n "$test_framework" ] && output="$output
+${BOLD}Testing:${NC} $test_framework"
+        if [ -n "$run_cmd" ] || [ -n "$build_cmd" ] || [ -n "$test_cmd" ]; then
+            output="$output
+"
+            [ -n "$run_cmd" ] && output="$output
+${BOLD}Run:${NC}   $run_cmd"
+            [ -n "$build_cmd" ] && output="$output
+${BOLD}Build:${NC} $build_cmd"
+            [ -n "$test_cmd" ] && output="$output
+${BOLD}Test:${NC}  $test_cmd"
+        fi
+        [ -n "$major_files" ] && output="$output
+
+${BOLD}Entry points:${NC} $(echo "$major_files" | tr ' ' ', ')"
+        output="$output
+$sep2
+Generated by loki explain --brief on $(date +%Y-%m-%d)"
+    else
+        output="$sep
+  PROJECT ANALYSIS: $project_name"
+        [ -n "$project_version" ] && output="$output (v$project_version)"
+        output="$output
+$sep
+
+${BOLD}EXECUTIVE SUMMARY${NC}
+$sep2
+"
+        if [ -n "$project_description" ]; then
+            output="$output$project_description"
+        else
+            output="${output}A ${languages:-software} project"
+            [ -n "$frameworks" ] && output="$output built with $frameworks"
+            [ -z "$readme_file" ] && output="$output. No README found -- description derived from project metadata."
+            [ -n "$readme_file" ] && output="$output."
+        fi
+        output="$output
+
+Scope: $total_files tracked files ($src_count source, $test_count test, $doc_count docs, $config_count config).
+
+${BOLD}ARCHITECTURE OVERVIEW${NC}
+$sep2
+"
+        if [ -n "$major_files" ]; then
+            output="${output}Entry points:"
+            for ef in $major_files; do
+                output="$output
+  - $ef"
+            done
+            output="$output
+"
+        fi
+        output="${output}
+Directory structure (by file count):"
+        while IFS= read -r line; do
+            [ -z "$line" ] && continue
+            local dcount dname
+            dcount=$(echo "$line" | awk '{print $1}')
+            dname=$(echo "$line" | awk '{print $2}')
+            if [ -d "$target_path/$dname" ]; then
+                output="$output
+  $dname/  ($dcount files)"
+            else
+                output="$output
+  $dname"
+            fi
+        done <<< "$top_dirs"
+        [ "$is_monorepo" = true ] && output="$output
+
+This is a monorepo project."
+        output="$output
+
+${BOLD}TECHNOLOGY STACK${NC}
+$sep2
+Languages:       ${languages:-N/A}
+Frameworks:      ${frameworks:-N/A}
+Build system:    ${build_system:-N/A}
+Package manager: ${package_manager:-N/A}
+Test framework:  ${test_framework:-N/A}
+CI/CD:           ${ci_system:-N/A}
+"
+        if [ -n "$detected_patterns" ]; then
+            output="$output
+${BOLD}KEY PATTERNS${NC}
+$sep2"
+            for pattern in $detected_patterns; do
+                case "$pattern" in
+                    REST) output="$output
+  - REST API (route/controller directories detected)" ;;
+                    GraphQL) output="$output
+  - GraphQL API" ;;
+                    gRPC) output="$output
+  - gRPC (protocol buffer based RPC)" ;;
+                    tRPC) output="$output
+  - tRPC (end-to-end typesafe APIs)" ;;
+                    WebSocket) output="$output
+  - WebSocket (real-time communication)" ;;
+                    EventDriven) output="$output
+  - Event-driven architecture" ;;
+                    MVC) output="$output
+  - MVC pattern (model/entity directories detected)" ;;
+                    ServiceLayer) output="$output
+  - Service layer pattern" ;;
+                    ComponentBased) output="$output
+  - Component-based UI architecture" ;;
+                    FileRouting) output="$output
+  - File-based routing (pages/app directory)" ;;
+                    Middleware) output="$output
+  - Middleware pipeline" ;;
+                    Docker) output="$output
+  - Docker containerized" ;;
+                    DockerCompose) output="$output
+  - Docker Compose multi-service" ;;
+                    Monorepo*) output="$output
+  - $pattern" ;;
+                    *) output="$output
+  - $pattern" ;;
+                esac
+            done
+            output="$output
+"
+        fi
+        output="$output
+${BOLD}GETTING STARTED${NC}
+$sep2
+"
+        if [ -n "$package_manager" ]; then
+            case "$package_manager" in
+                npm) output="${output}Install dependencies:  npm install
+" ;;
+                yarn) output="${output}Install dependencies:  yarn install
+" ;;
+                pnpm) output="${output}Install dependencies:  pnpm install
+" ;;
+                pip|poetry) output="${output}Install dependencies:  ${package_manager} install
+" ;;
+                cargo) output="${output}Build:  cargo build
+" ;;
+                go-modules) output="${output}Download dependencies:  go mod download
+" ;;
+                bundler) output="${output}Install dependencies:  bundle install
+" ;;
+                *) output="${output}Package manager: $package_manager
+" ;;
+            esac
+        fi
+        [ -n "$run_cmd" ] && output="${output}
+Run (development):  $run_cmd
+"
+        [ -n "$build_cmd" ] && output="${output}
+Build:  $build_cmd
+"
+        [ -n "$test_cmd" ] && output="${output}
+Test:  $test_cmd
+"
+        [ -n "$lint_cmd" ] && output="${output}
+Lint:  $lint_cmd
+"
+        output="$output
+${BOLD}FOR NEW CONTRIBUTORS${NC}
+$sep2
+"
+        if [ -n "$readme_file" ]; then
+            output="${output}Start by reading $readme_file for project-specific context.
+"
+        else
+            output="${output}Note: This project has no README. Consider adding one.
+"
+        fi
+        if [ -n "$major_files" ]; then
+            output="${output}
+Key files to understand first:"
+            for ef in $major_files; do
+                output="$output
+  - $ef"
+            done
+            output="$output
+"
+        fi
+        [ "$test_count" -gt 0 ] && [ -n "$test_cmd" ] && output="${output}
+Tests: $test_count test files found. Run '$test_cmd' to verify your changes.
+"
+        output="$output
+$sep
+Generated by loki explain on $(date +%Y-%m-%d)"
+    fi
+
+    # --- Output ---
+    if [ "$output_save" = true ]; then
+        local clean_output
+        clean_output=$(echo -e "$output" | sed 's/\x1b\[[0-9;]*m//g')
+        echo "$clean_output" > "$target_path/EXPLAIN.md"
+        echo -e "${GREEN}Saved to $target_path/EXPLAIN.md${NC}"
+    else
+        echo -e "$output"
+    fi
+    set -euo pipefail
+}
+
 # CI/CD quality gate integration (v6.22.0)
 cmd_ci() {
     local ci_pr=false

package/completions/_loki

@@ -70,6 +70,15 @@ function _loki {
                 issue)
                     _loki_issue
                     ;;
+                metrics)
+                    _arguments \
+                        '--json[Machine-readable JSON output]' \
+                        '--last[Analyze last N sessions]:number:' \
+                        '--save[Write report to METRICS.md]' \
+                        '--share[Upload report as GitHub Gist]' \
+                        '--help[Show help]' \
+                        '1:subcommand:(prometheus)'
+                    ;;
                 share)
                     _arguments \
                         '--private[Create a secret gist]' \
@@ -115,6 +124,7 @@ function _loki_commands {
         'voice:Voice input commands'
         'doctor:Check system prerequisites'
         'onboard:Analyze repo and generate CLAUDE.md'
+        'metrics:Session productivity report'
         'share:Share session report as GitHub Gist'
         'version:Show version'
         'completions:Output shell completions'

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 demo init stop pause resume status dashboard logs serve api sandbox notify import github issue config provider reset memory compound checkpoint council dogfood projects enterprise voice secrets doctor watchdog audit metrics syslog onboard share version completions help"
+    local main_commands="start quick demo init stop pause resume status dashboard logs serve api sandbox notify import github issue config provider reset memory compound checkpoint council dogfood projects enterprise voice secrets doctor watchdog audit metrics syslog onboard share explain plan report test ci version completions help"
 
     # 1. If we are on the first argument (subcommand)
     if [[ $cword -eq 1 ]]; then
@@ -144,6 +144,15 @@ _loki_completion() {
             _filedir -d
             ;;
 
+        metrics)
+            if [[ "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "--json --last --save --share --help" -- "$cur") )
+                return 0
+            fi
+            local metrics_cmds="prometheus"
+            COMPREPLY=( $(compgen -W "${metrics_cmds}" -- "$cur") )
+            ;;
+
         share)
             if [[ "$cur" == -* ]]; then
                 COMPREPLY=( $(compgen -W "--private --format --help" -- "$cur") )

package/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "6.30.3"
+__version__ = "6.32.0"
 
 # 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/). Complete installation instructions for all platforms and use cases.
 
-**Version:** v6.30.0
+**Version:** v6.32.0
 
 ---
 

package/mcp/__init__.py

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loki-mode",
-  "version": "6.30.3",
+  "version": "6.32.0",
   "description": "Loki Mode by Autonomi - Multi-agent autonomous startup system for Claude Code, Codex CLI, and Gemini CLI",
   "keywords": [
     "agent",