contextdevkit 1.8.0

package/templates/contextkit/squads/agent-forge/lib/package-ops.mjs

@@ -0,0 +1,101 @@
+/**
+ * package-ops — shared helpers for every `/forge-*` maintenance command.
+ * Pure + zero-dep on the JSON side; YAML reads are gated on `lib/yaml.mjs`
+ * (optional dep, ADR-0013). The `/forge-*` CLIs share these so the inspection
+ * + mutation surface stays consistent.
+ *
+ * The Agent Package directory convention: `<root>/<name>@<semver>/manifest.yaml`.
+ * `discoverPackages(root)` walks the registry without loading any YAML — it
+ * matches the directory shape — so a missing `yaml` dep does not break listing.
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const PKG_RE = /^([a-z][a-z0-9-]*)@(\d+\.\d+\.\d+(?:-[\w.-]+)?)$/;
+
+/** List every `<name>@<semver>` directory under `root`. Pure JSON, no YAML needed. */
+export async function discoverPackages(root) {
+  const out = [];
+  let entries = [];
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const match = PKG_RE.exec(entry.name);
+    if (!match) continue;
+    out.push({ name: match[1], version: match[2], path: join(root, entry.name) });
+  }
+  return out.sort((a, b) => (a.name === b.name ? a.version.localeCompare(b.version) : a.name.localeCompare(b.name)));
+}
+
+/** Read `manifest.yaml` for one package via the optional yaml dep (ADR-0013). */
+export async function loadManifest(pkgPath) {
+  const { parseYaml } = await import('./yaml.mjs');
+  const raw = await readFile(join(pkgPath, 'manifest.yaml'), 'utf-8');
+  return parseYaml(raw);
+}
+
+/** Read `.agentforgerc` (zero-dep JSON; reports `null` if the file is missing). */
+export async function loadProvenance(pkgPath) {
+  try {
+    const raw = await readFile(join(pkgPath, '.agentforgerc'), 'utf-8');
+    return JSON.parse(raw.replace(/^/, ''));
+  } catch {
+    return null;
+  }
+}
+
+/** One-line summary suitable for `/forge-list` output, derived from manifest + provenance. */
+export function summarize(pkg, manifest, provenance) {
+  const primary = manifest?.spec?.model_selection?.primary;
+  const primaryId = primary ? `${primary.provider}/${primary.model}` : '?';
+  const evalStamped = manifest?.metadata?.provenance?.eval_passed_at;
+  const evalMark = evalStamped ? '✅ eval' : '⚠️  unevaluated';
+  return `${pkg.name}@${pkg.version}  ${primaryId}  ${evalMark}` + (provenance?.provenance?.eval_run ? `  (run ${provenance.provenance.eval_run})` : '');
+}
+
+/** Doctor: structural checks against an APF directory. Returns `{ ok, problems[] }`. */
+export async function diagnosePackage(pkgPath) {
+  const problems = [];
+  const expectedFiles = ['manifest.yaml', 'README.md', '.agentforgerc',
+    'prompts/system.canonical.md', 'tools/schemas.canonical.json',
+    'governance/cost.policy.yaml', 'governance/compliance.policy.yaml',
+    'governance/quality.policy.yaml', 'governance/fallback-chain.yaml',
+    'evals/golden.jsonl', 'evals/thresholds.yaml'];
+  for (const rel of expectedFiles) {
+    try {
+      await stat(join(pkgPath, rel));
+    } catch {
+      problems.push(`missing: ${rel}`);
+    }
+  }
+  for (const rel of ['governance/cost.policy.yaml', 'governance/compliance.policy.yaml', 'governance/quality.policy.yaml']) {
+    try {
+      const body = await readFile(join(pkgPath, rel), 'utf-8');
+      if (body.includes('{{') && body.includes('}}')) problems.push(`${rel} still carries {{TOKEN}} placeholders`);
+    } catch {
+      /* already reported above */
+    }
+  }
+  return { ok: problems.length === 0, problems };
+}
+
+/** Compose the aggregate monthly budget across every package — for `/forge-budget`. */
+export function aggregateBudgets(manifests) {
+  let target = 0;
+  let hardCap = 0;
+  const perAgent = [];
+  for (const manifest of manifests) {
+    const cost = manifest?.spec?.cost ?? {};
+    const monthlyTarget = Number(cost.monthly_budget_usd ?? 0);
+    const perCallCap = Number(cost.max_usd_per_call ?? 0);
+    const monthlyCap = Math.round(monthlyTarget * 1.5);
+    target += monthlyTarget;
+    hardCap += monthlyCap;
+    perAgent.push({ name: manifest?.metadata?.name, target: monthlyTarget, hardCap: monthlyCap, perCallCap });
+  }
+  return { totals: { monthly_target_usd: target, monthly_hard_cap_usd: hardCap }, perAgent };
+}

package/templates/contextkit/squads/agent-forge/lib/packager.mjs

@@ -0,0 +1,219 @@
+/**
+ * packager — assembles the Agent Package (APF v1) for a routed blueprint. Reads the
+ * APF template tree, writes a stamped copy to the target dir, generates per-provider
+ * prompts + tool adapters, and stamps provenance (blueprint hash, forge version,
+ * timestamp) into the manifest.
+ *
+ * Split:
+ * - `assembleManifest(blueprint, decision)` — pure, returns the in-memory manifest
+ *   object. No I/O, no YAML dep — exercised by the unit tests.
+ * - `packageAgent(blueprint, decision, targetDir)` — full I/O: depends on the optional
+ *   `yaml` dep via `lib/yaml.mjs` (ADR-0013) to serialize the manifest. Required at
+ *   packaging time; not required to import this module.
+ */
+import { copyFile, mkdir, readdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { blueprintHash } from './architect.mjs';
+import { designEvalSet, toJsonl } from './eval-designer.mjs';
+import { attachGovernance } from './governance-officer.mjs';
+import { generatePrompts } from './prompt-gen.mjs';
+import { designRagConfig } from './rag-designer.mjs';
+import { generateAdapters } from './tool-gen.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const APF_TEMPLATE = resolve(HERE, '..', 'templates', 'agent-package');
+const FORGE_VERSION = '0.1.0';
+
+function splitId(fullId) {
+  const [provider, ...rest] = String(fullId).split('/');
+  return { provider, model: rest.join('/') };
+}
+
+/**
+ * Build the manifest object in memory. Pure, deterministic when `opts.now` is fixed.
+ * The YAML serializer is called by `packageAgent`; tests should call this directly
+ * to inspect structure without needing the `yaml` dep.
+ */
+export function assembleManifest(blueprint, decision, opts = {}) {
+  const now = opts.now ?? new Date().toISOString();
+  const today = now.slice(0, 10);
+  const primary = splitId(decision.primary);
+  const fallback = decision.fallback
+    ? { ...splitId(decision.fallback), condition: 'primary_5xx OR primary_timeout' }
+    : null;
+  const cheap = decision.cheap_path ? splitId(decision.cheap_path) : null;
+  const premium = decision.premium_path ? splitId(decision.premium_path) : null;
+  return {
+    apiVersion: 'agentforge.contextdevkit.io/v1',
+    kind: 'Agent',
+    metadata: {
+      name: blueprint.agent_name,
+      version: opts.version ?? '0.1.0',
+      description: blueprint.role_one_line,
+      author: blueprint.author || 'unknown',
+      created: today,
+      provenance: {
+        forged_by: `agent-forge@${opts.forgeVersion ?? FORGE_VERSION}`,
+        blueprint_hash: blueprintHash(blueprint),
+        eval_passed_at: opts.evalResult?.verdict === 'pass' ? (opts.evalPassedAt ?? now) : null,
+      },
+    },
+    spec: {
+      intent: blueprint.intent,
+      sla: blueprint.sla,
+      cost: blueprint.cost,
+      volume: blueprint.volume,
+      privacy: blueprint.privacy,
+      capabilities: blueprint.capabilities,
+      model_selection: {
+        primary: { ...primary, temperature: 0, max_tokens: 4000 },
+        ...(fallback ? { fallback: [fallback] } : {}),
+        ...(cheap ? { cheap_path: cheap } : {}),
+        ...(premium ? { premium_path: premium } : {}),
+        rules_applied: decision.applied_rules ?? [],
+      },
+      evals: { golden: 'evals/golden.jsonl', thresholds: 'evals/thresholds.yaml' },
+      governance: {
+        cost: 'governance/cost.policy.yaml',
+        compliance: 'governance/compliance.policy.yaml',
+        quality: 'governance/quality.policy.yaml',
+        fallback: 'governance/fallback-chain.yaml',
+      },
+      runtime_adapters: opts.runtimeAdapters ?? blueprint.runtime_adapters ?? ['node'],
+    },
+  };
+}
+
+async function copyTree(src, dest) {
+  await mkdir(dest, { recursive: true });
+  for (const entry of await readdir(src, { withFileTypes: true })) {
+    const s = join(src, entry.name);
+    const d = join(dest, entry.name);
+    if (entry.isDirectory()) await copyTree(s, d);
+    else await copyFile(s, d);
+  }
+}
+
+async function writeText(p, body) {
+  await mkdir(dirname(p), { recursive: true });
+  await writeFile(p, body);
+}
+
+/** Replace the README's Model Selection Rationale section body with the router's output. */
+function stampReadme(readme, decision) {
+  const sectionRe = /## Model Selection Rationale[\s\S]*?(?=\n## )/;
+  if (sectionRe.test(readme)) return readme.replace(sectionRe, decision.rationale.trim() + '\n\n');
+  return readme + '\n\n' + decision.rationale + '\n';
+}
+
+/**
+ * Write a complete Agent Package to `targetDir`. Requires the `yaml` dep (ADR-0013)
+ * at runtime; throws a clear, actionable error via `loadYaml` if absent.
+ */
+export async function packageAgent(blueprint, decision, targetDir, opts = {}) {
+  const governance = attachGovernance(blueprint, decision);
+  const evalSet = designEvalSet(blueprint);
+
+  const { stringifyYaml } = await import('./yaml.mjs');
+  await copyTree(APF_TEMPLATE, targetDir);
+
+  const manifest = assembleManifest(blueprint, decision, opts);
+  await writeText(join(targetDir, 'manifest.yaml'), await stringifyYaml(manifest));
+
+  await writeText(join(targetDir, 'evals/golden.jsonl'), toJsonl(evalSet.golden));
+  await writeText(join(targetDir, 'evals/red-team.jsonl'), toJsonl(evalSet.redTeam));
+  await writeText(join(targetDir, 'evals/rubric.yaml'), await stringifyYaml(evalSet.rubric));
+  await writeText(join(targetDir, 'evals/thresholds.yaml'), await stringifyYaml(evalSet.thresholds));
+
+  await writeText(join(targetDir, 'governance/cost.policy.yaml'), await stringifyYaml(governance.cost));
+  await writeText(join(targetDir, 'governance/compliance.policy.yaml'), await stringifyYaml(governance.compliance));
+  await writeText(join(targetDir, 'governance/quality.policy.yaml'), await stringifyYaml(governance.quality));
+  await writeText(join(targetDir, 'governance/fallback-chain.yaml'), await stringifyYaml(governance.fallback));
+
+  let rag = null;
+  if (blueprint?.capabilities?.rag === true) {
+    rag = designRagConfig(blueprint);
+    await writeText(join(targetDir, 'rag/config.yaml'), await stringifyYaml(rag.config));
+    await writeText(join(targetDir, 'rag/ingestion/chunker.config.yaml'), await stringifyYaml(rag.chunker));
+    await writeText(join(targetDir, 'rag/ingestion/sources.yaml'), await stringifyYaml(rag.sources));
+    await writeText(join(targetDir, 'rag/retrieval/query-template.md'), rag.queryTemplate);
+    await writeText(join(targetDir, 'rag/retrieval/rerank.config.yaml'), await stringifyYaml(rag.rerank));
+  }
+
+  const canonicalPrompt = await readFile(join(targetDir, 'prompts/system.canonical.md'), 'utf-8');
+  const prompts = generatePrompts(canonicalPrompt);
+  await writeText(join(targetDir, 'prompts/system.anthropic.md'), prompts.anthropic);
+  await writeText(join(targetDir, 'prompts/system.openai.md'), prompts.openai);
+  await writeText(join(targetDir, 'prompts/system.google.md'), prompts.google);
+  await writeText(join(targetDir, 'prompts/system.deepseek.md'), prompts.deepseek);
+  await writeText(join(targetDir, 'prompts/system.ollama.md'), prompts.ollama);
+
+  const canonicalTools = JSON.parse((await readFile(join(targetDir, 'tools/schemas.canonical.json'), 'utf-8')).replace(/^/, ''));
+  const adapters = generateAdapters(canonicalTools);
+  await writeText(join(targetDir, 'tools/adapters/anthropic.tools.json'), JSON.stringify(adapters.anthropic, null, 2) + '\n');
+  await writeText(join(targetDir, 'tools/adapters/openai.tools.json'), JSON.stringify(adapters.openai, null, 2) + '\n');
+  await writeText(join(targetDir, 'tools/adapters/google.tools.json'), JSON.stringify(adapters.google, null, 2) + '\n');
+  await writeText(join(targetDir, 'tools/adapters/deepseek.tools.json'), JSON.stringify(adapters.deepseek, null, 2) + '\n');
+  await writeText(join(targetDir, 'tools/adapters/ollama.tools.json'), JSON.stringify(adapters.ollama, null, 2) + '\n');
+
+  const readmePath = join(targetDir, 'README.md');
+  await writeText(readmePath, stampReadme(await readFile(readmePath, 'utf-8'), decision));
+
+  await stampRuntimeAdapters(targetDir, blueprint, manifest.spec.runtime_adapters);
+
+  return {
+    targetDir,
+    manifest,
+    files_written: ['manifest.yaml',
+      'prompts/system.anthropic.md', 'prompts/system.openai.md',
+      'prompts/system.google.md', 'prompts/system.deepseek.md', 'prompts/system.ollama.md',
+      'tools/adapters/anthropic.tools.json', 'tools/adapters/openai.tools.json',
+      'tools/adapters/google.tools.json', 'tools/adapters/deepseek.tools.json',
+      'tools/adapters/ollama.tools.json',
+      'evals/golden.jsonl', 'evals/red-team.jsonl', 'evals/rubric.yaml', 'evals/thresholds.yaml',
+      'governance/cost.policy.yaml', 'governance/compliance.policy.yaml',
+      'governance/quality.policy.yaml', 'governance/fallback-chain.yaml',
+      'README.md'],
+    provenance: manifest.metadata.provenance,
+    governance,
+    evalSet,
+    rag,
+  };
+}
+
+/**
+ * Replace `{{AGENT_NAME}}` (and the project version) in the Node + Python adapter
+ * manifests when those runtimes are requested. Pure I/O: no behavioural change to
+ * the adapter logic, just removes the literal placeholders so the package installs
+ * cleanly. Stays best-effort — a missing adapter dir is ignored.
+ */
+async function stampRuntimeAdapters(targetDir, blueprint, runtimes) {
+  const name = blueprint.agent_name;
+  const modulePath = blueprint?.go_module_path || 'example.com';
+  const subs = (text) => String(text)
+    .replaceAll('{{AGENT_NAME}}', name)
+    .replaceAll('{{SEE_LICENSE}}', 'UNLICENSED')
+    .replaceAll('{{MODULE_PATH}}', modulePath)
+    .replaceAll('{{1.22}}', '1.22')
+    .replaceAll('{{3.10}}', '3.10');
+  const safeStamp = async (path) => {
+    try {
+      await writeText(path, subs(await readFile(path, 'utf-8')));
+    } catch {
+      /* adapter dir absent or unreadable — ignore */
+    }
+  };
+  if (runtimes?.includes('node')) {
+    await safeStamp(join(targetDir, 'adapters/node/package.json'));
+    await safeStamp(join(targetDir, 'adapters/node/README.md'));
+  }
+  if (runtimes?.includes('python')) {
+    await safeStamp(join(targetDir, 'adapters/python/pyproject.toml'));
+    await safeStamp(join(targetDir, 'adapters/python/README.md'));
+  }
+  if (runtimes?.includes('go')) {
+    await safeStamp(join(targetDir, 'adapters/go/go.mod'));
+    await safeStamp(join(targetDir, 'adapters/go/README.md'));
+  }
+}

package/templates/contextkit/squads/agent-forge/lib/prompt-gen.mjs

@@ -0,0 +1,122 @@
+/**
+ * prompt-engineer — render the canonical system prompt to per-provider variants.
+ * Fase 1 shipped Anthropic + OpenAI; Fase 2 adds Gemini, DeepSeek, Ollama through
+ * the same section map. Pure + zero-dep — no LLM call at this layer.
+ *
+ * Canonical sections (the single source of truth) live in `prompts/system.canonical.md`:
+ *   `# Role` · `# Context` · `# Rules` · `# Output` · `# Examples`
+ *
+ * - Anthropic: separate `system` param, XML sections, `cache_control: ephemeral` on
+ *   the stable Context block.
+ * - OpenAI: first `system` message, Markdown headings (`# Role` then `## Section`).
+ *   o-series models take no system message — the runtime adapter folds it into the
+ *   first user turn (out of scope for the prompt renderer).
+ * - Google (Gemini): `systemInstruction` body, Markdown + few-shot. safetySettings
+ *   are a REQUEST-level concern, not embedded here.
+ * - DeepSeek: OpenAI-compatible body that prepends an explicit CoT cue to Rules
+ *   ("Think step by step before answering") — reasoner variants return
+ *   `reasoning_content` separately.
+ * - Ollama / vLLM (self-hosted): plain Markdown body; the per-model chat_template
+ *   (Llama 3 / Mistral / Qwen) is applied by the runtime, not here.
+ */
+
+const SECTION_RE = /^#\s+(\w[\w-]*)\s*$/;
+
+/**
+ * Split canonical Markdown into a `{ role, context, rules, output, examples }` map.
+ * Comment blocks at the very top (HTML comments before the first `# Section`) are
+ * dropped — they're authoring notes, not part of the prompt.
+ */
+export function extractSections(canonical) {
+  const lines = String(canonical).split('\n');
+  const sections = {};
+  let current = null;
+  let buf = [];
+  const flush = () => {
+    if (current) sections[current] = (sections[current] ? sections[current] + '\n' : '') + buf.join('\n').trim();
+    buf = [];
+  };
+  for (const line of lines) {
+    const match = SECTION_RE.exec(line);
+    if (match) {
+      flush();
+      current = match[1].toLowerCase();
+    } else if (current) {
+      buf.push(line);
+    }
+  }
+  flush();
+  return sections;
+}
+
+/** Anthropic system-prompt form: XML sections, ephemeral cache on Context. */
+export function renderAnthropic(sections) {
+  const lines = ['<!-- Generated by agent-forge prompt-engineer (Fase 1) from system.canonical.md. Do not hand-edit. -->'];
+  if (sections.role) lines.push(`<role>${sections.role}</role>`);
+  if (sections.context) lines.push('', '<context cache="ephemeral">', sections.context, '</context>');
+  if (sections.rules) lines.push('', '<rules>', sections.rules, '</rules>');
+  if (sections.output) lines.push('', '<output>', sections.output, '</output>');
+  if (sections.examples) lines.push('', '<examples>', sections.examples, '</examples>');
+  return lines.join('\n') + '\n';
+}
+
+/** OpenAI system-message form: Markdown with `# Role` then `## Sections`. */
+export function renderOpenAI(sections) {
+  const lines = ['<!-- Generated by agent-forge prompt-engineer (Fase 1) from system.canonical.md. Do not hand-edit. -->'];
+  if (sections.role) lines.push('# Role', sections.role);
+  if (sections.context) lines.push('', '## Context', sections.context);
+  if (sections.rules) lines.push('', '## Rules', sections.rules);
+  if (sections.output) lines.push('', '## Output', sections.output);
+  if (sections.examples) lines.push('', '## Examples', sections.examples);
+  return lines.join('\n') + '\n';
+}
+
+/** Google (Gemini): Markdown body for `systemInstruction`. */
+export function renderGoogle(sections) {
+  const lines = ['<!-- Generated by agent-forge prompt-engineer (Fase 2) from system.canonical.md. Do not hand-edit. -->'];
+  lines.push('<!-- NOTE: safetySettings are configured on the REQUEST; this is the systemInstruction body only. -->');
+  if (sections.role) lines.push('# Role', sections.role);
+  if (sections.context) lines.push('', '## Context', sections.context);
+  if (sections.rules) lines.push('', '## Rules', sections.rules);
+  if (sections.output) lines.push('', '## Output', sections.output);
+  if (sections.examples) lines.push('', '## Examples (few-shot)', sections.examples);
+  return lines.join('\n') + '\n';
+}
+
+/** DeepSeek: OpenAI-compatible body that prepends an explicit CoT cue to Rules. */
+export function renderDeepSeek(sections) {
+  const lines = ['<!-- Generated by agent-forge prompt-engineer (Fase 2) from system.canonical.md. Do not hand-edit. -->'];
+  if (sections.role) lines.push('# Role', sections.role);
+  if (sections.context) lines.push('', '## Context', sections.context);
+  const cot = '- Think step by step before answering.';
+  const rulesBody = sections.rules ? cot + '\n' + sections.rules : cot;
+  lines.push('', '## Rules', rulesBody);
+  if (sections.output) lines.push('', '## Output', sections.output);
+  if (sections.examples) lines.push('', '## Examples', sections.examples);
+  return lines.join('\n') + '\n';
+}
+
+/** Self-hosted (Ollama/vLLM): plain Markdown; chat_template applied by the runtime. */
+export function renderOllama(sections) {
+  const lines = ['<!-- Generated by agent-forge prompt-engineer (Fase 2) from system.canonical.md. Do not hand-edit. -->'];
+  lines.push('<!-- NOTE: the per-model chat_template (Llama 3 / Mistral / Qwen) is applied by the runtime, not here. -->');
+  if (sections.role) lines.push('# Role', sections.role);
+  if (sections.context) lines.push('', '## Context', sections.context);
+  if (sections.rules) lines.push('', '## Rules', sections.rules);
+  if (sections.output) lines.push('', '## Output', sections.output);
+  if (sections.examples) lines.push('', '## Examples', sections.examples);
+  return lines.join('\n') + '\n';
+}
+
+/** One-stop renderer; returns `{ sections, anthropic, openai, google, deepseek, ollama }`. */
+export function generatePrompts(canonical) {
+  const sections = extractSections(canonical);
+  return {
+    sections,
+    anthropic: renderAnthropic(sections),
+    openai: renderOpenAI(sections),
+    google: renderGoogle(sections),
+    deepseek: renderDeepSeek(sections),
+    ollama: renderOllama(sections),
+  };
+}

package/templates/contextkit/squads/agent-forge/lib/rag-designer.mjs

@@ -0,0 +1,102 @@
+/**
+ * rag-designer — produces the `rag/` config bundle (chunker, embedding, index,
+ * retrieval, optional reranker) when the blueprint declares `capabilities.rag`.
+ * Pure + zero-dep (rule 1). Deterministic heuristics shaped by the blueprint:
+ *
+ *  - **Embedding model.** Multilingual (`multilingual-e5`) by default; switched to
+ *    English-only (`text-embedding-3-large`) when `intent.domain` ends in `-en`.
+ *  - **Index backend.** `pgvector` when `privacy.data_residency: on-prem` /
+ *    `allow_cloud_providers: false`; `qdrant` otherwise — both are commodity, dev
+ *    swaps via `manifest.yaml` if a different backend is already in place.
+ *  - **Chunking.** Recursive 512/64 by default; tightened to 256/32 for `extraction`
+ *    where boundary precision matters more than context width.
+ *  - **Hybrid search + reranker** on by default — the cost is small at retrieval-time
+ *    and the precision lift is large; can be flipped off in the manifest later.
+ *  - **`top_k` and `min_score`.** Derived from `intent.complexity` — higher complexity
+ *    keeps more candidates and lowers the score floor.
+ *
+ * The packager calls `designRagConfig(blueprint)` only when `capabilities.rag === true`;
+ * it serializes the four returned objects into the RAG template files.
+ */
+
+const MULTILINGUAL = 'multilingual-e5';
+const ENGLISH = 'text-embedding-3-large';
+
+function pickEmbedding(blueprint) {
+  const domain = String(blueprint?.intent?.domain || '').toLowerCase();
+  return domain.endsWith('-en') ? { model: ENGLISH, dimensions: 3072 } : { model: MULTILINGUAL, dimensions: 1024 };
+}
+
+function pickIndexBackend(blueprint) {
+  const allowsCloud = blueprint?.privacy?.allow_cloud_providers !== false;
+  const residency = blueprint?.privacy?.data_residency;
+  if (!allowsCloud || residency === 'on-prem') return 'pgvector';
+  return 'qdrant';
+}
+
+function pickChunking(blueprint) {
+  const category = blueprint?.intent?.category;
+  if (category === 'extraction') return { strategy: 'recursive', chunk_size_tokens: 256, chunk_overlap_tokens: 32, respect_boundaries: ['heading', 'paragraph'], keep_metadata: ['source', 'section', 'page'] };
+  return { strategy: 'recursive', chunk_size_tokens: 512, chunk_overlap_tokens: 64, respect_boundaries: ['heading', 'paragraph'], keep_metadata: ['source', 'section', 'page'] };
+}
+
+function pickRetrieval(blueprint) {
+  const complexity = blueprint?.intent?.complexity || 'medium';
+  const topK = complexity === 'high' ? 12 : complexity === 'low' ? 6 : 8;
+  const minScore = complexity === 'high' ? 0.25 : 0.30;
+  return { top_k: topK, min_score: minScore, hybrid_search: true, rerank: true };
+}
+
+function buildSources(blueprint) {
+  return {
+    sources: [{
+      id: `${blueprint?.agent_name || 'agent'}-knowledge`,
+      type: 'filesystem',
+      location: './knowledge',
+      include: ['**/*.{md,pdf,txt}'],
+      refresh: 'manual',
+    }],
+  };
+}
+
+function buildRerank() {
+  return { enabled: true, model: 'bge-reranker-v2-m3', top_n_after_rerank: 4, min_score: 0.50 };
+}
+
+function buildQueryTemplate() {
+  return [
+    '<!-- How the user query is turned into a retrieval query + how context is injected. -->',
+    '',
+    '## Retrieval query',
+    'Strip PII, expand acronyms, and keep the original wording. The architect can override',
+    'this by hand-editing the file — the runtime adapter reads it verbatim.',
+    '',
+    '## Context injection',
+    'Inject the top-k chunks as:',
+    '',
+    '```',
+    '<context>',
+    '{{retrieved_chunks}}',
+    '</context>',
+    '```',
+    '',
+    'Instruct the model to answer ONLY from `<context>` and to say when the answer is not',
+    'present (faithfulness > fluency).',
+    '',
+  ].join('\n');
+}
+
+/** One-stop designer for the RAG bundle. Returns the four artefacts the packager writes. */
+export function designRagConfig(blueprint) {
+  return {
+    config: {
+      embedding: pickEmbedding(blueprint),
+      index: { backend: pickIndexBackend(blueprint), metric: 'cosine' },
+      retrieval: pickRetrieval(blueprint),
+    },
+    chunker: pickChunking(blueprint),
+    sources: buildSources(blueprint),
+    rerank: buildRerank(),
+    queryTemplate: buildQueryTemplate(),
+  };
+}