rulebookguard 0.8.0 → 0.10.0

package/dist/cli.mjs

@@ -1,23 +1,433 @@
 #!/usr/bin/env node
-import { F as messages, I as FormatError, L as formatIssue, M as CONFIG_FILE_NAME, O as CONTEXT_FILE_NAME, _ as expandGlobs, a as CliError, c as openCatalog, f as scanTestTags, l as writeJson, m as loadCatalog, o as findRule, p as findRulebookRoot, r as lintCommand, s as gitFallbackWarning, u as writeLines, y as toRepoPath } from "./lint-DfibQDW3.mjs";
-import { t as rulesForPath } from "./anchors-C2j9c5MI.mjs";
-import { access, mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { B as FormatError, I as CONFIG_FILE_NAME, M as CONTEXT_FILE_NAME, S as toRepoPath, V as formatIssue, _ as loadCatalog, b as expandGlobs, c as gitFallbackWarning, d as writeJson, f as writeLines, g as findRulebookRoot, h as scanTestTags, i as lintCommand, k as isRuleId, l as openCatalog, o as CliError, p as scanImplementations, s as findRule, t as changedFiles, u as shownPath, z as messages } from "./lint-BPdk6XxH.mjs";
+import { t as rulesForPath } from "./anchors-jf2bKfyg.mjs";
+import { access, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import { McpServer } from "@modelcontextprotocol/server";
 import * as z from "zod/v4";
+// src/commands/export-agents.ts
+const RULE_FILE_TARGETS = {
+	cursor: {
+		dir: ".cursor/rules",
+		extension: ".mdc",
+		frontmatter: (patterns) => [`globs: ${patterns.join(", ")}`, "alwaysApply: false"]
+	},
+	copilot: {
+		dir: ".github/instructions",
+		extension: ".instructions.md",
+		frontmatter: (patterns) => [`applyTo: ${JSON.stringify(patterns.join(","))}`]
+	},
+	kiro: {
+		dir: ".kiro/steering",
+		extension: ".md",
+		frontmatter: (patterns) => ["inclusion: fileMatch", `fileMatchPattern: ${JSON.stringify(patterns.length === 1 ? patterns[0] : patterns)}`]
+	}
+};
+const AGENTS_MD_FORMAT = "agents-md";
+const AGENTS_MD_FILE = "AGENTS.md";
+const BLOCK_START = "<!-- rulebookguard:start -->";
+const BLOCK_END = "<!-- rulebookguard:end -->";
+const RULE_FILE_PREFIX = "rulebookguard-";
+const AGENT_FORMATS = [...Object.keys(RULE_FILE_TARGETS), AGENTS_MD_FORMAT];
+async function exportAgentRules(catalog, io, format, out) {
+	const rules = catalog.rules.filter((rule) => rule.status === "active").sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+	const target = RULE_FILE_TARGETS[format];
+	const outDir = (dir) => out === void 0 ? join(catalog.root, dir) : resolve(io.cwd, out);
+	writeLines(io, target === void 0 ? await writeAgentsMd(catalog, io, rules, outDir(".")) : await writeRuleFiles(catalog, io, rules, format, target, outDir(target.dir)));
+}
+function anchoredRules(rules, io, text) {
+	const unanchored = rules.filter((rule) => rule.anchors.length === 0);
+	if (unanchored.length > 0) io.stderr(unanchored.map((rule) => `${text.unanchoredRuleSkipped(rule.id)}\n`).join(""));
+	return rules.filter((rule) => rule.anchors.length > 0);
+}
+async function writeRuleFiles(catalog, io, active, format, target, dir) {
+	const text = messages(catalog.config.language);
+	const rules = anchoredRules(active, io, text);
+	const nothing = active.length === 0 ? text.noActiveRules : text.noAnchoredRules;
+	const lines = rules.length === 0 ? [nothing] : [];
+	const fileName = (rule) => `${RULE_FILE_PREFIX}${rule.id}${target.extension}`;
+	const handWritten = await handWrittenFiles(dir, format, rules.map(fileName));
+	if (handWritten.length > 0) throw new CliError(handWritten.map((name) => text.handWrittenExport(toRepoPath(shownPath(io.cwd, join(dir, name))), format)).join("\n"));
+	const current = /* @__PURE__ */ new Set();
+	for (const rule of rules) {
+		const name = fileName(rule);
+		current.add(name);
+		await mkdir(dir, { recursive: true });
+		await writeFile(join(dir, name), ruleFile(rule, format, target, text));
+		lines.push(toRepoPath(shownPath(io.cwd, join(dir, name))));
+	}
+	for (const name of await staleRuleFiles(dir, format, target, current)) {
+		await rm(join(dir, name));
+		lines.push(text.removedExport(toRepoPath(shownPath(io.cwd, join(dir, name)))));
+	}
+	return lines;
+}
+function ruleFile(rule, format, target, text) {
+	return [
+		"---",
+		...target.frontmatter(patternsOf(rule)),
+		"---",
+		"",
+		`<!-- ${text.generatedRule(format, rule.file)} -->`,
+		"",
+		`**${rule.id}:** ${rule.summary}`,
+		"",
+		`${normalizedBody(rule)}\n`
+	].join("\n");
+}
+async function handWrittenFiles(dir, format, names) {
+	const existing = new Set(await listNames(dir));
+	const handWritten = [];
+	for (const name of names) if (existing.has(name) && !hasGeneratedLine(await readFile(join(dir, name), "utf8"), format)) handWritten.push(name);
+	return handWritten;
+}
+async function staleRuleFiles(dir, format, target, current) {
+	const stale = [];
+	for (const name of await listNames(dir)) if (!current.has(name) && name.startsWith(RULE_FILE_PREFIX) && name.endsWith(target.extension) && isRuleId(name.slice(14, -target.extension.length)) && hasGeneratedLine(await readFile(join(dir, name), "utf8"), format)) stale.push(name);
+	return stale.sort();
+}
+function hasGeneratedLine(content, format) {
+	const lines = content.split(/\r?\n/);
+	const closing = lines.indexOf("---", 1);
+	const line = lines[closing + 2] ?? "";
+	return lines[0] === "---" && closing !== -1 && lines[closing + 1] === "" && line.startsWith("<!-- ") && line.includes(` "rulebookguard export ${format}" `) && line.endsWith(" -->");
+}
+async function listNames(dir) {
+	try {
+		return await readdir(dir);
+	} catch (error) {
+		if (error.code === "ENOENT") return [];
+		throw error;
+	}
+}
+async function writeAgentsMd(catalog, io, rules, dir) {
+	const text = messages(catalog.config.language);
+	const file = join(dir, AGENTS_MD_FILE);
+	const shown = toRepoPath(shownPath(io.cwd, file));
+	const existing = await readOptional(file);
+	const start = existing.indexOf(BLOCK_START);
+	const end = existing.indexOf(BLOCK_END);
+	const starts = existing.split(BLOCK_START).length - 1;
+	if (starts !== existing.split(BLOCK_END).length - 1 || starts > 1 || end < start) throw new CliError(text.invalidAgentsMdMarkers(shown, BLOCK_START, BLOCK_END));
+	const hasBlock = starts === 1;
+	if (rules.length === 0 && !hasBlock) return [text.noActiveRules];
+	const before = hasBlock ? existing.slice(0, start) : existing;
+	const after = hasBlock ? existing.slice(end + 26) : "";
+	if (rules.length === 0) {
+		const rest = withoutBlock(before, after);
+		if (rest === "") {
+			await rm(file);
+			return [text.noActiveRules, text.removedExport(shown)];
+		}
+		await writeFile(file, rest);
+		return [text.noActiveRules, shown];
+	}
+	await mkdir(dir, { recursive: true });
+	await writeFile(file, withBlock(before, after, agentsBlock(rules, text), hasBlock));
+	return [shown];
+}
+function withBlock(before, after, block, hasBlock) {
+	if (hasBlock) return `${before}${block}${after}`;
+	return before.trim() === "" ? `${block}\n` : `${before.trimEnd()}\n\n${block}\n`;
+}
+function withoutBlock(before, after) {
+	const joined = `${before}${after.replace(/^(?:\r?\n)+/, "")}`;
+	return joined.trim() === "" ? "" : `${joined.trimEnd()}\n`;
+}
+function agentsBlock(rules, text) {
+	return [
+		BLOCK_START,
+		`<!-- ${text.generatedAgentsMd} -->`,
+		`## ${text.agentsMdHeading}`,
+		"",
+		text.agentsMdIntro,
+		"",
+		...rules.map((rule) => {
+			const anchors = rule.anchors.map((anchor) => `\`${toRepoPath(anchor)}\``).join(", ") || text.agentsMdNoAnchors;
+			return `- \`${rule.id}\` (${anchors}): ${rule.summary} ${text.agentsMdSeeFile(rule.file)}`;
+		}),
+		BLOCK_END
+	].join("\n");
+}
+async function readOptional(file) {
+	try {
+		return await readFile(file, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return "";
+		throw error;
+	}
+}
+function patternsOf(rule) {
+	return [...new Set(rule.anchors.flatMap((anchor) => expandBraces(toRepoPath(anchor))))];
+}
+function expandBraces(glob) {
+	const match = /\{([^{}]*,[^{}]*)\}/.exec(glob);
+	if (match === null) return [glob];
+	const head = glob.slice(0, match.index);
+	const tail = glob.slice(match.index + match[0].length);
+	return (match[1] ?? "").split(",").flatMap((option) => expandBraces(`${head}${option}${tail}`));
+}
+function normalizedBody(rule) {
+	return rule.body.replaceAll("\r\n", "\n").trim();
+}
+// src/commands/export.ts
+const EXPORT_USAGE = "rulebookguard export <format> [--out <dir>]";
+const GHERKIN_BLOCK = /^```gherkin[^\n]*\n([\s\S]*?)^```/gm;
+const LANGUAGE_LINE = /^\s*#\s*language:.*$/;
+async function exportCommand(catalog, io, format, out) {
+	if (AGENT_FORMATS.includes(format)) {
+		await exportAgentRules(catalog, io, format, out);
+		return;
+	}
+	if (format !== "gherkin") {
+		const supported = ["gherkin", ...AGENT_FORMATS].join(", ");
+		throw new CliError(`Unknown export format "${format}"; supported: ${supported}.\nUsage: ${EXPORT_USAGE}`, 2);
+	}
+	const language = catalog.config.language ?? "en";
+	const text = messages(language);
+	const outDir = resolve(io.cwd, out ?? "features/rules");
+	const written = [];
+	const rules = catalog.rules.filter((rule) => rule.status !== "deprecated").sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+	for (const rule of rules) {
+		const scenarios = gherkinBlocks(rule.body);
+		if (scenarios.length === 0) continue;
+		const file = join(outDir, rule.context, `${rule.id}.feature`);
+		await mkdir(dirname(file), { recursive: true });
+		await writeFile(file, featureFile(rule, scenarios, language === "es", text));
+		written.push(shownPath(io.cwd, file));
+	}
+	writeLines(io, written.length === 0 ? [text.noGherkinScenarios] : written);
+}
+function gherkinBlocks(body) {
+	return [...body.matchAll(GHERKIN_BLOCK)].map((match) => (match[1] ?? "").split("\n").filter((line) => !LANGUAGE_LINE.test(line)).join("\n").trim()).filter((block) => block !== "");
+}
+function featureFile(rule, scenarios, spanish, text) {
+	const indented = scenarios.map((block) => block.split("\n").map((line) => line.trim() === "" ? "" : `  ${line}`).join("\n"));
+	return [
+		...spanish ? ["# language: es"] : [],
+		`# ${text.generatedFeature(rule.file)}`,
+		`@${rule.id}`,
+		`${text.featureKeyword}: ${rule.id} ${rule.summary}`,
+		"",
+		`${indented.join("\n\n")}\n`
+	].join("\n");
+}
+// src/commands/read.ts
+const RULE_STATUSES = [
+	"proposed",
+	"active",
+	"deprecated"
+];
+function contextsCommand(catalog, io, json) {
+	const contexts = [...catalog.contexts].sort((a, b) => compare(a.context, b.context)).map(({ context, prefix, summary, file }) => ({
+		context,
+		prefix,
+		summary,
+		rules: catalog.rules.filter((rule) => rule.context === context).length,
+		file
+	}));
+	if (json) {
+		writeJson(io, { contexts });
+		return;
+	}
+	if (contexts.length === 0) {
+		writeLines(io, [messages(catalog.config.language).noContexts]);
+		return;
+	}
+	writeLines(io, contexts.map((item) => `${item.context} (${item.prefix}, ${messages(catalog.config.language).ruleCount(item.rules)}): ${item.summary}`));
+}
+function listCommand(catalog, io, options) {
+	const { context, status } = options;
+	const text = messages(catalog.config.language);
+	if (status !== void 0 && !RULE_STATUSES.includes(status)) throw new CliError(text.invalidStatus(status, RULE_STATUSES.join(", ")), 2);
+	if (context !== void 0 && !catalog.contexts.some((item) => item.context === context)) throw new CliError(text.unknownContext(context));
+	const rules = sortById(catalog.rules).filter((rule) => context === void 0 || rule.context === context).filter((rule) => status === void 0 || rule.status === status).map(toSummary);
+	if (options.json) {
+		writeJson(io, { rules });
+		return;
+	}
+	if (rules.length === 0) {
+		writeLines(io, [text.noRules]);
+		return;
+	}
+	writeLines(io, rules.map((rule) => `${rule.id} [${rule.status}] ${rule.summary}`));
+}
+function searchCommand(catalog, io, query, options) {
+	const { context } = options;
+	const text = messages(catalog.config.language);
+	if (context !== void 0 && !catalog.contexts.some((item) => item.context === context)) throw new CliError(text.unknownContext(context));
+	const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+	const rules = sortById(catalog.rules).filter((rule) => context === void 0 || rule.context === context).filter((rule) => {
+		const haystack = [
+			rule.id,
+			rule.summary,
+			...rule.entities,
+			rule.body
+		].join("\n").toLowerCase();
+		return terms.every((term) => haystack.includes(term));
+	}).map(toSummary);
+	if (options.json) {
+		writeJson(io, { rules });
+		return;
+	}
+	writeLines(io, rules.length === 0 ? [text.noRules] : rules.map((rule) => `${rule.id} [${rule.status}] ${rule.summary}`));
+}
+async function showCommand(catalog, io, id, json) {
+	const rule = findRule(catalog, id);
+	const files = await expandGlobs(catalog.root, rule.anchors, gitFallbackWarning(io, catalog.config.language));
+	const implementations = (await scanImplementations(catalog.root, files)).regions.get(rule.id) ?? [];
+	if (json) {
+		writeJson(io, { rule: {
+			...toSummary(rule),
+			entities: rule.entities,
+			anchors: rule.anchors,
+			supersedes: rule.supersedes ?? null,
+			dependsOn: rule.dependsOn ?? [],
+			conflictsWith: rule.conflictsWith ?? [],
+			origin: rule.origin ?? null,
+			evidence: rule.evidence ?? [],
+			implementations,
+			file: rule.file,
+			body: rule.body
+		} });
+		return;
+	}
+	const none = messages(catalog.config.language).none;
+	const header = [
+		`${rule.id}: ${rule.summary}`,
+		`context: ${rule.context}`,
+		`status: ${rule.status}`,
+		`entities: ${rule.entities.length === 0 ? none : rule.entities.join(", ")}`,
+		"anchors:",
+		...indent(rule.anchors, none),
+		...rule.supersedes === void 0 ? [] : [`supersedes: ${rule.supersedes}`],
+		...rule.dependsOn?.length ? [`dependsOn: ${rule.dependsOn.join(", ")}`] : [],
+		...rule.conflictsWith?.length ? [`conflictsWith: ${rule.conflictsWith.join(", ")}`] : [],
+		...rule.origin === void 0 ? [] : [`origin: ${rule.origin}`],
+		...rule.evidence?.length ? ["evidence:", ...indent(rule.evidence, none)] : [],
+		...implementations.length ? ["implementations:", ...indent(implementations.map((region) => `${region.file}:${region.line}-${region.endLine}`), none)] : [],
+		`file: ${rule.file}`
+	];
+	io.stdout(`${header.join("\n")}\n\n${rule.body}`);
+}
+async function forCommand(catalog, io, input, json) {
+	const text = messages(catalog.config.language);
+	const path = toRootPath(catalog, resolve(io.cwd, input), input);
+	const regions = await regionsIn(catalog.root, path);
+	const rules = rulesForPath(catalog.rules, path).filter((rule) => rule.status === "active").map((rule) => ({
+		...toSummary(rule),
+		file: rule.file,
+		regions: regions(rule.id)
+	}));
+	if (json) {
+		writeJson(io, {
+			path,
+			rules
+		});
+		return;
+	}
+	if (rules.length === 0) {
+		writeLines(io, [text.noActiveRulesFor(path)]);
+		return;
+	}
+	writeLines(io, rules.map((rule) => `${rule.id} (${rule.context}): ${rule.summary}${rule.regions.length === 0 ? "" : ` (${text.lines(formatSpans(rule.regions))})`}`));
+}
+async function forChangedCommand(catalog, io, base, json) {
+	const text = messages(catalog.config.language);
+	const { files } = await changedFiles(catalog.root, base, text, "for --changed", { bothRenamePaths: true });
+	const touched = /* @__PURE__ */ new Map();
+	for (const file of files) for (const rule of rulesForPath(catalog.rules, file)) touched.set(rule.id, [...touched.get(rule.id) ?? [], file]);
+	const rules = sortById(catalog.rules.filter((rule) => rule.status === "active")).flatMap((rule) => {
+		const ruleFiles = touched.get(rule.id);
+		return ruleFiles === void 0 ? [] : [{
+			...toSummary(rule),
+			file: rule.file,
+			files: ruleFiles
+		}];
+	});
+	if (json) {
+		writeJson(io, {
+			base,
+			files,
+			rules
+		});
+		return;
+	}
+	if (rules.length === 0) {
+		writeLines(io, [text.noActiveRulesForChanged(base)]);
+		return;
+	}
+	writeLines(io, rules.flatMap((rule) => [`${rule.id} (${rule.context}): ${rule.summary}`, ...indent(rule.files, text.none)]));
+}
+async function regionsIn(root, path) {
+	const found = (await scanImplementations(root, [path])).regions;
+	return (id) => (found.get(id) ?? []).map(({ line, endLine }) => ({
+		line,
+		endLine
+	}));
+}
+function formatSpans(spans) {
+	return spans.map(({ line, endLine }) => `${line}-${endLine}`).join(", ");
+}
+async function impactCommand(catalog, io, id, json) {
+	const rule = findRule(catalog, id);
+	const text = messages(catalog.config.language);
+	const warn = gitFallbackWarning(io, catalog.config.language);
+	const files = await expandGlobs(catalog.root, rule.anchors, warn);
+	const tests = (await scanTestTags(catalog.root, catalog.config.testGlobs, warn)).get(id) ?? [];
+	if (json) {
+		writeJson(io, {
+			id,
+			files,
+			tests
+		});
+		return;
+	}
+	writeLines(io, [
+		`${rule.id}: ${rule.summary}`,
+		text.filesMatched(files.length),
+		...indent(files, text.none),
+		text.testsTagging(rule.id, tests.length),
+		...indent(tests.map((test) => `${test.file}:${test.line}`), text.none)
+	]);
+}
+function toRootPath(catalog, absolute, input) {
+	const path = toRepoPath(relative(catalog.root, absolute));
+	if (path === "" || path === ".." || path.startsWith("../") || isAbsolute(path)) throw new CliError(messages(catalog.config.language).outsideRoot(input, catalog.root));
+	return path;
+}
+function toSummary(rule) {
+	return {
+		id: rule.id,
+		context: rule.context,
+		status: rule.status,
+		summary: rule.summary
+	};
+}
+function indent(lines, none) {
+	return lines.length === 0 ? [`  ${none}`] : lines.map((line) => `  ${line}`);
+}
+function sortById(rules) {
+	return [...rules].sort((a, b) => compare(a.id, b.id));
+}
+function compare(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
 // src/commands/hook.ts
 const HOOK_BODY_LIMIT = 1e4;
 const TEXT = {
 	en: {
 		header: (path) => `Business rules anchored to ${path} (rulebookguard). They are the source of truth: keep any change to this file consistent with them, and change the rule first if a change alters its behavior.`,
 		ruleFile: "Rule file",
+		lines: "Lines",
 		omitted: `Rule texts omitted (over ${HOOK_BODY_LIMIT} characters); run \`rulebookguard show <id>\` for the full text.`
 	},
 	es: {
 		header: (path) => `Reglas de negocio ancladas a ${path} (rulebookguard). Son la fuente de verdad: mantén cualquier cambio a este archivo coherente con ellas y, si un cambio altera su comportamiento, cambia primero la regla.`,
 		ruleFile: "Archivo de la regla",
+		lines: "Líneas",
 		omitted: `Se omitió el texto de las reglas (más de ${HOOK_BODY_LIMIT} caracteres); ejecuta \`rulebookguard show <id>\` para verlo completo.`
 	}
 };
@@ -42,7 +452,7 @@ async function hookContext(event, cwd) {
 	const repoPath = path.split(sep).join("/");
 	const rules = rulesForPath(catalog.rules, repoPath).filter((rule) => rule.status === "active");
 	if (rules.length === 0) return;
-	return render(repoPath, rules, TEXT[catalog.config.language ?? "en"]);
+	return render(repoPath, rules, await regionsIn(root, repoPath).catch(() => () => []), TEXT[catalog.config.language ?? "en"]);
 }
 function parseEvent(input) {
 	let event;
@@ -65,10 +475,15 @@ function parseEvent(input) {
 		filePath
 	};
 }
-function render(path, rules, text) {
+function render(path, rules, regions, text) {
 	const withBodies = rules.reduce((total, rule) => total + rule.body.trim().length, 0) <= HOOK_BODY_LIMIT;
 	const sections = rules.map((rule) => {
-		const lines = [`## ${rule.id} (${rule.context}): ${rule.summary}`, `${text.ruleFile}: ${rule.file}`];
+		const spans = regions(rule.id);
+		const lines = [
+			`## ${rule.id} (${rule.context}): ${rule.summary}`,
+			`${text.ruleFile}: ${rule.file}`,
+			...spans.length === 0 ? [] : [`${text.lines}: ${formatSpans(spans)}`]
+		];
 		return withBodies ? [
 			...lines,
 			"",
@@ -80,7 +495,7 @@ function render(path, rules, text) {
 	return parts.join("\n\n");
 }
 // package.json
-var version = "0.8.0";
+var version = "0.10.0";
 // src/commands/new.ts
 const MAX_NUMBER = 999;
 const CONTEXT_NAME = /^[a-z0-9][a-z0-9_-]*$/;
@@ -271,9 +686,53 @@ function createRulesServer(projectDir) {
 		id,
 		"--json"
 	]));
+	server.registerTool("contexts", {
+		description: "L0 map of the rulebook: each context with its prefix, summary and number of rules. Start here to find the contexts a change touches.",
+		inputSchema: z.object({}),
+		annotations: { readOnlyHint: true }
+	}, () => cli(projectDir, ["contexts", "--json"]));
+	server.registerTool("rules_list", {
+		description: "L1 list of rules: id, context, status and summary, optionally narrowed to one context and one status. Read the full text of the relevant ones with rules_show.",
+		inputSchema: z.object({
+			context: z.string().optional().describe("Context name, for example clients"),
+			status: z.enum([
+				"proposed",
+				"active",
+				"deprecated"
+			]).optional()
+		}),
+		annotations: { readOnlyHint: true }
+	}, ({ context, status }) => cli(projectDir, [
+		"list",
+		...context === void 0 ? [] : ["--context", context],
+		...status === void 0 ? [] : ["--status", status],
+		"--json"
+	]));
+	server.registerTool("rules_search", {
+		description: "Rules in any status whose id, summary, entities or text hold every word of the text, ignoring case (plain text search, no embeddings). Use it to find existing rules before proposing a new one.",
+		inputSchema: z.object({
+			text: z.string().describe("Words to look for, for example \"invoice number\""),
+			context: z.string().optional().describe("Context name to search in")
+		}),
+		annotations: { readOnlyHint: true }
+	}, ({ text, context }) => cli(projectDir, [
+		"search",
+		text,
+		...context === void 0 ? [] : ["--context", context],
+		"--json"
+	]));
+	server.registerTool("lint", {
+		description: "Checks the whole rulebook (schema, anchors, test tags, relations between rules) and answers the findings with a hint each; with base, rules changed since that git ref also need a changed test. Findings are data: the tool fails only when lint cannot run.",
+		inputSchema: z.object({ base: z.string().optional().describe("Git ref to compare with, for example origin/main") }),
+		annotations: { readOnlyHint: true }
+	}, ({ base }) => cli(projectDir, [
+		"lint",
+		...base === void 0 ? [] : ["--base", base],
+		"--json"
+	], { findingsAreData: true }));
 	return server;
 }
-async function cli(cwd, args) {
+async function cli(cwd, args, { findingsAreData = false } = {}) {
 	let stdout = "";
 	let stderr = "";
 	if (await runCli(args, {
@@ -284,7 +743,7 @@ async function cli(cwd, args) {
 		stderr: (text) => {
 			stderr += text;
 		}
-	}) === 0) return { content: [{
+	}) === 0 || findingsAreData && stdout !== "") return { content: [{
 		type: "text",
 		text: stdout
 	}] };
@@ -300,136 +759,6 @@ async function cli(cwd, args) {
 async function mcpCommand(io, project) {
 	await createRulesServer(resolve(io.cwd, project ?? ".")).connect(new StdioServerTransport());
 }
-// src/commands/read.ts
-const RULE_STATUSES = [
-	"proposed",
-	"active",
-	"deprecated"
-];
-function contextsCommand(catalog, io, json) {
-	const contexts = [...catalog.contexts].sort((a, b) => compare(a.context, b.context)).map(({ context, prefix, summary, file }) => ({
-		context,
-		prefix,
-		summary,
-		rules: catalog.rules.filter((rule) => rule.context === context).length,
-		file
-	}));
-	if (json) {
-		writeJson(io, { contexts });
-		return;
-	}
-	if (contexts.length === 0) {
-		writeLines(io, [messages(catalog.config.language).noContexts]);
-		return;
-	}
-	writeLines(io, contexts.map((item) => `${item.context} (${item.prefix}, ${messages(catalog.config.language).ruleCount(item.rules)}): ${item.summary}`));
-}
-function listCommand(catalog, io, options) {
-	const { context, status } = options;
-	const text = messages(catalog.config.language);
-	if (status !== void 0 && !RULE_STATUSES.includes(status)) throw new CliError(text.invalidStatus(status, RULE_STATUSES.join(", ")), 2);
-	if (context !== void 0 && !catalog.contexts.some((item) => item.context === context)) throw new CliError(text.unknownContext(context));
-	const rules = sortById(catalog.rules).filter((rule) => context === void 0 || rule.context === context).filter((rule) => status === void 0 || rule.status === status).map(toSummary);
-	if (options.json) {
-		writeJson(io, { rules });
-		return;
-	}
-	if (rules.length === 0) {
-		writeLines(io, [text.noRules]);
-		return;
-	}
-	writeLines(io, rules.map((rule) => `${rule.id} [${rule.status}] ${rule.summary}`));
-}
-function showCommand(catalog, io, id, json) {
-	const rule = findRule(catalog, id);
-	if (json) {
-		writeJson(io, { rule: {
-			...toSummary(rule),
-			entities: rule.entities,
-			anchors: rule.anchors,
-			supersedes: rule.supersedes ?? null,
-			file: rule.file,
-			body: rule.body
-		} });
-		return;
-	}
-	const none = messages(catalog.config.language).none;
-	const header = [
-		`${rule.id}: ${rule.summary}`,
-		`context: ${rule.context}`,
-		`status: ${rule.status}`,
-		`entities: ${rule.entities.length === 0 ? none : rule.entities.join(", ")}`,
-		"anchors:",
-		...indent(rule.anchors, none),
-		...rule.supersedes === void 0 ? [] : [`supersedes: ${rule.supersedes}`],
-		`file: ${rule.file}`
-	];
-	io.stdout(`${header.join("\n")}\n\n${rule.body}`);
-}
-function forCommand(catalog, io, input, json) {
-	const text = messages(catalog.config.language);
-	const path = toRootPath(catalog, resolve(io.cwd, input), input);
-	const rules = rulesForPath(catalog.rules, path).filter((rule) => rule.status === "active").map((rule) => ({
-		...toSummary(rule),
-		file: rule.file
-	}));
-	if (json) {
-		writeJson(io, {
-			path,
-			rules
-		});
-		return;
-	}
-	if (rules.length === 0) {
-		writeLines(io, [text.noActiveRulesFor(path)]);
-		return;
-	}
-	writeLines(io, rules.map((rule) => `${rule.id} (${rule.context}): ${rule.summary}`));
-}
-async function impactCommand(catalog, io, id, json) {
-	const rule = findRule(catalog, id);
-	const text = messages(catalog.config.language);
-	const warn = gitFallbackWarning(io, catalog.config.language);
-	const files = await expandGlobs(catalog.root, rule.anchors, warn);
-	const tests = (await scanTestTags(catalog.root, catalog.config.testGlobs, warn)).get(id) ?? [];
-	if (json) {
-		writeJson(io, {
-			id,
-			files,
-			tests
-		});
-		return;
-	}
-	writeLines(io, [
-		`${rule.id}: ${rule.summary}`,
-		text.filesMatched(files.length),
-		...indent(files, text.none),
-		text.testsTagging(rule.id, tests.length),
-		...indent(tests.map((test) => `${test.file}:${test.line}`), text.none)
-	]);
-}
-function toRootPath(catalog, absolute, input) {
-	const path = toRepoPath(relative(catalog.root, absolute));
-	if (path === "" || path === ".." || path.startsWith("../") || isAbsolute(path)) throw new CliError(messages(catalog.config.language).outsideRoot(input, catalog.root));
-	return path;
-}
-function toSummary(rule) {
-	return {
-		id: rule.id,
-		context: rule.context,
-		status: rule.status,
-		summary: rule.summary
-	};
-}
-function indent(lines, none) {
-	return lines.length === 0 ? [`  ${none}`] : lines.map((line) => `  ${line}`);
-}
-function sortById(rules) {
-	return [...rules].sort((a, b) => compare(a.id, b.id));
-}
-function compare(a, b) {
-	return a < b ? -1 : a > b ? 1 : 0;
-}
 // src/commands/run.ts
 const USAGE = `Usage: rulebookguard <command> [options]
 
@@ -442,17 +771,31 @@ Commands:
   contexts [--json]                                  L0: list the contexts
   list [--context <c>] [--status <s>] [--json]       L1: id and summary of each rule
   show <id> [--json]                                 L2: the full rule
+  search <text> [--context <c>] [--json]             rules whose id, summary, entities or text hold every
+                                                     word of <text>, ignoring case
   for <path> [--json]                                active rules anchored to a path
+  for --changed <ref> [--json]                       active rules anchored to the files changed since <ref>,
+                                                     each with those files
   impact <id> [--json]                               files matched by a rule's anchors and tests tagging it
   new <context> [--prefix <P>]                       scaffold the next free rule id as a proposed rule;
                                                      creates the context first when it does not exist,
                                                      --prefix: its id prefix (default: first 3 letters)
   lint [--base <ref>] [--json]                       check the catalog, anchors and test tags;
                                                      --base: rules changed since <ref> need a changed test
+  export gherkin [--out <dir>]                       write the Gherkin blocks of each non-deprecated rule as
+                                                     <out>/<context>/<id>.feature tagged @<id>;
+                                                     --out: output directory (default: features/rules)
+  export cursor|copilot|kiro [--out <dir>]           write each active rule as a rule file of the tool, scoped
+                                                     to its anchors, in .cursor/rules, .github/instructions
+                                                     or .kiro/steering, and remove those of rules no longer
+                                                     active; --out: output directory
+  export agents-md [--out <dir>]                     keep an index of the active rules in a marked block of
+                                                     AGENTS.md; --out: its directory (default: rulebook root)
   hook                                               Claude Code hook for PreToolUse and PostToolUse: reads
                                                      the event on stdin and prints the rules anchored to
                                                      the file of the tool (Read, Edit, Write...)
-  mcp [--project <dir>]                              MCP server over stdio with rules_for and rules_show;
+  mcp [--project <dir>]                              MCP server over stdio with rules_for, rules_show, contexts,
+                                                     rules_list, rules_search and lint;
                                                      --project: directory to find the rulebook from (default: cwd)
   site:generate [--out <dir>] [--base <path>]        build the read-only static site of the rulebook (alias: site);
                                                      --out: output directory (default: site), --base: URL path
@@ -495,10 +838,22 @@ const COMMANDS = {
 		argument: "id",
 		options: JSON_OPTION
 	},
+	search: {
+		usage: "rulebookguard search <text> [--context <c>] [--json]",
+		argument: "text",
+		options: {
+			...JSON_OPTION,
+			context: { type: "string" }
+		}
+	},
 	for: {
-		usage: "rulebookguard for <path> [--json]",
+		usage: "rulebookguard for <path>|--changed <ref> [--json]",
 		argument: "path",
-		options: JSON_OPTION
+		argumentUnless: "changed",
+		options: {
+			...JSON_OPTION,
+			changed: { type: "string" }
+		}
 	},
 	impact: {
 		usage: "rulebookguard impact <id> [--json]",
@@ -510,6 +865,11 @@ const COMMANDS = {
 		argument: "context",
 		options: { prefix: { type: "string" } }
 	},
+	export: {
+		usage: EXPORT_USAGE,
+		argument: "format",
+		options: { out: { type: "string" } }
+	},
 	hook: {
 		usage: "rulebookguard hook",
 		options: {}
@@ -575,7 +935,7 @@ async function dispatch(argv, io) {
 		return 0;
 	}
 	if (name === "site" || name === "site:generate" || name === "site:run") {
-		const { siteCommand } = await import("./site-DmY5YVte.mjs");
+		const { siteCommand } = await import("./site-B7g8lbjx.mjs");
 		await siteCommand(io, {
 			out: values.out,
 			base: values.base,
@@ -596,6 +956,7 @@ async function dispatch(argv, io) {
 		base: values.base,
 		json
 	});
+	if (name === "search" && argument.trim() === "") throw new CliError(`Search text is empty. Usage: ${spec.usage}`, 2);
 	const catalog = await openCatalog(io);
 	switch (name) {
 		case "contexts":
@@ -609,15 +970,25 @@ async function dispatch(argv, io) {
 			});
 			break;
 		case "show":
-			showCommand(catalog, io, argument, json);
+			await showCommand(catalog, io, argument, json);
+			break;
+		case "search":
+			searchCommand(catalog, io, argument, {
+				context: values.context,
+				json
+			});
 			break;
 		case "for":
-			forCommand(catalog, io, argument, json);
+			if (values.changed === void 0) await forCommand(catalog, io, argument, json);
+			else await forChangedCommand(catalog, io, values.changed, json);
 			break;
 		case "impact":
 			await impactCommand(catalog, io, argument, json);
 			break;
-		case "new": await newCommand(catalog, io, argument, values.prefix);
+		case "new":
+			await newCommand(catalog, io, argument, values.prefix);
+			break;
+		case "export": await exportCommand(catalog, io, argument, values.out);
 	}
 	return 0;
 }
@@ -643,7 +1014,8 @@ function parse(spec, args) {
 	} catch (error) {
 		throw new CliError(`${error.message}\nUsage: ${spec.usage}`, 2);
 	}
-	const expected = spec.argument === void 0 ? 0 : 1;
+	const replaced = spec.argumentUnless !== void 0 && parsed.values[spec.argumentUnless] !== void 0;
+	const expected = spec.argument === void 0 || replaced ? 0 : 1;
 	if (parsed.positionals.length < expected) throw new CliError(`Missing argument <${spec.argument}>. Usage: ${spec.usage}`, 2);
 	if (parsed.positionals.length > expected) throw new CliError(`Unexpected argument "${parsed.positionals[expected]}". Usage: ${spec.usage}`, 2);
 	return {