isorite 0.1.0 → 0.2.0

package/dist/main.js

@@ -9,13 +9,15 @@ import { createHash, randomBytes } from "node:crypto";
 import { serve } from "@hono/node-server";
 import { homedir, tmpdir } from "node:os";
 import { Worker } from "node:worker_threads";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { Hono } from "hono";
 import { streamSSE } from "hono/streaming";
 import { z } from "zod";
+import { OpenCode } from "@opencode/client";
 import { appendFile, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
-import { execFileSync, spawn } from "node:child_process";
 import { createInterface } from "node:readline";
-import { createServer } from "node:http";
+import { createServer } from "node:net";
+import { createServer as createServer$1 } from "node:http";
 //#region packages/core/src/text.ts
 const WS = "\\t\\n\\x0b\\x0c\\r\\x1c-\\x1f \\x85\\xa0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000";
 const LEAD = new RegExp(`^[${WS}]+`, "u");
@@ -1407,7 +1409,8 @@ function moments(entries) {
 			const what = e.why === "start" ? e.who === "external" ? "found" : "wrote" : e.why === "edit" ? "edited" : e.why === "restore" ? "restored" : e.why === "keep" ? "kept" : e.why === "move" ? "moved" : "changed elsewhere";
 			out.push({
 				...base,
-				what
+				what,
+				...e.asked ? { asked: e.asked } : {}
 			});
 		}
 	}
@@ -1574,6 +1577,11 @@ function understanding(events, now = Date.now()) {
 				s.last = when;
 				s.evidence.push(e.id);
 			}
+		} else if (e.event === "understood" && typeof e.note === "string") {
+			const s = at(e.note), by = e.by;
+			s.level = clamp(s.level + (typeof by === "number" && Number.isFinite(by) ? Math.max(-1, Math.min(1, by)) : 0));
+			s.last = when;
+			s.evidence.push(e.id);
 		} else if (e.event === "moved" && typeof e.from === "string" && typeof e.to === "string") {
 			const s = state.get(e.from);
 			if (s) {
@@ -2055,7 +2063,7 @@ async function rounds(o) {
 				callId: c.id,
 				content: text
 			});
-			o.onStep(step);
+			if (step) o.onStep(step);
 		}
 	}
 }
@@ -2063,7 +2071,7 @@ async function rounds(o) {
 //#region packages/engine/src/iso.ts
 /** The point in the note where new text is asked for. Not part of the note. */
 const HERE = "⟦HERE⟧";
-const WHO = `You are Iso, the companion in isorite, an app for understanding a subject by
+const WHO$1 = `You are Iso, the companion in isorite, an app for understanding a subject by
 writing it down. The person is writing a note in their own knowledge base: a
 folder of Markdown notes with links between them. They have asked you for
 something at one place in the note they have open.`;
@@ -2145,6 +2153,8 @@ const FORMAT = `# How notes work here
   equation as a paragraph of its own, with $$ alone on the line before it
   and $$ alone on the line after.
 - Ordinary Markdown otherwise. No HTML.`;
+/** How notes are written, for any request that writes or quotes them. */
+const FORMAT_RULES = FORMAT;
 const LOOKUP = (rounds, meaning) => `# Looking things up
 
 Before you reply you may look things up in their knowledge base with the
@@ -2245,14 +2255,23 @@ function windowed(lines, keep, budget = NOTE_BUDGET) {
 	flush();
 	return out.join("\n");
 }
+/** The notes a note links to, as they are sent with a request in it. */
+function linkedSection(linked, intro = "The notes this note links to") {
+	return linked.length ? `# ${intro}\n\n${linked.map((l) => `## ${l.title} (/${l.id}.md)\n\n${l.text}`).join("\n\n")}` : "";
+}
+const NO_LOOKUP = `# Looking things up
+
+You have no tools this time: they chose what you are sent. Answer from it, and
+say plainly what you would need to look up to say more.`;
 /** The messages for new text at a point, and what they hold, part by part. */
 function insertMessages(a) {
 	const system = [
-		WHO,
+		WHO$1,
 		INSERT$1,
 		FORMAT,
-		LOOKUP(ROUNDS[a.tier], a.meaning)
+		a.lookup === false ? NO_LOOKUP : looked$1(a)
 	].join("\n\n");
+	const linked = linkedSection(a.linked ?? []);
 	const note = `# Their note: ${a.title} (/${a.id}.md)\n\n${a.marked}` + (a.unkept.length ? `\n\n# Text you offered in this note that they have not kept yet\n\nIt is not part of the note. Do not write it again.\n\n${a.unkept.join("\n\n---\n\n")}` : "");
 	const earlier = a.conversation ? `# Earlier in this session\n\n${a.conversation}` : "";
 	const request = `# What they ask now\n\n${a.asked}`;
@@ -2267,47 +2286,54 @@ function insertMessages(a) {
 			role: "user",
 			content: [
 				earlier,
+				linked,
 				note,
 				request
 			].filter(Boolean).join("\n\n")
 		}],
-		parts: [
-			{
-				name: "instructions and tools",
-				detail: "",
-				tokens: estimate(system) + 500
-			},
-			{
-				name: "study record",
-				detail: "nothing yet",
-				tokens: 0
-			},
-			{
-				name: "your prompts and Iso's answers",
-				detail: a.moments ? `${a.moments} ${a.moments === 1 ? "moment" : "moments"}` : "",
-				tokens: estimate(earlier)
-			},
-			{
-				name: "this note",
-				detail: a.title,
-				tokens: estimate(note) + estimate(request)
-			},
-			{
-				name: "linked notes",
-				detail: a.linked?.notes ? `${a.linked.notes} read` : "",
-				tokens: a.linked?.tokens ?? 0
-			}
-		]
+		parts: inPlaceParts(a, system, earlier, linked, note, request)
 	};
 }
+/** The look-up instructions for a request in place, saying what is sent below it. */
+const looked$1 = (a) => LOOKUP(ROUNDS[a.tier], a.meaning).replace("below there is only the note.", a.linked?.length ? "below there is the note, and\nthe notes it links to that they chose to send." : "below there is only the note.");
+function inPlaceParts(a, system, earlier, linked, note, request) {
+	return [
+		{
+			name: "instructions and tools",
+			detail: a.lookup === false ? "no tools" : "",
+			tokens: estimate(system) + (a.lookup === false ? 0 : 500)
+		},
+		{
+			name: "study record",
+			detail: "nothing yet",
+			tokens: 0
+		},
+		{
+			name: "your prompts and Iso's answers",
+			detail: a.moments ? `${a.moments} ${a.moments === 1 ? "moment" : "moments"}` : "",
+			tokens: estimate(earlier)
+		},
+		{
+			name: "this note",
+			detail: a.title,
+			tokens: estimate(note) + estimate(request)
+		},
+		{
+			name: "linked notes",
+			detail: a.linked?.length ? `${a.linked.length} sent` : "",
+			tokens: estimate(linked)
+		}
+	];
+}
 /** The messages for a rewrite of chosen paragraphs. */
 function rewriteMessages(a) {
 	const system = [
-		WHO,
+		WHO$1,
 		REWRITE(a.count),
 		FORMAT,
-		LOOKUP(ROUNDS[a.tier], a.meaning)
+		a.lookup === false ? NO_LOOKUP : looked$1(a)
 	].join("\n\n");
+	const linked = linkedSection(a.linked ?? []);
 	const note = `# Their note: ${a.title} (/${a.id}.md)\n\n${a.marked}`;
 	const earlier = a.conversation ? `# Earlier in this session\n\n${a.conversation}` : "";
 	const request = `# What they ask now, of the marked ${a.count === 1 ? "passage" : "passages"}\n\n${a.asked}`;
@@ -2322,37 +2348,12 @@ function rewriteMessages(a) {
 			role: "user",
 			content: [
 				earlier,
+				linked,
 				note,
 				request
 			].filter(Boolean).join("\n\n")
 		}],
-		parts: [
-			{
-				name: "instructions and tools",
-				detail: "",
-				tokens: estimate(system) + 500
-			},
-			{
-				name: "study record",
-				detail: "nothing yet",
-				tokens: 0
-			},
-			{
-				name: "your prompts and Iso's answers",
-				detail: a.moments ? `${a.moments} ${a.moments === 1 ? "moment" : "moments"}` : "",
-				tokens: estimate(earlier)
-			},
-			{
-				name: "this note",
-				detail: a.title,
-				tokens: estimate(note) + estimate(request)
-			},
-			{
-				name: "linked notes",
-				detail: a.linked?.notes ? `${a.linked.notes} read` : "",
-				tokens: a.linked?.tokens ?? 0
-			}
-		]
+		parts: inPlaceParts(a, system, earlier, linked, note, request)
 	};
 }
 /** A rewrite's reply, taken apart: the new text for each of the `count` passages (null where it left one as it
@@ -2396,7 +2397,7 @@ const LINKED_BUDGET = 8e3;
 /** The messages for a note written for Iso. */
 function noteMessages(a) {
 	const system = [
-		WHO.replace("They have asked you for\nsomething at one place in the note they have open.", "This time they have written to you at length."),
+		WHO$1.replace("They have asked you for\nsomething at one place in the note they have open.", "This time they have written to you at length."),
 		NOTE,
 		FORMAT,
 		LOOKUP(ROUNDS[a.tier], a.meaning).replace("below there is only the note.", "below there is what they wrote, and the notes they linked.")
@@ -2654,8 +2655,8 @@ function exerciseReply(reply) {
 }
 //#endregion
 //#region packages/engine/src/lookup.ts
-const str = { type: "string" };
-const fn = (name, description, properties, required) => ({
+const str$1 = { type: "string" };
+const fn$1 = (name, description, properties, required) => ({
 	type: "function",
 	function: {
 		name,
@@ -2669,10 +2670,10 @@ const fn = (name, description, properties, required) => ({
 	}
 });
 const TOOLS = [
-	fn("search_notes", "Keyword search over the knowledge base. Returns note ids, titles, types, one-sentence descriptions and a one-line snippet. Search by the words a note would use.", {
-		query: str,
+	fn$1("search_notes", "Keyword search over the knowledge base. Returns note ids, titles, types, one-sentence descriptions and a one-line snippet. Search by the words a note would use.", {
+		query: str$1,
 		under: {
-			...str,
+			...str$1,
 			description: "Only notes in this folder."
 		},
 		limit: {
@@ -2680,25 +2681,25 @@ const TOOLS = [
 			description: "How many, 8 unless said, 15 at most."
 		}
 	}, ["query"]),
-	fn("outline_note", "A note's description, its headings, the notes it links to and the notes that link to it, without its body. Use it to choose a section to read.", { id: {
-		...str,
+	fn$1("outline_note", "A note's description, its headings, the notes it links to and the notes that link to it, without its body. Use it to choose a section to read.", { id: {
+		...str$1,
 		description: "The note's id or path: basics/entropy or /basics/entropy.md."
 	} }, ["id"]),
-	fn("read_note", "Read one section of a note, by its heading, or the whole note when no section is named. Prefer a section.", {
-		id: str,
+	fn$1("read_note", "Read one section of a note, by its heading, or the whole note when no section is named. Prefer a section.", {
+		id: str$1,
 		section: {
-			...str,
+			...str$1,
 			description: "A heading's text, as outline_note gives it."
 		}
 	}, ["id"])
 ];
-const FIND_SIMILAR = fn("find_similar", "Find notes by meaning: notes that say something like the text you give, even in quite other words. Slower and vaguer than search_notes: use it after search_notes and the links of the notes in hand have not found what you need, or when you cannot guess the words a note would use. Give a question or a sentence, not keywords. Returns each note's nearest section, with how alike it is (0 to 1).", {
+const FIND_SIMILAR = fn$1("find_similar", "Find notes by meaning: notes that say something like the text you give, even in quite other words. Slower and vaguer than search_notes: use it after search_notes and the links of the notes in hand have not found what you need, or when you cannot guess the words a note would use. Give a question or a sentence, not keywords. Returns each note's nearest section, with how alike it is (0 to 1).", {
 	text: {
-		...str,
+		...str$1,
 		description: "A question, or a sentence saying what you are looking for."
 	},
 	under: {
-		...str,
+		...str$1,
 		description: "Only notes in this folder."
 	},
 	limit: {
@@ -2867,89 +2868,341 @@ var Lookup = class {
 	}
 };
 //#endregion
-//#region packages/engine/src/agent.ts
-/** Which occurrence of `text` starts at `offset`, counted from 0 through the note. */
-function nthAt(note, text, offset) {
-	let n = 0;
-	for (let at = note.indexOf(text); at >= 0 && at < offset; at = note.indexOf(text, at + 1)) n++;
-	return n;
-}
-/** The passages a string replacement changes. Refused, in words the agent can act on, when it names nothing or
-*  more than one place without saying to replace them all. */
-function editRegions(note, oldString, newString, replaceAll = false) {
-	if (!oldString) throw new EngineError("oldString is empty: name the text to replace, or write the whole note.", 400);
-	if (oldString === newString) throw new EngineError("oldString and newString are the same: nothing would change.", 400);
-	let count = 0;
-	for (let at = note.indexOf(oldString); at >= 0; at = note.indexOf(oldString, at + 1)) count++;
-	if (!count) throw new EngineError("oldString is not in the note. Read the note again and copy the text exactly.", 400);
-	if (count > 1 && !replaceAll) throw new EngineError(`oldString is in the note ${count} times. Give more of the text around it, or replaceAll.`, 400);
-	return Array.from({ length: count }, (_, nth) => ({
-		old: {
-			text: oldString,
-			nth
-		},
-		new: newString
-	}));
+//#region packages/engine/src/understand.ts
+const UNDERSTANDING_PREFIX = "@understanding/";
+const UNDERSTANDING_DIR = "understanding";
+const isUnderstandingId = (id) => id.startsWith(UNDERSTANDING_PREFIX);
+const understandingId = (note) => UNDERSTANDING_PREFIX + note;
+const READING = "## Iso's reading";
+const PAD = "## Scratchpad";
+/** The two parts of an Understanding note's file. A file in another shape is read as all scratchpad. */
+function parseUnderstanding(text) {
+	if (!text) return {
+		reading: "",
+		scratchpad: ""
+	};
+	const body = text.replace(/^---\n[\s\S]*?\n---\n/, "");
+	const r = body.indexOf(READING), p = body.indexOf(PAD);
+	if (r < 0 && p < 0) return {
+		reading: "",
+		scratchpad: body.trim()
+	};
+	return {
+		reading: r < 0 ? "" : body.slice(r + 16, p > r ? p : void 0).trim(),
+		scratchpad: p < 0 ? "" : body.slice(p + 13, r > p ? r : void 0).trim()
+	};
 }
-/** The passages that change between a note and the whole of it written anew, by line. A passage is never empty:
-*  a line added between others is offered with the nearest line that has text beside it. */
-function writeRegions(before, after) {
-	const a = before.split("\n"), b = after.split("\n"), hunks = diffLines(a, b);
-	const filled = (i) => (a[i] ?? "").trim() !== "";
-	const spans = hunks.map((h) => {
-		let from = h.at, to = h.at + h.del.length;
-		if (!a.slice(from, to).some((line) => line.trim())) {
-			let k = from - 1;
-			while (k >= 0 && !filled(k)) k--;
-			if (k >= 0) from = k;
-			else {
-				k = to;
-				while (k < a.length && !filled(k)) k++;
-				if (k >= a.length) throw new EngineError("the note has no text to place the change against: write it with text in it", 400);
-				to = k + 1;
-			}
+/** An Understanding note's file, from its parts. */
+function understandingText(note, title, parts) {
+	return `---\ntype: Understanding\ntitle: ${JSON.stringify(`Understanding · ${title}`)}\nof: ${note}\n---\n\n${READING}\n\n${parts.reading.trim()}\n\n${PAD}\n\n${parts.scratchpad.trim()}\n`;
+}
+//#endregion
+//#region packages/engine/src/turn.ts
+/** What Iso may do. Build needs a project and a shell, and is the terminal's (M11). */
+const MODES = [
+	"ask",
+	"write",
+	"build",
+	"understand"
+];
+const CONVERSATIONS_DIR = "conversations";
+const conversationPath = (id) => `${CONVERSATIONS_DIR}/${id}.jsonl`;
+/** A conversation's turns from its file, oldest first. A line that cannot be read is passed over. */
+function readTurns(text) {
+	const turns = /* @__PURE__ */ new Map();
+	for (const raw of text.split("\n")) {
+		if (!raw.trim()) continue;
+		let line;
+		try {
+			line = JSON.parse(raw);
+		} catch {
+			continue;
 		}
-		return {
-			from,
-			to
-		};
-	});
-	const merged = [];
-	for (const s of spans) {
-		const last = merged.at(-1);
-		if (last && s.from <= last.to) last.to = Math.max(last.to, s.to);
-		else merged.push({ ...s });
-	}
-	const moved = (i, counts) => i + hunks.filter((h) => counts(h.at)).reduce((d, h) => d + h.ins.length - h.del.length, 0);
-	const start = (i) => moved(i, (at) => at < i), end = (i) => moved(i, (at) => at <= i);
-	const offset = (i) => a.slice(0, i).reduce((n, line) => n + line.length + 1, 0);
-	return merged.map(({ from, to }) => {
-		const lines = b.slice(start(from), end(to));
-		let text = a.slice(from, to).join("\n"), at = offset(from);
-		if (!lines.length) {
-			if (to < a.length) text += "\n";
-			else if (from > 0) {
-				text = "\n" + text;
-				at -= 1;
-			}
+		if (line.kind === "turn") {
+			const { kind: _, ...t } = line;
+			turns.set(t.id, {
+				...t,
+				items: [],
+				state: "running"
+			});
+			continue;
 		}
-		return {
-			old: {
-				text,
-				nth: nthAt(before, text, at)
-			},
-			new: lines.join("\n")
-		};
-	});
+		const t = turns.get(line.turn);
+		if (!t) continue;
+		if (line.kind === "item") t.items.push(line.item);
+		else if (line.kind === "answer") {
+			for (const i of t.items) if (i.kind === "permission" && i.id === line.permission) i.answer = line.decision;
+		} else {
+			t.state = line.state;
+			if (line.message) t.message = line.message;
+			if (line.cost) t.cost = line.cost;
+		}
+	}
+	return [...turns.values()].map((t) => t.state === "running" ? {
+		...t,
+		state: "stopped"
+	} : t).sort((a, b) => a.id < b.id ? -1 : 1);
+}
+const WHO = `You are Iso, the companion in isorite, an app for understanding a subject by
+writing it down. The person keeps a knowledge base: a folder of Markdown notes
+with links between them. They are talking with you in isorite's Iso pane,
+beside their notes and the Atlas, the map of their base. What you look up and
+what you change is shown to them there as you do it.`;
+const MODE_RULES = {
+	ask: `# Ask mode: what you may do
+
+You read their notes and answer. You cannot change anything in this mode: no
+note, no folder.
+
+- Answer what they ask, in plain prose. Short: a few sentences to a few
+  paragraphs, unless more is asked for. Markdown and maths are shown as they
+  are in their notes.
+- Rest on their notes where the base says something: look first, and link to
+  the notes you used, so they can open them. Where the base does not hold what
+  is asked, answer from what you know of the subject, exactly, and say that
+  their notes do not cover it.
+- When one of their notes would help them and they may not know it, point it
+  out with point_to_note. Use it sparingly: one or two notes.
+- Never invent a note, a link or a quotation.`,
+	write: `# Write mode: what you may do
+
+You may change their knowledge base: edit notes, make new ones, move them and
+delete them. What you change goes into their notes at once. They see every
+change marked as yours, and can undo it.
+
+- Do what they ask, and only that. Change the least that does it: edit the
+  passage that needs it with edit_note, not the whole note. Keep their words,
+  links, maths and voice wherever the request does not call for a change.
+- Look before you write: read the part of the note you change, and the notes
+  it rests on, so what you write agrees with the base and links to it.
+- A new note (write_note) is written as one of theirs: frontmatter with type
+  and title, their notation, their level, plain words, linked to the notes it
+  rests on.
+- Moving or deleting a note is asked of them before it happens. Do it only
+  when they asked for it.
+- When you are done, say in a sentence or two what you changed and why. Do not
+  repeat the text you wrote: they see it in the note.
+- Never invent a note, a link or a quotation.`,
+	understand: `# Understand mode: what you may do
+
+You help them understand: what is in their notes, what changed in them, or
+something they want to understand more deeply. You do not change their notes.
+You keep a record of their understanding, note by note, in their study base.
+
+- Start from where they are. Below, for each note in hand, is your reading of
+  their understanding of it so far and what changed it. Use it: do not explain
+  what they have shown they know; go to what they have not yet shown.
+- Ask before you explain, where a question would show you where they stand.
+  One question at a time. Short turns.
+- When they show understanding, or a gap, record it with
+  record_understanding: how far this turn is evidence that their
+  understanding of the note differs from what you had (-1, -0.5, 0, 0.5 or 1)
+  and why, in one plain sentence to them. At most once a note a turn.
+- At the end of a conversation about a note, or when your reading of them has
+  changed, rewrite your reading with write_understanding: a few plain
+  sentences on what they can do with the note and what they have not yet
+  shown. It is theirs to read.
+- Never invent a note, a link or a quotation.`
+};
+const LOOKING = (rounds, meaning, lookup) => lookup ? `# Looking things up
+
+- Look up only what the request needs. search_notes finds notes by their
+  words; outline_note shows a note's headings and links; read_note reads one
+  section. Prefer a section to a whole note. Follow links one step at a time.${meaning ? `
+- find_similar finds notes by meaning, when their words have not found them.` : ""}
+- You may call several tools at once, over ${rounds} rounds at most; then reply.
+- Say nothing between tool calls. Only the reply is shown.` : `# Looking things up
+
+They chose what you are sent and asked you not to look further: you have no
+tools for searching or reading. Answer from what is below, and say plainly what
+you would need to look at to say more.`;
+const str = { type: "string" };
+const fn = (name, description, properties, required) => ({
+	type: "function",
+	function: {
+		name,
+		description,
+		parameters: {
+			type: "object",
+			properties,
+			required,
+			additionalProperties: false
+		}
+	}
+});
+const POINT_TO_NOTE = fn("point_to_note", "Point the person to one of their notes: it is marked on their Atlas, with why. For a note that would help them that they may not know of.", {
+	id: {
+		...str,
+		description: "The note's id or path."
+	},
+	why: {
+		...str,
+		description: "Why, in a short sentence to them."
+	}
+}, ["id", "why"]);
+const EDIT_NOTE$1 = fn("edit_note", "Replace one passage of a note with new text. `old` must be exactly as it is in the note, and must occur in it once: read it first. Give enough of it to be unique. An empty `new` takes the passage out.", {
+	id: {
+		...str,
+		description: "The note's id or path."
+	},
+	old: {
+		...str,
+		description: "The passage as it is now, exactly."
+	},
+	new: {
+		...str,
+		description: "What it becomes."
+	}
+}, [
+	"id",
+	"old",
+	"new"
+]);
+const WRITE_NOTE$1 = fn("write_note", "Make a new note, or write a note's whole text anew. For a new note give its whole file: frontmatter (type, title) then the body. Prefer edit_note for a change to a note that exists.", {
+	id: {
+		...str,
+		description: "The note's id: folder/name, lower case with hyphens. A new folder is made for it."
+	},
+	text: {
+		...str,
+		description: "The note's whole file."
+	}
+}, ["id", "text"]);
+const MOVE_NOTE = fn("move_note", "Move or rename a note. Links to it are changed to match. They are asked first.", {
+	id: str,
+	to: {
+		...str,
+		description: "Its new id: folder/name."
+	}
+}, ["id", "to"]);
+const DELETE_NOTE = fn("delete_note", "Delete a note. They are asked first. Its history stays.", { id: str }, ["id"]);
+const RECORD_UNDERSTANDING = fn("record_understanding", "Record evidence of their understanding of one note from this turn: how far it differs from what you had, and why.", {
+	id: {
+		...str,
+		description: "The note's id."
+	},
+	by: {
+		type: "number",
+		enum: [
+			-1,
+			-.5,
+			0,
+			.5,
+			1
+		]
+	},
+	why: {
+		...str,
+		description: "One plain sentence, to them."
+	}
+}, [
+	"id",
+	"by",
+	"why"
+]);
+const WRITE_UNDERSTANDING = fn("write_understanding", "Rewrite your reading of their understanding of one note: a few plain sentences on what they can do with it and what they have not yet shown. Replaces the reading you had.", {
+	id: {
+		...str,
+		description: "The note's id."
+	},
+	reading: str
+}, ["id", "reading"]);
+/** The tools each mode adds to looking things up. */
+const MODE_TOOLS = {
+	ask: [POINT_TO_NOTE],
+	write: [
+		EDIT_NOTE$1,
+		WRITE_NOTE$1,
+		MOVE_NOTE,
+		DELETE_NOTE,
+		POINT_TO_NOTE
+	],
+	understand: [
+		RECORD_UNDERSTANDING,
+		WRITE_UNDERSTANDING,
+		POINT_TO_NOTE
+	]
+};
+function sentText(s) {
+	if (s.kind === "note") return `## ${s.title} (/${s.id}.md)\n\n${windowed(s.text.split("\n"), [0])}`;
+	if (s.kind === "passage") return `## A passage they chose in ${s.title} (/${s.id}.md)\n\n${s.text.split("\n").map((l) => `> ${l}`).join("\n")}`;
+	if (s.kind === "folder") return `## The folder ${s.id || "at the top of the base"}: its notes\n\n${s.notes.map((n) => `- ${n.title} (/${n.id}.md)${n.description ? `: ${n.description}` : ""}`).join("\n") || "(empty)"}`;
+	return `## Their understanding of ${s.title} (/${s.id}.md): ${s.squares} of 6 squares\n\nYour reading so far: ${s.reading || "none yet."}\n\nWhat changed it, newest first:\n${s.events.map((e) => `- ${e}`).join("\n") || "- nothing yet"}`;
+}
+/** An earlier turn as it is sent: in the shape `conversation()` shortens. */
+function turnExchange(t) {
+	const text = t.items.filter((i) => i.kind === "text").map((i) => i.text).join("\n\n").trim();
+	const changed = t.items.flatMap((i) => i.kind === "change" ? [`${i.why === "create" ? "made" : i.why === "delete" ? "deleted" : i.why === "move" ? "moved" : "changed"} ${i.title} (/${i.note}.md)`] : []);
+	const gave = t.given.filter((g) => g.kind !== "understanding").map((g) => g.kind === "passage" ? `a passage of /${g.id}.md` : `/${g.id}${g.kind === "note" ? ".md" : "/"}`);
+	return {
+		id: t.id,
+		note: "",
+		text: `In ${t.mode} mode they asked${gave.length ? `, giving you ${gave.join(", ")}` : ""}: ${t.asked}\n\nYou wrote:\n\n${text || "(nothing)"}\n\n${changed.length ? `You ${changed.join("; ")}.` : t.state === "done" ? "" : `The turn was ${t.state}.`}`.trim()
+	};
 }
-/** The passages an agent's edit changes in a note as it is. */
-function regionsOf(note, edit) {
-	return "content" in edit ? writeRegions(note, edit.content) : editRegions(note, edit.oldString, edit.newString, edit.replaceAll);
+/** The messages for a turn, and what they hold, part by part. */
+function turnMessages(a) {
+	const system = [
+		WHO,
+		MODE_RULES[a.mode],
+		FORMAT_RULES,
+		LOOKING(ROUNDS[a.tier], a.meaning, a.lookup)
+	].join("\n\n");
+	const talk = conversation(a.earlier.map(turnExchange));
+	const earlier = talk ? `# Earlier in this conversation\n\n${talk}` : "";
+	const understood = a.sent.filter((s) => s.kind === "understanding");
+	const given = a.sent.filter((s) => s.kind !== "understanding");
+	const gave = given.length ? `# What they gave you\n\n${given.map(sentText).join("\n\n")}` : "";
+	const known = understood.length ? `# Their understanding, as you have recorded it\n\n${understood.map(sentText).join("\n\n")}` : "";
+	const request = `# What they ask now\n\n${a.asked}`;
+	return {
+		messages: [{
+			role: "system",
+			content: [{
+				text: system,
+				cache: true
+			}]
+		}, {
+			role: "user",
+			content: [
+				earlier,
+				known,
+				gave,
+				request
+			].filter(Boolean).join("\n\n")
+		}],
+		parts: [
+			{
+				name: "instructions and tools",
+				detail: `${a.mode} mode${a.lookup ? "" : ", no look-ups"}`,
+				tokens: estimate(system) + (a.lookup ? 500 : 0) + MODE_TOOLS[a.mode].length * 120
+			},
+			{
+				name: "earlier in this conversation",
+				detail: a.earlier.length ? `${a.earlier.length} ${a.earlier.length === 1 ? "turn" : "turns"}` : "",
+				tokens: estimate(earlier)
+			},
+			{
+				name: "what you gave",
+				detail: given.length ? `${given.length} ${given.length === 1 ? "part" : "parts"}` : "nothing",
+				tokens: estimate(gave)
+			},
+			...a.mode === "understand" ? [{
+				name: "your understanding",
+				detail: `${understood.length} ${understood.length === 1 ? "note" : "notes"}`,
+				tokens: estimate(known)
+			}] : [],
+			{
+				name: "your message",
+				detail: "",
+				tokens: estimate(request)
+			}
+		]
+	};
 }
 //#endregion
 //#region packages/engine/src/meaning.ts
 const MAX_PIECE = 1800;
-const QUERY = "Represent this sentence for searching relevant passages: ";
 const fingerprint = (text) => sha256(text).slice(0, 20);
 /** Every note cut into pieces: at its first- and second-level headings (not inside a code fence), and a long section at its paragraphs. */
 function pieces(b) {
@@ -3105,7 +3358,7 @@ var Meaning = class {
 			pending: missing.length,
 			ready: false
 		};
-		const q = pack(await this.embedder.embed(QUERY + text)), dim = this.embedder.dim;
+		const q = pack(await this.embedder.embed((this.embedder.query ?? "") + text)), dim = this.embedder.dim;
 		const under = opts.under?.replace(/^\/+|\/+$/g, "");
 		const best = /* @__PURE__ */ new Map();
 		for (const p of ps) {
@@ -3140,9 +3393,9 @@ const DRAFT_PREFIX = "@draft/";
 const DRAFT_DIR = "drafts";
 const isDraftId = (id) => id.startsWith(DRAFT_PREFIX);
 /** A note's id without the prefix that says which folder of the study base it is in. */
-const bare = (id) => isStudyId(id) ? id.slice(7) : isDraftId(id) ? id.slice(7) : id;
+const bare = (id) => isStudyId(id) ? id.slice(7) : isDraftId(id) ? id.slice(7) : isUnderstandingId(id) ? id.slice(15) : id;
 /** In the knowledge base itself: neither an exercise nor a draft. */
-const inBase = (id) => !isStudyId(id) && !isDraftId(id);
+const inBase = (id) => !isStudyId(id) && !isDraftId(id) && !isUnderstandingId(id);
 const BAD_PART = /^\.|[\0\\:*?"<>|]|^\s|\s$/;
 /** A note's id, checked before it becomes a path: no "..", nothing hidden, no absolute path. */
 function checkNoteId(id) {
@@ -3150,6 +3403,8 @@ function checkNoteId(id) {
 	if (!id || id.length > 400 || parts.some((p) => !p || BAD_PART.test(p))) throw new EngineError(`not a note's id: ${JSON.stringify(id)}`);
 	return id;
 }
+/** A conversation's or turn's id: a ULID. */
+const TURN_ID = /^[0-9A-HJKMNP-TV-Z]{26}$/;
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 async function walk(files, root) {
 	const out = [];
@@ -3195,12 +3450,12 @@ const NOTE_ARG = {
 	type: "string",
 	description: "The note's id or path in the knowledge base: physics/softening or /physics/softening.md."
 };
-const WAITS = "Notes are checked by the person: the change waits for them to keep it, in the browser or the terminal, and the note's file is unchanged until they do. Use this, never edit or write, for any note of the knowledge base.";
-const PROPOSE_EDIT = {
+const MARKED = "The change is written at once, under your name: the person sees your words marked in the note, and can undo it from the browser. Use this, never edit or write, for any note of the knowledge base.";
+const EDIT_NOTE = {
 	type: "function",
 	function: {
-		name: "propose_note_edit",
-		description: `Propose a change to a note of the knowledge base: oldString replaced by newString, as the edit tool does. ${WAITS}`,
+		name: "edit_note",
+		description: `Change a note of the knowledge base: oldString replaced by newString, as the edit tool does. ${MARKED}`,
 		parameters: {
 			type: "object",
 			properties: {
@@ -3224,11 +3479,11 @@ const PROPOSE_EDIT = {
 		}
 	}
 };
-const PROPOSE_WRITE = {
+const WRITE_NOTE = {
 	type: "function",
 	function: {
-		name: "propose_note_write",
-		description: `Propose a whole note: a new note of the knowledge base, with its frontmatter (type, title), or one written anew. A new note waits as a note for review, and the person chooses its folder. ${WAITS}`,
+		name: "write_note",
+		description: `Write a whole note: a new note of the knowledge base, at folder/name (lower case, hyphens), with its frontmatter (type, title), or one written anew. ${MARKED}`,
 		parameters: {
 			type: "object",
 			properties: {
@@ -3341,6 +3596,14 @@ var Engine = class Engine {
 			step: read.get(c.id)?.step ?? 0,
 			tokens: estimate(c.body.trim())
 		};
+		for (const [id, u] of read) {
+			if (!notes[id] || u.last === null || !study) continue;
+			const changed = (await this.journal(id)).findLast((e) => e.kind === "change" && e.who !== "you" && e.why !== "move");
+			if (changed && Date.parse(changed.at) > u.last) notes[id] = {
+				...notes[id],
+				changedSince: changed.at
+			};
+		}
 		for (const c of exercises?.concepts.values() ?? []) notes[studyId(c.id)] = {
 			title: c.title,
 			step: 0,
@@ -3371,23 +3634,23 @@ var Engine = class Engine {
 			TOOLS[0],
 			...this.similar ? [FIND_SIMILAR] : [],
 			...TOOLS.slice(1),
-			PROPOSE_EDIT,
-			PROPOSE_WRITE
+			EDIT_NOTE,
+			WRITE_NOTE
 		];
 	}
 	async agentLook({ agent, session, tool, args, asked = "" }) {
 		if (tool === BRIEF.function.name) return { text: this.brief() };
-		if (tool === PROPOSE_EDIT.function.name || tool === PROPOSE_WRITE.function.name) {
+		if (tool === EDIT_NOTE.function.name || tool === WRITE_NOTE.function.name) {
 			const str = (v, name) => {
 				if (typeof v !== "string") throw new EngineError(`${tool} needs ${name}, as text`, 400);
 				return v;
 			};
-			const edit = tool === PROPOSE_WRITE.function.name ? { content: str(args.content, "content") } : {
+			const edit = tool === WRITE_NOTE.function.name ? { content: str(args.content, "content") } : {
 				oldString: str(args.oldString, "oldString"),
 				newString: str(args.newString, "newString"),
 				replaceAll: args.replaceAll === true
 			};
-			return this.agentPropose({
+			return this.agentWrite({
 				agent,
 				session,
 				note: str(args.note, "note"),
@@ -3419,44 +3682,43 @@ var Engine = class Engine {
 			});
 		}
 	}
-	async agentPropose({ agent, session, note, asked, edit }) {
-		if (!this.opts.study) throw new EngineError("there is no study base, so an edit to a note cannot wait to be kept: show the person the change instead", 409);
-		const id = checkNoteId(note.replace(/^\/+/, "").replace(/\.md$/i, ""));
-		const who = `agent:${agent}`, read = this.turns.get(`${agent}/${session}`)?.lookup.read() ?? [];
+	async agentWrite({ agent, session, note, asked, edit }) {
+		const who = `agent:${agent}`;
+		const raw = note.replace(/^\/+/, "").replace(/\.md$/i, "");
+		const existing = noteId(this.bundle, raw) ?? await this.onDisk(raw);
+		if (!existing) {
+			if (!("content" in edit)) throw new EngineError(`there is no note ${raw}: to make one, write the whole of it`, 404);
+			const id = this.newNoteId(raw);
+			if (!id) throw new EngineError(`${raw} is not a note's id in this base: give folder/name, lower case with hyphens`, 400);
+			let text = edit.content;
+			if (!/^---\n/.test(text)) text = `---\ntype: Concept\ntitle: ${JSON.stringify(/^#\s+(.+)$/m.exec(text)?.[1]?.trim() ?? id.split("/").at(-1).replace(/-/g, " "))}\n---\n\n${text.replace(/^#\s+.+\n+/, "")}`;
+			await this.one(() => this.put(id, text, null, "edit", { asked }, who));
+			return { text: `Made ${this.titleOf(id, text)} (/${id}.md). The person sees it as yours, and can undo it.` };
+		}
+		const id = existing, now = await this.readNote(id);
+		let text;
+		if ("content" in edit) text = edit.content;
+		else {
+			const at = now.text.indexOf(edit.oldString);
+			if (!edit.oldString || at < 0) throw new EngineError(`that passage is not in ${this.titleOf(id, now.text)} as you wrote it: read the note again and give the passage exactly`, 409);
+			if (edit.replaceAll) text = now.text.split(edit.oldString).join(edit.newString);
+			else {
+				if (now.text.indexOf(edit.oldString, at + 1) >= 0) throw new EngineError(`that passage occurs more than once in ${this.titleOf(id, now.text)}: give more of it, or replaceAll`, 409);
+				text = now.text.slice(0, at) + edit.newString + now.text.slice(at + edit.oldString.length);
+			}
+		}
+		return { text: (await this.one(() => this.put(id, text, now.version, "edit", { asked }, who))).changed ? `Changed ${this.titleOf(id, text)}. The person sees your words marked, and can undo it.` : `That leaves ${this.titleOf(id, now.text)} as it is.` };
+	}
+	/** A note's id when its file is there, though the index may not have it yet; else null. */
+	async onDisk(raw) {
+		let id;
+		try {
+			id = checkNoteId(raw);
+		} catch {
+			return null;
+		}
 		const { files, path } = this.where(id);
-		if (await files.read(path) === null) {
-			if (!("content" in edit)) throw new EngineError(`there is no note ${id}: to propose a new note, write the whole of it`, 404);
-			let meta = null, body = edit.content;
-			try {
-				[meta, body] = splitFrontmatter(edit.content);
-			} catch {}
-			const title = typeof meta?.title === "string" && meta.title ? meta.title : id.split("/").at(-1);
-			const draft = DRAFT_PREFIX + newId(this.opts.clock.now()).toLowerCase();
-			await this.createNote(draft, `---\ntype: ${typeof meta?.type === "string" ? meta.type : "Concept"}\ntitle: ${JSON.stringify(title)}\n---\n`);
-			await this.one(async () => this.enter(draft, await this.journal(draft), {
-				...await this.stamp(who),
-				kind: "proposal",
-				form: "insert",
-				after: null,
-				before: null,
-				text: body.replace(/^\n+/, ""),
-				asked: asked || `a new note at ${id}`,
-				read
-			}));
-			return { text: `The new note "${title}" waits for the person to review in the browser, as a note for review; they choose its folder when they keep it (you meant ${id.split("/").slice(0, -1).join("/") || "the top"}). Nothing was written to the knowledge base. Do not write it again.` };
-		}
-		const current = (await this.readNote(id)).text;
-		const regions = regionsOf(current, edit);
-		if (!regions.length) return { text: `That leaves ${this.titleOf(id, current)} as it is: nothing was proposed.` };
-		await this.one(async () => this.enter(id, await this.journal(id), {
-			...await this.stamp(who),
-			kind: "proposal",
-			form: "rewrite",
-			regions,
-			asked: asked || "an edit",
-			read
-		}));
-		return { text: `Your edit to ${this.titleOf(id, current)} (${regions.length} ${regions.length === 1 ? "passage" : "passages"}) waits for the person to keep it, in the browser or the terminal's note view. The file is unchanged until they do. Do not write it again; go on as if it may not be kept.` };
+		return await files.read(path) === null ? null : id;
 	}
 	async agentSend({ note, passage, said }) {
 		const id = checkNoteId(note), concept = this.bundle.concepts.get(id);
@@ -3521,7 +3783,8 @@ var Engine = class Engine {
 	createNote(id, text) {
 		return this.one(() => this.put(id, text, null));
 	}
-	async moveNote(id, to, base) {
+	/** `who` is you unless Iso moves it, in Write mode. */
+	async moveNote(id, to, base, who = "you") {
 		to = to.trim().replace(/^\/+|\/+$/g, "").replace(/\.md$/, "");
 		if (!inBase(id) || !inBase(to)) throw new EngineError("only a note of the base is moved, and only within it");
 		checkNoteId(to);
@@ -3549,7 +3812,7 @@ var Engine = class Engine {
 				}
 				const hash = hashText(now);
 				await this.enter(to, entries, {
-					...await this.stamp("you"),
+					...await this.stamp(who),
 					kind: "change",
 					why: "move",
 					before: hash,
@@ -3574,13 +3837,13 @@ var Engine = class Engine {
 				type: "note-changed",
 				id,
 				version: null,
-				who: "you"
+				who
 			});
 			this.publish({
 				type: "note-changed",
 				id: to,
 				version: hashText(now),
-				who: "you"
+				who
 			});
 			return now;
 		});
@@ -3588,10 +3851,7 @@ var Engine = class Engine {
 		for (const c of linking) {
 			const source = await this.readNote(c);
 			const changed = source.text.replace(old, `](/${to}.md`);
-			if (changed !== source.text) await this.saveNote(c, {
-				base: source.version,
-				text: changed
-			});
+			if (changed !== source.text) await this.one(() => this.put(c, changed, source.version, "edit", {}, who));
 		}
 		if (study) for (const ex of Bundle.fromFiles(await walk(study, STUDY_DIR)).concepts.values()) {
 			if (!testsOf(ex.meta).includes(id)) continue;
@@ -3609,7 +3869,7 @@ var Engine = class Engine {
 			changed: true
 		};
 	}
-	async deleteNote(id, base) {
+	async deleteNote(id, base, who = "you") {
 		if (!inBase(id)) throw new EngineError("only a note of the base is deleted here");
 		const notes = this.opts.notes, path = `${checkNoteId(id)}.md`;
 		await this.one(async () => {
@@ -3631,7 +3891,7 @@ var Engine = class Engine {
 			type: "note-changed",
 			id,
 			version: null,
-			who: "you"
+			who
 		});
 	}
 	/** Writes happen one at a time, in the order asked. */
@@ -3646,7 +3906,7 @@ var Engine = class Engine {
 			if (!this.opts.study) throw new EngineError("there is no study base open", 404);
 			return {
 				files: this.opts.study,
-				path: `${isDraftId(id) ? DRAFT_DIR : STUDY_DIR}/${checkNoteId(bare(id))}.md`
+				path: `${isDraftId(id) ? DRAFT_DIR : isUnderstandingId(id) ? UNDERSTANDING_DIR : STUDY_DIR}/${checkNoteId(bare(id))}.md`
 			};
 		}
 		return {
@@ -3666,7 +3926,7 @@ var Engine = class Engine {
 	restore(id, entry, base) {
 		return this.one(async () => this.put(id, await this.version(id, entry), base, "restore", { to: entry }));
 	}
-	async put(id, text, base, why = "edit", extra = {}) {
+	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);
 		const now = await files.read(path);
@@ -3686,7 +3946,8 @@ var Engine = class Engine {
 			changed: false
 		};
 		await files.write(path, text);
-		await this.enter(id, entries, change(entries, text, await this.stamp("you"), why, extra));
+		const entry = change(entries, text, await this.stamp(who), why, extra);
+		await this.enter(id, entries, entry);
 		if (inBase(id)) {
 			this.files.set(path, {
 				path,
@@ -3700,13 +3961,14 @@ var Engine = class Engine {
 			type: "note-changed",
 			id,
 			version,
-			who: "you"
+			who
 		});
 		return {
 			id,
 			text,
 			version,
-			changed: true
+			changed: true,
+			...entry ? { entry: entry.id } : {}
 		};
 	}
 	get provider() {
@@ -3808,7 +4070,7 @@ var Engine = class Engine {
 		if (!key && /\/\/(?:[^/]*\.)?openrouter\.ai\b/.test(this.provider.url)) throw new EngineError("There is no provider key yet. Set one in settings, behind the logo.", 409);
 		const { messages, olds, text: sent } = await this.compose(req, asked);
 		const maxTokens = req.form === "insert" ? REPLY_TOKENS : req.form === "note" ? NOTE_TOKENS : req.form === "mark" ? MARK_TOKENS : req.form === "exercise" ? EXERCISE_TOKENS : Math.max(REPLY_TOKENS, Math.ceil(olds.join("").length / 3) + 1e3);
-		const most = req.form === "mark" || req.form === "exercise" ? 0 : void 0;
+		const most = req.form === "mark" || req.form === "exercise" || (req.form === "insert" || req.form === "rewrite") && req.choice?.lookup === false ? 0 : void 0;
 		const request = newId(this.opts.clock.now()), abort = new AbortController();
 		this.running.set(request, abort);
 		this.asking.set(req.note, request);
@@ -4042,20 +4304,7 @@ var Engine = class Engine {
 				body = splitFrontmatter(text)[1];
 			} catch {}
 			if (!body.trim()) throw new EngineError("write what you want from Iso first");
-			const linked = [];
-			let room = LINKED_BUDGET;
-			for (const m of body.matchAll(/\]\(\/([^)\s#]+)\.md(?:#[^)\s]*)?(?:\s+"[^"]*")?\)/g)) {
-				const c = this.bundle.concepts.get(decodeURIComponent(m[1]));
-				if (!c || linked.some((l) => l.id === c.id)) continue;
-				const piece = c.body.trim().slice(0, Math.max(0, room) * 4);
-				if (piece.length < Math.min(c.body.trim().length, 400)) break;
-				linked.push({
-					id: c.id,
-					title: c.title,
-					text: piece + (piece.length < c.body.trim().length ? "\n[…cut: read the rest with read_note]" : "")
-				});
-				room -= estimate(piece);
-			}
+			const linked = this.linkedSent(body);
 			const earlier = await this.exchangesNow();
 			return {
 				...noteMessages({
@@ -4105,8 +4354,12 @@ var Engine = class Engine {
 		}
 		const title = this.titleOf(req.note, text);
 		const entries = await this.journal(req.note);
-		const earlier = await this.exchangesNow();
-		const read = new Set(entries.flatMap((e) => e.kind === "proposal" && earlier.some((x) => x.id === e.id) ? e.read ?? [] : []));
+		const off = new Set(req.choice?.off ?? []);
+		const earlier = (await this.exchangesNow()).filter((x) => !off.has(`x:${x.id}`));
+		let body = text;
+		try {
+			body = splitFrontmatter(text)[1];
+		} catch {}
 		const given = {
 			tier: req.tier,
 			meaning: Boolean(this.similar),
@@ -4117,10 +4370,8 @@ var Engine = class Engine {
 			unkept: pending(entries).map((p) => p.form === "insert" ? p.text : p.regions.map((r) => r.new).join("\n\n")),
 			conversation: conversation(earlier),
 			moments: earlier.length,
-			linked: {
-				notes: read.size,
-				tokens: [...read].reduce((n, id) => n + estimate(this.bundle.concepts.get(id)?.body ?? ""), 0)
-			}
+			linked: this.linkedSent(body, off, req.note),
+			lookup: req.choice?.lookup !== false
 		};
 		return {
 			...req.form === "insert" ? insertMessages(given) : rewriteMessages({
@@ -4131,6 +4382,37 @@ var Engine = class Engine {
 			olds
 		};
 	}
+	/** The notes a note's text links to, each once, in order: the note itself left out. */
+	linksOf(body, self = "") {
+		const out = [];
+		for (const m of body.matchAll(/\]\(\/([^)\s#]+)\.md(?:#[^)\s]*)?(?:\s+"[^"]*")?\)/g)) {
+			const c = this.bundle.concepts.get(decodeURIComponent(m[1]));
+			if (c && c.id !== self && !out.some((l) => l.id === c.id)) out.push({
+				id: c.id,
+				title: c.title,
+				body: c.body.trim()
+			});
+		}
+		return out;
+	}
+	/** The linked notes sent with a request, those switched off left out, as far as there is room; the rest Iso
+	*  reads with its tools. */
+	linkedSent(body, off = /* @__PURE__ */ new Set(), self = "") {
+		const linked = [];
+		let room = LINKED_BUDGET;
+		for (const c of this.linksOf(body, self)) {
+			if (off.has(`n:${c.id}`)) continue;
+			const piece = c.body.slice(0, Math.max(0, room) * 4);
+			if (piece.length < Math.min(c.body.length, 400)) break;
+			linked.push({
+				id: c.id,
+				title: c.title,
+				text: piece + (piece.length < c.body.length ? "\n[…cut: read the rest with read_note]" : "")
+			});
+			room -= estimate(piece);
+		}
+		return linked;
+	}
 	titleOf(id, text) {
 		try {
 			const t = splitFrontmatter(text)[0]?.title;
@@ -4208,22 +4490,43 @@ var Engine = class Engine {
 		if (!this.opts.study) return;
 		this.cleared = await this.one(() => this.record({ event: "context-cleared" }));
 	}
-	async context(note) {
-		let parts = null;
+	async context(note, choice) {
+		let parts = null, items = [];
 		if (note && isDraftId(note)) parts = await this.exerciseDraft(note).catch(() => null) ? await this.readNote(note).then(async (s) => (await this.exerciseCompose(note, s.text, await this.exerciseAsked(note))).parts, () => null) : await this.compose({
 			note,
 			form: "note",
 			tier: "mid"
 		}, "").then((c) => c.parts, () => null);
 		else if (note && isStudyId(note)) parts = await this.readNote(note).then(async (s) => (await this.markCompose(note, s.text, null)).parts, () => null);
-		else if (note) ({parts} = await this.compose({
-			note,
-			form: "insert",
-			after: null,
-			before: null,
-			asked: "",
-			tier: "mid"
-		}, ""));
+		else if (note) {
+			({parts} = await this.compose({
+				note,
+				form: "insert",
+				after: null,
+				before: null,
+				asked: "",
+				tier: "mid",
+				...choice ? { choice } : {}
+			}, ""));
+			const off = new Set(choice?.off ?? []);
+			let body = (await this.readNote(note)).text;
+			try {
+				body = splitFrontmatter(body)[1];
+			} catch {}
+			items = [...(await this.exchangesNow()).map((x) => ({
+				id: `x:${x.id}`,
+				kind: "exchange",
+				title: x.text.split("\n")[0].replace(/^In (.+?) \(\/[^)]*\) they asked[^:]*: /, "$1: "),
+				tokens: estimate(x.text),
+				on: !off.has(`x:${x.id}`)
+			})), ...this.linksOf(body, note).map((c) => ({
+				id: `n:${c.id}`,
+				kind: "linked",
+				title: c.title,
+				tokens: estimate(c.body),
+				on: !off.has(`n:${c.id}`)
+			}))];
+		}
 		if (!parts) {
 			const earlier = await this.exchangesNow();
 			({parts} = insertMessages({
@@ -4243,6 +4546,18 @@ var Engine = class Engine {
 				tokens: 0
 			} : p);
 		}
+		return {
+			tokens: parts.reduce((n, p) => n + p.tokens, 0),
+			limit: this.provider.context ?? 2e5,
+			parts,
+			session: await this.sessionCost(),
+			items,
+			lookup: choice?.lookup !== false
+		};
+	}
+	/** What the session has cost: every reply offered, kept or not, every turn in Iso's pane, and every reply that came
+	*  to nothing. */
+	async sessionCost() {
 		const session = await this.sessionNow();
 		let usd = 0, requests = 0;
 		for (const entries of (await this.sessionEntries()).values()) for (const e of entries) if ((e.kind === "proposal" && !e.copyOf || e.kind === "marks") && e.cost) {
@@ -4250,20 +4565,683 @@ var Engine = class Engine {
 			requests++;
 		}
 		const text = this.opts.study ? await this.opts.study.read(recordPath(this.opts.device)) : null;
-		for (const e of readRecord(text ?? "")) if (e.event === "iso-unused" && e.session === session) {
+		for (const e of readRecord(text ?? "")) if ((e.event === "iso-unused" || e.event === "iso-turn") && e.session === session) {
 			usd += typeof e.usd === "number" ? e.usd : 0;
 			requests++;
 		}
 		return {
-			tokens: parts.reduce((n, p) => n + p.tokens, 0),
-			limit: this.provider.context ?? 2e5,
-			parts,
-			session: {
-				usd,
-				requests
-			}
+			usd,
+			requests
 		};
 	}
+	/** The turn running in each conversation: one at a time. */
+	conversing = /* @__PURE__ */ new Map();
+	/** What Iso asked before doing something, waiting for your answer, by the permission's id. */
+	waitingAnswer = /* @__PURE__ */ new Map();
+	async conversation(id) {
+		const study = this.opts.study;
+		if (!study) return null;
+		if (!id) {
+			id = (await study.list(CONVERSATIONS_DIR).catch(() => [])).filter((f) => !f.dir && f.name.endsWith(".jsonl")).map((f) => f.name.slice(0, -6)).sort().at(-1);
+			if (!id) return null;
+		}
+		if (!TURN_ID.test(id)) throw new EngineError("not a conversation's id");
+		const text = await study.read(conversationPath(id));
+		return text === null ? null : {
+			id,
+			turns: readTurns(text).map((t) => this.running.has(t.id) ? {
+				...t,
+				state: "running"
+			} : t)
+		};
+	}
+	/** What was given, checked: notes and passages of the base, and its folders. */
+	given(raw) {
+		if (!Array.isArray(raw) || raw.length > 40) throw new EngineError("give Iso between none and forty notes, folders and passages");
+		return raw.map((g) => {
+			const id = typeof g?.id === "string" ? g.id.replace(/^\/+|\/+$/g, "") : "";
+			if (g?.kind === "folder") {
+				if (id) checkNoteId(id);
+				return {
+					kind: "folder",
+					id
+				};
+			}
+			if (!inBase(checkNoteId(id))) throw new EngineError("only notes of the base are given to Iso");
+			if (g?.kind === "note") return {
+				kind: "note",
+				id
+			};
+			if (g?.kind === "understanding") return {
+				kind: "understanding",
+				id
+			};
+			if (g?.kind === "passage" && typeof g.text === "string" && g.text.trim() && g.text.length <= 2e4) return {
+				kind: "passage",
+				id,
+				text: g.text
+			};
+			throw new EngineError("a part given to Iso is a note, a folder or a passage");
+		});
+	}
+	/** What was given, read now, as it is sent. A note that is gone is left out. */
+	async sentOf(given) {
+		const out = [];
+		for (const g of given) {
+			if (g.kind === "folder") {
+				const under = g.id ? `${g.id}/` : "";
+				out.push({
+					kind: "folder",
+					id: g.id,
+					notes: [...this.bundle.concepts.values()].filter((c) => c.id.startsWith(under) && inBase(c.id)).map((c) => ({
+						id: c.id,
+						title: c.title,
+						description: c.description
+					}))
+				});
+				continue;
+			}
+			const c = this.bundle.concepts.get(g.id);
+			if (!c) continue;
+			if (g.kind === "understanding") {
+				const u = await this.understanding(g.id);
+				const said = (e) => `${e.at.slice(0, 10)}: ${e.by > 0 ? "+" : ""}${e.by}${e.event === "wind-back" ? " (they wound you back)" : e.event === "attempt" ? " (an exercise)" : ""}${e.why ? `, ${e.why}` : ""}`;
+				out.push({
+					kind: "understanding",
+					id: g.id,
+					title: c.title,
+					reading: u.reading,
+					events: u.evidence.slice(-8).reverse().map(said),
+					squares: u.squares
+				});
+				continue;
+			}
+			if (g.kind === "passage") out.push({
+				kind: "passage",
+				id: g.id,
+				title: c.title,
+				text: g.text
+			});
+			else out.push({
+				kind: "note",
+				id: g.id,
+				title: c.title,
+				text: (await this.readNote(g.id)).text
+			});
+		}
+		return out;
+	}
+	async turnContext(req) {
+		const mode = req.mode === "build" ? "ask" : req.mode;
+		const all = req.conversation ? (await this.conversation(req.conversation))?.turns ?? [] : [];
+		const off = new Set(req.off ?? []), earlier = all.filter((t) => !off.has(t.id));
+		const sent = await this.sentOf(this.given(req.given ?? []));
+		const { parts } = turnMessages({
+			mode,
+			tier: req.tier,
+			meaning: Boolean(this.similar),
+			lookup: req.lookup !== false,
+			earlier,
+			sent,
+			asked: ""
+		});
+		const items = all.map((t) => ({
+			id: t.id,
+			kind: "exchange",
+			title: t.asked,
+			tokens: estimate(turnExchange(t).text),
+			on: !off.has(t.id)
+		}));
+		return {
+			tokens: parts.reduce((n, p) => n + p.tokens, 0),
+			limit: this.provider.context ?? 2e5,
+			parts,
+			session: await this.sessionCost(),
+			items,
+			lookup: req.lookup !== false,
+			given: sent.map((g) => ({
+				kind: g.kind,
+				id: g.id,
+				...g.kind === "passage" ? { text: g.text } : {},
+				tokens: estimate(sentText(g))
+			}))
+		};
+	}
+	async converse(req) {
+		const http = this.opts.http, study = this.opts.study;
+		if (!http) throw new EngineError("Iso cannot be asked here", 409);
+		if (!study) throw new EngineError("Iso's conversations are kept in a study base, and none is open (isorite study init)", 409);
+		if (!MODES.includes(req.mode)) throw new EngineError("the mode is ask, write, build or understand");
+		if (req.mode === "build") throw new EngineError("Build mode is the terminal's: start isorite term", 409);
+		if (!TIERS.includes(req.tier)) throw new EngineError("the tier is low, mid or max");
+		const asked = String(req.asked ?? "").trim();
+		if (!asked) throw new EngineError("say what you want from Iso");
+		if (asked.length > 4e3) throw new EngineError("that is too long to ask at once", 413);
+		const given = this.given(req.given ?? []);
+		if (req.conversation !== void 0 && !TURN_ID.test(req.conversation)) throw new EngineError("not a conversation's id");
+		const conversation = req.conversation ?? newId(this.opts.clock.now());
+		if (this.conversing.has(conversation)) throw new EngineError("Iso is still answering in this conversation. Wait for it, or stop it.", 409);
+		this.conversing.set(conversation, "");
+		try {
+			return {
+				conversation,
+				turn: await this.beginTurn(conversation, {
+					...req,
+					mode: req.mode,
+					asked,
+					given
+				}, http)
+			};
+		} catch (err) {
+			this.conversing.delete(conversation);
+			throw err;
+		}
+	}
+	async beginTurn(conversation, req, http) {
+		const study = this.opts.study;
+		const key = await this.opts.secrets?.get("provider.key") ?? null;
+		if (!key && /\/\/(?:[^/]*\.)?openrouter\.ai\b/.test(this.provider.url)) throw new EngineError("There is no provider key yet. Set one in settings, behind the logo.", 409);
+		const off = new Set(req.off ?? []), earlier = ((await this.conversation(conversation))?.turns ?? []).filter((t) => !off.has(t.id));
+		const lookupOn = req.lookup !== false, mode = req.mode;
+		const { messages } = turnMessages({
+			mode,
+			tier: req.tier,
+			meaning: Boolean(this.similar),
+			lookup: lookupOn,
+			earlier,
+			sent: await this.sentOf(req.given),
+			asked: req.asked
+		});
+		const s = await this.stamp("you"), turn = s.id, abort = new AbortController(), path = conversationPath(conversation);
+		this.last = {
+			at: s.at,
+			session: s.session
+		};
+		const line = (l) => this.one(() => study.append(path, JSON.stringify(l) + "\n"));
+		await line({
+			kind: "turn",
+			id: turn,
+			conversation,
+			at: s.at,
+			session: s.session,
+			mode,
+			asked: req.asked,
+			given: req.given,
+			tier: req.tier
+		});
+		this.running.set(turn, abort);
+		this.conversing.set(conversation, turn);
+		this.publish({
+			type: "iso-start",
+			request: turn,
+			note: "",
+			asked: req.asked,
+			tier: req.tier,
+			place: {
+				form: "turn",
+				conversation,
+				mode,
+				given: req.given
+			}
+		});
+		const item = async (i) => {
+			await line({
+				kind: "item",
+				turn,
+				item: i
+			});
+			this.publish({
+				type: "iso-item",
+				request: turn,
+				conversation,
+				item: i
+			});
+		};
+		const who = `iso:${this.provider.name}/${this.provider.tiers[req.tier]}`;
+		const lookup = new Lookup(this.bundle, req.given.find((g) => g.kind !== "folder")?.id ?? "", this.similar);
+		const looks = new Set(lookup.defs().map((d) => d.function.name));
+		const tools = {
+			defs: () => [...lookupOn ? lookup.defs() : [], ...MODE_TOOLS[mode]],
+			call: async (name, raw) => {
+				if (looks.has(name)) return lookupOn ? lookup.call(name, raw) : { text: "Looking things up is off: they chose what you are sent." };
+				let args = {};
+				try {
+					const parsed = raw.trim() ? JSON.parse(raw) : {};
+					if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) args = parsed;
+				} catch {}
+				if (!MODE_TOOLS[mode].some((d) => d.function.name === name)) return { text: `There is no tool ${name} in ${mode} mode.` };
+				return { text: await this.turnTool(name, args, {
+					turn,
+					conversation,
+					mode,
+					item,
+					signal: abort.signal,
+					who,
+					asked: req.asked
+				}) };
+			}
+		};
+		(async () => {
+			try {
+				const got = await rounds({
+					http,
+					provider: this.provider,
+					key,
+					tier: req.tier,
+					messages,
+					lookup: tools,
+					maxTokens: REPLY_TOKENS * 2,
+					signal: abort.signal,
+					most: ROUNDS[req.tier],
+					onText: (delta, again) => this.publish({
+						type: "iso-text",
+						request: turn,
+						note: "",
+						delta,
+						again
+					}),
+					onStep: (step) => {
+						item({
+							kind: "look",
+							step
+						});
+						this.publish({
+							type: "iso-step",
+							request: turn,
+							note: "",
+							step
+						});
+					}
+				});
+				if (abort.signal.aborted) throw Object.assign(/* @__PURE__ */ new Error("stopped"), { name: "AbortError" });
+				const cost = {
+					model: got.usage.model,
+					tier: req.tier,
+					tokensIn: got.usage.tokensIn,
+					tokensOut: got.usage.tokensOut,
+					tokensCached: got.usage.tokensCached,
+					usd: got.usage.usd
+				};
+				const said = got.text.trim() + (got.cut ? "\n\n[Cut off at its length limit.]" : "");
+				if (said) await item({
+					kind: "text",
+					text: said
+				});
+				await line({
+					kind: "end",
+					turn,
+					state: "done",
+					cost
+				});
+				if (cost.usd > 0) await this.one(async () => this.record({
+					event: "iso-turn",
+					conversation,
+					turn,
+					session: s.session,
+					model: cost.model,
+					usd: cost.usd
+				}));
+				this.publish({
+					type: "iso-done",
+					request: turn,
+					note: "",
+					proposal: "",
+					cost
+				});
+			} catch (err) {
+				const stopped = abort.signal.aborted || err.name === "AbortError";
+				const message = err.message || "Iso could not answer";
+				await line(stopped ? {
+					kind: "end",
+					turn,
+					state: "stopped"
+				} : {
+					kind: "end",
+					turn,
+					state: "failed",
+					message
+				}).catch(() => void 0);
+				if (stopped) this.publish({
+					type: "iso-stopped",
+					request: turn,
+					note: ""
+				});
+				else this.publish({
+					type: "iso-failed",
+					request: turn,
+					note: "",
+					message
+				});
+			} finally {
+				this.running.delete(turn);
+				this.conversing.delete(conversation);
+				for (const [id, w] of this.waitingAnswer) if (w.turn === turn) {
+					this.waitingAnswer.delete(id);
+					w.settle("reject");
+				}
+			}
+		})();
+		return turn;
+	}
+	/** What you allowed for the rest of a conversation ("always"): by conversation, the tools. */
+	allowed = /* @__PURE__ */ new Map();
+	/** Ask you before doing something; wait for your answer. "always" holds for the rest of the conversation. */
+	async permit(t, tool, note, what) {
+		if (this.allowed.get(t.conversation)?.has(tool)) return "always";
+		const id = newId(this.opts.clock.now());
+		const answer = new Promise((settle) => this.waitingAnswer.set(id, {
+			turn: t.turn,
+			conversation: t.conversation,
+			settle
+		}));
+		await t.item({
+			kind: "permission",
+			id,
+			tool,
+			note,
+			what
+		});
+		const stop = new Promise((settle) => t.signal.addEventListener("abort", () => settle("reject"), { once: true }));
+		const d = await Promise.race([answer, stop]);
+		this.waitingAnswer.delete(id);
+		if (d === "always") this.allowed.set(t.conversation, /* @__PURE__ */ new Set([...this.allowed.get(t.conversation) ?? [], tool]));
+		return d;
+	}
+	/** A note's id as Iso writes one for a new note: folder/name, without a leading slash or `.md`. */
+	newNoteId(raw) {
+		const id = String(raw ?? "").trim().replace(/^\/+|\/+$/g, "").replace(/\.md$/i, "");
+		try {
+			checkNoteId(id);
+		} catch {
+			return null;
+		}
+		return inBase(id) ? id : null;
+	}
+	/** One of a mode's own tools, in a turn: what is said back to Iso. */
+	async turnTool(name, args, t) {
+		const title = (id) => this.bundle.concepts.get(id)?.title ?? id;
+		if (name === "point_to_note") {
+			const id = noteId(this.bundle, args.id);
+			if (!id) return `There is no note ${String(args.id ?? "")}.`;
+			await t.item({
+				kind: "point",
+				note: id,
+				why: String(args.why ?? "").trim().slice(0, 300)
+			});
+			return `${title(id)} is marked on their Atlas.`;
+		}
+		const counted = (before, after) => {
+			const hunks = diffLines(before.split("\n"), after.split("\n"));
+			return {
+				added: hunks.reduce((n, h) => n + h.ins.length, 0),
+				removed: hunks.reduce((n, h) => n + h.del.length, 0)
+			};
+		};
+		if (name === "edit_note") {
+			const id = noteId(this.bundle, args.id);
+			if (!id) return `There is no note ${String(args.id ?? "")}. Search for it by its words.`;
+			const old = String(args.old ?? ""), next = String(args.new ?? "");
+			if (!old) return "Give the passage as it is now, in old.";
+			const now = await this.readNote(id);
+			const at = now.text.indexOf(old), again = at < 0 ? -1 : now.text.indexOf(old, at + 1);
+			if (at < 0) return `That passage is not in ${title(id)} as you wrote it. Read the note again and give the passage exactly.`;
+			if (again >= 0) return `That passage occurs more than once in ${title(id)}. Give more of it, so it is found once.`;
+			const text = now.text.slice(0, at) + next + now.text.slice(at + old.length);
+			const saved = await this.one(() => this.put(id, text, now.version, "edit", { asked: t.asked }, t.who));
+			if (saved.entry) await t.item({
+				kind: "change",
+				note: id,
+				entry: saved.entry,
+				why: "edit",
+				title: title(id),
+				...counted(now.text, text)
+			});
+			return `Changed ${title(id)}.`;
+		}
+		if (name === "write_note") {
+			const id = this.newNoteId(args.id);
+			if (!id) return `${String(args.id ?? "")} is not a note's id in their base: give folder/name, lower case with hyphens.`;
+			let text = String(args.text ?? "");
+			if (!text.trim()) return "Give the note's whole text.";
+			if (!/^---\n/.test(text)) text = `---\ntype: Concept\ntitle: ${JSON.stringify(/^#\s+(.+)$/m.exec(text)?.[1]?.trim() ?? id.split("/").at(-1).replace(/-/g, " "))}\n---\n\n${text.replace(/^#\s+.+\n+/, "")}`;
+			const was = this.bundle.concepts.has(id) ? await this.readNote(id) : null;
+			const saved = await this.one(() => this.put(id, text, was?.version ?? null, "edit", { asked: t.asked }, t.who));
+			if (saved.entry) await t.item({
+				kind: "change",
+				note: id,
+				entry: saved.entry,
+				why: was ? "edit" : "create",
+				title: title(id),
+				...counted(was?.text ?? "", text)
+			});
+			return was ? `Wrote ${title(id)} anew.` : `Made ${title(id)} (/${id}.md).`;
+		}
+		if (name === "move_note") {
+			const id = noteId(this.bundle, args.id), to = this.newNoteId(args.to);
+			if (!id) return `There is no note ${String(args.id ?? "")}.`;
+			if (!to) return `${String(args.to ?? "")} is not a note's id in their base.`;
+			if (await this.permit(t, "move_note", id, `move ${title(id)} to ${to}`) === "reject") return "They did not allow it. It was not moved.";
+			const now = await this.readNote(id), before = title(id);
+			try {
+				await this.moveNote(id, to, now.version, t.who);
+			} catch (e) {
+				return `It could not be moved: ${e.message}`;
+			}
+			const entry = (await this.journal(to)).at(-1)?.id ?? "";
+			await t.item({
+				kind: "change",
+				note: to,
+				entry,
+				why: "move",
+				to,
+				title: before,
+				added: 0,
+				removed: 0
+			});
+			return `Moved ${before} to /${to}.md.`;
+		}
+		if (name === "delete_note") {
+			const id = noteId(this.bundle, args.id);
+			if (!id) return `There is no note ${String(args.id ?? "")}.`;
+			if (await this.permit(t, "delete_note", id, `delete ${title(id)}`) === "reject") return "They did not allow it. It was not deleted.";
+			const now = await this.readNote(id), before = title(id);
+			try {
+				await this.deleteNote(id, now.version, t.who);
+			} catch (e) {
+				return `It could not be deleted: ${e.message}`;
+			}
+			await t.item({
+				kind: "change",
+				note: id,
+				entry: (await this.journal(id)).at(-1)?.id ?? "",
+				why: "delete",
+				title: before,
+				added: 0,
+				removed: now.text.split("\n").length
+			});
+			return `Deleted ${before}. Its history stays.`;
+		}
+		if (name === "record_understanding") {
+			const id = noteId(this.bundle, args.id);
+			if (!id) return `There is no note ${String(args.id ?? "")}.`;
+			const by = Number(args.by);
+			if (![
+				-1,
+				-.5,
+				0,
+				.5,
+				1
+			].includes(by)) return "by is one of -1, -0.5, 0, 0.5, 1.";
+			const why = String(args.why ?? "").trim().slice(0, 300);
+			if (this.recorded.get(t.turn)?.has(id)) return `You recorded ${title(id)} once this turn already.`;
+			this.recorded.set(t.turn, /* @__PURE__ */ new Set([...this.recorded.get(t.turn) ?? [], id]));
+			const event = await this.one(() => this.record({
+				event: "understood",
+				note: id,
+				by,
+				why,
+				conversation: t.conversation,
+				turn: t.turn
+			}));
+			await t.item({
+				kind: "understood",
+				note: id,
+				event,
+				by,
+				why
+			});
+			return `Recorded for ${title(id)}.`;
+		}
+		if (name === "write_understanding") {
+			const id = noteId(this.bundle, args.id);
+			if (!id) return `There is no note ${String(args.id ?? "")}.`;
+			const reading = String(args.reading ?? "").trim();
+			if (!reading) return "Give your reading.";
+			const uid = understandingId(id), was = await this.readNote(uid).catch(() => null);
+			const text = understandingText(id, title(id), {
+				...parseUnderstanding(was?.text ?? null),
+				reading
+			});
+			const saved = await this.one(() => this.put(uid, text, was?.version ?? null, "edit", {}, t.who));
+			if (saved.entry) await t.item({
+				kind: "change",
+				note: uid,
+				entry: saved.entry,
+				why: was ? "edit" : "create",
+				title: `Understanding · ${title(id)}`,
+				added: 0,
+				removed: 0
+			});
+			return `Your reading of ${title(id)} is written.`;
+		}
+		return `${name} cannot be used yet.`;
+	}
+	/** The notes each turn recorded understanding of: once a note a turn. */
+	recorded = /* @__PURE__ */ new Map();
+	/** A note's Understanding note (M10): Iso's reading, your scratchpad, and what the record says of it. */
+	async understanding(note) {
+		if (!inBase(checkNoteId(note))) throw new EngineError("only a note of the base has an Understanding note");
+		const uid = understandingId(note);
+		const source = this.opts.study ? await this.readNote(uid).catch(() => null) : null;
+		const read = (await this.study()).notes[note];
+		return {
+			note,
+			...parseUnderstanding(source?.text ?? null),
+			version: source?.version ?? null,
+			level: read?.level ?? 0,
+			squares: read?.squares ?? 0,
+			step: read?.step ?? 0,
+			due: read?.due ?? false,
+			evidence: read?.evidence ?? []
+		};
+	}
+	/** Your scratchpad in a note's Understanding note: yours alone; Iso does not write it. `base` as for saveNote, or
+	*  null when there is no Understanding note yet. */
+	async saveScratchpad(note, scratchpad, base) {
+		if (!this.opts.study) throw new EngineError("there is no study base open", 409);
+		if (!inBase(checkNoteId(note))) throw new EngineError("only a note of the base has an Understanding note");
+		const uid = understandingId(note), was = await this.readNote(uid).catch(() => null);
+		const title = this.bundle.concepts.get(note)?.title ?? note;
+		await this.one(() => this.put(uid, understandingText(note, title, {
+			...parseUnderstanding(was?.text ?? null),
+			scratchpad
+		}), base));
+		return this.understanding(note);
+	}
+	async undoTurn(conversation, turn) {
+		const t = (await this.conversation(conversation))?.turns.find((x) => x.id === turn);
+		if (!t) throw new EngineError("there is no such turn", 404);
+		if (t.state === "running") throw new EngineError("wait for Iso to finish, or stop it, first", 409);
+		if (t.items.some((i) => i.kind === "undone")) throw new EngineError("that turn was undone already", 409);
+		const changes = t.items.filter((i) => i.kind === "change");
+		const notes = [], left = [];
+		const done = /* @__PURE__ */ new Set();
+		for (const ch of [...changes].reverse()) {
+			const key = ch.why === "move" ? ch.to : ch.note;
+			if (done.has(key)) continue;
+			done.add(key);
+			try {
+				if (ch.why === "delete") {
+					const was = replay(await this.journal(ch.note))?.text;
+					if (was === void 0 || this.bundle.concepts.has(ch.note)) {
+						left.push(ch.note);
+						continue;
+					}
+					await this.createNote(ch.note, was);
+				} else if (ch.why === "move") {
+					const from = (await this.journal(ch.to)).find((e) => e.id === ch.entry);
+					const back = from && "from" in from ? from.from : void 0;
+					if (!back || !this.bundle.concepts.has(ch.to)) {
+						left.push(ch.to);
+						continue;
+					}
+					await this.moveNote(ch.to, back, (await this.readNote(ch.to)).version);
+				} else {
+					const entries = await this.journal(ch.note);
+					const mine = changes.filter((x) => x.note === ch.note && x.why !== "move").map((x) => x.entry);
+					const first = entries.findIndex((e) => mine.includes(e.id)), last = entries.findLastIndex((e) => e.kind === "change");
+					if (first < 0 || !mine.includes(entries[last]?.id ?? "")) {
+						left.push(ch.note);
+						continue;
+					}
+					const now = await this.readNote(ch.note);
+					if (hashText(now.text) !== hashText(replay(entries).text)) {
+						left.push(ch.note);
+						continue;
+					}
+					if (first === 0) await this.deleteNote(ch.note, now.version);
+					else await this.restore(ch.note, entries.slice(0, first).findLast((e) => e.kind === "change").id, now.version);
+				}
+				notes.push(key);
+			} catch {
+				left.push(key);
+			}
+		}
+		const item = {
+			kind: "undone",
+			notes,
+			left
+		};
+		await this.one(() => this.opts.study.append(conversationPath(conversation), JSON.stringify({
+			kind: "item",
+			turn,
+			item
+		}) + "\n"));
+		this.publish({
+			type: "iso-item",
+			request: turn,
+			conversation,
+			item
+		});
+		return {
+			notes,
+			left
+		};
+	}
+	async answer(turn, permission, decision) {
+		if (![
+			"once",
+			"always",
+			"reject"
+		].includes(decision)) throw new EngineError("the answer is once, always or reject");
+		const w = this.waitingAnswer.get(permission);
+		if (!w || w.turn !== turn) throw new EngineError("Iso is not waiting for that answer", 409);
+		this.waitingAnswer.delete(permission);
+		await this.one(() => this.opts.study.append(conversationPath(w.conversation), JSON.stringify({
+			kind: "answer",
+			turn,
+			permission,
+			decision
+		}) + "\n"));
+		this.publish({
+			type: "iso-answer",
+			request: turn,
+			conversation: w.conversation,
+			permission,
+			decision
+		});
+		w.settle(decision);
+	}
 	async drafts() {
 		const study = this.opts.study;
 		if (!study) return [];
@@ -4538,6 +5516,14 @@ var Engine = class Engine {
 				event: "wind-back",
 				by: -1
 			}];
+			if (e.event === "understood") return [{
+				id,
+				at: String(e.at),
+				event: "understood",
+				by: typeof e.by === "number" ? e.by : 0,
+				...typeof e.why === "string" && e.why ? { why: e.why } : {},
+				...typeof e.conversation === "string" ? { conversation: e.conversation } : {}
+			}];
 			const move = e.moves?.[note];
 			return [{
 				id,
@@ -4854,54 +5840,116 @@ function providerConfig(path = configPath()) {
 }
 //#endregion
 //#region packages/server/src/model.ts
-const BASE = `https://huggingface.co/Xenova/bge-small-en-v1.5/resolve/ea104dacec62c0de699686887e3f920caeb4f3e3`;
+const NAME$1 = "granite-embedding-small-english-r2";
+/** The npm package that carries the files, and the version this isorite expects. */
+const PACKAGE = "isorite-model-granite@1.0.0";
+const HUB = `https://huggingface.co/onnx-community/granite-embedding-small-english-r2-ONNX/resolve/1dc7835ba0cb9c76a3618d0bf0c427c97671b3c8`;
+/** Each file: where it is on Hugging Face, its name here, and its SHA-256. The weights are kept apart from the
+*  graph, under the name the graph gives them. */
 const FILES = [
 	[
 		"onnx/model_quantized.onnx",
 		"model.onnx",
-		"6c9c6101a956d62dfb5e7190c538226c0c5bb9cb27b651234b6df063ee7dbfe4"
+		"a3fad524afc3f060216a8ddbb1ac89c9b6498fba8995b5718bde879076a2e9ba"
+	],
+	[
+		"onnx/model_quantized.onnx_data",
+		"model_quantized.onnx_data",
+		"1f4cf47e4adec7f7ae09db03d071ba8667e07f9a4203142c7efa8d37fe453597"
 	],
 	[
 		"tokenizer.json",
 		"tokenizer.json",
-		"d241a60d5e8f04cc1b2b3e9ef7a4921b27bf526d9f6050ab90f9267a1f9e5c66"
+		"feeb83348dcb033bc6b9d2e1f7906ca9eb2d122845000c9416d894d7c2927149"
 	],
 	[
 		"tokenizer_config.json",
 		"tokenizer_config.json",
-		"9261e7d79b44c8195c1cada2b453e55b00aeb81e907a6664974b4d7776172ab3"
+		"ce06781b38bb393db68c9e0709bddd31ef5d88f2c6fbb3fd9f369778fb85e451"
 	]
 ];
 const sha = (buf) => createHash("sha256").update(buf).digest("hex");
 /** Where `isorite model` keeps the model: the user's data folder, outside any repository. */
-const userModelDir = (env = process.env) => join(env.XDG_DATA_HOME || join(homedir(), ".local", "share"), "isorite", "models", "bge-small-en-v1.5");
-/** Fetch the model's files into `out`, keeping only files whose SHA-256 is the one expected. */
-async function fetchModel(out, say = console.log) {
+const userModelDir = (env = process.env) => join(env.XDG_DATA_HOME || join(homedir(), ".local", "share"), "isorite", "models", NAME$1);
+/** Keep `buf` as `out/to` if it is the file expected. */
+function keep(out, to, want, buf, say) {
+	if (sha(buf) !== want) throw new Error(`${to}: not the file expected (its SHA-256 differs), so it was not kept`);
+	writeFileSync(join(out, to) + ".tmp", buf);
+	renameSync(join(out, to) + ".tmp", join(out, to));
+	say(`${to}: ${(buf.length / 1e6).toFixed(1)} MB`);
+}
+/** The package's files, unpacked into a temporary folder by npm itself (so its registry, proxy and mirror settings
+*  apply). The folder is the caller's to remove. */
+function unpack(pkg) {
+	const tmp = mkdtempSync(join(tmpdir(), "isorite-model-"));
+	const win = process.platform === "win32";
+	const run = (cmd, args) => spawnSync(cmd, args, {
+		cwd: tmp,
+		encoding: "utf8",
+		shell: win
+	});
+	const packed = run("npm", [
+		"pack",
+		pkg,
+		"--loglevel=error"
+	]);
+	const tgz = packed.stdout?.trim().split("\n").at(-1);
+	if (packed.status !== 0 || !tgz) {
+		rmSync(tmp, {
+			recursive: true,
+			force: true
+		});
+		throw new Error((packed.stderr?.split("\n").find((l) => /^npm error \d{3} /.test(l)) ?? packed.stderr?.split("\n").find((l) => /error/i.test(l)))?.replace(/^npm error\s*/, "").trim() || packed.error?.message || "npm pack failed");
+	}
+	if (run("tar", ["-xzf", tgz]).status !== 0) {
+		rmSync(tmp, {
+			recursive: true,
+			force: true
+		});
+		throw new Error("could not unpack " + tgz);
+	}
+	return tmp;
+}
+/** Fetch the model's files into `out`, keeping only files whose SHA-256 is the one expected: from a folder if one is
+*  named, else from npm, else from Hugging Face. */
+async function fetchModel(out, say = console.log, { from, pkg = PACKAGE, files = FILES } = {}) {
 	mkdirSync(out, { recursive: true });
-	for (const [from, to, want] of FILES) {
-		const path = join(out, to);
-		if (existsSync(path) && sha(readFileSync(path)) === want) {
-			say(`${to}: already here`);
-			continue;
+	const missing = files.filter(([, to, want]) => !(existsSync(join(out, to)) && sha(readFileSync(join(out, to))) === want));
+	for (const [, to] of files) if (!missing.some((f) => f[1] === to)) say(`${to}: already here`);
+	if (missing.length && from) for (const [, to, want] of missing) {
+		if (!existsSync(join(from, to))) throw new Error(`${to} is not in ${from}`);
+		keep(out, to, want, readFileSync(join(from, to)), say);
+	}
+	else if (missing.length && pkg) {
+		let dir = null;
+		try {
+			dir = unpack(pkg);
+			for (const [, to, want] of missing) keep(out, to, want, readFileSync(join(dir, "package", to)), say);
+			missing.length = 0;
+		} catch (e) {
+			say(`From npm (${pkg}): ${e.message}. Trying Hugging Face.`);
+		} finally {
+			if (dir) rmSync(dir, {
+				recursive: true,
+				force: true
+			});
 		}
-		const res = await fetch(`${BASE}/${from}`);
-		if (!res.ok) throw new Error(`${from}: ${res.status} ${res.statusText}`);
-		const buf = new Uint8Array(await res.arrayBuffer());
-		if (sha(buf) !== want) throw new Error(`${from}: not the file expected (its SHA-256 differs), so it was not kept`);
-		writeFileSync(path + ".tmp", buf);
-		renameSync(path + ".tmp", path);
-		say(`${to}: ${(buf.length / 1e6).toFixed(1)} MB`);
+	}
+	if (missing.length && !from) for (const [hub, to, want] of missing.filter(([, to, want]) => !(existsSync(join(out, to)) && sha(readFileSync(join(out, to))) === want))) {
+		const res = await fetch(`${HUB}/${hub}`);
+		if (!res.ok) throw new Error(`${hub}: ${res.status} ${res.statusText}`);
+		keep(out, to, want, new Uint8Array(await res.arrayBuffer()), say);
 	}
 	say(`The model is in ${out}`);
 }
 //#endregion
 //#region packages/server/src/embedder.ts
-const MODEL = "bge-small-en-v1.5-q8";
-/** Where the model's files are (npm run model in a checkout, isorite model when installed), or null when they are
-*  not there. */
+const MODEL = `${NAME$1}-q8`;
+/** Where the model's files are (npm run model in a checkout, into packages/model; isorite model when installed), or
+*  null when they are not there. */
 function modelDir(env = process.env) {
 	if (env.ISORITE_EMBED === "off") return null;
-	return (env.ISORITE_EMBED_DIR ? [env.ISORITE_EMBED_DIR] : [join(dirname(fileURLToPath(import.meta.url)), "..", "models", "bge-small-en-v1.5"), userModelDir(env)]).find((dir) => existsSync(join(dir, "model.onnx")) && existsSync(join(dir, "tokenizer.json"))) ?? null;
+	return (env.ISORITE_EMBED_DIR ? [env.ISORITE_EMBED_DIR] : [join(dirname(fileURLToPath(import.meta.url)), "..", "..", "model"), userModelDir(env)]).find((dir) => existsSync(join(dir, "model.onnx")) && existsSync(join(dir, "tokenizer.json"))) ?? null;
 }
 /** The folder caches are kept in: outside both repositories, rebuilt from the notes whenever it is lost. */
 const cacheDir = (env = process.env) => join(env.XDG_CACHE_HOME || join(homedir(), ".cache"), "isorite");
@@ -4952,6 +6000,341 @@ function nodeEmbedder(dir) {
 	};
 }
 //#endregion
+//#region packages/server/src/terminal.ts
+const OUTPUT = 4e3;
+const LOOKUPS = /* @__PURE__ */ new Set([
+	"search_notes",
+	"find_similar",
+	"outline_note",
+	"read_note",
+	"brief_base"
+]);
+/** isorite's tools that change a note: their line opens it, where the agent's words are marked. */
+const CHANGES = /* @__PURE__ */ new Set(["edit_note", "write_note"]);
+/** What a tool call acted on, in a line. */
+function titleOf(name, input = {}) {
+	const s = (k) => typeof input[k] === "string" ? input[k] : "";
+	if (name === "shell" || name === "bash") return s("command");
+	if (LOOKUPS.has(name)) return s("query") || s("text") || s("id") + (s("section") ? ` § ${s("section")}` : "");
+	if (CHANGES.has(name)) return s("note");
+	return s("path") || s("filePath") || s("pattern") || s("url") || s("description") || "";
+}
+/** An edit's lines as a diff: what it took out, then what it put in. A write is all put in. */
+function diffOf(name, input) {
+	const lines = (v) => typeof v === "string" ? v.replace(/\n$/, "").split("\n") : [];
+	if ((name === "edit" || name === "edit_note") && typeof input.oldString === "string") return [...lines(input.oldString).map((l) => "-" + l), ...lines(input.newString).map((l) => "+" + l)].slice(0, 200);
+	if ((name === "write" || name === "write_note") && typeof input.content === "string") return lines(input.content).map((l) => "+" + l).slice(0, 200);
+}
+/** The session's messages (oldest first) as the pane's turns. Text still arriving (`live`, by assistant message) is
+*  added where the listed message does not have it yet; `ours` are the prompts asked from a page. */
+function toTurns(messages, { live = /* @__PURE__ */ new Map(), ours = /* @__PURE__ */ new Set(), busy = false } = {}) {
+	const turns = [];
+	for (const m of messages) {
+		if (m.type === "user" && "text" in m) {
+			turns.push({
+				id: m.id,
+				asked: m.text,
+				from: ours.has(m.id) || ours.has(m.text) ? "here" : "terminal",
+				items: [],
+				state: "running"
+			});
+			continue;
+		}
+		const turn = turns.at(-1);
+		if (!turn) continue;
+		if (m.type === "idle" && "outcome" in m) {
+			turn.state = m.outcome === "succeeded" ? "done" : /interrupt|cancel|abort/.test(m.outcome) ? "stopped" : "failed";
+			continue;
+		}
+		if (m.type !== "assistant" || !("content" in m)) continue;
+		let texts = 0;
+		for (const c of m.content) if (c.type === "text" && "text" in c) {
+			texts++;
+			if (c.text) turn.items.push({
+				kind: "text",
+				text: c.text
+			});
+		} else if (c.type === "tool" && "state" in c) {
+			const input = c.state.input ?? {};
+			const output = (c.state.content ?? []).map((x) => x.text ?? "").join("").slice(0, OUTPUT);
+			const status = c.state.status === "completed" ? "done" : /error|fail/.test(c.state.status) ? "failed" : "running";
+			const item = {
+				kind: "tool",
+				id: c.id,
+				name: c.name,
+				title: titleOf(c.name, input),
+				status,
+				output
+			};
+			const named = LOOKUPS.has(c.name) ? input.id : CHANGES.has(c.name) ? input.note : void 0;
+			if (typeof named === "string" && named) item.note = named.replace(/^\//, "").replace(/\.md$/, "");
+			const diff = diffOf(c.name, input);
+			if (diff) item.diff = diff;
+			turn.items.push(item);
+		}
+		const streaming = live.get(m.id);
+		if (streaming && !texts) turn.items.push({
+			kind: "text",
+			text: streaming
+		});
+	}
+	const listed = new Set(messages.map((m) => m.id));
+	const last = turns.at(-1);
+	if (last && last.state === "running") {
+		for (const [id, text] of live) if (!listed.has(id) && text) last.items.push({
+			kind: "text",
+			text
+		});
+	}
+	if (!busy) {
+		for (const t of turns) if (t.state === "running") t.state = "done";
+	}
+	return turns;
+}
+/** What is asked from a page, with what was given in the Iso pane's context: notes and folders by name, for the
+*  agent to read with isorite's tools, and passages as they are. */
+function given(asked, parts, title) {
+	const notes = parts.filter((p) => p.kind === "note" || p.kind === "understanding").map((p) => `- ${title(p.id)} (${p.id})`);
+	const folders = parts.filter((p) => p.kind === "folder").map((p) => `- the folder ${p.id}`);
+	const passages = parts.flatMap((p) => p.kind === "passage" ? [`From ${title(p.id)} (${p.id}):\n${p.text.split("\n").map((l) => "> " + l).join("\n")}`] : []);
+	const out = [asked.trim()];
+	if (notes.length || folders.length) out.push(`From my knowledge base (read them with read_note, or outline_note first):\n${[...notes, ...folders].join("\n")}`);
+	if (passages.length) out.push(passages.join("\n\n"));
+	return out.join("\n\n");
+}
+const EMPTY = {
+	connected: false,
+	session: null,
+	title: "",
+	busy: false,
+	turns: [],
+	asking: [],
+	cost: 0,
+	tokens: {
+		input: 0,
+		output: 0
+	},
+	model: ""
+};
+/** Events after which the session is read again; text arrives as deltas in between. */
+const REREAD = /^session\.(step\.ended|tool\.|inbox\.delivered|execution\.|created|renamed)|^permission\./;
+/** The terminal's session, followed. One terminal at a time: a second `isorite term` on the same server takes over. */
+var Terminal = class {
+	#view = EMPTY;
+	#client = null;
+	#stop = null;
+	#listeners = /* @__PURE__ */ new Set();
+	#live = /* @__PURE__ */ new Map();
+	#ours = /* @__PURE__ */ new Set();
+	#asking = /* @__PURE__ */ new Map();
+	#timer = null;
+	#directory = "";
+	view() {
+		return this.#view;
+	}
+	listen(fn) {
+		this.#listeners.add(fn);
+		return () => this.#listeners.delete(fn);
+	}
+	#tell() {
+		for (const fn of this.#listeners) fn(this.#view);
+	}
+	async attach({ url, password, directory }) {
+		this.detach();
+		const client = OpenCode.make({
+			baseUrl: url,
+			headers: { authorization: "Basic " + Buffer.from(`opencode:${password}`).toString("base64") }
+		});
+		await client.server.info();
+		this.#client = client;
+		this.#directory = directory;
+		this.#view = {
+			...EMPTY,
+			connected: true
+		};
+		const stop = this.#stop = new AbortController();
+		this.#follow(client, stop.signal);
+		await this.#choose();
+		await this.#read();
+	}
+	detach() {
+		this.#stop?.abort();
+		this.#stop = null;
+		this.#client = null;
+		this.#live.clear();
+		this.#asking.clear();
+		if (this.#timer) clearTimeout(this.#timer);
+		if (this.#view.connected) {
+			this.#view = EMPTY;
+			this.#tell();
+		}
+	}
+	/** Ask in the session the terminal shows, from a page. While it works, the prompt steers the turn under way. */
+	async prompt(text) {
+		const client = this.#need();
+		if (!this.#view.session) await this.#choose(true);
+		this.#ours.add(text);
+		const sent = await client.session.prompt({
+			sessionID: this.#view.session,
+			text
+		});
+		if (sent?.id) this.#ours.add(sent.id);
+		this.#soon();
+	}
+	async interrupt() {
+		const client = this.#need();
+		if (this.#view.session) await client.session.interrupt({ sessionID: this.#view.session });
+		this.#soon();
+	}
+	/** Answer what the agent asked; only what this session is asking can be answered. */
+	async reply(id, decision) {
+		const client = this.#need();
+		if (!this.#asking.has(id) || !this.#view.session) throw new Error("the terminal is not asking that");
+		await client.permission.reply({
+			sessionID: this.#view.session,
+			requestID: id,
+			decision
+		});
+		this.#asking.delete(id);
+		this.#soon();
+	}
+	#need() {
+		if (!this.#client) throw new Error("no terminal is attached: start one with isorite term");
+		return this.#client;
+	}
+	/** The session to follow: the one the terminal last showed, else the latest. With `make`, one is made when none is. */
+	async #choose(make = false) {
+		const client = this.#client;
+		if (!client) return;
+		const sessions = [...(await client.session.list().catch(() => null))?.data ?? []].sort((a, b) => (b.time?.updated ?? 0) - (a.time?.updated ?? 0));
+		if (sessions[0]) {
+			this.#show(sessions[0].id);
+			return;
+		}
+		if (make) {
+			const made = await client.session.create({ location: { directory: this.#directory } });
+			this.#show(made.id);
+		}
+	}
+	#show(session) {
+		if (this.#view.session === session) return;
+		this.#live.clear();
+		this.#asking.clear();
+		this.#view = {
+			...this.#view,
+			session,
+			turns: [],
+			asking: []
+		};
+		this.#pending();
+	}
+	async #pending() {
+		const client = this.#client, session = this.#view.session;
+		if (!client || !session) return;
+		const asked = await client.permission.list({ sessionID: session }).catch(() => []);
+		for (const p of asked ?? []) this.#asking.set(p.id, {
+			id: p.id,
+			action: p.action,
+			resources: p.resources ?? [],
+			...p.source?.id ? { tool: p.source.id } : {}
+		});
+		this.#soon();
+	}
+	async #follow(client, signal) {
+		try {
+			for await (const raw of client.event.subscribe()) {
+				if (signal.aborted) return;
+				const e = raw;
+				const d = e.data ?? {};
+				const session = typeof d.sessionID === "string" ? d.sessionID : null;
+				if ((e.type === "session.viewed" || e.type === "session.created") && session) this.#show(session);
+				if (session && session !== this.#view.session) continue;
+				if (e.type === "session.execution.started") this.#view = {
+					...this.#view,
+					busy: true
+				};
+				if (/^session\.execution\.(succeeded|failed|interrupted|cancelled|stopped)/.test(e.type)) {
+					this.#view = {
+						...this.#view,
+						busy: false
+					};
+					this.#live.clear();
+				}
+				if (e.type === "session.text.delta" && typeof d.assistantMessageID === "string") {
+					this.#live.set(d.assistantMessageID, (this.#live.get(d.assistantMessageID) ?? "") + String(d.delta ?? ""));
+					this.#view = {
+						...this.#view,
+						turns: this.#turns(this.#messages)
+					};
+					this.#tell();
+					continue;
+				}
+				if (e.type === "permission.asked" && typeof d.id === "string") {
+					const source = d.source;
+					this.#asking.set(d.id, {
+						id: d.id,
+						action: String(d.action ?? ""),
+						resources: d.resources ?? [],
+						...source?.id ? { tool: source.id } : {}
+					});
+				}
+				if (e.type === "permission.replied" && typeof d.requestID === "string") this.#asking.delete(d.requestID);
+				if (e.type === "session.usage.updated") this.#view = {
+					...this.#view,
+					cost: Number(d.cost ?? 0),
+					tokens: {
+						input: Number(d.tokens?.input ?? 0),
+						output: Number(d.tokens?.output ?? 0)
+					}
+				};
+				if (REREAD.test(e.type) || e.type === "session.usage.updated") this.#soon();
+			}
+		} catch {
+			if (!signal.aborted && this.#client === client) this.detach();
+		}
+	}
+	#messages = [];
+	#turns(messages) {
+		return toTurns(messages, {
+			live: this.#live,
+			ours: this.#ours,
+			busy: this.#view.busy
+		});
+	}
+	/** Read the session again shortly, once for a burst of events. */
+	#soon() {
+		if (this.#timer) return;
+		this.#timer = setTimeout(() => {
+			this.#timer = null;
+			this.#read();
+		}, 80);
+	}
+	async #read() {
+		const client = this.#client, session = this.#view.session;
+		if (!client) return;
+		if (!session) {
+			this.#tell();
+			return;
+		}
+		const [listed, info] = await Promise.all([client.message.list({
+			sessionID: session,
+			limit: 200,
+			order: "desc"
+		}).catch(() => null), client.session.get({ sessionID: session }).catch(() => null)]);
+		if (this.#client !== client || this.#view.session !== session) return;
+		this.#messages = [...listed?.data ?? []].reverse();
+		const model = [...this.#messages].reverse().find((m) => m.type === "assistant" && "content" in m)?.model?.id ?? info?.model?.id ?? this.#view.model;
+		this.#view = {
+			...this.#view,
+			title: info?.title ?? this.#view.title,
+			model,
+			turns: this.#turns(this.#messages),
+			asking: [...this.#asking.values()]
+		};
+		this.#tell();
+	}
+};
+//#endregion
 //#region packages/server/src/http.ts
 const LOOPBACK = /* @__PURE__ */ new Set([
 	"localhost",
@@ -4964,6 +6347,7 @@ const TYPES = {
 	".js": "text/javascript; charset=utf-8",
 	".css": "text/css; charset=utf-8",
 	".json": "application/json",
+	".webmanifest": "application/manifest+json",
 	".svg": "image/svg+xml",
 	".png": "image/png",
 	".woff2": "font/woff2",
@@ -4986,6 +6370,11 @@ const Tier = z.enum([
 	"mid",
 	"max"
 ]);
+/** What you chose of Iso's context (I3): parts switched off by id, and whether it may look up more. */
+const ChoiceSchema = z.object({
+	off: z.array(z.string().max(400)).max(500).optional(),
+	lookup: z.boolean().optional()
+}).strict();
 const Ask = z.discriminatedUnion("form", [
 	z.object({
 		note: z.string(),
@@ -4993,7 +6382,8 @@ const Ask = z.discriminatedUnion("form", [
 		after: Anchor.nullable(),
 		before: Anchor.nullable(),
 		asked: z.string(),
-		tier: Tier
+		tier: Tier,
+		choice: ChoiceSchema.optional()
 	}).strict(),
 	z.object({
 		note: z.string(),
@@ -5002,7 +6392,8 @@ const Ask = z.discriminatedUnion("form", [
 		after: Anchor.nullable(),
 		before: Anchor.nullable(),
 		asked: z.string(),
-		tier: Tier
+		tier: Tier,
+		choice: ChoiceSchema.optional()
 	}).strict(),
 	z.object({
 		note: z.string(),
@@ -5021,6 +6412,41 @@ const Ask = z.discriminatedUnion("form", [
 		tier: Tier
 	}).strict()
 ]);
+const Given = z.discriminatedUnion("kind", [
+	z.object({
+		kind: z.literal("note"),
+		id: z.string().max(400)
+	}).strict(),
+	z.object({
+		kind: z.literal("folder"),
+		id: z.string().max(400)
+	}).strict(),
+	z.object({
+		kind: z.literal("passage"),
+		id: z.string().max(400),
+		text: z.string().max(2e4)
+	}).strict(),
+	z.object({
+		kind: z.literal("understanding"),
+		id: z.string().max(400)
+	}).strict()
+]);
+const Mode = z.enum([
+	"ask",
+	"write",
+	"build",
+	"understand"
+]);
+const TurnAsk = z.object({
+	conversation: z.string().max(64).optional(),
+	mode: Mode,
+	asked: z.string().max(8e3),
+	given: z.array(Given).max(40),
+	tier: Tier,
+	lookup: z.boolean().optional(),
+	off: z.array(z.string().max(64)).max(500).optional()
+}).strict();
+const TurnShape = TurnAsk.omit({ asked: true });
 const ExerciseAsk = z.object({
 	folder: z.string().max(400),
 	tests: z.array(z.string().max(400)).min(1).max(20),
@@ -5048,7 +6474,7 @@ const AgentEdit = z.union([z.object({
 	newString: z.string(),
 	replaceAll: z.boolean().optional()
 }).strict(), z.object({ content: z.string() }).strict()]);
-const AgentProposal = z.object({
+const AgentChange = z.object({
 	agent: AgentName,
 	session: z.string().min(1).max(200),
 	note: z.string().max(400),
@@ -5060,7 +6486,7 @@ const AgentStatus = z.object({
 	session: z.string().min(1).max(200),
 	busy: z.boolean()
 }).strict();
-function createApp({ api, token, loopback, web, allowHosts = [], notes }) {
+function createApp({ api, token, loopback, web, allowHosts = [], notes, terminal }) {
 	const app = new Hono();
 	const allowed = new Set([...allowHosts].map((h) => h.toLowerCase()));
 	const reply = (c, status, value) => c.body(JSON.stringify(value), status, {
@@ -5144,6 +6570,36 @@ function createApp({ api, token, loopback, web, allowHosts = [], notes }) {
 		return sent instanceof Response ? sent : answer(c, async () => await act(c, sent) ?? {});
 	});
 	post("/api/iso/ask", Ask, (_c, b) => api.ask(b));
+	post("/api/iso/converse", TurnAsk, (_c, b) => api.converse(b));
+	app.get("/api/understanding", (c) => answer(c, () => api.understanding(id(c))));
+	post("/api/understanding/scratchpad", z.object({
+		scratchpad: z.string().max(2e5),
+		base: z.string().max(64).nullable()
+	}).strict(), (c, b) => api.saveScratchpad(id(c), b.scratchpad, b.base));
+	post("/api/iso/undo", z.object({
+		conversation: z.string().max(64),
+		turn: z.string().max(64)
+	}).strict(), (_c, b) => api.undoTurn(b.conversation, b.turn));
+	post("/api/iso/answer", z.object({
+		turn: z.string().max(64),
+		permission: z.string().max(64),
+		decision: z.enum([
+			"once",
+			"always",
+			"reject"
+		])
+	}).strict(), (_c, b) => api.answer(b.turn, b.permission, b.decision));
+	app.get("/api/conversation", (c) => answer(c, async () => await api.conversation(c.req.query("id") || void 0) ?? {
+		id: "",
+		turns: []
+	}));
+	app.get("/api/turn/context", (c) => answer(c, () => {
+		let raw = {};
+		try {
+			raw = JSON.parse(c.req.query("turn") ?? "{}");
+		} catch {}
+		return api.turnContext(TurnShape.parse(raw));
+	}));
 	post("/api/iso/stop", z.object({ request: z.string().max(64) }).strict(), (_c, b) => api.stop(b.request));
 	post("/api/note/restore", z.object({
 		entry: z.string().max(64),
@@ -5168,7 +6624,7 @@ function createApp({ api, token, loopback, web, allowHosts = [], notes }) {
 	post("/api/exercise/draft", ExerciseAsk, (_c, b) => api.createExerciseDraft(b.folder, b.tests, b.after ?? null));
 	post("/api/exercise/keep", z.object({ proposal: z.string().max(64) }).strict(), (c, b) => api.keepExercise(id(c), b.proposal));
 	post("/api/exercise/wind-back", z.object({}).strict(), (c) => api.windBack(id(c)));
-	app.get("/api/context", (c) => answer(c, () => api.context(c.req.query("id") || void 0)));
+	app.get("/api/context", (c) => answer(c, () => api.context(c.req.query("id") || void 0, choiceOf(c.req.query("choice")))));
 	post("/api/context/clear", z.object({}).strict(), () => api.clearConversation());
 	app.get("/api/settings", (c) => answer(c, () => api.settings()));
 	post("/api/settings/key", Key, (_c, b) => api.setKey(b.key), "put");
@@ -5180,7 +6636,7 @@ function createApp({ api, token, loopback, web, allowHosts = [], notes }) {
 	app.get("/api/agent/tools", (c) => answer(c, () => api.agentTools()));
 	post("/api/agent/look", AgentLook, (_c, b) => api.agentLook(b));
 	app.get("/api/agent/base", (c) => answer(c, async () => ({ notes: notes ?? null })));
-	post("/api/agent/propose", AgentProposal, (_c, b) => api.agentPropose(b));
+	post("/api/agent/write", AgentChange, (_c, b) => api.agentWrite(b));
 	post("/api/agent/send", z.object({
 		note: z.string().max(400),
 		passage: z.string().max(1e4).optional(),
@@ -5191,6 +6647,53 @@ function createApp({ api, token, loopback, web, allowHosts = [], notes }) {
 		agent: AgentName
 	}).strict(), (_c, b) => api.agentReceived(b.id, b.agent));
 	post("/api/agent/status", AgentStatus, (_c, b) => api.agentStatus(b.agent, b.session, b.busy));
+	if (terminal) {
+		const Local = z.string().max(200).refine((u) => {
+			try {
+				const h = new URL(u).hostname;
+				return h === "127.0.0.1" || h === "localhost" || h === "[::1]";
+			} catch {
+				return false;
+			}
+		}, "OpenCode's server must be on this machine");
+		post("/api/terminal/attach", z.object({
+			url: Local,
+			password: z.string().min(1).max(200),
+			directory: z.string().max(4e3)
+		}).strict(), async (_c, b) => {
+			await terminal.attach(b).catch((e) => {
+				throw new EngineError(`OpenCode's server did not answer: ${e.message}`, 502);
+			});
+		});
+		post("/api/terminal/detach", z.object({}).strict(), async () => {
+			terminal.detach();
+		});
+		app.get("/api/terminal", (c) => answer(c, async () => terminal.view()));
+		const failed = (e) => {
+			throw new EngineError(e.message, 409);
+		};
+		post("/api/terminal/prompt", z.object({
+			asked: z.string().min(1).max(8e3),
+			given: z.array(Given).max(40)
+		}).strict(), async (_c, b) => {
+			const titles = new Map((await api.notes()).notes.map((n) => [n.id, n.title]));
+			const text = given(b.asked, b.given, (id) => titles.get(id) ?? id);
+			await terminal.prompt(text).catch(failed);
+		});
+		post("/api/terminal/stop", z.object({}).strict(), async () => {
+			await terminal.interrupt().catch(failed);
+		});
+		post("/api/terminal/permission", z.object({
+			id: z.string().max(200),
+			decision: z.enum([
+				"once",
+				"always",
+				"reject"
+			])
+		}).strict(), async (_c, b) => {
+			await terminal.reply(b.id, b.decision).catch(failed);
+		});
+	}
 	const streams = /* @__PURE__ */ new Map();
 	const watchers = () => {
 		const browsers = [...streams.values()].filter(Boolean).length;
@@ -5209,6 +6712,16 @@ function createApp({ api, token, loopback, web, allowHosts = [], notes }) {
 				data: JSON.stringify(event)
 			});
 		});
+		const send = (view) => {
+			stream.writeSSE({
+				event: "terminal",
+				data: JSON.stringify({
+					type: "terminal",
+					terminal: view
+				})
+			}).catch(() => void 0);
+		};
+		const unfollow = terminal?.listen(send);
 		const beat = setInterval(() => {
 			stream.write(": still here\n\n");
 		}, 25e3);
@@ -5216,6 +6729,7 @@ function createApp({ api, token, loopback, web, allowHosts = [], notes }) {
 			event: "open",
 			data: "{}"
 		});
+		if (terminal?.view().connected) send(terminal.view());
 		streams.set(stream, c.req.query("agent") === void 0);
 		watchers();
 		await new Promise((done) => stream.onAbort(done));
@@ -5223,6 +6737,7 @@ function createApp({ api, token, loopback, web, allowHosts = [], notes }) {
 		watchers();
 		clearInterval(beat);
 		stop();
+		unfollow?.();
 	}));
 	app.all("/api/*", (c) => refuse(c, 404, "not found"));
 	app.on(["GET", "HEAD"], "*", (c) => !hostOk(c) ? c.text(NOT_HERE, 403) : web ? staticFile(c, web) : c.text("Not found", 404));
@@ -5247,6 +6762,19 @@ function staticFile(c, web) {
 		"X-Content-Type-Options": "nosniff"
 	});
 }
+/** The choice of what Iso is sent, as the context route takes it: JSON, and only its known fields kept. */
+function choiceOf(raw) {
+	if (!raw) return void 0;
+	try {
+		const c = JSON.parse(raw);
+		return {
+			...Array.isArray(c.off) ? { off: c.off.filter((x) => typeof x === "string").slice(0, 500) } : {},
+			...typeof c.lookup === "boolean" ? { lookup: c.lookup } : {}
+		};
+	} catch {
+		return;
+	}
+}
 //#endregion
 //#region packages/server/src/nodefiles.ts
 const gone = (e) => ["ENOENT", "ENOTDIR"].includes(e.code ?? "");
@@ -5420,13 +6948,15 @@ async function serve$1(path, { host = "127.0.0.1", port = 4767, allowHosts = []
 	const opened = locate(path);
 	const api = await openEngine(opened);
 	const web = existsSync(join(WEB_DIR, "index.html")) ? WEB_DIR : null;
+	const terminal = new Terminal();
 	const app = createApp({
 		api,
 		token: randomBytes(24).toString("base64url"),
 		loopback: LOOPBACK.has(host),
 		web,
 		allowHosts,
-		notes: opened.notes
+		notes: opened.notes,
+		terminal
 	});
 	const server = serve({
 		fetch: app.fetch,
@@ -5462,100 +6992,333 @@ function scriptedHttp(answer, pace = 0) {
 				stop(Object.assign(/* @__PURE__ */ new Error("aborted"), { name: "AbortError" }));
 				return;
 			}
-			const t = setTimeout(done, ms);
-			signal?.addEventListener("abort", () => {
-				clearTimeout(t);
-				stop(Object.assign(/* @__PURE__ */ new Error("aborted"), { name: "AbortError" }));
-			});
-		});
-		const body = new ReadableStream({ async start(c) {
-			const enc = new TextEncoder(), send = (o) => c.enqueue(enc.encode(data(o)));
-			try {
-				const text = reply.text ?? "";
-				for (const piece of pace ? text.match(/[\s\S]{1,14}/g) ?? [] : text ? [text] : []) {
-					send({
-						model: request.model,
-						choices: [{ delta: { content: piece } }]
-					});
-					if (pace) await wait(pace);
+			const t = setTimeout(done, ms);
+			signal?.addEventListener("abort", () => {
+				clearTimeout(t);
+				stop(Object.assign(/* @__PURE__ */ new Error("aborted"), { name: "AbortError" }));
+			});
+		});
+		const body = new ReadableStream({ async start(c) {
+			const enc = new TextEncoder(), send = (o) => c.enqueue(enc.encode(data(o)));
+			try {
+				const text = reply.text ?? "";
+				for (const piece of pace ? text.match(/[\s\S]{1,14}/g) ?? [] : text ? [text] : []) {
+					send({
+						model: request.model,
+						choices: [{ delta: { content: piece } }]
+					});
+					if (pace) await wait(pace);
+				}
+				for (const [index, call] of (reply.calls ?? []).entries()) send({ choices: [{ delta: { tool_calls: [{
+					index,
+					id: `call_${index}_${Math.random().toString(36).slice(2, 8)}`,
+					function: {
+						name: call.name,
+						arguments: JSON.stringify(call.arguments)
+					}
+				}] } }] });
+				if (pace && reply.calls) await wait(pace * 20);
+				const u = reply.usage ?? {
+					in: 3e3,
+					out: 200,
+					usd: .008
+				};
+				send({ choices: [{
+					delta: {},
+					finish_reason: reply.calls ? "tool_calls" : "stop"
+				}] });
+				send({
+					choices: [],
+					usage: {
+						prompt_tokens: u.in,
+						completion_tokens: u.out,
+						cost: u.usd,
+						prompt_tokens_details: { cached_tokens: u.cached ?? 0 }
+					}
+				});
+				c.enqueue(enc.encode("data: [DONE]\n\n"));
+				c.close();
+			} catch (e) {
+				c.error(e);
+			}
+		} });
+		return new Response(body, {
+			status: 200,
+			headers: { "content-type": "text/event-stream" }
+		});
+	});
+	return { fetch };
+}
+//#endregion
+//#region packages/example/src/tutorial.ts
+const UNSCRIPTED$1 = "In this tutorial I answer only what it walks you through. With a provider key in your own isorite, I would answer this too.";
+const text = (r) => r.messages.filter((m) => m.role === "user").map((m) => String(m.content)).join("\n\n");
+const looked = (r) => r.messages.some((m) => m.role === "tool");
+const asked = (r) => (text(r).split(/# What they ask(?: now)?[^\n]*\n\n/).at(-1) ?? "").trim().toLowerCase();
+const INSERT = `To insert a body, start at the root and walk down: at each node, go into the one of its four squares that holds the body's position.
+
+- **An empty leaf** takes the body, and is done.
+- **A leaf with a body already** is split: both bodies go down into its new children, which may split again if they land in the same square.
+- **An inner node** passes the body down to the child whose square holds it.
+
+On the way down, every node passed adds the body to its total mass $M$ and to $M\\mathbf{R}$, so that each keeps its mass and centre of mass with no second pass. A node keeps its square (centre and side $s$), its mass, its centre of mass, and its four children or its one body.`;
+const THETA = `With $\\theta = 0.5$ the force error is about a percent for most bodies, and several percent for a few near dense nodes; it falls quickly as $\\theta$ shrinks. The error of a node used whole is of order $(s/d)^2$, the [centre of mass](/algorithms/centre-of-mass.md "uses")'s quadrupole, and $s/d < \\theta$ bounds it.
+
+The cost: a body opens nodes only near it. Around it, each level of the tree adds a ring of about the same number of nodes used whole, and there are $\\log_4 N$ levels, so each body visits $O(\\log N)$ nodes, and all of them $O(N \\log N)$.`;
+const SPEED = `About ten times fewer interactions. Direct summation computes $N(N-1)/2 \\approx 1.25 \\times 10^7$ pairs at $N = 5000$. Barnes–Hut at $\\theta = 0.5$ uses some 200 nodes for each body, so about $10^6$ interactions in all.
+
+Each of them costs more: the tree walk branches, and in plain Python it is slow enough to lose the whole factor. Measure it, as your note on [cost and accuracy](/algorithms/cost-and-accuracy.md) says, before counting on it.`;
+const OCTREE = `An octree is the same tree with eight children instead of four: each cube is split in half along each of the three axes.
+
+What changes:
+- **Insertion** picks one of eight children, by the sign of the body's position against the cube's centre on each axis: three comparisons, one bit each.
+- **The opening rule** is the same, $s/d < \\theta$, with $s$ the cube's side.
+- **The cost** is still $O(N \\log N)$; the log is now base 8, but each opened node has twice as many children, so the work per body is about the same.
+
+Nothing in the [main loop](/simulation/the-main-loop.md) changes: only \`accelerations\`.`;
+const OCTREE_NOTE = `---
+type: Concept
+title: The octree
+description: The quadtree in 3D: each cube split into eight.
+---
+
+The [quadtree](/algorithms/the-quadtree.md "requires") in three dimensions, for [Barnes–Hut](/algorithms/barnes-hut.md "uses") on the 3D simulation.
+
+${OCTREE}
+`;
+const CLOSE = `When two bodies pass within a small fraction of their usual distance, their acceleration grows as $1/r^2$, and a step of fixed length overshoots: the energy jumps.
+
+Three ways out:
+- **Soften the force.** With $\\varepsilon$ a little larger than the closest passes you care about, the force stays finite. Right for a galaxy, whose bodies stand for many stars.
+- **A shorter step**, for everyone. Simple, and leapfrog stays symplectic, but every body pays for the one close pair.
+- **Steps that differ by body** (block timesteps). Efficient, but only a careful scheme keeps the energy from drifting.
+
+For two galaxies colliding, the first is the usual answer.`;
+/** The answer to one request to the tutorial's Iso. */
+/** In a turn in Iso's pane (M10): which mode, from what it was told. */
+const modeOf = (r) => {
+	const system = JSON.stringify(r.messages.find((m) => m.role === "system")?.content ?? "");
+	return system.includes("# Write mode") ? "write" : system.includes("# Understand mode") ? "understand" : system.includes("# Ask mode") ? "ask" : null;
+};
+const tools = (r) => r.messages.filter((m) => m.role === "tool").length;
+const TODO = "TODO: how big an error does θ = 0.5 give, and why does the cost grow only as N log N?";
+/** Iso's pane (M10): Ask, Write and Understand mode, on the questions the tutorial walks through. */
+function turnAnswer(r, mode) {
+	const q = asked(r), n = tools(r);
+	if (mode === "ask" && q.includes("inserted")) {
+		if (n === 0) return {
+			calls: [{
+				name: "search_notes",
+				arguments: { query: "quadtree" }
+			}, {
+				name: "read_note",
+				arguments: { id: "algorithms/centre-of-mass" }
+			}],
+			usage: {
+				in: 5100,
+				out: 50,
+				usd: .0059
+			}
+		};
+		if (n === 2) return {
+			calls: [{
+				name: "point_to_note",
+				arguments: {
+					id: "algorithms/centre-of-mass",
+					why: "It is what each node keeps as bodies pass down."
+				}
+			}],
+			usage: {
+				in: 7800,
+				out: 40,
+				usd: .0061
+			}
+		};
+		return {
+			text: INSERT,
+			usage: {
+				in: 8400,
+				out: 310,
+				cached: 4800,
+				usd: .0163
+			}
+		};
+	}
+	if (mode === "ask" && q.includes("faster")) {
+		if (n === 0) return {
+			calls: [{
+				name: "read_note",
+				arguments: { id: "algorithms/direct-summation" }
+			}, {
+				name: "read_note",
+				arguments: { id: "algorithms/barnes-hut" }
+			}],
+			usage: {
+				in: 5300,
+				out: 50,
+				usd: .006
+			}
+		};
+		return {
+			text: SPEED,
+			usage: {
+				in: 8800,
+				out: 260,
+				cached: 5e3,
+				usd: .0158
+			}
+		};
+	}
+	if (mode === "write" && q.includes("octree")) {
+		if (n === 0) return {
+			calls: [{
+				name: "read_note",
+				arguments: { id: "algorithms/the-quadtree" }
+			}, {
+				name: "read_note",
+				arguments: { id: "algorithms/barnes-hut" }
+			}],
+			usage: {
+				in: 5200,
+				out: 60,
+				usd: .0058
+			}
+		};
+		if (n === 2) return {
+			calls: [{
+				name: "write_note",
+				arguments: {
+					id: "algorithms/the-octree",
+					text: OCTREE_NOTE
+				}
+			}],
+			usage: {
+				in: 9900,
+				out: 380,
+				cached: 4400,
+				usd: .0192
+			}
+		};
+		return {
+			text: "I wrote The octree in algorithms, from the quadtree and Barnes–Hut, and linked it to both.",
+			usage: {
+				in: 10400,
+				out: 40,
+				cached: 9800,
+				usd: .0043
+			}
+		};
+	}
+	if (mode === "write" && q.includes("todo")) {
+		if (n === 0) return {
+			calls: [{
+				name: "read_note",
+				arguments: { id: "algorithms/barnes-hut" }
+			}, {
+				name: "read_note",
+				arguments: { id: "algorithms/the-quadtree" }
+			}],
+			usage: {
+				in: 5600,
+				out: 60,
+				usd: .0061
+			}
+		};
+		if (n === 2) return {
+			calls: [{
+				name: "edit_note",
+				arguments: {
+					id: "algorithms/barnes-hut",
+					old: TODO,
+					new: THETA
+				}
+			}],
+			usage: {
+				in: 8900,
+				out: 290,
+				cached: 5100,
+				usd: .0154
+			}
+		};
+		return {
+			text: "I answered both questions in your TODO, from the quadtree's depth and the centre of mass, and took the TODO away.",
+			usage: {
+				in: 9400,
+				out: 40,
+				cached: 8800,
+				usd: .0041
+			}
+		};
+	}
+	if (mode === "understand" && /backwards|retrace|reverse/.test(q)) {
+		if (n === 0) return {
+			calls: [{
+				name: "record_understanding",
+				arguments: {
+					id: "integrators/leapfrog",
+					by: .5,
+					why: "You saw that running it backwards retraces it, and that this is why its error cannot pile up."
 				}
-				for (const [index, call] of (reply.calls ?? []).entries()) send({ choices: [{ delta: { tool_calls: [{
-					index,
-					id: `call_${index}_${Math.random().toString(36).slice(2, 8)}`,
-					function: {
-						name: call.name,
-						arguments: JSON.stringify(call.arguments)
-					}
-				}] } }] });
-				if (pace && reply.calls) await wait(pace * 20);
-				const u = reply.usage ?? {
-					in: 3e3,
-					out: 200,
-					usd: .008
-				};
-				send({ choices: [{
-					delta: {},
-					finish_reason: reply.calls ? "tool_calls" : "stop"
-				}] });
-				send({
-					choices: [],
-					usage: {
-						prompt_tokens: u.in,
-						completion_tokens: u.out,
-						cost: u.usd,
-						prompt_tokens_details: { cached_tokens: u.cached ?? 0 }
-					}
-				});
-				c.enqueue(enc.encode("data: [DONE]\n\n"));
-				c.close();
-			} catch (e) {
-				c.error(e);
+			}, {
+				name: "write_understanding",
+				arguments: {
+					id: "integrators/leapfrog",
+					reading: "You can say why leapfrog's energy error stays bounded: it is time-reversible, so it cannot drift one way. Not yet shown: what being symplectic adds to that."
+				}
+			}],
+			usage: {
+				in: 6200,
+				out: 120,
+				usd: .0068
 			}
-		} });
-		return new Response(body, {
-			status: 200,
-			headers: { "content-type": "text/event-stream" }
-		});
-	});
-	return { fetch };
+		};
+		return {
+			text: "Yes: run backwards it retraces its steps, so an error it made going forward is undone coming back, and it cannot keep growing one way. That is reversibility. Being [symplectic](/integrators/symplectic-integrators.md) is the stronger reason, and the next thing to look at.",
+			usage: {
+				in: 7100,
+				out: 90,
+				cached: 5600,
+				usd: .0049
+			}
+		};
+	}
+	if (mode === "understand" && /leapfrog|bounded|drift/.test(q)) {
+		if (n === 0) return {
+			calls: [{
+				name: "read_note",
+				arguments: {
+					id: "integrators/leapfrog",
+					section: "Why it does not drift"
+				}
+			}],
+			usage: {
+				in: 5200,
+				out: 40,
+				usd: .0056
+			}
+		};
+		return {
+			text: "Before I say why: what happens if you run leapfrog with $-\\Delta t$, from where it ended?",
+			usage: {
+				in: 6900,
+				out: 30,
+				cached: 4800,
+				usd: .0044
+			}
+		};
+	}
+	return null;
 }
-//#endregion
-//#region packages/example/src/tutorial.ts
-const UNSCRIPTED$1 = "In this tutorial I answer only what it walks you through. With a provider key in your own isorite, I would answer this too.";
-const text = (r) => r.messages.filter((m) => m.role === "user").map((m) => String(m.content)).join("\n\n");
-const looked = (r) => r.messages.some((m) => m.role === "tool");
-const asked = (r) => (text(r).split(/# What they ask(?: now)?[^\n]*\n\n/).at(-1) ?? "").trim().toLowerCase();
-const INSERT = `To insert a body, start at the root and walk down: at each node, go into the one of its four squares that holds the body's position.
-
-- **An empty leaf** takes the body, and is done.
-- **A leaf with a body already** is split: both bodies go down into its new children, which may split again if they land in the same square.
-- **An inner node** passes the body down to the child whose square holds it.
-
-On the way down, every node passed adds the body to its total mass $M$ and to $M\\mathbf{R}$, so that each keeps its mass and centre of mass with no second pass. A node keeps its square (centre and side $s$), its mass, its centre of mass, and its four children or its one body.`;
-const THETA = `With $\\theta = 0.5$ the force error is about a percent for most bodies, and several percent for a few near dense nodes; it falls quickly as $\\theta$ shrinks. The error of a node used whole is of order $(s/d)^2$, the [centre of mass](/algorithms/centre-of-mass.md "uses")'s quadrupole, and $s/d < \\theta$ bounds it.
-
-The cost: a body opens nodes only near it. Around it, each level of the tree adds a ring of about the same number of nodes used whole, and there are $\\log_4 N$ levels, so each body visits $O(\\log N)$ nodes, and all of them $O(N \\log N)$.`;
-const SPEED = `About ten times fewer interactions. Direct summation computes $N(N-1)/2 \\approx 1.25 \\times 10^7$ pairs at $N = 5000$. Barnes–Hut at $\\theta = 0.5$ uses some 200 nodes for each body, so about $10^6$ interactions in all.
-
-Each of them costs more: the tree walk branches, and in plain Python it is slow enough to lose the whole factor. Measure it, as your note on [cost and accuracy](/algorithms/cost-and-accuracy.md) says, before counting on it.`;
-const OCTREE = `An octree is the same tree with eight children instead of four: each cube is split in half along each of the three axes.
-
-What changes:
-- **Insertion** picks one of eight children, by the sign of the body's position against the cube's centre on each axis: three comparisons, one bit each.
-- **The opening rule** is the same, $s/d < \\theta$, with $s$ the cube's side.
-- **The cost** is still $O(N \\log N)$; the log is now base 8, but each opened node has twice as many children, so the work per body is about the same.
-
-Nothing in the [main loop](/simulation/the-main-loop.md) changes: only \`accelerations\`.`;
-const CLOSE = `When two bodies pass within a small fraction of their usual distance, their acceleration grows as $1/r^2$, and a step of fixed length overshoots: the energy jumps.
-
-Three ways out:
-- **Soften the force.** With $\\varepsilon$ a little larger than the closest passes you care about, the force stays finite. Right for a galaxy, whose bodies stand for many stars.
-- **A shorter step**, for everyone. Simple, and leapfrog stays symplectic, but every body pays for the one close pair.
-- **Steps that differ by body** (block timesteps). Efficient, but only a careful scheme keeps the energy from drifting.
-
-For two galaxies colliding, the first is the usual answer.`;
-/** The answer to one request to the tutorial's Iso. */
 function tutorialAnswer(r) {
+	const mode = modeOf(r);
+	if (mode) return turnAnswer(r, mode) ?? {
+		text: "In this tutorial I answer only what it walks you through. With a provider key in your own isorite, I would answer this too.",
+		usage: {
+			in: 4e3,
+			out: 40,
+			usd: .0049
+		}
+	};
 	const all = text(r);
 	if (all.includes("⟦answer⟧")) {
 		const answer = /⟦answer⟧([\s\S]*?)⟦\/answer⟧/.exec(all)?.[1] ?? "";
@@ -5721,6 +7484,70 @@ function tutorialAnswer(r) {
 			}
 		};
 	}
+	if (q.includes("octree") && q.includes("barnes")) {
+		if (!looked(r)) return {
+			calls: [
+				{
+					name: "read_note",
+					arguments: { id: "algorithms/the-quadtree" }
+				},
+				{
+					name: "read_note",
+					arguments: { id: "algorithms/barnes-hut" }
+				},
+				{
+					name: "search_notes",
+					arguments: { query: "octree" }
+				}
+			],
+			usage: {
+				in: 5200,
+				out: 60,
+				usd: .0058
+			}
+		};
+		return {
+			text: OCTREE,
+			usage: {
+				in: 9900,
+				out: 340,
+				cached: 4400,
+				usd: .0188
+			}
+		};
+	}
+	if (/pass(es)? close|close (pass|encounter)/.test(q)) {
+		if (!looked(r)) return {
+			calls: [
+				{
+					name: "read_note",
+					arguments: { id: "physics/softening" }
+				},
+				{
+					name: "read_note",
+					arguments: { id: "integrators/choosing-the-timestep" }
+				},
+				{
+					name: "find_similar",
+					arguments: { text: "an energy jump when two bodies pass close" }
+				}
+			],
+			usage: {
+				in: 4900,
+				out: 60,
+				usd: .0056
+			}
+		};
+		return {
+			text: CLOSE,
+			usage: {
+				in: 9600,
+				out: 360,
+				cached: 4100,
+				usd: .0191
+			}
+		};
+	}
 	if (/\b3d\b|three dimensions/.test(q)) return {
 		text: "In 3D the same tree has eight children a node: an octree.",
 		usage: {
@@ -6632,7 +8459,7 @@ function writeHome(dir, { gateway = null, plugin = pluginDir } = {}) {
 	mkdirSync(join(dir, "themes"), { recursive: true });
 	mkdirSync(join(dir, "plugins"), { recursive: true });
 	const json = (value) => JSON.stringify(value, null, 2) + "\n";
-	writeFileSync(join(dir, "opencode.json"), json(openCodeConfig(gateway)));
+	writeFileSync(join(dir, "opencode.json"), json(withLocal(openCodeConfig(gateway), join(dir, "local.json"))));
 	writeFileSync(join(dir, "cli.json"), json({
 		$schema: "https://opencode.ai/cli.json",
 		theme: {
@@ -6651,6 +8478,28 @@ function writeHome(dir, { gateway = null, plugin = pluginDir } = {}) {
 	}
 	return dir;
 }
+/** Your local.json over what isorite writes: its providers added to isorite's, everything else of yours taking the
+*  place of isorite's. A local.json that is not JSON is said, and left out. */
+function withLocal(config, local) {
+	if (!existsSync(local)) return config;
+	let mine;
+	try {
+		mine = JSON.parse(readFileSync(local, "utf8"));
+	} catch (e) {
+		console.error(`isorite: ${local} is not JSON, so it is left out: ${e.message}`);
+		return config;
+	}
+	const ours = config;
+	const providers = {
+		...ours.providers,
+		...mine.providers
+	};
+	return {
+		...ours,
+		...mine,
+		...Object.keys(providers).length ? { providers } : {}
+	};
+}
 function linksTo(path, target) {
 	try {
 		return lstatSync(path).isSymbolicLink() && readlinkSync(path) === target;
@@ -6703,7 +8552,7 @@ function lastAsked(request) {
 }
 async function startScripted(script) {
 	const requests = [];
-	const server = createServer((req, res) => {
+	const server = createServer$1((req, res) => {
 		let body = "";
 		req.on("data", (chunk) => body += chunk);
 		req.on("end", () => {
@@ -6891,7 +8740,7 @@ function tutorialScript(notes) {
 					newString: NOW
 				}
 			}
-		][done] ?? { text: "barnes_hut.py builds the quadtree and walks it with θ = 0.5 `[1]`. Your note on the goal now says where the code is: that change waits for you to keep or not `[2]`.\n\n```isorite\n[1] algorithms/barnes-hut\n[2] simulation/two-galaxies-colliding\n```" };
+		][done] ?? { text: "barnes_hut.py builds the quadtree and walks it with θ = 0.5 `[1]`. Your note on the goal now says where the code is, marked as mine `[2]`.\n\n```isorite\n[1] algorithms/barnes-hut\n[2] simulation/two-galaxies-colliding\n```" };
 		return { text: UNSCRIPTED };
 	};
 }
@@ -6969,23 +8818,147 @@ async function ensureServer(path, { port = 4767, env = process.env, wait = 12e4
 		}
 	};
 }
-async function term(path, { port = 4767, cwd = process.cwd(), env = process.env, wait = 12e4, onServer } = {}) {
-	const opencode = findOpenCode(env);
-	const gateway = gatewayFrom(env);
+/** A port nobody is listening on, on this machine. */
+async function freePort() {
+	return new Promise((done, fail) => {
+		const probe = createServer().once("error", fail).listen(0, "127.0.0.1", () => {
+			const { port } = probe.address();
+			probe.close(() => done(port));
+		});
+	});
+}
+/** A POST to the isorite server, made as its page makes one: from its origin, with the token it hands out. */
+async function tell(url, path, body) {
+	const { token } = await (await fetch(`${url}/api/session`)).json();
+	const response = await fetch(url + path, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"x-isorite-token": token,
+			Origin: url
+		},
+		body: JSON.stringify(body)
+	});
+	if (!response.ok) throw new Error((await response.json().catch(() => ({}))).error ?? `${response.status} from ${path}`);
+}
+/** OpenCode's own server, on this machine only, with a password of its own; its output kept in a log. The terminal
+*  attaches to it, and so does the isorite server, which shows its session in the Iso pane (M11). */
+async function startOpenCode(command, { cwd, env, wait = 6e4 }) {
+	const port = await freePort(), password = randomBytes(24).toString("base64url"), url = `http://127.0.0.1:${port}`;
+	const log = join(tmpdir(), `isorite-opencode-${port}.log`);
+	const out = openSync(log, "w");
+	const server = spawn(command, [
+		"serve",
+		"--port",
+		String(port),
+		"--hostname",
+		"127.0.0.1"
+	], {
+		cwd,
+		stdio: [
+			"ignore",
+			out,
+			out
+		],
+		env: {
+			...env,
+			OPENCODE_PASSWORD: password
+		}
+	});
+	const auth = { authorization: "Basic " + Buffer.from(`opencode:${password}`).toString("base64") };
+	const started = Date.now();
+	for (;;) {
+		if (server.exitCode !== null || Date.now() - started > wait) {
+			server.kill();
+			throw new StudyError(`OpenCode's server did not start; its output is in ${log}`);
+		}
+		try {
+			if ((await fetch(url, {
+				headers: auth,
+				signal: AbortSignal.timeout(1e3)
+			})).status < 500) break;
+		} catch {}
+		await new Promise((r) => setTimeout(r, 250));
+	}
+	return {
+		url,
+		password,
+		stop: () => {
+			server.kill();
+		}
+	};
+}
+/** The models the terminal uses: ISORITE_GATEWAY_URL and _MODELS when set; else Iso's own provider, as
+*  ~/.config/isorite/config.toml has it (OpenRouter unless `[provider] url` names another), its models the tiers'
+*  (mid, the default, then max and low), with the key it holds handed to OpenCode in the environment only. Null without a key: then
+*  OpenCode's own models, or whatever your local.json names. */
+async function modelsFor(env) {
+	const named = gatewayFrom(env);
+	if (named) return {
+		gateway: named,
+		env
+	};
+	const path = configPath(env);
+	const key = await new ConfigSecrets(path).get("provider.key");
+	if (!key) return {
+		gateway: null,
+		env
+	};
+	const provider = providerConfig(path);
+	const models = [.../* @__PURE__ */ new Set([
+		provider.tiers.mid,
+		provider.tiers.max,
+		provider.tiers.low
+	])];
+	return {
+		gateway: {
+			url: provider.url,
+			models
+		},
+		env: {
+			...env,
+			[GATEWAY_KEY]: key
+		}
+	};
+}
+async function term(path, { port = 4767, cwd = process.cwd(), env: given = process.env, wait = 12e4, onServer } = {}) {
+	const opencode = findOpenCode(given);
+	const { gateway, env } = await modelsFor(given);
 	const server = await ensureServer(path, {
 		port,
-		env,
+		env: given,
 		wait
 	});
 	onServer?.(server.url);
 	const home = writeHome(defaultHome(env), { gateway });
-	const child = spawn(opencode.command, ["--standalone"], {
+	const shared = {
+		...env,
+		OPENCODE_CONFIG_DIR: home,
+		ISORITE_URL: server.url
+	};
+	let backend;
+	try {
+		backend = await startOpenCode(opencode.command, {
+			cwd,
+			env: shared
+		});
+	} catch (e) {
+		server.release();
+		throw e;
+	}
+	await tell(server.url, "/api/terminal/attach", {
+		url: backend.url,
+		password: backend.password,
+		directory: cwd
+	}).catch((e) => console.error(`isorite: the Iso pane will not show the terminal: ${e.message}`));
+	const child = spawn(opencode.command, ["--server", backend.url], {
 		cwd,
 		stdio: "inherit",
 		env: {
-			...env,
+			...given,
 			OPENCODE_CONFIG_DIR: home,
-			ISORITE_URL: server.url
+			ISORITE_URL: server.url,
+			OPENCODE_PASSWORD: backend.password
 		}
 	});
 	const forward = (signal) => () => child.kill(signal);
@@ -6999,6 +8972,8 @@ async function term(path, { port = 4767, cwd = process.cwd(), env = process.env,
 		child.once("exit", (exit) => done(exit ?? 1));
 	});
 	for (const [signal, handler] of handlers) process.off(signal, handler);
+	await tell(server.url, "/api/terminal/detach", {}).catch(() => void 0);
+	backend.stop();
 	server.release();
 	return code;
 }
@@ -7176,7 +9151,7 @@ async function mcp(path, { port = 4767, agent = "mcp", quiet = QUIET_MS, input =
 }
 //#endregion
 //#region packages/server/src/main.ts
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 const USAGE = `isorite: an agentic harness for understanding
 
   isorite check <notes>                  check a folder of notes: frontmatter, links, cycles
@@ -7191,7 +9166,8 @@ const USAGE = `isorite: an agentic harness for understanding
   isorite mcp [<study base | notes>] [--port <n>] [--agent <name>]
                                          the knowledge base's tools over MCP, on stdio, for Claude Code or Pi:
                                          claude mcp add isorite -- isorite mcp <base> --agent claude-code
-  isorite model                          fetch the model for search by meaning (34 MB, once)
+  isorite model [--from <folder>]        fetch the model for search by meaning (53 MB, once): from npm, else
+                                         Hugging Face; or from a folder its files were copied into
   isorite --tutorial [<folder>] [--port <n>]
                                          the tutorial, on the example base, with a scripted model (no key,
                                          nothing sent anywhere): the terminal's tour in OpenCode 2, and the
@@ -7268,10 +9244,17 @@ function main(argv) {
 				return 2;
 			});
 		}
-		if (command === "model") return fetchModel(userModelDir()).then(() => 0, (e) => {
-			console.error(e.message);
-			return 1;
-		});
+		if (command === "model") {
+			const from = rest[rest.indexOf("--from") + 1];
+			if (rest.includes("--from") && !from) {
+				console.error("--from takes a folder");
+				return 2;
+			}
+			return fetchModel(userModelDir(), console.log, from && rest.includes("--from") ? { from } : {}).then(() => 0, (e) => {
+				console.error(e.message);
+				return 1;
+			});
+		}
 		if (command === "--version" || command === "-v") {
 			console.log(VERSION);
 			return 0;