@henols/c64-re-tools 2.0.0-rc.2 → 2.0.0-rc.21

package/skills/c64-testing/scripts/run.ts

@@ -0,0 +1,241 @@
+// The c64-testing run script (D45): runs steps in its own emulator, from a
+// program or a snapshot file, and writes what the steps ask for into a
+// directory: screens, coverage maps, snapshot files, and results.json with
+// the observations. One side, no comparison. Exit status: 0 when every step
+// ran, 1 when a step did not, 2 for a bad call.
+
+import { parseArgs } from "node:util";
+
+import { formatC64Address, formatSprite, formatVicii, parseC64Address } from "#src/c64.ts";
+import { runProgram } from "#src/host-client/autostart.ts";
+import { readCoverage } from "#src/host-client/coverage.ts";
+import { ACTION_STEP_KEYS, ACTION_STEP_KINDS, checkActionStep, isInteger, isObject, runActionStep, type ActionStep } from "#src/host-client/steps.ts";
+import { MAX_MEMORY_READ, MAX_TRACE_FRAMES, MAX_TRACE_HITS, MAX_TRACE_POINTS, TRACE_KINDS, WireFailure, type TraceHit, type TraceKind } from "#src/host-client/tools.ts";
+import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
+import { readMemoryInParts, ViceSessionClient } from "#src/host-client/vice-session.ts";
+import { resolveProjectPath } from "#src/project.ts";
+import { runScript, UsageError } from "#src/script.ts";
+import { loadSymbols } from "./lib/scenario.ts";
+
+const USAGE = `run.ts <run.json> --out <dir>
+
+<run.json> is a run file relative to the project folder: where to start,
+optional symbols, and the steps. See references/scenario-format.md, section
+Runs. The files that the steps write, and results.json, go into <dir>. The
+result is one JSON object.`;
+
+type RunStep =
+  | ActionStep
+  | { snapshot: string }
+  | { save: string }
+  | { screen: string }
+  | { coverage: string }
+  | { trace: string; points: Array<{ kind: TraceKind; at: string; end?: string }>; frames: number; maxHits?: number }
+  | { observe: string; memory?: "all" | Array<string | { at: string; size?: number; view?: "cpu" | "ram" }>; registers?: boolean; vicii?: boolean; sprites?: number[] };
+
+interface Run {
+  name: string;
+  videoStandard?: "pal" | "ntsc";
+  start: { program: string; load?: boolean } | { snapshot: string };
+  symbols?: string;
+  steps: RunStep[];
+}
+
+const OWN_KINDS = ["snapshot", "save", "screen", "coverage", "observe", "trace"] as const;
+const TRACE_KEYS = ["trace", "points", "frames", "maxHits"];
+const OBSERVE_KEYS = ["observe", "memory", "registers", "vicii", "sprites"];
+/** A name of a file that a step writes: letters, digits, dots, underscores or hyphens. */
+const NAME = /^[A-Za-z0-9._-]{1,64}$/;
+
+function readRun(path: string): Run {
+  let value: unknown;
+  try {
+    value = JSON.parse(readProjectFile(path).bytes.toString("utf8"));
+  } catch (error) {
+    if (error instanceof WireFailure) throw error;
+    throw new UsageError(`the run ${path} is not JSON: ${(error as Error).message}`);
+  }
+  const fail = (message: string): never => {
+    throw new UsageError(`run ${path}: ${message}`);
+  };
+  if (!isObject(value)) return fail("is not a JSON object");
+  if (typeof value.name !== "string" || value.name === "") fail("needs a name");
+  if (value.videoStandard !== undefined && value.videoStandard !== "pal" && value.videoStandard !== "ntsc") fail("videoStandard must be pal or ntsc");
+  const start = value.start;
+  if (!isObject(start) || (typeof start.program !== "string") === (typeof start.snapshot !== "string")) fail("start needs program or snapshot");
+  if (isObject(start) && start.load !== undefined && typeof start.load !== "boolean") fail("start.load must be true or false");
+  if (value.symbols !== undefined && typeof value.symbols !== "string") fail("symbols must be knowledge, none or a JSON file");
+  if (!Array.isArray(value.steps) || value.steps.length === 0) fail("needs steps");
+  const labels = new Set<string>();
+  (value.steps as unknown[]).forEach((step, index) => {
+    const at = `step ${index + 1}`;
+    if (!isObject(step)) return fail(`${at} must be an object`);
+    const kinds = "observe" in step ? ["observe"] : "trace" in step ? ["trace"] : Object.keys(step).filter((key) => (ACTION_STEP_KINDS as readonly string[]).includes(key) || (OWN_KINDS as readonly string[]).includes(key));
+    if (kinds.length !== 1) return fail(`${at} must have exactly one of ${[...ACTION_STEP_KINDS, ...OWN_KINDS].join(", ")}`);
+    const kind = kinds[0]!;
+    const allowed = kind === "observe" ? OBSERVE_KEYS : kind === "trace" ? TRACE_KEYS : (ACTION_STEP_KEYS[kind] ?? [kind]);
+    for (const key of Object.keys(step)) if (!allowed.includes(key)) fail(`${at} has the key ${key}, which a ${kind} step does not have`);
+    if ((ACTION_STEP_KINDS as readonly string[]).includes(kind)) return checkActionStep(kind, step, at, fail);
+    const name = step[kind];
+    if (kind === "snapshot") {
+      if (typeof name !== "string" || name === "") fail(`${at}: snapshot needs a project file`);
+      return;
+    }
+    if (typeof name !== "string" || !NAME.test(name)) fail(`${at}: ${kind} needs a name of 1 to 64 letters, digits, dots, underscores or hyphens`);
+    if (kind === "trace") {
+      if (labels.has(name as string)) fail(`${at} needs a new name`);
+      labels.add(name as string);
+      const points = step.points;
+      if (!Array.isArray(points) || points.length === 0 || points.length > MAX_TRACE_POINTS) return fail(`${at}: points is a list of 1 to ${MAX_TRACE_POINTS} objects with kind and at`);
+      for (const point of points as unknown[]) {
+        if (!isObject(point) || Object.keys(point).some((key) => !["kind", "at", "end"].includes(key))) return fail(`${at}: a point has kind, at and end, and nothing else`);
+        if (!(TRACE_KINDS as readonly unknown[]).includes(point.kind)) fail(`${at}: a point kind is exec, read or write`);
+        if (typeof point.at !== "string" || (point.end !== undefined && typeof point.end !== "string")) fail(`${at}: a point needs at, and end when it is a range, as names or $ addresses`);
+      }
+      if (!isInteger(step.frames, 1, MAX_TRACE_FRAMES)) fail(`${at}: frames must be a number from 1 to ${MAX_TRACE_FRAMES}`);
+      if (step.maxHits !== undefined && !isInteger(step.maxHits, 1, MAX_TRACE_HITS)) fail(`${at}: maxHits must be a number from 1 to ${MAX_TRACE_HITS}`);
+      return;
+    }
+    if (kind !== "observe") return;
+    if (labels.has(name as string)) fail(`${at} needs a new observation name`);
+    labels.add(name as string);
+    const memoryItem = (item: unknown) =>
+      typeof item === "string" ||
+      (isObject(item) &&
+        typeof item.at === "string" &&
+        Object.keys(item).every((key) => ["at", "size", "view"].includes(key)) &&
+        (item.size === undefined || isInteger(item.size, 1, 0x10000)) &&
+        (item.view === undefined || item.view === "cpu" || item.view === "ram"));
+    if (step.memory !== undefined && step.memory !== "all" && (!Array.isArray(step.memory) || !step.memory.every(memoryItem))) {
+      fail(`${at}: memory is "all", or a list of names, $ addresses, or objects with at, size (1 to 65536) and view (cpu or ram)`);
+    }
+    if (step.registers !== undefined && typeof step.registers !== "boolean") fail(`${at}: registers must be true or false`);
+    if (step.vicii !== undefined && typeof step.vicii !== "boolean") fail(`${at}: vicii must be true or false`);
+    if (step.sprites !== undefined && (!Array.isArray(step.sprites) || !step.sprites.every((sprite) => isInteger(sprite, 0, 7)))) fail(`${at}: sprites is a list of numbers from 0 to 7`);
+  });
+  return value as unknown as Run;
+}
+
+/** A trace hit with $ addresses, as a person reads it. */
+function showHit(hit: TraceHit) {
+  return { ...hit, pc: formatC64Address(hit.pc), ...(hit.address === undefined ? {} : { address: formatC64Address(hit.address) }) };
+}
+
+async function runFile(path: string, out: string): Promise<{ output: Record<string, unknown>; failed: boolean }> {
+  const run = readRun(path);
+  const symbols = loadSymbols({ program: "", symbols: run.symbols ?? "none" });
+  const at = (location: string): number => {
+    if (location.startsWith("$")) return parseC64Address(location);
+    const address = symbols.get(location);
+    if (address === undefined) throw new UsageError(`the symbols have no ${location}`);
+    return address;
+  };
+  const files: string[] = [];
+  const write = (name: string, bytes: Uint8Array) => {
+    writeProjectFile(`${out}/${name}`, bytes, { what: "--out" });
+    files.push(name);
+  };
+  const observations: Record<string, unknown> = {};
+  const traces: Record<string, unknown> = {};
+  const client = await ViceSessionClient.open({ videoStandard: run.videoStandard ?? "pal" });
+  let done = 0;
+  let reason: string | undefined;
+  try {
+    await client.reset({ mode: "hard", run: false });
+    if ("snapshot" in run.start) {
+      await client.snapshotRestore(readProjectFile(run.start.snapshot).bytes);
+    } else if (run.start.load === true) {
+      await client.execution({ action: "advance-frames", count: 150, space: "c64" });
+      await client.programLoad({ path: run.start.program });
+    } else {
+      const failed = await runProgram(client, run.start.program, readProjectFile(run.start.program).bytes);
+      if (failed !== undefined) reason = failed === "not-loaded" ? "The program was not in memory after autostart." : "The program did not start after RUN; it needs a BASIC start line.";
+    }
+    await client.memmap({ action: "clear" });
+    for (const step of reason === undefined ? run.steps : []) {
+      if ("snapshot" in step) {
+        await client.snapshotRestore(readProjectFile(step.snapshot).bytes);
+      } else if ("save" in step) {
+        await client.snapshot({ action: "save", name: "run-save" });
+        write(`${step.save}.vsf`, await client.snapshotExport("run-save"));
+        await client.snapshot({ action: "discard", name: "run-save" });
+      } else if ("screen" in step) {
+        write(`${step.screen}.png`, Buffer.from((await client.screenCapture()).png, "base64"));
+      } else if ("coverage" in step) {
+        write(`${step.coverage}.bin`, await readCoverage(client));
+        await client.memmap({ action: "clear" });
+      } else if ("trace" in step) {
+        // A trace (D76): every hit of the points while the program runs on, to <name>.json.
+        const points = step.points.map((point) => ({ kind: point.kind, start: at(point.at), end: at(point.end ?? point.at) }));
+        if (points.some((point) => point.end < point.start)) throw new UsageError(`the trace ${step.trace} has a point whose end is before its start`);
+        const traced = await client.trace({ points, frames: step.frames, maxHits: step.maxHits ?? MAX_TRACE_HITS });
+        write(`${step.trace}.json`, Buffer.from(`${JSON.stringify({ points: step.points, frames: traced.frames, end: traced.end, hits: traced.hits.map(showHit) }, null, 1)}\n`));
+        traces[step.trace] = { file: `${step.trace}.json`, hits: traced.hits.length, frames: traced.frames, end: traced.end };
+        if (traced.end !== "frames" && traced.end !== "hits") {
+          reason = `The trace ${step.trace} ended at a ${traced.end} at ${formatC64Address(traced.pc)}.`;
+          break;
+        }
+      } else if ("observe" in step) {
+        const seen: Record<string, unknown> = {};
+        if (step.memory === "all") {
+          // All 64 KiB of RAM, also under the ROMs and the I/O area, as one file (M23.9).
+          write(`${step.observe}.bin`, await readMemoryInParts(client, 0x0000, 0x10000, "ram"));
+          seen.memory = { file: `${step.observe}.bin` };
+        } else if (step.memory !== undefined) {
+          const memory: Record<string, string | { file: string }> = {};
+          for (const item of step.memory) {
+            const spec = typeof item === "string" ? { at: item } : item;
+            const size = spec.size ?? 1;
+            const bytes = await readMemoryInParts(client, at(spec.at), size, spec.view ?? "cpu");
+            // More than one read gives goes to a file: results.json stays small.
+            if (size <= MAX_MEMORY_READ) memory[spec.at] = bytes.toString("hex");
+            else {
+              const file = `${step.observe}-${spec.at.replace(/^\$/, "")}.bin`;
+              write(file, bytes);
+              memory[spec.at] = { file };
+            }
+          }
+          seen.memory = memory;
+        }
+        if (step.registers === true) {
+          const registers = await client.registersGet("c64");
+          seen.registers = { ...registers, pc: formatC64Address(registers.pc) };
+        }
+        if (step.vicii === true) seen.vicii = formatVicii(await client.vicii());
+        if (step.sprites !== undefined) seen.sprites = (await client.sprites(step.sprites)).sprites.map(formatSprite);
+        observations[step.observe] = seen;
+      } else {
+        const notReached = await runActionStep(client, step, at);
+        if (notReached !== undefined && "runUntil" in step) {
+          reason = `Step ${done + 1} did not reach its target in ${step.timeoutFrames} frames. It stopped by ${notReached.stopReason} at ${formatC64Address(notReached.pc)}.`;
+          break;
+        }
+      }
+      done++;
+    }
+    const pc = (await client.registersGet("c64")).pc;
+    const results = { name: run.name, completed: reason === undefined, steps: run.steps.length, done, ...(reason === undefined ? {} : { reason }), pc: formatC64Address(pc), files: [...files], observations, ...(Object.keys(traces).length === 0 ? {} : { traces }) };
+    write("results.json", Buffer.from(`${JSON.stringify(results, null, 2)}\n`));
+    return { output: { ...results, files, observations: Object.keys(observations), out }, failed: reason !== undefined };
+  } finally {
+    await client.close();
+  }
+}
+
+await runScript(
+  async (argv) => {
+    const { values, positionals } = parseArgs({ args: argv, strict: true, allowPositionals: true, options: { out: { type: "string" }, help: { type: "boolean" } } });
+    if (values.help) throw new UsageError("");
+    if (positionals.length !== 1) throw new UsageError("give one run file");
+    if (values.out === undefined) throw new UsageError("run needs --out <dir>");
+    try {
+      resolveProjectPath(values.out);
+    } catch {
+      throw new UsageError(`--out must be a path relative to the project folder that stays inside it, not ${values.out}`);
+    }
+    const { output, failed } = await runFile(positionals[0]!, values.out);
+    if (failed) process.exitCode = 1;
+    return output;
+  },
+  { usage: USAGE },
+);

package/skills/c64-testing/scripts/test.ts

@@ -6,22 +6,32 @@ import { parseArgs } from "node:util";
 
 import { ViceSessionClient } from "#src/host-client/vice-session.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
+import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
-import { readScenario, runScenario, ScenarioError, type ScenarioResult } from "./scenario.ts";
+import { readScenario, runScenario, ScenarioError, type ScenarioResult } from "./lib/scenario.ts";
 
-const USAGE = `test.ts <scenario.json>
+const USAGE = `test.ts <scenario.json> [--out <dir>]
 
-<scenario.json> is a scenario file relative to the project directory. See
-references/scenario-format.md. The result is one JSON object.`;
+<scenario.json> is a scenario file relative to the project folder. See
+references/scenario-format.md. With --out, a FAIL writes both screens, the
+difference image and memory.json with each differing byte into <dir>. The
+result is one JSON object.`;
 
 const EXIT = { PASS: 0, FAIL: 1, INCONCLUSIVE: 3 } as const;
 
 async function run(argv: string[]): Promise<ScenarioResult> {
-  const { values, positionals } = parseArgs({ args: argv, strict: true, allowPositionals: true, options: { help: { type: "boolean" } } });
+  const { values, positionals } = parseArgs({ args: argv, strict: true, allowPositionals: true, options: { out: { type: "string" }, help: { type: "boolean" } } });
   if (values.help) throw new UsageError("");
   if (positionals.length !== 1) throw new UsageError("give one scenario file");
+  if (values.out !== undefined) {
+    try {
+      resolveProjectPath(values.out);
+    } catch {
+      throw new UsageError(`--out must be a path relative to the project folder that stays inside it, not ${values.out}`);
+    }
+  }
   try {
-    return await runScenarioFile(positionals[0]!);
+    return await runScenarioFile(positionals[0]!, values.out);
   } catch (error) {
     // A scenario or symbol file that is not usable is a bad call.
     if (error instanceof ScenarioError) throw new UsageError(error.message);
@@ -29,7 +39,7 @@ async function run(argv: string[]): Promise<ScenarioResult> {
   }
 }
 
-async function runScenarioFile(path: string): Promise<ScenarioResult> {
+async function runScenarioFile(path: string, out: string | undefined): Promise<ScenarioResult> {
   const scenario = readScenario(path);
   let client: ViceSessionClient;
   try {
@@ -39,15 +49,15 @@ async function runScenarioFile(path: string): Promise<ScenarioResult> {
     return { result: "INCONCLUSIVE", scenario: scenario.name, reason: `no emulator: ${error.message}`, checkpoints: [], differences: [] };
   }
   try {
-    return await runScenario(client, scenario);
+    return await runScenario(client, scenario, out === undefined ? {} : { out });
   } finally {
     await client.close();
   }
 }
 
 await runScript(
-  async () => {
-    const result = await run(process.argv.slice(2));
+  async (argv) => {
+    const result = await run(argv);
     process.exitCode = EXIT[result.result];
     return result;
   },

package/skills/c64-unpacker/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: c64-unpacker
-description: Use this skill to find out if a packer or a cruncher compressed a C64 program, and to get the unpacked program for analysis. It shows evidence of packing without a guess of the packer name. It runs the program in an emulator until the unpacked code starts, then writes the memory into the project. Do not use it to analyze the unpacked code.
+description: Use this skill to find out if a packer or a cruncher compressed a C64 program, and to get the unpacked program for analysis. It shows evidence of packing without a guess of the packer name. It runs the program in an emulator until the unpacked code starts, then writes the memory into the project. It also captures each part of a multi-load program and the drive RAM. Do not use it to analyze the unpacked code.
 ---
 
 # c64-unpacker
@@ -13,46 +13,109 @@ This skill does not change project knowledge.
 
 ## Inputs
 
-- The program: a PRG file, relative to the project directory.
-- For a capture: the address where the unpacked program starts, and where to write the result.
+- The program: a PRG file, relative to the project folder.
+- For a capture: the address where the unpacked program starts, and the directory for the result.
 
 ## Tools / execution path
 
 ```
 node <skill>/scripts/unpack.ts inspect original/game.prg
 node <skill>/scripts/unpack.ts trace original/game.prg
-node <skill>/scripts/unpack.ts capture original/game.prg --until '$c000' --out unpacked/game.prg --range '$c000' '$cfff'
+node <skill>/scripts/unpack.ts capture original/game.prg --until '$c000' --out .c64-re-tools/local/capture
+node <skill>/scripts/unpack.ts stages original/game.prg --steps .c64-re-tools/local/input.json
+node <skill>/scripts/unpack.ts loads original/game.d64 --steps .c64-re-tools/local/parts.json --out .c64-re-tools/local/parts --drive
 ```
 
-`inspect` examines the file locally. `trace` and `capture` start their own emulator through the host runtime and start the program. `trace` runs the program and finds the memory that the program wrote and then executed. `capture` stops the program when the CPU gets to the `--until` address.
+`inspect` examines the file locally. `trace` and `capture` start their own emulator through the host runtime and start the program. `trace` runs the program and finds the memory that the program wrote and then executed. `capture` stops the program when the CPU gets to the `--until` address. `stages` runs the program and finds each stage: a decruncher, an intro, a copier, and then the program. For each stage it gives the entry, the frames, the written memory (`wrote`) and the entry of the next stage (`next`). In `stages` and `capture`, a `frames` step and a `runUntil` step with only `at` count as run time. `stages` refuses a `runUntil` step with `raster` or `memory`.
 
 | Option | Meaning |
 |---|---|
-| `--until '$c000'` | The address where the unpacked program starts. |
-| `--out unpacked/game.prg` | Where to write the result, relative to the project directory. |
+| `--until '$c000'` | The address where the unpacked program starts. The capture stops there after the steps. To capture a later arrival at the address, add a `runUntil` step to an address after the first arrival. |
+| `--out .c64-re-tools/local/capture` | Where to write the result, relative to the project folder. |
 | `--range '$c000' '$cfff'` | Write this range as a PRG. Without it, the script writes all 64 KiB of RAM as a flat file. |
+| `--exclude '$a000-$a9ff'` | `capture` only: remove this range from the segments. You can give it more than once. `image.json` lists the ranges in `excluded`. The entry must not be in the range. |
 | `--timeout-frames 3000` | How many frames the program can run before the capture stops (default 3000). |
 | `--frames 3000` | `trace` only: how many frames the program runs (default 3000). |
-| `--entry '$c000'` | `trace` only: start the program at this address. Without it, `trace` types RUN. A program without a BASIC start line needs it. |
+| `--entry '$c000'` | `trace`, `stages` and `capture`: start the program at this address. Without it, the script types RUN. A file that is not a BASIC program at `$0801` needs it. |
+| `--steps input.json` | Input for the program, right after it starts: a JSON list of steps. Use it when an intro waits for a key or a menu waits for a choice. The scripts start the program as a c64-testing scenario does. Thus the same steps in a scenario get the program to the entry at the same time. |
+| `--drive` | `loads` only: each capture also writes the 2 KiB RAM of the 1541 drive as `drive8.prg`. |
+| `--min-block 64` | `loads` only: the smallest block of changed memory that becomes a segment (default 64). The result counts smaller changes as `smallChanges`. |
+| `--min-stage 64` | `stages` and `capture`: the smallest block of written memory that starts a new stage when the CPU executes it (default 64). |
 
-The capture reads RAM, also the RAM under the ROMs and the I/O area. The script prints one JSON object.
+The capture reads RAM, also the RAM under the ROMs and the I/O area. The script prints one JSON object. The script refuses an option that the command does not use.
+
+A steps file has the steps `write`, `registers`, `joystick`, `type`, `frames` and `runUntil` of the c64-testing skill. Addresses are `$` and four hex digits. For example, wait 50 frames and press the space bar:
+
+```json
+[{ "frames": 50 }, { "type": " " }]
+```
+
+A `frames` step runs 1 to 30000 frames. A `runUntil` step has `timeoutFrames` from 1 to 30000.
+
+A `type` step puts keys in the keyboard queue of the KERNAL. A program that reads the keyboard hardware does not see them. A step cannot press one specific key of the keyboard matrix. A wait for any key that reads all keyboard columns can end without a key.
+
+### 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/`.
+- 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 `inspect`. Read `basicStart` and `packing`:
+1. Run `inspect`. Read `basicStart` and `packing`. `basicStart` gives the first SYS line and its address. When the SYS argument needs values at run time, `sys` is null and `expression` gives the argument. Then `trace`, `stages` and `capture` stop at the first instruction after the BASIC text:
    - `likely`: most of the bytes look compressed. Packed data has this property.
    - `unlikely`: the bytes look like code and data. A simple cruncher can also give this result.
-   - `unclear`: the file is short, or the blocks do not give clear evidence.
+   - `unclear`: the file is short, or the blocks do not give clear evidence. Or the code at the SYS address decodes or moves bytes outside the program.
+
+   Also read the evidence that the script finds in the file. The script never names a packer from it:
+   - `basicText`: raw evidence from the BASIC lines, not a listing. A byte that is not a printable character shows as `{$xx}`. A packer or a crack often puts its name there. For a listing, use the c64-basic skill.
+   - `strings`: readable text near the start of the code.
+   - `start`: the code at the SYS address. `jumpsOutside` and `writesOutside` give an address outside the loaded program, where the code jumps or writes.
+   - `decodeLoops`: EOR instructions in loops that store with an index. This is usually decryption or decoding.
 2. Run `trace`. It gives the evidence from the run. Read `packing`:
-   - `likely`: the program wrote code and then executed it. It unpacked, decrypted or moved code. `runningRange` is the code that runs now. Its `start` is usually the entry point of the unpacked program.
+   - `likely`: the program wrote code and then executed it. It unpacked, decrypted or moved code. `runningRange` is the written code that runs at the end of the trace. When the trace ends in ROM code, for example in an interrupt, it is the written code that runs next. Its `start` is code that runs after the unpacking. It is not always the entry point of the program. When no written code runs in 50 more frames, the result has no `runningRange` and no `suggestedUntil`.
    - `unclear`: the program executed a small quantity of code that it wrote. This can be code that changes itself.
    - `unlikely`: the program executed no code that it wrote. If the program waits for a key or a joystick, it can move code after that input. Then use the c64-emulator skill.
 3. Find the address where the unpacked program starts:
-   - Use `runningRange.start` from `trace`, or `suggestedUntil`. The CPU gets to `suggestedUntil` after the unpacking.
+   - Run `stages`. The `entry` of the last stage is usually the start of the program. A routine that a stage writes and calls is part of that stage when it returns to the stage.
+   - Or use `runningRange.start` from `trace`, or `suggestedUntil`. The CPU gets to `suggestedUntil` after the unpacking.
    - Or use the c64-emulator skill: set a breakpoint after the unpack loop, or look at the last JMP of the unpacker.
-4. Run `capture` with that address. Use `--range` for the area that holds the unpacked program, if you know it.
-5. Make sure that the result is the application: the code at the start address must not be the unpacker again.
-6. Give the result to the c64-static-analysis skill. For a flat 64 KiB file, use its `--flat64k` option.
+   - Disassemble the code at the address with the c64-emulator skill. Make sure that it is the start of the program. The start of a program often sets the stack pointer, the interrupts and the vectors.
+   - A program can be relocated and not packed. Then a short copier moves the code and jumps to it. The moved code is the last stage. Make sure that the `entry` of the last stage is not code that the program writes later. An example is a routine that the program makes at run time. Disassemble the entry to make sure.
+4. Run `capture` with that address and a directory in `--out`. Give the same `--steps` as before. The directory gets:
+   - `image.bin`: all 64 KiB of RAM at the entry.
+   - `image.json`: the entry, the segments, the vectors and the stages. A segment is a block that a stage wrote. A block is not a segment when it holds the entry of a later stage before the program, and no stage wrote over that entry. The block with the capture entry is always a segment. Segments do not overlap. `writtenBy` tells the last stage that wrote into the segment.
+   - One PRG for each segment.
+   - `entry_state.json`: the registers, `$00` and `$01`, pages 0 to 3, the VIC, SID and CIA registers, and the vectors. `cia` gives the CIA timer latches and interrupt masks. `differsFromReset` lists the bytes that are not as a clean C64 has them at READY. A rebuild must make these bytes the same, because the program can read them.
+5. Make sure that the result is the application: the code at the entry must not be the unpacker again. A segment can be data that a loader left, for example intro graphics. Keep it until other evidence shows that the program does not use it. Then capture again with `--exclude` for that range. Thus the source and the loader do not include the range.
+6. Put the capture into the knowledge with `image <out>/image.json` of the c64-knowledge skill. The knowledge keeps the segments, the entry, the entry state and the stages. The other skills read them there. The files in `<out>` are not necessary after that.
+7. Use `--range` only when you know the area of the program. Then the capture writes that one segment.
+
+## Multi-load programs
+
+A multi-load program loads more parts from the disk while it runs, for example one part for each level. Use `loads` to capture each part. The program can be a PRG, or a disk, tape or cartridge image that VICE starts.
+
+1. Write a steps file. Put a `capture` step after each point where a part is in memory, for example:
+
+```json
+[
+  { "runUntil": { "at": "$080d" }, "timeoutFrames": 6000 },
+  { "capture": "main" },
+  { "type": " " },
+  { "runUntil": { "at": "$c000" }, "timeoutFrames": 6000 },
+  { "capture": "level1" }
+]
+```
+
+2. Run `loads` with the steps file and a directory in `--out`. Add `--drive` when the program has its own drive code, for example a fast loader.
+3. Each capture writes `<out>/<name>/` with `image.bin`, `image.json`, `entry_state.json` and a PRG for each segment. A segment is a block of RAM from `$0400` that the program changed after the capture before. The first capture also has the program itself.
+4. Put the part that you work on into the knowledge with `image <out>/<name>/image.json` of the c64-knowledge skill.
+5. With `--drive`, `drive8.prg` is the drive RAM at `$0000`-`$07ff`. Put it into the knowledge with `image <out>/<name>/drive8.prg --space drive8`. Then analyze it with c64-static-analysis and `--space drive8`.
+
+VICE records no memory access map for the drive CPU. Thus no tool gives coverage of drive code.
 
 ## Knowledge
 
@@ -63,18 +126,22 @@ Do not record the unpacker in the project knowledge, unless the user asks to exa
 
 ## Result
 
-The packing evidence, or the unpacked program in the project with the address where it starts.
+The packing evidence, the stages, or the unpacked program with its image, segments and entry state in a directory of the project.
+
+For `loads`: `captures`, with the name, the PC, the segments and the drive file of each capture. `keyWait: true` tells that the CPU was in the KERNAL wait for a key.
 
-The exit status is 0 for a result. The exit status is 1 for `traced: false`, for `captured: false` and for an error. The exit status is 2 for a wrong argument.
+The exit status is 0 for a result. The exit status is 1 for `traced: false`, for `captured: false`, for `loaded: false` and for an error. The exit status is 2 for a wrong argument.
 
 ## Failure and conflicts
 
 - `traced: false`: the emulator did not load the program into memory in the time limit. The reason gives the load address. Make sure that the file is a PRG that the C64 can load.
-- `captured: false`: the program did not get to the address in the time limit. The reason tells where it stopped. Find a better address with the c64-emulator skill, or give more frames.
+- `captured: false`: the program did not get to the address in the time limit. The reason tells where it stopped. Find a better address with the c64-emulator skill, or give more frames. If it stopped in a key wait, give `--steps` with a key.
+- A step did not reach its target: the reason names the step. Change the step or give it more frames.
+- `loaded: false` and no capture has a segment: the program did not load a part, or it did not start. `keyWait: true` on a capture tells that the C64 waited at READY. or at an INPUT statement. For a tape image, read `emulatorFlaw`. A known VICE flaw can stop a tape load. Tell the user to install the latest VICE.
 - Do not name a packer from weak evidence. The script never names one.
-- Some programs unpack in more than one stage. Make sure that the captured code is the application and not a second unpacker.
+- Some programs unpack in more than one stage. Run `stages` to find each stage. Capture at the entry of the last stage. Make sure that it is the application and not a second unpacker.
 - `not-found` or `invalid-input`: a path or an argument is wrong. Read the message.
-- `operation-failed` with a message about the host runtime: the host runtime does not run. Tell the user to start the host runtime with `npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host`.
+- `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.
 
 ## Handoffs