karajan-code 1.36.0 → 1.36.1

package/README.md

@@ -58,31 +58,143 @@ npm install -g karajan-code
 
 That's it. No Docker required (SonarQube uses Docker, but Karajan auto-manages it). No config files to copy. `kj init` auto-detects your installed agents.
 
-## Quick start
+## Three ways to use Karajan
 
-```bash
-# Run a task — Karajan handles the rest
-kj run "Create a utility function that validates Spanish DNI numbers, with tests"
-```
+Karajan installs **three commands**: `kj`, `kj-tail`, and `karajan-mcp`.
 
-[**▶ Watch the full pipeline demo**](https://karajancode.com#demo) — HU certification, triage, architecture, TDD, SonarQube, code review, Solomon arbitration, security audit.
+### 1. CLI — Direct from terminal
 
-Karajan will:
-1. Triage the task complexity and activate the right roles
-2. Write tests first (TDD)
-3. Implement code to pass those tests
-4. Run SonarQube analysis (auto-starts Docker if needed)
-5. Review the code (Solomon evaluates every rejection)
-6. Iterate until approved or escalate to you
+Run Karajan directly. You see the full pipeline output in real time.
 
 ```bash
-# More examples
+kj run "Create a utility function that validates Spanish DNI numbers, with tests"
 kj code "Add input validation to the signup form"     # Coder only
 kj review "Check the authentication changes"           # Review current diff
 kj audit "Full health analysis of this codebase"       # Read-only audit
 kj plan "Refactor the database layer"                  # Plan without coding
 ```
 
+### 2. MCP — Inside your AI agent
+
+This is the primary use case. Karajan runs as an MCP server inside Claude Code, Codex, or Gemini. You ask your AI agent to do something, and it delegates the heavy lifting to Karajan's pipeline.
+
+```
+You → Claude Code → kj_run (via MCP) → triage → coder → sonar → reviewer → tester → security
+```
+
+The MCP server auto-registers during `npm install`. Your AI agent sees 20 tools (`kj_run`, `kj_code`, `kj_review`, etc.) and uses them as needed.
+
+**The problem**: when Karajan runs inside an AI agent, you lose visibility. The agent shows you the final result, but not the pipeline stages, iterations, or Solomon decisions happening in real time.
+
+### 3. kj-tail — Monitor from a separate terminal
+
+**This is the companion tool.** Open a second terminal in the **same project directory** where your AI agent is working, and run:
+
+```bash
+kj-tail
+```
+
+You'll see the live pipeline output — stages, results, iterations, errors — as they happen. Same view as running `kj run` directly.
+
+```
+kj-tail                  # Follow pipeline in real time (default)
+kj-tail -v               # Verbose: include agent heartbeats and budget
+kj-tail -t               # Show timestamps
+kj-tail -s               # Snapshot: show current log and exit
+kj-tail -n 50            # Show last 50 lines then follow
+kj-tail --help           # Full options
+```
+
+> **Important**: `kj-tail` must run from the same directory where the AI agent is executing. It reads `<project>/.kj/run.log`, which is created when Karajan starts a pipeline via MCP.
+
+**Typical workflow:**
+
+```
+┌─────────────────────────┐    ┌─────────────────────────┐
+│  Terminal 1              │    │  Terminal 2              │
+│                          │    │                          │
+│  $ claude                │    │  $ kj-tail               │
+│  > implement the next    │    │                          │
+│    priority task         │    │  ├─ 📋 Triage: medium    │
+│                          │    │  ├─ 🔬 Researcher ✅     │
+│  (Claude calls kj_run   │    │  ├─ 🧠 Planner ✅        │
+│   via MCP — you see      │    │  ├─ 🔨 Coder ✅          │
+│   only the final result) │    │  ├─ 🔍 Sonar: OK        │
+│                          │    │  ├─ 👁️ Reviewer ❌       │
+│                          │    │  ├─ ⚖️ Solomon: 2 cond.  │
+│                          │    │  ├─ 🔨 Coder (iter 2) ✅ │
+│                          │    │  ├─ ✅ Review: APPROVED   │
+│                          │    │  ├─ 🧪 Tester: passed    │
+│                          │    │  └─ 🏁 Result: APPROVED  │
+└─────────────────────────┘    └─────────────────────────┘
+```
+
+**Full pipeline example** — a complex task with all roles:
+
+```
+┌─ Terminal 1 ─────────────────────────────────────────────────────────────────┐
+│                                                                              │
+│  $ claude                                                                    │
+│                                                                              │
+│  > Build a REST API for a booking system. Requirements:                      │
+│  > - Express + TypeScript with Zod validation on every endpoint              │
+│  > - Endpoints: POST /bookings, GET /bookings/:id, PATCH /bookings/:id/cancel│
+│  > - A booking has: id, guestName, roomType (standard|suite|penthouse),      │
+│  >   checkIn, checkOut, status (confirmed|cancelled)                         │
+│  > - Validate: checkOut must be after checkIn, no past dates,                │
+│  >   roomType must be a valid enum value                                     │
+│  > - Cancel returns 409 if already cancelled                                 │
+│  > - Use TDD. Run it through Karajan with architect and planner enabled,     │
+│  >   paranoid review mode. Coder claude, reviewer codex.                     │
+│                                                                              │
+│  Claude calls kj_run via MCP with:                                           │
+│    --enable-architect --enable-researcher --enable-planner --mode paranoid    │
+│                                                                              │
+└──────────────────────────────────────────────────────────────────────────────┘
+
+┌─ Terminal 2: kj-tail ────────────────────────────────────────────────────────┐
+│                                                                              │
+│  kj-tail v1.36.1 — .kj/run.log                                              │
+│                                                                              │
+│  ├─ 📋 Triage: medium (sw) — enabling researcher, architect, planner         │
+│  ├─ ⚙️ Preflight passed — all checks OK                                     │
+│  ├─ 🔬 Researcher: 8 files analyzed, 3 patterns, 5 constraints              │
+│  ├─ 🏗️ Architect: 3-layer design (routes → service → validators)            │
+│  ├─ 🧠 Planner: 6 steps — tests first, then routes, service, validators     │
+│  │                                                                           │
+│  ▶ Iteration 1/5                                                             │
+│  ├─ 🔨 Coder (claude): implemented 3 endpoints + 18 tests                   │
+│  ├─ 📋 TDD: PASS (3 src, 2 test files)                                      │
+│  ├─ 🔍 Sonar: Quality gate OK — 0 blockers                                  │
+│  ├─ 👁️ Reviewer (codex): REJECTED (2 blocking)                              │
+│  │   "Missing 404 for GET nonexistent booking"                               │
+│  │   "Cancel endpoint lacks idempotency test"                                │
+│  ├─ ⚖️ Solomon: approve_with_conditions (2 conditions)                      │
+│  │   "Add 404 response and test for GET /bookings/:id with unknown id"       │
+│  │   "Add test: cancel already-cancelled booking returns 409, not 500"       │
+│  │                                                                           │
+│  ▶ Iteration 2/5                                                             │
+│  ├─ 🔨 Coder (claude): fixed — 22 tests now                                 │
+│  ├─ 📋 TDD: PASS                                                            │
+│  ├─ 🔍 Sonar: OK                                                            │
+│  ├─ 👁️ Reviewer (codex): APPROVED                                           │
+│  ├─ 🧪 Tester: passed — coverage 94%, 22 tests                              │
+│  ├─ 🔒 Security: passed — 0 critical, 1 low (helmet recommended)            │
+│  ├─ 📊 Audit: CERTIFIED (with 3 advisory warnings)                          │
+│  │                                                                           │
+│  🏁 Result: APPROVED                                                         │
+│     🔬 Research: 8 files, 3 patterns identified                              │
+│     🗺 Plan: 6 steps (tests first)                                           │
+│     🧪 Coverage: 94%, 22 tests                                               │
+│     🔒 Security: passed                                                      │
+│     🔍 Sonar: OK                                                             │
+│     💰 Budget: $0.42 (claude: $0.38, codex: $0.04)                           │
+│                                                                              │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+[**▶ Watch the full pipeline demo**](https://karajancode.com#demo) — triage, architecture, TDD, SonarQube, code review, Solomon arbitration, security audit.
+
 ## The pipeline
 
 ```
@@ -123,16 +235,20 @@ Mix and match. Use Claude as coder and Codex as reviewer. Karajan auto-detects i
 
 ## MCP server — 20 tools
 
-Karajan is designed to be used as an MCP server inside your AI agent. After install, it auto-registers in Claude and Codex:
+After `npm install -g karajan-code`, the MCP server auto-registers in Claude and Codex. Manual config if needed:
 
 ```bash
-# Already done by npm install, but manual config if needed:
-# Add to ~/.claude.json → "mcpServers":
+# Claude: add to ~/.claude.json → "mcpServers":
 # { "karajan-mcp": { "command": "karajan-mcp" } }
+
+# Codex: add to ~/.codex/config.toml → [mcp_servers."karajan-mcp"]
+# command = "karajan-mcp"
 ```
 
 **20 tools** available: `kj_run`, `kj_code`, `kj_review`, `kj_plan`, `kj_audit`, `kj_scan`, `kj_doctor`, `kj_config`, `kj_report`, `kj_resume`, `kj_roles`, `kj_agents`, `kj_preflight`, `kj_status`, `kj_init`, `kj_discover`, `kj_triage`, `kj_researcher`, `kj_architect`, `kj_impeccable`.
 
+Use `kj-tail` in a separate terminal to see what the pipeline is doing in real time (see [Three ways to use Karajan](#three-ways-to-use-karajan)).
+
 ## The role architecture
 
 Every role in Karajan is defined by a markdown file — a plain document that describes how the agent should behave, what to check, and what good output looks like.

package/bin/kj-tail

@@ -1,10 +1,12 @@
 #!/usr/bin/env bash
-# kj-tail — Colorized, filtered tail for Karajan run logs
-# Usage: kj-tail [project-dir] [-v|--verbose]
+# kj-tail — Real-time pipeline monitor for Karajan Code
+# Follows the run log and displays colorized, filtered output.
 
 set -euo pipefail
 
-# Colors
+VERSION="1.36.0"
+
+# ── Colors ──────────────────────────────────────────────
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[0;33m'
@@ -13,58 +15,309 @@ CYAN='\033[0;36m'
 MAGENTA='\033[0;35m'
 GRAY='\033[0;90m'
 BOLD='\033[1m'
+DIM='\033[2m'
 RESET='\033[0m'
 
+# ── Defaults ────────────────────────────────────────────
 VERBOSE=false
+SHOW_AGENT_OUTPUT=false
+SHOW_TIMESTAMPS=false
+FOLLOW=true
+NUM_LINES=0
 PROJECT_DIR=""
 
-for arg in "$@"; do
-  case "$arg" in
-    -v|--verbose) VERBOSE=true ;;
-    *) PROJECT_DIR="$arg" ;;
+# ── Help ────────────────────────────────────────────────
+show_help() {
+  cat <<EOF
+${BOLD}kj-tail${RESET} — Real-time pipeline monitor for Karajan Code
+
+${BOLD}USAGE${RESET}
+  kj-tail [options] [project-dir]
+
+${BOLD}DESCRIPTION${RESET}
+  Follows the Karajan run log (<project>/.kj/run.log) and displays
+  colorized, filtered output. By default shows the same pipeline
+  progress view as 'kj run': stages, results, iterations, and errors.
+
+  Run this in a separate terminal while kj executes via MCP/CLI.
+
+${BOLD}OPTIONS${RESET}
+  -v, --verbose       Show agent heartbeats, budget, and metadata
+  -a, --agent-output  Show raw agent output lines (very noisy)
+  -t, --timestamps    Show timestamps on each line
+  -n, --lines <N>     Show last N lines then follow (default: follow only new)
+  -s, --snapshot      Show current log (no follow) — like 'cat' with colors
+  -h, --help          Show this help
+  --version           Show version
+
+${BOLD}EXAMPLES${RESET}
+  kj-tail                  # Follow current directory's run log
+  kj-tail /path/to/project # Follow a specific project's log
+  kj-tail -v               # Verbose: include heartbeats and budget
+  kj-tail -a               # Show everything including agent output
+  kj-tail -n 50            # Show last 50 lines then follow
+  kj-tail -s               # Snapshot: show full log and exit
+  kj-tail -t               # Show timestamps
+
+${BOLD}LOG LOCATION${RESET}
+  <project-dir>/.kj/run.log
+  Created automatically when kj_run, kj_code, or kj_review starts.
+
+EOF
+  exit 0
+}
+
+# ── Parse args ──────────────────────────────────────────
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help) show_help ;;
+    --version) echo "kj-tail $VERSION"; exit 0 ;;
+    -v|--verbose) VERBOSE=true; shift ;;
+    -a|--agent-output) SHOW_AGENT_OUTPUT=true; VERBOSE=true; shift ;;
+    -t|--timestamps) SHOW_TIMESTAMPS=true; shift ;;
+    -s|--snapshot) FOLLOW=false; shift ;;
+    -n|--lines)
+      shift
+      NUM_LINES="${1:-50}"
+      shift
+      ;;
+    -*)
+      echo -e "${RED}Unknown option: $1${RESET}" >&2
+      echo "Run 'kj-tail --help' for usage." >&2
+      exit 1
+      ;;
+    *) PROJECT_DIR="$1"; shift ;;
   esac
 done
 
 PROJECT_DIR="${PROJECT_DIR:-$(pwd)}"
 LOG_FILE="${PROJECT_DIR}/.kj/run.log"
 
+# ── Locate log ──────────────────────────────────────────
 if [[ ! -f "$LOG_FILE" ]]; then
-  echo -e "${RED}No run.log found at ${LOG_FILE}${RESET}"
-  echo "Usage: kj-tail [project-dir] [-v|--verbose]"
+  echo -e "${RED}No run log found at ${LOG_FILE}${RESET}"
+  echo ""
+  echo "The run log is created when Karajan starts a pipeline."
+  echo "Make sure you're in the project directory, or pass it as argument:"
+  echo ""
+  echo "  kj-tail /path/to/project"
+  echo ""
   exit 1
 fi
 
-echo -e "${BOLD}${CYAN}Karajan tail${RESET} ${GRAY}— ${LOG_FILE}${RESET}"
-echo -e "${GRAY}Ctrl+C to stop. Use -v to include agent output.${RESET}"
-echo ""
+# ── Filter & colorize ──────────────────────────────────
+filter_line() {
+  local line="$1"
+  local ts=""
+  local clean="$line"
 
-tail -F "$LOG_FILE" 2>/dev/null | while IFS= read -r line; do
-  # Strip timestamp (HH:MM:SS.mmm)
-  clean="${line#[0-9][0-9]:[0-9][0-9]:[0-9][0-9].[0-9][0-9][0-9] }"
-
-  # Strip [agent:output] tag — it's the default, no need to show it
-  clean="${clean/\[agent:output\] /}"
-
-  # Colorize by content
-  if [[ "$clean" == *"[coder:start]"* ]] || [[ "$clean" == *"[coder:done]"* ]] || [[ "$clean" == *"[coder]"* ]]; then
-    echo -e "${GREEN}${clean}${RESET}"
-  elif [[ "$clean" == *"[reviewer"* ]]; then
-    echo -e "${YELLOW}${clean}${RESET}"
-  elif [[ "$clean" == *"[sonar"* ]]; then
-    echo -e "${BLUE}${clean}${RESET}"
-  elif [[ "$clean" == *"[solomon"* ]]; then
-    echo -e "${MAGENTA}${clean}${RESET}"
-  elif [[ "$clean" == *"[iteration"* ]] || [[ "$clean" == *"[session"* ]] || [[ "$clean" == *"[kj_run]"* ]] || [[ "$clean" == *"[kj_code]"* ]]; then
-    echo -e "${BOLD}${CYAN}${clean}${RESET}"
-  elif [[ "$clean" == *"fail"* ]] || [[ "$clean" == *"error"* ]] || [[ "$clean" == *"FAIL"* ]] || [[ "$clean" == *"ERROR"* ]]; then
-    echo -e "${RED}${clean}${RESET}"
-  elif [[ "$clean" == *"[agent:heartbeat]"* ]]; then
-    echo -e "${GRAY}${clean}${RESET}"
-  elif [[ "$clean" == *"[standby]"* ]] || [[ "$clean" == *"standby"* ]]; then
-    echo -e "${YELLOW}${clean}${RESET}"
-  elif [[ "$clean" == "---"* ]]; then
-    echo -e "${BOLD}${clean}${RESET}"
-  else
-    echo "$clean"
+  # Extract and optionally strip timestamp (HH:MM:SS.mmm)
+  if [[ "$clean" =~ ^([0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3})\ (.*) ]]; then
+    ts="${BASH_REMATCH[1]}"
+    clean="${BASH_REMATCH[2]}"
   fi
-done
+
+  # Skip noise in default mode
+  if [[ "$VERBOSE" == "false" ]]; then
+    # Skip agent heartbeats
+    [[ "$clean" == *"[agent:heartbeat]"* ]] && return
+    [[ "$clean" == *"heartbeat"* ]] && return
+    # Skip budget lines
+    [[ "$clean" == *"Budget:"* ]] && return
+    # Skip agent raw output
+    [[ "$clean" == *"[agent:output]"* ]] && return
+    # Skip internal metadata
+    [[ "$clean" == *"[agent:start]"* ]] && return
+    [[ "$clean" == *"[agent:end]"* ]] && return
+    # Skip noisy JSON dumps (system init, tool lists, etc.)
+    [[ "${#clean}" -gt 500 ]] && return
+  fi
+
+  if [[ "$SHOW_AGENT_OUTPUT" == "false" ]]; then
+    # Skip raw agent output (often JSON/stream data)
+    [[ "$clean" == "{"* ]] && [[ "$clean" == *"}" ]] && return
+    [[ "$clean" == *'"type":'* ]] && [[ "${#clean}" -gt 200 ]] && return
+  fi
+
+  # Build prefix
+  local prefix=""
+  if [[ "$SHOW_TIMESTAMPS" == "true" ]] && [[ -n "$ts" ]]; then
+    prefix="${DIM}${ts}${RESET} "
+  fi
+
+  # ── Colorize by content ──────────────────────────────
+  # Session markers
+  if [[ "$clean" == "---"* ]]; then
+    echo -e "${prefix}${BOLD}${CYAN}${clean}${RESET}"
+    return
+  fi
+
+  # Stage: started/finished
+  if [[ "$clean" == *"started"* ]] && [[ "$clean" == *"[kj_"* ]]; then
+    echo -e "${prefix}${BOLD}${CYAN}▶ ${clean}${RESET}"
+    return
+  fi
+  if [[ "$clean" == *"finished"* ]] && [[ "$clean" == *"[kj_"* ]]; then
+    echo -e "${prefix}${BOLD}${GREEN}✓ ${clean}${RESET}"
+    return
+  fi
+
+  # Iterations
+  if [[ "$clean" == *"[iteration]"* ]] || [[ "$clean" == *"Iteration "* ]]; then
+    echo -e "${prefix}${BOLD}${clean}${RESET}"
+    return
+  fi
+
+  # Coder
+  if [[ "$clean" == *"[coder"* ]] || [[ "$clean" == *"Coder"* ]]; then
+    echo -e "${prefix}${GREEN}  ├─ 🔨 ${clean}${RESET}"
+    return
+  fi
+
+  # Reviewer
+  if [[ "$clean" == *"APPROVED"* ]]; then
+    echo -e "${prefix}${GREEN}  ├─ ✅ ${clean}${RESET}"
+    return
+  fi
+  if [[ "$clean" == *"REJECTED"* ]]; then
+    echo -e "${prefix}${RED}  ├─ ❌ ${clean}${RESET}"
+    return
+  fi
+  if [[ "$clean" == *"[reviewer"* ]]; then
+    echo -e "${prefix}${YELLOW}  ├─ 👁️  ${clean}${RESET}"
+    return
+  fi
+
+  # Solomon
+  if [[ "$clean" == *"[solomon"* ]] || [[ "$clean" == *"Solomon"* ]]; then
+    echo -e "${prefix}${MAGENTA}  ├─ ⚖️  ${clean}${RESET}"
+    return
+  fi
+
+  # Sonar
+  if [[ "$clean" == *"[sonar"* ]] || [[ "$clean" == *"SonarQube"* ]] || [[ "$clean" == *"Quality gate"* ]]; then
+    echo -e "${prefix}${BLUE}  ├─ 🔍 ${clean}${RESET}"
+    return
+  fi
+
+  # Tester
+  if [[ "$clean" == *"[tester"* ]] || [[ "$clean" == *"Tester"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 🧪 ${clean}${RESET}"
+    return
+  fi
+
+  # Security
+  if [[ "$clean" == *"[security"* ]] || [[ "$clean" == *"Security"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 🔒 ${clean}${RESET}"
+    return
+  fi
+
+  # Researcher
+  if [[ "$clean" == *"[researcher"* ]] || [[ "$clean" == *"Researcher"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 🔬 ${clean}${RESET}"
+    return
+  fi
+
+  # Architect
+  if [[ "$clean" == *"[architect"* ]] || [[ "$clean" == *"Architect"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 🏗️  ${clean}${RESET}"
+    return
+  fi
+
+  # Planner
+  if [[ "$clean" == *"[planner"* ]] || [[ "$clean" == *"Planner"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 🧠 ${clean}${RESET}"
+    return
+  fi
+
+  # Triage
+  if [[ "$clean" == *"[triage"* ]] || [[ "$clean" == *"Triage"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 📋 ${clean}${RESET}"
+    return
+  fi
+
+  # Audit
+  if [[ "$clean" == *"[audit"* ]] || [[ "$clean" == *"Audit"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 📊 ${clean}${RESET}"
+    return
+  fi
+
+  # Preflight
+  if [[ "$clean" == *"[preflight"* ]] || [[ "$clean" == *"Preflight"* ]]; then
+    echo -e "${prefix}${GRAY}  ├─ ⚙️  ${clean}${RESET}"
+    return
+  fi
+
+  # TDD
+  if [[ "$clean" == *"TDD"* ]] || [[ "$clean" == *"tdd"* ]]; then
+    echo -e "${prefix}${GREEN}  ├─ 📋 ${clean}${RESET}"
+    return
+  fi
+
+  # Errors / failures
+  if [[ "$clean" == *"fail"*  || "$clean" == *"FAIL"* || "$clean" == *"error"* || "$clean" == *"ERROR"* ]]; then
+    echo -e "${prefix}${RED}  ├─ ⚠️  ${clean}${RESET}"
+    return
+  fi
+
+  # Standby / rate limit
+  if [[ "$clean" == *"[standby]"* ]] || [[ "$clean" == *"standby"* ]] || [[ "$clean" == *"rate limit"* ]]; then
+    echo -e "${prefix}${YELLOW}  ├─ ⏸️  ${clean}${RESET}"
+    return
+  fi
+
+  # Model fallback
+  if [[ "$clean" == *"not supported"* ]] || [[ "$clean" == *"retrying with"* ]]; then
+    echo -e "${prefix}${YELLOW}  ├─ 🔄 ${clean}${RESET}"
+    return
+  fi
+
+  # Result line
+  if [[ "$clean" == *"Result:"* ]]; then
+    echo -e "${prefix}${BOLD}${GREEN}🏁 ${clean}${RESET}"
+    return
+  fi
+
+  # Budget (verbose only — already filtered above)
+  if [[ "$clean" == *"Budget:"* ]]; then
+    echo -e "${prefix}${GRAY}  ├─ 💰 ${clean}${RESET}"
+    return
+  fi
+
+  # Agent heartbeat (verbose only)
+  if [[ "$clean" == *"heartbeat"* ]] || [[ "$clean" == *"active —"* ]] || [[ "$clean" == *"elapsed"* ]]; then
+    echo -e "${prefix}${GRAY}  ├─ • ${clean}${RESET}"
+    return
+  fi
+
+  # Default
+  echo -e "${prefix}  ├─ ${clean}"
+}
+
+# ── Header ──────────────────────────────────────────────
+echo -e "${BOLD}${CYAN}kj-tail${RESET} ${DIM}v${VERSION} — ${LOG_FILE}${RESET}"
+if [[ "$FOLLOW" == "true" ]]; then
+  echo -e "${GRAY}Ctrl+C to stop${RESET}${VERBOSE:+ ${DIM}(verbose)${RESET}}"
+fi
+echo ""
+
+# ── Run ─────────────────────────────────────────────────
+if [[ "$FOLLOW" == "false" ]]; then
+  # Snapshot mode: show full log and exit
+  while IFS= read -r line; do
+    filter_line "$line"
+  done < "$LOG_FILE"
+  exit 0
+fi
+
+if [[ "$NUM_LINES" -gt 0 ]]; then
+  # Show last N lines then follow
+  tail -n "$NUM_LINES" -F "$LOG_FILE" 2>/dev/null | while IFS= read -r line; do
+    filter_line "$line"
+  done
+else
+  # Follow only new lines
+  tail -n 0 -F "$LOG_FILE" 2>/dev/null | while IFS= read -r line; do
+    filter_line "$line"
+  done
+fi

package/docs/README.es.md

@@ -129,33 +129,135 @@ Guias completas: [`docs/multi-instance.md`](multi-instance.md) | [`docs/install-
 
 `kj init` auto-detecta los agentes instalados. Si solo hay uno disponible, se asigna a todos los roles automaticamente.
 
-## Inicio rapido
+## Tres formas de usar Karajan
+
+Karajan instala **tres comandos**: `kj`, `kj-tail` y `karajan-mcp`.
+
+### 1. CLI — Directamente desde terminal
 
 ```bash
-# Ejecutar una tarea con defaults (claude=coder, codex=reviewer, TDD)
 kj run "Implementar autenticacion de usuario con JWT"
-
-# Solo coder (sin revision)
 kj code "Anadir validacion de inputs al formulario de registro"
-
-# Solo reviewer (revisar diff actual)
 kj review "Revisar los cambios de autenticacion"
+kj plan "Refactorizar la capa de base de datos"
+```
 
-# Generar un plan de implementacion
-kj plan "Refactorizar la capa de base de datos para usar connection pooling"
+### 2. MCP — Dentro de tu agente de IA
 
-# Pipeline completo con todas las opciones
-kj run "Corregir inyeccion SQL critica en el endpoint de busqueda" \
-  --coder claude \
-  --reviewer codex \
-  --reviewer-fallback claude \
-  --methodology tdd \
-  --enable-triage \
-  --enable-tester \
-  --enable-security \
-  --auto-commit \
-  --auto-push \
-  --max-iterations 5
+El caso de uso principal. Karajan corre como servidor MCP dentro de Claude Code, Codex o Gemini. El agente tiene acceso a 20 herramientas (`kj_run`, `kj_code`, `kj_review`, etc.) y delega el trabajo pesado al pipeline de Karajan.
+
+```
+Tu → Claude Code → kj_run (via MCP) → triage → coder → sonar → reviewer → tester → security
+```
+
+**El problema**: cuando Karajan corre dentro de un agente de IA, pierdes visibilidad. El agente te muestra el resultado final, pero no las etapas del pipeline, iteraciones o decisiones de Solomon en tiempo real.
+
+### 3. kj-tail — Monitorizar desde otro terminal
+
+**La herramienta companera.** Abre un segundo terminal en el **mismo directorio del proyecto** donde esta trabajando tu agente de IA:
+
+```bash
+kj-tail
+```
+
+Veras la salida del pipeline en vivo — etapas, resultados, iteraciones, errores — tal como ocurren.
+
+```bash
+kj-tail                  # Seguir pipeline en tiempo real (por defecto)
+kj-tail -v               # Verbose: incluir heartbeats de agente y presupuesto
+kj-tail -t               # Mostrar timestamps
+kj-tail -s               # Snapshot: mostrar log actual y salir
+kj-tail -n 50            # Mostrar ultimas 50 lineas y seguir
+kj-tail --help           # Todas las opciones
+```
+
+> **Importante**: `kj-tail` debe ejecutarse desde el mismo directorio donde el agente de IA esta trabajando. Lee `<proyecto>/.kj/run.log`, que se crea cuando Karajan arranca un pipeline via MCP.
+
+**Flujo tipico:**
+
+```
+┌──────────────────────────┐    ┌──────────────────────────┐
+│  Terminal 1               │    │  Terminal 2               │
+│                           │    │                           │
+│  $ claude                 │    │  $ kj-tail                │
+│  > implementa la          │    │                           │
+│    siguiente tarea        │    │  ├─ 📋 Triage: medium     │
+│    prioritaria            │    │  ├─ 🔬 Researcher ✅      │
+│                           │    │  ├─ 🧠 Planner ✅         │
+│  (Claude llama a kj_run   │    │  ├─ 🔨 Coder ✅           │
+│   via MCP — solo ves      │    │  ├─ 🔍 Sonar: OK         │
+│   el resultado final)     │    │  ├─ 👁️ Reviewer ❌        │
+│                           │    │  ├─ ⚖️ Solomon: 2 cond.   │
+│                           │    │  ├─ 🔨 Coder (iter 2) ✅  │
+│                           │    │  ├─ ✅ Review: APPROVED    │
+│                           │    │  ├─ 🧪 Tester: passed     │
+│                           │    │  └─ 🏁 Result: APPROVED   │
+└──────────────────────────┘    └──────────────────────────┘
+```
+
+**Ejemplo con pipeline completo** — tarea compleja con todos los roles:
+
+```
+┌─ Terminal 1 ─────────────────────────────────────────────────────────────────┐
+│                                                                              │
+│  $ claude                                                                    │
+│                                                                              │
+│  > Construye una API REST para un sistema de reservas. Requisitos:           │
+│  > - Express + TypeScript con validacion Zod en cada endpoint                │
+│  > - Endpoints: POST /bookings, GET /bookings/:id,                           │
+│  >   PATCH /bookings/:id/cancel                                              │
+│  > - Una reserva tiene: id, guestName, roomType (standard|suite|penthouse),  │
+│  >   checkIn, checkOut, status (confirmed|cancelled)                         │
+│  > - Validar: checkOut posterior a checkIn, sin fechas pasadas,              │
+│  >   roomType debe ser un valor valido del enum                              │
+│  > - Cancelar devuelve 409 si ya esta cancelada                              │
+│  > - Usa TDD. Ejecutalo con Karajan con architect y planner activos,         │
+│  >   modo paranoid. Coder claude, reviewer codex.                            │
+│                                                                              │
+│  Claude llama a kj_run via MCP con:                                          │
+│    --enable-architect --enable-researcher --enable-planner --mode paranoid    │
+│                                                                              │
+└──────────────────────────────────────────────────────────────────────────────┘
+
+┌─ Terminal 2: kj-tail ────────────────────────────────────────────────────────┐
+│                                                                              │
+│  kj-tail v1.36.1 — .kj/run.log                                              │
+│                                                                              │
+│  ├─ 📋 Triage: medium (sw) — activando researcher, architect, planner        │
+│  ├─ ⚙️ Preflight passed — all checks OK                                     │
+│  ├─ 🔬 Researcher: 8 ficheros, 3 patrones, 5 restricciones                  │
+│  ├─ 🏗️ Architect: diseno 3 capas (routes → service → validators)            │
+│  ├─ 🧠 Planner: 6 pasos — tests primero, luego rutas, servicio, validadores │
+│  │                                                                           │
+│  ▶ Iteracion 1/5                                                             │
+│  ├─ 🔨 Coder (claude): 3 endpoints + 18 tests                               │
+│  ├─ 📋 TDD: PASS (3 src, 2 test)                                            │
+│  ├─ 🔍 Sonar: Quality gate OK                                               │
+│  ├─ 👁️ Reviewer (codex): REJECTED (2 blocking)                              │
+│  │   "Falta 404 para GET booking inexistente"                                │
+│  │   "Endpoint cancel sin test de idempotencia"                              │
+│  ├─ ⚖️ Solomon: approve_with_conditions (2 condiciones)                     │
+│  │   "Anadir respuesta 404 y test para GET /bookings/:id con id desconocido" │
+│  │   "Anadir test: cancelar reserva ya cancelada devuelve 409, no 500"       │
+│  │                                                                           │
+│  ▶ Iteracion 2/5                                                             │
+│  ├─ 🔨 Coder (claude): corregido — 22 tests                                 │
+│  ├─ 📋 TDD: PASS                                                            │
+│  ├─ 🔍 Sonar: OK                                                            │
+│  ├─ 👁️ Reviewer (codex): APPROVED                                           │
+│  ├─ 🧪 Tester: passed — cobertura 94%, 22 tests                             │
+│  ├─ 🔒 Security: passed — 0 criticos, 1 bajo (helmet recomendado)           │
+│  ├─ 📊 Audit: CERTIFIED (3 advertencias)                                    │
+│  │                                                                           │
+│  🏁 Resultado: APPROVED                                                      │
+│     🔬 Investigacion: 8 ficheros, 3 patrones                                 │
+│     🗺 Plan: 6 pasos (tests primero)                                         │
+│     🧪 Cobertura: 94%, 22 tests                                              │
+│     🔒 Seguridad: OK                                                         │
+│     🔍 Sonar: OK                                                             │
+│     💰 Presupuesto: $0.42 (claude: $0.38, codex: $0.04)                      │
+│                                                                              │
+└──────────────────────────────────────────────────────────────────────────────┘
 ```
 
 ## Comandos CLI

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.36.0",
+  "version": "1.36.1",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -38,6 +38,7 @@
   ],
   "bin": {
     "kj": "bin/kj.js",
+    "kj-tail": "bin/kj-tail",
     "karajan-mcp": "bin/karajan-mcp.js"
   },
   "scripts": {