karajan-code 2.25.0 → 2.27.0

package/README.md

@@ -345,6 +345,23 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 
 ## Recent releases
 
+> **v2.27.0 released** — Minor. **RAG polish** — three improvements triggered by the v2.26.0 smoke test on karajan-code itself:
+>
+> - **Per-project isolation** (PR #831): new `project_slug` column on chunks; `kj rag query --project <slug>` (auto-detected from cwd) filters the global DB. `--project all` to query across everything.
+> - **`docs/RAG.md` + `docs/es/RAG.md`** (PR #832): single unified guide covering architecture, install, six workflows, configuration, limitations and troubleshooting. Replaces the documentation spread across CHANGELOG / templates / landing.
+> - **Asymmetric source-vs-test ranking** (PR #833): NL queries like `how does X work` no longer rank `tests/X.test.js` above `src/X.js`; test-flavoured queries still surface tests.
+> - Plus **KJC-BUG-0063** (PR #834): skipped a TZ-dependent test that was blocking every CI run, and a `shrink-budget` workflow exclude fix for `docs/*.md` at the root.
+>
+> **Coming in v2.28.0+**: chokidar watcher for live re-indexing, AST source chunker (tree-sitter / @babel/parser), BM25 + cosine hybrid scoring, OpenAI/Voyage embedder adapters (for users without local Docker).
+>
+> **v2.26.0 released** — Minor. **RAG Auto-Bootstrap** — Ollama runs in Docker out of the box. `kj init` now provisions the embedder automatically (or skips with a clear reason on modest hardware / `--no-ollama`); `kj doctor` surfaces health; `kj ollama [start|stop|status|pull]` manages lifecycle without docker compose. See [docs/RAG.md](docs/RAG.md) for the full RAG guide ([español](docs/es/RAG.md)).
+>
+> Capability check (RAM + Docker) means the bootstrap never breaks init: on Windows without Docker Desktop, on hosts under 4 GB free, or with `--no-ollama`, the wizard logs a one-liner and continues. Where Ollama is already running on `:11434`, `kj init` reuses the external instance instead of spawning a second container.
+>
+> Bundles **KJC-BUG-0061** fix (caught during v2.25.0 smoke test): `kj onboard --no-synth` was ignored by Commander shape mapping, `OnboarderRole.run()` was called without `init()`, and `kj rag query --json` on empty store emitted just `[]` instead of the `{empty: true}` contract the MCP handler returns.
+>
+> **Coming next from v2.26.0**: addressed in v2.27.0 above.
+>
 > **v2.25.0 released** — Minor. **RAG Camino B + Camino D** (KJC-PCS-0049). Closes the consumer-surface plan. Skills hosts can now invoke RAG via `/kj-rag-query` without MCP, and the pre-loop retrieval stage from v2.24.0 only fires when triage signals make it worthwhile.
 >
 > Camino B — `/kj-rag-query <text> [--scope <s>] [--top-k <n>]` slash command shipped by `kj init` to `.claude/commands/`. Thin wrapper over `kj rag query`; passes flags through, surfaces `empty:true` as a one-line hint, renders hits as background context rather than raw JSON. For Claude Code / Cursor instances loaded without MCP.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.25.0",
+  "version": "2.27.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/scripts/esbuild-sea.config.mjs

@@ -161,6 +161,15 @@ const ragStubPlugin = {
           openVecStore: notAvailable, OllamaEmbedder: notAvailable,
           indexFile: notAvailable, indexProject: notAvailable,
           query: notAvailable, chunkMarkdown: notAvailable, chunkPlan: notAvailable, chunkSource: notAvailable,
+          // KJC-TSK-0435 — Ollama Docker manager.
+          ollamaUp: notAvailable, ollamaDown: notAvailable, ensureComposeFile: notAvailable,
+          isOllamaReachable: notAvailable, findAvailableOllamaPort: notAvailable,
+          waitForOllamaReady: notAvailable, buildComposeTemplate: notAvailable, normalizeOllamaConfig: notAvailable,
+          // KJC-TSK-0436 — Ollama capability check + model pull.
+          checkDockerAvailable: notAvailable, checkRamCapacity: notAvailable,
+          checkOllamaCapability: notAvailable, pullOllamaModel: notAvailable,
+          // KJC-TSK-0438 — RAG project isolation.
+          projectSlug: notAvailable,
           default: notAvailable,
         };
       `,

package/src/checks/ollama.js

@@ -0,0 +1,41 @@
+// KJC-TSK-0437 — `kj doctor` check for the RAG embedder.
+// Only fires when rag.preload.enabled === true; otherwise reports
+// "Disabled in config" so doctor stays quiet on greenfield projects
+// that never opted in to RAG.
+import { isOllamaReachable } from "../rag/ollama-manager.js";
+import { STRATEGY } from "./types.js";
+
+function ragEnabled(config) {
+  return config?.rag?.preload?.enabled === true;
+}
+function ollamaHost(config) {
+  const port = config?.rag?.embedder?.port || 11434;
+  return config?.rag?.embedder?.host || `http://localhost:${port}`;
+}
+
+function createOllamaStatusCheck() {
+  return {
+    name: "ollama",
+    label: "Ollama (RAG embedder)",
+    strategy: STRATEGY.NONE,
+    async detect({ config }) {
+      if (!ragEnabled(config)) {
+        return { ok: true, severity: "info", detail: "Disabled in config (rag.preload.enabled=false)" };
+      }
+      const host = ollamaHost(config);
+      let reachable;
+      try { reachable = await isOllamaReachable(host); } catch { reachable = false; }
+      return {
+        ok: reachable,
+        severity: reachable ? "info" : "warn",
+        detail: reachable ? `Reachable at ${host}` : `Not reachable at ${host}`,
+        fix: reachable ? undefined : "Run `kj ollama start` to bootstrap the container, or `kj init --no-ollama` to opt out.",
+        extra: { host, reachable },
+      };
+    },
+  };
+}
+
+export function getOllamaChecks() {
+  return [createOllamaStatusCheck()];
+}

package/src/cli/register-meta.js

@@ -113,6 +113,7 @@ export function registerMeta(program, { pkgVersion }) {
     .description("Run a semantic query against the indexed RAG corpus")
     .option("--scope <scope>", "plans | code | onboarding | all (default: all)", "all")
     .option("--top-k <n>", "Number of hits to return (default: 5)", "5")
+    .option("--project <slug>", "Filter by project slug. Pass 'all' to query across every indexed project. Default: cwd basename")
     .option("--json", "Output the hits as JSON")
     .action(async (text, flags) => {
       await withConfig(pkgVersion, "rag-query", flags, async ({ config, logger }) => {

package/src/cli/register-pipeline.js

@@ -1,4 +1,5 @@
 import { initCommand } from "../commands/init.js";
+import { ollamaStartCommand, ollamaStopCommand, ollamaStatusCommand, ollamaPullCommand } from "../commands/ollama.js";
 import { configCommand } from "../commands/config.js";
 import { codeCommand } from "../commands/code.js";
 import { reviewCommand } from "../commands/review.js";
@@ -25,6 +26,7 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--scaffold-ci", "Scaffold Karajan CI Gateway workflow files")
     .option("--global", "Save config to ~/.karajan/kj.config.yml (skip the scope wizard)")
     .option("--local", "Save config to ./.karajan/kj.config.yml (skip the scope wizard)")
+    .option("--no-ollama", "Skip the RAG embedder bootstrap (Ollama-in-Docker). Useful on modest hardware or when an external embedder will be wired manually")
     .action(async (flags) => {
       await withConfig(pkgVersion, "init", flags, async ({ config: _config, logger }) => {
         await initCommand({ logger, flags });
@@ -236,4 +238,19 @@ export function registerPipeline(program, { pkgVersion }) {
     .action(async (flags) => {
       await reportCommand(flags);
     });
+
+  // KJC-TSK-0437 — `kj ollama [start|stop|status|pull]`
+  const ollama = program.command("ollama").description("Manage the RAG embedder container (Ollama-in-Docker)");
+  ollama.command("start").description("Start Ollama container").action(async () => {
+    await withConfig(pkgVersion, "ollama:start", {}, async ({ config, logger }) => ollamaStartCommand({ config, logger }));
+  });
+  ollama.command("stop").description("Stop Ollama container").action(async () => {
+    await withConfig(pkgVersion, "ollama:stop", {}, async ({ config, logger }) => ollamaStopCommand({ config, logger }));
+  });
+  ollama.command("status").description("Report Ollama reachability + container").action(async () => {
+    await withConfig(pkgVersion, "ollama:status", {}, async ({ config, logger }) => ollamaStatusCommand({ config, logger }));
+  });
+  ollama.command("pull <model>").description("Pull a model into the Ollama container").action(async (model) => {
+    await withConfig(pkgVersion, "ollama:pull", {}, async ({ config, logger }) => ollamaPullCommand({ model, config, logger }));
+  });
 }

package/src/commands/doctor.js

@@ -18,6 +18,7 @@ import { getSystemChecks } from "../checks/system.js";
 import { getConfigFileChecks } from "../checks/config-files.js";
 import { getBinaryChecks } from "../checks/binaries.js";
 import { getSonarChecks } from "../checks/sonar.js";
+import { getOllamaChecks } from "../checks/ollama.js";
 import { getCiChecks } from "../checks/ci.js";
 import { getRtkChecks } from "../checks/rtk.js";
 import { getNodeChecks } from "../checks/node.js";
@@ -52,6 +53,7 @@ function buildChecks(config, { projectOnly = false } = {}) {
     ...getConfigFileChecks(),
     ...getBinaryChecks(),
     ...getSonarChecks(),
+    ...getOllamaChecks(),
     ...getPortChecks(),
     ...getTokenChecks(config),
     ...getMcpHealthChecks(),

package/src/commands/init.js

@@ -3,6 +3,8 @@ import os from "node:os";
 import path from "node:path";
 import { getConfigPath, getProjectConfigPath, loadConfig, writeConfig } from "../config.js";
 import { sonarUp, checkVmMaxMapCount } from "../sonar/manager.js";
+import { ollamaUp, waitForOllamaReady, normalizeOllamaConfig } from "../rag/ollama-manager.js";
+import { checkOllamaCapability, pullOllamaModel } from "../rag/ollama-capability.js";
 import { exists, ensureDir } from "../utils/fs.js";
 import { getKarajanHome } from "../utils/paths.js";
 import { detectAvailableAgents } from "../utils/agent-detect.js";
@@ -500,6 +502,50 @@ async function scaffoldCiGateway(config, flags, logger) {
   logger.info("  4. Push the workflow files and enable 'kj run --enable-ci'");
 }
 
+// KJC-TSK-0436 — RAG embedder bootstrap. Default-on, opt-out with
+// `--no-ollama`. Skipped automatically when the host can't run it
+// (no Docker, daemon down, < 4 GB free RAM) — a one-line warning
+// tells the user how to wire an external embedder instead.
+async function bootstrapOllama({ flags, config, logger, interactive }) {
+  // Commander maps `--no-ollama` to `flags.ollama=false`.
+  const skip = flags?.noOllama === true || flags?.ollama === false;
+  if (skip) {
+    logger.info("Ollama bootstrap skipped (--no-ollama). RAG embedder will be unavailable until you configure one.");
+    return;
+  }
+  const cap = await checkOllamaCapability();
+  if (!cap.capable) {
+    logger.warn(`Ollama bootstrap skipped: ${cap.reasons.join("; ")}.`);
+    logger.warn("  Wire an external embedder via `config.rag.embedder` or rerun `kj init` after fixing the cause.");
+    return;
+  }
+  const result = await ollamaUp(config?.rag?.embedder || null);
+  if (result.exitCode !== 0) {
+    logger.warn(`Ollama bootstrap failed: ${result.stderr || result.stdout}`);
+    return;
+  }
+  if (result.reusedHost) {
+    logger.info(`Reusing existing Ollama at ${result.reusedHost}.`);
+  } else {
+    logger.info("Ollama container started. Waiting for /api/tags...");
+    const ollamaCfg = normalizeOllamaConfig(config?.rag?.embedder || {});
+    const ready = await waitForOllamaReady(ollamaCfg.host, ollamaCfg.timeouts.readyMs);
+    if (!ready) {
+      logger.warn(`Ollama did not become ready within ${ollamaCfg.timeouts.readyMs} ms. Continuing — pull the model manually with \`kj ollama pull nomic-embed-text\`.`);
+      return;
+    }
+  }
+  const model = config?.rag?.embedder?.model || "nomic-embed-text";
+  logger.info(`Pulling embedder model ${model} (first run downloads ~270 MB)...`);
+  const pull = await pullOllamaModel(model, { containerName: config?.rag?.embedder?.container_name });
+  if (pull.exitCode === 0) {
+    logger.info(`  -> ${model} ready. RAG embedder available.`);
+    if (interactive) logger.info("  -> Enable pre-loop retrieval with `yq -i '.rag.preload.enabled = true' " + getConfigPath() + "`");
+  } else {
+    logger.warn(`Model pull failed: ${pull.stderr || pull.stdout}. Retry with \`kj ollama pull ${model}\`.`);
+  }
+}
+
 async function installSkills(logger, interactive) {
   const projectDir = process.cwd();
   const commandsDir = path.join(projectDir, ".claude", "commands");
@@ -636,6 +682,7 @@ export async function initCommand({ logger, flags = {} }) {
   await ensureCoderRules(coderRulesPath, logger);
   await ensureGitignoreEntries(process.cwd(), logger);
   await installSkills(logger, interactive);
+  await bootstrapOllama({ flags, config, logger, interactive });
 
   // Auto-detect project stack and preconfigure
   const stack = await detectProjectStack(process.cwd());

package/src/commands/ollama.js

@@ -0,0 +1,44 @@
+// KJC-TSK-0437 — `kj ollama [start|stop|status|pull <model>]` subcommand.
+// Thin wrappers around src/rag/ollama-manager.js so the user can manage
+// the RAG embedder lifecycle without touching docker compose.
+import { ollamaUp, ollamaDown, isOllamaReachable, normalizeOllamaConfig } from "../rag/ollama-manager.js";
+import { pullOllamaModel } from "../rag/ollama-capability.js";
+
+function embedderCfg(config) {
+  return normalizeOllamaConfig(config?.rag?.embedder || {});
+}
+
+export async function ollamaStartCommand({ config, logger }) {
+  const result = await ollamaUp(config?.rag?.embedder || null);
+  if (result.exitCode !== 0) {
+    logger.warn(`ollama start failed: ${result.stderr || result.stdout}`);
+    return result;
+  }
+  logger.info(result.reusedHost ? `Reusing Ollama at ${result.reusedHost}` : "Ollama container started.");
+  return result;
+}
+
+export async function ollamaStopCommand({ config, logger }) {
+  const result = await ollamaDown(config?.rag?.embedder || null);
+  if (result.exitCode === 0) logger.info(result.stdout || "Ollama stopped.");
+  else logger.warn(`ollama stop failed: ${result.stderr || result.stdout}`);
+  return result;
+}
+
+export async function ollamaStatusCommand({ config, logger }) {
+  const cfg = embedderCfg(config);
+  const reachable = await isOllamaReachable(cfg.host, cfg.timeouts.healthcheckSeconds);
+  const status = { host: cfg.host, container: cfg.containerName, reachable };
+  if (reachable) logger.info(`Ollama reachable at ${cfg.host} (container ${cfg.containerName}).`);
+  else logger.warn(`Ollama not reachable at ${cfg.host}. Try \`kj ollama start\`.`);
+  return status;
+}
+
+export async function ollamaPullCommand({ model, config, logger }) {
+  if (!model) throw new Error("kj ollama pull: model argument required");
+  logger.info(`Pulling ${model} into ${embedderCfg(config).containerName}...`);
+  const result = await pullOllamaModel(model, { containerName: embedderCfg(config).containerName });
+  if (result.exitCode === 0) logger.info(`  -> ${model} ready.`);
+  else logger.warn(`pull ${model} failed: ${result.stderr || result.stdout}`);
+  return result;
+}

package/src/commands/onboard.js

@@ -15,10 +15,14 @@ export function briefPath(projectDir) {
 export async function onboardCommand({ config, logger, flags = {} }) {
   const projectDir = config?.projectDir || process.cwd();
   const out = flags.output || briefPath(projectDir);
+  // KJC-BUG-0061 Bug A: Commander maps `--no-synth` to `flags.synth=false`,
+  // not `flags.noSynth=true`. Accept both shapes so callers from Commander
+  // and direct API callers behave the same.
+  const skipSynth = flags.noSynth === true || flags.synth === false;
   logger.info(`[onboard] collecting from ${projectDir}`);
   const bundle = await collectAll(projectDir);
   await mkdir(path.dirname(out), { recursive: true });
-  if (flags.noSynth) {
+  if (skipSynth) {
     await writeFile(out, `# Onboarding bundle — ${projectDir}\n\n\`\`\`json\n${JSON.stringify(bundle, null, 2)}\n\`\`\`\n`, "utf8");
     logger.info(`[onboard] wrote raw bundle to ${out} (--no-synth)`);
     return { path: out, bundle, brief: null };
@@ -27,6 +31,11 @@ export async function onboardCommand({ config, logger, flags = {} }) {
   const templatePath = new URL("../../templates/roles/onboarder.md", import.meta.url).pathname;
   const instructions = existsSync(templatePath) ? await readFile(templatePath, "utf8") : "";
   const role = new OnboarderRole({ instructions, config, ...roleCfg });
+  // KJC-BUG-0061 Bug B: BaseRole.run() refuses to execute unless init()
+  // has populated the agent / template context. The plan-generate path
+  // already does this; the onboard command was relying on a code path
+  // that never ran in isolation.
+  await role.init({ projectDir });
   const result = await role.run({ bundle });
   const brief = result?.result?.brief || "# Project is greenfield\n\nNo synth output.\n";
   await writeFile(out, brief, "utf8");

package/src/commands/rag.js

@@ -2,7 +2,7 @@
 //   kj rag index [--project <slug>] [--with-sources]
 //   kj rag query <text>   [--scope plans|code|onboarding|all] [--top-k N] [--json]
 // Closes the v2.22.0 RAG MVP end-to-end from the terminal.
-import { openVecStore, countChunks } from "../rag/vec-store.js";
+import { openVecStore, countChunks, projectSlug } from "../rag/vec-store.js";
 import { OllamaEmbedder } from "../rag/embedder.js";
 import { indexProject } from "../rag/indexer.js";
 import { query } from "../rag/retriever.js";
@@ -41,14 +41,26 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
   if (!text) throw new Error("kj rag query: text argument required");
   const db = openDb(config);
   try {
+    const topK = Math.max(1, Number(flags.topK) || 5);
+    const scope = flags.scope || "all";
+    // KJC-TSK-0438 — project isolation. Auto-detect slug from projectDir
+    // (basename normalised); `--project all` disables the filter, `--project
+    // <slug>` overrides. Pre-v2.27 chunks with NULL slug are only visible
+    // when no filter is in effect.
+    const detected = projectSlug(config?.projectDir || process.cwd());
+    const project = flags.project === "all" ? null : (flags.project || detected || null);
+    // KJC-BUG-0061 follow-up: align the CLI `--json` shape with the MCP
+    // handler. The MCP tool responds `{ hits: [], empty: true, topK, scope }`
+    // so agents (and the `/kj-rag-query` skill from Camino B) have a
+    // deterministic recovery signal. The CLI was emitting just `[]`, which
+    // is indistinguishable from "query returned zero hits over a populated
+    // store" and forced consumers to parse stderr.
     if (countChunks(db) === 0) {
       logger.warn("[rag] No chunks indexed yet. Run 'kj rag index' first.");
-      if (flags.json) process.stdout.write("[]\n");
+      if (flags.json) process.stdout.write(`${JSON.stringify({ hits: [], empty: true, topK, scope })}\n`);
       return [];
     }
-    const topK = Math.max(1, Number(flags.topK) || 5);
-    const scope = flags.scope || "all";
-    const hits = await query(db, makeEmbedder(config), text, { topK, scope });
+    const hits = await query(db, makeEmbedder(config), text, { topK, scope, project });
     if (flags.json) {
       process.stdout.write(`${JSON.stringify(hits)}\n`);
     } else {

package/src/rag/indexer.js

@@ -41,7 +41,7 @@ function chunksFor(path, kind) {
  * fresh batch is written, so a second call against the same file
  * leaves the store with exactly the latest chunks (no duplicates).
  */
-export async function indexFile(path, { db, embedder, logger = console } = {}) {
+export async function indexFile(path, { db, embedder, logger = console, project = null } = {}) {
   if (!existsSync(path)) { logger.warn?.(`[rag-indexer] file not found: ${path}`); return { indexed: 0, failed: 0 }; }
   const kind = detectKind(path);
   if (!kind) { logger.warn?.(`[rag-indexer] unknown kind: ${path}`); return { indexed: 0, failed: 0 }; }
@@ -53,7 +53,7 @@ export async function indexFile(path, { db, embedder, logger = console } = {}) {
   for (const ch of chunks) {
     try {
       const embedding = await embedder.embed(ch.text);
-      insertChunk(db, { source: path, kind: ch.metadata.kind || kind, text: ch.text, metadata: ch.metadata, embedding });
+      insertChunk(db, { source: path, kind: ch.metadata.kind || kind, text: ch.text, metadata: ch.metadata, embedding, project });
       indexed += 1;
     } catch (err) {
       failed += 1;
@@ -95,20 +95,25 @@ export async function indexProject(projectDir, { db, embedder, karajanHome, logg
   if (existsSync(planRoot)) {
     const plans = await listFiles(planRoot, (p) => /plan-.*\.json$/.test(p));
     for (const p of plans) {
-      const r = await indexFile(p, { db, embedder, logger });
+      const r = await indexFile(p, { db, embedder, logger, project: slug });
       totals.indexed += r.indexed; totals.failed += r.failed; totals.files += 1;
     }
   }
   const onboarding = join(karajanHome, ONBOARDING_DIR, `${slug}.md`);
   if (existsSync(onboarding)) {
-    const r = await indexFile(onboarding, { db, embedder, logger });
+    const r = await indexFile(onboarding, { db, embedder, logger, project: slug });
     totals.indexed += r.indexed; totals.failed += r.failed; totals.files += 1;
   }
   if (withSources) {
-    const SKIP = new Set(["node_modules", ".git", "dist", "build", "coverage", ".karajan", ".next"]);
+    // KJC-BUG-0062: `.kj/worktrees/HU-*/` contains git worktrees Karajan spawns
+    // per HU during `kj run`; they hold complete copies of `src/` that
+    // duplicate every chunk and contaminate retrieval scores. `_diet` is the
+    // tests/_diet/ sandbox used by the test-diet audit harness — never user
+    // code. Skip both.
+    const SKIP = new Set(["node_modules", ".git", "dist", "build", "coverage", ".karajan", ".next", ".kj", "_diet"]);
     const sources = await listFiles(projectDir, (p) => /\.(js|mjs|cjs|ts|tsx|jsx)$/.test(p) && !p.split("/").some((seg) => SKIP.has(seg)));
     for (const s of sources) {
-      const r = await indexFile(s, { db, embedder, logger });
+      const r = await indexFile(s, { db, embedder, logger, project: slug });
       totals.indexed += r.indexed; totals.failed += r.failed; totals.files += 1;
     }
   }

package/src/rag/ollama-capability.js

@@ -0,0 +1,59 @@
+// KJC-TSK-0436 (RAG Auto-Bootstrap PR2) — Capability check for Ollama
+// bootstrap. Returns whether the host can reasonably run a local Ollama
+// container: Docker installed, daemon reachable, and enough RAM
+// (default >= 4 GB free). The caller (kj init) decides whether to
+// bootstrap, warn, or skip.
+import os from "node:os";
+import { runCommand } from "../utils/process.js";
+
+const DEFAULT_MIN_RAM_BYTES = 4 * 1024 * 1024 * 1024; // 4 GB free
+const DEFAULT_TIMEOUT_MS = 5000;
+
+export async function checkDockerAvailable(timeoutMs = DEFAULT_TIMEOUT_MS) {
+  const v = await runCommand("docker", ["--version"], { timeout: timeoutMs }).catch(() => ({ exitCode: 127 }));
+  if (v.exitCode !== 0) return { ok: false, reason: "docker:not-installed" };
+  const info = await runCommand("docker", ["info"], { timeout: timeoutMs }).catch(() => ({ exitCode: 1 }));
+  if (info.exitCode !== 0) return { ok: false, reason: "docker:daemon-unreachable" };
+  return { ok: true };
+}
+
+export function checkRamCapacity(minBytes = DEFAULT_MIN_RAM_BYTES) {
+  const free = os.freemem();
+  const total = os.totalmem();
+  if (free < minBytes) {
+    return {
+      ok: false,
+      reason: `ram:insufficient (${formatGB(free)} free < ${formatGB(minBytes)} required)`,
+      freeBytes: free,
+      totalBytes: total,
+    };
+  }
+  return { ok: true, freeBytes: free, totalBytes: total };
+}
+
+/**
+ * Combined capability check. Returns `{ capable, reasons[] }`.
+ * Caller decides what to do (bootstrap, warn, skip).
+ */
+export async function checkOllamaCapability({ minRamBytes = DEFAULT_MIN_RAM_BYTES } = {}) {
+  const reasons = [];
+  const docker = await checkDockerAvailable();
+  if (!docker.ok) reasons.push(docker.reason);
+  const ram = checkRamCapacity(minRamBytes);
+  if (!ram.ok) reasons.push(ram.reason);
+  return { capable: reasons.length === 0, reasons, docker, ram };
+}
+
+function formatGB(bytes) {
+  return `${(bytes / (1024 ** 3)).toFixed(1)} GB`;
+}
+
+/**
+ * Pull a model into the Ollama container. Uses `docker exec` so we do
+ * not depend on the host having `ollama` CLI installed. Wired by `kj
+ * init` after `ollamaUp`, and by `kj ollama pull <model>` (PR3).
+ */
+export async function pullOllamaModel(model, { containerName = "kj-ollama", timeoutMs = 10 * 60 * 1000 } = {}) {
+  if (!model || typeof model !== "string") throw new Error("pullOllamaModel: model is required");
+  return runCommand("docker", ["exec", containerName, "ollama", "pull", model], { timeout: timeoutMs });
+}

package/src/rag/ollama-manager.js

@@ -0,0 +1,98 @@
+// KJC-TSK-0435 (RAG Auto-Bootstrap PR1) — Ollama-in-Docker manager.
+// Mirrors src/sonar/manager.js: write docker-compose, start/stop the
+// container, discover a free port, wait for readiness. Next PR wires
+// it to `kj init`.
+import fs from "node:fs/promises";
+import net from "node:net";
+import { ensureDir } from "../utils/fs.js";
+import { runCommand } from "../utils/process.js";
+import { getKarajanHome, getOllamaComposePath } from "../utils/paths.js";
+
+const DEFAULTS = { port: 11434, hcS: 5, upMs: 300000, ctrlMs: 120000, readyMs: 90000 };
+const pos = (v, d) => (Number(v) > 0 ? Number(v) : d);
+
+export function normalizeOllamaConfig(ollama = {}) {
+  const t = ollama.timeouts || {};
+  const port = Number(ollama.port) || DEFAULTS.port;
+  return {
+    host: ollama.host || `http://localhost:${port}`,
+    port,
+    external: ollama.external === true,
+    containerName: ollama.container_name || "kj-ollama",
+    volume: ollama.volume || "kj_ollama_data",
+    timeouts: {
+      healthcheckSeconds: pos(t.healthcheck_seconds, DEFAULTS.hcS),
+      composeUpMs: pos(t.compose_up_ms, DEFAULTS.upMs),
+      composeControlMs: pos(t.compose_control_ms, DEFAULTS.ctrlMs),
+      readyMs: pos(t.ready_ms, DEFAULTS.readyMs),
+    },
+  };
+}
+
+export function buildComposeTemplate(cfg) {
+  return `services:
+  ollama:
+    image: ollama/ollama:latest
+    container_name: ${cfg.containerName}
+    ports:
+      - "${cfg.port}:11434"
+    volumes:
+      - ${cfg.volume}:/root/.ollama
+    restart: unless-stopped
+
+volumes:
+  ${cfg.volume}:
+`;
+}
+
+export async function ensureComposeFile(ollama = null) {
+  const cfg = normalizeOllamaConfig(ollama || {});
+  await ensureDir(getKarajanHome());
+  await fs.writeFile(getOllamaComposePath(), buildComposeTemplate(cfg), "utf8");
+  return getOllamaComposePath();
+}
+
+export async function isOllamaReachable(host, healthcheckSeconds = DEFAULTS.hcS) {
+  const t = String(pos(healthcheckSeconds, DEFAULTS.hcS));
+  const r = await runCommand("curl", ["-s", "-o", "/dev/null", "-w", "%{http_code}", "--max-time", t, `${host}/api/tags`]);
+  return r.exitCode === 0 && r.stdout.trim().startsWith("2");
+}
+
+export async function findAvailableOllamaPort(start = DEFAULTS.port, span = 10) {
+  for (let p = start; p < start + span; p++) {
+    const free = await new Promise((res) => {
+      const s = net.createServer();
+      s.once("error", () => res(false));
+      s.once("listening", () => s.close(() => res(true)));
+      s.listen(p, "127.0.0.1");
+    });
+    if (free) return p;
+  }
+  throw new Error(`No free port in [${start}, ${start + span})`);
+}
+
+export async function waitForOllamaReady(host, timeoutMs = DEFAULTS.readyMs) {
+  const dl = Date.now() + timeoutMs;
+  while (Date.now() < dl) {
+    if (await isOllamaReachable(host, 2)) return true;
+    await new Promise((r) => setTimeout(r, 1500));
+  }
+  return false;
+}
+
+export async function ollamaUp(ollama = null) {
+  const cfg = normalizeOllamaConfig(ollama || {});
+  if (await isOllamaReachable(cfg.host, cfg.timeouts.healthcheckSeconds)) {
+    return { exitCode: 0, stdout: `Ollama already reachable at ${cfg.host}, skipping container start.`, stderr: "", reusedHost: cfg.host };
+  }
+  if (cfg.external) return { exitCode: 1, stdout: "", stderr: `Configured external Ollama is not reachable at ${cfg.host}.` };
+  const compose = await ensureComposeFile(ollama);
+  return runCommand("docker", ["compose", "-f", compose, "up", "-d"], { timeout: cfg.timeouts.composeUpMs });
+}
+
+export async function ollamaDown(ollama = null) {
+  const cfg = normalizeOllamaConfig(ollama || {});
+  if (cfg.external) return { exitCode: 0, stdout: "ollama.external=true, skipping Docker stop.", stderr: "" };
+  const compose = await ensureComposeFile(ollama);
+  return runCommand("docker", ["compose", "-f", compose, "stop"], { timeout: cfg.timeouts.composeControlMs });
+}

package/src/rag/retriever.js

@@ -10,6 +10,24 @@ import { searchSimilar } from "./vec-store.js";
 // between equidistant chunks but won't reorder by big distance gaps.
 const DEFAULT_KIND_BOOST = { plan: 0.05, onboarding: 0.03, code: 0 };
 
+// KJC-TSK-0440 — asymmetric source/test boost. v2.26 smoke caught a
+// systematic bias: queries in natural language ("how does X work") return
+// tests/X.test.js ahead of src/X.js because tests carry more descriptive
+// prose. When the query itself does NOT mention test-flavoured terms,
+// give code chunks +0.05 — but only chunks whose source path is NOT a
+// test file. Tests keep the baseline boost.
+const SOURCE_BOOST_NON_TEST = 0.05;
+const TEST_TERMS_RE = /\b(test|tests|spec|specs|expect|describe|it\(|jest|vitest|mocha)\b/i;
+const TEST_PATH_RE = /[\\/](tests?|specs?|__tests__)[\\/]|\.test\.[jt]sx?$|\.spec\.[jt]sx?$/i;
+
+function shouldBoostSources(queryText) {
+  return !TEST_TERMS_RE.test(queryText);
+}
+
+function isTestPath(source) {
+  return TEST_PATH_RE.test(source || "");
+}
+
 /**
  * Run a natural-language query against the indexed RAG corpus. Returns
  * the top-K chunks ranked by adjusted distance (lower = closer).
@@ -25,7 +43,7 @@ const DEFAULT_KIND_BOOST = { plan: 0.05, onboarding: 0.03, code: 0 };
  * @param {'plans'|'code'|'onboarding'|'all'} [opts.scope='all']
  * @param {Object} [opts.kindBoost]
  */
-export async function query(db, embedder, text, { topK = 5, scope = "all", kindBoost = DEFAULT_KIND_BOOST } = {}) {
+export async function query(db, embedder, text, { topK = 5, scope = "all", kindBoost = DEFAULT_KIND_BOOST, project = null } = {}) {
   if (!text || typeof text !== "string") throw new Error("query: text must be a non-empty string");
   const queryEmbedding = await embedder.embed(text);
   // Over-fetch (topK * 2) so the rerank step has room to reshuffle
@@ -33,15 +51,27 @@ export async function query(db, embedder, text, { topK = 5, scope = "all", kindB
   // avoid loading the entire store on tiny topK calls.
   const fetchK = Math.min(50, topK * 2);
   const scopeKind = scope === "plans" ? "plan" : scope === "code" ? "code" : scope === "onboarding" ? "onboarding" : null;
-  const raw = searchSimilar(db, queryEmbedding, fetchK, { kind: scopeKind });
+  // KJC-TSK-0438 — `project` filters by chunks.project_slug. null means
+  // no filter (pre-v2.27 behaviour). Caller's CLI defaults this to the
+  // basename of cwd; pass "all" through commands/rag.js to disable.
+  const raw = searchSimilar(db, queryEmbedding, fetchK, { kind: scopeKind, project });
   if (raw.length === 0) return [];
   // Adjust each chunk's distance by its kind boost. The vec store returns
   // cosine distance (smaller = closer); subtracting the boost makes
   // higher-priority kinds appear "closer" without altering the source
   // truth in the DB.
-  const reranked = raw.map((r) => ({
-    ...r,
-    score: r.distance - (kindBoost[r.kind] || 0),
-  })).sort((a, b) => a.score - b.score).slice(0, topK);
+  // KJC-TSK-0440 — apply the source-vs-test asymmetric boost only when
+  // the query itself is not test-flavoured. Test-flavoured queries keep
+  // the symmetric baseline so e.g. "vitest mock setup" still surfaces
+  // test files.
+  const boostSources = shouldBoostSources(text);
+  const reranked = raw.map((r) => {
+    const kindB = kindBoost[r.kind] || 0;
+    const sourceB = (boostSources && r.kind === "code" && !isTestPath(r.source)) ? SOURCE_BOOST_NON_TEST : 0;
+    return { ...r, score: r.distance - kindB - sourceB };
+  }).sort((a, b) => a.score - b.score).slice(0, topK);
   return reranked;
 }
+
+// Exported for tests.
+export { shouldBoostSources, isTestPath };

package/src/rag/vec-store.js

@@ -45,6 +45,14 @@ export function openVecStore({ dim = DEFAULT_DIM, path = dbPath() } = {}) {
     CREATE INDEX IF NOT EXISTS chunks_by_source ON chunks(source);
     CREATE INDEX IF NOT EXISTS chunks_by_kind ON chunks(kind);
   `);
+  // KJC-TSK-0438 — Project isolation. project_slug = basename of projectDir
+  // normalized; chunks indexed before the migration carry NULL and remain
+  // queryable when `--project all` (or no slug detected at query time).
+  const cols = db.prepare("PRAGMA table_info(chunks)").all().map((c) => c.name);
+  if (!cols.includes("project_slug")) {
+    db.exec("ALTER TABLE chunks ADD COLUMN project_slug TEXT;");
+    db.exec("CREATE INDEX IF NOT EXISTS chunks_by_project ON chunks(project_slug);");
+  }
   db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS vec_chunks USING vec0(embedding float[${dim}]);`);
   return db;
 }
@@ -54,13 +62,13 @@ export function openVecStore({ dim = DEFAULT_DIM, path = dbPath() } = {}) {
  * because the virtual table rowid is set explicitly to the freshly
  * minted chunks.id. Returns that id.
  */
-export function insertChunk(db, { source, kind, text, metadata = null, embedding }) {
+export function insertChunk(db, { source, kind, text, metadata = null, embedding, project = null }) {
   if (!Array.isArray(embedding) && !ArrayBuffer.isView(embedding)) {
     throw new Error("insertChunk: embedding must be an array or typed array of floats");
   }
   const meta = metadata == null ? null : (typeof metadata === "string" ? metadata : JSON.stringify(metadata));
-  const ins = db.prepare("INSERT INTO chunks (source, kind, text, metadata) VALUES (?, ?, ?, ?)");
-  const info = ins.run(source, kind, text, meta);
+  const ins = db.prepare("INSERT INTO chunks (source, kind, text, metadata, project_slug) VALUES (?, ?, ?, ?, ?)");
+  const info = ins.run(source, kind, text, meta, project);
   // sqlite-vec's vec0 virtual table requires the rowid to arrive as a BigInt
   // even for values that comfortably fit in a Number. Better-sqlite3 returns
   // lastInsertRowid as BigInt only when safeIntegers mode is on; force it.
@@ -75,22 +83,36 @@ export function insertChunk(db, { source, kind, text, metadata = null, embedding
  * text, metadata, distance }]` for the topK best matches; lower
  * distance = closer. Returns `[]` when the store is empty.
  */
-export function searchSimilar(db, embedding, topK = 5, { kind = null } = {}) {
+export function searchSimilar(db, embedding, topK = 5, { kind = null, project = null } = {}) {
   const buf = embedding instanceof Float32Array ? embedding : Float32Array.from(embedding);
   const kindClause = kind ? "AND c.kind = ?" : "";
+  const projectClause = project ? "AND c.project_slug = ?" : "";
   const sql = `
-    SELECT c.id, c.source, c.kind, c.text, c.metadata, v.distance
+    SELECT c.id, c.source, c.kind, c.text, c.metadata, c.project_slug, v.distance
     FROM vec_chunks v
     JOIN chunks c ON c.id = v.rowid
-    WHERE v.embedding MATCH ? AND k = ? ${kindClause}
+    WHERE v.embedding MATCH ? AND k = ? ${kindClause} ${projectClause}
     ORDER BY v.distance
   `;
   const params = [Buffer.from(buf.buffer), topK];
   if (kind) params.push(kind);
+  if (project) params.push(project);
   const rows = db.prepare(sql).all(...params);
   return rows.map((r) => ({ ...r, metadata: r.metadata ? safeParse(r.metadata) : null }));
 }
 
+/**
+ * Normalize a projectDir into a stable slug used for project isolation.
+ * Basename → lowercased → non-alphanumeric stripped to dashes.
+ * KJC-TSK-0438.
+ */
+export function projectSlug(projectDir) {
+  if (!projectDir) return null;
+  const base = String(projectDir).replace(/\/+$/, "").split("/").pop();
+  if (!base) return null;
+  return base.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
 function safeParse(s) { try { return JSON.parse(s); } catch { return s; } }
 
 /**

package/src/utils/paths.js

@@ -90,6 +90,11 @@ export function getSonarComposePath() {
   return path.join(getKarajanHome(), "docker-compose.sonar.yml");
 }
 
+/** Ollama RAG embedder compose: `<karajan-home>/docker-compose.ollama.yml` — KJC-TSK-0435. */
+export function getOllamaComposePath() {
+  return path.join(getKarajanHome(), "docker-compose.ollama.yml");
+}
+
 /** Webperf cache: `<karajan-home>/webperf/` — KJC-TSK-0420. */
 export function getWebperfDir() {
   return path.join(getKarajanHome(), "webperf");