@henols/c64-re-tools 2.0.0-rc.10 → 2.0.0-rc.12

package/README.md

@@ -12,8 +12,8 @@ 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.
 
@@ -37,6 +37,8 @@ npx -y @henols/c64-re-tools@latest install --target claude
 claude
 ```
 
+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>`.
+
 `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).
@@ -76,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:
@@ -93,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
 
@@ -107,7 +109,7 @@ 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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henols/c64-re-tools",
-  "version": "2.0.0-rc.10",
+  "version": "2.0.0-rc.12",
   "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
@@ -37,6 +37,13 @@ The script copies the full source root. Put all files that the program includes
 
 The script prints one JSON object. The target CPU is the 6510 and the output is always a C64 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.
+- Keep the results, batches and step files that you save for yourself in `.c64-re-tools/local/` of the project. Git ignores that folder.
+- 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.

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

@@ -16,7 +16,7 @@ import { compareBuild } from "./compare.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)
@@ -61,7 +61,7 @@ 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}`);
   }
   const defines = Object.fromEntries((values.define ?? []).map(parseDefine));
   let setPc: number | undefined;
@@ -101,8 +101,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-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,13 @@ 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.
+- Keep the results, batches and step files that you save for yourself in `.c64-re-tools/local/` of the project. Git ignores that folder.
+- 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
 
@@ -42,6 +42,13 @@ 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}'`.
 
+### 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.
+- Keep the results, batches and step files that you save for yourself in `.c64-re-tools/local/` of the project. Git ignores that folder.
+- 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.

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

@@ -23,7 +23,7 @@ const USAGE = `disk.ts <action> <image> [name] [--out <file>]
   read <image> <name> --out <file>  write the bytes of one file into the project
   crt <file.crt> --out <dir>        write each CHIP packet of a cartridge as a PRG
 
-<image> is a .d64, .d71, .d81 or .g64 file, relative to the project directory.
+<image> is a .d64, .d71, .d81 or .g64 file, relative to the project folder.
 directory and read also take a .t64 tape file, and directory a .crt cartridge
 file; the script reads those itself. A CRT can have hardware type 0 (normal
 8K, 16K or Ultimax), 5 (Ocean), 19 (Magic Desk) or 32 (EasyFlash).
@@ -49,7 +49,7 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
     try {
       outPath = resolveProjectPath(values.out);
     } catch {
-      throw new UsageError(`--out must be a path relative to the project directory that stays inside it, not ${values.out}`);
+      throw new UsageError(`--out must be a path relative to the project folder that stays inside it, not ${values.out}`);
     }
   }
 
@@ -111,8 +111,8 @@ function local(kind: "t64" | "crt", action: Action, image: string, name: string
 }
 
 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-emulator/SKILL.md

@@ -52,6 +52,10 @@ For a large result, give `out` with a path in the project. `c64_memory_read`, `c
 
 `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.
 
+### Project folder
+
+Paths (`path`, `file` and `out`) are relative to the project folder. A project folder holds `.c64-re-tools/`. The tools use the nearest project folder at or above the folder where the agent started. If that folder is not in a project and has projects below it, a tool with a path refuses and lists them. Then give `project` with the project folder, for example `"project": "game"`. Give the same folder as the `--project` of the skill scripts. A tool without a path does not need `project`.
+
 ## Workflow
 
 1. Read the project knowledge for the addresses in the question. Use the c64-knowledge skill.

package/skills/c64-knowledge/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: c64-knowledge
-description: Use this skill to read, write, correct and review the durable knowledge of a C64 project in .c64-re-tools/knowledge.db. It gives the knowledge at an address, and it names symbols, classifies memory regions, sets comments and records references. It also shows the history of each change, and it can revert to an earlier revision. Do not use it for live emulator state or for static analysis.
+description: Use this skill to read, write, correct and review the durable knowledge of a C64 project in .c64-re-tools/knowledge/. It gives the knowledge at an address, and it names symbols, classifies memory regions, sets comments and records references. It also shows the history of each change, and it can revert to an earlier revision. Do not use it for live emulator state or for static analysis.
 ---
 
 # c64-knowledge
 
 ## Purpose
 
-Read, write, correct and review the durable understanding of a C64 project. The knowledge is in `.c64-re-tools/knowledge.db` in the project directory. Git can version that file.
+Read, write, correct and review the durable understanding of a C64 project. The knowledge is text in `.c64-re-tools/knowledge/` in the project folder: one JSON line for each row. Commit that folder with git. The script keeps an index of the text in `.c64-re-tools/local/knowledge.db` and makes the index again when the text changes. Do not commit the index.
 
 This skill is the only write path for conclusions of the user and the LLM. It does not run an emulator or an analyzer.
 
@@ -22,8 +22,6 @@ One of these:
 
 ## Tools / execution path
 
-Run the script in the project directory. The project directory is the directory that the harness started in.
-
 ```
 node <skill>/scripts/knowledge.ts <command> [arguments] [options]
 ```
@@ -41,20 +39,25 @@ The script prints one JSON object. An error prints `{"error": {"code": ..., "mes
 | Remove a symbol | `remove-symbol '$2100'` |
 | Classify memory | `classify '$3000' '$303f' sprite` |
 | Classify a table of records | `classify '$3000' '$303b' bytes --element 6` |
-| Many writes as one revision | `apply batch.json`, or `apply -` with the JSON on standard input |
+| Many writes as one revision | `apply -` with the JSON on standard input, or `apply <file>` |
 | Make memory unknown, and keep the analyzers out of it | `unclassify '$3000' '$303f'` |
 | Set or remove a comment | `comment '$2100' line Reads joystick 2.` / `uncomment '$2100' line` |
 | Add or remove a reference | `reference '$2000' '$2100' call` / `unreference ...` |
 | Places that a removal blocks | `suppressions` with `--start` and `--end` |
 | Start a file of generated source | `module '$2000' player.asm --title 'Player movement'` / `unmodule '$2000'` |
+| Write the operand of an instruction as an expression | `operand '$8079' --lo irq_handler --image unpacked/image.json` / `unoperand '$8079'` |
+| Operand expressions | `operands` with `--start` and `--end` |
 | Files of generated source | `modules` |
 | The address spaces that hold knowledge | `spaces` |
-| History | `history '$2100'`, `history --name update_player`, `revisions`, `revision 12` |
-| Go back to an earlier state | `revert 12` |
+| History | `history '$2100'`, `history --name update_player`, `revisions`, `revision 20261015T2145` |
+| Go back to an earlier state | `revert 20261015T2145` |
+| Decide the conflicts after a git merge | `merge --reason 'merge of two computers'` |
+
+A revision has an id such as `20261015T214501.123-k3f9qz`. The id starts with the date and time. A command takes the full id, or a start of the id that only one revision has. The revision `0` is the knowledge before the first revision.
 
 Every command takes `--space`: `c64` (the default), `drive8` for code in the 1541 drive, or `bank0` to `bank255` for cartridge banks. Drive code and banks use the same addresses as the C64, so each space has its own knowledge. A name is unique inside one space. In a batch, a write can name its own `space`.
 
-Symbol kinds are `label`, `routine`, `variable`, `data` and `vector`. Reference kinds are `call`, `jump`, `read`, `write` and `reference`.
+Symbol kinds are `label`, `routine`, `variable`, `data` and `vector`. Reference kinds are `call`, `jump`, `read`, `write`, `reference` and `pointer`. Only an operand expression writes a `pointer` reference.
 
 Region types:
 
@@ -71,6 +74,13 @@ Region types:
 
 `--element` gives the bytes of one element of a table. The length of the region must be a multiple of it. The result shows `element` and `count`.
 
+### 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.
+- Keep the results, batches and step files that you save for yourself in `.c64-re-tools/local/` of the project. Git ignores that folder.
+- 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
 
 Read:
@@ -87,7 +97,7 @@ Write:
 
 Each write is one revision. A classification inside a region splits that region, so regions never overlap.
 
-For more than a few writes, put them in one JSON file and use `apply`. The file is a list of writes. Each write has `op` and the arguments of the command with the same name, for example:
+For more than a few writes, use `apply -` and give the writes on standard input as one JSON list. Each write has `op` and the arguments of the command with the same name, for example:
 
 ```json
 [
@@ -110,13 +120,39 @@ The ops and their fields:
 | `reference`, `unreference` | `from`, `to`, `kind` |
 | `module` | `start`, `file`, `title` (optional) |
 | `unmodule` | `start` |
+| `operand` | `address`, `select` (`lo`, `hi`, `value` or `expr`), `symbol` and `offset` (optional), or `expression` for `expr` |
+| `unoperand` | `address` |
 
 A `line` comment is a line of its own above the address. A `side` comment is at the end of the line of the address. All writes become one revision. If the knowledge refuses one write, the script writes nothing, and the error names the write.
 
+The c64-provenance skill writes a batch with `match --out`. The batch holds the names of library routines at their addresses in this program. Read the `batch.leftOut` of its result first. Then apply the batch with the command in its `apply`.
+
 ## Modules
 
 A module tells the c64-source skill where a file of the generated source starts. The file runs to the next module or to the end of its segment. Each address has one module, and each file name has one module. A file name has letters, digits, underscores or hyphens, and ends in `.asm`. The c64-source skill writes `main.asm`, `loader.asm` and `constants.asm` itself. Thus a module cannot have one of these names, in upper or lower case. The title becomes the first line of the file. A `module` write without a title keeps the title that the module has. Modules have a history, and `revert` restores them.
 
+## Operand expressions
+
+An operand expression tells the c64-source skill how to write the operand of one instruction. The source then has a name, not a number. When code or data changes its length, the operand follows the address that moved.
+
+Give one selector:
+
+| Option | Operand | Source |
+|---|---|---|
+| `--lo <symbol>` | The low byte of the symbol plus the offset | `lda #<irq_handler` |
+| `--hi <symbol>` | The high byte of the symbol plus the offset | `lda #>(sprite_bank+$1000)` |
+| `--value <symbol>` | The symbol plus the offset | `lda bar_colours-1,x` |
+| `--expr <text>` | ACME expression text with names and numbers | `lda #(sprite_bank + 5*64) / 64` |
+
+- `--offset` adds a whole number to the symbol. Write a negative offset as `--offset=-1`.
+- A name is a symbol of the knowledge or a platform name of the c64-memory-map skill.
+- `--expr` takes `$`, `%` and decimal numbers, names, brackets, the operators `+ - * / % << >> >>> & | XOR`, and `<`, `>`, `-` and `!` before an operand.
+- The script compares the value of the expression with the operand in the image. If they are not equal, the script refuses the write. Give the image with `--image`: an `image.json` of the c64-unpacker skill or a PRG. `apply` with an `operand` write also needs `--image`.
+- Each name in the expression gets a `pointer` reference from the instruction. Thus `at` on the named address shows the code that uses the address.
+- A `rename` of a symbol changes the name in each expression. The knowledge refuses `remove-symbol` while an expression uses the symbol. Use `unoperand` first.
+
+Write an operand expression for each immediate that is a byte of an address. Also write one for each table read through the byte before the table. The pointer candidates of the c64-static-analysis skill show many of these places.
+
 ## Removals
 
 `remove-symbol`, `unclassify` and `unreference` block the place for DXA and Ghidra. An analysis does not add a symbol at that address, a region in that range or that reference again. This applies to every removed fact, also to a fact from the LLM.
@@ -146,7 +182,7 @@ The script records the origin `llm`. Use `--origin user` only when the user deci
 
 For a read: the current or historical knowledge in compact JSON.
 
-For a write: the new revision and the current value after the write. If the write replaces a symbol or a region of a different origin, `previous` gives that row as it was before the write. For example, an `llm` write over a `user` name gives `previous`. Read `previous` and tell the user about the change. For `apply`, `replaced` lists each write that replaced a row. Each item has the number of the write, its `op` and its `previous`.
+For a write: the new revision and the current value after the write. If the write replaces a symbol, a region or an operand expression of a different origin, `previous` gives that row as it was before the write. For example, an `llm` write over a `user` name gives `previous`. Read `previous` and tell the user about the change. For `apply`, `replaced` lists each write that replaced a row. Each item has the number of the write, its `op` and its `previous`.
 
 The exit status is 0 for a result. The exit status is 1 for an error from the knowledge, for example `conflict`. The exit status is 2 for a wrong argument.
 
@@ -155,7 +191,8 @@ The exit status is 0 for a result. The exit status is 1 for an error from the kn
 - `conflict`: the change contradicts current knowledge. For example, the name belongs to another address. Read that address and its history, then decide.
 - `stale-revision`: the knowledge changed after you read it. Read it again, then decide again.
 - `not-found`: there is nothing to remove or no such revision.
-- `invalid-database` or `unsupported-schema`: tell the user the message. Do not edit the file.
+- `conflict` with "from a git merge": git joined the knowledge of two computers, and two rows are current where the knowledge permits one row. For example, two names are at one address. Every read shows these rows in `conflicts`. Writes stop until you run `merge`. The `merge` command keeps the newest row of each conflict and closes the other rows, in one revision. Its result lists each choice. Tell the user the choices.
+- `invalid-database` or `unsupported-schema`: tell the user the message. Do not edit the knowledge files.
 
 A revert makes a new revision. The history stays complete.
 
@@ -164,3 +201,4 @@ A revert makes a new revision. The history stays complete.
 - Runtime evidence → c64-emulator
 - Static evidence → c64-static-analysis
 - Source from the knowledge → c64-source
+- Names of routines that other programs share → c64-provenance