@henols/c64-re-tools 2.0.0-rc.18 → 2.0.0-rc.19

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

@@ -4,6 +4,7 @@
 
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import type { DatabaseSync } from "node:sqlite";
 import { parseArgs } from "node:util";
 
@@ -13,7 +14,6 @@ import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts"
 import { CONFLICT_RULES, conflicts, type Conflict } from "#src/knowledge/conflicts.ts";
 import { joinBatches, type Batch, type JoinChoice, type JoinClash } from "#src/knowledge/join.ts";
 import { KnowledgeError, openForRead, withWrite } from "#src/knowledge/database.ts";
-import { readCoverageFiles } from "#src/host-client/coverage.ts";
 import { operandText } from "#src/knowledge/expression.ts";
 import { historyAt, historyNamed, historyOfMacro, revision, revisionNote, revisions, type HistoryEntry } from "#src/knowledge/history.ts";
 import {
@@ -98,6 +98,9 @@ import {
   type WriteContext,
 } from "#src/knowledge/write.ts";
 import { platformNames } from "#src/platform.ts";
+import { addCoverage, coverageRuns, programCoverage, programImage, requireProgram, setImage, type ImageRequest } from "#src/knowledge/program.ts";
+import { WireFailure } from "#src/host-client/tools.ts";
+import { isInside, LOCAL_DIRECTORY, PROJECT_DIRECTORY, projectRoot, resolveProjectPath } from "#src/project.ts";
 import { listing, listingText, type ListingSource } from "./lib/listing.ts";
 import { runScript, UsageError } from "#src/script.ts";
 
@@ -120,15 +123,19 @@ Read (no database needed):
   macros [--origin O]                 the macros of the generated source
   uses [--start A --end A --macro M --origin O]   instructions written as a macro
   spaces                              the address spaces that hold knowledge
+  program                             the program in the knowledge (D83): its
+                                      segments and entry, and the coverage maps
+                                      that coverage imported, with the ranges
   history <address> | history --name <name> | history --macro <name>
   revisions [--limit N --before R]
   revision <revision>
   export --out <file> [--start A --end A --origin O]   all current knowledge to a project file
-  listing <start> <end> --image <file> [--coverage <file>]... [--out <file>]
-                                      the image as ACME lines with names, operand
+  listing <start> <end> [--out <file>]
+                                      the program as ACME lines with names, operand
                                       expressions, comments, the access of each line
-                                      (x executed, r read, w written) and the
-                                      references in and out; --out writes it as text
+                                      in the coverage (x executed, r read, w written)
+                                      and the references in and out; --out writes it
+                                      as text
 
 Every command takes --space S: c64 (the default), drive8 for code in the 1541
 drive, or bank0 to bank255 for cartridge banks. A write in a batch can name its
@@ -148,15 +155,15 @@ Write (one revision each; creates .c64-re-tools/knowledge/ when needed):
   unreference <from> <to> <kind>
   module <start> <file.asm> [--title T]   a file of generated source starts here
   unmodule <start>
-  operand <address> --lo|--hi|--value <symbol> [--offset N] --image <file>
-  operand <address> --expr <text> --image <file>
+  operand <address> --lo|--hi|--value <symbol> [--offset N]
+  operand <address> --expr <text>
                            write the operand of the instruction at <address> as
                            an expression: the low or high byte of symbol + N, the
                            value symbol + N, or ACME expression text; refused when
-                           it does not give the operand in the image (image.json
-                           or PRG); give a negative offset as --offset=-1
+                           it does not give the operand in the program of the
+                           knowledge; give a negative offset as --offset=-1
   unoperand <address>
-  patch <start> <end> <SWITCH> --code <text>|--code-file <file>|--nop [--comment T] --image <file>
+  patch <start> <end> <SWITCH> --code <text>|--code-file <file>|--nop [--comment T]
                            ACME code that replaces <start>-<end> when the build
                            defines SWITCH as 1 (c64-assembler --define SWITCH=1);
                            NOP fills the rest of the range; --nop puts only NOP
@@ -164,10 +171,17 @@ Write (one revision each; creates .c64-re-tools/knowledge/ when needed):
   macro <name> [--params a,b] --body <text>|--body-file <file> [--comment T]
                            an ACME macro; the body names a param with a dot: .a
   unmacro <name>
-  use <start> <end> <macro> [--args "x, y"] --image <file>
+  use <start> <end> <macro> [--args "x, y"]
                            write the instructions <start>-<end> as one use of
                            the macro, with one expression for each param
   unuse <start>
+  image <image.json|prg>   put the program into the knowledge (D83): its bytes, and
+                           for an image.json of c64-unpacker capture also the
+                           entry, the entry state and the stages; with --space for
+                           drive code or a cartridge bank. Only changed bytes write
+  coverage <map.bin>...    join coverage maps of c64_memmap or a run into the
+                           coverage of the knowledge (D83); each map is evidence
+                           of the revision, named by its path
   revert <revision>
   merge                    decide the conflicts that a git merge of two
                            computers' work left: of the rows of one conflict,
@@ -180,12 +194,14 @@ Write (one revision each; creates .c64-re-tools/knowledge/ when needed):
                            operand and module win, and its regions come last
   apply <file>             many writes from a JSON file ('-' reads standard input),
                            all as one revision, or none when one is refused;
-                           operand, patch and use writes need --image <file>
+                           operand, patch and use writes are checked against the
+                           program of --space in the knowledge
 
 Write options:
   --reason <text>          why, kept with the revision
-  --evidence <kind:ref>    what the change rests on: coverage:<file>, test:<file>,
-                           file:<file> or note:<text> (repeatable)
+  --evidence <kind:ref>    what the change rests on: coverage:<map> (a map that
+                           coverage imported), test:<file>, file:<file> or
+                           note:<text> (repeatable)
   --expect-revision <R>    refuse the write if knowledge changed after revision R
   --origin user|llm        who decided (default llm)
 
@@ -364,7 +380,6 @@ function run(argv: string[]): unknown {
       value: { type: "string" },
       expr: { type: "string" },
       offset: { type: "string" },
-      image: { type: "string" },
       code: { type: "string" },
       "code-file": { type: "string" },
       nop: { type: "boolean" },
@@ -376,7 +391,6 @@ function run(argv: string[]): unknown {
       switch: { type: "string" },
       macro: { type: "string" },
       analyzer: { type: "boolean" },
-      coverage: { type: "string", multiple: true },
       help: { type: "boolean" },
     },
   });
@@ -387,8 +401,8 @@ function run(argv: string[]): unknown {
   nameSpace = space;
   const range = { start: values.start === undefined ? 0x0000 : address(values.start, "--start"), end: values.end === undefined ? 0xffff : address(values.end, "--end") };
 
-  const read = new Set(["at", "search", "symbols", "regions", "comments", "references", "suppressions", "modules", "operands", "patches", "switches", "macros", "uses", "spaces", "history", "revisions", "revision", "export", "listing"]);
-  const write = new Set(["rename", "remove-symbol", "classify", "unclassify", "comment", "uncomment", "reference", "unreference", "module", "unmodule", "operand", "unoperand", "patch", "unpatch", "macro", "unmacro", "use", "unuse", "revert", "apply", "merge"]);
+  const read = new Set(["at", "search", "symbols", "regions", "comments", "references", "suppressions", "modules", "operands", "patches", "switches", "macros", "uses", "spaces", "program", "history", "revisions", "revision", "export", "listing"]);
+  const write = new Set(["rename", "remove-symbol", "classify", "unclassify", "comment", "uncomment", "reference", "unreference", "module", "unmodule", "operand", "unoperand", "patch", "unpatch", "macro", "unmacro", "use", "unuse", "revert", "apply", "merge", "image", "coverage"]);
   // join reads batch files and writes one: no knowledge opens (D79).
   if (command === "join") return joinCommand(args, values.out, space);
   // Refuse a mistyped command before anything opens, so no database appears by accident.
@@ -417,7 +431,6 @@ function run(argv: string[]): unknown {
     if (values[option] !== undefined && command !== "operand") throw new UsageError(`--${option} works only with operand`);
   }
   const only: Array<[keyof typeof values, readonly string[]]> = [
-    ["image", ["operand", "patch", "use", "apply"]],
     ["code", ["patch"]],
     ["code-file", ["patch"]],
     ["nop", ["patch"]],
@@ -431,8 +444,10 @@ function run(argv: string[]): unknown {
     if (values[option] !== undefined && !commands.includes(command)) throw new UsageError(`--${option} works only with ${commands.join(", ")}`);
   }
   const operation =
-    command === "apply"
-      ? applyOperation(args, context, space, values.image)
+    command === "image" || command === "coverage"
+      ? programOperation(command, args, context, space)
+      : command === "apply"
+      ? applyOperation(args, context, space)
       : command === "operand"
         ? operandOperation(args, values, context, space)
         : command === "patch" || command === "macro" || command === "use"
@@ -443,8 +458,6 @@ function run(argv: string[]): unknown {
 
 type ReadValues = {
   analyzer?: boolean | undefined;
-  image?: string | undefined;
-  coverage?: string[] | undefined;
   kind?: string | undefined;
   type?: string | undefined;
   name?: string | undefined;
@@ -455,19 +468,10 @@ type ReadValues = {
   macro?: string | undefined;
 };
 
-/** The lookups of a listing (D78): the image, the knowledge of the space and the platform names of the C64. */
-function listingSource(db: DatabaseSync | undefined, imagePath: string | undefined, coveragePaths: string[], space: string): ListingSource {
-  if (imagePath === undefined) throw new UsageError("listing reads the bytes from the image: give --image <image.json|prg>");
-  let image: ReturnType<typeof readImage>;
-  try {
-    image = readImage(imagePath);
-  } catch (error) {
-    if (error instanceof ImageError) throw new UsageError(error.message);
-    throw error;
-  }
-  const coverage = readCoverageFiles(coveragePaths, (message) => {
-    throw new UsageError(message);
-  });
+/** The lookups of a listing (D78): the program and the coverage in the knowledge (D83), the knowledge of the space and the platform names of the C64. */
+function listingSource(db: DatabaseSync | undefined, space: string): ListingSource {
+  const image = requireProgram(db, space);
+  const coverage = programCoverage(db, space)?.map;
   const inside = (at: number) => image.segments.some((segment) => at >= segment.start && at <= segment.end);
   const platform = new Map(space === DEFAULT_SPACE ? platformNames().map((entry) => [entry.address, entry.name]) : []);
   return {
@@ -501,7 +505,7 @@ function readAnswer(db: DatabaseSync | undefined, command: string, args: string[
       const start = address(args[0], "start");
       const end = address(args[1], "end");
       if (end < start) throw new UsageError("the end must not be before the start");
-      const source = listingSource(db, values.image, values.coverage ?? [], space);
+      const source = listingSource(db, space);
       const lines = listing(source, start, end);
       if (values.out !== undefined) {
         writeProjectFile(values.out, Buffer.from(listingText(lines), "utf8"), { what: "--out" });
@@ -543,6 +547,24 @@ function readAnswer(db: DatabaseSync | undefined, command: string, args: string[
       return { comments: listComments(db, range, origins, space).map(comment) };
     case "references":
       return { references: listReferences(db, range, values.kind === undefined ? undefined : oneOf(REFERENCE_KINDS, values.kind, "--kind"), origins, space).map(reference) };
+    case "program": {
+      const image = programImage(db, space);
+      const ranges = db === undefined ? [] : (db.prepare("SELECT kind, count(*) AS count FROM current_coverage WHERE space = ? GROUP BY kind ORDER BY kind").all(space) as Array<{ kind: string; count: number }>);
+      return {
+        ...(space === DEFAULT_SPACE ? {} : { space }),
+        image:
+          image === undefined
+            ? null
+            : {
+                segments: image.segments.map((segment) => ({ start: formatC64Address(segment.start), end: formatC64Address(segment.end) })),
+                bytes: image.segments.reduce((sum, segment) => sum + segment.end - segment.start + 1, 0),
+                ...(image.entry === undefined ? {} : { entry: formatC64Address(image.entry) }),
+                state: image.state !== undefined,
+                stages: image.stages?.length ?? 0,
+              },
+        coverage: { maps: coverageRuns(db).map((run) => run.name), ranges: Object.fromEntries(ranges.map((row) => [row.kind, row.count])) },
+      };
+    }
     case "export": {
       const exported = {
         revision: currentRevision(db),
@@ -622,23 +644,37 @@ function originFilter(value: string): Origin[] {
   return [...origins];
 }
 
-/** --evidence kind:ref. A file kind names a project file and keeps its SHA-256, so a later change of the file shows. */
+/**
+ * --evidence kind:ref. A file kind names a project file and keeps its SHA-256, so a later change of the file shows.
+ * A file in .c64-re-tools/local/ is refused (D82): git ignores it, and the move that keeps it changes the path.
+ */
 function evidenceOf(value: string): Evidence {
   const colon = value.indexOf(":");
   const kind = oneOf(EVIDENCE_KINDS, colon < 0 ? value : value.slice(0, colon), "--evidence kind");
   const ref = colon < 0 ? "" : value.slice(colon + 1);
   if (ref === "") throw new UsageError(`--evidence needs ${kind}:<${kind === "note" ? "text" : "file"}>`);
   if (kind === "note") return { kind, ref };
-  return { kind, ref, sha256: createHash("sha256").update(readProjectFile(ref).bytes).digest("hex") };
+  // A coverage map is evidence by the name that coverage imported it with (D83).
+  if (kind === "coverage") {
+    const db = openForRead();
+    try {
+      const run = coverageRuns(db).find((item) => item.name === ref);
+      if (run === undefined) throw new UsageError(`--evidence coverage:${ref} names no coverage map of the knowledge: import the map with coverage first`);
+      return { kind, ref, sha256: run.sha256 };
+    } finally {
+      db?.close();
+    }
+  }
+  const bytes = readProjectFile(ref).bytes;
+  const root = projectRoot();
+  if (isInside(join(root, PROJECT_DIRECTORY, LOCAL_DIRECTORY), resolveProjectPath(ref, root))) {
+    throw new UsageError(`--evidence ${kind}:${ref} is in ${PROJECT_DIRECTORY}/${LOCAL_DIRECTORY}/, which git ignores: move it to a folder that git keeps (a run folder to runs/<name>/) and give the new path`);
+  }
+  return { kind, ref, sha256: createHash("sha256").update(bytes).digest("hex") };
 }
 
-/**
- * The image that operand, patch and macro use writes are checked against (D65,
- * D72, D73), with the platform names. A byte outside the segments of the image
- * is not in the image.
- */
-function operandImage(path: string | undefined, what: string): OperandImage {
-  if (path === undefined) throw new UsageError(`${what} checks the write against the image: give --image <image.json|prg>`);
+/** An image.json of c64-unpacker capture or a PRG as a write of the program (D83). */
+function imageRequest(path: string, space: string): ImageRequest {
   let image: ReturnType<typeof readImage>;
   try {
     image = readImage(path);
@@ -646,6 +682,57 @@ function operandImage(path: string | undefined, what: string): OperandImage {
     if (error instanceof ImageError) throw new UsageError(error.message);
     throw error;
   }
+  const request: ImageRequest = { space, segments: image.segments, byteAt: image.byteAt };
+  if (image.entry !== undefined) request.entry = image.entry;
+  if (image.stages !== undefined) request.stages = image.stages;
+  if (image.statePath !== undefined) {
+    let bytes: Buffer | undefined;
+    try {
+      bytes = readProjectFile(image.statePath).bytes;
+    } catch (error) {
+      if (!(error instanceof WireFailure && error.code === "not-found")) throw error;
+    }
+    if (bytes !== undefined) {
+      let state: unknown;
+      try {
+        state = JSON.parse(bytes.toString("utf8"));
+      } catch (error) {
+        throw new UsageError(`${image.statePath} is not JSON: ${(error as Error).message}`);
+      }
+      if (typeof state !== "object" || state === null || Array.isArray(state)) throw new UsageError(`${image.statePath} is not an entry state of c64-unpacker capture`);
+      // The comparison with a clean reset only tells the capture what it found.
+      const { differsFromReset: _differs, ...kept } = state as Record<string, unknown>;
+      request.state = kept;
+    }
+  }
+  return request;
+}
+
+/** image and coverage (D83): the program and what the runs did go into the knowledge, so no project file is made again. */
+function programOperation(command: "image" | "coverage", args: string[], context: WriteContext, space: string): WriteOperation {
+  if (command === "image") {
+    if (args.length !== 1) throw new UsageError("image needs one image.json or PRG");
+    const request = imageRequest(args[0]!, space);
+    return (db) => {
+      const { revision, current } = setImage(db, context, request);
+      return { revision, ...spaceOf(current), bytes: current.bytes, rowsAdded: current.rowsAdded, rowsClosed: current.rowsClosed, entryChanged: current.entry };
+    };
+  }
+  if (args.length === 0) throw new UsageError("coverage needs one or more coverage maps");
+  const maps = args.map((path) => ({ name: path, bytes: readProjectFile(path).bytes }));
+  return (db) => {
+    const { revision, current } = addCoverage(db, context, { space, maps });
+    return { revision, ...spaceOf(current), imported: current.imported, known: current.known, ranges: current.ranges };
+  };
+}
+
+/**
+ * The program in the knowledge (D83) that operand, patch and macro use writes
+ * are checked against (D65, D72, D73), with the platform names. A byte outside
+ * the segments of the program is not in it.
+ */
+function operandImage(db: DatabaseSync, space: string): OperandImage {
+  const image = requireProgram(db, space);
   const inside = (at: number) => image.segments.some((segment) => at >= segment.start && at <= segment.end);
   return { byteAt: (at) => (inside(at) ? image.byteAt(at) : undefined), platform: new Map(platformNames().map((entry) => [entry.name, entry.address])) };
 }
@@ -672,9 +759,8 @@ function operandOperation(args: string[], values: Record<string, unknown>, conte
     request.symbol = values[select] as string;
     if (values.offset !== undefined) request.offset = offsetOf(values.offset, "--offset");
   }
-  const image = operandImage(values.image as string | undefined, "operand");
   return (db) => {
-    const result = setOperand(db, { ...context, image }, request);
+    const result = setOperand(db, { ...context, image: operandImage(db, space) }, request);
     return { revision: result.revision, operand: operand(result.current), ...(result.previous === undefined ? {} : { previous: operand(result.previous) }) };
   };
 }
@@ -702,9 +788,8 @@ function sourceOperation(command: "patch" | "macro" | "use", args: string[], val
       const code = textOrFile(values, "code", "--code");
       if ((code === undefined) === (values.nop !== true)) throw new UsageError("patch needs exactly one of --code, --code-file or --nop");
       const request = { space, start: address(args[0], "start"), end: address(args[1], "end"), switch: args[2], code: code ?? "", ...(comment === undefined ? {} : { comment }) };
-      const image = operandImage(values.image as string | undefined, "patch");
       return (db) => {
-        const result = setPatch(db, { ...context, image }, request);
+        const result = setPatch(db, { ...context, image: operandImage(db, space) }, request);
         return { revision: result.revision, patch: patch(result.current), ...(result.previous === undefined ? {} : { previous: patch(result.previous) }) };
       };
     }
@@ -721,9 +806,8 @@ function sourceOperation(command: "patch" | "macro" | "use", args: string[], val
     case "use": {
       if (args[2] === undefined) throw new UsageError("the macro name is missing");
       const request = { space, start: address(args[0], "start"), end: address(args[1], "end"), macro: args[2], args: commaList((values.args as string | undefined) ?? "") };
-      const image = operandImage(values.image as string | undefined, "use");
       return (db) => {
-        const result = setMacroUse(db, { ...context, image }, request);
+        const result = setMacroUse(db, { ...context, image: operandImage(db, space) }, request);
         return { revision: result.revision, use: macroUse(result.current), ...(result.previous === undefined ? {} : { previous: macroUse(result.previous) }) };
       };
     }
@@ -731,7 +815,7 @@ function sourceOperation(command: "patch" | "macro" | "use", args: string[], val
 }
 
 /** apply <file>: the batch as BatchOperation values, checked before the database opens. */
-function applyOperation(args: string[], context: WriteContext, space: string, imagePath: string | undefined): WriteOperation {
+function applyOperation(args: string[], context: WriteContext, space: string): WriteOperation {
   if (args.length !== 1) throw new UsageError("apply needs one file, or - for standard input");
   const text = args[0] === "-" ? readFileSync(0, "utf8") : readProjectFile(args[0]!).bytes.toString("utf8");
   let parsed: unknown;
@@ -743,9 +827,8 @@ function applyOperation(args: string[], context: WriteContext, space: string, im
   if (!Array.isArray(parsed)) throw new UsageError("the batch is a JSON list of writes, for example [{\"op\": \"rename\", \"address\": \"$2100\", \"name\": \"update_player\"}]");
   const operations = parsed.map((item, index) => batchOperation(item, `write ${index + 1}`, space));
   const checked = operations.some((operation) => operation.op === "operand" || operation.op === "patch" || operation.op === "use");
-  const withImage = checked ? { ...context, image: operandImage(imagePath, "apply with operand, patch or use writes") } : context;
   return (db) => {
-    const applied = applyBatch(db, withImage, operations);
+    const applied = applyBatch(db, checked ? { ...context, image: operandImage(db, space) } : context, operations);
     // replaced: each write that replaced a row of another origin, with that row as previous gives it for one write (b2/07).
     const replaced = applied.steps.flatMap((step, index) =>
       step.previous === undefined

package/skills/c64-memory-map/SKILL.md

@@ -42,8 +42,9 @@ The script prints one JSON object.
 
 - 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.
-- Keep the results, batches and step files that you use only one time in `.c64-re-tools/local/` of the project. Git ignores that folder.
-- Put a run file whose results are the evidence for a finding in `runs/`, with its results. Then git keeps the run file and the results, and another person can do the run again.
+- 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

package/skills/c64-provenance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: c64-provenance
-description: Use this skill to compare two or more releases of a C64 program, for example cracked versions from different groups. It finds the bytes where the releases differ and shows which releases agree there. It can run each release and tell how the program uses each difference. With one release, it gives evidence for each range: the unpack stage, the access, and the code that the entry does not reach. Use the result to separate the content of the application from changes that a release added. It also keeps a library of routines that several programs share. It finds them in a program and writes their names as a batch for c64-knowledge. Do not use it to analyze the code.
+description: Use this skill to compare two or more releases of a C64 program, for example cracked versions from different groups. It finds the bytes where the releases differ and shows which releases agree there. It can run each release and tell how the program uses each difference. It also gives evidence for each range of the program in the knowledge. The evidence is the unpack stage, the access, and the code that the entry does not reach. Use the result to separate the content of the application from changes that a release added. It also keeps a library of routines that several programs share. It finds them in the program of the knowledge and writes their names as a batch for c64-knowledge. Do not use it to analyze the code.
 ---
 
 # c64-provenance
@@ -19,8 +19,8 @@ This skill does not change project knowledge.
 - Optional: an address range to compare.
 - Optional: a shift for a release that loads at a different address.
 - Optional: a number of frames to run each release, and a steps file.
-- For one release: the release, coverage files, and the knowledge of the project.
-- For the library: the image of a program, the knowledge of its project, and the library folder.
+- For one release: the program, the coverage and the other knowledge of the project. Put the program and the coverage in with `image` and `coverage` of the c64-knowledge skill.
+- For the library: the program and the other knowledge of its project, and the library folder.
 
 ## Tools / execution path
 
@@ -29,8 +29,8 @@ The script compares the files locally. Only `--run` uses the host runtime: each
 ```
 node <skill>/scripts/provenance.ts releases/a.prg releases/b.prg releases/c.prg
 node <skill>/scripts/provenance.ts releases/a.prg releases/b.prg --shift 2:-256 --from '$0900' --to '$09ff'
-node <skill>/scripts/provenance.ts releases/a.prg unpacked/b/image.json --run 600 --steps steps/start-game.json
-node <skill>/scripts/provenance.ts separate unpacked/image.json --coverage coverage/attract.bin --coverage coverage/level1.bin --out notes/separate.json
+node <skill>/scripts/provenance.ts releases/a.prg .c64-re-tools/local/b/image.json --run 600 --steps .c64-re-tools/local/start-game.json
+node <skill>/scripts/provenance.ts separate --out .c64-re-tools/local/separate.json
 ```
 
 | Option | Meaning |
@@ -51,8 +51,9 @@ With `--run`, a PRG starts with autostart and RUN. An image starts from its byte
 
 - 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.
-- Keep the results, batches and step files that you use only one time in `.c64-re-tools/local/` of the project. Git ignores that folder.
-- Put a run file whose results are the evidence for a finding in `runs/`, with its results. Then git keeps the run file and the results, and another person can do the run again.
+- 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
@@ -76,15 +77,15 @@ With `--run`, a PRG starts with autostart and RUN. An image starts from its byte
 
 ## One release
 
-Use `separate` when you have only one release. It gives evidence, not a decision:
+Use `separate` when you have only one release. It reads the program, its stages and the coverage from the knowledge. It gives evidence, not a decision:
 
-- `ranges`: the image in ranges with the same stage and access. `stage` is the last unpack stage that wrote the range. In `image.json`, the last stage is the program. An earlier stage is a depacker, an intro or a loader. Only an image from c64-unpacker `capture` has stages. For an image from `loads`, `noStages` tells this.
-- `access`: from the joined `--coverage` files: `executed`, `read`, `written`, `read-written` or `untouched`. `untouched` bytes did not take part in the runs. A `read` byte right after executed code, or at a return address, can be a dummy read of the 6502 that the program does not use.
+- `ranges`: the program in ranges with the same stage and access. `stage` is the last unpack stage that wrote the range. The last stage is the program. An earlier stage is a depacker, an intro or a loader. Only a capture of c64-unpacker `capture` has stages. For a program from `loads` or a PRG, `noStages` tells this.
+- `access`: from the coverage of the knowledge: `executed`, `read`, `written`, `read-written` or `untouched`. `untouched` bytes did not take part in the runs. A `read` byte right after executed code, or at a return address, can be a dummy read of the 6502 that the program does not use.
 - `codeRegions.total`: the number of code regions in the knowledge.
 - `codeRegions.unreachable`: code regions of the knowledge that no chain of call and jump references reaches from the entry. Run c64-static-analysis first, so that the knowledge has the code regions and the references.
-- `outside`: RAM outside the image that the program `read` or `executed` but did not write, and code it `generated`. A loader or an earlier stage put the bytes that the program did not write. A `generated` range can have gaps of two bytes or less: these are operand bytes.
+- `outside`: RAM outside the program that the program `read` or `executed` but did not write, and code it `generated`. A loader or an earlier stage put the bytes that the program did not write. A `generated` range can have gaps of two bytes or less: these are operand bytes.
 
-Each list has `count` and `listed`. `listed` has the first ranges, at most `--max-listed`. `--out` writes all of them. Run more coverage runs for parts that are `untouched` before you decide.
+Each list has `count` and `listed`. `listed` has the first ranges, at most `--max-listed`. `--out` writes all of them. Run more coverage runs for parts that are `untouched`, and add them with `coverage` of the c64-knowledge skill, before you decide.
 
 ## Library of routines
 
@@ -93,14 +94,14 @@ A library is a folder of routine files. Each file holds one routine: its bytes a
 `--library` is relative to the working directory, as `--project`. All other paths are relative to the project folder.
 
 ```
-node <skill>/scripts/provenance.ts routine unpacked/image.json --module '$1000' --library library --project game-a
-node <skill>/scripts/provenance.ts routine game.prg --start '$1000' --end '$1026' --name play --library library --project game-a
-node <skill>/scripts/provenance.ts match unpacked/image.json --library library --out .c64-re-tools/local/match.json --project game-b
+node <skill>/scripts/provenance.ts routine --module '$1000' --library library --project game-a
+node <skill>/scripts/provenance.ts routine --start '$1000' --end '$1026' --name play --library library --project game-a
+node <skill>/scripts/provenance.ts match --library library --out .c64-re-tools/local/match.json --project game-b
 ```
 
 To save a routine:
 
-1. Name the routine in the knowledge of its program first. The file keeps the user and LLM names, comments, regions, references and operand expressions in the range. It also keeps the code regions of each origin.
+1. Put the program into the knowledge, and name the routine there first. The file keeps the user and LLM names, comments, regions, references and operand expressions in the range. It also keeps the code regions of each origin.
 2. Run `routine` with the start of a module (`--module`), or with `--start` and `--end`. A module ends at the next module or at the end of its segment.
    - `--name` is the name of the routine and of its file. When you do not give it, the script uses the user or LLM name at the start.
    - `--title` is the title of the routine. When you do not give it, the script uses the module title.
@@ -109,7 +110,7 @@ To save a routine:
 
 To find the routines in a program:
 
-1. Run `match` on the image of the program. The script examines each routine of the library at each address of the image.
+1. Put the program into the knowledge. Then run `match`. The script examines each routine of the library at each address of the program.
    - The opcodes and the other bytes must be equal.
    - An address into the routine must point into the routine at its new address. `shift` is the address in the program minus the address in the library.
    - An operand that addresses something outside the routine can be different. `differing` lists each one with its value in the library and in the program. Examine them. For example, the program can use other variables or another SID voice.
@@ -119,7 +120,7 @@ To find the routines in a program:
    - The program uses the name at another address.
    - A removal holds at that place.
    - The routine occurs two times. Only the first copy gets the names.
-   - The script leaves out the name that an operand expression uses, or the expression does not give the operand in the image.
+   - The script leaves out the name that an operand expression uses, or the expression does not give the operand in the program.
 4. Apply the batch with the command in `apply`. Add `--project` when you are not in the project folder. The batch is one revision of the LLM. `batch.known` counts the writes that the program has already.
 
 ## Knowledge
@@ -151,7 +152,7 @@ The exit status is 0 for a result. The exit status is 1 for an error. The exit s
 - `not-found` from `match`: the library folder does not exist, or it has no routine files. Save a routine with `routine` first.
 - `conflict` from `routine`: the library has a routine with that name. Give another `--name`, or give `--replace` to save over it.
 - `invalid-input` with "is a project folder": the library folder is a project. Give a folder beside the projects.
-- `match` gives `count: 0`: the routine is not in the image. A packed program can hold the routine in a packed form. Unpack the program with c64-unpacker first.
+- `match` gives `count: 0`: the routine is not in the program. A packed program can hold the routine in a packed form. Unpack the program with c64-unpacker first.
 - `invalid-input`: a file, an address or a shift is wrong. A path that goes out of the project folder is also wrong, also through a link. Read the message.
 
 ## Handoffs