little-coder 1.0.0

package/.pi/extensions/evidence/index.ts

@@ -0,0 +1,119 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { randomBytes } from "node:crypto";
+
+// Port of local/tools/evidence.py. Per-session in-memory store of evidence
+// entries. GAIA requires cite-before-answer, and these entries survive
+// compaction (Phase 10's evidence-compact extension preserves them).
+
+const SNIPPET_CAP = 1024;
+
+interface EvidenceEntry {
+  id: string;
+  source: string;
+  note: string;
+  snippet: string;
+}
+
+// Map<sessionId, entries[]>
+const stores = new Map<string, EvidenceEntry[]>();
+
+function sessionKey(): string {
+  return process.env.LITTLE_CODER_SESSION_ID || "default";
+}
+
+function bucket(): EvidenceEntry[] {
+  const key = sessionKey();
+  let b = stores.get(key);
+  if (!b) {
+    b = [];
+    stores.set(key, b);
+  }
+  return b;
+}
+
+// Exported so tests and the evidence-compact extension can reach in.
+export function resetSessionStore(sessionId?: string): void {
+  stores.delete(sessionId ?? sessionKey());
+}
+
+export function getSessionStore(sessionId?: string): EvidenceEntry[] {
+  return stores.get(sessionId ?? sessionKey()) ?? [];
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_shutdown", async () => {
+    resetSessionStore();
+  });
+
+  pi.registerTool({
+    name: "EvidenceAdd",
+    label: "EvidenceAdd",
+    description:
+      "Save a short evidence snippet with its source and a one-line note. " +
+      "Use for any fact you will cite in your final answer. Snippet is capped at 1KB.",
+    parameters: Type.Object({
+      source: Type.String({ description: "URL or identifier of origin" }),
+      note: Type.String({ description: "One-line summary for later recall" }),
+      snippet: Type.String({ description: "The exact citable span (<=1KB)" }),
+    }),
+    async execute(_id, { source, note, snippet }) {
+      const src = (source ?? "").trim();
+      const n = (note ?? "").trim();
+      let sn = snippet ?? "";
+      if (!src) {
+        return { content: [{ type: "text", text: "Error: source is required (URL or identifier)" }], details: {}, isError: true };
+      }
+      if (!n) {
+        return { content: [{ type: "text", text: "Error: note is required (1-line summary of the snippet)" }], details: {}, isError: true };
+      }
+      if (!sn) {
+        return { content: [{ type: "text", text: "Error: snippet is required" }], details: {}, isError: true };
+      }
+      if (sn.length > SNIPPET_CAP) {
+        sn = sn.slice(0, SNIPPET_CAP) + `\n[... snippet truncated, kept ${SNIPPET_CAP} chars ...]`;
+      }
+      const id = "e" + randomBytes(3).toString("hex");
+      bucket().push({ id, source: src, note: n, snippet: sn });
+      return { content: [{ type: "text", text: `stored ${id}: ${n}` }], details: {} };
+    },
+  });
+
+  pi.registerTool({
+    name: "EvidenceGet",
+    label: "EvidenceGet",
+    description: "Retrieve a previously-saved evidence entry by its id.",
+    parameters: Type.Object({
+      id: Type.String({ description: "Evidence id from EvidenceAdd/List" }),
+    }),
+    async execute(_id, { id }) {
+      const eid = (id ?? "").trim();
+      if (!eid) {
+        return { content: [{ type: "text", text: "Error: id is required" }], details: {}, isError: true };
+      }
+      const e = bucket().find((x) => x.id === eid);
+      if (!e) {
+        return { content: [{ type: "text", text: `Error: evidence id '${eid}' not found` }], details: {}, isError: true };
+      }
+      return {
+        content: [{ type: "text", text: `[${e.id}] source: ${e.source}\nnote: ${e.note}\nsnippet:\n${e.snippet}` }],
+        details: {},
+      };
+    },
+  });
+
+  pi.registerTool({
+    name: "EvidenceList",
+    label: "EvidenceList",
+    description: "List all evidence entries in this session: id, source, one-line note.",
+    parameters: Type.Object({}),
+    async execute() {
+      const b = bucket();
+      if (b.length === 0) {
+        return { content: [{ type: "text", text: "(no evidence stored yet)" }], details: {} };
+      }
+      const lines = b.map((e) => `${e.id}\t${e.source}\t${e.note}`);
+      return { content: [{ type: "text", text: lines.join("\n") }], details: {} };
+    },
+  });
+}

package/.pi/extensions/evidence-compact/bridge.test.ts

@@ -0,0 +1,25 @@
+import { describe, it, expect } from "vitest";
+
+// Exercise the bridge template as a pure function.
+const BRIDGE_TEMPLATE = (n: number): string =>
+  `[Preserved evidence from earlier in the conversation follows.] ` +
+  `${n} evidence entr${n === 1 ? "y remains" : "ies remain"} available via ` +
+  `EvidenceList and EvidenceGet.`;
+
+describe("evidence-compact bridge message", () => {
+  it("starts with exact preservation prefix (Python-version parity)", () => {
+    const m = BRIDGE_TEMPLATE(3);
+    expect(m.startsWith("[Preserved evidence from earlier in the conversation follows.]")).toBe(true);
+  });
+  it("uses singular for 1 entry", () => {
+    expect(BRIDGE_TEMPLATE(1)).toContain("1 evidence entry remains");
+  });
+  it("uses plural for multiple entries", () => {
+    expect(BRIDGE_TEMPLATE(5)).toContain("5 evidence entries remain");
+  });
+  it("references the retrieval tools by name", () => {
+    const m = BRIDGE_TEMPLATE(2);
+    expect(m).toContain("EvidenceList");
+    expect(m).toContain("EvidenceGet");
+  });
+});

package/.pi/extensions/evidence-compact/index.ts

@@ -0,0 +1,32 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { getSessionStore } from "../evidence/index.ts";
+
+// Port of compaction.py's Evidence-preservation contract.
+//
+// In the Python version, Evidence entries lived as tool-result content
+// inside the message array, so compaction had to explicitly skip them
+// (via _PRESERVE_TOOL_NAMES) and re-emit them with a bridge message. The
+// TypeScript port stores Evidence in extension-state (evidence/index.ts
+// `stores` map), so it survives message-array compaction automatically.
+//
+// This extension preserves the BEHAVIORAL contract: after compaction, the
+// model sees an assistant-side bridge reminding it that its evidence is
+// still addressable via EvidenceList/EvidenceGet. The exact bridge string
+// matches the Python version so replay stays deterministic.
+
+const BRIDGE_TEMPLATE = (n: number): string =>
+  `[Preserved evidence from earlier in the conversation follows.] ` +
+  `${n} evidence entr${n === 1 ? "y remains" : "ies remain"} available via ` +
+  `EvidenceList and EvidenceGet.`;
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_compact", async (_event, ctx) => {
+    const store = getSessionStore();
+    if (store.length === 0) return;
+    ctx.ui.notify(
+      `evidence-compact: ${store.length} evidence entries preserved across compaction`,
+      "info",
+    );
+    pi.sendUserMessage(BRIDGE_TEMPLATE(store.length), { deliverAs: "followUp" });
+  });
+}

package/.pi/extensions/extra-tools/index.ts

@@ -0,0 +1,139 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { glob as globSync } from "node:fs/promises";
+
+// Ports of tools.py::_glob, _webfetch, _websearch. Pi ships its own grep/find,
+// so those are not re-registered here.
+export default function (pi: ExtensionAPI) {
+  // ── glob ────────────────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "glob",
+    label: "Glob",
+    description:
+      "Find files matching a glob pattern. Returns a sorted list of matching paths (up to 500).",
+    parameters: Type.Object({
+      pattern: Type.String({ description: "Glob pattern e.g. **/*.py" }),
+      path: Type.Optional(Type.String({ description: "Base directory (default: cwd)" })),
+    }),
+    async execute(_id, { pattern, path }) {
+      try {
+        const base = path || process.cwd();
+        const matches: string[] = [];
+        // Node 22's fs/promises.glob — returns an async iterator
+        for await (const m of globSync(pattern, { cwd: base })) {
+          matches.push(`${base}/${m}`);
+          if (matches.length >= 500) break;
+        }
+        matches.sort();
+        const text = matches.length === 0 ? "No files matched" : matches.join("\n");
+        return {
+          content: [{ type: "text", text }],
+          details: {},
+        };
+      } catch (e) {
+        return {
+          content: [{ type: "text", text: `Error: ${(e as Error).message}` }],
+          details: {},
+          isError: true,
+        };
+      }
+    },
+  });
+
+  // ── webfetch ────────────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "webfetch",
+    label: "WebFetch",
+    description: "Fetch a URL and return its text content (HTML stripped). Capped at 25K chars.",
+    parameters: Type.Object({
+      url: Type.String({ description: "URL to fetch" }),
+      prompt: Type.Optional(Type.String({ description: "Hint for what to extract (informational)" })),
+    }),
+    async execute(_id, { url }) {
+      try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 30_000);
+        const res = await fetch(url, {
+          headers: { "User-Agent": "little-coder/0.1" },
+          redirect: "follow",
+          signal: controller.signal,
+        });
+        clearTimeout(timer);
+        if (!res.ok) {
+          return {
+            content: [{ type: "text", text: `Error: HTTP ${res.status} ${res.statusText}` }],
+            details: {},
+            isError: true,
+          };
+        }
+        const ct = res.headers.get("content-type") || "";
+        let text = await res.text();
+        if (ct.includes("html")) {
+          text = text.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "");
+          text = text.replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "");
+          text = text.replace(/<[^>]+>/g, " ");
+          text = text.replace(/\s+/g, " ").trim();
+        }
+        if (text.length > 25_000) text = text.slice(0, 25_000);
+        return { content: [{ type: "text", text }], details: {} };
+      } catch (e) {
+        return {
+          content: [{ type: "text", text: `Error: ${(e as Error).message}` }],
+          details: {},
+          isError: true,
+        };
+      }
+    },
+  });
+
+  // ── websearch ───────────────────────────────────────────────────────────
+  pi.registerTool({
+    name: "websearch",
+    label: "WebSearch",
+    description: "Search the web via DuckDuckGo and return the top ~8 results as Markdown.",
+    parameters: Type.Object({
+      query: Type.String({ description: "Search query" }),
+    }),
+    async execute(_id, { query }) {
+      try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 30_000);
+        const url = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
+        const res = await fetch(url, {
+          headers: { "User-Agent": "Mozilla/5.0 (compatible)" },
+          redirect: "follow",
+          signal: controller.signal,
+        });
+        clearTimeout(timer);
+        const body = await res.text();
+        const titleRe = /class="result__title"[^>]*>[\s\S]*?<a[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/g;
+        const snippetRe = /class="result__snippet"[^>]*>([\s\S]*?)<\/div>/g;
+        const titles: Array<{ link: string; title: string }> = [];
+        let m: RegExpExecArray | null;
+        while ((m = titleRe.exec(body)) && titles.length < 8) {
+          titles.push({ link: m[1], title: m[2].replace(/<[^>]+>/g, "").trim() });
+        }
+        const snippets: string[] = [];
+        while ((m = snippetRe.exec(body)) && snippets.length < 8) {
+          snippets.push(m[1].replace(/<[^>]+>/g, "").trim());
+        }
+        if (titles.length === 0) {
+          return {
+            content: [{ type: "text", text: "No results found" }],
+            details: {},
+          };
+        }
+        const out = titles
+          .map((t, i) => `**${t.title}**\n${t.link}\n${snippets[i] ?? ""}`)
+          .join("\n\n");
+        return { content: [{ type: "text", text: out }], details: {} };
+      } catch (e) {
+        return {
+          content: [{ type: "text", text: `Error: ${(e as Error).message}` }],
+          details: {},
+          isError: true,
+        };
+      }
+    },
+  });
+}

package/.pi/extensions/finalize-warn/index.ts

@@ -0,0 +1,73 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+// Pre-cap finalize-warn: when the agent has WARN_REMAINING turns left
+// (this turn included), inject a follow-up user message reminding it to
+// emit `Answer: <value>` before the cap aborts.
+//
+// Why this exists: a recurring small-model failure mode is "ran out of
+// turns mid-thought, never produced final-answer line, extract_final_answer
+// fell back to last line of prose and returned garbage." The warning fires
+// once per agent run, only when the cap is large enough for the warning
+// to give the model real headroom (cap > WARN_REMAINING).
+//
+// This is intentionally a separate extension from turn-cap so that the
+// abort policy and the warn policy stay independent and can be tuned /
+// disabled separately.
+//
+// pi.sendUserMessage(...,{deliverAs:"followUp"}) queues the message for the
+// NEXT user turn — so a warning fired at turn 39 only reaches the model at
+// turn 40, leaving 1 useful turn of headroom (then turn 41 = abort). Raised
+// to 5 so the message lands ~4 turns before cap, giving the model real room.
+
+const WARN_REMAINING = 5;
+
+let turnsThisRun = 0;
+let capForRun = 0;
+let warnedThisRun = false;
+
+function envCap(): number {
+  const raw = process.env.LITTLE_CODER_MAX_TURNS;
+  if (!raw) return 0;
+  const n = parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("before_agent_start", async (event) => {
+    turnsThisRun = 0;
+    warnedThisRun = false;
+    const opts: any = (event as any).systemPromptOptions ?? {};
+    const lcCap = Number(opts?.littleCoder?.maxTurns);
+    capForRun = Number.isFinite(lcCap) && lcCap > 0 ? lcCap : envCap();
+  });
+
+  pi.on("turn_start", async (_event, ctx) => {
+    if (capForRun <= 0) return;
+    turnsThisRun++;
+    if (warnedThisRun) return;
+    if (capForRun <= WARN_REMAINING) return;
+
+    // Fire once when the agent is starting the turn that leaves it
+    // exactly WARN_REMAINING turns to play with. For cap=40, that's
+    // turn 39 — the agent then has turn 39 and turn 40 before the
+    // abort at turn 41.
+    if (turnsThisRun !== capForRun - WARN_REMAINING + 1) return;
+
+    warnedThisRun = true;
+    const msg =
+      `You have ${WARN_REMAINING} turns left. Produce your final reply now, ` +
+      `ending with a single line: \`Answer: <value>\`. ` +
+      `Do not start new tool chains; if you need a fact you don't have, ` +
+      `answer with your best supported guess from EvidenceList rather than ` +
+      `leaving it blank.`;
+    ctx.ui.notify(
+      `finalize-warn: ${WARN_REMAINING} turns left at ${turnsThisRun}/${capForRun}`,
+      "info",
+    );
+    try {
+      pi.sendUserMessage(msg, { deliverAs: "followUp" });
+    } catch {
+      // SDK without sendUserMessage — silently no-op rather than break the run
+    }
+  });
+}

package/.pi/extensions/hello/index.ts

@@ -0,0 +1,7 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", async (_event, ctx) => {
+    ctx.ui.notify("little-coder scaffold loaded", "info");
+  });
+}

package/.pi/extensions/knowledge-inject/index.ts

@@ -0,0 +1,149 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseSkillFile } from "../skill-inject/frontmatter.ts";
+
+// ── Knowledge-entry registry ────────────────────────────────────────────
+// Port of local/knowledge_augment.py. Loads skills/knowledge/*.md plus the
+// three root-level protocol skills (skills/protocols/*.md). Scores entries
+// against the user's prompt, selects top within budget, publishes
+// `requires_tools` on systemPromptOptions so skill-inject can include them.
+
+interface KnowledgeEntry {
+  topic: string;
+  body: string;
+  tokenCost: number;
+  keywords: string[];
+  requiresTools: string[];
+}
+
+const entries = new Map<string, KnowledgeEntry>();
+const cache = new Map<string, string>();
+let loaded = false;
+
+const MIN_SCORE_THRESHOLD = 2.0;
+const PER_ENTRY_CAP = 150;
+
+function dirs(): string[] {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const repo = join(here, "..", "..", "..");
+  return [join(repo, "skills", "knowledge"), join(repo, "skills", "protocols")];
+}
+
+function loadEntries(): void {
+  if (loaded) return;
+  loaded = true;
+  for (const dir of dirs()) {
+    if (!existsSync(dir)) continue;
+    for (const file of readdirSync(dir)) {
+      if (!file.endsWith(".md")) continue;
+      const parsed = parseSkillFile(readFileSync(join(dir, file), "utf-8"));
+      if (!parsed) continue;
+      const fm = parsed.frontmatter;
+      const topic = (typeof fm.topic === "string" ? fm.topic : "") ||
+                    (typeof fm.name === "string" ? fm.name : "");
+      if (!topic || !parsed.body) continue;
+      let cost = typeof fm.token_cost === "number" ? fm.token_cost : 150;
+      if (cost > PER_ENTRY_CAP) cost = PER_ENTRY_CAP;
+      const keywords = Array.isArray(fm.keywords)
+        ? (fm.keywords as string[]).map((k) => k.toLowerCase())
+        : [];
+      const requiresTools = Array.isArray(fm.requires_tools)
+        ? (fm.requires_tools as string[])
+        : [];
+      entries.set(topic, { topic, body: parsed.body, tokenCost: cost, keywords, requiresTools });
+    }
+  }
+}
+
+// ── Scoring (word=1.0, bigram/phrase=2.0) ───────────────────────────────
+function scoreEntry(userText: string, e: KnowledgeEntry): number {
+  if (e.keywords.length === 0) return 0;
+  const textLower = userText.toLowerCase();
+  const words = new Set(textLower.split(/\s+/).filter(Boolean));
+  let score = 0;
+  for (const kw of e.keywords) {
+    if (kw.includes(" ")) {
+      if (textLower.includes(kw)) score += 2.0;
+    } else {
+      if (words.has(kw)) score += 1.0;
+    }
+  }
+  return score;
+}
+
+function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 3.5);
+}
+
+function buildBlock(selected: KnowledgeEntry[]): string {
+  let out = "\n\n## Algorithm Reference\n";
+  for (const e of selected) out += `\n### ${e.topic}\n${e.body}\n`;
+  return out;
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("before_agent_start", async (event, ctx) => {
+    loadEntries();
+    if (entries.size === 0) return;
+
+    const opts: any = (event as any).systemPromptOptions ?? {};
+    const lc = opts.littleCoder ?? {};
+    const budget: number = lc.knowledgeTokenBudget ?? 200;
+    if (budget <= 0) return;
+    if (lc.isSubtask) return;
+
+    const base = event.systemPrompt ?? "";
+    const contextLimit: number = lc.contextLimit ?? 8192;
+    if (estimateTokens(base) > contextLimit * 0.4) return;
+
+    const prompt = event.prompt ?? "";
+    if (!prompt) return;
+
+    const scored: Array<{ score: number; entry: KnowledgeEntry }> = [];
+    for (const e of entries.values()) {
+      const s = scoreEntry(prompt, e);
+      if (s >= MIN_SCORE_THRESHOLD) scored.push({ score: s, entry: e });
+    }
+    if (scored.length === 0) return;
+    scored.sort((a, b) => b.score - a.score);
+
+    const selected: KnowledgeEntry[] = [];
+    let used = 0;
+    for (const { entry } of scored) {
+      if (used + entry.tokenCost > budget) continue;
+      selected.push(entry);
+      used += entry.tokenCost;
+    }
+    if (selected.length === 0) return;
+
+    // Publish required tools on systemPromptOptions. skill-inject reads this
+    // to include the requires_tools' skill cards in its own selection.
+    const requiredTools = Array.from(
+      new Set(selected.flatMap((e) => e.requiresTools)),
+    );
+    if (requiredTools.length > 0) {
+      if (!opts.littleCoder) opts.littleCoder = {};
+      opts.littleCoder.requiredTools = requiredTools;
+    }
+
+    const key = selected.map((e) => e.topic).sort().join("|");
+    let block = cache.get(key);
+    if (block === undefined) {
+      block = buildBlock(selected);
+      cache.set(key, block);
+    }
+
+    try {
+      ctx.ui.notify(
+        `knowledge-inject: +${selected.length} [${selected.map((e) => e.topic).join(",")}]`,
+        "info",
+      );
+    } catch {
+      // best-effort
+    }
+
+    return { systemPrompt: base + block };
+  });
+}

package/.pi/extensions/knowledge-inject/scoring.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseSkillFile } from "../skill-inject/frontmatter.ts";
+
+// Duplicate scoring so tests can exercise it as a pure function.
+function scoreEntry(userText: string, keywords: string[]): number {
+  if (keywords.length === 0) return 0;
+  const textLower = userText.toLowerCase();
+  const words = new Set(textLower.split(/\s+/).filter(Boolean));
+  let score = 0;
+  for (const kw of keywords) {
+    if (kw.includes(" ")) {
+      if (textLower.includes(kw)) score += 2.0;
+    } else {
+      if (words.has(kw)) score += 1.0;
+    }
+  }
+  return score;
+}
+
+describe("knowledge entry scoring", () => {
+  it("scores single word matches at 1.0 each", () => {
+    expect(scoreEntry("find the bucket", ["bucket"])).toBe(1.0);
+    expect(scoreEntry("find the bucket and pour", ["bucket", "pour"])).toBe(2.0);
+  });
+
+  it("scores bigram/phrase matches at 2.0 each", () => {
+    expect(scoreEntry("minimum moves to solve", ["minimum moves"])).toBe(2.0);
+    expect(scoreEntry("state space search", ["state space"])).toBe(2.0);
+  });
+
+  it("combines word + bigram scores", () => {
+    const kw = ["bucket", "minimum moves", "pour"];
+    // "bucket" word (1.0) + "minimum moves" phrase (2.0) + "pour" word (1.0) = 4.0
+    expect(scoreEntry("bucket pouring problem with minimum moves and pour", kw)).toBe(4.0);
+  });
+
+  it("does not match partial words", () => {
+    // 'bucket' shouldn't match 'buckets' because the scorer tokenizes on whitespace
+    expect(scoreEntry("many buckets here", ["bucket"])).toBe(0);
+  });
+
+  it("threshold at 2.0 requires at least two signals", () => {
+    // The extension's MIN_SCORE_THRESHOLD = 2.0 means one word isn't enough
+    expect(scoreEntry("find bucket", ["bucket", "pour"])).toBeLessThan(2.0);
+    expect(scoreEntry("bucket pour together", ["bucket", "pour"])).toBeGreaterThanOrEqual(2.0);
+  });
+});
+
+describe("knowledge directory loads from repo", () => {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const kDir = join(here, "..", "..", "..", "skills", "knowledge");
+  const pDir = join(here, "..", "..", "..", "skills", "protocols");
+
+  it("knowledge dir has 13 files", () => {
+    expect(existsSync(kDir)).toBe(true);
+    expect(readdirSync(kDir).filter((f) => f.endsWith(".md")).length).toBe(13);
+  });
+
+  it("protocols dir has 3 files", () => {
+    expect(existsSync(pDir)).toBe(true);
+    expect(readdirSync(pDir).filter((f) => f.endsWith(".md")).length).toBe(3);
+  });
+
+  it("every knowledge entry has topic + keywords in frontmatter", () => {
+    const files = readdirSync(kDir).filter((f) => f.endsWith(".md"));
+    for (const file of files) {
+      const parsed = parseSkillFile(readFileSync(join(kDir, file), "utf-8"));
+      expect(parsed, `${file} should parse`).not.toBeNull();
+      expect(typeof parsed!.frontmatter.topic).toBe("string");
+      expect(Array.isArray(parsed!.frontmatter.keywords), `${file} keywords`).toBe(true);
+    }
+  });
+
+  it("workspace_docs declares requires_tools", () => {
+    const parsed = parseSkillFile(readFileSync(join(kDir, "workspace_docs.md"), "utf-8"));
+    expect(parsed!.frontmatter.requires_tools).toEqual(["Read", "Glob"]);
+  });
+});