@possumtech/rummy 0.2.7 → 0.3.0

package/src/plugins/hedberg/normalize.js

@@ -19,6 +19,8 @@ const KNOWN_ATTRS = new Set([
 	"results",
 	"command",
 	"warn",
+	"summary",
+	"fidelity",
 ]);
 
 export function normalizeAttrs(attrs) {
@@ -37,5 +39,31 @@ export function normalizeAttrs(attrs) {
 		}
 	}
 	if ("preview" in out) out.preview = true;
+	// summary="..." is the description text, not a fidelity flag
+	if ("summary" in out && !out.summary) out.summary = true;
+	// file:// prefix — strip silently, bare paths are the convention
+	if (out.path?.startsWith("file://")) out.path = out.path.slice(7);
 	return out;
 }
+
+/**
+ * Parse JSON-style edit from body content.
+ * Accepts: {"search":"old","replace":"new"} and {search="old",replace="new"}
+ * Returns { search, replace } or null.
+ */
+export function parseJsonEdit(text) {
+	const trimmed = text.trim();
+	if (!trimmed.startsWith("{") || !/search/.test(trimmed)) return null;
+	try {
+		const json = JSON.parse(trimmed);
+		if (json.search != null)
+			return { search: json.search, replace: json.replace ?? "" };
+	} catch {
+		const searchMatch = trimmed.match(/search\s*=\s*"([^"]*)"/);
+		const replaceMatch = trimmed.match(/replace\s*=\s*"([^"]*)"/);
+		if (searchMatch) {
+			return { search: searchMatch[1], replace: replaceMatch?.[1] ?? "" };
+		}
+	}
+	return null;
+}

package/src/plugins/hedberg/patterns.js

@@ -1,4 +1,6 @@
-import { JSDOM } from "jsdom";
+import { DOMParser } from "@xmldom/xmldom";
+import picomatch from "picomatch";
+import xpath from "xpath";
 
 export const deterministic = true;
 
@@ -130,26 +132,7 @@ function detect(pattern) {
 
 // --- Compilation ---
 
-function globToRegex(glob) {
-	let result = "";
-	for (let i = 0; i < glob.length; i++) {
-		const c = glob[i];
-		if (c === "*") result += ".*";
-		else if (c === "?") result += ".";
-		else if (c === "[") {
-			const close = glob.indexOf("]", i + 1);
-			if (close === -1) {
-				result += "\\[";
-				continue;
-			}
-			result += glob.slice(i, close + 1);
-			i = close;
-		} else if (/[.+^${}()|\\]/.test(c)) {
-			result += `\\${c}`;
-		} else result += c;
-	}
-	return result;
-}
+// Glob matching delegated to picomatch (standard, battle-tested).
 
 function parseRegex(pattern) {
 	const lastSlash = pattern.lastIndexOf("/");
@@ -213,12 +196,28 @@ function compile(pattern) {
 	switch (type) {
 		case "literal":
 			return { type, pattern };
-		case "glob":
-			return {
-				type,
-				anchoredRe: new RegExp(`^${globToRegex(pattern)}$`),
-				searchRe: new RegExp(globToRegex(pattern)),
-			};
+		case "glob": {
+			const escaped = pattern.replace(/([()])/g, "\\$1");
+			// Scheme paths have no directory structure — * matches everything
+			const opts = escaped.includes("://")
+				? {
+						dot: true,
+						nobrace: true,
+						noextglob: true,
+						bash: false,
+						regex: true,
+					}
+				: { dot: true, nobrace: true, noextglob: true };
+
+			// For scheme paths, convert single * after :// to ** so it crosses "/"
+			const prepared = escaped.includes("://")
+				? escaped.replace(/:\/\/\*(?!\*)/, "://**")
+				: escaped;
+
+			const isMatch = picomatch(prepared, opts);
+			const picoRe = picomatch.makeRe(prepared, opts);
+			return { type, isMatch, searchRe: picoRe };
+		}
 		case "regex": {
 			const { body, flags } = parseRegex(pattern);
 			return {
@@ -250,11 +249,10 @@ function compile(pattern) {
 
 function evalXpath(expr, string) {
 	try {
-		const dom = new JSDOM(string, { contentType: "text/xml" });
-		const doc = dom.window.document;
-		const result = doc.evaluate(expr, doc, null, 0, null);
-		const node = result.iterateNext();
-		if (!node) return null;
+		const doc = new DOMParser().parseFromString(string, "text/xml");
+		const nodes = xpath.select(expr, doc);
+		if (!nodes || nodes.length === 0) return null;
+		const node = nodes[0];
 		return { match: node.textContent, node };
 	} catch {
 		return null;
@@ -332,7 +330,7 @@ export function hedmatch(pattern, string) {
 		case "literal":
 			return string === compiled.pattern;
 		case "glob":
-			return compiled.anchoredRe.test(string);
+			return compiled.isMatch(string);
 		case "regex":
 			return compiled.re.test(string);
 		case "sed":

package/src/plugins/hedberg/sed.js

@@ -5,14 +5,15 @@
  * - Flag extraction (g, i, m, s, v)
  */
 
-function splitSed(str) {
+function splitSed(str, delim) {
 	const parts = [];
 	let current = "";
+	const escaped = `\\${delim}`;
 	for (let i = 0; i < str.length; i++) {
 		if (str[i] === "\\" && i + 1 < str.length) {
 			current += str[i] + str[i + 1];
 			i++;
-		} else if (str[i] === "/") {
+		} else if (str[i] === delim) {
 			parts.push(current);
 			current = "";
 		} else {
@@ -20,26 +21,32 @@ function splitSed(str) {
 		}
 	}
 	parts.push(current);
-	return parts;
+	return { parts, escaped };
 }
 
 export function parseSed(input) {
-	if (!input.startsWith("s/")) return null;
+	// Sed allows any non-alphanumeric delimiter: s/old/new/, s|old|new|, s#old#new#
+	const match = input.match(/^s([^\w\s])/);
+	if (!match) return null;
 
+	const delim = match[1];
 	const blocks = [];
 	let remaining = input;
-	while (remaining.startsWith("s/")) {
-		const parts = splitSed(remaining.slice(2));
+	const prefix = `s${delim}`;
+
+	while (remaining.startsWith(prefix)) {
+		const { parts, escaped } = splitSed(remaining.slice(2), delim);
 		if (parts.length < 2) break;
 		const flags = (parts[2] || "").match(/^[gimsv]*/)?.[0] || "";
+		const unesc = (s) => s.replaceAll(escaped, delim);
 		blocks.push({
-			search: parts[0].replaceAll("\\/", "/"),
-			replace: parts[1].replaceAll("\\/", "/"),
+			search: unesc(parts[0]),
+			replace: unesc(parts[1]),
 			flags,
 			sed: true,
 		});
-		const rest = parts.slice(2).join("/");
-		const next = rest.indexOf("s/");
+		const rest = parts.slice(2).join(delim);
+		const next = rest.indexOf(prefix);
 		remaining = next >= 0 ? rest.slice(next) : "";
 	}
 

package/src/plugins/helpers.js

@@ -10,7 +10,7 @@ export async function storePatternResult(
 	path,
 	bodyFilter,
 	matches,
-	preview = false,
+	{ preview = false, loopId = null } = {},
 ) {
 	const slug = await store.slugPath(runId, scheme, path);
 	const filter = bodyFilter ? ` body="${bodyFilter}"` : "";
@@ -18,5 +18,5 @@ export async function storePatternResult(
 	const listing = matches.map((m) => `${m.path} (${m.tokens_full})`).join("\n");
 	const prefix = preview ? "PREVIEW " : "";
 	const body = `${prefix}${scheme} path="${path}"${filter}: ${matches.length} matched (${total} tokens)\n${listing}`;
-	await store.upsert(runId, turn, slug, body, "pattern");
+	await store.upsert(runId, turn, slug, body, 200, { loopId });
 }

package/src/plugins/index.js

@@ -1,9 +1,16 @@
+import { execSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { readdir, stat } from "node:fs/promises";
-import { basename, join } from "node:path";
+import { basename, isAbsolute, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import PluginContext from "../hooks/PluginContext.js";
 
+let globalPrefix;
+function getGlobalPrefix() {
+	globalPrefix ??= execSync("npm prefix -g", { encoding: "utf8" }).trim();
+	return globalPrefix;
+}
+
 const instances = new Map();
 
 /**
@@ -23,10 +30,6 @@ export async function registerPlugins(dirs = [], hooks) {
 const AUDIT_SCHEMES = [
 	"instructions",
 	"system",
-	"prompt",
-	"ask",
-	"act",
-	"progress",
 	"reasoning",
 	"model",
 	"error",
@@ -35,20 +38,26 @@ const AUDIT_SCHEMES = [
 	"content",
 ];
 
+const PROMPT_SCHEMES = ["prompt", "progress"];
+
 /**
  * After DB is ready, inject db and store into all PluginContext instances,
  * upsert declared schemes, and bootstrap audit schemes.
  */
 export async function initPlugins(db, store, hooks) {
 	for (const name of AUDIT_SCHEMES) {
-		const scheme = {
+		await db.upsert_scheme.run({
 			name,
-			fidelity: ["ask", "act", "progress"].includes(name) ? "full" : "null",
-			model_visible: ["ask", "act", "progress"].includes(name) ? 1 : 0,
-			valid_states: JSON.stringify(["info"]),
+			model_visible: 0,
 			category: "audit",
-		};
-		await db.upsert_scheme.run(scheme);
+		});
+	}
+	for (const name of PROMPT_SCHEMES) {
+		await db.upsert_scheme.run({
+			name,
+			model_visible: 1,
+			category: "prompt",
+		});
 	}
 
 	for (const ctx of instances.values()) {
@@ -66,25 +75,37 @@ export async function initPlugins(db, store, hooks) {
 			for (const s of ctx.schemes) registered.add(s.name);
 		}
 		for (const name of AUDIT_SCHEMES) registered.add(name);
+		for (const name of PROMPT_SCHEMES) registered.add(name);
 
 		for (const toolName of hooks.tools.names) {
 			if (registered.has(toolName)) continue;
 			await db.upsert_scheme.run({
 				name: toolName,
-				fidelity: "full",
 				model_visible: 1,
-				valid_states: JSON.stringify([
-					"full",
-					"proposed",
-					"pass",
-					"rejected",
-					"error",
-					"info",
-				]),
-				category: "result",
+				category: "logging",
 			});
 		}
 	}
+
+	if (store) store.loadSchemes(db);
+}
+
+function resolvePlugin(packageName) {
+	// Check local node_modules first, then global
+	const localDir = join(process.cwd(), "node_modules", packageName);
+	if (existsSync(join(localDir, "package.json"))) return localDir;
+	const globalDir = join(getGlobalPrefix(), "lib", "node_modules", packageName);
+	if (existsSync(join(globalDir, "package.json"))) return globalDir;
+	throw new Error(`Package '${packageName}' not found locally or globally`);
+}
+
+async function importPlugin(packageName) {
+	const dir = resolvePlugin(packageName);
+	const pkg = JSON.parse(
+		(await import("node:fs")).readFileSync(join(dir, "package.json"), "utf8"),
+	);
+	const entry = pkg.exports?.["."] || pkg.main || "index.js";
+	return import(pathToFileURL(join(dir, entry)).href);
 }
 
 async function loadEnvPlugins(hooks) {
@@ -92,9 +113,20 @@ async function loadEnvPlugins(hooks) {
 		if (!key.startsWith("RUMMY_PLUGIN_") || !value) continue;
 		const name = key.replace("RUMMY_PLUGIN_", "").toLowerCase();
 		try {
-			const { default: Plugin } = await import(value);
+			const importPromise = isAbsolute(value)
+				? importAbsolute(value)
+				: importPlugin(value);
+			const { default: Plugin } = await withTimeout(
+				importPromise,
+				PLUGIN_LOAD_TIMEOUT,
+				`Plugin import timed out: ${value}`,
+			);
 			if (typeof Plugin?.register === "function") {
-				await Plugin.register(hooks);
+				await withTimeout(
+					Plugin.register(hooks),
+					PLUGIN_LOAD_TIMEOUT,
+					`Plugin register timed out: ${value}`,
+				);
 			} else if (typeof Plugin === "function") {
 				const ctx = new PluginContext(name, hooks);
 				new Plugin(ctx);
@@ -107,6 +139,19 @@ async function loadEnvPlugins(hooks) {
 	}
 }
 
+async function importAbsolute(dir) {
+	const pkgPath = join(dir, "package.json");
+	if (!existsSync(pkgPath)) {
+		// Bare .js file
+		return import(pathToFileURL(dir).href);
+	}
+	const pkg = JSON.parse(
+		(await import("node:fs")).readFileSync(pkgPath, "utf8"),
+	);
+	const entry = pkg.exports?.["."] || pkg.main || "index.js";
+	return import(pathToFileURL(join(dir, entry)).href);
+}
+
 async function scanDir(dir, hooks, isRoot = false) {
 	if (!existsSync(dir)) return;
 
@@ -154,18 +199,29 @@ async function scanDir(dir, hooks, isRoot = false) {
 				await loadPlugin(fullPath, hooks);
 			}
 		} else if (stats.isDirectory()) {
+			if (existsSync(join(fullPath, "DISABLED"))) continue;
 			await scanDir(fullPath, hooks, false);
 		}
 	}
 }
 
+const PLUGIN_LOAD_TIMEOUT = 10000;
+
 async function loadPlugin(filePath, hooks) {
 	try {
 		const url = pathToFileURL(filePath).href;
-		const { default: Plugin } = await import(url);
+		const { default: Plugin } = await withTimeout(
+			import(url),
+			PLUGIN_LOAD_TIMEOUT,
+			`Plugin import timed out: ${filePath}`,
+		);
 
 		if (typeof Plugin?.register === "function") {
-			await Plugin.register(hooks);
+			await withTimeout(
+				Plugin.register(hooks),
+				PLUGIN_LOAD_TIMEOUT,
+				`Plugin register timed out: ${filePath}`,
+			);
 		} else if (typeof Plugin === "function") {
 			const name = basename(filePath, ".js");
 			const ctx = new PluginContext(name, hooks);
@@ -173,8 +229,17 @@ async function loadPlugin(filePath, hooks) {
 			instances.set(name, ctx);
 		}
 	} catch (err) {
-		if (process.env.RUMMY_DEBUG === "true") {
-			console.error(`[RUMMY] Plugin load failed at ${filePath}:`, err);
-		}
+		console.warn(
+			`[RUMMY] Plugin load failed: ${basename(filePath)} — ${err.message}`,
+		);
 	}
 }
+
+function withTimeout(promise, ms, message) {
+	return Promise.race([
+		promise,
+		new Promise((_, reject) =>
+			setTimeout(() => reject(new Error(message)), ms),
+		),
+	]);
+}

package/src/plugins/instructions/README.md

@@ -4,8 +4,12 @@ Projects the system prompt instructions into model context.
 
 ## Registration
 
-- **Projection**: `onProject("instructions", ...)` — no tool handler.
+- **View**: `full` — renders preamble + tool docs + persona.
+- **Event**: `turn.started` — writes `instructions://system` entry.
+- **Filter**: `instructions.toolDocs` — gathers docs from all tool plugins.
 
 ## Behavior
 
-Replaces the `[%TOOLS%]` placeholder in the prompt body with the `tools` attribute. Appends tool descriptions and persona text when present in attributes.
+Replaces the `[%TOOLS%]` placeholder in the preamble with the active
+tool list. Appends tool descriptions gathered via the `toolDocs` filter
+and persona text when present in attributes.

package/src/plugins/instructions/instructions.js

@@ -17,20 +17,36 @@ export default class Instructions {
 	async onTurnStarted({ rummy }) {
 		const { entries: store, sequence: turn, runId } = rummy;
 		const runRow = await rummy.db.get_run_by_id.get({ id: runId });
-		await store.upsert(runId, turn, "instructions://system", "", "info", {
-			attributes: { persona: runRow?.persona || null },
+		const toolSet = rummy.toolSet
+			? [...rummy.toolSet]
+			: this.#core.hooks.tools.names;
+		await store.upsert(runId, turn, "instructions://system", "", 200, {
+			attributes: {
+				persona: runRow?.persona || null,
+				toolSet,
+			},
 		});
 	}
 
 	async full(entry) {
 		const attrs = entry.attributes;
-		const tools = this.#core.hooks.tools.names.join(", ");
+		const activeTools = attrs.toolSet
+			? new Set(attrs.toolSet)
+			: new Set(this.#core.hooks.tools.names);
+		const sorted = this.#core.hooks.tools.names.filter((n) =>
+			activeTools.has(n),
+		);
+		const tools = sorted.join(", ");
 		let prompt = preamble.replace("[%TOOLS%]", tools);
 		const toolDocs = await this.#core.hooks.instructions.toolDocs.filter(
-			"",
 			{},
+			{ toolSet: activeTools },
 		);
-		if (toolDocs) prompt += `\n\n${toolDocs}`;
+		const docsText = sorted
+			.filter((key) => toolDocs[key])
+			.map((key) => toolDocs[key])
+			.join("\n\n");
+		if (docsText) prompt += `\n\n${docsText}`;
 		if (attrs.persona) prompt += `\n\n## Persona\n\n${attrs.persona}`;
 		return prompt;
 	}

package/src/plugins/instructions/preamble.md

@@ -1,12 +1,16 @@
-You are an assistant. You gather information, then either answer questions or take action.
+You are an assistant. YOU MUST gather information, then YOU MAY either answer questions or take action.
 
 # Response Rules
 
-* You must register unknowns with <unknown>(thing I don't know yet)</unknown> before acting.
-* Save known information with <known>(thing I know now)</known>.
-* Respond with Tool Commands. You may use multiple tools in your response.
+Required: YOU MUST respond with Tool Commands in the XML format. YOU MAY use multiple tools in your response.
+Optional: YOU MAY think in an optional <think></think> tag before using any other Tool Commands.
+Required: YOU MUST register all unknowns with <unknown>(specific thing I need to learn)</unknown>.
+Required: YOU MUST register all new information, decisions, and plans with <known>(specific information, ideas, or plans)</known>.
+Required: YOU MUST conclude every turn with EITHER <update/> if still working OR <summarize/> if done. Never both.
+Required: Path and summary information is approximate. YOU MUST use <get> to verify before acting on summarized content.
+Info: When information conflicts, later turns are more likely to be relevant and correct than earlier turns.
+Info: Your context is limited but your storage is not. Organize and categorize your information, ideas, plans, and history to optimize your context.
 
 # Tool Commands
 
 Tools: [%TOOLS%]
-Required: Either `<update/>` if still working or `<summarize/>` if done. Never both.

package/src/plugins/known/README.md

@@ -1,18 +1,21 @@
 # known
 
-Writes arbitrary key/value entries into the store at full fidelity.
+Writes knowledge entries into the store at full fidelity.
 
 ## Registration
 
 - **Tool**: `known`
-- **Modes**: ask, act
-- **Category**: act
-- **Handler**: Upserts the entry body at the target path with `full` state.
+- **Category**: `data`
+- **Handler**: Upserts the entry body at the target path with status 200.
+- **Filter**: `assembly.system` at priority 100 — renders `<knowns>` section.
 
 ## Projection
 
-Shows `known {path}` followed by the entry body.
+Shows `# known {path}` followed by the entry body.
 
-## Behavior
+## Assembly
 
-The target path defaults to `entry.resultPath` but can be overridden via `attrs.path`. Used by the model to persist structured notes and context.
+Filters turn_context rows where `category === "data"`. Renders all
+data entries (files, knowledge, skills, URLs) into the `<knowns>` section
+of the system message. Third-party plugins that register with
+`category: "data"` automatically appear here.

package/src/plugins/known/known.js

@@ -1,28 +1,24 @@
-import { readFileSync } from "node:fs";
+import docs from "./knownDoc.js";
 
 export default class Known {
 	#core;
 
 	constructor(core) {
 		this.#core = core;
-		core.registerScheme({
-			fidelity: "turn",
-			validStates: ["full", "stored"],
-			category: "knowledge",
-		});
+		core.registerScheme({ category: "data" });
 		core.on("handler", this.handler.bind(this));
 		core.on("full", this.full.bind(this));
 		core.filter("assembly.system", this.assembleKnown.bind(this), 100);
-		const docs = readFileSync(new URL("./docs.md", import.meta.url), "utf8");
-		core.filter("instructions.toolDocs", async (content) =>
-			content ? `${content}\n\n${docs}` : docs,
-		);
+		core.filter("instructions.toolDocs", async (docsMap) => {
+			docsMap.known = docs;
+			return docsMap;
+		});
 	}
 
 	async handler(entry, rummy) {
 		const { entries: store, sequence: turn, runId } = rummy;
 		const target = entry.attributes.path || entry.resultPath;
-		await store.upsert(runId, turn, target, entry.body, "full");
+		await store.upsert(runId, turn, target, entry.body, 200);
 	}
 
 	full(entry) {
@@ -30,28 +26,42 @@ export default class Known {
 	}
 
 	async assembleKnown(content, ctx) {
-		const entries = ctx.rows.filter(
-			(r) =>
-				r.category === "file" ||
-				r.category === "file_index" ||
-				r.category === "known" ||
-				r.category === "known_index",
-		);
+		const entries = ctx.rows.filter((r) => r.category === "data");
 		if (entries.length === 0) return content;
 
 		// Rows arrive pre-sorted by SQL: skill → index → summary → full, then by recency
-		const lines = entries.map((e) => renderKnownTag(e));
+		const demotedSet = new Set(ctx.demoted || []);
+		const panic = ctx.type === "panic";
+		const lines = entries.map((e) => renderKnownTag(e, demotedSet, panic));
 		return `${content}\n\n<knowns>\n${lines.join("\n")}\n</knowns>`;
 	}
 }
 
-function renderKnownTag(entry) {
+function renderKnownTag(entry, demotedSet, panic = false) {
+	const tag = entry.scheme || "file";
+	const turn = entry.source_turn ? ` turn="${entry.source_turn}"` : "";
 	const tokens = entry.tokens ? ` tokens="${entry.tokens}"` : "";
-	const state = entry.state ? ` state="${entry.state}"` : "";
+	const status = entry.status ? ` status="${entry.status}"` : "";
+	const fidelity = entry.fidelity ? ` fidelity="${entry.fidelity}"` : "";
+	const flag = demotedSet?.has(entry.path) ? " demoted" : "";
+
+	// Panic mode: index-only view so context fits in LLM window
+	if (panic) {
+		return `<${tag} path="${entry.path}"${turn}${fidelity}${tokens}/>`;
+	}
+
+	const attrs =
+		typeof entry.attributes === "string"
+			? JSON.parse(entry.attributes)
+			: entry.attributes;
+	const summary =
+		typeof attrs?.summary === "string"
+			? ` summary="${attrs.summary.slice(0, 80)}"`
+			: "";
 
 	if (entry.body) {
-		return `<known path="${entry.path}"${state}${tokens}>${entry.body}</known>`;
+		return `<${tag} path="${entry.path}"${turn}${status}${fidelity}${summary}${tokens}${flag}>${entry.body}</${tag}>`;
 	}
 
-	return `<known path="${entry.path}"${state}${tokens}/>`;
+	return `<${tag} path="${entry.path}"${turn}${status}${fidelity}${summary}${tokens}${flag}/>`;
 }

package/src/plugins/known/knownDoc.js

@@ -0,0 +1,33 @@
+// Tool doc for <known/>. Each entry: [text, rationale].
+// Text goes to the model. Rationale stays in source.
+// Changing ANY line requires reading ALL rationales first.
+const LINES = [
+	// --- Syntax: body = the information to save
+	[
+		"## <known>[specific information, ideas, or plans]</known> - Sort and save what you learn for later recall",
+	],
+	// --- Examples: summary-with-keywords first (teaches the right pattern)
+	[
+		'Example: <known summary="hedberg,comedian,death,2005">Mitch Hedberg died on March 30, 2005</known>',
+		"Primary pattern: comma-separated keywords in summary. Path auto-generated from summary as known://hedberg/comedian/death/2005. Keywords become searchable path segments.",
+	],
+	[
+		'Example: <known path="known://people/rumsfeld" summary="defense,secretary,born,1932">Donald Rumsfeld was born in 1932 and served as Secretary of Defense</known>',
+		"Explicit path form: slashed path=category/key, summary=keywords. For when the model wants direct control over taxonomy.",
+	],
+	// --- Lifecycle
+	[
+		'* Recall with <get path="known://people/*">keyword</get>',
+		"Cross-tool lifecycle: glob by category, filter by keyword. Matches the slashed path convention.",
+	],
+	[
+		"* `summary` keywords survive compression — write keywords you'll search for later",
+		"Teaches WHY summaries matter. Keywords become the path AND the compressed view.",
+	],
+	[
+		"* YOU MUST sort and save all new information, ideas, and plans in their own <known> entries",
+		"Critical behavioral constraint. 'new' prevents re-saving known facts.",
+	],
+];
+
+export default LINES.map(([text]) => text).join("\n");

package/src/plugins/mv/README.md

@@ -5,9 +5,8 @@ Moves (renames) an entry from one path to another within the K/V store.
 ## Registration
 
 - **Tool**: `mv`
-- **Modes**: ask, act
-- **Category**: act
-- **Handler**: Reads source body, writes to destination, removes source. K/V destinations resolve immediately (`pass`); file destinations produce a `proposed` entry.
+- **Category**: `logging`
+- **Handler**: Reads source body, writes to destination, removes source. Scheme destinations resolve immediately (status 200); file destinations produce status 202 (proposed).
 
 ## Projection
 
@@ -15,4 +14,6 @@ Shows `mv {from} {to}`.
 
 ## Behavior
 
-Warns if the destination already exists and will be overwritten. Uses `KnownStore.scheme()` to determine K/V vs file paths. Source entry is removed on successful K/V moves.
+Warns if the destination already exists and will be overwritten. Uses
+`KnownStore.scheme()` to determine scheme vs file paths. Source entry
+is removed on successful scheme moves.