karajan-code 2.24.0 → 2.26.0

package/README.md

@@ -345,6 +345,22 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 
 ## Recent releases
 
+> **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.
+>
+> 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 in v2.27.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.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.
+>
+> Camino D — Brain decisor heuristic in `src/orchestrator/stages/rag-preload-decisor.js`. New `config.rag.preload.policy`: `always` (v2.24.0 behaviour, kept for back-compat), `never` (benchmarking), `auto` (default). In `auto` mode, retrieval fires when triage decomposes, level ∈ {complex, high, epic}, task body ≥ 200 chars, or `config.rag.preload.brownfield` is set. Otherwise the stage persists `{ skipped: true, reason: 'auto:low-value' }` and the pipeline pays no retrieval cost on trivial tasks.
+>
+> **Coming in v2.26.0+**: chokidar watcher for live re-indexing, AST source chunker (tree-sitter / `@babel/parser`), BM25 + cosine hybrid scoring.
+>
 > **v2.24.0 released** — Minor. **RAG Camino C — pre-loop auto-retrieval** (KJC-PCS-0049). After v2.23.0 taught the agents that `kj_rag_query` exists, Karajan now injects prior context for them automatically: a new pre-loop stage queries the vec store with the task description and prepends the top-K chunks to the task before any LLM call.
 >
 > Opt-in: `config.rag.preload.enabled = false` by default. Five guards before the retrieval fires (`disabled`, `no-task`, empty corpus, no hits, error). The stage never throws — best-effort enrichment, opt-out by default, opt-back-out on failure. When all guards pass, the task receives an extra block:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.24.0",
+  "version": "2.26.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,13 @@ 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,
           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-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");
@@ -544,7 +590,7 @@ async function installSkills(logger, interactive) {
 
   if (installed > 0) {
     logger.info(`Installed ${installed} Karajan skill(s) in .claude/commands/`);
-    logger.info("Available as slash commands: /kj-run, /kj-code, /kj-review, /kj-test, /kj-security, /kj-discover, /kj-architect, /kj-sonar");
+    logger.info("Available as slash commands: /kj-run, /kj-code, /kj-review, /kj-test, /kj-security, /kj-discover, /kj-architect, /kj-sonar, /kj-rag-query");
   } else {
     logger.info("All skills already installed.");
   }
@@ -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

@@ -41,13 +41,19 @@ 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-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 });
     if (flags.json) {
       process.stdout.write(`${JSON.stringify(hits)}\n`);

package/src/orchestrator/drivers/pre-loop.js

@@ -41,6 +41,7 @@ import {
   runDiscoverStage, runHuReviewerStage,
 } from "../pre-loop-stages.js";
 import { runRagContextStage } from "../stages/rag-context-stage.js";
+import { shouldPreloadRag } from "../stages/rag-preload-decisor.js";
 // TSK-0336: triage goes through the StageRegistry / StageExecutor contract
 // so canRun / execute / onFailure are actually exercised in production.
 // The registry is a singleton with TriageStage / CoderStage / ReviewerStage
@@ -131,10 +132,24 @@ export async function runPreLoopStages({ config, logger, emitter, eventBase, ses
   // all see prior context without having to call kj_rag_query themselves.
   // Empty store / network / etc. degrade to no-op via the stage itself.
   if (!resumeSkip("ragPreload")) {
-    const ragRes = await runRagContextStage({ config, logger, emitter, eventBase, task });
-    if (!ragRes.skipped && ragRes.contextBlock) {
-      task = `${task}\n\n${ragRes.contextBlock}`;
-      await persistStage("ragPreload", { hits: ragRes.hits.length, scope: config?.rag?.preload?.scope || "all" });
+    // KJC-TSK-0434 (Camino D): Brain decisor heuristic — skip retrieval
+    // when triage + task shape say it would be low-value. Defaults to
+    // policy=auto; `always`/`never` are escape hatches.
+    const decision = shouldPreloadRag({ triage: triageResult.stageResult, task, config });
+    if (!decision.pull) {
+      await persistStage("ragPreload", { skipped: true, reason: decision.reason });
+    } else {
+      const ragRes = await runRagContextStage({ config, logger, emitter, eventBase, task });
+      if (!ragRes.skipped && ragRes.contextBlock) {
+        task = `${task}\n\n${ragRes.contextBlock}`;
+        await persistStage("ragPreload", {
+          hits: ragRes.hits.length,
+          scope: config?.rag?.preload?.scope || "all",
+          decisor: decision.reason,
+        });
+      } else {
+        await persistStage("ragPreload", { skipped: true, reason: ragRes.reason, decisor: decision.reason });
+      }
     }
   }
 

package/src/orchestrator/stages/rag-preload-decisor.js

@@ -0,0 +1,58 @@
+// KJC-TSK-0434 — RAG Camino D: Brain decisor heuristic for retrieval.
+// Decides WHETHER to pay the cost of running the RAG preload stage based
+// on signals from triage + task shape, instead of pre-fetching every run.
+//
+// Returns `{ pull: boolean, reason: string }`. The pre-loop driver
+// skips `runRagContextStage` when `pull === false`.
+//
+// Policies (config.rag.preload.policy):
+//   - "always"  : pull regardless (back-compat with v2.24.0 behaviour)
+//   - "never"   : never pull (useful for benchmarking, debugging)
+//   - "auto"    : heuristic — pull only when triage signals complexity,
+//                 decomposition, or when the task body is long enough
+//                 to suggest non-trivial scope. Default.
+
+const DEFAULT_POLICY = "auto";
+const COMPLEX_LEVELS = new Set(["complex", "high", "epic"]);
+const LONG_TASK_CHARS = 200;
+
+/**
+ * @param {object} params
+ * @param {object} [params.triage]   - triage stage result (may be null)
+ * @param {string} [params.task]     - the user task text
+ * @param {object} [params.config]   - full karajan config
+ * @returns {{ pull: boolean, reason: string }}
+ */
+export function shouldPreloadRag({ triage, task, config } = {}) {
+  const policy = config?.rag?.preload?.policy || DEFAULT_POLICY;
+
+  if (policy === "always") return { pull: true, reason: "policy:always" };
+  if (policy === "never") return { pull: false, reason: "policy:never" };
+
+  // policy === "auto" — apply heuristic.
+  // Brownfield is an explicit user signal — if onboarding produced a
+  // brief and config marks the project as brownfield, prior context is
+  // almost always worth pulling.
+  if (config?.rag?.preload?.brownfield === true) {
+    return { pull: true, reason: "auto:brownfield" };
+  }
+
+  // Triage said this is big enough to decompose → multi-HU run benefits
+  // from prior context fed to researcher/architect/planner.
+  if (triage?.shouldDecompose === true) {
+    return { pull: true, reason: "auto:decompose" };
+  }
+
+  // Triage classified the task as complex / high-effort.
+  if (triage?.level && COMPLEX_LEVELS.has(String(triage.level).toLowerCase())) {
+    return { pull: true, reason: "auto:complex" };
+  }
+
+  // Long task body usually means a brief with context, motivation and
+  // non-trivial scope — worth checking the RAG.
+  if (typeof task === "string" && task.length >= LONG_TASK_CHARS) {
+    return { pull: true, reason: "auto:long-task" };
+  }
+
+  return { pull: false, reason: "auto:low-value" };
+}

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/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");

package/templates/skills/kj-rag-query.md

@@ -0,0 +1,50 @@
+# kj-rag-query — Query Project RAG index
+
+Query the Project RAG (vector store + embedder) and return the top-K most relevant chunks of the indexed project: plans, onboarding briefs, and (optionally) source code.
+
+Use this when you need prior context about the project before deciding, refactoring, planning, or coding — without scanning the filesystem manually.
+
+## Your task
+
+$ARGUMENTS
+
+## How it works
+
+This skill is a thin wrapper over the Karajan CLI:
+
+```
+kj rag query "<text>" [--scope <all|plans|onboarding|code>] [--top-k <n>] [--json]
+```
+
+Parse `$ARGUMENTS` as the natural-language query plus optional flags:
+
+- `--scope <s>`: restrict retrieval to one source bucket. Default: `all`.
+  - `plans` → indexed plan JSON files (HU titles, scope, blocked_by).
+  - `onboarding` → onboarding briefs from `~/.karajan/onboarding/`.
+  - `code` → indexed source files (only present if user ran `kj rag index --with-sources`).
+- `--top-k <n>`: number of chunks to return. Default: 3. Max recommended: 10.
+- `--json`: emit raw JSON (use when piping into another tool).
+
+If `$ARGUMENTS` is empty, print a one-line usage hint and stop.
+
+## Behavior contract
+
+1. **Empty store**: if the CLI replies with `empty: true`, do NOT block the conversation. Tell the user once: "RAG index is empty — run `kj rag index` to seed it" and continue without prior context.
+2. **Zero hits**: if the store has chunks but no match scored above threshold, say "no relevant prior context" and continue.
+3. **Hits returned**: render each as a short block — `[score] source — snippet` — and use them as background context for the user's actual question. Do NOT dump raw JSON unless `--json` was passed.
+4. **Never re-validate flags**. Pass `--scope`/`--top-k` straight to the CLI; the CLI is the source of truth.
+
+## Examples
+
+User: `/kj-rag-query how does the retriever rank chunks`
+→ `kj rag query "how does the retriever rank chunks"`
+
+User: `/kj-rag-query auth flow --scope plans --top-k 5`
+→ `kj rag query "auth flow" --scope plans --top-k 5`
+
+User: `/kj-rag-query --scope onboarding architecture`
+→ `kj rag query "architecture" --scope onboarding`
+
+## Why this exists (Camino B)
+
+Hosts that load Karajan as Skills (Claude Code without MCP, Cursor without MCP) cannot reach the `kj_rag_query` MCP tool. This skill bridges that gap with the same retrieval contract.