isorite 0.15.0 → 0.16.0

package/dist/main.js

@@ -619,6 +619,39 @@ function splitFrontmatter(source) {
 	if (typeof meta !== "object" || Array.isArray(meta)) throw new FrontmatterError("frontmatter is not a mapping");
 	return [meta, body.replace(/^\n+/, "")];
 }
+/** A frontmatter line `key: value` at the top level whose value the YAML parser refused, such as an unquoted
+*  colon (`title: Foo: bar`) or a value starting with a backtick, `%` or `@`: agents write these often. The value
+*  is put in double quotes, for those lines alone, and the text kept as it was otherwise. Null when the
+*  frontmatter reads already, or the quotes would not make it read (an unclosed list, say): the note is left as written. */
+function repairFrontmatter(source) {
+	try {
+		if (frontmatterText(source)[0] === null) return null;
+	} catch {
+		return null;
+	}
+	const bom = source.startsWith(BOM$1) ? BOM$1 : "", lines = source.slice(bom.length).split("\n");
+	let close = 1;
+	while (rstrip(lines[close]) !== "---") close++;
+	const raw = lines.slice(1, close).join("\n") + "\n";
+	const bad = /* @__PURE__ */ new Set();
+	for (const e of parseYaml(raw).errors) {
+		const at = e.linePos?.[0]?.line;
+		if (at) bad.add(at);
+	}
+	const fixed = [];
+	for (const n of bad) {
+		const m = /^([A-Za-z_][\w .-]*):[ \t]+(\S.*?)[ \t]*(\r?)$/.exec(lines[n] ?? "");
+		if (!m || /^["'\[{|>&*!#]/.test(m[2])) continue;
+		lines[n] = `${m[1]}: ${JSON.stringify(m[2])}${m[3]}`;
+		fixed.push(m[1]);
+	}
+	if (!fixed.length) return null;
+	if (parseYaml(lines.slice(1, close).join("\n") + "\n").errors.length) return null;
+	return {
+		text: bom + lines.join("\n"),
+		fixed
+	};
+}
 /** Serialise frontmatter, keeping key order. */
 function dumpFrontmatter(meta) {
 	return stringify(meta, {
@@ -885,16 +918,19 @@ function embedFor(id, ids) {
 	for (const other of ids) if (other.split("/").at(-1) === name) shared++;
 	return `[[!${shared > 1 ? id : name}]]`;
 }
-/** A code link's file and lines, or null when it is not one, or names a path outside the repository. */
+/** A code link's file and, after `#`, its lines (`L40-L52`) or the symbol it names (`leapfrog`, `Body.step`: a
+*  function, method or class, found by its name wherever it has moved to, M29). Null when it is not one, or names a
+*  path outside the repository. */
 function codeTarget(href) {
-	const m = /^code:([^#?]+)(?:#L(\d+)(?:-L?(\d+))?)?$/.exec(href.trim());
+	const m = /^code:([^#?]+)(?:#(?:L(\d+)(?:-L?(\d+))?|([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)))?$/.exec(href.trim());
 	if (!m) return null;
 	const path = decodeURIComponent(m[1]).replace(/^\.?\/+/, "");
 	if (!path || path.split("/").some((p) => p === ".." || !p)) return null;
 	return {
 		path,
 		...m[2] ? { line: Number(m[2]) } : {},
-		...m[3] ? { end: Number(m[3]) } : {}
+		...m[3] ? { end: Number(m[3]) } : {},
+		...m[4] ? { symbol: m[4] } : {}
 	};
 }
 /** A note's links out of the base, in order, each once. */
@@ -922,14 +958,20 @@ function outwardLinks(body) {
 	for (const { href, embed, alt } of citeRefs(body)) {
 		if (!embed || seen.has(href)) continue;
 		const c = codeTarget(href);
-		if (!c || !pictureType(c.path)) continue;
-		out.push({
+		if (!c) continue;
+		if (pictureType(c.path)) out.push({
 			kind: "code",
 			href,
 			text: alt || c.path.split("/").at(-1),
 			path: c.path,
 			picture: true
 		});
+		else out.push({
+			kind: "code",
+			href,
+			text: alt || c.symbol || c.path.split("/").at(-1),
+			...c
+		});
 		seen.add(href);
 	}
 	return out;
@@ -2197,6 +2239,176 @@ function mapModel(base) {
 	};
 }
 //#endregion
+//#region packages/core/src/symbol.ts
+const PY = /* @__PURE__ */ new Set(["py", "pyi"]);
+const BRACE = /* @__PURE__ */ new Set([
+	"js",
+	"jsx",
+	"mjs",
+	"cjs",
+	"ts",
+	"tsx",
+	"mts",
+	"cts",
+	"go",
+	"rs",
+	"java",
+	"kt",
+	"kts",
+	"cs",
+	"c",
+	"h",
+	"cc",
+	"cpp",
+	"cxx",
+	"hpp",
+	"swift",
+	"php",
+	"scala",
+	"dart",
+	"zig",
+	"svelte",
+	"vue"
+]);
+/** Whether symbols can be found in a file of this name. */
+function hasSymbols(path) {
+	const ext = path.split(".").at(-1).toLowerCase();
+	return PY.has(ext) || BRACE.has(ext);
+}
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** The lines of `path`'s symbol `name` (`Class.method` for one inside another) in `text`, or null. */
+function findSymbol(text, path, name) {
+	const ext = path.split(".").at(-1).toLowerCase();
+	const lines = text.split(/\r?\n/);
+	const parts = name.split(".").filter(Boolean);
+	if (!parts.length || !PY.has(ext) && !BRACE.has(ext)) return null;
+	let from = 0, to = lines.length - 1, span = null;
+	for (const part of parts) {
+		const found = PY.has(ext) ? pyFind(lines, part, from, to) : braceFind(lines, part, from, to);
+		if (!found) return null;
+		span = found;
+		from = found.start;
+		to = found.end - 1;
+	}
+	return span;
+}
+function pyFind(lines, name, from, to) {
+	const re = new RegExp(`^(\\s*)(?:async\\s+)?(?:def|class)\\s+${esc(name)}\\b`);
+	const at = [];
+	for (let i = from; i <= to; i++) {
+		const m = re.exec(lines[i]);
+		if (m) at.push({
+			i,
+			indent: m[1].length
+		});
+	}
+	const shallow = Math.min(...at.map((a) => a.indent), Infinity);
+	const top = from === 0 && to === lines.length - 1;
+	const here = at.filter((a) => a.indent === shallow && (!top || shallow === 0));
+	let first = null, count = 0;
+	for (const { i, indent } of here) {
+		count++;
+		if (first) continue;
+		let open = i;
+		while (open < lines.length - 1 && !/:\s*(#.*)?$/.test(lines[open])) open++;
+		let end = open;
+		for (let j = open + 1; j < lines.length; j++) {
+			const l = lines[j];
+			if (!l.trim()) continue;
+			if (l.length - l.trimStart().length <= indent) break;
+			end = j;
+		}
+		let start = i;
+		while (start > 0 && new RegExp(`^\\s{${indent}}@`).test(lines[start - 1])) start--;
+		first = {
+			start: start + 1,
+			end: Math.min(end, to) + 1,
+			count: 1
+		};
+	}
+	return first ? {
+		...first,
+		count
+	} : null;
+}
+const DECL = (n) => [
+	new RegExp(`\\b(?:function\\*?|class|interface|enum|struct|trait|union|impl|fn|func|def|type|record|namespace|object|module)\\s+(?:<[^>]*>\\s*)?(?:\\([^)]*\\)\\s*)?${n}\\b`),
+	new RegExp(`\\b(?:const|let|var|val)\\s+${n}\\s*(?::[^=]+)?=\\s*(?:async\\s*)?(?:function\\b|\\([^)]*\\)\\s*(?::[^=]+)?=>|\\w+\\s*=>)`),
+	new RegExp(`^\\s*(?:(?:public|private|protected|internal|static|async|override|final|abstract|export|default|get|set|pub|unsafe|virtual|readonly|suspend|inline|open)\\s+)*(?:[\\w<>\\[\\],.?*&:]+\\s+)?\\*?${n}\\s*(?:<[^>]*>)?\\(`)
+];
+function braceFind(lines, name, from, to) {
+	const res = DECL(esc(name));
+	let first = null, count = 0;
+	let i = from;
+	while (i <= to) {
+		const line = lines[i];
+		if (/^\s*(\/\/|\*|\/\*|#)/.test(line) || !res.some((re) => re.test(line))) {
+			i++;
+			continue;
+		}
+		const body = openBrace(lines, i, to);
+		if (!body) {
+			i++;
+			continue;
+		}
+		count++;
+		const end = closeBrace(lines, body.line, body.col);
+		if (!first) {
+			let start = i;
+			while (start > 0 && /^\s*(@|#\[|\/\/|\/\*|\*)/.test(lines[start - 1])) start--;
+			first = {
+				start: start + 1,
+				end: Math.min(end, to) + 1,
+				count: 1
+			};
+		}
+		i = end + 1;
+	}
+	return first ? {
+		...first,
+		count
+	} : null;
+}
+/** The first `{` from line `i`, if it comes before a `;` (within a few lines, the signature). */
+function openBrace(lines, i, to) {
+	for (let j = i; j <= Math.min(to, i + 8); j++) {
+		const l = stripStrings(lines[j]);
+		const b = l.indexOf("{"), s = l.indexOf(";");
+		if (b >= 0 && (s < 0 || b < s)) return {
+			line: j,
+			col: b
+		};
+		if (s >= 0) return null;
+	}
+	return null;
+}
+/** Blank out what is inside quotes and after `//`, so braces there are not counted. */
+function stripStrings(l) {
+	return l.replace(/\/\/.*$/, (m) => " ".repeat(m.length)).replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\]|\\.)*`/g, (m) => " ".repeat(m.length));
+}
+/** The line holding the `}` that closes the `{` at (line, col). The end of the file when it does not. */
+function closeBrace(lines, line, col) {
+	let depth = 0, block = false;
+	for (let j = line; j < lines.length; j++) {
+		let l = stripStrings(lines[j]);
+		if (block) {
+			const e = l.indexOf("*/");
+			if (e < 0) continue;
+			l = " ".repeat(e + 2) + l.slice(e + 2);
+			block = false;
+		}
+		l = l.replace(/\/\*.*?\*\//g, (m) => " ".repeat(m.length));
+		const o = l.indexOf("/*");
+		if (o >= 0) {
+			block = true;
+			l = l.slice(0, o);
+		}
+		for (let k = j === line ? col : 0; k < l.length; k++) if (l[k] === "{") depth++;
+		else if (l[k] === "}" && --depth === 0) return j;
+	}
+	return lines.length - 1;
+}
+//#endregion
 //#region packages/core/src/node.ts
 /** Every file and folder under `root`, Markdown with its text. */
 function readFolder(root) {
@@ -2231,6 +2443,32 @@ function loadBundle(root) {
 	return Bundle.fromFiles(readFolder(root));
 }
 //#endregion
+//#region packages/server/src/term.ts
+const wrap = (open, close) => (text) => colour() ? `\x1b[${open}m${text}\x1b[${close}m` : text;
+/** Whether to paint: asked each time, so a test or a caller can change the environment. */
+function colour(env = process.env, tty = Boolean(process.stdout.isTTY)) {
+	if (env.NO_COLOR) return false;
+	if (env.FORCE_COLOR !== void 0) return env.FORCE_COLOR !== "0" && env.FORCE_COLOR !== "false";
+	return tty && env.TERM !== "dumb";
+}
+const bold = wrap(1, 22);
+const dim = wrap(2, 22);
+const red = wrap(31, 39);
+const green = wrap(32, 39);
+const yellow = wrap(33, 39);
+/** A help text with its commands in bold and what they say dimmed: a line `  isorite word …  said` and its continuations. */
+function helpText(text) {
+	if (!colour()) return text;
+	return text.split("\n").map((line, i) => {
+		if (i === 0) return bold(line);
+		if (/^ {20,}\S/.test(line)) return dim(line);
+		const m = /^(  isorite(?: [a-z-]+)?)( .*?)(\s{2,})(\S.*)$/.exec(line);
+		if (m) return `${bold(m[1])}${m[2]}${m[3]}${dim(m[4])}`;
+		const c = /^(  isorite(?: [a-z-]+)?)(.*)$/.exec(line);
+		return c ? `${bold(c[1])}${c[2]}` : line;
+	}).join("\n");
+}
+//#endregion
 //#region packages/server/src/config.ts
 const configPath = (env = process.env) => join(env.XDG_CONFIG_HOME || join(homedir(), ".config"), "isorite", "config.toml");
 const DEVICE$1 = /^[a-z0-9]{4,16}$/;
@@ -3233,6 +3471,14 @@ const ISORITE = `# Their knowledge base
   together. A problem has no steps inside it.
 - Files beside the notes that are not notes (data, documents, pictures,
   artifacts) are linked as any note is: [runs](/simulation/runs.csv).
+- Code in their repository is linked as [the step](code:sim/step.py#leapfrog):
+  the path from the repository's root, then a name (\`#leapfrog\`, or
+  \`#Class.method\`) or lines (\`#L40-L52\`). Prefer a name: it still finds the
+  code when it moves. Look in the file for the name before you write it; a name
+  that is not there marks the link broken. \`![the step](code:sim/step.py#leapfrog)\`
+  shows that code in the note, where it is read.
+- Frontmatter is YAML: put a value in quotes when it holds a colon, as
+  \`title: "Gauss: Bonnet"\` and \`description: "Why: the proof"\`.
 - Every change you make is marked as yours, in the note's history, and they
   can undo it.
 
@@ -3931,7 +4177,9 @@ var Engine = class Engine {
 			for (const c of b.concepts.values()) for (const o of c.outward) {
 				if (o.kind !== "code") continue;
 				const k = o.path.lastIndexOf("/");
-				if (!(await names(k < 0 ? "" : o.path.slice(0, k))).has(o.path.slice(k + 1))) broken.set(c.id, [...broken.get(c.id) ?? [], o.href]);
+				let gone = !(await names(k < 0 ? "" : o.path.slice(0, k))).has(o.path.slice(k + 1));
+				if (!gone && o.symbol) gone = (await this.code(o.href)).state === "no-symbol";
+				if (gone) broken.set(c.id, [...broken.get(c.id) ?? [], o.href]);
 			}
 		}
 		this.codeCheck = {
@@ -4307,6 +4555,25 @@ var Engine = class Engine {
 	createNote(id, text) {
 		return this.one(() => this.put(id, text, null));
 	}
+	async makeFolder(path) {
+		path = path.trim().replace(/^\/+|\/+$/g, "");
+		if (!inBase(path)) throw new EngineError("only a folder of the base is made here");
+		checkNoteId(path);
+		if (!this.opts.notes.mkdir) throw new EngineError("an empty folder can't be made here");
+		if (this.files.has(`${path}.md`)) throw new EngineError(`there is a note at ${path} already`, 409);
+		await this.one(async () => {
+			await this.opts.notes.mkdir(path);
+			const parts = path.split("/");
+			for (let i = 1; i <= parts.length; i++) {
+				const p = parts.slice(0, i).join("/");
+				if (!this.files.has(p)) this.files.set(p, {
+					path: p,
+					dir: true
+				});
+			}
+			this.built = this.index = null;
+		});
+	}
 	/** `who` is you unless Iso moves it, in Write mode. */
 	async moveNote(id, to, base, who = "you") {
 		to = to.trim().replace(/^\/+|\/+$/g, "").replace(/\.md$/, "");
@@ -4451,6 +4718,63 @@ var Engine = class Engine {
 			version: sha256(bytes).slice(0, 16)
 		};
 	}
+	/** The code a code link names (M29): its symbol's lines, or the lines it gives, or the file's start. A symbol is
+	*  found by its name in the file as it is now, so the link holds where the code has moved. */
+	async code(href) {
+		const target = codeTarget(href);
+		if (!target) throw new EngineError("not a code link", 400);
+		const { path, symbol } = target, where = await this.repositoryOfBase();
+		const files = where ? this.opts.repository?.(where) ?? null : null;
+		if (!files) return {
+			state: "no-repository",
+			path,
+			...symbol ? { symbol } : {}
+		};
+		const bytes = await files.readBytes(path);
+		if (!bytes) return {
+			state: "no-file",
+			path,
+			...symbol ? { symbol } : {}
+		};
+		if (bytes.length > 2e6) return {
+			state: "too-large",
+			path
+		};
+		const lines = new TextDecoder().decode(bytes).split(/\r?\n/);
+		if (lines.at(-1) === "") lines.pop();
+		let start = target.line ?? 1, end = target.end ?? target.line ?? lines.length, count;
+		if (symbol) {
+			if (!hasSymbols(path)) return {
+				state: "unsupported",
+				path,
+				symbol
+			};
+			const found = findSymbol(lines.join("\n"), path, symbol);
+			if (!found) return {
+				state: "no-symbol",
+				path,
+				symbol
+			};
+			({start, end, count} = found);
+		}
+		end = Math.min(Math.max(end, start), lines.length);
+		if (start > lines.length) return {
+			state: "no-symbol",
+			path
+		};
+		const shown = Math.min(end, start + 120 - 1);
+		return {
+			state: "ok",
+			path,
+			...symbol ? { symbol } : {},
+			start,
+			end,
+			total: lines.length,
+			text: lines.slice(start - 1, shown).join("\n"),
+			...shown < end ? { more: true } : {},
+			...count && count > 1 ? { count } : {}
+		};
+	}
 	/** What was read of each picture, kept while its size and time are the same. */
 	pictureCache = /* @__PURE__ */ new Map();
 	/** Every picture in the notes (M22), found afresh: one put in the folder by hand since the base was opened is
@@ -4556,6 +4880,7 @@ var Engine = class Engine {
 	async put(id, text, base, why = "edit", extra = {}, who = "you") {
 		const { files, path } = this.where(id);
 		if (text.length > 2e6) throw new EngineError("note too large", 413);
+		if (who !== "you" && path.endsWith(".md")) text = repairFrontmatter(text)?.text ?? text;
 		const now = await files.read(path);
 		if (base === null && now !== null) throw new EngineError(`there is already a note at ${id}`, 409);
 		if (base !== null && now === null) throw new Conflict(`${id} is gone`, null);
@@ -4947,6 +5272,8 @@ var MemoryFiles = class {
 	files = /* @__PURE__ */ new Map();
 	/** Files held as bytes (pictures), apart from text. */
 	bytes = /* @__PURE__ */ new Map();
+	/** Folders made empty (M31). */
+	folders = /* @__PURE__ */ new Set();
 	constructor(files = {}) {
 		for (const [path, text] of Object.entries(files)) this.files.set(path, text);
 	}
@@ -4971,10 +5298,17 @@ var MemoryFiles = class {
 		this.files.delete(path);
 		this.bytes.delete(path);
 	}
+	async mkdir(dir) {
+		this.folders.add(dir);
+	}
 	async list(dir) {
 		const prefix = dir ? dir + "/" : "";
 		const found = /* @__PURE__ */ new Map();
-		for (const path of [...this.files.keys(), ...this.bytes.keys()]) {
+		for (const path of [
+			...this.files.keys(),
+			...this.bytes.keys(),
+			...[...this.folders].map((f) => f + "/")
+		]) {
 			if (!path.startsWith(prefix)) continue;
 			const rest = path.slice(prefix.length), cut = rest.indexOf("/");
 			if (cut >= 0) {
@@ -6155,7 +6489,7 @@ var AcpFollower = class {
 };
 //#endregion
 //#region packages/server/src/version.ts
-const VERSION = "0.15.0";
+const VERSION = "0.16.0";
 //#endregion
 //#region packages/server/src/connect.ts
 const HARNESSES = [{
@@ -6989,6 +7323,10 @@ function createApp({ api, token, loopback, web, allowHosts = [], notes, acp, bas
 		if (c.req.header("if-none-match") === etag) return c.body(null, 304, headers);
 		return c.body(found.bytes, 200, headers);
 	});
+	app.get("/api/code", async (c) => {
+		const href = c.req.query("href") ?? "";
+		return answer(c, () => api.code(href));
+	});
 	app.put("/api/note", async (c) => {
 		const refused = writeRefused(c);
 		if (refused) return refused;
@@ -7026,6 +7364,7 @@ function createApp({ api, token, loopback, web, allowHosts = [], notes, acp, bas
 		to: z.string().max(400),
 		base: z.string().max(64)
 	}).strict(), (c, b) => api.moveNote(id(c), b.to, b.base));
+	post("/api/folder", z.object({ path: z.string().max(400) }).strict(), (_c, b) => api.makeFolder(b.path));
 	post("/api/note/delete", z.object({ base: z.string().max(64) }).strict(), (c, b) => api.deleteNote(id(c), b.base));
 	post("/api/note/done", z.object({
 		done: z.boolean(),
@@ -7401,6 +7740,9 @@ var NodeFiles = class {
 			throw e;
 		}
 	}
+	async mkdir(dir) {
+		await mkdir(this.at(dir), { recursive: true });
+	}
 	async append(path, text) {
 		const full = this.at(path);
 		await mkdir(dirname(full), { recursive: true });
@@ -7757,12 +8099,14 @@ async function serve$1(path, { host = "127.0.0.1", port = 4767, allowHosts = [],
 		console.error(e.code === "EADDRINUSE" ? `port ${port} is in use (isorite serve --port <n>)` : e.message);
 		process.exit(1);
 	});
-	console.log(`isorite: ${notes}`);
-	console.log(embedder ? "  search by meaning: on" : "  search by meaning: off (isorite model fetches its model, 53 MB)");
+	const row = (label, text) => console.log(`  ${dim(label.padEnd(8))}${text}`);
+	console.log(`${bold("isorite")}  ${notes}`);
+	row("search", embedder ? "by meaning" : `by words ${dim("(isorite model fetches the model, 53 MB)")}`);
 	const lent = bases.lent().filter((l) => l.name !== bases.first).map((l) => l.name);
-	if (lent.length) console.log(`  lent to every session: ${lent.join(", ")} (isorite bases)`);
-	console.log(existsSync(join(WEB_DIR, "index.html")) ? `  ${link(`http://localhost:${port}/`)}` : `  the app is not built (npm run build); the engine alone is at http://localhost:${port}/api/`);
-	if (process.env.SSH_CONNECTION && LOOPBACK.has(host)) console.log(`  over SSH, the link opens on this machine; from your own, first run: ssh -L ${port}:localhost:${port} ${hostname()}`);
+	if (lent.length) row("lent", `${lent.join(", ")} ${dim("(isorite bases)")}`);
+	if (existsSync(join(WEB_DIR, "index.html"))) row("open", link(`http://localhost:${port}/`));
+	else row("open", `the app is not built (npm run build); the engine alone is at http://localhost:${port}/api/`);
+	if (process.env.SSH_CONNECTION && LOOPBACK.has(host)) row("ssh", `opens on this machine; from your own, first: ssh -L ${port}:localhost:${port} ${hostname()}`);
 	stop = () => {
 		server.close();
 		process.exit(0);
@@ -7781,6 +8125,12 @@ const MARK = {
 	warn: "!",
 	skip: "–"
 };
+const PAINT = {
+	ok: green,
+	fail: red,
+	warn: yellow,
+	skip: dim
+};
 /** The environment variables isorite and Node read for it; the secret ones are shown only by length. */
 const READ = [
 	"XDG_CONFIG_HOME",
@@ -7823,7 +8173,7 @@ async function doctor(folder, o = {}) {
 			outcome,
 			said
 		});
-		if (!o.report) out(`${MARK[outcome]} ${step}: ${said}`);
+		if (!o.report) out(`${PAINT[outcome](MARK[outcome])} ${bold(step)}: ${outcome === "skip" ? dim(said) : said}`);
 	};
 	const path = configPath(env), execArgv = o.execArgv ?? process.execArgv;
 	if (!existsSync(path)) say("config", "ok", `there is no ${path} yet: it is made when a base is first opened`);
@@ -7931,7 +8281,7 @@ async function doctor(folder, o = {}) {
 			...checks.map((c) => `${MARK[c.outcome]} ${c.step}: ${c.said}`),
 			"```"
 		].join("\n"));
-	} else out(failed ? `${failed} failed. isorite doctor --report gives all this as one block, its secrets hidden, to paste to someone helping.` : "nothing failed");
+	} else out(failed ? `${red(`${failed} failed.`)} isorite doctor --report gives all this as one block, its secrets hidden, to paste to someone helping.` : green("nothing failed"));
 	return failed ? 1 : 0;
 }
 //#endregion
@@ -9521,7 +9871,7 @@ function bases(args, { config = configPath(), out = console.log } = {}) {
 		return 0;
 	}
 	const width = Math.max(...known.map((b) => b.name.length));
-	for (const b of known) out(`${b.name.padEnd(width)}  ${b.lend ? "lent " : "     "}  ${b.path}${existsSync(b.path) ? "" : "  (not there)"}`);
+	for (const b of known) out(`${bold(b.name.padEnd(width))}  ${b.lend ? "lent " : "     "}  ${dim(b.path)}${existsSync(b.path) ? "" : `  ${red("(not there)")}`}`);
 	return 0;
 }
 //#endregion
@@ -9591,7 +9941,7 @@ async function start(io) {
 	if (found.kind === "base") return io.open(found.notes);
 	if (found.kind === "several") {
 		io.out(`isorite: more than one base here:`);
-		found.notes.forEach((n, i) => io.out(`  ${i + 1}  ${n}`));
+		found.notes.forEach((n, i) => io.out(`  ${dim(String(i + 1))}  ${n}`));
 		const pick = await io.choose("Open which?", found.notes.length);
 		return pick === null ? 2 : io.open(found.notes[pick]);
 	}
@@ -9612,7 +9962,7 @@ async function start(io) {
 		"the guide"
 	];
 	io.out(known.length ? "isorite: the bases on this machine, last used first:" : "isorite:");
-	rows.forEach((r, i) => io.out(`  ${i + 1}  ${r}`));
+	rows.forEach((r, i) => io.out(`  ${dim(String(i + 1))}  ${r}`));
 	const pick = await io.choose("Open which?", rows.length);
 	if (pick === null) return 2;
 	if (pick < known.length) return io.open(known[pick].path);
@@ -9639,62 +9989,66 @@ init_embedder();
 init_model();
 const SHORT = `isorite: an agentic harness for understanding
 
-  isorite                 open the base here, or choose one (a terminal; --no-open, --port <n>)
-  isorite doctor          whether isorite can work here, and what to change if not (--report to paste to
-                          someone helping; run in a project it checks that project's base)
-  isorite help            this; isorite help all lists every command
+  isorite                 open the base here, or choose one
+  isorite doctor          can isorite work here, and what to change if not
+  isorite help            this; help all lists every command
   isorite --version
 
-Notes are plain Markdown in a folder of your project; your own agent reads and writes them with you.
+Notes are plain Markdown in a folder of your project. Your agent reads and writes them with you.
 `;
 const USAGE = `isorite: an agentic harness for understanding
 
-  isorite new <folder>                   start a knowledge base: the folder, empty, with isorite's .isorite/
-  isorite check <notes> [--unused]       check a folder of notes: frontmatter, links, cycles; --unused lists
-                                         the pictures no note shows
+  isorite new <folder>                   a new base: an empty folder with .isorite/
+  isorite check <notes> [--unused] [--fix]
+                                         lint: frontmatter, links, cycles; --unused: pictures no note
+                                         shows; --fix: quote a colon in frontmatter
   isorite serve <notes> [--port <n>] [--allow-host <name>]
                                          open it in the browser, on this machine only
-  isorite migrate <study base> [--merge] move a study base (format 1) into its notes' .isorite/; exercises
-                                         become problem notes; the study base is left as it was
-  isorite example <folder> [--geometry]  write the example base (notes on an N-body simulation, three weeks
-                                         into being built), into an empty folder; --geometry: notes on the
-                                         differential geometry of surfaces, with their questions and problems
+  isorite migrate <study base> [--merge] a study base (format 1) into its notes' .isorite/
+  isorite example <folder> [--geometry]  an example base, partway built, in an empty folder
   isorite mcp [<notes>] [--port <n>] [--agent <name>]
-                                         the knowledge base's tools over MCP, on stdio, for your agent in its
-                                         own terminal: claude mcp add isorite -- isorite mcp <base>
+                                         the base's tools over MCP, on stdio:
+                                         claude mcp add isorite -- isorite mcp <base>
   isorite acp --agent "<command>" [<notes>] [--port <n>] [--pane]
-                                         an ACP agent (claude-agent-acp, codex-acp, opencode acp, hermes acp)
-                                         behind your ACP front end (Toad, Zed), with the base's MCP, and its
-                                         sessions in Iso's pane; --pane: no front end, the pane alone
+                                         an ACP agent behind your ACP front end, its sessions in Iso's
+                                         pane; --pane: the pane alone
   isorite model [--from <folder|.tgz>] [--url <url>]
-                                         the model for search by meaning: which is installed, and where; else
-                                         fetched (53 MB, once) from ISORITE_MODEL_BASE_URL, npm, GitHub or
-                                         Hugging Face, or --url alone; or from the .tgz fetched by hand, or a
-                                         folder: its files copied there, or any compatible model
+                                         the model for search by meaning: which, and where; else fetch it
+                                         (53 MB, once)
   isorite doctor [<notes>] [--report] [--offline]
-                                         whether isorite can work here: the configuration, the network, the
-                                         model for search by meaning, the server, the notes and the project's
-                                         MCP config; --report gives it as one block, to paste to someone (or
-                                         an AI) helping
-  isorite memory [<folder>]              the agent's memory: a knowledge base (~/isorite-memory unless named),
-                                         a git repository of its own, lent to every agent's session
-  isorite bases [lend|keep <name>]       the bases this device knows, each listed as it is opened; lend one to
-                                         every session, or keep it to itself
-  isorite help setup                     how isorite is set up, every setting and failure: written for an AI
-                                         helping you set it up (docs/setup.md is for people)
-  isorite guide [<folder>] [--port <n>]  the guide: a knowledge base about isorite, with things to do in it,
-                                         written into a folder (~/isorite-guide unless named) and opened in
-                                         the browser; run again, as you left it (also: isorite --tutorial)
+                                         can isorite work here, a step at a time; --report: one block to
+                                         paste to someone helping
+  isorite memory [<folder>]              the agent's memory: a base of its own, lent to every session
+  isorite bases [lend|keep <name>]       the bases this device knows; lend one to every session, or keep it
+  isorite help setup                     every setting and failure, written for an AI helping you set up
+  isorite guide [<folder>] [--port <n>]  the guide: a base about isorite, to do things in (--tutorial)
 `;
-function check(notes, out = console.log, unused = false) {
+function check(notes, out = console.log, unused = false, fix = false) {
 	const root = resolve(notes);
 	if (!existsSync(root) || !statSync(root).isDirectory()) {
 		out(`no folder at ${root}`);
 		return 2;
 	}
-	const bundle = loadBundle(root), issues = bundle.lint(), cycles = bundle.requiresCycles();
-	for (const i of issues) out(`${i.level.padEnd(7)} ${i.path}: ${i.message}`);
-	for (const c of cycles) out(`warning requires cycle: ${c.join(" -> ")}`);
+	let bundle = loadBundle(root), issues = bundle.lint();
+	const mendable = issues.filter((i) => i.code === "frontmatter-invalid").flatMap((i) => {
+		const m = repairFrontmatter(readFileSync(join(root, i.path), "utf8"));
+		return m ? [{
+			path: i.path,
+			...m
+		}] : [];
+	});
+	if (fix && mendable.length) {
+		for (const m of mendable) {
+			writeFileSync(join(root, m.path), m.text);
+			out(`fixed   ${m.path}: quoted ${m.fixed.join(", ")}`);
+		}
+		bundle = loadBundle(root);
+		issues = bundle.lint();
+	}
+	const cycles = bundle.requiresCycles();
+	const level = (l) => (l === "error" ? red(l) : yellow(l)) + " ".repeat(Math.max(0, 7 - l.length));
+	for (const i of issues) out(`${level(i.level)} ${bold(i.path)}: ${i.message}${i.code === "frontmatter-invalid" && !fix && mendable.some((m) => m.path === i.path) ? " (isorite check --fix quotes it)" : ""}`);
+	for (const c of cycles) out(`${level("warning")} requires cycle: ${c.join(" -> ")}`);
 	let artifactErrors = 0, artifactWarnings = 0;
 	for (const f of [...bundle.files].filter((x) => citeKind(x) === "artifact").sort()) {
 		const html = readFileSync(join(root, f), "utf8");
@@ -9711,13 +10065,14 @@ function check(notes, out = console.log, unused = false) {
 			files,
 			columns
 		})) {
-			out(`${b.level.padEnd(7)} ${f}: ${b.message}`);
+			out(`${level(b.level)} ${bold(f)}: ${b.message}`);
 			if (b.level === "error") artifactErrors++;
 			else artifactWarnings++;
 		}
 	}
 	const errors = issues.filter((i) => i.level === "error").length + artifactErrors;
-	out(`${bundle.concepts.size} notes in ${bundle.directories.size} folders; ${errors} errors, ${issues.length - issues.filter((i) => i.level === "error").length + artifactWarnings} warnings, ${cycles.length} requires cycles`);
+	const warnings = issues.length - issues.filter((i) => i.level === "error").length + artifactWarnings;
+	out(`${dim(`${bundle.concepts.size} notes in ${bundle.directories.size} folders;`)} ${(errors ? red : green)(`${errors} errors`)}, ${(warnings ? yellow : green)(`${warnings} warnings`)}, ${cycles.length} requires cycles`);
 	if (unused) {
 		const cited = new Set([...bundle.concepts.values()].flatMap((c) => c.cites.map((x) => x.target)));
 		const idle = [...bundle.files].filter((f) => citeKind(f) === "image" && !cited.has(f)).sort();
@@ -9803,7 +10158,7 @@ function main(argv) {
 				noOpen: args.includes("--no-open")
 			});
 		}
-		if (command === "check" && rest.find((r) => !r.startsWith("--"))) return check(rest.find((r) => !r.startsWith("--")), console.log, rest.includes("--unused"));
+		if (command === "check" && rest.find((r) => !r.startsWith("--"))) return check(rest.find((r) => !r.startsWith("--")), console.log, rest.includes("--unused"), rest.includes("--fix"));
 		if (command === "new" && rest[0]) {
 			const made = newBase(rest[0]);
 			const next = `${made}: a knowledge base, empty. Open it in the browser, and attach your agent from Iso's pane:\n  isorite serve ${made}`;
@@ -10001,7 +10356,7 @@ function main(argv) {
 		}
 		throw e;
 	}
-	process.stdout.write(command === "help" && rest[0] === "all" ? USAGE : command && command !== "help" && command !== "--help" ? USAGE : SHORT);
+	process.stdout.write(helpText(command === "help" && rest[0] === "all" ? USAGE : command && command !== "help" && command !== "--help" ? USAGE : SHORT));
 	return command && command !== "help" && command !== "--help" ? 2 : 0;
 }
 /** The commands that start something, which say so at once (M21): a subprocess that stalls after this is then