@henols/c64-re-tools 2.1.0-rc.1 → 2.1.0-rc.2

package/skills/c64-docs/scripts/docs.ts

@@ -0,0 +1,323 @@
+// The c64-docs script. generate writes the reference pages of a program from
+// the knowledge, the source map of c64-source and the program in the
+// knowledge; the pages are generated and never edited. link links the name
+// mentions of the documentation to the source and the reference, and checks
+// every link and image of the pages.
+
+import { existsSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { join, posix } from "node:path";
+
+import { Refusal } from "#src/errors.ts";
+import { WireFailure } from "#src/host-client/tools.ts";
+import { writeProjectFile, writeReported } from "#src/host-client/transfer.ts";
+import { conflicts } from "#src/knowledge/conflicts.ts";
+import { openForRead } from "#src/knowledge/database.ts";
+import { programImage, type ProgramImage } from "#src/knowledge/program.ts";
+import { currentRevision, listComments, listModules, listReferences, listRegions, listSymbols } from "#src/knowledge/read.ts";
+import { resolveProjectFile, resolveProjectPath } from "#src/project.ts";
+import { listed, OPTIONS, runScript, UsageError, type Call } from "#src/script.ts";
+import { checkLinks, linkPage, type Files, type Problem } from "./lib/links.ts";
+import { buildReference, GENERATED_MARK } from "./lib/reference.ts";
+import { readSourceMap } from "./lib/source-map.ts";
+
+// ---------------------------------------------------------------------------
+// generate
+
+/** The files of an earlier run in `directory`, the real folder of --out, or a refusal that names a file of a person. */
+function oldFiles(out: string, directory: string): string[] {
+  if (!existsSync(directory)) return [];
+  const found: string[] = [];
+  const walk = (relative: string) => {
+    for (const entry of readdirSync(join(directory, relative), { withFileTypes: true })) {
+      const path = posix.join(relative, entry.name);
+      if (entry.isDirectory()) {
+        walk(path);
+        continue;
+      }
+      const generated = path.endsWith(".md") ? readFileSync(join(directory, path), "utf8").startsWith(GENERATED_MARK) : path.startsWith("images/") && path.endsWith(".png");
+      if (!generated) throw new WireFailure("invalid-input", `${posix.join(out, path)} is not a page of docs.ts generate. Nothing was written. Give --out a directory that holds only the reference, and keep the pages of a person outside it.`);
+      found.push(path);
+    }
+  };
+  walk("");
+  return found;
+}
+
+function generate(call: Call): Record<string, unknown> {
+  const source = call.subject(0);
+  const out = call.string("out")!;
+  // The files of an earlier run are deleted: only in a folder that is inside the project, also after its symbolic links.
+  let directory = resolveProjectPath(out);
+  if (existsSync(directory)) {
+    try {
+      directory = resolveProjectFile(out);
+    } catch {
+      throw new UsageError(`--out must be a path relative to the project folder that stays inside it, also through symbolic links, not ${out}`);
+    }
+  }
+  const map = readSourceMap(source);
+  const db = openForRead();
+  let knowledge;
+  let image: ProgramImage | undefined;
+  try {
+    image = programImage(db, map.space);
+    const found = conflicts(db).length;
+    if (found > 0) throw new Refusal("conflict", `The knowledge has ${found} conflict${found === 1 ? "" : "s"} from a git merge. Nothing was written. Run c64-knowledge's knowledge.ts merge, then generate the source and the reference again.`);
+    const revision = currentRevision(db);
+    // A source of another revision has other lines: the links would point to the wrong code.
+    if (map.revision !== revision) {
+      throw new WireFailure("invalid-input", `${map.pathOf("source-map.json")} is from knowledge revision ${map.revision}, and the knowledge is at revision ${revision}. Nothing was written. Generate the source again with c64-source, then run docs.ts generate.`);
+    }
+    knowledge = {
+      revision,
+      symbols: listSymbols(db, undefined, undefined, undefined, map.space),
+      regions: listRegions(db, undefined, undefined, undefined, map.space),
+      comments: listComments(db, undefined, undefined, map.space),
+      references: listReferences(db, undefined, undefined, undefined, map.space),
+      modules: listModules(db, undefined, undefined, map.space),
+    };
+  } finally {
+    db?.close();
+  }
+  const old = oldFiles(out, directory);
+  const built = buildReference({
+    out: posix.normalize(out),
+    map,
+    ...knowledge,
+    ...(image === undefined ? {} : { image: { byteAt: image.byteAt, inImage: (address: number) => image.segments.some((segment) => address >= segment.start && address <= segment.end) } }),
+  });
+  for (const path of old) rmSync(join(directory, path), { force: true });
+  const written = built.files.map((file) => writeReported(file.path, file.bytes, { what: "--out" }));
+  return { out, revision: knowledge.revision, index: posix.join(posix.normalize(out), "index.md"), ...built.counts, files: listed(written, call.count("max-listed")!), program: image === undefined ? "none: put the program into the knowledge with knowledge.ts image to decode the tables and show the graphics" : "the knowledge" };
+}
+
+// ---------------------------------------------------------------------------
+// link
+
+/** A name outside the image covers the addresses up to the next name, at most this many. */
+const MAX_BODY = 256;
+
+const isDirectory = (path: string) => {
+  const real = resolveProjectPath(path);
+  return existsSync(real) && statSync(real).isDirectory();
+};
+
+function markdownFiles(directory: string): string[] {
+  if (!isDirectory(directory)) throw new WireFailure("not-found", `There is no directory ${directory} in the project folder.`);
+  let root: string;
+  try {
+    root = resolveProjectFile(directory);
+  } catch {
+    throw new WireFailure("invalid-input", `${directory} leads out of the project folder through a symbolic link.`);
+  }
+  const found: string[] = [];
+  const walk = (relative: string) => {
+    for (const entry of readdirSync(join(root, relative), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const path = posix.join(relative, entry.name);
+      if (entry.isDirectory()) walk(path);
+      else if (entry.name.endsWith(".md")) found.push(posix.join(directory, path));
+    }
+  };
+  walk("");
+  return found;
+}
+
+/** The text of each file that the run read: a page, a source file or a reference page is read once. */
+const texts = new Map<string, string | undefined>();
+
+const files: Files = {
+  inside: (path) => {
+    try {
+      resolveProjectPath(path);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  exists: (path) => {
+    try {
+      resolveProjectFile(path);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  text: (path) => {
+    if (texts.has(path)) return texts.get(path);
+    let text: string | undefined;
+    try {
+      const real = resolveProjectFile(path);
+      text = statSync(real).isFile() ? readFileSync(real, "utf8") : undefined;
+    } catch {
+      text = undefined;
+    }
+    texts.set(path, text);
+    return text;
+  },
+};
+
+/** A .md entry of a directory that is a symbolic link to no file, or to a file outside the project. */
+const unreadable = (page: string): Problem => ({ page, line: 1, kind: "missing-file", message: `${page} is a symbolic link to no file or to a file outside the project folder.` });
+
+function link(call: Call): Record<string, unknown> {
+  const check = call.flag("check");
+  const given = [...new Set(call.subjects.map((path) => posix.normalize(path)))];
+  for (const path of given) if (!files.inside(path)) throw new UsageError(`<page> must be a path relative to the project folder that stays inside it, not ${path}`);
+  for (const path of given) {
+    if (!path.endsWith(".md") && files.exists(path) && !isDirectory(path)) throw new UsageError(`<pages> takes .md files and directories, not ${path}`);
+  }
+  const directories = given.filter((path) => !path.endsWith(".md") || isDirectory(path));
+  const map = readSourceMap(call.string("source")!);
+  const givenReference = call.string("reference");
+  const reference = givenReference === undefined ? directories.map((path) => posix.join(path, "reference")).find((path) => isDirectory(path)) : posix.normalize(givenReference);
+  const problems: Problem[] = [];
+  const db = openForRead();
+  let symbols;
+  let revision;
+  try {
+    revision = currentRevision(db);
+    symbols = listSymbols(db, undefined, undefined, undefined, map.space);
+  } finally {
+    db?.close();
+  }
+  if (map.revision !== revision) {
+    problems.push({ page: map.pathOf("source-map.json"), line: 1, kind: "stale-reference", message: `The source is from knowledge revision ${map.revision}, and the knowledge is at ${revision}. Generate the source and the reference again, then run docs.ts link.` });
+  }
+  const addresses = new Map<string, number>();
+  for (const label of map.labels) addresses.set(label.name, label.address);
+  for (const symbol of symbols) addresses.set(symbol.name, symbol.address);
+  // A routine runs to the next routine; any other name to the next name of the knowledge, in its file, and outside the image at most MAX_BODY bytes.
+  const routines = symbols.filter((symbol) => symbol.kind === "routine").map((symbol) => symbol.address).sort((a, b) => a - b);
+  const named = [...new Set(symbols.map((symbol) => symbol.address))].sort((a, b) => a - b);
+  const kinds = new Map(symbols.map((symbol) => [symbol.name, symbol.kind]));
+  const bodyEnds = new Map<string, number | undefined>();
+  const bodyEnd = (name: string) => {
+    if (bodyEnds.has(name)) return bodyEnds.get(name);
+    const address = addresses.get(name);
+    let end: number | undefined;
+    if (address !== undefined) {
+      const next = ((kinds.get(name) === "routine" ? routines : named).find((other) => other > address) ?? 0x10000) - 1;
+      const file = map.lineOf(address)?.file;
+      if (file === undefined) end = Math.min(next, address + MAX_BODY - 1);
+      else {
+        end = address;
+        while (end < next && map.lineOf(end + 1)?.file === file) end++;
+      }
+    }
+    bodyEnds.set(name, end);
+    return end;
+  };
+  const nameAt = new Map(symbols.map((symbol) => [symbol.address, symbol.name]));
+  /** The routine, else the name, whose body holds an address. */
+  const placeOf = (address: number) => {
+    for (const list of [routines, named]) {
+      let start: number | undefined;
+      for (const other of list) if (other <= address) start = other;
+      const name = start === undefined ? undefined : nameAt.get(start);
+      if (name !== undefined && (bodyEnd(name) ?? start!) >= address) return name;
+    }
+    return undefined;
+  };
+
+  // The entries of the reference: each <a id> that is a name.
+  const entries = new Map<string, string>();
+  const referencePages = reference === undefined ? [] : markdownFiles(reference);
+  for (const page of referencePages) {
+    const text = files.text(page);
+    if (text === undefined) {
+      problems.push(unreadable(page));
+      continue;
+    }
+    const stamp = /^<!-- Generated by c64-docs from knowledge revision (\S+) /.exec(text);
+    if (text.startsWith(GENERATED_MARK) && stamp !== null && stamp[1] !== map.revision) {
+      problems.push({ page, line: 1, kind: "stale-reference", message: `${page} is from knowledge revision ${stamp[1]}, and the source from ${map.revision}. Run docs.ts generate again.` });
+    }
+    for (const match of text.matchAll(/<a id="([^"]+)"><\/a>/g)) if (addresses.has(match[1]!) && !entries.has(match[1]!)) entries.set(match[1]!, `${page}#${match[1]}`);
+  }
+  const inside = (path: string, directory: string | undefined) => directory !== undefined && (path === directory || path.startsWith(`${directory}/`));
+  const context = {
+    addressOf: (name: string) => addresses.get(name),
+    codeOf: (name: string) => {
+      const label = map.labelOf(name);
+      return label === undefined ? undefined : `${map.pathOf(label.file)}#L${label.line}`;
+    },
+    entryOf: (name: string) => entries.get(name),
+    bodyEnd,
+    placeOf,
+    lineOf: (address: number) => {
+      const line = map.lineOf(address);
+      return line === undefined ? undefined : `${map.pathOf(line.file)}#L${line.line}`;
+    },
+    managed: (path: string) => inside(path, posix.normalize(map.directory)) || inside(path, reference),
+  };
+
+  const pages = [...new Set(given.flatMap((path) => {
+    if (directories.includes(path)) return markdownFiles(path);
+    if (files.text(path) === undefined) throw new WireFailure("not-found", `There is no file ${path} in the project folder.`);
+    return [path];
+  }))];
+  const changedPages: string[] = [];
+  let links = 0;
+  for (const page of pages) {
+    const text = files.text(page);
+    if (text === undefined) {
+      problems.push(unreadable(page));
+      continue;
+    }
+    // A generated page is right by its making: it is only checked.
+    const generated = text.startsWith(GENERATED_MARK);
+    const linked = generated ? { text, changed: 0, problems: [] } : linkPage(text, { page, ...context });
+    problems.push(...linked.problems, ...checkLinks(page, linked.text, files));
+    if (linked.changed === 0) continue;
+    links += linked.changed;
+    changedPages.push(page);
+    if (check) continue;
+    writeProjectFile(page, Buffer.from(linked.text, "utf8"));
+    texts.set(page, linked.text);
+  }
+  const byKind: Record<string, number> = {};
+  for (const problem of problems) byKind[problem.kind] = (byKind[problem.kind] ?? 0) + 1;
+  const output: Record<string, unknown> = {
+    pages: pages.length,
+    ...(reference === undefined ? { reference: "none: run docs.ts generate for links to the entries" } : { reference }),
+    ...(check ? { notUpToDate: { links, pages: changedPages } } : { linked: { links, pages: changedPages } }),
+    problems: { byKind, ...listed(problems, call.count("max-listed")!, (problem) => ({ at: `${problem.page}:${problem.line}`, kind: problem.kind, message: problem.message })) },
+  };
+  return { result: problems.length > 0 || (check && links > 0) ? "FAIL" : "PASS", ...output };
+}
+
+const SOURCE = { kind: "path", value: "<dir>", help: "the source folder of c64-source, with its source-map.json, relative to the project folder" } as const;
+
+await runScript({
+  name: "docs",
+  summary: "Generates the reference pages of a program, and links the name mentions of the documentation to the source and the reference.",
+  commands: [
+    {
+      name: "generate",
+      summary: "Writes the reference pages: a page for each module, and pages for the names, the variables, the tables, the memory map and the graphics.",
+      subjects: [{ name: "<source-dir>", help: SOURCE.help }],
+      options: {
+        out: { ...OPTIONS.out, value: "<dir>", help: "the folder for the reference pages, relative to the project folder, for example docs/reference. generate writes only there and refuses a page in it that it did not write", required: true },
+        "max-listed": OPTIONS["max-listed"],
+      },
+      notes: "When the knowledge has the program of the source (knowledge.ts image of the c64-knowledge skill), the reference decodes the tables and shows the graphics.",
+      run: (call) => {
+        if (!isDirectory(call.subject(0))) throw new Refusal("not-found", `There is no folder ${call.subject(0)} in the project folder. Give the source folder of c64-source.`);
+        return generate(call);
+      },
+    },
+    {
+      name: "link",
+      summary: "Links the name mentions of the pages to the source and the reference, and checks every link and image. result is FAIL when a page has a problem, or with --check when a link is not up to date.",
+      subjects: [{ name: "<page>", help: ".md files and folders of the documentation, relative to the project folder, for example README.md docs. link reads each file and every .md file below each folder", list: true }],
+      options: {
+        source: { ...SOURCE, required: true },
+        reference: { kind: "path", value: "<dir>", help: "the reference pages of docs.ts generate. The default is the reference/ folder of the first folder that has one" },
+        check: { kind: "flag", help: "write nothing. FAIL when a link is not up to date or a page has a problem" },
+        "max-listed": OPTIONS["max-listed"],
+      },
+      notes: "A name in backticks gets a link to its line in the source. An address in backticks after the name gets a link to the entry of the name in the reference.",
+      run: link,
+    },
+  ],
+});

package/skills/c64-docs/scripts/lib/source-map.ts

@@ -38,7 +38,7 @@ export function readSourceMap(directory: string): SourceMap {
     text = readProjectFile(path).bytes.toString("utf8");
   } catch (error) {
     if (error instanceof WireFailure && error.code === "not-found") {
-      throw new WireFailure("not-found", `There is no ${path}. Generate the source with c64-source generate.ts --out ${directory}: it writes the source map.`);
+      throw new WireFailure("not-found", `There is no ${path}. Generate the source with c64-source source.ts generate --out ${directory}: it writes the source map.`);
     }
     throw error;
   }

package/skills/c64-emulator/SKILL.md

@@ -17,7 +17,7 @@ This skill does not analyse code statically. It does not write project knowledge
 - The target address, state or condition, when the question needs one.
 - The project path of the program or disk to load, when the question needs one.
 
-Addresses are four hex digits after a dollar sign, for example `$c000`. Resolve a symbol name to its address before you use a tool. The c64-knowledge skill gives the address of a known symbol.
+An address is `$` and 1 to 4 hex digits, for example `$c000` or `$fb`. A tool takes no names. Get the address of a name with `knowledge.ts at <name>` of the c64-knowledge skill.
 
 ## Tools / execution path
 
@@ -34,20 +34,20 @@ Use only the MCP tools. Each MCP session has its own C64. Nothing else can chang
 | Run to a place and read the machine there in one call | `c64_run_until` with `observe` and `history` |
 | Each write, read or routine entry over many frames, with the instruction and the raster line | `c64_trace` |
 | Stop on an instruction address | `c64_breakpoint` |
-| Stop on a memory read or write | `c64_watchpoint` |
+| Stop on a memory read or write from `start` to `end` | `c64_watchpoint` |
 | Memory | `c64_memory_read`, `c64_memory_write`, `c64_memory_search`, `c64_memory_compare` |
-| CPU registers | `c64_registers` |
+| CPU registers | `c64_registers` (action `read` or `write`) |
 | Code as it is in memory now | `c64_disassemble` |
 | Executed instructions, call chain | `c64_cpu_history`, `c64_backtrace` |
 | Which instruction reads or writes an address | `c64_trace` with a `read` or `write` point |
 | Where the CPU spends cycles, which memory it uses | `c64_profile`, `c64_memmap` |
 | Cycle count between two points | `c64_timing` |
 | Video chip, sprites, CIAs, sound chip | `c64_vicii`, `c64_sprite`, `c64_cia`, `c64_sid` |
-| Screen image, screen compare | `c64_screen` |
+| Screen image, screen compare, remove a baseline | `c64_screen` |
 | Several of these from one moment | `c64_observe` |
 | Keys, joystick | `c64_keyboard`, `c64_joystick` |
 | Program and disk media | `c64_autostart`, `c64_program_load`, `c64_disk_attach` |
-| Machine state to go back to, also in a later session | `c64_snapshot` (with `out` and `file`) |
+| Machine state to go back to, also in a later session, remove a snapshot | `c64_snapshot` (with `out` and `file`) |
 
 Each memory and register tool has a `space`. Use `c64` for the computer. Use `drive8` for the CPU of the 1541 disk drive. The memory `view` is `cpu` or `ram`. With `cpu`, you see what the CPU sees now, with ROM and I/O where the memory configuration puts them. With `ram`, you see the RAM under them.
 
@@ -82,10 +82,12 @@ A cartridge from `c64_autostart` stays in the C64 through every reset, as on a r
 
 Step, next and until-return work only in space `c64`. The emulator cannot stop the disk drive CPU after one instruction. To find when the drive executes an address, use `c64_run_until` with an address target in space `drive8`, or a breakpoint in space `drive8`. The drive can execute a few more instructions before it stops. The computer completes its current instruction. The `pc` in the result is the drive address where it stopped.
 
-`c64_keyboard` puts keys in the keyboard queue of the KERNAL. A program that reads the keyboard hardware directly does not see them. Many games do this. The emulator has no command that presses one key of the keyboard matrix. For such a program:
+`c64_keyboard` puts keys in the keyboard queue of the KERNAL. A program that reads the keyboard matrix directly does not see them. Many games do this. No MCP tool presses a key of the keyboard matrix. For such a program:
 
 - VICE 3.10 and older have a known flaw: bits 5-7 of `$DC00` and `$DC01` are always 0. Then `emulatorFlaw` in the result of `c64_keyboard` and `c64_joystick` gives the flaw. With this flaw, a wait for any key that reads all keyboard columns at one time ends without a key. A wait for one specific key, or a compare of the full byte of a joystick port, never ends. Tell the user about the flaw. The next VICE release and the VICE nightly builds do not have it. Joystick port 1 uses the same lines as the keyboard.
-- For one specific key, for example F1 or RUN/STOP, open the window and ask the user to press the key.
+- For one specific key, for example F1 or RUN/STOP, use one of these two ways:
+  - Open the window and ask the user to press the key.
+  - Record a session with a `press` step. Use `testing.ts record` of the c64-testing skill.
 - Do not change the program to make it accept a key.
 
 Before a risky experiment, save the state with `c64_snapshot`. Restore it to try again from the same point.
@@ -126,6 +128,8 @@ If you cannot get the machine into the necessary state, say which state you coul
 
 ## Failure and conflicts
 
+An error is `{"error": {"code": "...", "message": "..."}}`. The message tells what is wrong and what to do.
+
 - `machine-state-lost` and the message says that the VICE window closed: the window closed before `c64_window` action `close`. The emulator has no window again. The machine state is the same as at the time when the window opened. The breakpoints and the watchpoints stay. Do not use results from the window time. Read the machine state again, then continue.
 - `machine-unavailable` and the message says that the VICE window closed: the session starts the emulator again. Wait a few seconds. Then do the operation again.
 - `machine-state-lost` with a different message: the connection to the host runtime was lost, and the machine state is gone. Do not continue with results from before. The next call starts a new machine when the host runtime runs. Load the program again, and set the breakpoints and the watchpoints again. If the next call gives `machine-unavailable` with a message that the host runtime does not run, obey the rule for that message.

package/skills/c64-knowledge/SKILL.md

@@ -24,43 +24,41 @@ One of these:
 ## Tools / execution path
 
 ```
-node <skill>/scripts/knowledge.ts <command> [arguments] [options]
+node <skill>/scripts/knowledge.ts <command> [subjects] [options]
 ```
 
-The script prints one JSON object. An error prints `{"error": {"code": ..., "message": ...}}`. Addresses are `$` and four hex digits. Quote them in a shell, for example `'$2100'`. A name also gives an address, for example `at update_player`. The script tries the symbols first and then the analyzer names.
-
 A symbol is the name of an address from the user or the LLM. An analyzer name is a second name from DXA, Ghidra or an idiom, for example `FUN_17e2`. Each analyzer keeps its own name at an address. `at`, `search` and `export` show the analyzer names. The generated source uses only the symbols, unless c64-source gets `--analyzer-names`. To use an analyzer name in the source, `rename` the address with it.
 
 | Need | Command |
 |---|---|
 | Everything known at one address | `at '$2100'` |
 | Find names and comment text | `search player` |
-| Lists in a range | `symbols`, `regions`, `comments`, `references` with `--start` and `--end` |
+| Lists in a range | `symbols`, `regions`, `comments`, `references` with `--range '$2000-$2fff'` |
 | The names that DXA, Ghidra and the idioms gave | `symbols --analyzer` |
 | Only some origins | add `--origin semantic`, `--origin analyzer` (dxa, ghidra and heuristic), or `--origin user,llm` |
 | All knowledge in one file | `export --out .c64-re-tools/local/knowledge.json` |
 | Put the program into the knowledge | `image .c64-re-tools/local/capture/image.json` or `image original/game.prg` |
 | Add the coverage of runs | `coverage .c64-re-tools/local/runs/rooms/room0.bin ...` |
 | What the knowledge holds of the program | `program` |
-| The code of a range with names, comments, access and references | `listing '$0400' '$04ff'` |
+| The code of a range with names, comments, access and references | `listing '$0400-$04ff'` |
 | Name the symbol at an address | `rename '$2100' update_player --kind routine` |
 | Remove a symbol | `remove-symbol '$2100'` |
-| Classify memory | `classify '$3000' '$303f' sprite` |
-| Classify a table of records | `classify '$3000' '$303b' bytes --element 6` |
+| Classify memory | `classify '$3000-$303f' sprite` |
+| Classify a table of records | `classify '$3000-$303b' bytes --element 6` |
 | Many writes as one revision | `apply -` with the JSON on standard input, or `apply <file>` |
 | One batch from the batches of parallel agents | `join a.json b.json --out .c64-re-tools/local/joined.json` |
-| Make memory unknown, and keep the analyzers out of it | `unclassify '$3000' '$303f'` |
+| Make memory unknown, and keep the analyzers out of it | `unclassify '$3000-$303f'` |
 | Set or remove a comment | `comment '$2100' line Reads joystick 2.` / `uncomment '$2100' line` |
 | Add or remove a reference | `reference '$2000' '$2100' call` / `unreference ...` |
-| Places that a removal blocks | `suppressions` with `--start` and `--end` |
+| Places that a removal blocks | `suppressions` with `--range` |
 | Start a file of generated source | `module '$2000' player.asm --title 'Player movement'` / `unmodule '$2000'` |
 | Write the operand of an instruction as an expression | `operand '$8079' --lo irq_handler` / `unoperand '$8079'` |
-| Operand expressions | `operands` with `--start` and `--end` |
-| Replace a range with code when a switch is on | `patch '$100e' '$1010' CRACK --code-file crack.asm` / `unpatch '$100e'` |
+| Operand expressions | `operands` with `--range` |
+| Replace a range with code when a switch is on | `patch '$100e-$1010' CRACK --code-file crack.asm` / `unpatch '$100e'` |
 | Patches and switches | `patches` with `--switch`, and `switches` |
 | Write a macro | `macro inc16 --params dst --body-file inc16.asm` / `unmacro inc16` |
-| Write instructions as one use of a macro | `use '$1005' '$100a' inc16 --args ptr` / `unuse '$1005'` |
-| Macros and their uses | `macros`, and `uses` with `--start`, `--end` and `--macro` |
+| Write instructions as one use of a macro | `use '$1005-$100a' inc16 --args ptr` / `unuse '$1005'` |
+| Macros and their uses | `macros`, and `uses` with `--range` and `--macro` |
 | Files of generated source | `modules` |
 | The address spaces that hold knowledge | `spaces` |
 | History | `history '$2100'`, `history --name update_player`, `history --macro inc16`, `revisions`, `revision 20261015T2145` |
@@ -89,12 +87,24 @@ Region types:
 
 `--element` gives the bytes of one element of a table. The length of the region must be a multiple of it. The result shows `element` and `count`.
 
+### Calling the script
+
+- Call a script as `node <skill>/scripts/<script>.ts <command> [subjects] [options]`. The command comes first.
+- `<script>.ts --help` lists the commands. `<script>.ts <command> --help` gives the subjects and the options of one command. The help is JSON: `{"text": "..."}`.
+- An address is `$` and 1 to 4 hex digits, for example `'$c000'` or `'$fb'`, or a name. A name is a symbol, else an analyzer name that only one analyzer gives. Quote an address in a shell.
+- A range is `<start>-<end>`, for example `'$c000-$cfff'`. In a JSON file, a range is `start` and `end`.
+- Bytes in a JSON file are hex in a field `data`, for example `"data": "a900"`.
+- The result is one JSON object on one line. A file that the script writes shows as `{"out", "bytes", "sha256"}`. A list shows as `{"count", "listed"}`, and `rest` tells where to get the rest of a long list.
+- An error is `{"error": {"code": "...", "message": "..."}}`. The message tells what is wrong and what to do.
+- The exit status is 0 for done or PASS, 1 for FAIL, 2 for an error and 3 for INCONCLUSIVE.
+
 ### Project folder
 
 - Paths are relative to the project folder. The project folder is the nearest folder at or above the working directory that holds `.c64-re-tools/`.
 - If the working directory is not in a project and has projects below it, the script refuses and lists them. Then give `--project <folder>` to each script.
 - Write each file that you make for your work in `.c64-re-tools/local/` of the project. Git ignores that folder. Examples are results, batches, step files, runs, snapshots and memory dumps.
-- Move a file out of `.c64-re-tools/local/` only when it is the evidence for a finding. Move it before you give it to `--evidence` of c64-knowledge. `--evidence` refuses a file in `.c64-re-tools/local/`.
+- Move a file out of `.c64-re-tools/local/` only when it is the evidence for a finding. Move it before you give it to `--evidence test:<file>` or `--evidence file:<file>` of c64-knowledge. These two refuse a file in `.c64-re-tools/local/`.
+- Do not move a coverage map after `coverage` of c64-knowledge imported it. `--evidence coverage:<map>` names the map by its path at the import. The knowledge keeps the coverage and the SHA-256 of the map, so the evidence stays valid.
 - Put a run that is evidence in `runs/<name>/`, with its run file, its results and the snapshot files that it uses. Change the paths in the run file to the new paths. Then git keeps them, and another person can do the run again.
 - A shell redirect (`>`) is relative to the working directory, not to the project folder. From the folder above the project, write `<folder>/.c64-re-tools/local/result.json`.
 
@@ -109,7 +119,10 @@ Write:
 
 1. Read the current value with `at`. Note the `revision` in the result.
 2. Decide the change. Keep observed facts apart from your conclusions.
-3. Write it with `--reason` and `--expect-revision` set to the revision you read. Add `--evidence` for each thing that the change rests on: `coverage:<map>`, `test:<file>`, `file:<file>` or `note:<text>`. `<map>` is a coverage map that `coverage` put into the knowledge, by its path at that time. The script uses the last import of the map into the space of the write. The script keeps the SHA-256 of each file and map.
+3. Write it with `--reason` and `--expect-revision` set to the revision you read. Add `--evidence` for each thing that the change rests on: `coverage:<map>`, `test:<file>`, `file:<file>` or `note:<text>`.
+   - `coverage:<map>` names a map by its path at the import. The script uses the last import of that map into the space of the write.
+   - `test:<file>` and `file:<file>` name a file outside `.c64-re-tools/local/`. Move the file before the write.
+   - The script keeps the SHA-256 of each file and map.
 4. Read the result. A `revision` of `null` means that nothing changed.
 
 Each write is one revision. A classification inside a region splits that region, so regions never overlap.
@@ -170,7 +183,7 @@ The c64-provenance skill writes a batch with `match --out`. The batch holds the
 
 ## Batches of parallel agents
 
-When more agents name the program at the same time, give each agent one range of addresses. Each agent writes one batch file and does not apply it. A batch of an agent has the form `{"owner": "$1000-$1fff", "ops": [...]}`. `ops` holds the writes, as for `apply`. The owner ranges must not overlap.
+When more agents name the program at the same time, give each agent one range of addresses. Each agent writes one batch file and does not apply it. A batch of an agent has the form `{"owner": {"start": "$1000", "end": "$1fff"}, "ops": [...]}`. `ops` holds the writes, as for `apply`. The owner ranges must not overlap.
 
 `join` makes one batch from the batch files. It writes no knowledge.
 
@@ -179,7 +192,7 @@ When more agents name the program at the same time, give each agent one range of
 - The regions of the owner come after the regions of the other batches. Thus the regions of the owner stay where they overlap.
 - A name from a batch stays when another batch removes the symbol at that address.
 - `choices` lists each place where the batches gave different values, with the value that stays.
-- When one name or one module file is at two addresses, `join` writes nothing. `clashes` lists the addresses and the batches. Correct the batches, then do `join` again.
+- When one name or one module file is at two addresses, `join` writes nothing and gives the error `conflict`. The message names the addresses and the batches. Correct the batches, then do `join` again.
 
 Then apply the joined batch with the command in `apply`.
 
@@ -235,7 +248,7 @@ A macro writes a run of instructions as one line of the source, for example `+in
 - The knowledge refuses `unmacro` while the macro has uses. It also refuses a change of the number of params while the macro has uses.
 - A use cannot overlap a patch or another use.
 
-The c64-source skill writes a use only when the use gives the bytes of the program. If not, it writes the instructions and gives the reason. The c64-static-analysis skill finds uses of known 6502 idioms and writes them to a batch with `--macro-batch`.
+The c64-source skill writes a use only when the use gives the bytes of the program. If not, it writes the instructions and gives the reason. The c64-static-analysis skill finds uses of known 6502 idioms and writes them to a batch with `--out-macro-batch`.
 
 ## Removals
 
@@ -260,7 +273,7 @@ Do not store:
 - a guess, only because a routine needs a temporary name
 - confidence or status words in comment text.
 
-The script records the origin `llm`. Use `--origin user` only when the user decides the change.
+The script records the origin `llm`. Use `--by user` only when the user decides the change.
 
 ## Result
 
@@ -268,13 +281,13 @@ For a read: the current or historical knowledge in compact JSON.
 
 For a write: the new revision and the current value after the write. If the write replaces a symbol, a region or an operand expression of a different origin, `previous` gives that row as it was before the write. For example, an `llm` write over a `user` name gives `previous`. Read `previous` and tell the user about the change. For `apply`, `replaced` lists each write that replaced a row. Each item has the number of the write, its `op` and its `previous`.
 
-The exit status is 0 for a result. The exit status is 1 for an error from the knowledge, for example `conflict`. The exit status is 2 for a wrong argument.
+For `export`, `listing --out` and `join`: the written file as `{out, bytes, sha256}`.
 
 ## Failure and conflicts
 
 - `conflict`: the change contradicts current knowledge. For example, the name belongs to another address. Read that address and its history, then decide.
 - `stale-revision`: the knowledge changed after you read it. Read it again, then decide again.
-- `not-found`: there is nothing to remove or no such revision.
+- `not-found`: there is nothing to remove, no such revision or no such file.
 - `conflict` with "from a git merge": git joined the knowledge of two computers, and two rows are current where the knowledge permits one row. For example, two names are at one address. Every read shows these rows in `conflicts`. Writes stop until you run `merge`. The `merge` command keeps the newest row of each conflict and closes the other rows, in one revision. Its result lists each choice. Tell the user the choices.
 - `invalid-database` or `unsupported-schema`: tell the user the message. Do not edit the knowledge files.