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

package/README.md

@@ -12,78 +12,51 @@ 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`.
+run ACME, DXA and Ghidra themselves, and keep project knowledge local as
+text in `.c64-re-tools/knowledge/`.
 The design is in [`docs/redesign/`](docs/redesign/README.md), and
 [`docs/plan.md`](docs/plan.md) tracks the implementation.
 
-## Install and start
+## Install
 
-Requirements:
+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.
 
-- Node.js 24 or newer with npx.
-- On the machine with VICE: VICE 3.9 or later (`x64sc`, `c1541`, `petcat`) with its ROM files.
-- Where the agent runs: ACME, DXA and Ghidra, for the skills that use them.
-
-Everything runs through npx. Nothing is installed globally.
-
-### Release or prerelease
-
-| Channel | Version |
-| --- | --- |
-| `latest` | The current release. |
-| `next` | The current prerelease, for example `2.0.0-rc.1`. |
-
-Until 2.0.0 is released, `latest` is the old 1.1.0. Use `next` until then. In the commands below, replace `<channel>` with `latest` or `next`. Use the same channel on both machines.
-
-### On one machine
-
-Start the Host Runtime in its own terminal. Ctrl+C stops it and every emulator:
+Start the Host Runtime and leave it running:
 
 ```
-npx -y --package=@henols/c64-re-tools@<channel> c64-re-tools-host
+npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host
 ```
 
-Install into the project, check it, and start the agent:
+The host logs each call from a skill script. Add `--log-console` to print also each MCP call and each c1541 or petcat run, or `--log-dir <directory>` to write them to a file. Both are off by default.
+
+Install into your project and start the agent:
 
 ```
 cd my-c64-project
-npx -y @henols/c64-re-tools@<channel> install --target claude
-npx -y @henols/c64-re-tools@<channel> status
+npx -y @henols/c64-re-tools@latest install --target claude
 claude
 ```
 
-### In a dev container
+Several programs in one repository: install once at the root, give each program its own folder, and start the agent at the root. A folder with `.c64-re-tools/` is a project; the agent names one with `--project <folder>`.
 
-On the host, start the Host Runtime on the container bridge with a shared secret:
+`npx -y @henols/c64-re-tools@latest status` shows what works.
 
-```
-export C64RT_HOST_TOKEN=$(openssl rand -hex 16)
-npx -y --package=@henols/c64-re-tools@<channel> c64-re-tools-host --listen 172.17.0.1
-```
+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).
 
-In the container, set the same `C64RT_HOST_TOKEN`, then:
+### Dev container
 
-```
-npx -y @henols/c64-re-tools@<channel> install --target claude
-npx -y @henols/c64-re-tools@<channel> status
-claude
-```
-
-The container reaches the host as `host.docker.internal`. `status` must show the Host Runtime as reachable.
+The agent runs in the container, VICE and the Host Runtime on the host. In `.devcontainer/devcontainer.json`:
 
-### Update and remove
-
-```
-npx -y @henols/c64-re-tools@<channel> update      # the newest skills into the project
-npx -y @henols/c64-re-tools@<channel> uninstall
+```json
+"features": {
+  "https://github.com/henols/c64-re-tools/releases/latest/download/devcontainer-feature-c64-re-tools.tgz": { "target": "claude" }
+},
+"runArgs": ["--add-host=host.docker.internal:host-gateway"]
 ```
 
-Restart the Host Runtime after a new release. `--global` installs into your home directory.
+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" }`.
 
-### Debugging
-
-See [docs/debugging.md](docs/debugging.md) for the trace and the field test.
+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.
 
 ### Settings
 
@@ -94,9 +67,8 @@ See [docs/debugging.md](docs/debugging.md) for the trace and the field test.
 | `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_HOST_TOKEN` | host, MCP, skills, CLI | The shared secret for a Host Runtime that listens beyond loopback. |
 | `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/debugging.md](docs/debugging.md). Nothing of the trace reaches the agent. |
+| `C64RT_TRACE` | 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. The host uses `--log-dir` instead. |
 
 Ghidra runs with its own settings directory for each request. The toolkit
 brings its own NMOS 6510 language (all 256 opcodes); your Ghidra installation
@@ -106,7 +78,7 @@ and settings stay unchanged.
 
 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.
+3. Start the harness in the project (or at the root of a repository with several projects), 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.
 
 Examples:
@@ -123,7 +95,7 @@ Build it, run it in the emulator, and write a test for it.
 Show me the emulator window.
 ```
 
-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 the program as text in `.c64-re-tools/knowledge/`. Commit that folder with the project. After a `git pull` that joined the work of two computers, run `knowledge.ts merge` when a command reports conflicts.
 
 ## Skills
 
@@ -137,7 +109,8 @@ The agent keeps what it learns about the program in `.c64-re-tools/knowledge.db`
 | 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-provenance | Byte comparison of releases, and a library of routines that several programs share. |
+| 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. |
 
@@ -190,14 +163,7 @@ 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 on a commit of `main`. The tag gives the version:
-
-```
-git tag v2.0.0-rc.2 && git push origin v2.0.0-rc.2   # a prerelease, to npm next
-git tag v2.0.0      && git push origin v2.0.0        # a release, to npm latest
-```
-
-CI checks and tests the tagged commit, publishes it to npm and makes a GitHub Release. The repository keeps the version `0.0.0-development`.
+To release, push a tag. See [docs/releasing.md](docs/releasing.md).
 
 ## Layout
 

package/distribution/package.ts

@@ -2,22 +2,7 @@
 // only reads package.json, so a caller that needs the declaration does not
 // build the plugin.
 
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-
-/**
- * The npm dist-tag that a version is published under: a prerelease
- * (2.0.0-rc.1) goes to "next", a release to "latest".
- */
-export function channelOf(version: string): "latest" | "next" {
-  return version.includes("-") ? "next" : "latest";
-}
-
-/** The name, version and dist-tag of this npm package, from its package.json. */
-export const PACKAGE = (() => {
-  const metadata = JSON.parse(readFileSync(join(import.meta.dirname, "..", "package.json"), "utf8")) as { name: string; version: string };
-  return { name: metadata.name, version: metadata.version, tag: channelOf(metadata.version) };
-})();
+import { PACKAGE } from "../src/package.ts";
 
 /**
  * The agent starts the MCP server through npx with the newest version of the

package/distribution/plugin.ts

@@ -13,7 +13,8 @@ import { dirname, join, relative, resolve, sep } from "node:path";
 
 import { definePlugin, defineSkill, type Skill } from "@jalco/ap-sdk";
 
-import { MCP_SERVER, PACKAGE } from "./package.ts";
+import { PACKAGE } from "../src/package.ts";
+import { MCP_SERVER } from "./package.ts";
 
 const root = resolve(import.meta.dirname, "..");
 const SOURCE = join(root, "src");
@@ -27,9 +28,10 @@ const SPECIFIER = /(?:\bfrom\s*|\bimport\s*\(?\s*|\bnew URL\(\s*)(["'])((?:\.\.?
 
 /**
  * The package.json of an installed skill: ES modules, #src/* resolved inside
- * the skill, and the version of c64-re-tools that the copy comes from.
+ * the skill, and the name and version of c64-re-tools that the copy comes
+ * from, which src/package.ts reads.
  */
-export const SKILL_PACKAGE = `${JSON.stringify({ type: "module", version: PACKAGE.version, imports: { "#src/*": "./src/*" } }, null, 2)}\n`;
+export const SKILL_PACKAGE = `${JSON.stringify({ name: PACKAGE.name, type: "module", version: PACKAGE.version, imports: { "#src/*": "./src/*" } }, null, 2)}\n`;
 
 /** The scripts that a SKILL.md runs, by file name. */
 export function scriptsOf(skillMarkdown: string): string[] {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/c64-re-tools",
-  "version": "2.0.0-rc.2",
+  "version": "2.0.0-rc.21",
   "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,19 +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` | 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:
@@ -59,12 +76,14 @@ 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.
 
-The exit status is 0 for a PRG. The exit status is 1 for `assembled: false` and for an error. The exit status is 2 for a wrong argument.
+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.
 
 ## Failure and conflicts
 
 - `assembled: false`: the source has errors. This is a normal result. Correct the source.
-- `installation-incomplete`: ACME is not installed on this machine. Tell the user the message.
+- `installation-incomplete`, or `machine-unavailable` with a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
 - `invalid-input`: an option or a path is wrong. Read the message and correct the call.
 
 ## Handoffs

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

@@ -12,17 +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 "./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                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
 
-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);
@@ -45,6 +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: "boolean" },
+      space: { type: "string" },
+      plain: { type: "boolean" },
+      "all-symbols": { type: "boolean" },
       help: { type: "boolean" },
     },
   });
@@ -57,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;
@@ -75,29 +103,36 @@ 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 = 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 }),
     },
-    failed: false,
+    // A build that differs from its reference is a failed check.
+    failed: compared !== undefined && !compared.identical,
   };
 }
 
 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 (D47): the assembled program against the program
+// in the knowledge (D83), 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,14 +25,23 @@ 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.
 2. Read `listing`. Each line starts with its BASIC line number. Keywords show in lower case. Control characters in strings show in braces, for example `{clr}`.
 3. Read `handoffs`. Each handoff has a `kind` (`sys` or `usr`) and the BASIC `line`.
-   - A `sys` handoff with an `address`: BASIC calls the machine code at that address.
-   - A handoff with `computed: true`: the address comes from a calculation at run time. Use the c64-emulator skill to find the address.
-4. Compare the address with `loadRange` and `basicEnd`. From `basicEnd` to the end of `loadRange`, the file holds bytes that are not BASIC. Usually this is the machine code that the handoff calls.
+   - A `sys` handoff with an `address`: BASIC calls the machine code at that address. The script calculates a SYS argument with numbers, π, `+`, `-`, `*`, `/` and brackets. For example, `SYS π*656` calls `$080c`.
+   - A handoff with `computed: true`: the address comes from a calculation at run time, for example with `PEEK`. A `sys` handoff gives its argument in `expression`. Use the c64-emulator skill to find the address.
+4. Compare the address with `loadRange` and `basicEnd`. From `basicEnd` to the end of `loadRange`, the file holds bytes that are not BASIC. Usually this is the machine code that the handoff calls. Some programs have no end marker (two zero bytes) after the last line. The machine code starts directly after the last line. Then `basicEnd` is the first byte of that machine code.
 
 The address ranges are for a load to the load address of the file. A load without `,1` puts a BASIC program at `$0801`. Most loaders have `$0801` as their load address.
 
@@ -54,10 +63,9 @@ The exit status is 0 for a listing. The exit status is 1 for `decoded: false` an
 
 ## Failure and conflicts
 
-- `decoded: false`: the file is not a BASIC program. This is a normal result. Usually the file is machine code. Give it to the c64-static-analysis skill.
+- `decoded: false`: the file is not a BASIC program. This is a normal result. Usually the file is machine code. Give it to the c64-static-analysis skill. A memory dump also gives `decoded: false`: its first two bytes are not a load address, and its bytes go past `$ffff`.
 - An empty `handoffs` list: the BASIC does not start machine code with SYS or USR. Do not make up a handoff. Look for a POKE into a vector or a LOAD of another file in the listing.
-- `installation-incomplete`: petcat is not on the host. Tell the user the message.
-- `operation-failed` with a message about the host runtime: the host runtime does not run. Tell the user to start the host runtime with `npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host`.
+- `installation-incomplete`, or `machine-unavailable` with a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
 - `not-found` or `invalid-input`: the path or an argument is wrong. Read the message and correct the call.
 
 ## Handoffs

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 }> {
@@ -22,7 +22,7 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
   const result = await decodeBasic({ program });
   if (!result.decoded) return { output: { decoded: false, reason: result.reason }, failed: true };
   const size = statSync(resolveProjectPath(program)).size - 2;
-  const end = Math.min(0xffff, result.loadAddress + size - 1);
+  const end = result.loadAddress + size - 1;
   return {
     output: {
       decoded: true,
@@ -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

@@ -1,25 +1,26 @@
 ---
 name: c64-disk
-description: Use this skill to examine a C64 disk image (D64, D71, D81 or G64) and to extract files from it into the project. It shows the directory, the BAM, the directory entry of a file and the sector chain of a file. Do not use it to run a program or to decode BASIC. Give an extracted file to the c64-basic, c64-unpacker or c64-static-analysis skill.
+description: Use this skill to examine a C64 disk image (D64, D71, D81 or G64), a T64 tape file or a CRT cartridge file. It extracts files into the project. It shows the directory, the BAM, the directory entry of a file and the sector chain of a file. It writes each bank of a cartridge as a PRG. Do not use it to run a program or to decode BASIC. Give an extracted file to the c64-basic, c64-unpacker or c64-static-analysis skill.
 ---
 
 # c64-disk
 
 ## Purpose
 
-Examine a C64 disk image. Extract a file from the image into the project.
+Examine a C64 disk image, a T64 tape file or a CRT cartridge file. Extract a file from it into the project.
 
 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.
+- 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
 
-The script sends the image to the host runtime. The host runs c1541 and sends the result back. The script writes an extracted file into the project.
+The script sends a disk image to the host runtime. The host runs c1541 and sends the result back. The script writes an extracted file into the project. It reads T64 and CRT files itself.
 
 ```
 node <skill>/scripts/disk.ts <action> <image> [name] [--out <file>]
@@ -28,21 +29,34 @@ node <skill>/scripts/disk.ts <action> <image> [name] [--out <file>]
 | Need | Command |
 |---|---|
 | The disk name, the free blocks and the files | `directory original/game.d64` |
-| The free and used sectors of each track | `bam original/game.d64` |
+| The free and used sectors of each track, and the used sectors that no file uses | `bam original/game.d64` |
 | The type, size and first block of one file | `entry original/game.d64 GAME` |
 | The track and sector of each block of one file | `chain original/game.d64 GAME` |
 | Extract one file | `read original/game.d64 GAME --out extracted/game.prg` |
+| The files of a tape | `directory original/game.t64` |
+| Extract one file of a tape | `read original/game.t64 GAME --out extracted/game.prg` |
+| The banks of a cartridge | `directory original/game.crt` |
+| Write each bank of a cartridge as a PRG | `crt original/game.crt --out cart` |
 
 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
 
 1. Run `directory`. Find the file in `entries`. Each entry has a `name`, a `type`, a size in `blocks` and the `closed` and `locked` flags.
 2. Run `read` with an output path to extract the file. A PRG file keeps its 2-byte load address at the start.
 3. Run `entry` or `chain` only when the disk structure is important, for example for a loader that reads sectors directly.
-4. Run `bam` only to find used sectors that no file uses.
+4. Run `bam` only to find used sectors that no file uses. `unreferenced` lists them. The list does not include the header, the directory and the BAM blocks. These sectors can hold data that a loader reads directly.
 
 ## Knowledge
 
@@ -55,6 +69,15 @@ Do not store:
 
 A downstream skill records the meaning of the extracted content.
 
+## Tapes and cartridges
+
+The script reads T64 and CRT files itself. The host runtime is not necessary for them.
+
+- T64: `directory` and `read`. Many T64 files have a wrong end address. Then the entry has `fixedSize: true`, and the size comes from the position of the next file.
+- CRT: `directory` and `crt`. The script reads hardware types 0 (normal 8K, 16K or Ultimax), 5 (Ocean), 19 (Magic Desk) and 32 (EasyFlash). It refuses other types by name. `crt` writes `crt.json` and one PRG for each CHIP packet, for example `bank3-8000.prg`.
+- A cartridge bank uses the same addresses as other banks. Analyze each bank PRG with c64-static-analysis and `--space bank3`, and record its knowledge in space `bank3`.
+- TAP: a TAP file holds tape signals, and turbo loaders have their own formats. The script does not read it. Start it with the c64-emulator skill, or capture its parts with `loads` of the c64-unpacker skill.
+
 ## Result
 
 The directory, the BAM, an entry or a sector chain as JSON. Or the extracted file in the project at the output path.
@@ -65,8 +88,7 @@ The exit status is 0 for a result with the file. The exit status is 1 for `found
 
 - `found: false`: the image has no file with that name. This is a normal result. Read the directory again and compare the names.
 - `media-error`: the image has a defect or is not a disk image. The message tells the problem, for example a sector chain that loops. Tell the user. Do not change the image.
-- `installation-incomplete`: c1541 is not on the host. Tell the user the message.
-- `operation-failed` with a message about the host runtime: the host runtime does not run. Tell the user to start the host runtime with `npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host`.
+- `installation-incomplete`, or `machine-unavailable` with a message that the host runtime does not run: stop the task. Give the message to the user and wait for the user. The message gives the remedy. Do not make a replacement for the tool or the host runtime, for example your own disk parser, disassembler or emulator script.
 - `invalid-input`: an argument or a path is wrong. Read the message and correct the call.
 
 A file that is not `closed` was not written fully. Its data can be incomplete.
@@ -75,5 +97,6 @@ A file that is not `closed` was not written fully. Its data can be incomplete.
 
 - BASIC program → c64-basic
 - Packed program → c64-unpacker
-- Machine code → c64-static-analysis
+- Machine code, also a cartridge bank → c64-static-analysis
+- A TAP file → c64-unpacker
 - Run the program → c64-emulator