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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/c64-re-tools",
-  "version": "2.0.0-rc.18",
+  "version": "2.0.0-rc.19",
   "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

@@ -31,7 +31,7 @@ node <skill>/scripts/assemble.ts --source-root src --entry main.a --out build/ga
 | `--include lib` | An include directory, relative to the source root. Use it again for more directories. |
 | `--define DEBUG=1` | An assembler symbol: an integer, also as `$` hex, or `true` or `false`. Use it again for more symbols. |
 | `--set-pc '$0801'` | The start address when the source does not set one. |
-| `--compare unpacked/image.json` | Check the program byte by byte against a reference. The reference is the `image.json` of the c64-unpacker skill, a PRG, or 64 KiB of memory. |
+| `--compare` | Check the program byte by byte against the program in the knowledge, each segment. Put it in with `image` of the c64-knowledge skill. `--space drive8` or `--space bank0` compares with the program of that space. |
 | `--plain` | Write only the bytes of the program, without the 2-byte load address of a PRG. `loadRange` still tells where the bytes go. |
 | `--all-symbols` | List all symbols. Without it, the list does not include the constants that the source does not use. `unusedConstants` gives their count. |
 
@@ -43,8 +43,9 @@ The script prints one JSON object. The target CPU is the 6510. The output is a C
 
 - 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
@@ -75,7 +76,7 @@ A symbol from the rebuilt source can give the address of a routine in the rebuil
 
 The PRG in the project at the output path, with its load range and symbols. Or the source diagnostics when the assembly failed.
 
-With `--compare`, `compare` gives `identical` and one check for each segment of the reference. A check is `identical`, `different` with the first different address, or `not covered` when the program does not hold the segment.
+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.
 
 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.
 

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

@@ -13,6 +13,9 @@ import type { AcmeParams } from "#src/native/types.ts";
 import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
 import { compareBuild } from "./lib/compare.ts";
+import { KnowledgeError, openForRead } from "#src/knowledge/database.ts";
+import { requireProgram, type ProgramImage } from "#src/knowledge/program.ts";
+import { DEFAULT_SPACE, SPACE } from "#src/knowledge/schema.ts";
 
 const USAGE = `assemble.ts --source-root <dir> --entry <file> --out <file.prg> [options]
 
@@ -22,8 +25,11 @@ const USAGE = `assemble.ts --source-root <dir> --entry <file> --out <file.prg> [
   --include <dir>          include directory relative to the source root (repeatable)
   --define NAME=VALUE      assembler symbol: an integer ($hex allowed) or true/false (repeatable)
   --set-pc <address>       start address when the source sets none, for example '$0801'
-  --compare <file>         check the program byte by byte against an image.json of the
-                           c64-unpacker skill (each segment), a PRG, or 64 KiB of memory
+  --compare                check the program byte by byte against the program in the
+                           knowledge (D83), each segment; put it in with knowledge.ts
+                           image of the c64-knowledge skill
+  --space <space>          with --compare: the knowledge space of the program, c64 (the
+                           default), drive8, or bank0 to bank255
   --plain                  write the bytes only, without the 2-byte load address of a PRG
   --all-symbols            list also the constants that the source does not use
 
@@ -50,7 +56,8 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
       include: { type: "string", multiple: true },
       define: { type: "string", multiple: true },
       "set-pc": { type: "string" },
-      compare: { type: "string" },
+      compare: { type: "boolean" },
+      space: { type: "string" },
       plain: { type: "boolean" },
       "all-symbols": { type: "boolean" },
       help: { type: "boolean" },
@@ -67,6 +74,19 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
   } catch {
     throw new UsageError(`--out must be a path relative to the project folder that stays inside it, not ${out}`);
   }
+  if (values.space !== undefined && !values.compare) throw new UsageError("--space works only with --compare");
+  const space = values.space ?? DEFAULT_SPACE;
+  if (!SPACE.test(space)) throw new UsageError("--space must be c64, drive8, or bank0 to bank255");
+  // Read the program before ACME runs, so a project without it stops at once.
+  let program: ProgramImage | undefined;
+  if (values.compare) {
+    const db = openForRead();
+    try {
+      program = requireProgram(db, space);
+    } finally {
+      db?.close();
+    }
+  }
   const defines = Object.fromEntries((values.define ?? []).map(parseDefine));
   let setPc: number | undefined;
   if (values["set-pc"] !== undefined) {
@@ -85,7 +105,7 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
   mkdirSync(dirname(outPath), { recursive: true });
   writeFileSync(outPath, values.plain ? attachments![0]!.subarray(2) : attachments![0]!);
   const range = result.loadRange!;
-  const compared = values.compare === undefined ? undefined : compareBuild(attachments![0]!, values.compare);
+  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 listed = result.symbols!.filter((symbol) => values["all-symbols"] || symbol.kind === "address" || symbol.used);
   return {
@@ -114,5 +134,5 @@ await runScript(
     if (failed) process.exitCode = 1;
     return output;
   },
-  { usage: USAGE },
+  { usage: USAGE, refusals: [KnowledgeError] },
 );

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

@@ -1,12 +1,7 @@
-// The byte check of a build (D47): the assembled program against the image
-// of the unpacker (image.json with image.bin), a reference PRG, or 64 KiB of
-// memory, segment by segment.
-
-import { posix } from "node:path";
+// The byte check of a build (D47): the assembled program against the program
+// in the knowledge (D83), segment by segment.
 
 import { formatC64Address, prgRange } from "#src/c64.ts";
-import { readProjectFile } from "#src/host-client/transfer.ts";
-import { UsageError } from "#src/script.ts";
 
 export interface SegmentCheck {
   start: string;
@@ -18,47 +13,16 @@ export interface SegmentCheck {
   firstDifference?: { address: string; built: number; reference: number };
 }
 
-const FULL = 0x10000;
-
-/** The reference as memory and the ranges to check in it. */
-function reference(path: string, built: { start: number; end: number }): { memory: (address: number) => number | undefined; segments: Array<{ start: number; end: number }> } {
-  const { bytes } = readProjectFile(path);
-  if (path.endsWith(".json")) {
-    let manifest: { image?: unknown; segments?: unknown };
-    try {
-      manifest = JSON.parse(bytes.toString("utf8")) as typeof manifest;
-    } catch (error) {
-      throw new UsageError(`--compare ${path} is not JSON: ${(error as Error).message}`);
-    }
-    const segments = manifest.segments;
-    if (typeof manifest.image !== "string" || !Array.isArray(segments) || segments.length === 0) throw new UsageError(`--compare ${path} is not an image.json: it needs image and segments`);
-    const image = readProjectFile(posix.join(posix.dirname(path), manifest.image)).bytes;
-    if (image.length !== FULL) throw new UsageError(`the image of ${path} has ${image.length} bytes, not 65536`);
-    return {
-      memory: (address) => image[address],
-      segments: segments.map((segment: { start?: unknown; end?: unknown }) => {
-        const parse = (value: unknown) => (typeof value === "string" && /^\$[0-9a-f]{4}$/i.test(value) ? Number.parseInt(value.slice(1), 16) : NaN);
-        const range = { start: parse(segment.start), end: parse(segment.end) };
-        if (!(range.start <= range.end)) throw new UsageError(`--compare ${path}: a segment needs start and end as $ addresses`);
-        return range;
-      }),
-    };
-  }
-  if (bytes.length === FULL && !path.endsWith(".prg")) return { memory: (address) => bytes[address], segments: [built] };
-  let range: ReturnType<typeof prgRange>;
-  try {
-    range = prgRange(bytes);
-  } catch (error) {
-    throw new UsageError(`--compare ${path}: ${(error as Error).message}`);
-  }
-  return { memory: (address) => (address >= range.start && address <= range.end ? range.body[address - range.start] : undefined), segments: [{ start: range.start, end: range.end }] };
+/** The program that the build is checked against: its segments and its bytes in them. */
+export interface Reference {
+  segments: ReadonlyArray<{ start: number; end: number }>;
+  byteAt: (address: number) => number;
 }
 
 /** Compares the assembled PRG with the reference, segment by segment. */
-export function compareBuild(prg: Uint8Array, path: string): { against: string; identical: boolean; segments: SegmentCheck[] } {
+export function compareBuild(prg: Uint8Array, program: Reference): { identical: boolean; segments: SegmentCheck[] } {
   const built = prgRange(prg);
-  const { memory, segments } = reference(path, built);
-  const checks = segments.map((segment): SegmentCheck => {
+  const checks = program.segments.map((segment): SegmentCheck => {
     const from = Math.max(segment.start, built.start);
     const to = Math.min(segment.end, built.end);
     const shown = { start: formatC64Address(segment.start), end: formatC64Address(segment.end) };
@@ -67,8 +31,8 @@ export function compareBuild(prg: Uint8Array, path: string): { against: string;
     let first: SegmentCheck["firstDifference"];
     for (let address = from; address <= to; address++) {
       const builtByte = built.body[address - built.start]!;
-      const referenceByte = memory(address);
-      if (referenceByte === undefined || builtByte === referenceByte) continue;
+      const referenceByte = program.byteAt(address);
+      if (builtByte === referenceByte) continue;
       differences++;
       first ??= { address: formatC64Address(address), built: builtByte, reference: referenceByte };
     }
@@ -80,5 +44,5 @@ export function compareBuild(prg: Uint8Array, path: string): { against: string;
       ...(differences > 0 ? { differences, firstDifference: first! } : {}),
     };
   });
-  return { against: path, identical: checks.every((check) => check.result === "identical"), segments: checks };
+  return { identical: checks.every((check) => check.result === "identical"), segments: checks };
 }

package/skills/c64-basic/SKILL.md

@@ -29,8 +29,9 @@ The script prints one JSON object. Addresses are `$` and four hex digits.
 
 - 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-disk/SKILL.md

@@ -46,8 +46,9 @@ File names show the characters that the C64 shows in a directory list. A byte th
 
 - 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-docs/SKILL.md

@@ -19,7 +19,7 @@ This skill does not change the knowledge.
 ## Inputs
 
 - The source directory of c64-source, with its `source-map.json`, for example `src`. The source must be from the current knowledge revision.
-- The image of the source, for example `unpacked/image.json`. It decodes the tables and shows the graphics.
+- The program in the knowledge. Put it in with `image` of the c64-knowledge skill. The reference decodes the tables and shows the graphics from it.
 - The directory of the documentation, for example `docs`. The reference goes into a directory of its own, for example `docs/reference`.
 
 ## Tools / execution path
@@ -27,7 +27,7 @@ This skill does not change the knowledge.
 The scripts run on this machine. They do not use the emulator or the host runtime.
 
 ```
-node <skill>/scripts/generate.ts --source src --out docs/reference --image unpacked/image.json
+node <skill>/scripts/generate.ts --source src --out docs/reference
 node <skill>/scripts/link.ts docs --source src
 node <skill>/scripts/link.ts docs --source src --check
 ```
@@ -36,7 +36,6 @@ node <skill>/scripts/link.ts docs --source src --check
 |---|---|
 | `--source src` | The source directory of c64-source. Both scripts read `src/source-map.json`. |
 | `--out docs/reference` | The directory of the reference. `generate.ts` writes only there. It refuses to start when the directory holds a page that it did not write. |
-| `--image unpacked/image.json` | The image. Without it, the tables are not decoded and the graphics page has no images. |
 | `docs` | The directory of the documentation. `link.ts` reads every `.md` file below it. It changes only the pages that you wrote. It checks the pages of the reference. |
 | `--reference <dir>` | The directory of the reference for `link.ts`. The default is `docs/reference` when it exists. |
 | `--check` | `link.ts` writes nothing. It fails when a link is not up to date or a page has a problem. |
@@ -109,7 +108,7 @@ Do not store:
 
 - `out`, `index` and `revision`.
 - `pages`, `entries`, `tables`, `images` and `edges`: the counts of the reference.
-- `image`: the image, or a note when `--image` is not given.
+- `program`: `the knowledge`, or a note when the knowledge has no program. Without the program, the tables are not decoded and the graphics page has no images.
 
 `link.ts` gives one JSON object:
 

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

@@ -1,12 +1,11 @@
 // c64-docs generate.ts (D80): the reference pages of a program from the
-// knowledge, the source map of c64-source and the image. The pages are
+// knowledge, the source map of c64-source and the program in the knowledge. The pages are
 // generated and never edited; the pages of a person link to them.
 
 import { existsSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { join, posix } from "node:path";
 import { parseArgs } from "node:util";
 
-import { ImageError, readImage } from "#src/host-client/image.ts";
 import { WireFailure } from "#src/host-client/tools.ts";
 import { writeProjectFile } from "#src/host-client/transfer.ts";
 import { conflicts } from "#src/knowledge/conflicts.ts";
@@ -16,18 +15,18 @@ import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
 import { buildReference, GENERATED_MARK } from "./lib/reference.ts";
 import { readSourceMap } from "./lib/source-map.ts";
+import { programImage, type ProgramImage } from "#src/knowledge/program.ts";
 
-const USAGE = `generate.ts --source <dir> --out <dir> [--image <file>]
+const USAGE = `generate.ts --source <dir> --out <dir>
 
   --source <dir>   the source directory of c64-source, with its source-map.json,
                    relative to the project folder
   --out <dir>      the directory for the reference pages, relative to the project
                    folder, for example docs/reference; generate.ts writes only
                    there and refuses a page in it that it did not write
-  --image <file>   the image of the source: an image.json of the c64-unpacker
-                   skill, or a PRG; it decodes the tables and shows the graphics
-
-The result is one JSON object.`;
+When the knowledge has the program of the source (knowledge.ts image of the
+c64-knowledge skill, D83), the reference decodes the tables and shows the
+graphics. The result is one JSON object.`;
 
 /** The files of an earlier run, or a refusal that names a file of a person. */
 function oldFiles(out: string): string[] {
@@ -51,7 +50,7 @@ function oldFiles(out: string): string[] {
 }
 
 function run(argv: string[]): Record<string, unknown> {
-  const { values, positionals } = parseArgs({ args: argv, strict: true, allowPositionals: true, options: { source: { type: "string" }, out: { type: "string" }, image: { type: "string" }, help: { type: "boolean" } } });
+  const { values, positionals } = parseArgs({ args: argv, strict: true, allowPositionals: true, options: { source: { type: "string" }, out: { type: "string" }, help: { type: "boolean" } } });
   if (values.help) throw new UsageError("");
   if (positionals.length > 0) throw new UsageError(`generate.ts takes no positional arguments, not ${positionals[0]}`);
   if (values.source === undefined) throw new UsageError("give --source <dir>: the source directory of c64-source");
@@ -64,18 +63,11 @@ function run(argv: string[]): Record<string, unknown> {
     }
   }
   const map = readSourceMap(values.source);
-  let image: ReturnType<typeof readImage> | undefined;
-  if (values.image !== undefined) {
-    try {
-      image = readImage(values.image);
-    } catch (error) {
-      if (error instanceof ImageError) throw new UsageError(error.message);
-      throw error;
-    }
-  }
   const db = openForRead();
   let knowledge;
+  let image: ProgramImage | undefined;
   try {
+    image = programImage(db, map.space);
     const found = conflicts(db).length;
     if (found > 0) throw new KnowledgeError("conflict", `The knowledge has ${found} conflict${found === 1 ? "" : "s"} from a git merge. Nothing was written. Run c64-knowledge's knowledge.ts merge, then generate the source and the reference again.`);
     const revision = currentRevision(db);
@@ -99,12 +91,12 @@ function run(argv: string[]): Record<string, unknown> {
     out: posix.normalize(values.out),
     map,
     ...knowledge,
-    ...(image === undefined ? {} : { image: { path: image.path, byteAt: image.byteAt, inImage: (address: number) => image.segments.some((segment) => address >= segment.start && address <= segment.end) } }),
+    ...(image === undefined ? {} : { image: { byteAt: image.byteAt, inImage: (address: number) => image.segments.some((segment) => address >= segment.start && address <= segment.end) } }),
   });
   const directory = resolveProjectPath(values.out);
   for (const path of old) rmSync(join(directory, path), { force: true });
   for (const file of built.files) writeProjectFile(file.path, file.bytes, { what: "--out" });
-  return { out: values.out, revision: knowledge.revision, index: posix.join(posix.normalize(values.out), "index.md"), ...built.counts, image: image?.path ?? "none: give --image to decode the tables and show the graphics" };
+  return { out: values.out, revision: knowledge.revision, index: posix.join(posix.normalize(values.out), "index.md"), ...built.counts, program: image === undefined ? "none: put the program into the knowledge with knowledge.ts image to decode the tables and show the graphics" : "the knowledge" };
 }
 
 await runScript(run, { usage: USAGE, refusals: [KnowledgeError] });

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

@@ -25,7 +25,7 @@ export interface ReferenceInput {
   comments: CommentRow[];
   references: ReferenceRow[];
   modules: ModuleRow[];
-  image?: { path: string; byteAt: (address: number) => number; inImage: (address: number) => boolean };
+  image?: { byteAt: (address: number) => number; inImage: (address: number) => boolean };
 }
 
 export interface ReferenceFile {
@@ -299,7 +299,7 @@ export function buildReference(input: ReferenceInput): { files: ReferenceFile[];
   {
     const page = posix.join(out, "tables.md");
     const lines = ["# Tables", "", `Each table of addresses, jumps and words, entry by entry. An RTS table holds each target minus 1; the target column gives the target. Index: [the reference](${rel(page, posix.join(out, "index.md"))}).`];
-    if (input.image === undefined) lines.push("", "Generate the reference with --image to decode the tables.");
+    if (input.image === undefined) lines.push("", "Put the program into the knowledge with knowledge.ts image, then generate the reference again to decode the tables.");
     for (const table of tables) {
       const name = entryAt.get(table.start);
       lines.push("", `<a id="${tableAnchor(table)}"></a>`, `## ${name === undefined ? `\`${range(table.start, table.end)}\`` : `${codeOfName(page, name.name)} \`${range(table.start, table.end)}\``}`, "", `*${table.type}*`);
@@ -329,7 +329,7 @@ export function buildReference(input: ReferenceInput): { files: ReferenceFile[];
       "",
       `Each sprite, bitmap, charset and screen region of the knowledge. The knowledge gives no display mode and no colours, so a sprite, bitmap or charset shows in hires and in multicolour, in pattern colours: black is pixel value 0, white is 1 in hires; in multicolour light grey is 1, grey is 2 and yellow is 3. Index: [the reference](${rel(page, posix.join(out, "index.md"))}).`,
     ];
-    if (input.image === undefined && graphics.length > 0) lines.push("", "Generate the reference with --image to show the graphics.");
+    if (input.image === undefined && graphics.length > 0) lines.push("", "Put the program into the knowledge with knowledge.ts image, then generate the reference again to show the graphics.");
     for (const region of graphics) {
       const anchor = entryAt.get(region.start)?.name ?? `${region.type}_${region.start.toString(16).padStart(4, "0")}`;
       const name = entryAt.get(region.start);

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

@@ -18,7 +18,6 @@ export interface SourceLine {
 export interface SourceMap {
   /** The source directory, relative to the project folder. */
   directory: string;
-  image: string;
   space: Space;
   revision: string;
   files: string[];
@@ -60,7 +59,6 @@ export function readSourceMap(directory: string): SourceMap {
   const byName = new Map(labels.map((label) => [label.name, label]));
   return {
     directory,
-    image: String(raw.image),
     space: String(raw.space ?? "c64") as Space,
     revision: String(raw.revision),
     files: (raw.files as unknown[]).map(String),

package/skills/c64-emulator/SKILL.md

@@ -51,9 +51,9 @@ Use only the MCP tools. Each MCP session has its own C64. Nothing else can chang
 
 Each memory and register tool has a `space`. Use `c64` for the computer. Use `drive8` for the CPU of the 1541 disk drive. The memory `view` is `cpu` or `ram`. With `cpu`, you see what the CPU sees now, with ROM and I/O where the memory configuration puts them. With `ram`, you see the RAM under them.
 
-For a large result, give `out` with a path in the project. `c64_memory_read`, `c64_disassemble`, `c64_cpu_history` and `c64_screen` then write the result to that file. The answer gives only the file, the number of bytes and a SHA-256. Use it for a memory dump of more than a few hundred bytes, a long listing, or a screen that the user wants to keep. `c64_memmap` action `read` and `c64_snapshot` action `save` also take `out`.
+For a large result, give `out` with a path in the project. `c64_memory_read`, `c64_disassemble`, `c64_cpu_history` and `c64_screen` then write the result to that file. The answer gives only the file, the number of bytes and a SHA-256. Use it for a memory dump of more than a few hundred bytes, a long listing, or a screen that the user wants to keep. `c64_memmap` action `read` and `c64_snapshot` action `save` also take `out`. Write a file that is only for your work in `.c64-re-tools/local/` of the project. Git ignores that folder.
 
-`c64_memmap` keeps RAM, ROM and I/O apart. Use action `summary` to see which code ran. Use action `read` with `out` to keep a coverage run as a file, for example `coverage/attract.bin`. Clear the map before each run that you want to keep apart.
+`c64_memmap` keeps RAM, ROM and I/O apart. Use action `summary` to see which code ran. Use action `read` with `out` to keep a coverage run as a file, for example `.c64-re-tools/local/attract.bin`. Then add it to the knowledge with `coverage` of the c64-knowledge skill. Clear the map before each run that you want to keep apart.
 
 - Only the first byte of an instruction gets execute. Thus `read` without `out` gives a new range at each instruction of code. For code, use `summary`, or `read` with `out`.
 - A read on a byte right after executed code, or at a return address, can be a dummy read of the 6502. The CPU reads such a byte but does not use it.

package/skills/c64-knowledge/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: c64-knowledge
-description: Use this skill to read, write, correct and review the durable knowledge of a C64 project in .c64-re-tools/knowledge/. It gives the knowledge at an address, and it names symbols, classifies memory regions, sets comments and records references. It records patches and macros for the generated source. It also shows the history of each change, and it can revert to an earlier revision. Do not use it for live emulator state or for static analysis.
+description: Use this skill to read, write, correct and review the durable knowledge of a C64 project in .c64-re-tools/knowledge/. The knowledge holds the program, its entry state and the coverage of the runs. It gives the knowledge at an address, and it names symbols, classifies memory regions, sets comments and records references. It records patches and macros for the generated source. It also shows the history of each change, and it can revert to an earlier revision. Do not use it for live emulator state or for static analysis.
 ---
 
 # c64-knowledge
 
 ## Purpose
 
-Read, write, correct and review the durable understanding of a C64 project. The knowledge is text in `.c64-re-tools/knowledge/` in the project folder: one JSON line for each row. Commit that folder with git. The script keeps an index of the text in `.c64-re-tools/local/knowledge.db` and makes the index again when the text changes. Do not commit the index.
+Read, write, correct and review the durable understanding of a C64 project. The knowledge also holds the program: its bytes, its entry state and the stages of its unpacker. It holds the coverage of the runs too. The other skills read the program and the coverage from the knowledge. The knowledge is text in `.c64-re-tools/knowledge/` in the project folder: one JSON line for each row. Commit that folder with git. The script keeps an index of the text in `.c64-re-tools/local/knowledge.db` and makes the index again when the text changes. Do not commit the index.
 
 This skill is the only write path for conclusions of the user and the LLM. It does not run an emulator or an analyzer. Write the knowledge only with the script. The script checks each write. Do not write or edit the files in `.c64-re-tools/knowledge/` or the index yourself.
 
@@ -18,6 +18,7 @@ One of these:
 - an address, a range or a symbol name to look up
 - text to search for
 - a change to a symbol, a region, a comment or a reference, with a short reason
+- a capture of the c64-unpacker skill, a PRG, or coverage maps to put into the knowledge
 - a request to see the history or a revision.
 
 ## Tools / execution path
@@ -37,8 +38,11 @@ A symbol is the name of an address from the user or the LLM. An analyzer name is
 | Lists in a range | `symbols`, `regions`, `comments`, `references` with `--start` and `--end` |
 | The names that DXA, Ghidra and the idioms gave | `symbols --analyzer` |
 | Only some origins | add `--origin semantic`, `--origin analyzer` (dxa, ghidra and heuristic), or `--origin user,llm` |
-| All knowledge in one file | `export --out exports/knowledge.json` |
-| The code of a range with names, comments, access and references | `listing '$0400' '$04ff' --image unpacked/image.json --coverage coverage/game.bin` |
+| All knowledge in one file | `export --out .c64-re-tools/local/knowledge.json` |
+| Put the program into the knowledge | `image .c64-re-tools/local/capture/image.json` or `image original/game.prg` |
+| Add the coverage of runs | `coverage .c64-re-tools/local/runs/rooms/room0.bin ...` |
+| What the knowledge holds of the program | `program` |
+| The code of a range with names, comments, access and references | `listing '$0400' '$04ff'` |
 | Name the symbol at an address | `rename '$2100' update_player --kind routine` |
 | Remove a symbol | `remove-symbol '$2100'` |
 | Classify memory | `classify '$3000' '$303f' sprite` |
@@ -50,12 +54,12 @@ A symbol is the name of an address from the user or the LLM. An analyzer name is
 | Add or remove a reference | `reference '$2000' '$2100' call` / `unreference ...` |
 | Places that a removal blocks | `suppressions` with `--start` and `--end` |
 | Start a file of generated source | `module '$2000' player.asm --title 'Player movement'` / `unmodule '$2000'` |
-| Write the operand of an instruction as an expression | `operand '$8079' --lo irq_handler --image unpacked/image.json` / `unoperand '$8079'` |
+| Write the operand of an instruction as an expression | `operand '$8079' --lo irq_handler` / `unoperand '$8079'` |
 | Operand expressions | `operands` with `--start` and `--end` |
-| Replace a range with code when a switch is on | `patch '$100e' '$1010' CRACK --code-file crack.asm --image unpacked/image.json` / `unpatch '$100e'` |
+| Replace a range with code when a switch is on | `patch '$100e' '$1010' CRACK --code-file crack.asm` / `unpatch '$100e'` |
 | Patches and switches | `patches` with `--switch`, and `switches` |
 | Write a macro | `macro inc16 --params dst --body-file inc16.asm` / `unmacro inc16` |
-| Write instructions as one use of a macro | `use '$1005' '$100a' inc16 --args ptr --image unpacked/image.json` / `unuse '$1005'` |
+| Write instructions as one use of a macro | `use '$1005' '$100a' inc16 --args ptr` / `unuse '$1005'` |
 | Macros and their uses | `macros`, and `uses` with `--start`, `--end` and `--macro` |
 | Files of generated source | `modules` |
 | The address spaces that hold knowledge | `spaces` |
@@ -89,8 +93,9 @@ Region types:
 
 - 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
@@ -104,11 +109,24 @@ Write:
 
 1. Read the current value with `at`. Note the `revision` in the result.
 2. Decide the change. Keep observed facts apart from your conclusions.
-3. Write it with `--reason` and `--expect-revision` set to the revision you read. Add `--evidence` for each thing that the change rests on: `coverage:<file>`, `test:<file>`, `file:<file>` or `note:<text>`. The script keeps the SHA-256 of each file.
+3. Write it with `--reason` and `--expect-revision` set to the revision you read. Add `--evidence` for each thing that the change rests on: `coverage:<map>`, `test:<file>`, `file:<file>` or `note:<text>`. `<map>` is a coverage map that `coverage` put into the knowledge, by its path at that time. The script keeps the SHA-256 of each file and map.
 4. Read the result. A `revision` of `null` means that nothing changed.
 
 Each write is one revision. A classification inside a region splits that region, so regions never overlap.
 
+## The program and the coverage
+
+The knowledge holds the program, so a project needs no image or coverage files. The other skills read them from the knowledge and take no path to them.
+
+1. Capture a packed program with the c64-unpacker skill into `.c64-re-tools/local/`. Then put it in with `image .c64-re-tools/local/capture/image.json`. The script reads `image.bin`, `entry_state.json` and the stages next to it.
+2. For a program without a packer, drive code or a cartridge bank, put the PRG in with `image <file.prg>`. Give `--space drive8` or `--space bank0` for drive code or a bank.
+3. Write each coverage map of a run into `.c64-re-tools/local/`. Then add it with `coverage <map.bin> ...`.
+4. Read what the knowledge holds with `program`: the segments, the entry, and the coverage maps that it has.
+
+- `image` writes only the bytes that changed. The same image again writes nothing. A new image replaces the program of the space. The history keeps the old bytes.
+- `coverage` joins the maps. It keeps each address that a run executed, read or wrote. It also keeps each address that one run wrote and executed: self-modified code. A map that the knowledge has is not added again.
+- The capture and the maps are not necessary after the import. Keep them in `.c64-re-tools/local/`.
+
 For more than a few writes, use `apply -` and give the writes on standard input as one JSON list. Each write has `op` and the arguments of the command with the same name, for example:
 
 ```json
@@ -140,15 +158,15 @@ The ops and their fields:
 | `unmacro` | `name` |
 | `use` | `start`, `end`, `macro`, `args` (a list or a comma list) |
 
-A `line` comment is a line of its own above the address. A `side` comment is at the end of the line of the address. `apply` with an `operand`, `patch` or `use` write needs `--image`. All writes become one revision. If the knowledge refuses one write, the script writes nothing, and the error names the write.
+A `line` comment is a line of its own above the address. A `side` comment is at the end of the line of the address. The script checks an `operand`, `patch` or `use` write against the program of the knowledge in the space of `--space`. All writes become one revision. If the knowledge refuses one write, the script writes nothing, and the error names the write.
 
 The c64-provenance skill writes a batch with `match --out`. The batch holds the names of library routines at their addresses in this program. Read the `batch.leftOut` of its result first. Then apply the batch with the command in its `apply`.
 
 ## Listing
 
-`listing` reads the image and the knowledge, and writes no knowledge. Use it in place of your own disassembler.
+`listing` reads the program and the other knowledge, and writes no knowledge. Use it in place of your own disassembler.
 
-- `listing` gives one line for each instruction of a code region, and one `!byte` line for other bytes. A line has the name of the address, the instruction with the names of its target, and the comments. An operand expression of the knowledge replaces the operand. `analyzerNames` gives the second names. `referencesIn` and `referencesOut` count the references. With `--coverage`, `access` tells if a run executed (`x`), read (`r`) or wrote (`w`) the bytes of the line, or `-` for none. `--out` writes the listing as text to a project file.
+- `listing` gives one line for each instruction of a code region, and one `!byte` line for other bytes. A line has the name of the address, the instruction with the names of its target, and the comments. An operand expression of the knowledge replaces the operand. `analyzerNames` gives the second names. `referencesIn` and `referencesOut` count the references. When the knowledge has coverage, `access` tells if a run executed (`x`), read (`r`) or wrote (`w`) the bytes of the line, or `-` for none. `--out` writes the listing as text to a project file.
 
 ## Batches of parallel agents
 
@@ -163,7 +181,7 @@ When more agents name the program at the same time, give each agent one range of
 - `choices` lists each place where the batches gave different values, with the value that stays.
 - When one name or one module file is at two addresses, `join` writes nothing. `clashes` lists the addresses and the batches. Correct the batches, then do `join` again.
 
-Then apply the joined batch with the command in `apply`. Add `--image` when the batch has an `operand`, `patch` or `use` write.
+Then apply the joined batch with the command in `apply`.
 
 ## Modules
 
@@ -185,7 +203,7 @@ Give one selector:
 - `--offset` adds a whole number to the symbol. Write a negative offset as `--offset=-1`.
 - A name is a symbol of the knowledge or a platform name of the c64-memory-map skill.
 - `--expr` takes `$`, `%` and decimal numbers, names, brackets, the operators `+ - * / % << >> >>> & | XOR`, and `<`, `>`, `-` and `!` before an operand.
-- The script compares the value of the expression with the operand in the image. If they are not equal, the script refuses the write. Give the image with `--image`: an `image.json` of the c64-unpacker skill or a PRG. `apply` with an `operand` write also needs `--image`.
+- The script compares the value of the expression with the operand in the program of the knowledge. If they are not equal, the script refuses the write.
 - Each name in the expression gets a `pointer` reference from the instruction. Thus `at` on the named address shows the code that uses the address.
 - A `rename` of a symbol changes the name in each expression. The knowledge refuses `remove-symbol` while an expression uses the symbol. Use `unoperand` first.
 
@@ -193,7 +211,7 @@ Write an operand expression for each immediate that is a byte of an address. Als
 
 ## Code switches
 
-A patch is ACME code that replaces a range of the image when the build defines its switch as 1. Use patches to change the program, for example for a crack, a trainer or a debug hook. The default build does not define the switch. Thus the c64-source skill still makes a source that is identical to the image.
+A patch is ACME code that replaces a range of the program when the build defines its switch as 1. Use patches to change the program, for example for a crack, a trainer or a debug hook. The default build does not define the switch. Thus the c64-source skill still makes a source that is identical to the program.
 
 - A switch name is upper case, for example `CRACK` or `TRAINER`. It cannot be the name of a symbol or a platform name.
 - Many patches can have the same switch. The c64-source skill builds each switch on its own. It does not build two switches together.
@@ -201,7 +219,7 @@ A patch is ACME code that replaces a range of the image when the build defines i
 - `--code` gives the code as text. `--code-file` reads the code from a project file. The code can use the labels and the macros of the source, and local labels with a dot, for example `.skip`.
 - The braces in the code must be pairs, because the source puts the code inside `{ }`.
 - A patch cannot overlap another patch or a macro use.
-- Give the image with `--image`. Each byte of the range must be in the image.
+- Each byte of the range must be in the program of the knowledge.
 - A `patch` write without `--comment` keeps the comment that the patch has.
 
 Build the program with a switch on with the c64-assembler skill: `--define CRACK=1`.
@@ -212,12 +230,12 @@ A macro writes a run of instructions as one line of the source, for example `+in
 
 - `macro` writes the ACME macro: its name, its params and its body. `--params` gives the params as a comma list, without a dot. The body uses each param with a dot, for example `.dst`.
 - `use` writes the instructions from the start to the end as one use of a macro. `--args` gives one expression for each param, as a comma list. Each name in an arg is a symbol of the knowledge or a platform name.
-- The range of a use is complete instructions. Give the image with `--image`.
+- The range of a use is complete instructions of the program of the knowledge.
 - A `rename` of a symbol changes the name in each arg. The knowledge refuses `remove-symbol` while an arg uses the symbol.
 - The knowledge refuses `unmacro` while the macro has uses. It also refuses a change of the number of params while the macro has uses.
 - A use cannot overlap a patch or another use.
 
-The c64-source skill writes a use only when the use gives the bytes of the image. If not, it writes the instructions and gives the reason. The c64-static-analysis skill finds uses of known 6502 idioms and writes them to a batch with `--macro-batch`.
+The c64-source skill writes a use only when the use gives the bytes of the program. If not, it writes the instructions and gives the reason. The c64-static-analysis skill finds uses of known 6502 idioms and writes them to a batch with `--macro-batch`.
 
 ## Removals