loki-mode 6.30.2 → 6.31.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.31.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.31.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.31.0 | [Autonomi](https://www.autonomi.dev/) flagship product | ~260 lines core**

package/VERSION

@@ -1 +1 @@
-6.30.2
+6.31.0

package/autonomy/loki

@@ -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 "$@"
             ;;
@@ -15049,6 +15053,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/dashboard/__init__.py

@@ -7,7 +7,7 @@ Modules:
     control: Session control API (start/stop/pause/resume)
 """
 
-__version__ = "6.30.2"
+__version__ = "6.31.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.31.0
 
 ---
 

package/mcp/__init__.py

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

package/package.json

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