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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/c64-re-tools",
-  "version": "2.0.0-rc.17",
+  "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. |
@@ -82,7 +81,13 @@ node <skill>/scripts/link.ts docs --source src --check
 - `tables.md`: each table of addresses, jumps and words, entry by entry, with its target. An RTS table holds each target minus 1. The table gives the target.
 - `memory-map.md`: each region in address order.
 - `symbols.md`: each name in alphabetical order.
-- `graphics.md`: each `sprite`, `bitmap` and `screen` region. A sprite or a bitmap shows in hires and in multicolour, because the knowledge has no graphics mode. A screen shows as text.
+- `graphics.md`: each `sprite`, `bitmap`, `charset` and `screen` region. A sprite, a bitmap or a charset shows in hires and in multicolour, because the knowledge has no graphics mode. A charset shows 16 characters in each row. A screen shows as text.
+
+### Images and assets
+
+- The reference draws each sprite, bitmap and charset region, and it decodes each table. To get the image of a graphic or the entries of a table, classify its region with c64-knowledge. Do not write a script that draws or decodes them.
+- A script of the project decodes only a format of the program, for example a packed map or a music stream. Put the script in `tools/` of the project. Its output files are the assets, for example in `assets/rooms/`.
+- When the code of the program makes the data, run that code in VICE with a run of c64-testing. Observe the memory, or capture the screen. Do not write a 6502 emulator in the script.
 
 In the call graph, a solid arrow is a call, a thick arrow is a table entry, and a dotted arrow is a jump. A table entry goes from each routine that reads the table to each target in code. A table of data addresses gives no arrow.
 
@@ -103,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/references/style.md

@@ -27,7 +27,7 @@ These rules apply to each page that you write. `link.ts` checks the rules that a
 - Use mermaid for the diagrams: `flowchart` for calls and data flow, `stateDiagram-v2` for state machines. Write the name and the address in each node: `"draw_room $09BC"`.
 - A diagram gets no links. Give the links in a table or a list under the diagram.
 - Keep a diagram small: at most about 20 nodes. Make two diagrams before one diagram that a reader cannot read.
-- Embed an image only from the project. It can be an extracted asset (for example `../assets/sprites/bruce.png`), an image of the reference (`reference/images/`), or a PNG that a skill made. `link.ts` checks that each image exists.
+- Embed an image only from the project. It can be an image of the reference (`reference/images/`) or a PNG that a skill made. It can also be an asset that a script of the project made from a format of the program, for example `../assets/rooms/room00.png`. `link.ts` checks that each image exists.
 - Give each image one line of text that tells what it shows.
 
 ## Text

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

@@ -6,7 +6,7 @@
 import { posix } from "node:path";
 
 import { formatC64Address, POINTER_TABLE_TYPES, pointerTableEntries, type PointerTableType } from "#src/c64.ts";
-import { bitmapFrame, encodePng, PATTERN_PALETTES, scaleFrame, screenText, spriteSheet, type GraphicsMode } from "#src/graphics.ts";
+import { bitmapFrame, charsetFrame, encodePng, PATTERN_PALETTES, scaleFrame, screenText, spriteSheet, type GraphicsMode } from "#src/graphics.ts";
 import { mermaidGraph, ownerOf, routineEdges, routineHeads, type GraphReference, type RoutineHead } from "#src/knowledge/graph.ts";
 import type { CommentRow, ModuleRow, ReferenceRow, RegionRow, SymbolRow } from "#src/knowledge/read.ts";
 import type { RegionType } from "#src/knowledge/schema.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 {
@@ -37,7 +37,7 @@ export interface ReferenceFile {
 /** Files that the source map lists but that hold no code of the program. */
 const NOT_PIECES = new Set(["main.asm", "constants.asm", "macros.asm", "loader.asm"]);
 const TABLE_TYPES: readonly RegionType[] = [...POINTER_TABLE_TYPES, "jumps", "words"];
-const GRAPHICS_TYPES: readonly RegionType[] = ["sprite", "bitmap", "screen"];
+const GRAPHICS_TYPES: readonly RegionType[] = ["sprite", "bitmap", "charset", "screen"];
 /** A list longer than this ends with the number of the rest. */
 const MAX_LISTED = 40;
 /** A call graph with more edges is not readable: then it shows the calls only, and at most this many. */
@@ -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}*`);
@@ -327,9 +327,9 @@ export function buildReference(input: ReferenceInput): { files: ReferenceFile[];
     const lines = [
       "# Graphics",
       "",
-      `Each sprite, bitmap and screen region of the knowledge. The knowledge gives no display mode and no colours, so a sprite or bitmap 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"))}).`,
+      `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);
@@ -343,9 +343,9 @@ export function buildReference(input: ReferenceInput): { files: ReferenceFile[];
         continue;
       }
       for (const mode of ["hires", "multicolour"] as GraphicsMode[]) {
-        // A sheet of sprites, or a bitmap of at most 8 rows of cells, is small: each pixel shows as 2 x 2.
-        const raw = region.type === "sprite" ? spriteSheet(bytes, mode, region.element === 63 ? 63 : 64) : bitmapFrame(bytes, mode);
-        const frame = region.type === "sprite" || raw.height <= 64 ? scaleFrame(raw, 2) : raw;
+        // A sheet of sprites, a charset, or a bitmap of at most 8 rows of cells, is small: each pixel shows as 2 x 2.
+        const raw = region.type === "sprite" ? spriteSheet(bytes, mode, region.element === 63 ? 63 : 64) : region.type === "charset" ? charsetFrame(bytes, mode) : bitmapFrame(bytes, mode);
+        const frame = region.type === "sprite" || region.type === "charset" || raw.height <= 64 ? scaleFrame(raw, 2) : raw;
         const image = posix.join(out, "images", `${anchor}-${mode}.png`);
         files.push({ path: image, bytes: encodePng(frame, PATTERN_PALETTES[mode]) });
         lines.push("", `![${anchor} in ${mode}](${rel(page, image)})`);

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.