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

package/README.md

@@ -1,5 +1,8 @@
 # c64-re-tools
 
+<img src="assets/branding/c64-re-tools-transparent.svg" alt="C64 RE Tools" width="440">
+
+
 Let an AI agent work on Commodore 64 programs. The agent drives a real VICE
 emulator and runs ACME, DXA and Ghidra. Use it to build new C64 apps and games,
 and to reverse engineer old ones.
@@ -51,7 +54,7 @@ npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host
 
 ### Dev container
 
-This is the preferred way. The container gets Node.js 24, ACME, dxa, Java 21 and Ghidra,
+This is the preferred way. The container gets Node.js 24, ACME, dxa, Java 21, Ghidra and c64run,
 installs the toolkit into the project when it is created, and updates it at
 each start. Add to `.devcontainer/devcontainer.json`:
 
@@ -67,7 +70,7 @@ needs a Debian or Ubuntu image. `runArgs` is for Docker on Linux.
 
 ### Without a container
 
-Install ACME, dxa and Ghidra as in [docs/install-tools.md](docs/install-tools.md).
+Install ACME, dxa, Ghidra and c64run as in [docs/install-tools.md](docs/install-tools.md).
 Then, in your project:
 
 ```
@@ -119,7 +122,7 @@ program its own folder. A folder with `.c64-re-tools/` is a project.
 | c64-unpacker | Packing evidence, and capture of the unpacked program. |
 | c64-static-analysis | Analysis with DXA and Ghidra into the knowledge. |
 | c64-knowledge | Symbols, regions, comments and references, with history. |
-| c64-provenance | Compares releases, and keeps a library of shared routines. |
+| c64-provenance | Compares releases, finds leftovers of the development and of cracks, and keeps a library of shared routines. |
 | c64-source | ACME source from the knowledge, checked byte for byte. |
 | c64-docs | Documentation of a program from its knowledge and source. |
 | c64-reverse-engineering | Leads an investigation and picks the next skill. |
@@ -129,7 +132,8 @@ program its own folder. A folder with `.c64-re-tools/` is a project.
 | Variable | Meaning |
 | --- | --- |
 | `C64RT_VICE`, `C64RT_C1541`, `C64RT_PETCAT` | Full path of the VICE tool, when it is not on `PATH` (host). |
-| `C64RT_ACME`, `C64RT_DXA` | Full path of the tool, when it is not on `PATH`. |
+| `C64RT_ACME`, `C64RT_DXA`, `C64RT_C64RUN` | Full path of the tool, when it is not on `PATH`. |
+| `C64RT_C64_ROMS` | The C64 ROM folder of c64run, when it is not `share/c64-re-tools/roms` next to its `bin`. |
 | `C64RT_GHIDRA` | The Ghidra installation directory, when `analyzeHeadless` is not on `PATH`. |
 | `C64RT_HOST` | `host:port` of the Host Runtime, when it is not on 127.0.0.1, `host.docker.internal` or `host.containers.internal` at port 6464. |
 | `C64RT_VIDEO` | `pal` (default) or `ntsc`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/c64-re-tools",
-  "version": "2.0.1",
+  "version": "2.1.0-rc.2",
   "description": "Agent-friendly Commodore 64 engineering toolkit for reverse engineering, debugging, development and testing.",
   "license": "MIT",
   "author": "Henrik Olsson",

package/skills/c64-assembler/SKILL.md

@@ -23,7 +23,7 @@ This skill does not run the program and does not change project knowledge.
 The script runs ACME on this machine. It copies the source root to a temporary directory, assembles it there and writes the program into the project. The host runtime is not necessary.
 
 ```
-node <skill>/scripts/assemble.ts --source-root src --entry main.a --out build/game.prg
+node <skill>/scripts/assembler.ts build src main.a --out build/game.prg
 ```
 
 | Option | Meaning |
@@ -37,14 +37,26 @@ node <skill>/scripts/assemble.ts --source-root src --entry main.a --out build/ga
 
 The script copies the full source root. Put all files that the program includes under it. Version control directories stay out.
 
-The script prints one JSON object. The target CPU is the 6510. The output is a C64 PRG, or the bytes only with `--plain`.
+The target CPU is the 6510. The output is a C64 PRG, or the bytes only with `--plain`.
+
+### 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`.
 
@@ -52,11 +64,11 @@ The script prints one JSON object. The target CPU is the 6510. The output is a C
 
 1. Find the source root and the entry source. The entry source sets its own start address with `* = $0801` or similar.
 2. Run the script.
-3. If `assembled` is `true`, the PRG is at `output`. `loadRange` tells where it loads. `symbols` gives each symbol:
+3. If `result` is `PASS`, the PRG is at `out`. `loadRange` tells where it loads. `symbols` gives each symbol:
    - Kind `address` has a value in `loadRange`. It gives the `address`.
    - Kind `constant` has a value outside `loadRange`. It gives the `value` as `$` and four or more hex digits. A label in a `!pseudopc` block can be a constant, because its value is the run address, not the load address.
    - `used` is `false` when the source does not use the symbol.
-4. If `assembled` is `false`, read `diagnostics`. Each one has a severity, a file, a line and a message. Correct the source and run the script again.
+4. If `result` is `FAIL` and `assembled` is `false`, read `diagnostics`. Each one has a severity, a file, a line and a message. Correct the source and run the script again.
 5. To run the program, give the PRG path to the c64-emulator skill.
 
 The source of the c64-source skill has switches. Each switch is 0 when the build does not define it. `--define CRACK=1` puts in the patches of the switch `CRACK`. With `--compare`, only the bytes of those patches are different.
@@ -74,15 +86,18 @@ A symbol from the rebuilt source can give the address of a routine in the rebuil
 
 ## Result
 
-The PRG in the project at the output path, with its load range and symbols. Or the source diagnostics when the assembly failed.
+`result` is `PASS` or `FAIL`.
 
-With `--compare`, `compare` gives `identical` and one check for each segment of the program in the knowledge. A check is `identical`, `different` with the first different address, or `not covered` when the program does not hold the segment.
+- `PASS`: the PRG is in the project at `out`, with its load range and symbols.
+- `FAIL` with `assembled: false`: the source has errors. `diagnostics` gives them.
+- `FAIL` with `assembled: true`: `--compare` found differences. The PRG is at `out`.
 
-The exit status is 0 for a PRG. The exit status is 1 for `assembled: false`, for a `--compare` that is not identical, and for an error. The exit status is 2 for a wrong argument.
+With `--compare`, `compare` gives `identical` and `segments`: one check for each segment of the program in the knowledge. The `result` of a check is `identical`, `different` with `firstDifference`, or `not covered` when the build does not hold the segment.
 
 ## Failure and conflicts
 
-- `assembled: false`: the source has errors. This is a normal result. Correct the source.
+- `FAIL` with `assembled: false`: the source has errors. Correct the source.
+- `FAIL` with `assembled: true`: the build is not identical to the program in the knowledge. Read `compare.segments`.
 - `installation-incomplete`, or `machine-unavailable` with a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
 - `invalid-input`: an option or a path is wrong. Read the message and correct the call.
 

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

@@ -0,0 +1,95 @@
+// The c64-assembler script: assembles project source with ACME, which it runs
+// itself, and writes the program into the project.
+
+import { formatC64Address } from "#src/c64.ts";
+import { Refusal } from "#src/errors.ts";
+import { readProjectTree, writeReported } from "#src/host-client/transfer.ts";
+import { openForRead } from "#src/knowledge/database.ts";
+import { knowledgeNames } from "#src/knowledge/names.ts";
+import { requireProgram, type ProgramImage } from "#src/knowledge/program.ts";
+import { assemble } from "#src/native/acme.ts";
+import { localToolContext } from "#src/native/local.ts";
+import type { AcmeParams } from "#src/native/types.ts";
+import { OPTIONS, runScript, UsageError } from "#src/script.ts";
+import { compareBuild } from "./lib/compare.ts";
+
+function parseDefine(text: string): [string, number | boolean] {
+  const match = /^([A-Za-z_][A-Za-z0-9_]*)=(.+)$/.exec(text);
+  if (match === null) throw new UsageError(`--define needs NAME=VALUE, not ${text}`);
+  const value = match[2]!;
+  if (value === "true" || value === "false") return [match[1]!, value === "true"];
+  if (/^\$[0-9a-fA-F]+$/.test(value)) return [match[1]!, Number.parseInt(value.slice(1), 16)];
+  if (/^-?\d+$/.test(value)) return [match[1]!, Number(value)];
+  throw new UsageError(`--define ${match[1]} needs an integer or true/false, not ${value}`);
+}
+
+await runScript({
+  name: "assembler",
+  summary: "Assembles project source with ACME and writes the program into the project.",
+  names: knowledgeNames,
+  commands: [
+    {
+      name: "build",
+      summary: "Assembles the source and writes the program. result is PASS when it assembles (and with --compare, when it is the program of the knowledge), else FAIL with the diagnostics or the differences.",
+      subjects: [
+        { name: "<source-root>", help: "the folder in the project to assemble from: all of it is sent" },
+        { name: "<entry>", help: "the main source file, relative to the source root" },
+      ],
+      options: {
+        out: { ...OPTIONS.out, value: "<file.prg>", help: "where to write the program, relative to the project folder", required: true },
+        include: { kind: "text", value: "<dir>", multiple: true, help: "an include folder, relative to the source root" },
+        define: { kind: "text", value: "NAME=VALUE", multiple: true, help: "an assembler symbol: an integer ($hex allowed) or true/false" },
+        "set-pc": { kind: "address", value: "<address>", help: "the start address when the source sets none, for example '$0801'" },
+        compare: { kind: "flag", help: "check the program byte by byte against the program in the knowledge, each segment" },
+        space: { ...OPTIONS.space, help: "with --compare: the knowledge space of the program: c64 (the default), drive8, or bank0 to bank255" },
+        plain: { kind: "flag", help: "write the bytes only, without the 2-byte load address of a PRG" },
+        "all-symbols": { kind: "flag", help: "list also the constants that the source does not use" },
+      },
+      notes: "Symbol values are $ and at least four hex digits. Put the program into the knowledge with knowledge.ts image of the c64-knowledge skill before --compare.",
+      run: async (call) => {
+        const [sourceRoot, entry] = [call.subject(0), call.subject(1)];
+        const out = call.string("out")!;
+        // Read the program before ACME runs, so a project without it stops at once.
+        let program: ProgramImage | undefined;
+        if (call.flag("compare")) {
+          const db = openForRead();
+          try {
+            program = requireProgram(db, call.space);
+          } finally {
+            db?.close();
+          }
+        }
+        const setPc = call.address("set-pc");
+        const tree = readProjectTree(sourceRoot);
+        if (!tree.files.some((file) => file.path === entry)) throw new Refusal("not-found", `${entry} is not a file in ${sourceRoot}. Give the main source file relative to the source root.`);
+        const params: AcmeParams = { files: tree.files, entrySource: entry, includeDirs: call.strings("include"), defines: Object.fromEntries(call.strings("define").map(parseDefine)), ...(setPc === undefined ? {} : { setPc }) };
+
+        const { result, attachments } = await assemble(params, tree.contents, localToolContext());
+        if (!result.assembled) return { result: "FAIL", assembled: false, diagnostics: result.diagnostics };
+        const plain = call.flag("plain");
+        const written = writeReported(out, plain ? attachments![0]!.subarray(2) : attachments![0]!, { what: "--out" });
+        const range = result.loadRange!;
+        const compared = program === undefined ? undefined : compareBuild(attachments![0]!, program);
+        // An include file of platform names gives many constants that the program does not use.
+        const all = call.flag("all-symbols");
+        const listed = result.symbols!.filter((symbol) => all || symbol.kind === "address" || symbol.used);
+        return {
+          // A build that differs from its reference is a failed check.
+          result: compared !== undefined && !compared.identical ? "FAIL" : "PASS",
+          assembled: true,
+          ...written,
+          ...(plain ? { plain: true } : {}),
+          loadRange: { start: formatC64Address(range.start), end: formatC64Address(range.end), bytes: range.bytes },
+          symbols: listed.map((symbol) =>
+            symbol.kind === "address"
+              ? { name: symbol.name, kind: "address", address: formatC64Address(symbol.address), used: symbol.used }
+              : { name: symbol.name, kind: "constant", value: `$${symbol.value.toString(16).padStart(4, "0")}`, used: symbol.used },
+          ),
+          ...(all ? {} : { unusedConstants: result.symbols!.length - listed.length }),
+          diagnostics: result.diagnostics,
+          ...(compared === undefined ? {} : { compare: compared }),
+        };
+      },
+    },
+  ],
+});

package/skills/c64-basic/SKILL.md

@@ -20,23 +20,33 @@ This skill does not run the program and does not change project knowledge.
 The script sends the program to the host runtime. The host decodes it with petcat and finds the handoffs.
 
 ```
-node <skill>/scripts/basic.ts extracted/game.prg
+node <skill>/scripts/basic.ts list extracted/game.prg
 ```
 
-The script prints one JSON object. Addresses are `$` and four hex digits.
+### 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`.
 
 ## Workflow
 
-1. Run the script on the program.
+1. Run `list` on the program.
 2. Read `listing`. Each line starts with its BASIC line number. Keywords show in lower case. Control characters in strings show in braces, for example `{clr}`.
 3. Read `handoffs`. Each handoff has a `kind` (`sys` or `usr`) and the BASIC `line`.
    - A `sys` handoff with an `address`: BASIC calls the machine code at that address. The script calculates a SYS argument with numbers, π, `+`, `-`, `*`, `/` and brackets. For example, `SYS π*656` calls `$080c`.
@@ -57,16 +67,14 @@ The entry point of the machine code can be durable knowledge. The c64-reverse-en
 
 ## Result
 
-The listing and the handoff addresses. Or `decoded: false` with a reason when the file is not a BASIC program.
-
-The exit status is 0 for a listing. The exit status is 1 for `decoded: false` and for an error. The exit status is 2 for a wrong argument.
+The listing and the handoff addresses.
 
 ## Failure and conflicts
 
-- `decoded: false`: the file is not a BASIC program. This is a normal result. Usually the file is machine code. Give it to the c64-static-analysis skill. A memory dump also gives `decoded: false`: its first two bytes are not a load address, and its bytes go past `$ffff`.
+- `invalid-input` with "is no BASIC program": the file is not a BASIC program. Usually the file is machine code. Give it to the c64-static-analysis skill. A memory dump also gives this error: its first two bytes are not a load address, and its bytes go past `$ffff`.
 - An empty `handoffs` list: the BASIC does not start machine code with SYS or USR. Do not make up a handoff. Look for a POKE into a vector or a LOAD of another file in the listing.
 - `installation-incomplete`, or `machine-unavailable` with a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
-- `not-found` or `invalid-input`: the path or an argument is wrong. Read the message and correct the call.
+- `not-found` or another `invalid-input`: the path or an argument is wrong. Read the message and correct the call.
 
 ## Handoffs
 

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

@@ -2,45 +2,35 @@
 // through the Host Runtime and reports its machine-code handoffs.
 
 import { statSync } from "node:fs";
-import { parseArgs } from "node:util";
 
 import { formatC64Address } from "#src/c64.ts";
+import { Refusal } from "#src/errors.ts";
 import { decodeBasic } from "#src/host-client/tools.ts";
 import { resolveProjectPath } from "#src/project.ts";
-import { runScript, UsageError } from "#src/script.ts";
+import { runScript } from "#src/script.ts";
 
-const USAGE = `basic.ts <program>
-
-<program> is a PRG file relative to the project folder. The result is one
-JSON object. Addresses are $ and four hex digits.`;
-
-async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }> {
-  const { values, positionals } = parseArgs({ args: argv, strict: true, allowPositionals: true, options: { help: { type: "boolean" } } });
-  if (values.help) throw new UsageError("");
-  if (positionals.length !== 1) throw new UsageError("give one program");
-  const program = positionals[0]!;
-  const result = await decodeBasic({ program });
-  if (!result.decoded) return { output: { decoded: false, reason: result.reason }, failed: true };
-  const size = statSync(resolveProjectPath(program)).size - 2;
-  const end = result.loadAddress + size - 1;
-  return {
-    output: {
-      decoded: true,
-      loadRange: { start: formatC64Address(result.loadAddress), end: formatC64Address(end) },
-      // From here to the end of the load range, the file holds no BASIC (often machine code).
-      basicEnd: result.basicEnd <= end ? formatC64Address(result.basicEnd) : null,
-      listing: result.listing,
-      handoffs: result.handoffs.map((handoff) => ("address" in handoff ? { ...handoff, address: formatC64Address(handoff.address) } : handoff)),
+await runScript({
+  name: "basic",
+  summary: "Decodes a C64 BASIC V2 program with petcat and reports its machine-code handoffs: SYS and USR.",
+  commands: [
+    {
+      name: "list",
+      summary: "The BASIC lines of a PRG, where the BASIC ends, and the handoffs to machine code.",
+      subjects: [{ name: "<program>", help: "a PRG file, relative to the project folder" }],
+      run: async (call) => {
+        const program = call.subject(0);
+        const result = await decodeBasic({ program });
+        if (!result.decoded) throw new Refusal("invalid-input", `${program} is no BASIC program: ${result.reason}`);
+        const size = statSync(resolveProjectPath(program)).size - 2;
+        const end = result.loadAddress + size - 1;
+        return {
+          loadRange: { start: formatC64Address(result.loadAddress), end: formatC64Address(end) },
+          // From here to the end of the load range, the file holds no BASIC (often machine code).
+          basicEnd: result.basicEnd <= end ? formatC64Address(result.basicEnd) : null,
+          listing: result.listing,
+          handoffs: result.handoffs.map((handoff) => ("address" in handoff ? { ...handoff, address: formatC64Address(handoff.address) } : handoff)),
+        };
+      },
     },
-    failed: false,
-  };
-}
-
-await runScript(
-  async (argv) => {
-    const { output, failed } = await run(argv);
-    if (failed) process.exitCode = 1;
-    return output;
-  },
-  { usage: USAGE },
-);
+  ],
+});

package/skills/c64-disk/SKILL.md

@@ -23,7 +23,7 @@ This skill does not change the disk image and does not change project knowledge.
 The script sends a disk image to the host runtime. The host runs c1541 and sends the result back. The script writes an extracted file into the project. It reads T64 and CRT files itself.
 
 ```
-node <skill>/scripts/disk.ts <action> <image> [name] [--out <file>]
+node <skill>/scripts/disk.ts <command> <image> [name] [--out <file>]
 ```
 
 | Need | Command |
@@ -38,16 +38,26 @@ node <skill>/scripts/disk.ts <action> <image> [name] [--out <file>]
 | The banks of a cartridge | `directory original/game.crt` |
 | Write each bank of a cartridge as a PRG | `crt original/game.crt --out cart` |
 
-The script prints one JSON object.
-
 File names show the characters that the C64 shows in a directory list. A byte that has no character shows as `{$xx}`, for example `{$c1}`. Write the name in the same form. The letter case of a name is not important. Put the name in single quotes in a shell, for example `'GAME {$c1}'`. A name that starts with `-` needs `--` before it, after all options, for example `read d.d64 --out x.prg -- '-----'`.
 
+### 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`.
 
@@ -80,13 +90,13 @@ The script reads T64 and CRT files itself. The host runtime is not necessary for
 
 ## Result
 
-The directory, the BAM, an entry or a sector chain as JSON. Or the extracted file in the project at the output path.
+The directory, the BAM, an entry or a sector chain as JSON.
 
-The exit status is 0 for a result with the file. The exit status is 1 for `found: false` and for an error. The exit status is 2 for a wrong argument.
+`read` writes the file at the output path. Its result gives the `name` and the file as `{out, bytes, sha256}`. `crt` gives the header, `chips` and `files`: one item for each PRG and one for `crt.json`.
 
 ## Failure and conflicts
 
-- `found: false`: the image has no file with that name. This is a normal result. Read the directory again and compare the names.
+- `not-found`: the image file is missing, or the image has no file with that name. Read the directory again and compare the names.
 - `media-error`: the image has a defect or is not a disk image. The message tells the problem, for example a sector chain that loops. Tell the user. Do not change the image.
 - `installation-incomplete`, or `machine-unavailable` with a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
 - `invalid-input`: an argument or a path is wrong. Read the message and correct the call.