@meshxdata/fops 0.0.1 → 0.0.3

package/src/agent/llm.js

@@ -1,7 +1,7 @@
 import chalk from "chalk";
 import { execa, execaSync } from "execa";
 import { resolveAnthropicApiKey, resolveOpenAiApiKey, readClaudeCodeKeychain } from "../auth/index.js";
-import { renderSpinner } from "../ui/index.js";
+import { renderThinking } from "../ui/index.js";
 
 // Check if Claude Code CLI is available
 export function hasClaudeCode() {
@@ -86,22 +86,61 @@ export async function streamAssistantReply(root, messages, systemContent, opts)
   const model = opts.model || (anthropicKey ? "claude-sonnet-4-20250514" : "gpt-4o-mini");
 
   let fullText = "";
-  const spinner = renderSpinner();
+  const display = renderThinking();
 
   try {
     if (useClaudeCode) {
-      // Build full conversation prompt so context is preserved between turns
       const prompt = buildConversationPrompt(messages);
-      fullText = await streamViaClaudeCode(prompt, systemContent);
+      fullText = await streamViaClaudeCode(prompt, systemContent, (chunk) => {
+        display.setStatus("Responding");
+        display.appendContent(chunk);
+      });
     } else if (anthropicKey) {
       const { default: Anthropic } = await import("@anthropic-ai/sdk");
       const client = new Anthropic({ apiKey: anthropicKey });
-      const stream = await client.messages.create({
-        model, max_tokens: 2048, system: systemContent, messages, stream: true,
-      });
+      const isClaudeModel = model.includes("claude");
+
+      const createParams = {
+        model, max_tokens: isClaudeModel ? 16000 : 2048,
+        system: systemContent, messages, stream: true,
+      };
+
+      // Enable extended thinking for Claude models
+      if (isClaudeModel) {
+        createParams.thinking = { type: "enabled", budget_tokens: 10000 };
+      }
+
+      let stream;
+      try {
+        stream = await client.messages.create(createParams);
+      } catch (err) {
+        // Fall back to regular streaming if extended thinking is unsupported
+        if (isClaudeModel && (err?.status === 400 || err?.status === 422)) {
+          delete createParams.thinking;
+          createParams.max_tokens = 2048;
+          stream = await client.messages.create(createParams);
+        } else {
+          throw err;
+        }
+      }
+
       for await (const event of stream) {
-        if (event.type === "content_block_delta" && event.delta?.type === "text_delta" && event.delta.text) {
-          fullText += event.delta.text;
+        if (event.type === "content_block_start") {
+          if (event.content_block?.type === "thinking") {
+            display.setStatus("Reasoning");
+          } else if (event.content_block?.type === "text") {
+            display.setThinking(""); // clear thinking preview
+            display.setStatus("Responding");
+          }
+        }
+        if (event.type === "content_block_delta") {
+          if (event.delta?.type === "thinking_delta" && event.delta.thinking) {
+            display.appendThinking(event.delta.thinking);
+          }
+          if (event.delta?.type === "text_delta" && event.delta.text) {
+            fullText += event.delta.text;
+            display.setContent(fullText);
+          }
         }
       }
     } else if (openaiKey) {
@@ -114,13 +153,17 @@ export async function streamAssistantReply(root, messages, systemContent, opts)
       });
       for await (const chunk of stream) {
         const delta = chunk.choices?.[0]?.delta?.content;
-        if (delta) fullText += delta;
+        if (delta) {
+          fullText += delta;
+          display.setStatus("Responding");
+          display.setContent(fullText);
+        }
       }
     } else {
       throw new Error("No API key (use ANTHROPIC_API_KEY, OPENAI_API_KEY, or ~/.claude auth)");
     }
   } finally {
-    spinner.stop();
+    display.stop();
   }
 
   return fullText;

package/src/auth/coda.js

@@ -0,0 +1,128 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import chalk from "chalk";
+import inquirer from "inquirer";
+import { openBrowser } from "./login.js";
+
+const CODA_ACCOUNT_URL = "https://coda.io/account";
+const FOPS_CONFIG_PATH = path.join(os.homedir(), ".fops.json");
+
+function readFopsConfig() {
+  try {
+    if (fs.existsSync(FOPS_CONFIG_PATH)) {
+      return JSON.parse(fs.readFileSync(FOPS_CONFIG_PATH, "utf8"));
+    }
+  } catch {}
+  return {};
+}
+
+function saveFopsConfig(config) {
+  fs.writeFileSync(FOPS_CONFIG_PATH, JSON.stringify(config, null, 2) + "\n", { mode: 0o600 });
+}
+
+export function resolveCodaApiToken() {
+  const envToken = process.env.CODA_API_TOKEN?.trim();
+  if (envToken) return envToken;
+  try {
+    const config = readFopsConfig();
+    const token = config.coda?.apiToken?.trim();
+    if (token) return token;
+  } catch {}
+  return null;
+}
+
+function saveCodaToken(token) {
+  const config = readFopsConfig();
+  config.coda = { ...config.coda, apiToken: token.trim() };
+  saveFopsConfig(config);
+}
+
+async function validateCodaToken(token) {
+  try {
+    const res = await fetch("https://coda.io/apis/v1/whoami", {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    if (res.ok) {
+      const data = await res.json();
+      return { valid: true, name: data.name, loginId: data.loginId };
+    }
+    if (res.status === 401 || res.status === 403) {
+      return { valid: false, error: "Invalid or expired API token." };
+    }
+    return { valid: false, error: `Coda API returned ${res.status}.` };
+  } catch (err) {
+    return { valid: false, error: `Could not reach Coda API: ${err.message}` };
+  }
+}
+
+export async function runCodaLogin() {
+  const existing = resolveCodaApiToken();
+  if (existing) {
+    const masked = existing.slice(0, 8) + "..." + existing.slice(-4);
+    const { overwrite } = await inquirer.prompt([{
+      type: "confirm",
+      name: "overwrite",
+      message: `Already have a Coda API token (${masked}). Replace it?`,
+      default: false,
+    }]);
+    if (!overwrite) {
+      console.log(chalk.gray("Keeping existing Coda token."));
+      return true;
+    }
+  }
+
+  console.log("");
+  console.log(chalk.bold.cyan("  Coda API Token Setup"));
+  console.log("");
+  console.log(chalk.white("  To connect Foundation to Coda, you need an API token."));
+  console.log(chalk.white("  Here's how to get one:\n"));
+  console.log(chalk.gray("  1. Go to ") + chalk.cyan(CODA_ACCOUNT_URL));
+  console.log(chalk.gray("  2. Scroll to ") + chalk.white("\"API Settings\""));
+  console.log(chalk.gray("  3. Click ") + chalk.white("\"Generate API token\""));
+  console.log(chalk.gray("  4. Give it a name (e.g. \"Foundation CLI\")"));
+  console.log(chalk.gray("  5. Copy the token and paste it below"));
+  console.log("");
+
+  const { openIt } = await inquirer.prompt([{
+    type: "confirm",
+    name: "openIt",
+    message: "Open Coda account page in your browser?",
+    default: true,
+  }]);
+
+  if (openIt) {
+    const opened = openBrowser(CODA_ACCOUNT_URL);
+    if (!opened) {
+      console.log(chalk.yellow("\n  Could not open browser. Visit: " + CODA_ACCOUNT_URL + "\n"));
+    } else {
+      console.log("");
+    }
+  }
+
+  const { token } = await inquirer.prompt([{
+    type: "password",
+    name: "token",
+    message: "Paste your Coda API token:",
+    mask: "*",
+    validate: (v) => {
+      if (!v?.trim()) return "API token is required.";
+      return true;
+    },
+  }]);
+
+  console.log(chalk.gray("\n  Validating token..."));
+  const result = await validateCodaToken(token.trim());
+
+  if (!result.valid) {
+    console.log(chalk.red(`\n  ${result.error}`));
+    console.log(chalk.gray("  Check the token and try again with: fops login coda\n"));
+    return false;
+  }
+
+  saveCodaToken(token);
+  console.log(chalk.green(`\n  Coda login successful!`));
+  console.log(chalk.gray(`  Logged in as: ${result.name || result.loginId}`));
+  console.log(chalk.gray("  Token saved to ~/.fops.json\n"));
+  return true;
+}

package/src/auth/index.js

@@ -2,3 +2,4 @@ export { resolveAnthropicApiKey, resolveOpenAiApiKey, readJsonKey } from "./reso
 export { readClaudeCodeKeychain } from "./keychain.js";
 export { authHelp, offerClaudeLogin, runLogin } from "./login.js";
 export { runOAuthLogin } from "./oauth.js";
+export { runCodaLogin, resolveCodaApiToken } from "./coda.js";

package/src/commands/index.js

@@ -10,7 +10,7 @@ import { runSetup, runInitWizard } from "../setup/index.js";
 import { ensureEcrAuth } from "../setup/aws.js";
 import { runAgentSingleTurn, runAgentInteractive } from "../agent/index.js";
 import { runDoctor } from "../doctor.js";
-import { runLogin } from "../auth/index.js";
+import { runLogin, runCodaLogin } from "../auth/index.js";
 import { runHook, loadSkills } from "../plugins/index.js";
 
 export function registerCommands(program, registry) {
@@ -18,10 +18,19 @@ export function registerCommands(program, registry) {
 
   program
     .command("login")
-    .description("Authenticate with Claude (OAuth login via browser)")
+    .description("Authenticate with services (Claude, Coda)")
+    .argument("[service]", "Service to login to: claude (default) or coda")
     .option("--no-browser", "Paste API key in terminal instead of OAuth")
-    .action(async (opts) => {
-      await runLogin({ browser: opts.browser });
+    .action(async (service, opts) => {
+      const target = (service || "claude").toLowerCase();
+      if (target === "coda") {
+        await runCodaLogin();
+      } else if (target === "claude") {
+        await runLogin({ browser: opts.browser });
+      } else {
+        console.error(chalk.red(`Unknown service "${target}". Use: claude, coda`));
+        process.exit(1);
+      }
     });
 
   program
@@ -82,9 +91,9 @@ export function registerCommands(program, registry) {
     .action(async (opts) => {
       const root = requireRoot(program);
       if (opts.message) {
-        await runAgentSingleTurn(root, opts.message, { runSuggestions: opts.run !== false, model: opts.model });
+        await runAgentSingleTurn(root, opts.message, { runSuggestions: opts.run !== false, model: opts.model, registry });
       } else {
-        await runAgentInteractive(root);
+        await runAgentInteractive(root, { registry });
       }
     });
 
@@ -97,9 +106,14 @@ export function registerCommands(program, registry) {
       const root = requireRoot(program);
       await ensureEcrAuth(root);
       await runHook(registry, "before:up", { root });
-      await make(root, "start");
+      const result = await make(root, "start");
       await runHook(registry, "after:up", { root });
-      if (opts.chat !== false) await runAgentInteractive(root);
+      if (result.exitCode !== 0) {
+        console.error(chalk.red(`\n  Some services failed to start (exit code ${result.exitCode}).`));
+        console.error(chalk.gray("  Run `fops doctor` to diagnose or `fops logs` to inspect.\n"));
+        process.exit(result.exitCode);
+      }
+      if (opts.chat !== false) await runAgentInteractive(root, { registry });
     });
 
   program
@@ -107,7 +121,7 @@ export function registerCommands(program, registry) {
     .description("Interactive AI assistant (same as foundation agent with no -m)")
     .action(async () => {
       const root = requireRoot(program);
-      await runAgentInteractive(root);
+      await runAgentInteractive(root, { registry });
     });
 
   program

package/src/doctor.js

@@ -116,6 +116,29 @@ export async function runDoctor(opts = {}, registry = null) {
   // ── Prerequisites ──────────────────────────────────
   header("Prerequisites");
 
+  // winget (Windows only — needed to install other tools)
+  let hasWinget = false;
+  if (process.platform === "win32") {
+    const wingetVer = await cmdVersion("winget");
+    if (wingetVer) {
+      ok("winget available", wingetVer);
+      hasWinget = true;
+    } else {
+      fail("winget not found", "needed to install Docker", async () => {
+        console.log(chalk.cyan("  ▶ Installing winget via Add-AppxPackage…"));
+        await execa("powershell", ["-Command", [
+          "$url = (Invoke-RestMethod 'https://api.github.com/repos/microsoft/winget-cli/releases/latest').assets",
+          "| Where-Object { $_.name -match '.msixbundle$' } | Select-Object -First 1 -ExpandProperty browser_download_url;",
+          "$tmp = Join-Path $env:TEMP 'winget.msixbundle';",
+          "Invoke-WebRequest -Uri $url -OutFile $tmp;",
+          "Add-AppxPackage -Path $tmp;",
+          "Remove-Item $tmp",
+        ].join(" ")], { stdio: "inherit", timeout: 120_000 });
+        hasWinget = true;
+      });
+    }
+  }
+
   // Docker
   const dockerVer = await cmdVersion("docker");
   if (dockerVer) {
@@ -124,12 +147,91 @@ export async function runDoctor(opts = {}, registry = null) {
       await execa("docker", ["info"], { timeout: 5000 });
       ok("Docker running", dockerVer);
     } catch {
-      fail("Docker daemon not running", "start Docker Desktop or dockerd");
+      fail("Docker daemon not running", "start Docker Desktop or dockerd", async () => {
+        if (process.platform === "darwin") {
+          console.log(chalk.cyan("  ▶ open -a Docker"));
+          await execa("open", ["-a", "Docker"], { timeout: 10000 });
+        } else if (process.platform === "win32") {
+          console.log(chalk.cyan('  ▶ start "" "Docker Desktop"'));
+          await execa("cmd", ["/c", "start", "", "Docker Desktop"], { timeout: 10000 });
+        } else {
+          console.log(chalk.cyan("  ▶ sudo systemctl start docker"));
+          await execa("sudo", ["systemctl", "start", "docker"], { stdio: "inherit", timeout: 30000 });
+          return;
+        }
+        // macOS / Windows: wait for daemon to become ready
+        console.log(chalk.gray("  Waiting for Docker daemon to start…"));
+        for (let i = 0; i < 30; i++) {
+          await new Promise((r) => setTimeout(r, 2000));
+          try {
+            await execa("docker", ["info"], { timeout: 5000 });
+            return;
+          } catch {}
+        }
+        throw new Error("Docker daemon did not start within 60 s");
+      });
     }
   } else {
-    fail("Docker not found", "install from docker.com");
+    fail("Docker not found", "install from docker.com", async () => {
+      if (process.platform === "darwin") {
+        let hasBrew = false;
+        try { await execa("brew", ["--version"]); hasBrew = true; } catch {}
+        if (!hasBrew) {
+          console.log(chalk.cyan("  ▶ Installing Homebrew…"));
+          await execa("bash", ["-c", 'NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"'], {
+            stdio: "inherit", timeout: 300_000,
+          });
+          // Add brew to PATH for Apple Silicon
+          const brewPaths = ["/opt/homebrew/bin/brew", "/usr/local/bin/brew"];
+          for (const bp of brewPaths) {
+            if (fs.existsSync(bp)) {
+              const { stdout } = await execa(bp, ["shellenv"], { timeout: 5000 });
+              for (const line of stdout.split("\n")) {
+                const m = line.match(/export\s+PATH="([^"]+)"/);
+                if (m) process.env.PATH = m[1] + ":" + process.env.PATH;
+              }
+              break;
+            }
+          }
+          hasBrew = true;
+        }
+        console.log(chalk.cyan("  ▶ brew install --cask docker"));
+        await execa("brew", ["install", "--cask", "docker"], { stdio: "inherit", timeout: 300_000 });
+        console.log(chalk.cyan("  ▶ open -a Docker"));
+        await execa("open", ["-a", "Docker"], { timeout: 10000 });
+      } else if (process.platform === "win32") {
+        if (!hasWinget) throw new Error("winget is required to install Docker — fix winget first");
+        console.log(chalk.cyan("  ▶ winget install Docker.DockerDesktop"));
+        await execa("winget", ["install", "Docker.DockerDesktop", "--accept-source-agreements", "--accept-package-agreements"], {
+          stdio: "inherit", timeout: 300_000,
+        });
+        console.log(chalk.cyan('  ▶ start "" "Docker Desktop"'));
+        await execa("cmd", ["/c", "start", "", "Docker Desktop"], { timeout: 10000 });
+      } else {
+        console.log(chalk.cyan("  ▶ curl -fsSL https://get.docker.com | sudo sh"));
+        await execa("sh", ["-c", "curl -fsSL https://get.docker.com | sudo sh"], {
+          stdio: "inherit", timeout: 300_000,
+        });
+        return;
+      }
+      // macOS / Windows: wait for daemon after install
+      console.log(chalk.gray("  Waiting for Docker daemon to start…"));
+      for (let i = 0; i < 30; i++) {
+        await new Promise((r) => setTimeout(r, 2000));
+        try {
+          await execa("docker", ["info"], { timeout: 5000 });
+          return;
+        } catch {}
+      }
+      throw new Error("Docker daemon did not start within 60 s");
+    });
   }
 
+  // Docker Compose (bundled with Docker Desktop, but verify)
+  const composeVer = await cmdVersion("docker", ["compose", "version"]);
+  if (composeVer) ok("Docker Compose", composeVer);
+  else fail("Docker Compose not found", "included with Docker Desktop — restart Docker or install the compose plugin");
+
   // Git
   const gitVer = await cmdVersion("git");
   if (gitVer) ok("Git available", gitVer);
@@ -141,6 +243,11 @@ export async function runDoctor(opts = {}, registry = null) {
   if (nodeMajor >= 18) ok(`Node.js v${nodeVer}`, ">=18 required");
   else fail(`Node.js v${nodeVer}`, "upgrade to >=18");
 
+  // Claude CLI (bundled as a dependency)
+  const claudeVer = await cmdVersion("claude");
+  if (claudeVer) ok("Claude CLI", claudeVer);
+  else fail("Claude CLI not found", "run: npm install (included as a dependency)");
+
   // AWS CLI (optional)
   const awsVer = await cmdVersion("aws");
   if (awsVer) ok("AWS CLI", awsVer);
@@ -316,21 +423,42 @@ export async function runDoctor(opts = {}, registry = null) {
 
     // Host disk available
     try {
-      const { stdout: dfHost } = await execa("df", ["-h", "/"], {
-        timeout: 5000, reject: false,
-      });
-      if (dfHost) {
-        const lines = dfHost.trim().split("\n");
-        if (lines.length >= 2) {
-          const cols = lines[lines.length - 1].split(/\s+/);
-          const size = cols[1];
-          const avail = cols[3];
-          const pct = parseInt(cols[4], 10);
-          if (pct >= 90) fail(`Host disk: ${avail} free of ${size}`, "critically low — Docker needs room");
-          else if (pct >= 80) warn(`Host disk: ${avail} free of ${size}`, "getting low");
-          else ok(`Host disk: ${avail} free of ${size}`);
+      let size, avail, pct;
+      if (process.platform === "win32") {
+        const { stdout: wmicOut } = await execa("wmic", ["logicaldisk", "where", "DeviceID='C:'", "get", "Size,FreeSpace", "/format:csv"], {
+          timeout: 5000, reject: false,
+        });
+        if (wmicOut) {
+          const parts = wmicOut.trim().split("\n").pop()?.split(",");
+          if (parts?.length >= 3) {
+            const free = parseInt(parts[1], 10);
+            const total = parseInt(parts[2], 10);
+            if (total > 0) {
+              size = `${(total / (1024 ** 3)).toFixed(0)} GB`;
+              avail = `${(free / (1024 ** 3)).toFixed(0)} GB`;
+              pct = Math.round(((total - free) / total) * 100);
+            }
+          }
+        }
+      } else {
+        const { stdout: dfHost } = await execa("df", ["-h", "/"], {
+          timeout: 5000, reject: false,
+        });
+        if (dfHost) {
+          const lines = dfHost.trim().split("\n");
+          if (lines.length >= 2) {
+            const cols = lines[lines.length - 1].split(/\s+/);
+            size = cols[1];
+            avail = cols[3];
+            pct = parseInt(cols[4], 10);
+          }
         }
       }
+      if (size && avail && pct != null) {
+        if (pct >= 90) fail(`Host disk: ${avail} free of ${size}`, "critically low — Docker needs room");
+        else if (pct >= 80) warn(`Host disk: ${avail} free of ${size}`, "getting low");
+        else ok(`Host disk: ${avail} free of ${size}`);
+      }
     } catch {}
 
     // Port conflicts

package/src/plugins/api.js

@@ -33,5 +33,14 @@ export function createPluginApi(pluginId, registry) {
     registerHook(event, handler, priority = 0) {
       registry.hooks.push({ pluginId, event, handler, priority });
     },
+
+    registerKnowledgeSource(source) {
+      registry.knowledgeSources.push({
+        pluginId,
+        name: source.name,
+        description: source.description || "",
+        search: source.search,
+      });
+    },
   };
 }

package/src/plugins/index.js

@@ -1,3 +1,4 @@
 export { loadPlugins } from "./loader.js";
 export { runHook } from "./hooks.js";
 export { loadSkills } from "./skills.js";
+export { searchKnowledge } from "./knowledge.js";

package/src/plugins/knowledge.js

@@ -0,0 +1,124 @@
+/**
+ * RAG knowledge orchestrator.
+ * Fans out search queries to all registered knowledge sources,
+ * merges results, enforces token budgets, and caches.
+ */
+
+const MAX_TOTAL_BYTES = 16_384;   // ~4000 tokens
+const MAX_PER_SOURCE_BYTES = 8192;
+const MAX_PER_RESULT_BYTES = 4096;
+const SOURCE_TIMEOUT_MS = 5000;
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const CACHE_MAX_ENTRIES = 50;
+
+/** Simple LRU cache keyed by query string. */
+const cache = new Map();
+
+function cacheGet(key) {
+  const entry = cache.get(key);
+  if (!entry) return null;
+  if (Date.now() - entry.ts > CACHE_TTL_MS) {
+    cache.delete(key);
+    return null;
+  }
+  // Move to end (most-recently used)
+  cache.delete(key);
+  cache.set(key, entry);
+  return entry.value;
+}
+
+function cacheSet(key, value) {
+  // Evict oldest if over capacity
+  if (cache.size >= CACHE_MAX_ENTRIES) {
+    const oldest = cache.keys().next().value;
+    cache.delete(oldest);
+  }
+  cache.set(key, { value, ts: Date.now() });
+}
+
+function truncate(str, maxBytes) {
+  if (str.length <= maxBytes) return str;
+  return str.slice(0, maxBytes - 3) + "...";
+}
+
+/**
+ * Search all registered knowledge sources and return formatted context.
+ * @param {object} registry — plugin registry
+ * @param {string} query — user's message / search query
+ * @returns {string|null} formatted knowledge block or null if no results
+ */
+export async function searchKnowledge(registry, query) {
+  const sources = registry?.knowledgeSources;
+  if (!sources?.length || !query?.trim()) return null;
+
+  const normalizedQuery = query.trim().toLowerCase();
+  const cached = cacheGet(normalizedQuery);
+  if (cached !== null) return cached;
+
+  // Fan out to all sources in parallel with individual timeouts
+  const sourceResults = await Promise.all(
+    sources.map(async (source) => {
+      try {
+        const results = await Promise.race([
+          source.search(query),
+          new Promise((_, reject) =>
+            setTimeout(() => reject(new Error("timeout")), SOURCE_TIMEOUT_MS),
+          ),
+        ]);
+        if (!Array.isArray(results)) return [];
+        return results.map((r) => ({ ...r, _source: source.name }));
+      } catch {
+        // Skip failing sources silently
+        return [];
+      }
+    }),
+  );
+
+  // Flatten and sort by score (descending), then by source order
+  const allResults = sourceResults.flat();
+  if (!allResults.length) {
+    cacheSet(normalizedQuery, null);
+    return null;
+  }
+
+  allResults.sort((a, b) => (b.score ?? 0) - (a.score ?? 0));
+
+  // Enforce per-source budget
+  const sourceBytes = {};
+  const budgeted = allResults.filter((r) => {
+    const src = r._source;
+    const used = sourceBytes[src] || 0;
+    const content = truncate(r.content || "", MAX_PER_RESULT_BYTES);
+    const size = content.length;
+    if (used + size > MAX_PER_SOURCE_BYTES) return false;
+    sourceBytes[src] = used + size;
+    r._truncatedContent = content;
+    return true;
+  });
+
+  // Enforce total budget and format
+  let totalBytes = 0;
+  const sections = [];
+
+  for (const r of budgeted) {
+    const title = r.title || "Untitled";
+    const source = r._source || "unknown";
+    const url = r.url ? ` (${r.url})` : "";
+    const header = `### [${source}] ${title}${url}`;
+    const content = r._truncatedContent || "";
+    const section = `${header}\n${content}`;
+
+    if (totalBytes + section.length > MAX_TOTAL_BYTES) break;
+    totalBytes += section.length;
+    sections.push(section);
+  }
+
+  if (!sections.length) {
+    cacheSet(normalizedQuery, null);
+    return null;
+  }
+
+  const result = "## Knowledge Base\n\n" + sections.join("\n\n");
+  cacheSet(normalizedQuery, result);
+  return result;
+}

package/src/plugins/registry.js

@@ -10,5 +10,6 @@ export function createRegistry() {
     doctorChecks: [],  // { pluginId, name, fn }
     hooks: [],         // { pluginId, event, handler, priority }
     skills: [],        // { pluginId, name, description, content }
+    knowledgeSources: [], // { pluginId, name, description, search }
   };
 }