karajan-code 2.28.0 → 2.30.0

package/README.md

@@ -345,6 +345,21 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 
 ## Recent releases
 
+> **v2.30.0 released** — Minor. **Writable config UI on HU Board** — settings modal with grouped sections, atomic-write backend, and a global vs per-project scope toggle. No more hand-editing the YAML.
+>
+> - **Pipeline role toggles** (PR #854): 8 nuevos booleanos en el modal (`planner`, `researcher`, `architect`, `tester`, `security`, `refactorer`, `impeccable`, `brain`) reflejan los defaults reales de `src/config/defaults.js`.
+> - **RAG controls** (PR #855): `rag.preload.{enabled,topK,scope}` + `rag.embedder.provider` editables sin abrir el archivo. El dropdown del provider lista los 6 embedders (ollama / openai / voyage / cohere / mistral / onnx).
+> - **Grouped sections** (PR #856): los campos se agrupan por categoría (Agentes y modelos, Roles del pipeline, RAG, Tiempos de sesión, Calidad) con iconos y orden determinista. Campos nuevos sin categoría caen en "Otros" — defensivo.
+> - **Scope toggle global vs per-project** (PR #857): pill toggle en el header del modal. Switchea entre `~/.karajan/kj.config.yml` (global, default) y `<projectDir>/.karajan/kj.config.yml` (override del proyecto, se crea al guardar). Atomic-write + `.bak` aplican a ambos.
+>
+> **v2.29.0 released** — Minor. **RAG quality lift** — dashboard + three new providers + metadata filter + rerank.
+>
+> - **Retrieval dashboard on HU Board** (PR #843): nuevo `/rag.html` con embedder activo, tamaño de DB, last-index, chunks por kind, chunks por proyecto. Primera pieza del config UI que llega completo en v2.30.
+> - **Cohere + Mistral embedders** (PR #848): `embed-multilingual-v3.0` (multi-idioma) y `mistral-embed` (EU-hosted, útil para GDPR). `KJ_COHERE_KEY` / `KJ_MISTRAL_KEY` Karajan-scoped.
+> - **ONNX local embedder** (PR #??): `@huggingface/transformers` corriendo en Node — sin Docker, sin API key, sin Ollama. Default `Xenova/all-MiniLM-L6-v2` (384 dim). Es la base para el zero-config init de v2.31.
+> - **Metadata `--where` filter** (PR #??): `kj rag query 'auth' --where 'symbol=loadConfig AND kind=plan'`. Gramática mínima KEY=VALUE AND KEY=VALUE; cualquier metadata que emite el chunker es queryable sin schema changes.
+> - **Cross-encoder rerank** (PR #??): opt-in `--rerank` re-ordena los topK con un cross-encoder (`Xenova/ms-marco-MiniLM-L-6-v2`). Latencia acotada, calidad final notablemente mejor.
+>
 > **v2.28.0 released** — Minor. **RAG advanced** — live re-index + cloud embedders + hybrid scoring + AST chunker, plus a real fix for the v2.27.0 chapuza.
 >
 > - **`kj watch`** (PR #836): chokidar daemon que re-indexa los archivos del proyecto tras cada edit (1s debounce). Fin del `kj rag index` manual.
@@ -360,7 +375,7 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 > - **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).
+> **Coming in v2.30.0+**: writable config UI on the HU Board (toggle roles, switch coder/reviewer, adjust alpha/mode/rerank without re-editing the YAML), then v2.31 zero-config init (reduce the wizard to one critical question, smart defaults for everything).
 >
 > **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)).
 >

package/package.json

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

package/packages/hu-board/public/app.js

@@ -3272,10 +3272,14 @@ function handleRoute() {
 // row. `select` → <select>, `boolean` → <input type=checkbox>,
 // `number` → <input type=number min/max>. Help text under each
 // label as a small grey paragraph.
-async function showConfigEditor() {
+async function showConfigEditor(scope = 'global') {
+  // v2.30.0 PR4 — scope toggle. 'global' edita ~/.karajan/kj.config.yml
+  // (afecta a todos los proyectos); 'project' edita
+  // <projectDir>/.karajan/kj.config.yml (sólo el repo actual). El backend
+  // resuelve <projectDir> desde KJ_PROJECT_DIR || cwd.
   let cfg;
   try {
-    const r = await fetch('/api/config');
+    const r = await fetch(`/api/config?scope=${encodeURIComponent(scope)}`);
     if (!r.ok) throw new Error(`HTTP ${r.status}`);
     cfg = await r.json();
   } catch (err) {
@@ -3306,14 +3310,66 @@ async function showConfigEditor() {
       </div>
     `;
   };
+
+  // v2.30.0 — agrupa los campos por `f.category`. El backend declara
+  // las categorías ordenadas en `cfg.categories`; cualquier campo sin
+  // categoría cae a "Otros" (defensivo, no se pierde si olvidamos
+  // etiquetar uno nuevo). Mantiene el orden interno del whitelist
+  // dentro de cada sección.
+  const cats = Array.isArray(cfg.categories) && cfg.categories.length > 0
+    ? cfg.categories
+    : [{ id: 'misc', label: 'Otros', icon: '⚙', order: 999 }];
+  const byCat = new Map(cats.map((c) => [c.id, []]));
+  byCat.set('misc', byCat.get('misc') || []);
+  for (const f of cfg.fields) {
+    const id = byCat.has(f.category) ? f.category : 'misc';
+    if (!byCat.has(id)) byCat.set(id, []);
+    byCat.get(id).push(f);
+  }
+  const renderSection = (cat) => {
+    const fields = byCat.get(cat.id) || [];
+    if (fields.length === 0) return '';
+    return `
+      <section style="margin-bottom:22px;">
+        <h3 style="display:flex;align-items:center;gap:8px;margin:0 0 12px;padding-bottom:6px;border-bottom:1px solid var(--border);font-size:0.95rem;font-weight:700;color:var(--text);">
+          <span aria-hidden="true">${esc(cat.icon || '⚙')}</span>
+          <span>${esc(cat.label)}</span>
+        </h3>
+        ${fields.map(renderField).join('')}
+      </section>
+    `;
+  };
+  const allCats = [...cats];
+  if ((byCat.get('misc') || []).length > 0 && !allCats.some((c) => c.id === 'misc')) {
+    allCats.push({ id: 'misc', label: 'Otros', icon: '⚙', order: 999 });
+  }
+  const sectionsHtml = allCats.map(renderSection).join('');
+
+  // PR4 — toggle global / proyecto. Cambiarlo recarga el modal contra el
+  // otro fichero. Visual: dos pills mutuamente excluyentes.
+  const pill = (id, value, label, active) => `
+    <button data-scope="${value}" id="${id}" type="button"
+      style="padding:4px 10px;border-radius:999px;border:1px solid var(--border);
+      background:${active ? 'var(--color-blue)' : 'var(--bg-primary)'};
+      color:${active ? '#fff' : 'var(--text)'};font-size:0.75rem;cursor:pointer;">
+      ${esc(label)}
+    </button>`;
+  const scopeToggle = `
+    <div style="display:flex;align-items:center;gap:4px;margin-left:auto;" role="radiogroup" aria-label="Ámbito de configuración">
+      ${pill('cfg-scope-global',  'global',  'Global',         scope === 'global')}
+      ${pill('cfg-scope-project', 'project', 'Este proyecto',  scope === 'project')}
+    </div>`;
   dlg.innerHTML = `
     <div style="padding:14px 18px;border-bottom:1px solid var(--border);font-weight:700;display:flex;align-items:center;gap:10px;">
       <span style="font-size:1.2rem;">⚙</span>
       <span>Configuración de Karajan</span>
-      <span style="margin-left:auto;font-family:var(--font-mono,monospace);font-size:0.75rem;color:var(--text-muted);">${esc(cfg.path || '')}</span>
+      ${scopeToggle}
+    </div>
+    <div style="padding:6px 18px 0;font-family:var(--font-mono,monospace);font-size:0.7rem;color:var(--text-muted);">
+      ${esc(cfg.path || '')}${cfg.exists === false ? ' · (aún no existe, se creará al guardar)' : ''}
     </div>
     <div style="padding:14px 18px;max-height:65vh;overflow:auto;">
-      ${cfg.fields.map(renderField).join('')}
+      ${sectionsHtml}
       <p style="margin:14px 0 0;font-size:0.75rem;color:var(--text-muted);">
         Los cambios se guardan en <code>kj.config.yml</code> de forma atómica (con copia de seguridad <code>.bak</code>).
         El próximo <code>kj run</code> los aplicará — no hace falta reiniciar el board.
@@ -3325,6 +3381,15 @@ async function showConfigEditor() {
     </div>
   `;
   if (typeof dlg.showModal === 'function' && !dlg.open) dlg.showModal();
+  // PR4 — al cambiar de pill, recargar el modal con el otro scope.
+  for (const btn of dlg.querySelectorAll('[data-scope]')) {
+    btn.addEventListener('click', () => {
+      const next = btn.getAttribute('data-scope');
+      if (next === scope) return;
+      try { dlg.close(); } catch { /* ignore */ }
+      showConfigEditor(next);
+    }, { once: true });
+  }
   dlg.querySelector('#config-cancel')?.addEventListener('click', () => { try { dlg.close(); } catch { /* ignore */ } }, { once: true });
   dlg.querySelector('#config-save')?.addEventListener('click', async () => {
     // Build the patch from the form, comparing against initial values
@@ -3347,7 +3412,7 @@ async function showConfigEditor() {
       const r = await fetch('/api/config', {
         method: 'PUT',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ patch }),
+        body: JSON.stringify({ patch, scope }),
       });
       if (!r.ok) {
         const body = await r.json().catch(() => ({}));

package/packages/hu-board/public/index.html

@@ -25,6 +25,7 @@
       <button class="nav-btn" data-view="dashboard" title="Per-project landing: stats grid + project list. Click a project card to focus the kanban / graph on that project.">Dashboard</button>
       <button class="nav-btn" data-view="sessions" title="Every kj run that has touched the board, newest first. Filter by project; click a session to inspect its iterations, commits and checkpoints.">Sessions</button>
       <a class="nav-btn" href="/pipeline.html" title="Live observability of pipeline runs (Karajan v2.7+): stage timings, agent calls, decision logs.">Pipeline</a>
+      <a class="nav-btn" href="/rag.html" title="RAG retrieval-quality dashboard: chunk counts, embedder provider, db size.">RAG</a>
       <select class="project-select" id="project-select">
         <option value="">All Projects</option>
       </select>

package/packages/hu-board/public/rag.html

@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Karajan RAG · Retrieval Dashboard</title>
+  <link rel="stylesheet" href="/styles.css">
+</head>
+<body>
+  <header class="header">
+    <div class="header__logo"><div><div class="header__title">Karajan RAG</div><div class="header__subtitle">retrieval-quality dashboard</div></div></div>
+    <nav class="header__nav">
+      <a class="nav-btn" href="/">← Board</a>
+      <button class="nav-btn active">RAG</button>
+      <div class="header__controls"><button class="control-btn" id="rag-refresh" title="Reload stats">🔄</button></div>
+    </nav>
+  </header>
+  <main class="main" id="rag-app"><div class="loading"><div class="loading__spinner"></div><p>Loading…</p></div></main>
+  <script src="/rag.js"></script>
+</body>
+</html>

package/packages/hu-board/public/rag.js

@@ -0,0 +1,39 @@
+// KJC-TSK-0445 — Retrieval dashboard frontend. Fetches /api/rag/stats and
+// renders chunk counts per project/kind, embedder, DB size and last-index.
+const TOKEN = new URLSearchParams(location.search).get("token") || localStorage.getItem("kj_board_token") || "";
+const HEADERS = TOKEN ? { Authorization: `Bearer ${TOKEN}` } : {};
+const ESC = (s) => String(s).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+
+function bytes(n) { for (const u of ["B", "KB", "MB", "GB"]) { if (n < 1024) return `${u === "B" ? n : n.toFixed(1)} ${u}`; n /= 1024; } return `${n.toFixed(2)} TB`; }
+
+function bars(rows, lab, val, max) {
+  if (!rows.length) return '<p class="rag-empty">no data</p>';
+  return rows.map((r) => `<div class="rag-bar"><span class="rag-bar__label">${ESC(lab(r))}</span><span class="rag-bar__fill" style="width:${Math.round((val(r) / max) * 100)}%"></span><span class="rag-bar__value">${val(r).toLocaleString()}</span></div>`).join("");
+}
+
+function embedderCard(e) {
+  return e ? `<div class="rag-card"><h3>Embedder</h3><p class="rag-stat-big">${ESC(e.provider)}</p><p class="rag-stat-sub">${ESC(e.model || "default model")} · dim ${e.dim ?? "?"}</p></div>` : "";
+}
+
+function render(root, data) {
+  if (!data.initialized) { root.innerHTML = `<section class="rag-grid"><div class="rag-card"><h3>RAG DB</h3><p class="rag-empty">${ESC(data.message || "not initialized")}</p></div>${embedderCard(data.embedder)}</section>`; return; }
+  const lastIdx = data.last_indexed ? new Date(data.last_indexed).toLocaleString() : "never";
+  const mk = Math.max(1, ...data.by_kind.map((r) => r.n));
+  const mp = Math.max(1, ...data.by_project.map((r) => r.n));
+  root.innerHTML = `<section class="rag-grid">
+    <div class="rag-card"><h3>Totals</h3><p class="rag-stat-big">${data.total_chunks.toLocaleString()}</p><p class="rag-stat-sub">chunks · ${bytes(data.db_size_bytes)} · last indexed ${ESC(lastIdx)}</p></div>
+    ${embedderCard(data.embedder)}
+    <div class="rag-card rag-card--wide"><h3>By kind</h3>${bars(data.by_kind, (r) => r.kind, (r) => r.n, mk)}</div>
+    <div class="rag-card rag-card--wide"><h3>By project (top 20)</h3>${bars(data.by_project, (r) => r.project, (r) => r.n, mp)}</div>
+  </section>`;
+}
+
+async function load() {
+  const app = document.getElementById("rag-app");
+  app.innerHTML = '<div class="loading"><div class="loading__spinner"></div><p>Loading…</p></div>';
+  try { const r = await fetch("/api/rag/stats", { headers: HEADERS }); if (!r.ok) throw new Error(`HTTP ${r.status}`); render(app, await r.json()); }
+  catch (e) { app.innerHTML = `<div class="rag-card rag-card--error"><strong>Error:</strong> ${ESC(e.message)}</div>`; }
+}
+
+document.getElementById("rag-refresh").addEventListener("click", load);
+load();

package/packages/hu-board/public/styles.css

@@ -916,3 +916,17 @@ body.scoped-mode .nav-btn[data-view="dashboard"],
 body.scoped-mode .header__nav a[href="/pipeline.html"] {
   display: none;
 }
+
+/* KJC-TSK-0445 — RAG dashboard */
+.rag-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 1rem; padding: 1rem; }
+.rag-card { background: var(--bg-secondary, #1e1e2e); border-radius: 8px; padding: 1.25rem; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
+.rag-card--wide { grid-column: 1 / -1; }
+.rag-card--error { color: #f87171; background: #2a1414; }
+.rag-card h3 { margin: 0 0 .75rem; font-size: .9rem; text-transform: uppercase; letter-spacing: .05em; color: var(--text-secondary, #94a3b8); }
+.rag-stat-big { font-size: 2rem; font-weight: 700; margin: 0; color: var(--text-primary, #f8fafc); }
+.rag-stat-sub { margin: .25rem 0 0; font-size: .85rem; color: var(--text-secondary, #94a3b8); }
+.rag-empty { color: var(--text-secondary, #94a3b8); font-style: italic; }
+.rag-bar { display: grid; grid-template-columns: 140px 1fr 60px; align-items: center; gap: .5rem; margin: .35rem 0; font-size: .85rem; }
+.rag-bar__label { color: var(--text-secondary, #cbd5e1); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.rag-bar__fill { display: block; height: 14px; background: linear-gradient(90deg, #7c3aed, #a78bfa); border-radius: 3px; }
+.rag-bar__value { text-align: right; color: var(--text-primary, #f8fafc); font-variant-numeric: tabular-nums; }

package/packages/hu-board/src/config-yaml.js

@@ -34,7 +34,29 @@ import { tmpdir } from 'node:os';
 import yaml from 'js-yaml';
 import { getKjHome } from './db.js';
 
-function configPath() {
+/**
+ * v2.30.0 PR4 — scope resolver.
+ *
+ *   'global'  → ~/.karajan/kj.config.yml (mismo path que el resto de
+ *               Karajan; afecta a todos los proyectos).
+ *   'project' → <projectDir>/.karajan/kj.config.yml (override por
+ *               proyecto; cuando existe, el loader del padre lo prefiere
+ *               sobre el global).
+ *
+ * projectDir se resuelve desde `KJ_PROJECT_DIR` (ya usado por
+ * journal-parser.js) con fallback a `process.cwd()` — el board se
+ * arranca desde el repo del usuario, así que cwd es el proyecto.
+ */
+export const SCOPES = ['global', 'project'];
+
+function getProjectDir() {
+  return process.env.KJ_PROJECT_DIR || process.cwd();
+}
+
+function configPath(scope = 'global') {
+  if (scope === 'project') {
+    return join(getProjectDir(), '.karajan', 'kj.config.yml');
+  }
   // Same path the parent uses (src/utils/paths.js::getKarajanHome).
   // KJC-TSK-0420: delegate to db.js::getKjHome — gives us KARAJAN_HOME
   // priority + KJ_HOME fallback + VITEST guard from one place, instead
@@ -42,13 +64,28 @@ function configPath() {
   return join(getKjHome(), 'kj.config.yml');
 }
 
-function backupPath() { return `${configPath()}.bak`; }
+function backupPath(scope = 'global') { return `${configPath(scope)}.bak`; }
+
+/**
+ * v2.30.0 — Categorías para agrupar los campos en el modal. El backend
+ * sólo declara la metadata (id, label, icon, order). El front (app.js)
+ * itera sobre EDITABLE_FIELDS, agrupa por `f.category` y dibuja un
+ * <h3> por sección. Si un campo nuevo no declara categoría, cae en
+ * "Otros" (defensivo: no se pierde aunque se nos olvide etiquetarlo).
+ */
+export const CATEGORIES = [
+  { id: 'agents',   label: 'Agentes y modelos',        icon: '🤖', order: 1 },
+  { id: 'pipeline', label: 'Roles del pipeline',       icon: '🔌', order: 2 },
+  { id: 'rag',      label: 'RAG (búsqueda de contexto)', icon: '📚', order: 3 },
+  { id: 'session',  label: 'Tiempos de sesión',        icon: '⏱',  order: 4 },
+  { id: 'quality',  label: 'Calidad',                  icon: '✅', order: 5 },
+];
 
 /**
  * Whitelist of fields the board's modal exposes. Everything else
  * stays untouched in the yml. Each entry says where in the yml the
  * field lives (`path`) and how to render it for the UI (`type`,
- * `label`, `options` for selects).
+ * `label`, `options` for selects, `category` for grouping).
  *
  * The path is a dotted notation we resolve manually (so we never
  * need to take a runtime dep on lodash for `_.get`/`_.set`).
@@ -57,6 +94,7 @@ export const EDITABLE_FIELDS = [
   {
     key: 'coder',
     path: 'coder',
+    category: 'agents',
     type: 'select',
     label: 'Agente para el rol "coder"',
     help: 'Quién escribe el código. Claude es el más fiable, Codex es más rápido.',
@@ -66,6 +104,7 @@ export const EDITABLE_FIELDS = [
   {
     key: 'reviewer',
     path: 'reviewer',
+    category: 'agents',
     type: 'select',
     label: 'Agente para el rol "reviewer"',
     help: 'Quién revisa el código del coder. Conviene que sea un agente distinto al coder para detectar errores.',
@@ -75,6 +114,7 @@ export const EDITABLE_FIELDS = [
   {
     key: 'modelMode',
     path: '_modelMode_virtual',
+    category: 'agents',
     type: 'select',
     label: 'Estrategia de modelos',
     help: 'Auto = Karajan elige el modelo según la complejidad (haiku/sonnet/opus). Sonnet siempre = barato, ideal para pruebas. Opus siempre = caro, máxima calidad.',
@@ -86,6 +126,7 @@ export const EDITABLE_FIELDS = [
   {
     key: 'maxIterationMinutes',
     path: 'session.max_iteration_minutes',
+    category: 'session',
     type: 'number',
     label: 'Tope de minutos por iteración',
     help: 'Si una iteración (coder + reviewer) supera este tiempo, Karajan la corta y Solomon decide qué hacer.',
@@ -96,6 +137,7 @@ export const EDITABLE_FIELDS = [
   {
     key: 'maxTotalMinutes',
     path: 'session.max_total_minutes',
+    category: 'session',
     type: 'number',
     label: 'Tope de minutos total por sesión',
     help: 'Tope absoluto del wall-clock de la sesión. Si se llega aquí, Karajan para aunque queden HUs.',
@@ -106,11 +148,133 @@ export const EDITABLE_FIELDS = [
   {
     key: 'sonarEnabled',
     path: 'sonarqube.enabled',
+    category: 'quality',
     type: 'boolean',
     label: 'Activar análisis SonarQube',
     help: 'Pasa el código por SonarQube y bloquea si el quality gate falla. Requiere SonarQube corriendo.',
     default: false,
   },
+  // v2.30.0 — pipeline role toggles. Cada uno controla si una etapa
+  // del pipeline se ejecuta. Brain está OFF por defecto porque sigue
+  // siendo opt-in (v2 feature); el resto reflejan los defaults de
+  // src/config/defaults.js.
+  {
+    key: 'plannerEnabled',
+    path: 'pipeline.planner.enabled',
+    category: 'pipeline',
+    type: 'boolean',
+    label: 'Activar rol planner',
+    help: 'Genera un plan de implementación antes de codificar. Útil en tareas con >2 archivos o devPoints ≥ 3.',
+    default: true,
+  },
+  {
+    key: 'researcherEnabled',
+    path: 'pipeline.researcher.enabled',
+    category: 'pipeline',
+    type: 'boolean',
+    label: 'Activar rol researcher',
+    help: 'Investiga la codebase antes del coder (lectura de archivos clave, patrones existentes).',
+    default: true,
+  },
+  {
+    key: 'architectEnabled',
+    path: 'pipeline.architect.enabled',
+    category: 'pipeline',
+    type: 'boolean',
+    label: 'Activar rol architect',
+    help: 'Diseña la arquitectura (capas, patrones, contratos) antes de codificar. Recomendado en cambios estructurales.',
+    default: true,
+  },
+  {
+    key: 'testerEnabled',
+    path: 'pipeline.tester.enabled',
+    category: 'pipeline',
+    type: 'boolean',
+    label: 'Activar rol tester',
+    help: 'Genera tests automáticos durante o después del coder. Refuerza la calidad.',
+    default: true,
+  },
+  {
+    key: 'securityEnabled',
+    path: 'pipeline.security.enabled',
+    category: 'pipeline',
+    type: 'boolean',
+    label: 'Activar rol security',
+    help: 'Audita el código contra OWASP-style issues, secret leaks, dependencias vulnerables.',
+    default: true,
+  },
+  {
+    key: 'refactorerEnabled',
+    path: 'pipeline.refactorer.enabled',
+    category: 'pipeline',
+    type: 'boolean',
+    label: 'Activar rol refactorer',
+    help: 'Pasa una iteración de limpieza tras el coder (extract function, rename, etc.).',
+    default: false,
+  },
+  {
+    key: 'impeccableEnabled',
+    path: 'pipeline.impeccable.enabled',
+    category: 'pipeline',
+    type: 'boolean',
+    label: 'Activar rol impeccable',
+    help: 'Auditoría UI/UX automática (Lighthouse, a11y, contraste). Solo útil en frontend.',
+    default: false,
+  },
+  {
+    key: 'brainEnabled',
+    path: 'pipeline.brain.enabled',
+    category: 'pipeline',
+    type: 'boolean',
+    label: 'Activar Karajan Brain (v2)',
+    help: 'Orquestador IA central: enriquece feedback, comprime outputs y verifica cambios reales. Opt-in.',
+    default: false,
+  },
+  // v2.30.0 — RAG controls. Sólo se exponen las claves que el código
+  // realmente lee hoy (rag.preload.* en rag-context-stage.js y
+  // rag.embedder.provider en embedders/factory.js). mode/alpha/rerank
+  // se controlan vía flags CLI; cuando se cableen en config se añadirán
+  // aquí (ver task #99).
+  {
+    key: 'ragPreloadEnabled',
+    path: 'rag.preload.enabled',
+    category: 'rag',
+    type: 'boolean',
+    label: 'Activar pre-carga RAG en el pipeline',
+    help: 'Si está activo, antes de cada iteración se inyecta contexto del vector store en el prompt del coder.',
+    default: false,
+  },
+  {
+    key: 'ragPreloadTopK',
+    path: 'rag.preload.topK',
+    category: 'rag',
+    type: 'number',
+    label: 'Nº de chunks a pre-cargar (topK)',
+    help: 'Cuántos fragmentos del vector store se inyectan como contexto. 3-5 funciona bien; subir gasta tokens.',
+    min: 1,
+    max: 20,
+    default: 5,
+  },
+  {
+    key: 'ragPreloadScope',
+    path: 'rag.preload.scope',
+    category: 'rag',
+    type: 'select',
+    label: 'Scope de la pre-carga RAG',
+    help: '"all" mezcla todo. "code" solo busca en el código indexado, "plans" en planes previos, "onboarding" en el brief del proyecto.',
+    options: ['all', 'code', 'plans', 'onboarding'],
+    default: 'all',
+  },
+  {
+    key: 'ragEmbedderProvider',
+    path: 'rag.embedder.provider',
+    category: 'rag',
+    type: 'select',
+    label: 'Proveedor de embeddings RAG',
+    help: 'Ollama local es gratis. OpenAI/Voyage/Cohere/Mistral son cloud (requieren API key). ONNX corre 100% local con @huggingface/transformers.',
+    options: ['ollama', 'openai', 'voyage', 'cohere', 'mistral', 'onnx'],
+    default: 'ollama',
+  },
 ];
 
 const ROLES_FOR_MODEL_MODE = [
@@ -203,8 +367,13 @@ function applyModelMode(parsed, mode) {
  *
  * Returns sane defaults when the file doesn't exist yet.
  */
-export function readConfig() {
-  const p = configPath();
+export function readConfig({ scope = 'global' } = {}) {
+  // PR4 — accept scope. Default 'global' preserves the previous behavior;
+  // 'project' reads <projectDir>/.karajan/kj.config.yml.
+  if (!SCOPES.includes(scope)) {
+    throw new Error(`Scope inválido: ${scope}. Permitidos: ${SCOPES.join(', ')}`);
+  }
+  const p = configPath(scope);
   let parsed = {};
   let exists = false;
   if (existsSync(p)) {
@@ -222,7 +391,11 @@ export function readConfig() {
     if (value === undefined) value = f.default;
     return { ...f, value };
   });
-  return { path: p, exists, fields, raw: parsed };
+  // v2.30.0 — also expose CATEGORIES so the modal can render grouped
+  // sections without re-importing the constant client-side. Ordered
+  // by `order` for deterministic UI.
+  const categories = [...CATEGORIES].sort((a, b) => (a.order ?? 999) - (b.order ?? 999));
+  return { path: p, scope, exists, fields, categories, raw: parsed };
 }
 
 /**
@@ -232,16 +405,20 @@ export function readConfig() {
  *
  * @returns {{ path: string, written: boolean, applied: object[], errors: string[] }}
  */
-export function writeConfigPatch(patch) {
+export function writeConfigPatch(patch, { scope = 'global' } = {}) {
+  // PR4 — same shape as readConfig: scope decides target file.
+  if (!SCOPES.includes(scope)) {
+    return { path: '', scope, written: false, applied: [], errors: [`Scope inválido: ${scope}. Permitidos: ${SCOPES.join(', ')}`] };
+  }
   if (!patch || typeof patch !== 'object') {
-    return { path: configPath(), written: false, applied: [], errors: ['patch debe ser un objeto'] };
+    return { path: configPath(scope), scope, written: false, applied: [], errors: ['patch debe ser un objeto'] };
   }
   // Read current state (or empty if file doesn't exist yet).
-  const p = configPath();
+  const p = configPath(scope);
   let parsed = {};
   if (existsSync(p)) {
     try { parsed = yaml.load(readFileSync(p, 'utf8'), { json: true }) || {}; }
-    catch (err) { return { path: p, written: false, applied: [], errors: [`No se pudo parsear el yml actual: ${err.message}`] }; }
+    catch (err) { return { path: p, scope, written: false, applied: [], errors: [`No se pudo parsear el yml actual: ${err.message}`] }; }
   }
   const errors = [];
   const applied = [];
@@ -268,18 +445,18 @@ export function writeConfigPatch(patch) {
     else setDeep(parsed, field.path, field.type === 'number' ? Number(val) : val);
     applied.push({ key, value: val });
   }
-  if (errors.length > 0) return { path: p, written: false, applied, errors };
+  if (errors.length > 0) return { path: p, scope, written: false, applied, errors };
 
   // Write atomically: serialize → write to .tmp → rename. Backup the
   // existing file first so the user can recover.
   const dir = dirname(p);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  if (existsSync(p)) { try { copyFileSync(p, backupPath()); } catch { /* best-effort */ } }
+  if (existsSync(p)) { try { copyFileSync(p, backupPath(scope)); } catch { /* best-effort */ } }
   const dump = yaml.dump(parsed, { lineWidth: 120 });
   // mkstemp would be nicer but we want to stay in the same dir for
   // a guaranteed-atomic rename across the same filesystem.
   const tmpFile = join(dir, `.kj.config.yml.${process.pid}.${Date.now()}.tmp`);
   writeFileSync(tmpFile, dump, 'utf8');
   renameSync(tmpFile, p);
-  return { path: p, written: true, applied, errors: [] };
+  return { path: p, scope, written: true, applied, errors: [] };
 }

package/packages/hu-board/src/routes/api.js

@@ -1031,29 +1031,41 @@ router.post('/projects/:id/run', (req, res) => {
 });
 
 /**
- * GET /api/config — read the editable subset of ~/.karajan/kj.config.yml.
+ * GET /api/config — read the editable subset of the kj.config.yml.
  * Powers the board's settings modal; non-editable keys in the yml are
  * left untouched on PUT (see writeConfigPatch's whitelist semantics).
+ *
+ * v2.30.0 PR4 — supports `?scope=global|project`:
+ *   - `global` (default): reads ~/.karajan/kj.config.yml.
+ *   - `project`: reads <projectDir>/.karajan/kj.config.yml.
+ * Unknown scopes are 400'd. Response includes the resolved `scope` and
+ * `path` so the UI can show which file backs the current view.
  */
-router.get('/config', (_req, res) => {
+router.get('/config', (req, res) => {
   try {
-    const data = readConfig();
+    const scope = req.query?.scope || 'global';
+    const data = readConfig({ scope });
     res.json(data);
   } catch (err) {
-    res.status(500).json({ error: err.message });
+    res.status(400).json({ error: err.message });
   }
 });
 
 /**
- * PUT /api/config — apply a patch to the yml. Body is `{ patch: { key: value } }`
- * with the keys defined in EDITABLE_FIELDS. Unknown keys are 400'd; type
- * errors are 400'd; validation errors are 400'd. Writes are atomic
- * (tmp + rename) and a `.bak` is kept of the previous content.
+ * PUT /api/config — apply a patch to the yml. Body is
+ * `{ patch: { key: value }, scope?: 'global'|'project' }` with the keys
+ * defined in EDITABLE_FIELDS. Unknown keys are 400'd; type errors are
+ * 400'd; validation errors are 400'd. Writes are atomic (tmp + rename)
+ * and a `.bak` is kept of the previous content.
+ *
+ * v2.30.0 PR4 — `scope` decides which file is patched. Default 'global'
+ * preserves the previous behavior.
  */
 router.put('/config', (req, res) => {
   try {
     const patch = req.body?.patch;
-    const result = writeConfigPatch(patch);
+    const scope = req.body?.scope || 'global';
+    const result = writeConfigPatch(patch, { scope });
     if (!result.written) {
       return res.status(400).json({ error: 'No se pudo guardar la configuración', details: result });
     }

package/packages/hu-board/src/routes/rag.js

@@ -0,0 +1,36 @@
+// KJC-TSK-0445 — RAG retrieval-quality dashboard route.
+// GET /api/rag/stats → snapshot of the local rag.db (counts per kind/project,
+// active embedder, db size, last-index timestamp). Missing DB returns an
+// "uninitialized" payload so the dashboard renders an empty state cleanly.
+import { Router } from "express";
+import { existsSync, statSync } from "node:fs";
+import Database from "better-sqlite3";
+import { dbPath } from "../../../../src/rag/vec-store.js";
+import { readConfig } from "../config-yaml.js";
+
+const router = Router();
+const DIMS = { ollama: 768, openai: 1536, voyage: 1024, cohere: 1024, mistral: 1024, onnx: 384 };
+
+function embedder() {
+  try {
+    const e = (readConfig()?.rag?.embedder) || {};
+    const provider = e.provider || "ollama";
+    return { provider, model: e.model || null, dim: e.dim || DIMS[provider] || null };
+  } catch { return { provider: "ollama", model: null, dim: 768 }; }
+}
+
+router.get("/stats", (_req, res) => {
+  const path = dbPath();
+  if (!existsSync(path)) return res.json({ ok: true, initialized: false, message: "rag.db not initialized — run `kj rag index <dir>` to start indexing.", embedder: embedder() });
+  try {
+    const db = new Database(path, { readonly: true, fileMustExist: true });
+    const total_chunks = db.prepare("SELECT COUNT(*) AS n FROM chunks").get().n;
+    const by_kind = db.prepare("SELECT kind, COUNT(*) AS n FROM chunks GROUP BY kind").all();
+    const by_project = db.prepare("SELECT COALESCE(project_slug, '(no slug)') AS project, COUNT(*) AS n FROM chunks GROUP BY project_slug ORDER BY n DESC LIMIT 20").all();
+    const last_indexed = db.prepare("SELECT MAX(created_at) AS ts FROM chunks").get().ts;
+    db.close();
+    res.json({ ok: true, initialized: true, db_path: path, db_size_bytes: statSync(path).size, total_chunks, by_kind, by_project, last_indexed, embedder: embedder() });
+  } catch (err) { res.status(500).json({ ok: false, error: String(err.message || err) }); }
+});
+
+export default router;

package/packages/hu-board/src/server.js

@@ -9,6 +9,7 @@ import { initDb, closeDb } from './db.js';
 import { fullScan, startWatcher } from './sync.js';
 import apiRoutes from './routes/api.js';
 import pipelineRoutes from './routes/pipeline.js';
+import ragRoutes from './routes/rag.js';
 import { authMiddleware } from './auth.js';
 import { getOrCreateToken, getTokenPath } from './token-store.js';
 import { reapZombieSessions } from './zombie-reaper.js';
@@ -298,6 +299,7 @@ async function main() {
   app.use(express.static(PUBLIC_DIR, { setHeaders: noStoreHeaders, etag: false, lastModified: false }));
   app.use('/api', buildRateLimiter(), authMiddleware(), apiRoutes);
   app.use('/api/pipeline', authMiddleware(), pipelineRoutes);
+  app.use('/api/rag', authMiddleware(), ragRoutes);
 
   // SPA fallback: serve index.html for non-API, non-static routes
   app.get('/{*splat}', (_req, res) => {

package/scripts/esbuild-sea.config.mjs

@@ -173,9 +173,16 @@ const ragStubPlugin = {
           // KJC-TSK-0441 — RAG chokidar watcher.
           startWatcher: notAvailable, readPidFile: notAvailable, clearPidFile: notAvailable,
           isPidAlive: notAvailable, writePidFile: notAvailable,
-          // KJC-TSK-0442 — RAG embedders cloud + factory.
+          // KJC-TSK-0442 / KJC-TSK-0446 — RAG embedders cloud + factory.
           makeEmbedder: notAvailable, OpenAIEmbedder: notAvailable, VoyageEmbedder: notAvailable,
           OpenAIEmbedderError: notAvailable, VoyageEmbedderError: notAvailable, PROVIDERS: notAvailable,
+          CohereEmbedder: notAvailable, CohereEmbedderError: notAvailable,
+          MistralEmbedder: notAvailable, MistralEmbedderError: notAvailable,
+          ONNXEmbedder: notAvailable, ONNXEmbedderError: notAvailable,
+          // KJC-TSK-0448 — RAG --where metadata filter.
+          parseWhere: notAvailable, buildWhereSql: notAvailable,
+          // KJC-TSK-0449 — RAG cross-encoder rerank.
+          rerank: notAvailable, RerankError: notAvailable, _resetPipeline: notAvailable,
           default: notAvailable,
         };
       `,

package/src/cli/register-meta.js

@@ -117,6 +117,9 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--project <slug>", "Filter by project slug. Pass 'all' to query across every indexed project. Default: cwd basename")
     .option("--mode <mode>", "hybrid (default) | semantic (cosine only) | keyword (BM25 only)", "hybrid")
     .option("--alpha <n>", "Hybrid weight for semantic component (0..1). Default 0.6", "0.6")
+    .option("--where <clause>", "Metadata filter, e.g. 'symbol=loadConfig' or 'hu_id=HU-003 AND kind=plan'")
+    .option("--rerank", "Apply cross-encoder rerank to top-K (needs @huggingface/transformers, slower but more precise)")
+    .option("--rerank-model <name>", "Cross-encoder model id. Default: Xenova/ms-marco-MiniLM-L-6-v2")
     .option("--json", "Output the hits as JSON")
     .action(async (text, flags) => {
       await withConfig(pkgVersion, "rag-query", flags, async ({ config, logger }) => {

package/src/commands/rag.js

@@ -57,7 +57,9 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
     }
     const mode = flags.mode || "hybrid";
     const alpha = Math.max(0, Math.min(1, Number(flags.alpha) || 0.6));
-    const hits = await query(db, makeEmbedder(config), text, { topK, scope, project, mode, alpha });
+    const where = flags.where || null;
+    const rerankOpts = flags.rerank ? { model: flags.rerankModel } : null;
+    const hits = await query(db, makeEmbedder(config), text, { topK, scope, project, mode, alpha, where, rerankOpts });
     if (flags.json) {
       process.stdout.write(`${JSON.stringify(hits)}\n`);
     } else {

package/src/rag/embedders/cohere.js

@@ -0,0 +1,28 @@
+// KJC-TSK-0446 — Cohere embed-v3 adapter. Cohere returns
+// { embeddings: { float: [[...]] } } when `embedding_types: ["float"]`
+// is requested, or { embeddings: [[...]] } in legacy v1. We extract the
+// modern shape with a v1 fallback.
+import { cloudEmbed } from "./_cloud-base.js";
+
+const DEFAULTS = { url: "https://api.cohere.com/v2/embed", model: "embed-multilingual-v3.0", dim: 1024, timeoutMs: 30000 };
+
+export class CohereEmbedderError extends Error {
+  constructor(message, { cause, status } = {}) { super(message); this.name = "CohereEmbedderError"; if (cause) this.cause = cause; if (status != null) this.status = status; }
+}
+
+export class CohereEmbedder {
+  constructor({ url = DEFAULTS.url, apiKey = process.env.KJ_COHERE_KEY, model = process.env.KJ_COHERE_EMBED_MODEL || DEFAULTS.model, dim = DEFAULTS.dim, timeoutMs = DEFAULTS.timeoutMs, fetchFn = globalThis.fetch } = {}) {
+    // KJC architecture invariant: scoped env var (KJ_COHERE_KEY), not the
+    // generic COHERE_API_KEY — same rule as OpenAI/Voyage adapters.
+    if (!apiKey) throw new CohereEmbedderError("Cohere embedder requires an api_key (config.rag.embedder.api_key or KJ_COHERE_KEY env)");
+    Object.assign(this, { url, apiKey, model, dim, timeoutMs, fetch: fetchFn });
+  }
+  async embed(text) {
+    return cloudEmbed(this, text, CohereEmbedderError, {
+      provider: "Cohere",
+      body: { model: this.model, texts: [text], input_type: "search_document", embedding_types: ["float"] },
+      extract: (b) => b?.embeddings?.float?.[0] || b?.embeddings?.[0],
+    });
+  }
+  async embedBatch(texts) { if (!Array.isArray(texts)) throw new CohereEmbedderError("embedBatch: texts must be an array"); const out = []; for (const t of texts) out.push(await this.embed(t)); return out; }
+}

package/src/rag/embedders/factory.js

@@ -1,12 +1,22 @@
-// KJC-TSK-0442 — Embedder factory. Selects provider from
-// config.rag.embedder.provider (ollama | openai | voyage; default ollama).
-// Each provider has its own dim default; the factory wires it so the
-// caller does not need to know.
+// KJC-TSK-0442 / KJC-TSK-0446 — Embedder factory. Selects provider from
+// config.rag.embedder.provider (ollama | openai | voyage | cohere | mistral;
+// default ollama). Each provider has its own dim default; the factory wires
+// it so the caller does not need to know.
 import { OllamaEmbedder } from "../embedder.js";
 import { OpenAIEmbedder } from "./openai.js";
 import { VoyageEmbedder } from "./voyage.js";
+import { CohereEmbedder } from "./cohere.js";
+import { MistralEmbedder } from "./mistral.js";
+import { ONNXEmbedder } from "./onnx.js";
 
-const PROVIDERS = { ollama: { cls: OllamaEmbedder, dim: 768 }, openai: { cls: OpenAIEmbedder, dim: 1536 }, voyage: { cls: VoyageEmbedder, dim: 1024 } };
+const PROVIDERS = {
+  ollama: { cls: OllamaEmbedder, dim: 768 },
+  openai: { cls: OpenAIEmbedder, dim: 1536 },
+  voyage: { cls: VoyageEmbedder, dim: 1024 },
+  cohere: { cls: CohereEmbedder, dim: 1024 },
+  mistral: { cls: MistralEmbedder, dim: 1024 },
+  onnx: { cls: ONNXEmbedder, dim: 384 },
+};
 
 export function makeEmbedder(config = {}) {
   const cfg = config?.rag?.embedder || {};

package/src/rag/embedders/mistral.js

@@ -0,0 +1,26 @@
+// KJC-TSK-0446 — Mistral AI embeddings adapter. EU-hosted, useful for
+// users with GDPR constraints that prefer not to send chunks to US
+// endpoints. Single model today (`mistral-embed`, 1024 dim).
+import { cloudEmbed } from "./_cloud-base.js";
+
+const DEFAULTS = { url: "https://api.mistral.ai/v1/embeddings", model: "mistral-embed", dim: 1024, timeoutMs: 30000 };
+
+export class MistralEmbedderError extends Error {
+  constructor(message, { cause, status } = {}) { super(message); this.name = "MistralEmbedderError"; if (cause) this.cause = cause; if (status != null) this.status = status; }
+}
+
+export class MistralEmbedder {
+  constructor({ url = DEFAULTS.url, apiKey = process.env.KJ_MISTRAL_KEY, model = process.env.KJ_MISTRAL_EMBED_MODEL || DEFAULTS.model, dim = DEFAULTS.dim, timeoutMs = DEFAULTS.timeoutMs, fetchFn = globalThis.fetch } = {}) {
+    // KJC architecture invariant: scoped env var (KJ_MISTRAL_KEY).
+    if (!apiKey) throw new MistralEmbedderError("Mistral embedder requires an api_key (config.rag.embedder.api_key or KJ_MISTRAL_KEY env)");
+    Object.assign(this, { url, apiKey, model, dim, timeoutMs, fetch: fetchFn });
+  }
+  async embed(text) {
+    return cloudEmbed(this, text, MistralEmbedderError, {
+      provider: "Mistral",
+      body: { model: this.model, input: [text] },
+      extract: (b) => b?.data?.[0]?.embedding,
+    });
+  }
+  async embedBatch(texts) { if (!Array.isArray(texts)) throw new MistralEmbedderError("embedBatch: texts must be an array"); const out = []; for (const t of texts) out.push(await this.embed(t)); return out; }
+}

package/src/rag/embedders/onnx.js

@@ -0,0 +1,63 @@
+// KJC-TSK-0447 — ONNX local embedder via @huggingface/transformers
+// (formerly @xenova/transformers). Runs sentence-transformer models
+// directly in Node — no API key, no Docker, no Ollama.
+//
+// First call downloads the model weights to ~/.cache/huggingface/ (~80 MB
+// for the default MiniLM). Subsequent calls reuse the cache, so the steady
+// state is fully offline.
+//
+// Default model: `Xenova/all-MiniLM-L6-v2` (384 dim, ~80 MB, fast).
+// Higher-quality alternative: `Xenova/jina-embeddings-v2-base-en`
+// (768 dim, ~260 MB, slower but better for retrieval).
+
+const DEFAULTS = { model: "Xenova/all-MiniLM-L6-v2", dim: 384, pooling: "mean", normalize: true };
+
+export class ONNXEmbedderError extends Error {
+  constructor(message, { cause } = {}) { super(message); this.name = "ONNXEmbedderError"; if (cause) this.cause = cause; }
+}
+
+async function loadTransformers() {
+  // Prefer the modern @huggingface/transformers (post-2024 rebrand);
+  // fall back to @xenova/transformers for users still on the legacy package.
+  // Both are optional peer deps — Karajan does not ship them by default to
+  // keep the install size small (~500 MB with WASM + weights). The user
+  // installs whichever they prefer when they opt into provider: onnx.
+  /* eslint-disable import-x/no-unresolved */
+  try { return await import("@huggingface/transformers"); }
+  catch (e1) {
+    try { return await import("@xenova/transformers"); }
+    catch (e2) {
+      throw new ONNXEmbedderError(
+        "ONNX embedder requires @huggingface/transformers (or legacy @xenova/transformers). Install with `npm install @huggingface/transformers`.",
+        { cause: e2 },
+      );
+    }
+  }
+  /* eslint-enable import-x/no-unresolved */
+}
+
+export class ONNXEmbedder {
+  constructor({ model = process.env.KJ_ONNX_EMBED_MODEL || DEFAULTS.model, dim = DEFAULTS.dim, pooling = DEFAULTS.pooling, normalize = DEFAULTS.normalize } = {}) {
+    Object.assign(this, { model, dim, pooling, normalize, _pipe: null });
+  }
+  async _ensurePipeline() {
+    if (this._pipe) return this._pipe;
+    const transformers = await loadTransformers();
+    this._pipe = await transformers.pipeline("feature-extraction", this.model);
+    return this._pipe;
+  }
+  async embed(text) {
+    if (typeof text !== "string" || text.length === 0) throw new ONNXEmbedderError("embed: text must be a non-empty string");
+    const pipe = await this._ensurePipeline();
+    const out = await pipe(text, { pooling: this.pooling, normalize: this.normalize });
+    const arr = Array.from(out.data || []);
+    if (arr.length !== this.dim) throw new ONNXEmbedderError(`ONNX dim mismatch: got ${arr.length}, expected ${this.dim} for model ${this.model}`);
+    return Float32Array.from(arr);
+  }
+  async embedBatch(texts) {
+    if (!Array.isArray(texts)) throw new ONNXEmbedderError("embedBatch: texts must be an array");
+    const out = [];
+    for (const t of texts) out.push(await this.embed(t));
+    return out;
+  }
+}

package/src/rag/rerank.js

@@ -0,0 +1,74 @@
+// KJC-TSK-0449 — Cross-encoder rerank stage. Re-scores the top-N hits
+// from the hybrid retriever using a (query, passage) cross-encoder.
+//
+// Cross-encoders are slower than the bi-encoder embedders (they jointly
+// encode query + passage instead of caching the passage), but they are
+// substantially more precise for the final top-K ranking. Karajan calls
+// the reranker only on the post-fusion candidates (≤topK*2), so the
+// added latency is bounded.
+//
+// Model is loaded dynamically via @huggingface/transformers (same dep as
+// the ONNX embedder, KJC-TSK-0447). Default: `Xenova/ms-marco-MiniLM-L-6-v2`,
+// the de-facto standard sentence-transformers reranker.
+
+const DEFAULT_MODEL = "Xenova/ms-marco-MiniLM-L-6-v2";
+
+export class RerankError extends Error {
+  constructor(message, { cause } = {}) { super(message); this.name = "RerankError"; if (cause) this.cause = cause; }
+}
+
+async function loadTransformers() {
+  /* eslint-disable import-x/no-unresolved */
+  try { return await import("@huggingface/transformers"); }
+  catch (e1) {
+    try { return await import("@xenova/transformers"); }
+    catch (e2) {
+      throw new RerankError(
+        "rerank requires @huggingface/transformers (or legacy @xenova/transformers). Install with `npm install @huggingface/transformers`.",
+        { cause: e2 },
+      );
+    }
+  }
+  /* eslint-enable import-x/no-unresolved */
+}
+
+/**
+ * Lazy singleton — first call downloads weights (~80 MB), every subsequent
+ * call reuses the same pipeline instance.
+ */
+let _pipelinePromise = null;
+function getPipeline(modelName) {
+  if (!_pipelinePromise) _pipelinePromise = (async () => {
+    const t = await loadTransformers();
+    // text-classification pipeline returns the cross-encoder relevance score
+    // for a `[query, passage]` text pair when applied to a CE model.
+    return t.pipeline("text-classification", modelName);
+  })();
+  return _pipelinePromise;
+}
+
+/** Reset for tests. */
+export function _resetPipeline() { _pipelinePromise = null; }
+
+/**
+ * Rerank `hits` against `queryText` using the cross-encoder. Returns a NEW
+ * array sorted by descending rerank score (best first), `score` mutated
+ * so the existing downstream code (kindBoost, slicing) keeps working.
+ *
+ * Each input hit is treated as a [query, hit.text] pair. Truncates the
+ * passage to `maxChars` to avoid blowing past the CE model's context
+ * window — most CE models handle 512 tokens, ~2000 chars is safe.
+ *
+ * If `pipelineFn` is injected (tests), it bypasses model loading.
+ */
+export async function rerank(queryText, hits, { model = process.env.KJ_RERANK_MODEL || DEFAULT_MODEL, maxChars = 2000, pipelineFn = null } = {}) {
+  if (!queryText || typeof queryText !== "string") throw new RerankError("rerank: queryText must be a non-empty string");
+  if (!Array.isArray(hits)) throw new RerankError("rerank: hits must be an array");
+  if (hits.length === 0) return hits;
+  const pipe = pipelineFn || await getPipeline(model);
+  const pairs = hits.map((h) => ({ text: queryText, text_pair: String(h.text || "").slice(0, maxChars) }));
+  const results = await pipe(pairs);
+  return hits
+    .map((h, i) => ({ ...h, _rerank: Number(results[i]?.score) || 0, score: -Number(results[i]?.score) || 0 }))
+    .sort((a, b) => a.score - b.score);
+}

package/src/rag/retriever.js

@@ -1,5 +1,7 @@
 // KJC-PCS-0049 Step 5 — Retriever for the RAG pipeline.
 import { searchSimilar, searchBM25 } from "./vec-store.js";
+import { parseWhere, buildWhereSql } from "./where-parser.js";
+import { rerank } from "./rerank.js";
 
 const DEFAULT_KIND_BOOST = { plan: 0.05, onboarding: 0.03, code: 0 };
 
@@ -39,14 +41,21 @@ function fuseHits(semantic, keyword, alpha, mode) {
   return list;
 }
 
-export async function query(db, embedder, text, { topK = 5, scope = "all", kindBoost = DEFAULT_KIND_BOOST, project = null, mode = "hybrid", alpha = 0.6 } = {}) {
+export async function query(db, embedder, text, { topK = 5, scope = "all", kindBoost = DEFAULT_KIND_BOOST, project = null, mode = "hybrid", alpha = 0.6, where = null, rerankOpts = null } = {}) {
   if (!text || typeof text !== "string") throw new Error("query: text must be a non-empty string");
   const fetchK = Math.min(50, topK * 2);
   const scopeKind = scope === "plans" ? "plan" : scope === "code" ? "code" : scope === "onboarding" ? "onboarding" : null;
+  // KJC-TSK-0448 — metadata filter. `where` is a string like "symbol=Foo AND
+  // hu_id=HU-003"; we parse once and reuse the SQL fragment across both
+  // semantic and keyword searches.
+  const parsed = parseWhere(where);
+  if (!parsed.ok) throw new Error(`query: ${parsed.error}`);
+  const { sql: whereSql, params: whereParams } = buildWhereSql(parsed.clauses);
+  const opts = { kind: scopeKind, project, whereSql, whereParams };
   const wantSemantic = mode !== "keyword";
   const wantKeyword = mode !== "semantic";
-  const semanticHits = wantSemantic ? searchSimilar(db, await embedder.embed(text), fetchK, { kind: scopeKind, project }) : [];
-  const keywordHits = wantKeyword ? searchBM25(db, text, fetchK, { kind: scopeKind, project }) : [];
+  const semanticHits = wantSemantic ? searchSimilar(db, await embedder.embed(text), fetchK, opts) : [];
+  const keywordHits = wantKeyword ? searchBM25(db, text, fetchK, opts) : [];
   const raw = fuseHits(semanticHits, keywordHits, alpha, mode);
   if (raw.length === 0) return [];
   const boostSources = shouldBoostSources(text);
@@ -55,6 +64,11 @@ export async function query(db, embedder, text, { topK = 5, scope = "all", kindB
     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);
+  // KJC-TSK-0449 — optional cross-encoder rerank. When `rerankOpts` is set,
+  // we re-score the topK survivors with a (query, passage) cross-encoder;
+  // the kind+source boost has already been applied, so the rerank acts as
+  // a finer-grained quality lever on top.
+  if (rerankOpts) return await rerank(text, reranked, rerankOpts);
   return reranked;
 }
 

package/src/rag/vec-store.js

@@ -106,7 +106,7 @@ 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, project = null } = {}) {
+export function searchSimilar(db, embedding, topK = 5, { kind = null, project = null, whereSql = "", whereParams = [] } = {}) {
   const buf = embedding instanceof Float32Array ? embedding : Float32Array.from(embedding);
   const kindClause = kind ? "AND c.kind = ?" : "";
   const projectClause = project ? "AND c.project_slug = ?" : "";
@@ -114,12 +114,13 @@ export function searchSimilar(db, embedding, topK = 5, { kind = null, project =
     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} ${projectClause}
+    WHERE v.embedding MATCH ? AND k = ? ${kindClause} ${projectClause}${whereSql}
     ORDER BY v.distance
   `;
   const params = [Buffer.from(buf.buffer), topK];
   if (kind) params.push(kind);
   if (project) params.push(project);
+  if (whereParams.length) params.push(...whereParams);
   const rows = db.prepare(sql).all(...params);
   return rows.map((r) => ({ ...r, metadata: r.metadata ? safeParse(r.metadata) : null }));
 }
@@ -163,7 +164,7 @@ export function countChunks(db, { kind = null } = {}) {
  * relevance (lower bm25 = better in SQLite FTS5). `query` is sanitized for
  * the FTS5 grammar: special chars are stripped, words split on whitespace.
  */
-export function searchBM25(db, queryText, topK = 10, { kind = null, project = null } = {}) {
+export function searchBM25(db, queryText, topK = 10, { kind = null, project = null, whereSql = "", whereParams = [] } = {}) {
   const cleaned = String(queryText || "").replace(/["'()]/g, " ").split(/\s+/).filter(Boolean).join(" OR ");
   if (!cleaned) return [];
   const kindClause = kind ? "AND c.kind = ?" : "";
@@ -171,12 +172,13 @@ export function searchBM25(db, queryText, topK = 10, { kind = null, project = nu
   const sql = `
     SELECT c.id, c.source, c.kind, c.text, c.metadata, c.project_slug, bm25(chunks_fts) AS bm25
     FROM chunks_fts JOIN chunks c ON c.id = chunks_fts.rowid
-    WHERE chunks_fts MATCH ? ${kindClause} ${projectClause}
+    WHERE chunks_fts MATCH ? ${kindClause} ${projectClause}${whereSql}
     ORDER BY bm25 LIMIT ?
   `;
   const params = [cleaned];
   if (kind) params.push(kind);
   if (project) params.push(project);
+  if (whereParams.length) params.push(...whereParams);
   params.push(topK);
   try {
     const rows = db.prepare(sql).all(...params);

package/src/rag/where-parser.js

@@ -0,0 +1,54 @@
+// KJC-TSK-0448 — minimal --where filter parser for metadata-aware RAG
+// queries. Grammar (intentionally small):
+//
+//   clause     := pair ( "AND" pair )*
+//   pair       := IDENT "=" VALUE
+//   IDENT      := [A-Za-z_][A-Za-z0-9_.-]*
+//   VALUE      := unquoted token  | "quoted string"
+//
+// Examples:
+//   symbol=loadConfig
+//   hu_id=HU-003 AND kind=plan
+//   "headingPath.0"=Architecture
+//
+// Returns { ok: true, clauses: [["symbol","loadConfig"], ...] } or
+// { ok: false, error: "...explanation..." }. The retriever turns each
+// clause into a `json_extract(c.metadata, '$.<key>') = ?` SQL fragment;
+// the `kind` key is special-cased to filter the column directly.
+
+const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_.-]*$/;
+
+export function parseWhere(input) {
+  if (input == null) return { ok: true, clauses: [] };
+  if (typeof input !== "string") return { ok: false, error: "where: input must be a string" };
+  const s = input.trim();
+  if (!s) return { ok: true, clauses: [] };
+  const parts = s.split(/\s+AND\s+/i);
+  const clauses = [];
+  for (const p of parts) {
+    const eq = p.indexOf("=");
+    if (eq <= 0) return { ok: false, error: `where: bad pair "${p}" — expected key=value` };
+    const key = p.slice(0, eq).trim().replace(/^"|"$/g, "");
+    let val = p.slice(eq + 1).trim();
+    if (!IDENT_RE.test(key)) return { ok: false, error: `where: invalid key "${key}"` };
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) val = val.slice(1, -1);
+    if (val.length === 0) return { ok: false, error: `where: empty value for key "${key}"` };
+    clauses.push([key, val]);
+  }
+  return { ok: true, clauses };
+}
+
+/**
+ * Build a `(sqlFragment, params)` pair to append to a chunks-table query.
+ * `kind` filters the column directly; everything else goes through json_extract.
+ */
+export function buildWhereSql(clauses) {
+  if (!clauses?.length) return { sql: "", params: [] };
+  const fragments = [];
+  const params = [];
+  for (const [k, v] of clauses) {
+    if (k === "kind") { fragments.push("c.kind = ?"); params.push(v); }
+    else { fragments.push(`json_extract(c.metadata, '$.${k}') = ?`); params.push(v); }
+  }
+  return { sql: ` AND ${fragments.join(" AND ")}`, params };
+}