@henols/c64-re-tools 2.0.0-rc.8 → 2.0.0

package/README.md

@@ -1,47 +1,59 @@
 # c64-re-tools
 
-An agent-friendly Commodore 64 engineering toolkit for reverse engineering
-unknown applications and for developing, debugging, building and testing new
-C64 applications.
-
-An agent drives a real VICE emulator through an MCP server, and uses skills
-for the rest: disk images, BASIC, static analysis with DXA and Ghidra, a project
-knowledge database, the ACME assembler, unpacking, release comparison and
-functional-equivalence tests.
-
-Architecture in one line: one MCP process owns one VICE instance and is
-VICE-only; a Host Runtime on the graphical host owns VICE and the tools that
-come with it (c1541, petcat); skill scripts call the Host Runtime for those,
-run ACME, DXA and Ghidra themselves, and keep project knowledge local in
-`.c64-re-tools/knowledge.db`.
-The design is in [`docs/redesign/`](docs/redesign/README.md), and
-[`docs/plan.md`](docs/plan.md) tracks the implementation.
+Let an AI agent work on Commodore 64 programs. The agent drives a real VICE
+emulator and runs ACME, DXA and Ghidra. Use it to build new C64 apps and games,
+and to reverse engineer old ones.
 
-## Install
+It works with Claude Code, Codex, pi, opencode, Gemini, Copilot, Cursor and
+Windsurf.
 
-You need Node.js 24 or newer, and VICE 3.9 or later (`x64sc`, `c1541`, `petcat`) with its ROM files; use the latest VICE release. `status` and the host name the known flaws of an older VICE. ACME, DXA and Ghidra are needed only for the skills that use them: [docs/install-tools.md](docs/install-tools.md) has the steps for each system.
+## What it can do
 
-Start the Host Runtime and leave it running:
+**Build new apps and games**
 
-```
-npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host
-```
+- Assemble 6510 source with ACME, with errors by file and line, and symbols.
+- Load and run the program in VICE. Set breakpoints and watchpoints, step, and read the CPU history and the call stack.
+- Read, write, search and compare memory, and disassemble it.
+- Show the VIC-II, sprite, SID and CIA state, and capture the screen.
+- Type on the keyboard and move the joystick.
+- Count cycles, profile the code, and wait for a raster line.
+- Run many steps in one go and keep screens, snapshots and coverage as files.
+- Tell what any address or register value means on the C64.
+
+**Reverse engineer existing programs**
 
-Install into your project and start the agent:
+- Read D64, D71, D81, G64, T64 and CRT images, list BASIC and find the SYS address.
+- Find packers and capture the unpacked program from the emulator.
+- Analyse the code with DXA and Ghidra. The toolkit brings its own NMOS 6510 language for Ghidra, with all 256 opcodes.
+- Keep names, regions and comments as text in the project, ready for git.
+- Compare releases, and find routines that several programs share.
+- Generate ACME source that rebuilds the program byte for byte, and its documentation.
+- Test that a rebuild behaves as the original: PASS, FAIL or INCONCLUSIVE.
+
+## How it works
+
+VICE and the Host Runtime run on your computer, where VICE can open a window.
+The agent runs in your project, preferably in a dev container. It reaches VICE
+through an MCP server, and it runs ACME, DXA and Ghidra through its skills.
+
+## Install
+
+You need Node.js 24 or newer and VICE 3.9 or later (`x64sc`, `c1541`, `petcat`)
+with its ROM files on the host. Use the latest VICE release.
+
+Start the Host Runtime on the host, and leave it running:
 
 ```
-cd my-c64-project
-npx -y @henols/c64-re-tools@latest install --target claude
-claude
+npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host
 ```
 
-`npx -y @henols/c64-re-tools@latest status` shows what works.
-
-Until 2.0.0 is released, `@latest` is the old 1.1.0. Use the prerelease instead. For the prerelease, a dev container and debugging, see [docs/debug-install.md](docs/debug-install.md).
+`--log-console` prints each call, and `--log-dir <directory>` writes them to a file.
 
 ### Dev container
 
-The agent runs in the container, VICE and the Host Runtime on the host. In `.devcontainer/devcontainer.json`:
+This is the preferred way. The container gets ACME, dxa, Java 21 and Ghidra,
+installs the toolkit into the project when it is created, and updates it at
+each start. Add to `.devcontainer/devcontainer.json`:
 
 ```json
 "features": {
@@ -50,127 +62,98 @@ The agent runs in the container, VICE and the Host Runtime on the host. In `.dev
 "runArgs": ["--add-host=host.docker.internal:host-gateway"]
 ```
 
-Until 2.0.0 is released, the `latest` URL has no Feature. Use the prerelease: `https://github.com/henols/c64-re-tools/releases/download/v2.0.0-rc.4/devcontainer-feature-c64-re-tools.tgz` with `{ "target": "claude", "channel": "next" }`.
+`target` is the harness, or a comma list such as `claude,codex`. The Feature
+needs a Debian or Ubuntu image. `runArgs` is for Docker on Linux.
+
+### Without a container
 
-The Feature installs ACME, dxa, Java 21 and Ghidra, puts the toolkit into the project when the container is created, and updates it at each start. `target` is a harness or a comma list. `channel` is `latest` (default) or `next`. Debian and Ubuntu images only. `runArgs` is for Docker on Linux. Start the Host Runtime on the host as above.
+Install ACME, dxa and Ghidra as in [docs/install-tools.md](docs/install-tools.md).
+Then, in your project:
 
-### Settings
+```
+npx -y @henols/c64-re-tools@latest install --target claude
+```
 
-| Variable | Read by | Meaning |
-| --- | --- | --- |
-| `C64RT_VICE` | host | Full path of `x64sc` when it is not on `PATH`. |
-| `C64RT_C1541`, `C64RT_PETCAT` | host | Full path of the tool when it is not on `PATH`. |
-| `C64RT_ACME`, `C64RT_DXA` | skills, CLI | Full path of the tool when it is not on `PATH`. |
-| `C64RT_GHIDRA` | skills, CLI | The Ghidra installation directory, when `analyzeHeadless` is not on `PATH`. |
-| `C64RT_HOST` | MCP, skills, CLI | `host:port` of the Host Runtime when it is not on 127.0.0.1, `host.docker.internal` or `host.containers.internal` at 6464. |
-| `C64RT_VIDEO` | MCP | `pal` (default) or `ntsc`, fixed for the life of the MCP process. |
-| `C64RT_TRACE` | host, MCP, skills, CLI | A directory for a trace of what the programs do, for a person who debugs a run. See [docs/debug-install.md](docs/debug-install.md). Nothing of the trace reaches the agent. |
+`--target` is `claude`, `codex`, `pi`, `opencode`, `gemini`, `copilot`, `cursor`
+or `windsurf`. Without it, `install` installs for all of them.
 
-Ghidra runs with its own settings directory for each request. The toolkit
-brings its own NMOS 6510 language (all 256 opcodes); your Ghidra installation
-and settings stay unchanged.
+Check what works:
 
-## Use it with an agent
+```
+npx -y @henols/c64-re-tools@latest status
+```
 
-1. Install for your harness: `--target claude`, `codex`, `pi`, `opencode`, `gemini`, `copilot`, `cursor` or `windsurf`. Without `--target`, `install` installs for all of them.
-2. Start the Host Runtime and leave it running.
-3. Start the harness in the project, for example `claude` or `codex`, or open the project in Cursor or Windsurf. The harness starts the MCP server and finds the skills by itself.
-4. Ask for the result you want, in plain words. The agent picks the skills and the `c64_*` tools.
+## Use it
 
-Examples:
+Start the agent in the project, for example `claude`, and ask for what you want:
 
 ```
-Reverse engineer original/game.d64. Find how it starts, unpack it if it is packed,
-and name the main routines in project knowledge.
+Write a game in ACME where a sprite moves with the joystick and the border
+flashes when it hits the edge. Build it, run it, and show me the screen.
 
-Find the routine that draws the score, and explain how it works.
+The music stops when the title screen starts. Find out why.
 
-Write a program in ACME that scrolls a text at the bottom of the screen.
-Build it, run it in the emulator, and write a test for it.
+Reverse engineer original/game.d64. Find how it starts, unpack it if it is
+packed, and name the main routines.
 
-Show me the emulator window.
+Find the routine that draws the score, and explain how it works.
 ```
 
-The agent keeps what it learns about the program in `.c64-re-tools/knowledge.db`. Commit that file with the project.
+The agent keeps what it learns about a program as text in
+`.c64-re-tools/knowledge/`. Commit that folder with the project. If a command
+reports conflicts after a `git pull`, run `knowledge.ts merge`.
+
+Several programs in one repository: install once at the root and give each
+program its own folder. A folder with `.c64-re-tools/` is a project.
 
 ## Skills
 
 | Skill | Use |
 | --- | --- |
-| c64-reverse-engineering | Coordinates an investigation and picks the specialist for the next unknown. |
-| c64-emulator | Runs and observes the program in VICE through the MCP tools. |
-| c64-static-analysis | A fast first pass with DXA and a deeper pass with Ghidra into knowledge, with seeds from knowledge and decompilation. |
-| c64-knowledge | Reads and writes symbols, regions, comments and references, with history. |
+| c64-assembler | Builds ACME source, with errors and symbols. |
+| c64-emulator | Runs, debugs and observes the program in VICE. |
+| c64-memory-map | What an address or a register value means. |
+| c64-testing | Runs scenarios: original against rebuild, or many steps on one program. |
 | c64-disk | Directory, BAM, entries, sector chains and extraction of disk images. |
 | c64-basic | BASIC V2 listings and the SYS/USR handoff to machine code. |
-| c64-unpacker | Packing evidence, and capture of the unpacked program from the emulator. |
-| c64-memory-map | Platform meaning of addresses and register values. |
-| c64-provenance | Byte comparison of releases. |
-| c64-source | ACME source from the image and the knowledge, checked byte by byte, and a loader for the entry state. |
-| c64-assembler | ACME builds with diagnostics and symbols. |
-| c64-testing | Original-against-rebuild scenarios with PASS, FAIL or INCONCLUSIVE. |
-
-## Examples
+| c64-unpacker | Packing evidence, and capture of the unpacked program. |
+| c64-static-analysis | Analysis with DXA and Ghidra into the knowledge. |
+| c64-knowledge | Symbols, regions, comments and references, with history. |
+| c64-provenance | Compares releases, and keeps a library of shared routines. |
+| c64-source | ACME source from the knowledge, checked byte for byte. |
+| c64-docs | Documentation of a program from its knowledge and source. |
+| c64-reverse-engineering | Leads an investigation and picks the next skill. |
 
-Reverse engineering, from an unknown disk to a verified rebuild (the commands
-that the skills run for the agent; `<skills>` is the installed skills
-directory):
+## Settings
 
-```
-node <skills>/c64-disk/scripts/disk.ts directory original/game.d64
-node <skills>/c64-disk/scripts/disk.ts read original/game.d64 GAME --out extracted/game.prg
-node <skills>/c64-basic/scripts/basic.ts extracted/game.prg                  # the SYS address, e.g. $080d
-node <skills>/c64-unpacker/scripts/unpack.ts inspect extracted/game.prg
-node <skills>/c64-static-analysis/scripts/analyze.ts extracted/game.prg --analyzer dxa --listing analysis/game.lst
-node <skills>/c64-static-analysis/scripts/analyze.ts extracted/game.prg --entry '$080d'
-node <skills>/c64-knowledge/scripts/knowledge.ts rename '$080d' main --kind routine --reason 'entry from BASIC'
-node <skills>/c64-static-analysis/scripts/analyze.ts extracted/game.prg --entry '$080d' --decompile '$080d'
-node <skills>/c64-assembler/scripts/assemble.ts --source-root src --entry game.a --out build/game.prg > build/game.json
-node <skills>/c64-testing/scripts/test.ts tests/counts.json                   # PASS, FAIL or INCONCLUSIVE
-```
-
-Development: build with the c64-assembler skill, then load and debug with the
-MCP tools (`c64_program_load`, `c64_breakpoint`, `c64_run_until`,
-`c64_memory_read`, `c64_screen`), and test with the c64-testing skill.
+| Variable | Meaning |
+| --- | --- |
+| `C64RT_VICE`, `C64RT_C1541`, `C64RT_PETCAT` | Full path of the VICE tool, when it is not on `PATH` (host). |
+| `C64RT_ACME`, `C64RT_DXA` | Full path of the tool, when it is not on `PATH`. |
+| `C64RT_GHIDRA` | The Ghidra installation directory, when `analyzeHeadless` is not on `PATH`. |
+| `C64RT_HOST` | `host:port` of the Host Runtime, when it is not on 127.0.0.1, `host.docker.internal` or `host.containers.internal` at port 6464. |
+| `C64RT_VIDEO` | `pal` (default) or `ntsc`. |
+| `C64RT_TRACE` | A directory for a trace of a run. See [docs/debug-install.md](docs/debug-install.md). |
 
 ## Developing
 
-To work on the toolkit itself, Node 24 or newer and pnpm are required; install pnpm yourself (for example
-`corepack enable pnpm`). `packageManager` in `package.json` pins its version.
+To work on the toolkit itself you need Node 24 or newer and pnpm.
 
 ```
 pnpm install --frozen-lockfile
-pnpm typecheck     # tsc checks everything; it emits nothing
-pnpm test          # node --test on src/**/*.test.ts and test/**/*.test.ts
+pnpm typecheck
+pnpm test
+pnpm host          # the Host Runtime from this checkout
 ```
 
-Unit tests sit beside their source as `src/**/*.test.ts`; `test/` holds
-integration and end-to-end tests. Node runs the TypeScript directly (type
-stripping), so relative imports name the `.ts` file. Skill scripts import
-`src/` as `#src/...` (the `imports` map in `package.json`); an installed skill
-gets the `src/` modules it reaches and its own `package.json` with that map.
-
-Tests that need real tools are opt-in. Without them they are reported as
-skipped, never as passed:
+Tests that need real tools are skipped unless you turn them on:
 
 ```
 C64RT_LIVE_VICE=/usr/bin/x64sc C64RT_GHIDRA=/opt/ghidra pnpm test
 ```
 
-ACME, DXA, c1541 and petcat tests run when the tools are on `PATH`.
-
-To release, push a tag. See [docs/releasing.md](docs/releasing.md).
-
-## Layout
-
-```
-src/             # mcp, host, host-client, native, knowledge, cli; unit tests beside the source
-skills/          # the skills: SKILL.md, scripts (TypeScript) and references
-distribution/    # the AP SDK plugin definition: skills with the src/ modules they reach
-test/            # fixtures, integration and end-to-end tests
-docs/redesign/   # the design
-```
+To release, see [docs/releasing.md](docs/releasing.md).
 
 ## License
 
-MIT. See [`LICENSE`](./LICENSE).
+MIT. See [LICENSE](LICENSE).

package/package.json

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

@@ -13,9 +13,9 @@ This skill does not run the program and does not change project knowledge.
 
 ## Inputs
 
-- The source root: the project directory that holds all source files of the program.
+- The source root: the folder in the project that holds all source files of the program.
 - The entry source: the main file, relative to the source root.
-- The output path: where to write the PRG, relative to the project directory.
+- The output path: where to write the PRG, relative to the project folder.
 - Optional include directories, symbol definitions and a start address.
 
 ## Tools / execution path
@@ -31,20 +31,36 @@ 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. |
 
 The script copies the full source root. Put all files that the program includes under it. Version control directories stay out.
 
-The script prints one JSON object. The target CPU is the 6510 and the output is always a C64 PRG.
+The script prints one JSON object. The target CPU is the 6510. The output is a C64 PRG, or the bytes only with `--plain`.
+
+### Project folder
+
+- Paths are relative to the project folder. The project folder is the nearest folder at or above the working directory that holds `.c64-re-tools/`.
+- If the working directory is not in a project and has projects below it, the script refuses and lists them. Then give `--project <folder>` to each script.
+- Write each file that you make for your work in `.c64-re-tools/local/` of the project. Git ignores that folder. Examples are results, batches, step files, runs, snapshots and memory dumps.
+- Move a file out of `.c64-re-tools/local/` only when it is the evidence for a finding. Move it before you give it to `--evidence` of c64-knowledge. `--evidence` refuses a file in `.c64-re-tools/local/`.
+- Put a run that is evidence in `runs/<name>/`, with its run file, its results and the snapshot files that it uses. Change the paths in the run file to the new paths. Then git keeps them, and another person can do the run again.
+- A shell redirect (`>`) is relative to the working directory, not to the project folder. From the folder above the project, write `<folder>/.c64-re-tools/local/result.json`.
 
 ## Workflow
 
 1. Find the source root and the entry source. The entry source sets its own start address with `* = $0801` or similar.
 2. Run the script.
-3. If `assembled` is `true`, the PRG is at `output`. `loadRange` tells where it loads. `symbols` gives each symbol as an `address` or a `value`.
+3. If `assembled` is `true`, the PRG is at `output`. `loadRange` tells where it loads. `symbols` gives each symbol:
+   - Kind `address` has a value in `loadRange`. It gives the `address`.
+   - Kind `constant` has a value outside `loadRange`. It gives the `value` as `$` and four or more hex digits. A label in a `!pseudopc` block can be a constant, because its value is the run address, not the load address.
+   - `used` is `false` when the source does not use the symbol.
 4. If `assembled` is `false`, read `diagnostics`. Each one has a severity, a file, a line and a message. Correct the source and run the script again.
 5. To run the program, give the PRG path to the c64-emulator skill.
 
+The source of the c64-source skill has switches. Each switch is 0 when the build does not define it. `--define CRACK=1` puts in the patches of the switch `CRACK`. With `--compare`, only the bytes of those patches are different.
+
 ## Knowledge
 
 Automatic write:
@@ -60,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

@@ -12,20 +12,28 @@ import { localToolContext } from "#src/native/local.ts";
 import type { AcmeParams } from "#src/native/types.ts";
 import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
-import { compareBuild } from "./compare.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]
 
-  --source-root <dir>      project directory to assemble from; all of it is sent
+  --source-root <dir>      folder in the project to assemble from; all of it is sent
   --entry <file>           the main source file, relative to the source root
   --out <file.prg>         where to write the program, relative to the project
   --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, 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
 
-The result is one JSON object. Addresses are $ and four hex digits.`;
+The result is one JSON object. Addresses and symbol values are $ and at least four hex digits.`;
 
 function parseDefine(text: string): [string, number | boolean] {
   const match = /^([A-Za-z_][A-Za-z0-9_]*)=(.+)$/.exec(text);
@@ -48,7 +56,10 @@ 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" },
     },
   });
@@ -61,7 +72,20 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
   try {
     outPath = resolveProjectPath(out);
   } catch {
-    throw new UsageError(`--out must be a path relative to the project directory that stays inside it, not ${out}`);
+    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;
@@ -79,19 +103,23 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
   const { result, attachments } = await assemble(params, tree.contents, localToolContext());
   if (!result.assembled) return { output: { assembled: false, diagnostics: result.diagnostics }, failed: true };
   mkdirSync(dirname(outPath), { recursive: true });
-  writeFileSync(outPath, attachments![0]!);
+  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 {
     output: {
       assembled: true,
       output: out,
+      ...(values.plain ? { plain: true } : {}),
       loadRange: { start: formatC64Address(range.start), end: formatC64Address(range.end), bytes: range.bytes },
-      symbols: result.symbols!.map((symbol) =>
+      symbols: listed.map((symbol) =>
         symbol.kind === "address"
           ? { name: symbol.name, kind: "address", address: formatC64Address(symbol.address), used: symbol.used }
-          : { name: symbol.name, kind: "constant", value: symbol.value, used: symbol.used },
+          : { name: symbol.name, kind: "constant", value: `$${symbol.value.toString(16).padStart(4, "0")}`, used: symbol.used },
       ),
+      ...(values["all-symbols"] ? {} : { unusedConstants: result.symbols!.length - listed.length }),
       diagnostics: result.diagnostics,
       ...(compared === undefined ? {} : { compare: compared }),
     },
@@ -101,10 +129,10 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
 }
 
 await runScript(
-  async () => {
-    const { output, failed } = await run(process.argv.slice(2));
+  async (argv) => {
+    const { output, failed } = await run(argv);
     if (failed) process.exitCode = 1;
     return output;
   },
-  { usage: USAGE },
+  { usage: USAGE, refusals: [KnowledgeError] },
 );

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

@@ -0,0 +1,48 @@
+// The byte check of a build: the assembled program against the program
+// in the knowledge, segment by segment.
+
+import { formatC64Address, prgRange } from "#src/c64.ts";
+
+export interface SegmentCheck {
+  start: string;
+  end: string;
+  result: "identical" | "different" | "not covered";
+  /** Bytes of the segment that the build does not hold. */
+  uncovered?: number;
+  differences?: number;
+  firstDifference?: { address: string; built: number; reference: number };
+}
+
+/** 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, program: Reference): { identical: boolean; segments: SegmentCheck[] } {
+  const built = prgRange(prg);
+  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) };
+    if (from > to) return { ...shown, result: "not covered", uncovered: segment.end - segment.start + 1 };
+    let differences = 0;
+    let first: SegmentCheck["firstDifference"];
+    for (let address = from; address <= to; address++) {
+      const builtByte = built.body[address - built.start]!;
+      const referenceByte = program.byteAt(address);
+      if (builtByte === referenceByte) continue;
+      differences++;
+      first ??= { address: formatC64Address(address), built: builtByte, reference: referenceByte };
+    }
+    const uncovered = segment.end - segment.start + 1 - (to - from + 1);
+    return {
+      ...shown,
+      result: differences > 0 ? "different" : uncovered > 0 ? "not covered" : "identical",
+      ...(uncovered > 0 ? { uncovered } : {}),
+      ...(differences > 0 ? { differences, firstDifference: first! } : {}),
+    };
+  });
+  return { identical: checks.every((check) => check.result === "identical"), segments: checks };
+}

package/skills/c64-basic/SKILL.md

@@ -13,7 +13,7 @@ This skill does not run the program and does not change project knowledge.
 
 ## Inputs
 
-- The program: a PRG file, relative to the project directory.
+- The program: a PRG file, relative to the project folder.
 
 ## Tools / execution path
 
@@ -25,6 +25,15 @@ node <skill>/scripts/basic.ts extracted/game.prg
 
 The script prints one JSON object. Addresses are `$` and four hex digits.
 
+### Project folder
+
+- Paths are relative to the project folder. The project folder is the nearest folder at or above the working directory that holds `.c64-re-tools/`.
+- If the working directory is not in a project and has projects below it, the script refuses and lists them. Then give `--project <folder>` to each script.
+- Write each file that you make for your work in `.c64-re-tools/local/` of the project. Git ignores that folder. Examples are results, batches, step files, runs, snapshots and memory dumps.
+- Move a file out of `.c64-re-tools/local/` only when it is the evidence for a finding. Move it before you give it to `--evidence` of c64-knowledge. `--evidence` refuses a file in `.c64-re-tools/local/`.
+- Put a run that is evidence in `runs/<name>/`, with its run file, its results and the snapshot files that it uses. Change the paths in the run file to the new paths. Then git keeps them, and another person can do the run again.
+- A shell redirect (`>`) is relative to the working directory, not to the project folder. From the folder above the project, write `<folder>/.c64-re-tools/local/result.json`.
+
 ## Workflow
 
 1. Run the script on the program.

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

@@ -11,7 +11,7 @@ import { runScript, UsageError } from "#src/script.ts";
 
 const USAGE = `basic.ts <program>
 
-<program> is a PRG file relative to the project directory. The result is one
+<program> is a PRG file relative to the project folder. The result is one
 JSON object. Addresses are $ and four hex digits.`;
 
 async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }> {
@@ -37,8 +37,8 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
 }
 
 await runScript(
-  async () => {
-    const { output, failed } = await run(process.argv.slice(2));
+  async (argv) => {
+    const { output, failed } = await run(argv);
     if (failed) process.exitCode = 1;
     return output;
   },

package/skills/c64-disk/SKILL.md

@@ -13,10 +13,10 @@ This skill does not change the disk image and does not change project knowledge.
 
 ## Inputs
 
-- The disk image: a `.d64`, `.d71`, `.d81` or `.g64` file, relative to the project directory.
+- The disk image: a `.d64`, `.d71`, `.d81` or `.g64` file, relative to the project folder.
 - For one file: the file name as the directory shows it.
-- To extract a file: the output path, relative to the project directory.
-- A T64 tape file or a CRT cartridge file, relative to the project directory.
+- To extract a file: the output path, relative to the project folder.
+- A T64 tape file or a CRT cartridge file, relative to the project folder.
 
 ## Tools / execution path
 
@@ -40,7 +40,16 @@ node <skill>/scripts/disk.ts <action> <image> [name] [--out <file>]
 
 The script prints one JSON object.
 
-File names show the characters that the C64 shows in a directory list. A byte that has no character shows as `{$xx}`, for example `{$c1}`. Write the name in the same form. The letter case of a name is not important. Put the name in single quotes in a shell, for example `'GAME {$c1}'`.
+File names show the characters that the C64 shows in a directory list. A byte that has no character shows as `{$xx}`, for example `{$c1}`. Write the name in the same form. The letter case of a name is not important. Put the name in single quotes in a shell, for example `'GAME {$c1}'`. A name that starts with `-` needs `--` before it, after all options, for example `read d.d64 --out x.prg -- '-----'`.
+
+### Project folder
+
+- Paths are relative to the project folder. The project folder is the nearest folder at or above the working directory that holds `.c64-re-tools/`.
+- If the working directory is not in a project and has projects below it, the script refuses and lists them. Then give `--project <folder>` to each script.
+- Write each file that you make for your work in `.c64-re-tools/local/` of the project. Git ignores that folder. Examples are results, batches, step files, runs, snapshots and memory dumps.
+- Move a file out of `.c64-re-tools/local/` only when it is the evidence for a finding. Move it before you give it to `--evidence` of c64-knowledge. `--evidence` refuses a file in `.c64-re-tools/local/`.
+- Put a run that is evidence in `runs/<name>/`, with its run file, its results and the snapshot files that it uses. Change the paths in the run file to the new paths. Then git keeps them, and another person can do the run again.
+- A shell redirect (`>`) is relative to the working directory, not to the project folder. From the folder above the project, write `<folder>/.c64-re-tools/local/result.json`.
 
 ## Workflow