loki-mode 6.74.6 → 6.75.1

package/autonomy/loki

@@ -449,6 +449,7 @@ show_help() {
     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 "  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)"
@@ -11195,6 +11196,9 @@ main() {
         explain)
             cmd_explain "$@"
             ;;
+        docs)
+            cmd_docs "$@"
+            ;;
         ci)
             cmd_ci "$@"
             ;;
@@ -18322,6 +18326,997 @@ Generated by loki explain on $(date +%Y-%m-%d)"
     set -euo pipefail
 }
 
+# Generate, update, check, and manage project documentation (v6.75.0)
+cmd_docs() {
+    local subcmd="${1:-}"
+    shift 2>/dev/null || true
+
+    case "$subcmd" in
+        generate) _docs_generate "$@" ;;
+        update)   _docs_update "$@" ;;
+        check)    _docs_check "$@" ;;
+        status)   _docs_status "$@" ;;
+        --help|-h|help|"")
+            echo -e "${BOLD}loki docs${NC} - Generate, update, check project documentation"
+            echo ""
+            echo "Usage: loki docs <command> [options]"
+            echo ""
+            echo "Commands:"
+            echo "  generate [path]    Generate full documentation suite in .loki/docs/"
+            echo "  update [path]      Incremental update based on git changes since last generation"
+            echo "  check [path]       Validate documentation coverage and staleness (exit 0=pass, 1=fail)"
+            echo "  status [path]      Show documentation metrics (count, coverage, staleness)"
+            echo ""
+            echo "Options:"
+            echo "  --help, -h         Show this help"
+            echo ""
+            echo "Generated documentation:"
+            echo "  .loki/docs/README.md         Project overview, setup, usage"
+            echo "  .loki/docs/ARCHITECTURE.md   System design, data flow, key decisions"
+            echo "  .loki/docs/API.md            Public API reference (endpoints, functions, classes)"
+            echo "  .loki/docs/SETUP.md          Dev environment setup, dependencies, running locally"
+            echo "  .loki/docs/COMPONENTS.md     Per-component/module documentation"
+            echo "  .loki/docs/TESTING.md        Test strategy, running tests, coverage"
+            echo "  .loki/docs/DECISIONS.md      Architectural Decision Records"
+            echo "  .loki/docs/CLAUDE.md         AI agent context file"
+            echo "  .loki/docs/docs-manifest.json  Manifest with SHAs and timestamps"
+            echo ""
+            echo "Examples:"
+            echo "  loki docs generate                 # Generate docs for current project"
+            echo "  loki docs generate ~/projects/app  # Generate docs for specific project"
+            echo "  loki docs update                   # Update only changed components"
+            echo "  loki docs check                    # Validate docs (CI-friendly)"
+            echo "  loki docs status                   # Show doc metrics"
+            return 0
+            ;;
+        *)
+            log_error "Unknown docs command: $subcmd"
+            echo "Run 'loki docs --help' for usage."
+            return 1
+            ;;
+    esac
+}
+
+# --- Docs helper: scan project and build context ---
+_docs_scan_project() {
+    local target_path="$1"
+
+    # Build file tree (excluding common noise)
+    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
+    echo "$tree_output"
+}
+
+_docs_build_context() {
+    local target_path="$1"
+    local tree_output="$2"
+    local context=""
+
+    context="PROJECT PATH: $target_path
+PROJECT NAME: $(basename "$target_path")
+"
+
+    # File tree summary
+    local total_files src_count test_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; })
+    context="${context}
+FILES: $total_files total, $src_count source, $test_count test
+"
+
+    # Top-level directories
+    local top_dirs
+    top_dirs=$(echo "$tree_output" | sed 's|/.*||' | sort | uniq -c | sort -rn | head -20)
+    context="${context}
+DIRECTORY STRUCTURE:
+$top_dirs
+"
+
+    # File tree (first 200 files)
+    context="${context}
+FILE TREE:
+$(echo "$tree_output" | head -200)
+"
+
+    # Key config files - read first 50 lines of each
+    for cfg in package.json pyproject.toml Cargo.toml go.mod Gemfile pom.xml requirements.txt Makefile Dockerfile docker-compose.yml; do
+        if [ -f "$target_path/$cfg" ]; then
+            context="${context}
+--- $cfg (first 50 lines) ---
+$(head -50 "$target_path/$cfg" 2>/dev/null || true)
+"
+        fi
+    done
+
+    # README if present
+    for f in README.md readme.md README.rst README; do
+        if [ -f "$target_path/$f" ]; then
+            context="${context}
+--- $f (first 80 lines) ---
+$(head -80 "$target_path/$f" 2>/dev/null || true)
+"
+            break
+        fi
+    done
+
+    # Key entry point files (first 50 lines)
+    local entry_count=0
+    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
+        if [ -f "$target_path/$candidate" ]; then
+            context="${context}
+--- $candidate (first 50 lines) ---
+$(head -50 "$target_path/$candidate" 2>/dev/null || true)
+"
+            ((++entry_count))
+            [ "$entry_count" -ge 5 ] && break
+        fi
+    done
+
+    echo "$context"
+}
+
+# --- Docs helper: invoke AI provider and capture output ---
+_docs_invoke_provider() {
+    local prompt="$1"
+    local provider="${LOKI_PROVIDER:-claude}"
+    if [ -f ".loki/state/provider" ]; then
+        provider=$(cat ".loki/state/provider" 2>/dev/null)
+    fi
+
+    local result=""
+    local exit_code=0
+    local timeout_cmd="timeout"
+    command -v gtimeout &>/dev/null && timeout_cmd="gtimeout"
+    command -v $timeout_cmd &>/dev/null || timeout_cmd=""
+    local t_prefix=""
+    [ -n "$timeout_cmd" ] && t_prefix="$timeout_cmd 120"
+
+    case "$provider" in
+        claude)
+            result=$($t_prefix claude -p "$prompt" 2>/dev/null) || exit_code=$?
+            ;;
+        codex)
+            result=$($t_prefix codex exec --full-auto "$prompt" 2>/dev/null) || exit_code=$?
+            ;;
+        gemini)
+            result=$($t_prefix gemini --approval-mode=yolo "$prompt" 2>/dev/null) || exit_code=$?
+            ;;
+        cline)
+            result=$($t_prefix cline -y "$prompt" 2>/dev/null) || exit_code=$?
+            ;;
+        aider)
+            result=$($t_prefix aider --message "$prompt" --yes-always --no-auto-commits < /dev/null 2>/dev/null) || exit_code=$?
+            ;;
+        *)
+            log_error "Unknown provider: $provider"
+            return 1
+            ;;
+    esac
+
+    if [ $exit_code -ne 0 ] && [ -z "$result" ]; then
+        log_error "Provider '$provider' failed (exit $exit_code)"
+        return 1
+    fi
+
+    echo "$result"
+}
+
+# --- Docs helper: write manifest ---
+_docs_write_manifest() {
+    local docs_dir="$1"
+    shift
+    # Remaining args are file names
+
+    local git_sha=""
+    git_sha=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
+    local generated_at
+    generated_at=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+    local files_json="{"
+    local first=true
+    for doc_file in "$@"; do
+        local fname
+        fname=$(basename "$doc_file")
+        if [ -f "$docs_dir/$fname" ]; then
+            local file_sha
+            file_sha=$(shasum -a 256 "$docs_dir/$fname" 2>/dev/null | awk '{print $1}' || echo "unknown")
+            if [ "$first" = true ]; then
+                first=false
+            else
+                files_json="${files_json},"
+            fi
+            files_json="${files_json}
+    \"$fname\": {\"sha256\": \"$file_sha\", \"generated_at\": \"$generated_at\"}"
+        fi
+    done
+    files_json="${files_json}
+  }"
+
+    cat > "$docs_dir/docs-manifest.json" <<MANIFEST_EOF
+{
+  "generated_at": "$generated_at",
+  "git_sha": "$git_sha",
+  "files": $files_json
+}
+MANIFEST_EOF
+}
+
+# --- loki docs generate ---
+_docs_generate() {
+    local target_path="."
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --help|-h)
+                echo "Usage: loki docs generate [path]"
+                echo "Generate full documentation suite in .loki/docs/"
+                return 0
+                ;;
+            -*)
+                log_error "Unknown option: $1"
+                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 docs_dir="$target_path/.loki/docs"
+    mkdir -p "$docs_dir"
+
+    log_info "Scanning project at: $target_path"
+
+    # Scan project
+    local tree_output
+    tree_output=$(_docs_scan_project "$target_path")
+    local context
+    context=$(_docs_build_context "$target_path" "$tree_output")
+
+    local project_name
+    project_name="$(basename "$target_path")"
+
+    # Check if provider CLI is available
+    local provider="${LOKI_PROVIDER:-claude}"
+    if [ -f "$target_path/.loki/state/provider" ]; then
+        provider=$(cat "$target_path/.loki/state/provider" 2>/dev/null)
+    fi
+
+    local provider_available=true
+    if ! command -v "$provider" &>/dev/null; then
+        provider_available=false
+        log_warn "Provider '$provider' not found. Generating template-based docs instead."
+    fi
+
+    # Doc types to generate
+    local doc_types="README ARCHITECTURE API SETUP COMPONENTS TESTING DECISIONS CLAUDE"
+    local generated_files=""
+
+    for doc_type in $doc_types; do
+        local doc_file="${doc_type}.md"
+        local prompt=""
+
+        echo -e "  ${CYAN}Generating${NC} $doc_file ..."
+
+        if [ "$provider_available" = true ]; then
+            # Build a focused prompt for each doc type
+            case "$doc_type" in
+                README)
+                    prompt="Based on the following project context, generate a comprehensive README.md file. Include: project title, description, features, installation instructions, usage examples, and contribution guidelines. Use markdown formatting. Do NOT use emojis. Output ONLY the markdown content, no explanations.
+
+$context"
+                    ;;
+                ARCHITECTURE)
+                    prompt="Based on the following project context, generate an ARCHITECTURE.md file. Include: system overview, high-level design, component diagram (as text), data flow, directory structure explanation, key design decisions, and technology choices. Use markdown formatting. Do NOT use emojis. Output ONLY the markdown content, no explanations.
+
+$context"
+                    ;;
+                API)
+                    prompt="Based on the following project context, generate an API.md file. Document all public APIs: REST endpoints, exported functions, classes, and their signatures. Include parameter types, return types, and brief descriptions. If no API is detected, document the main public interfaces. Use markdown formatting. Do NOT use emojis. Output ONLY the markdown content, no explanations.
+
+$context"
+                    ;;
+                SETUP)
+                    prompt="Based on the following project context, generate a SETUP.md file. Include: prerequisites, installation steps, environment variables, database setup, running locally, running in Docker (if applicable), and common troubleshooting. Use markdown formatting. Do NOT use emojis. Output ONLY the markdown content, no explanations.
+
+$context"
+                    ;;
+                COMPONENTS)
+                    prompt="Based on the following project context, generate a COMPONENTS.md file. Document each major component/module/directory: its purpose, key files, public interface, and dependencies on other components. Use markdown formatting. Do NOT use emojis. Output ONLY the markdown content, no explanations.
+
+$context"
+                    ;;
+                TESTING)
+                    prompt="Based on the following project context, generate a TESTING.md file. Include: test strategy, test types (unit, integration, e2e), how to run tests, test configuration, coverage goals, and CI integration. Use markdown formatting. Do NOT use emojis. Output ONLY the markdown content, no explanations.
+
+$context"
+                    ;;
+                DECISIONS)
+                    prompt="Based on the following project context, generate a DECISIONS.md file with Architectural Decision Records (ADRs). Infer key decisions from the technology stack, directory structure, and configuration. Each ADR should have: title, status, context, decision, and consequences. Use markdown formatting. Do NOT use emojis. Output ONLY the markdown content, no explanations.
+
+$context"
+                    ;;
+                CLAUDE)
+                    prompt="Based on the following project context, generate a CLAUDE.md file for AI agent context. Include: project overview, key commands (build, test, run, lint), project structure with brief descriptions of each directory, coding conventions, important files, and any gotchas. This file helps AI coding assistants understand the project quickly. Use markdown formatting. Do NOT use emojis. Output ONLY the markdown content, no explanations.
+
+$context"
+                    ;;
+            esac
+
+            local result=""
+            result=$(_docs_invoke_provider "$prompt" 2>/dev/null) || true
+
+            if [ -n "$result" ]; then
+                echo "$result" > "$docs_dir/$doc_file"
+                generated_files="$generated_files $doc_file"
+            else
+                # Fallback to template
+                _docs_generate_template "$doc_type" "$target_path" "$context" > "$docs_dir/$doc_file"
+                generated_files="$generated_files $doc_file"
+            fi
+        else
+            # Template-based generation (no AI provider)
+            _docs_generate_template "$doc_type" "$target_path" "$context" > "$docs_dir/$doc_file"
+            generated_files="$generated_files $doc_file"
+        fi
+
+        echo -e "  ${GREEN}[done]${NC} $doc_file"
+    done
+
+    # Write manifest
+    # shellcheck disable=SC2086
+    _docs_write_manifest "$docs_dir" $generated_files
+
+    echo ""
+    log_info "Documentation generated in $docs_dir/"
+    log_info "Files: $(echo "$generated_files" | wc -w | tr -d ' ') docs + manifest"
+    echo -e "  Manifest: ${CYAN}$docs_dir/docs-manifest.json${NC}"
+}
+
+# --- Docs helper: generate template-based doc (fallback when no AI provider) ---
+_docs_generate_template() {
+    local doc_type="$1"
+    local target_path="$2"
+    local context="$3"
+    local project_name
+    project_name="$(basename "$target_path")"
+    local timestamp
+    timestamp=$(date +%Y-%m-%d)
+
+    # Extract basic metadata from context
+    local files_line
+    files_line=$(echo "$context" | grep '^FILES:' | head -1 || echo "FILES: unknown")
+
+    case "$doc_type" in
+        README)
+            cat <<EOF
+# $project_name
+
+## Overview
+
+Project at \`$target_path\`.
+
+$files_line
+
+## Getting Started
+
+See SETUP.md for installation and development instructions.
+
+## Documentation
+
+- [Architecture](ARCHITECTURE.md)
+- [API Reference](API.md)
+- [Setup Guide](SETUP.md)
+- [Components](COMPONENTS.md)
+- [Testing](TESTING.md)
+- [Decisions](DECISIONS.md)
+
+---
+Generated by loki docs generate on $timestamp
+EOF
+            ;;
+        ARCHITECTURE)
+            cat <<EOF
+# Architecture
+
+## Overview
+
+This document describes the architecture of $project_name.
+
+## Directory Structure
+
+\`\`\`
+$(echo "$context" | sed -n '/^DIRECTORY STRUCTURE:/,/^$/p' | tail -n +2)
+\`\`\`
+
+## Key Components
+
+See COMPONENTS.md for detailed component documentation.
+
+---
+Generated by loki docs generate on $timestamp
+EOF
+            ;;
+        API)
+            cat <<EOF
+# API Reference
+
+## Overview
+
+Public API documentation for $project_name.
+
+TODO: Document public endpoints, functions, and classes.
+
+---
+Generated by loki docs generate on $timestamp
+EOF
+            ;;
+        SETUP)
+            cat <<EOF
+# Setup Guide
+
+## Prerequisites
+
+See the project configuration files for required dependencies.
+
+## Installation
+
+Clone the repository and install dependencies.
+
+## Running Locally
+
+Refer to the project's build and run scripts.
+
+---
+Generated by loki docs generate on $timestamp
+EOF
+            ;;
+        COMPONENTS)
+            cat <<EOF
+# Components
+
+## Overview
+
+Component documentation for $project_name.
+
+## Modules
+
+$(echo "$context" | sed -n '/^DIRECTORY STRUCTURE:/,/^$/p' | tail -n +2 | awk '{print "### " $2 "\n\n" $1 " files\n"}')
+
+---
+Generated by loki docs generate on $timestamp
+EOF
+            ;;
+        TESTING)
+            cat <<EOF
+# Testing
+
+## Overview
+
+Test documentation for $project_name.
+
+## Running Tests
+
+Refer to the project's test configuration for instructions.
+
+---
+Generated by loki docs generate on $timestamp
+EOF
+            ;;
+        DECISIONS)
+            cat <<EOF
+# Architectural Decision Records
+
+## Overview
+
+Key architectural decisions for $project_name.
+
+## ADR-001: [Title]
+
+- **Status**: Proposed
+- **Context**: [Why this decision was needed]
+- **Decision**: [What was decided]
+- **Consequences**: [What are the trade-offs]
+
+---
+Generated by loki docs generate on $timestamp
+EOF
+            ;;
+        CLAUDE)
+            cat <<EOF
+# $project_name
+
+## Project Overview
+
+$files_line
+
+## Project Structure
+
+\`\`\`
+$(echo "$context" | sed -n '/^FILE TREE:/,/^---/p' | head -50 | tail -n +2)
+\`\`\`
+
+## Key Commands
+
+Refer to the project's configuration files for build, test, and run commands.
+
+---
+Generated by loki docs generate on $timestamp
+EOF
+            ;;
+    esac
+}
+
+# --- loki docs update ---
+_docs_update() {
+    local target_path="."
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --help|-h)
+                echo "Usage: loki docs update [path]"
+                echo "Incrementally update docs based on git changes since last generation."
+                return 0
+                ;;
+            -*)
+                log_error "Unknown option: $1"
+                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 docs_dir="$target_path/.loki/docs"
+    local manifest="$docs_dir/docs-manifest.json"
+
+    if [ ! -f "$manifest" ]; then
+        log_warn "No docs-manifest.json found. Running full generation instead."
+        _docs_generate "$target_path"
+        return $?
+    fi
+
+    # Get the SHA from last generation
+    local last_sha=""
+    if command -v python3 &>/dev/null; then
+        last_sha=$(python3 -c "
+import json
+try:
+    d = json.load(open('$manifest'))
+    print(d.get('git_sha', ''))
+except: pass
+" 2>/dev/null || true)
+    fi
+
+    if [ -z "$last_sha" ] || [ "$last_sha" = "unknown" ]; then
+        log_warn "Cannot determine last generation SHA. Running full generation."
+        _docs_generate "$target_path"
+        return $?
+    fi
+
+    # Check if HEAD is the same as last generation
+    local current_sha
+    current_sha=$(cd "$target_path" && git rev-parse HEAD 2>/dev/null || echo "unknown")
+
+    if [ "$current_sha" = "$last_sha" ]; then
+        log_info "Documentation is up to date (SHA: ${last_sha:0:8})"
+        return 0
+    fi
+
+    # Get changed files since last generation
+    local changed_files=""
+    changed_files=$(cd "$target_path" && git diff --name-only "$last_sha"..HEAD 2>/dev/null || true)
+
+    if [ -z "$changed_files" ]; then
+        log_info "No file changes detected since last generation."
+        return 0
+    fi
+
+    local changed_count
+    changed_count=$(echo "$changed_files" | wc -l | tr -d ' ')
+    log_info "Found $changed_count changed files since last generation (${last_sha:0:8}..${current_sha:0:8})"
+
+    # Determine which doc types need updating based on changed files
+    local docs_to_update=""
+
+    # README: always update if any significant files changed
+    if echo "$changed_files" | grep -qE '\.(md|txt|json|toml|yaml|yml)$'; then
+        docs_to_update="$docs_to_update README"
+    fi
+
+    # ARCHITECTURE: update if directory structure or config changed
+    if echo "$changed_files" | grep -qE '(package\.json|pyproject\.toml|Cargo\.toml|go\.mod|Dockerfile|docker-compose)'; then
+        docs_to_update="$docs_to_update ARCHITECTURE"
+    fi
+
+    # API: update if source files changed
+    if echo "$changed_files" | grep -qE '\.(ts|js|py|go|rs|java|rb)$'; then
+        docs_to_update="$docs_to_update API COMPONENTS"
+    fi
+
+    # SETUP: update if config/dependency files changed
+    if echo "$changed_files" | grep -qE '(package\.json|requirements\.txt|pyproject\.toml|Cargo\.toml|go\.mod|Dockerfile|\.env)'; then
+        docs_to_update="$docs_to_update SETUP"
+    fi
+
+    # TESTING: update if test files or test config changed
+    if echo "$changed_files" | grep -qE '(test|spec|\.test\.|\.spec\.|jest\.config|vitest\.config|pytest|\.bats)'; then
+        docs_to_update="$docs_to_update TESTING"
+    fi
+
+    # CLAUDE: always update on any source change
+    if echo "$changed_files" | grep -qE '\.(ts|js|py|go|rs|java|rb|sh)$'; then
+        docs_to_update="$docs_to_update CLAUDE"
+    fi
+
+    # Deduplicate
+    docs_to_update=$(echo "$docs_to_update" | tr ' ' '\n' | sort -u | tr '\n' ' ' | sed 's/^ *//;s/ *$//')
+
+    if [ -z "$docs_to_update" ]; then
+        log_info "No documentation updates needed for the changed files."
+        # Still update manifest SHA
+        _docs_write_manifest "$docs_dir" $(ls "$docs_dir"/*.md 2>/dev/null | xargs -I{} basename {} || true)
+        return 0
+    fi
+
+    log_info "Updating docs: $docs_to_update"
+
+    # Re-scan and rebuild context
+    local tree_output
+    tree_output=$(_docs_scan_project "$target_path")
+    local context
+    context=$(_docs_build_context "$target_path" "$tree_output")
+
+    # Add changed files context
+    context="${context}
+RECENTLY CHANGED FILES (since last doc generation):
+$changed_files
+"
+
+    local provider="${LOKI_PROVIDER:-claude}"
+    if [ -f "$target_path/.loki/state/provider" ]; then
+        provider=$(cat "$target_path/.loki/state/provider" 2>/dev/null)
+    fi
+
+    local provider_available=true
+    if ! command -v "$provider" &>/dev/null; then
+        provider_available=false
+        log_warn "Provider '$provider' not found. Generating template-based docs instead."
+    fi
+
+    local updated_files=""
+    for doc_type in $docs_to_update; do
+        local doc_file="${doc_type}.md"
+        echo -e "  ${CYAN}Updating${NC} $doc_file ..."
+
+        if [ "$provider_available" = true ]; then
+            local existing_content=""
+            [ -f "$docs_dir/$doc_file" ] && existing_content=$(cat "$docs_dir/$doc_file" 2>/dev/null || true)
+
+            local prompt="Based on the following project context, update the ${doc_type}.md documentation. Here are the files that changed since the last generation:
+
+$changed_files
+
+Current ${doc_type}.md content:
+$existing_content
+
+Project context:
+$context
+
+Generate an updated ${doc_type}.md that reflects the current state of the project. Use markdown formatting. Do NOT use emojis. Output ONLY the markdown content, no explanations."
+
+            local result=""
+            result=$(_docs_invoke_provider "$prompt" 2>/dev/null) || true
+            if [ -n "$result" ]; then
+                echo "$result" > "$docs_dir/$doc_file"
+            fi
+        else
+            _docs_generate_template "$doc_type" "$target_path" "$context" > "$docs_dir/$doc_file"
+        fi
+
+        updated_files="$updated_files $doc_file"
+        echo -e "  ${GREEN}[done]${NC} $doc_file"
+    done
+
+    # Update manifest with all existing docs
+    local all_doc_files=""
+    for f in "$docs_dir"/*.md; do
+        [ -f "$f" ] && all_doc_files="$all_doc_files $(basename "$f")"
+    done
+    # shellcheck disable=SC2086
+    _docs_write_manifest "$docs_dir" $all_doc_files
+
+    echo ""
+    log_info "Updated $(echo "$updated_files" | wc -w | tr -d ' ') documentation files"
+}
+
+# --- loki docs check ---
+_docs_check() {
+    local target_path="."
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --help|-h)
+                echo "Usage: loki docs check [path]"
+                echo "Validate documentation coverage and staleness. Exit 0=pass, 1=fail."
+                return 0
+                ;;
+            -*)
+                log_error "Unknown option: $1"
+                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 docs_dir="$target_path/.loki/docs"
+    local manifest="$docs_dir/docs-manifest.json"
+    local pass=true
+
+    echo -e "${BOLD}Documentation Check${NC}"
+    echo "----------------"
+
+    # Check 1: docs directory exists
+    if [ ! -d "$docs_dir" ]; then
+        echo -e "  ${RED}[FAIL]${NC} No .loki/docs/ directory found"
+        echo ""
+        echo "Run 'loki docs generate' to create documentation."
+        return 1
+    fi
+
+    # Check 2: README.md exists and is non-empty
+    if [ -f "$docs_dir/README.md" ] && [ -s "$docs_dir/README.md" ]; then
+        echo -e "  ${GREEN}[PASS]${NC} README.md exists and is non-empty"
+    else
+        echo -e "  ${RED}[FAIL]${NC} README.md missing or empty"
+        pass=false
+    fi
+
+    # Check 3: manifest exists
+    if [ -f "$manifest" ]; then
+        echo -e "  ${GREEN}[PASS]${NC} docs-manifest.json exists"
+    else
+        echo -e "  ${RED}[FAIL]${NC} docs-manifest.json missing"
+        pass=false
+    fi
+
+    # Check 4: expected doc files exist
+    local expected_docs="README.md ARCHITECTURE.md API.md SETUP.md COMPONENTS.md TESTING.md DECISIONS.md CLAUDE.md"
+    local doc_count=0
+    local expected_count=0
+    for doc in $expected_docs; do
+        ((++expected_count))
+        if [ -f "$docs_dir/$doc" ] && [ -s "$docs_dir/$doc" ]; then
+            ((++doc_count))
+        else
+            echo -e "  ${YELLOW}[WARN]${NC} Missing or empty: $doc"
+        fi
+    done
+    local coverage_pct=0
+    [ "$expected_count" -gt 0 ] && coverage_pct=$(( doc_count * 100 / expected_count ))
+    echo -e "  ${BOLD}Coverage:${NC} $doc_count/$expected_count docs ($coverage_pct%)"
+
+    # Check 5: staleness (commits since last doc generation)
+    if [ -f "$manifest" ] && command -v python3 &>/dev/null; then
+        local last_sha=""
+        last_sha=$(python3 -c "
+import json
+try:
+    d = json.load(open('$manifest'))
+    print(d.get('git_sha', ''))
+except: pass
+" 2>/dev/null || true)
+
+        if [ -n "$last_sha" ] && [ "$last_sha" != "unknown" ]; then
+            local commits_behind=0
+            commits_behind=$(cd "$target_path" && git rev-list --count "$last_sha"..HEAD 2>/dev/null || echo "0")
+            if [ "$commits_behind" -gt 10 ]; then
+                echo -e "  ${RED}[FAIL]${NC} Docs are $commits_behind commits behind HEAD (threshold: 10)"
+                pass=false
+            elif [ "$commits_behind" -gt 0 ]; then
+                echo -e "  ${YELLOW}[WARN]${NC} Docs are $commits_behind commits behind HEAD"
+            else
+                echo -e "  ${GREEN}[PASS]${NC} Docs are up to date with HEAD"
+            fi
+        fi
+    fi
+
+    # Check 6: component coverage (check if major dirs have doc entries)
+    local tree_output
+    tree_output=$(_docs_scan_project "$target_path")
+    local major_dirs
+    major_dirs=$(echo "$tree_output" | sed 's|/.*||' | sort -u | head -20)
+    local dir_count=0
+    local documented_dirs=0
+    if [ -f "$docs_dir/COMPONENTS.md" ]; then
+        local components_content
+        components_content=$(cat "$docs_dir/COMPONENTS.md" 2>/dev/null || true)
+        while IFS= read -r dir; do
+            [ -z "$dir" ] && continue
+            [ ! -d "$target_path/$dir" ] && continue
+            ((++dir_count))
+            if echo "$components_content" | grep -qi "$dir" 2>/dev/null; then
+                ((++documented_dirs))
+            fi
+        done <<< "$major_dirs"
+        if [ "$dir_count" -gt 0 ]; then
+            local dir_pct=$(( documented_dirs * 100 / dir_count ))
+            echo -e "  ${BOLD}Component coverage:${NC} $documented_dirs/$dir_count directories ($dir_pct%)"
+        fi
+    fi
+
+    echo ""
+    if [ "$pass" = true ] && [ "$coverage_pct" -ge 75 ]; then
+        echo -e "${GREEN}Result: PASS${NC}"
+        return 0
+    else
+        echo -e "${RED}Result: FAIL${NC}"
+        [ "$coverage_pct" -lt 75 ] && echo "  Doc coverage below 75%. Run 'loki docs generate' to create missing docs."
+        return 1
+    fi
+}
+
+# --- loki docs status ---
+_docs_status() {
+    local target_path="."
+
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --help|-h)
+                echo "Usage: loki docs status [path]"
+                echo "Show documentation metrics."
+                return 0
+                ;;
+            -*)
+                log_error "Unknown option: $1"
+                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 docs_dir="$target_path/.loki/docs"
+    local manifest="$docs_dir/docs-manifest.json"
+
+    echo -e "${BOLD}Documentation Status${NC}"
+    echo "===================="
+    echo ""
+
+    if [ ! -d "$docs_dir" ]; then
+        echo "No documentation generated yet."
+        echo "Run 'loki docs generate' to create documentation."
+        return 0
+    fi
+
+    # Doc count and sizes
+    local doc_count=0
+    local total_size=0
+    echo -e "${BOLD}Documents:${NC}"
+    for f in "$docs_dir"/*.md; do
+        [ ! -f "$f" ] && continue
+        ((++doc_count))
+        local fsize
+        fsize=$(wc -c < "$f" 2>/dev/null | tr -d ' ')
+        total_size=$((total_size + fsize))
+        local flines
+        flines=$(wc -l < "$f" 2>/dev/null | tr -d ' ')
+        local fname
+        fname=$(basename "$f")
+        printf "  %-22s %5d lines  %6s\n" "$fname" "$flines" "$(_docs_human_size "$fsize")"
+    done
+    echo ""
+    echo "  Total: $doc_count documents, $(_docs_human_size "$total_size")"
+    echo ""
+
+    # Coverage
+    local tree_output
+    tree_output=$(_docs_scan_project "$target_path")
+    local total_files
+    total_files=$(echo "$tree_output" | { grep -c . || true; })
+    local src_files
+    src_files=$(echo "$tree_output" | { grep -cE '\.(js|ts|tsx|jsx|py|rs|go|rb|java|kt|c|cpp|h|hpp|sh)$' || true; })
+
+    local expected_docs="README.md ARCHITECTURE.md API.md SETUP.md COMPONENTS.md TESTING.md DECISIONS.md CLAUDE.md"
+    local existing=0
+    local expected_total=0
+    for doc in $expected_docs; do
+        ((++expected_total))
+        [ -f "$docs_dir/$doc" ] && [ -s "$docs_dir/$doc" ] && ((++existing))
+    done
+    local pct=0
+    [ "$expected_total" -gt 0 ] && pct=$(( existing * 100 / expected_total ))
+    echo -e "${BOLD}Coverage:${NC} $existing/$expected_total doc types ($pct%)"
+    echo "  Project: $total_files files ($src_files source)"
+    echo ""
+
+    # Staleness
+    if [ -f "$manifest" ] && command -v python3 &>/dev/null; then
+        local last_sha="" generated_at=""
+        eval "$(python3 -c "
+import json
+try:
+    d = json.load(open('$manifest'))
+    print('last_sha=\"' + d.get('git_sha', 'unknown') + '\"')
+    print('generated_at=\"' + d.get('generated_at', 'unknown') + '\"')
+except: pass
+" 2>/dev/null || true)"
+
+        echo -e "${BOLD}Last generated:${NC} $generated_at"
+        if [ -n "$last_sha" ] && [ "$last_sha" != "unknown" ]; then
+            echo "  Git SHA: ${last_sha:0:12}"
+            local commits_behind=0
+            commits_behind=$(cd "$target_path" && git rev-list --count "$last_sha"..HEAD 2>/dev/null || echo "0")
+            if [ "$commits_behind" -eq 0 ]; then
+                echo -e "  Staleness: ${GREEN}up to date${NC}"
+            elif [ "$commits_behind" -le 10 ]; then
+                echo -e "  Staleness: ${YELLOW}$commits_behind commits behind${NC}"
+            else
+                echo -e "  Staleness: ${RED}$commits_behind commits behind${NC} (consider running 'loki docs update')"
+            fi
+        fi
+    fi
+}
+
+# --- Docs helper: human-readable file size ---
+_docs_human_size() {
+    local bytes="$1"
+    if [ "$bytes" -ge 1048576 ]; then
+        echo "$((bytes / 1048576))MB"
+    elif [ "$bytes" -ge 1024 ]; then
+        echo "$((bytes / 1024))KB"
+    else
+        echo "${bytes}B"
+    fi
+}
+
 # CI/CD quality gate integration (v6.22.0)
 cmd_ci() {
     local ci_pr=false