karajan-code 2.34.0 → 3.1.0

package/README.md

@@ -13,16 +13,18 @@
   <a href="https://www.npmjs.com/package/karajan-code"><img src="https://img.shields.io/npm/dw/karajan-code.svg" alt="npm downloads"></a>
   <a href="https://github.com/manufosela/karajan-code/actions"><img src="https://github.com/manufosela/karajan-code/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://www.gnu.org/licenses/agpl-3.0"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue.svg" alt="License"></a>
-  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node.js"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg" alt="Node.js"></a>
   <a href="https://github.com/manufosela/homebrew-tap"><img src="https://img.shields.io/badge/homebrew-tap-orange.svg" alt="Homebrew"></a>
 </p>
 
 <p align="center">
-  <a href="docs/README.es.md">Leer en Español</a> · <a href="https://karajancode.com">Documentation</a>
+  <a href="docs/README.es.md">Leer en Español</a> · <a href="https://karajancode.com">Documentation</a> · <a href="https://planning-game-xp.web.app/public/?project=Karajan%20Code">Public roadmap</a>
 </p>
 
 ---
 
+> **v3.1.0 released** — first minor on v3. Bundles tool-correctness judge and TDD-discipline as new quality gates, `kj clean --all/--vector-stores/--repo` for housekeeping, `kj sync --apply` closing the SPDD loop, semantic test-diet auditor (498 test files, 0 loss-of-meaning findings), HU Board structural refactor (17 PRs), and a batch of security + flake fixes. No breaking changes; drop-in upgrade from v3.0.0. Full notes in [CHANGELOG.md](CHANGELOG.md).
+
 You describe what you want to build. Karajan orchestrates multiple AI agents to plan it, implement it, test it, review it with SonarQube, and iterate. No babysitting required.
 
 ## What is Karajan?
@@ -60,7 +62,6 @@ While Genkit, Mastra, LangChain and Vercel AI SDK call `/v1/messages`, Karajan o
 | Calls provider HTTP API (`/v1/messages`, etc.) | ❌ Delegates to CLIs | ✅ |
 | Orchestrates existing AI CLIs (claude, codex, gemini, aider, opencode) as subprocesses | ✅ | ❌ |
 | Depends on cloud infrastructure | ❌ Fully local | ⚠️ Varies |
-| Vanilla JS (no TypeScript required) | ✅ | ⚠️ TS-first |
 | Token billing | **Uses your existing CLI subscriptions** | Pay per API call |
 
 Two technical facts worth keeping straight:
@@ -105,28 +106,79 @@ docker run --rm -v $(pwd):/workspace karajan-code kj --version
 ```
 
 **Python**:
+
+The Python wrapper is a thin shim over the `kj` binary, useful when your stack lives in `pyproject.toml` / `requirements.txt` and you want to invoke Karajan from a venv.
+
 ```bash
-cd wrappers/python && pip install .
+# Option A — once published to PyPI (recommended)
+pip install karajan-code
+
+# Option B — install from the cloned repo (dev)
+git clone https://github.com/manufosela/karajan-code.git
+cd karajan-code/wrappers/python
+pip install .
 ```
 
+Both options expect the `kj` binary to be on your `PATH` (via one of the methods above) — the Python wrapper does not vendor it.
+
 That's it. `kj init` auto-detects your installed agents and installs RTK for token optimization.
 
 ### Optional scanners for `kj audit` + `kj webperf`
 
-Karajan auto-skips any scanner that isn't installed. Add the ones that match your projects:
+None of these are required. Karajan auto-skips any scanner that isn't installed, so the pipeline runs fine with zero of them. Add the ones that match your projects to get more signal:
 
-| Tool | Install | What you get |
-|------|---------|--------------|
-| **SonarQube** | `docker compose -f ~/sonarqube/docker-compose.yml up -d` | Code quality + security rules with line-precision in `kj audit` |
-| **OSV-Scanner** | `go install github.com/google/osv-scanner@latest` | Dependency CVE coverage broader than `npm audit` |
-| **Semgrep** | `pipx install semgrep` | SAST: XSS, SQLi, taint flow, secrets — equivalent to `snyk code`, free for OSS |
-| **Lighthouse** | `npm install -g lighthouse` | Core Web Vitals + opportunities for `kj webperf` (auto-feeds `kj audit`) |
+| Tool | Scope | Install | Installable from `kj init`? | What you get |
+|------|-------|---------|-----------------------------|--------------|
+| **SonarQube** | Any stack | `docker compose -f ~/sonarqube/docker-compose.yml up -d` | ✅ Yes (wizard configures Docker container + token) | Code quality + security rules with line-precision in `kj audit` |
+| **OSV-Scanner** | Any stack | `go install github.com/google/osv-scanner@latest` | ❌ No (install manually) | Dependency CVE coverage broader than `npm audit` |
+| **Semgrep** | Any stack | `pipx install semgrep` | ❌ No (install manually) | SAST: XSS, SQLi, taint flow, secrets — equivalent to `snyk code`, free for OSS |
+| **Lighthouse** | **Frontend only** | `npm install -g lighthouse` | ❌ No (install manually) | Core Web Vitals + opportunities for `kj webperf` (auto-feeds `kj audit`) |
 
 Skip any per-run with `--no-sonar`, `--no-osv`, `--no-semgrep`. See [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md#optional-scanners--kj-audit--kj-webperf) for full table.
 
-## Three ways to use Karajan
+## Footprint & hardware requirements
+
+Karajan ships as **layers you opt into**. The base CLI is tiny (~5 MB). Heavier pieces — Ollama for local RAG, SonarQube for static analysis, the `qmd` model cache for global semantic search — are only pulled if you ask for them. None of them are pulled during `npm install`.
+
+### What lives where
+
+| Layer | Size | When you pay it | Notes |
+| --- | --- | --- | --- |
+| `karajan-code` npm tarball | 5.2 MB / 555 files | Always | The CLI itself |
+| `node_modules/` (global) | ~208 MB | After `npm install -g karajan-code` | Standard for any Node global; SEA binary skips it |
+| `~/.karajan/` (state) | ~40 MB typical | After first `kj run` | Sessions, plans, audit history, HU board DB. `kj clean` prunes it |
+| Ollama Docker image | 6.55 GB | If you use the **local** RAG embedder (default since v2.26) | Auto-pulled in the background on first `kj rag index` (~5 min) |
+| Ollama embedding model | ~260 MB | First `kj rag index` | `nomic-embed-text` by default; lives inside the Ollama container |
+| SonarQube Docker image | 1.47 GB | If you enable Sonar in `kj init` | Optional; `kj audit` runs fine without it |
+| `qmd` model cache | ~2.2 GB | If you use `qmd query` for global semantic search | Local LLMs for query expansion + rerank; entirely off-box otherwise |
+
+### Three install profiles
+
+| Profile | Disk | What's enabled | Trade-off |
+| --- | --- | --- | --- |
+| **Minimum** | ~250 MB | `kj`, audits, reviews, RAG with **cloud embedder** (OpenAI / Voyage / Cohere / Mistral) | Needs an API key; no offline RAG |
+| **Recommended** | ~8.5 GB | + Ollama (local RAG, no API key) + SonarQube | Offline-capable; needs Docker running |
+| **Full house** | ~11 GB | + `qmd` (semantic search across personal docs/memory) | All features local; biggest footprint |
+
+### Hardware
+
+| Profile | CPU | RAM | Free disk | Notes |
+| --- | --- | --- | --- | --- |
+| **Minimum** | 2 cores | 4 GB | 1 GB | Cloud embedder only; pipeline peaks ~1 GB RAM |
+| **Recommended** | 4–8 cores | 8–12 GB | 10–15 GB | Docker + Ollama running in background |
+| **Ideal** | 16+ cores | 32+ GB | 50+ GB | Multiple Docker stacks, large repos, big audit history |
+
+### Operational notes
+
+- **No GPU required.** Embeddings are CPU-only by default; cloud embedders push the compute off-box entirely.
+- **Pipeline RAM peak**: 1–2 GB per `kj run` (one orchestrator + one coder + one reviewer subprocess at a time).
+- **SQLite is in-process.** No separate DB daemon. `~/.karajan/` is a folder, not a service.
+- **First-run Ollama pull**: ~5 min in the background; you can keep working — `kj` falls back to a cloud embedder if Ollama isn't ready yet.
+- **Runtime**: Node.js ≥ 22.22.1 (Active LTS). v3.0.0 dropped Node 20 support. Use `kj doctor` to verify your environment.
 
-Karajan installs **three commands**: `kj`, `kj-tail`, and `karajan-mcp`.
+## Two ways to use Karajan
+
+Karajan installs **three commands**: `kj` (the CLI), `karajan-mcp` (the MCP server) and `kj-tail` (a monitoring companion). There are two *ways to use it* — CLI or MCP — and `kj-tail` is the monitor you keep open in a second terminal while either mode is running.
 
 ### 1. CLI: direct from terminal
 
@@ -164,13 +216,13 @@ This is the primary use case. Karajan runs as an MCP server inside Claude Code,
 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 23 tools (`kj_run`, `kj_code`, `kj_review`, etc.) and uses them as needed.
+The MCP server auto-registers during `npm install`. Your AI agent sees 27 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
+### Companion: `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:
+`kj-tail` is **not a third way to run Karajan** — it's a read-only monitor for whichever of the two ways above you're using. Open a second terminal in the **same project directory** where the pipeline is running, and run:
 
 ```bash
 kj-tail
@@ -221,7 +273,13 @@ iteration: coder → refactorer? → guard(output) → guard(perf) → sonar?
 post-loop: tester? → security? → perf? → impeccable? → audit?
 ```
 
-**24 stages** across three phases: 18 AI-agent-backed roles (table below), 6 deterministic stages without an LLM call (`intent`, `skills`, `acceptance`, `guard(output)`, `guard(perf)`, `tdd`). Two extra classes (`commiter`, `repairer`) are post-approval / internal helpers, not standalone pipeline stages. Each AI role is executed by the agent you choose:
+**24 stages max** across three phases: 18 AI-agent-backed roles (table below), 6 deterministic stages without an LLM call (`intent`, `skills`, `acceptance`, `guard(output)`, `guard(perf)`, `tdd`). Two extra classes (`commiter`, `repairer`) are post-approval / internal helpers, not standalone pipeline stages.
+
+> **Karajan is multi-language.** The 24 figure is the upper bound for a frontend project. On a **backend / library / CLI** task, three stages are skipped automatically because they have nothing to assess: `impeccable` (UI/UX audit), `perf` (Core Web Vitals via Lighthouse) and `guard(perf)` (frontend anti-pattern check). That leaves a typical pipeline at **~21 stages** for backend / systems / CLI / data work, with the same triage rules trimming further on trivial tasks. Stage selection is auto-detected from the repo (presence of frontend frameworks, `index.html`, `package.json` browser fields, etc.) — no flag required.
+>
+> The **minimum useful pipeline** on a `trivial` task is roughly: `intent → triage → coder → guard(output) → tdd → reviewer → brain` (~7 stages). Triage decides.
+
+Each AI role is executed by the agent you choose:
 
 | Role | What it does | Default |
 |------|-------------|---------|
@@ -263,7 +321,7 @@ post-loop: tester? → security? → perf? → impeccable? → audit?
 
 Mix and match. Use Claude as coder and Codex as reviewer. Karajan auto-detects installed agents during `kj init`.
 
-## MCP server (23 tools)
+## MCP server (27 tools)
 
 After `npm install -g karajan-code`, the MCP server auto-registers in Claude and Codex. Manual config if needed:
 
@@ -275,7 +333,7 @@ After `npm install -g karajan-code`, the MCP server auto-registers in Claude and
 # command = "karajan-mcp"
 ```
 
-**24 tools** available: `kj_run`, `kj_code`, `kj_review`, `kj_plan`, `kj_board`, `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`, `kj_hu`, `kj_skills`, `kj_suggest`.
+**27 tools** available: `kj_run`, `kj_code`, `kj_review`, `kj_plan`, `kj_board`, `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_hu`, `kj_skills`, `kj_suggest`, `kj_undo`, `kj_clean`, `kj_rag_query`, `kj_rag_index`.
 
 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)).
 
@@ -308,20 +366,20 @@ Karajan auto-detects and auto-configures everything it can:
 
 No per-project configuration required. If you want to customize, config is layered: session > project > global.
 
-## Why vanilla JavaScript?
+## Recommended companions
 
-Not nostalgia, not stubbornness. I've been using JavaScript since 1997, when Brendan Eich created it in a week and changed the lives of everyone building for the web. I know its guts, its bugs, its quirks. And I know that whoever truly understands JS turns those bugs into features. TypeScript exists so that developers used to strongly-typed languages don't panic when they see JS. I respect that. But I don't need it. Tests are my type safety. JSDoc and a good IDE are my intellisense. And not having a compiler between the code and me is what lets me ship 57 releases in 45 days without fear.
+None of these are required. Karajan runs fine on its own. They're tools that, when present, Karajan can take advantage of — or that help *you* work better around Karajan.
 
-[Why vanilla JavaScript: the long version](docs/why-vanilla-js.md)
+| Tool | Invoked by | Why |
+|------|-----------|-----|
+| [**RTK**](https://github.com/rtk-ai/rtk) | Karajan (auto, on Bash outputs) | Reduces token consumption by 60-90% on Bash command outputs |
+| [**QMD**](https://github.com/manufosela/qmd) | You (CLI / MCP), complementary to RAG | Semantic search engine over Markdown corpora — works alongside `kj rag query` when you want a richer index over your own docs |
+| [**GitHub MCP**](https://github.com/github/github-mcp-server) | Your AI agent (via MCP) | Create PRs, manage issues directly from the agent |
+| [**Chrome DevTools MCP**](https://github.com/ChromeDevTools/chrome-devtools-mcp) | Your AI agent (via MCP) | Verify UI changes visually after frontend modifications |
 
-## Recommended companions
+## Why vanilla JavaScript?
 
-| Tool | Why |
-|------|-----|
-| [**RTK**](https://github.com/rtk-ai/rtk) | Reduces token consumption by 60-90% on Bash command outputs |
-| [**Planning Game MCP**](https://github.com/manufosela/planning-game-xp-mcp) | Agile project management (tasks, sprints, estimation), XP-native |
-| [**GitHub MCP**](https://github.com/github/github-mcp-server) | Create PRs, manage issues directly from the agent |
-| [**Chrome DevTools MCP**](https://github.com/ChromeDevTools/chrome-devtools-mcp) | Verify UI changes visually after frontend modifications |
+Tests are the type safety; JSDoc + a good IDE are the intellisense; no compiler in the loop is what makes shipping fast. The long version is anecdotal and lives in [docs/why-vanilla-js.md](docs/why-vanilla-js.md).
 
 ## Contributing
 
@@ -329,19 +387,42 @@ Not nostalgia, not stubbornness. I've been using JavaScript since 1997, when Bre
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Run ~2599 tests with Vitest
+npm test              # Run ~5 368 tests across 482 files with Vitest
 npm run validate      # Lint + test
 ```
 
 Issues and pull requests welcome. If something doesn't work as documented, [open an issue](https://github.com/manufosela/karajan-code/issues). That's the most useful contribution at this stage.
 
-## Telemetry
+## Privacy & telemetry
+
+**Telemetry is OFF by default.** The `kj init` wizard asks once, in your OS
+language, with a plain-text "yes / no" prompt:
+
+> *Help improve Karajan by sending anonymous telemetry to the project?*
+> *(version, OS, commands, pipeline duration — no code, no tasks, no personal data)*
+
+Answer "yes" once and `telemetry: true` is persisted to `~/.karajan/kj.config.yml`.
+Anything else — undefined, missing key, `false`, fresh install with no wizard run —
+keeps it off. There is no hidden default-on path.
+
+### What gets sent (when enabled)
+
+Three event types, anonymous, no userID / email / IP collected by Karajan itself:
+
+| Event | When | Payload |
+|---|---|---|
+| `install` | first `kj init` | `version`, `os`, `node`, `ts` |
+| `cli_command` | each `kj <subcommand>` | `version`, `os`, `node`, `ts`, `command` |
+| `pipeline_complete` | end of `kj run` | `version`, `os`, `node`, `ts`, `mode`, `agent`, `duration_s`, `success`, `taskType` |
+
+Endpoint: `https://karajan-code.web.app/api/telemetry` (POST, 3 s timeout, fire-and-forget).
+Implementation: [`src/utils/telemetry.js`](src/utils/telemetry.js).
 
-Karajan collects anonymous usage statistics to improve the tool:
-version, OS, command used, pipeline duration and success rate.
-No code, task descriptions, or personal data is ever sent.
+### Flip it later
 
-Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
+Open `~/.karajan/kj.config.yml`, set `telemetry: true` (opt in) or `telemetry: false` (opt out),
+save. Or re-run `kj init` and answer the prompt again. Set `KJ_DEBUG=1` to see telemetry
+errors on stderr (otherwise failures are silent — telemetry never blocks the pipeline).
 
 ## Recent releases
 
@@ -533,7 +614,7 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 >
 > KJC-BUG-0058 (PR #798, reported by [@aitormf](https://github.com/aitormf)): a session that stopped during Sonar would re-run the full pre-loop on `kj resume <id>` — HU-reviewer, intent, discover, triage, domainCurator, **researcher, architect, planner** all from scratch — doubling token cost and breaking the value-prop of the command. Root cause: `resumeFlow` (flow-runner.js:280) called `runFlow` without rehydrating stage state, and the session never persisted stage outputs in the first place. **Fix**: two new mutators in `src/session/mutators.js` (`setStageResult` mirrors into `stage_results[name]` + `stages_completed[]`; `setStageBundle` adds `stage_bundles[name]` for cross-stage context like `researchContext`, `architectContext`, `plannedTask`). Two closures inside `runPreLoopStages` (`persistStage` + `resumeSkip`) wrap every cacheable stage. `init-context.js` rehydrates `ctx.stageResults` from the loaded session before invoking the pre-loop. Triage is *not* skipped on resume — it produces `roleOverrides` the Brain decisor depends on and is cheap to re-run.
 >
-> KJC-BUG-0060 (PR #797, reported by mjfosela during the v2.19.3 release): `git checkout main` reported `[ahead 27]` of origin/main. Every commit was titled `initial commit`, authored by `manufosela@gmail.com`, and had the **exact same tree as its parent** — completely empty. The reflog held **2 495 such SHAs** accumulated since April 2026. None ever reached origin/main (gh push / CI would have rejected them) so runtime impact was zero, but the local history was noisy and on every release it looked like a sync loss. Root cause: `src/orchestrator/config-init.js::autoInit()` guarded with `!(await exists(projectDir/.git))`, which fails two ways: (a) dogfooding kj on karajan-code itself from a subdir → `exists()` returns false → `git init` re-initializes the *parent's* `.git/` (idempotent, harmless) → `git commit --allow-empty` then resolves upward and lands an empty commit on the parent's main; (b) transient FS hicks (EACCES/ENOENT) flip `exists()` to a false negative. **Fix**: switch the static FS probe for `git rev-parse --is-inside-work-tree`, which performs the same upward search git would use for the commit itself — guard cannot disagree with the operation it guards. And drop the `git commit --allow-empty -m "initial commit"` step entirely: no downstream stage needs a root commit; the 2 495 zombies never broke anything, the seed was decorative and turned out to be the actual user-visible symptom.
+> KJC-BUG-0060 (PR #797, reported by @manufosela during the v2.19.3 release): `git checkout main` reported `[ahead 27]` of origin/main. Every commit was titled `initial commit`, authored by the local git identity, and had the **exact same tree as its parent** — completely empty. The reflog held **2 495 such SHAs** accumulated since April 2026. None ever reached origin/main (gh push / CI would have rejected them) so runtime impact was zero, but the local history was noisy and on every release it looked like a sync loss. Root cause: `src/orchestrator/config-init.js::autoInit()` guarded with `!(await exists(projectDir/.git))`, which fails two ways: (a) dogfooding kj on karajan-code itself from a subdir → `exists()` returns false → `git init` re-initializes the *parent's* `.git/` (idempotent, harmless) → `git commit --allow-empty` then resolves upward and lands an empty commit on the parent's main; (b) transient FS hicks (EACCES/ENOENT) flip `exists()` to a false negative. **Fix**: switch the static FS probe for `git rev-parse --is-inside-work-tree`, which performs the same upward search git would use for the commit itself — guard cannot disagree with the operation it guards. And drop the `git commit --allow-empty -m "initial commit"` step entirely: no downstream stage needs a root commit; the 2 495 zombies never broke anything, the seed was decorative and turned out to be the actual user-visible symptom.
 >
 > **If your `kj resume` re-runs researcher/architect, or your `git status` shows mysterious `[ahead N]` after dogfooding kj on a kj-linked source tree, upgrade to v2.19.4.**
 >
@@ -589,9 +670,10 @@ See [CHANGELOG.md](./CHANGELOG.md) for the full version history.
 
 ---
 
-Built by [@manufosela](https://github.com/manufosela). Head of Engineering at Geniova Technologies, co-organizer of NodeJS Madrid, author of [Liderazgo Afectivo](https://www.liderazgoafectivo.com). 90+ npm packages published.
+Built by [@manufosela](https://github.com/manufosela). Engineering Lead, co-organizer of NodeJS Madrid, author of [Liderazgo Afectivo](https://www.liderazgoafectivo.com). 100+ npm packages published.
 
 ### Contributors
 
-- [@aitormf](https://github.com/aitormf) — OpenCode agent (5th built-in agent)
+- [@aitormf](https://github.com/aitormf) — OpenCode agent (5th built-in agent), early-bug reporter on resume/standby flow
+- [@jorgecasar](https://github.com/jorgecasar) — Model registry, display refactor, valibot config proposals; multiple issue triages
 - [@reiaguilera](https://github.com/reiaguilera) — Beta testing, feature proposals, and quality feedback

package/bin/kj-rag-mcp.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * kj-rag-mcp — standalone MCP server exposing only RAG tools.
+ *
+ * For external IDEs (Cursor, Windsurf, Continue, Zed) that want semantic
+ * search over a Karajan-indexed project without pulling in the full 27-tool
+ * orchestrator surface. Re-uses handleRagQuery / handleRagIndex from the
+ * main server, so behavior stays in sync with `karajan-mcp`.
+ */
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { handleRagQuery, handleRagIndex } from "../src/mcp/handlers/rag-handler.js";
+import { responseText, enrichedFailPayload } from "../src/mcp/shared-helpers.js";
+import { setupOrphanGuard } from "../src/mcp/orphan-guard.js";
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PKG_PATH = path.resolve(MODULE_DIR, "../package.json");
+const VERSION = JSON.parse(readFileSync(PKG_PATH, "utf8")).version;
+
+const RAG_TOOLS = [
+  {
+    name: "kj_rag_query",
+    description: "Semantic search across the indexed Karajan plans, onboarding briefs and (optionally) project source code. Returns the top-K nearest chunks with metadata so the agent can quote prior decisions or locate where a concept was last implemented. Empty until `kj_rag_index` has run at least once.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "Natural-language query." },
+        topK: { type: "number", description: "Max hits to return. Default 5." },
+        scope: { type: "string", description: "'plans' | 'code' | 'onboarding' | 'all' (default)." },
+        projectDir: { type: "string", description: "Absolute path to the project directory." }
+      },
+      required: ["text"]
+    }
+  },
+  {
+    name: "kj_rag_index",
+    description: "(Re)index this project's Karajan-managed assets into the local vector store. Idempotent. Pass `withSources: true` to also index project source files. Required as a one-time bootstrap before `kj_rag_query` returns anything.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        withSources: { type: "boolean", description: "Also index source files under projectDir. Default false." },
+        projectDir: { type: "string", description: "Absolute path to the project directory." }
+      }
+    }
+  }
+];
+
+const mcpServer = new McpServer(
+  { name: "kj-rag-mcp", version: VERSION },
+  { capabilities: { tools: {}, logging: {} } }
+);
+const server = mcpServer.server;
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: RAG_TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const name = request.params?.name;
+  const args = request.params?.arguments || {};
+  try {
+    if (name === "kj_rag_query") return responseText(await handleRagQuery(args, server));
+    if (name === "kj_rag_index") return responseText(await handleRagIndex(args, server));
+    return responseText({ ok: false, error: `Unknown tool: ${name}` });
+  } catch (error) {
+    return responseText(enrichedFailPayload(error, name));
+  }
+});
+
+setupOrphanGuard();
+
+const transport = new StdioServerTransport();
+await mcpServer.connect(transport);

package/docs/README.es.md

@@ -18,7 +18,7 @@
 </p>
 
 <p align="center">
-  <a href="../README.md">Read in English</a> · <a href="https://karajancode.com">Documentacion</a>
+  <a href="../README.md">Read in English</a> · <a href="https://karajancode.com">Documentacion</a> · <a href="https://planning-game-xp.web.app/public/?project=Karajan%20Code">Roadmap publico</a>
 </p>
 
 ---
@@ -111,7 +111,7 @@ Este es el caso de uso principal. Karajan corre como servidor MCP dentro de Clau
 Tu → Claude Code → kj_run (via MCP) → triage → coder → sonar → reviewer → tester → security
 ```
 
-El servidor MCP se auto-registra durante `npm install`. Tu agente de IA ve 23 herramientas (`kj_run`, `kj_code`, `kj_review`, `kj_hu`, etc.) y las usa segun necesite.
+El servidor MCP se auto-registra durante `npm install`. Tu agente de IA ve 27 herramientas (`kj_run`, `kj_code`, `kj_review`, `kj_hu`, etc.) y las usa segun necesite.
 
 **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.
 
@@ -188,7 +188,7 @@ post-loop: tester? → security? → perf? → impeccable? → audit?
 
 Mezcla y combina. Usa Claude como coder y Codex como reviewer. Karajan auto-detecta agentes instalados durante `kj init`.
 
-## Servidor MCP (23 herramientas)
+## Servidor MCP (27 herramientas)
 
 Tras `npm install -g karajan-code`, el servidor MCP se auto-registra en Claude y Codex. Config manual si es necesario:
 
@@ -200,7 +200,7 @@ Tras `npm install -g karajan-code`, el servidor MCP se auto-registra en Claude y
 # command = "karajan-mcp"
 ```
 
-**23 herramientas** disponibles: `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`, `kj_hu`, `kj_skills`, `kj_suggest`.
+**27 herramientas** disponibles: `kj_run`, `kj_code`, `kj_review`, `kj_plan`, `kj_board`, `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_hu`, `kj_skills`, `kj_suggest`, `kj_undo`, `kj_clean`, `kj_rag_query`, `kj_rag_index`.
 
 Usa `kj-tail` en un terminal separado para ver lo que el pipeline esta haciendo en tiempo real (ver [Tres formas de usar Karajan](#tres-formas-de-usar-karajan)).
 
@@ -254,7 +254,7 @@ No es nostalgia ni cabezoneria. Es que llevo usando JavaScript desde 1997, cuand
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Ejecutar ~2599 tests con Vitest
+npm test              # Ejecutar ~5 368 tests en 482 ficheros con Vitest
 npm run validate      # Lint + test
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.34.0",
+  "version": "3.1.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -24,7 +24,7 @@
     "cli"
   ],
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=22.22.1"
   },
   "imports": {
     "#utils/*": "./src/utils/*",
@@ -49,7 +49,8 @@
   "bin": {
     "kj": "bin/kj.js",
     "kj-tail": "bin/kj-tail",
-    "karajan-mcp": "bin/karajan-mcp.js"
+    "karajan-mcp": "bin/karajan-mcp.js",
+    "kj-rag-mcp": "bin/kj-rag-mcp.js"
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
@@ -64,7 +65,8 @@
     "format:fix": "prettier --write .",
     "typecheck": "npx -p typescript@5 tsc --noEmit -p tsconfig.json",
     "validate": "npm run lint && npm run lint:syntax && npm test",
-    "mcp": "node src/mcp/server.js"
+    "mcp": "node src/mcp/server.js",
+    "audit:test-diet": "node scripts/audit-test-diet.mjs"
   },
   "simple-git-hooks": {
     "pre-commit": "npx lint-staged"
@@ -72,35 +74,38 @@
   "lint-staged": {
     "src/**/*.js": "eslint --max-warnings=999"
   },
+  "overrides": {
+    "fast-uri": "^3.1.2"
+  },
   "dependencies": {
-    "@babel/parser": "^7.29.3",
-    "@modelcontextprotocol/sdk": "^1.26.0",
-    "better-sqlite3": "^11.0.0",
-    "chokidar": "^4.0.0",
-    "commander": "^14.0.0",
+    "@babel/parser": "^7.29.7",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.10.0",
+    "chokidar": "^5.0.0",
+    "commander": "^15.0.0",
     "execa": "^9.6.0",
     "express": "^5.1.0",
     "express-rate-limit": "^8.5.0",
     "helmet": "^8.1.0",
-    "js-yaml": "^4.1.0",
-    "knip": "^6.14.1",
+    "js-yaml": "^4.2.0",
+    "knip": "^6.15.0",
     "madge": "^8.0.0",
     "sqlite-vec": "^0.1.9",
-    "valibot": "^1.3.1",
+    "valibot": "^1.4.1",
     "web-tree-sitter": "^0.26.9"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/coverage-v8": "^4.1.8",
     "esbuild": "^0.28.0",
-    "eslint": "^10.2.1",
+    "eslint": "^10.4.1",
     "eslint-plugin-import-x": "^4.16.2",
     "eslint-plugin-security": "^4.0.0",
-    "globals": "^17.5.0",
-    "lint-staged": "^16.4.0",
+    "globals": "^17.6.0",
+    "lint-staged": "^17.0.7",
     "postject": "^1.0.0-alpha.6",
     "prettier": "^3.4.2",
     "simple-git-hooks": "^2.13.1",
-    "vitest": "^4.0.0"
+    "vitest": "^4.1.8"
   }
 }

package/packages/hu-board/package.json

@@ -4,14 +4,17 @@
   "description": "HU Story Board dashboard for Karajan Code",
   "type": "module",
   "private": true,
+  "engines": {
+    "node": ">=22.22.1"
+  },
   "scripts": {
     "start": "node src/server.js",
     "dev": "node --watch src/server.js",
     "test": "vitest run"
   },
   "dependencies": {
-    "better-sqlite3": "^11.0.0",
-    "chokidar": "^4.0.0",
+    "better-sqlite3": "^12.10.0",
+    "chokidar": "^5.0.0",
     "express": "^5.1.0",
     "express-rate-limit": "^8.5.0",
     "helmet": "^8.1.0"