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

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

@@ -0,0 +1,103 @@
+// The c64-assembler script: assembles project source with ACME, which it runs
+// itself, and writes the program into the project.
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parseArgs } from "node:util";
+
+import { formatC64Address, parseC64Address } from "#src/c64.ts";
+import { readProjectTree } from "#src/host-client/transfer.ts";
+import { assemble } from "#src/native/acme.ts";
+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";
+
+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
+  --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'
+
+The result is one JSON object. Addresses are $ and four hex digits.`;
+
+function parseDefine(text: string): [string, number | boolean] {
+  const match = /^([A-Za-z_][A-Za-z0-9_]*)=(.+)$/.exec(text);
+  if (match === null) throw new UsageError(`--define needs NAME=VALUE, not ${text}`);
+  const value = match[2]!;
+  if (value === "true" || value === "false") return [match[1]!, value === "true"];
+  if (/^\$[0-9a-fA-F]+$/.test(value)) return [match[1]!, Number.parseInt(value.slice(1), 16)];
+  if (/^-?\d+$/.test(value)) return [match[1]!, Number(value)];
+  throw new UsageError(`--define ${match[1]} needs an integer or true/false, not ${value}`);
+}
+
+async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }> {
+  const { values } = parseArgs({
+    args: argv,
+    strict: true,
+    options: {
+      "source-root": { type: "string" },
+      entry: { type: "string" },
+      out: { type: "string" },
+      include: { type: "string", multiple: true },
+      define: { type: "string", multiple: true },
+      "set-pc": { type: "string" },
+      help: { type: "boolean" },
+    },
+  });
+  if (values.help) throw new UsageError("");
+  const sourceRoot = values["source-root"];
+  const entry = values.entry;
+  const out = values.out;
+  if (sourceRoot === undefined || entry === undefined || out === undefined) throw new UsageError("--source-root, --entry and --out are necessary");
+  let outPath: string;
+  try {
+    outPath = resolveProjectPath(out);
+  } catch {
+    throw new UsageError(`--out must be a path relative to the project directory that stays inside it, not ${out}`);
+  }
+  const defines = Object.fromEntries((values.define ?? []).map(parseDefine));
+  let setPc: number | undefined;
+  if (values["set-pc"] !== undefined) {
+    try {
+      setPc = parseC64Address(values["set-pc"]);
+    } catch {
+      throw new UsageError(`--set-pc must be $ followed by four hex digits, not ${values["set-pc"]}`);
+    }
+  }
+  const tree = readProjectTree(sourceRoot);
+  if (!tree.files.some((file) => file.path === entry)) throw new UsageError(`--entry ${entry} is not a file in ${sourceRoot}`);
+  const params: AcmeParams = { files: tree.files, entrySource: entry, includeDirs: values.include ?? [], defines, ...(setPc === undefined ? {} : { setPc }) };
+
+  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]!);
+  const range = result.loadRange!;
+  return {
+    output: {
+      assembled: true,
+      output: out,
+      loadRange: { start: formatC64Address(range.start), end: formatC64Address(range.end), bytes: range.bytes },
+      symbols: result.symbols!.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 },
+      ),
+      diagnostics: result.diagnostics,
+    },
+    failed: false,
+  };
+}
+
+await runScript(
+  async () => {
+    const { output, failed } = await run(process.argv.slice(2));
+    if (failed) process.exitCode = 1;
+    return output;
+  },
+  { usage: USAGE },
+);

package/skills/c64-basic/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: c64-basic
+description: Use this skill to decode a C64 BASIC V2 program (PRG) into a readable listing. It also finds where the BASIC gives control to machine code with SYS or USR. Use it on the start file of a game or of a demo. Do not use it on machine code or to run the program. Give the handoff address to the c64-static-analysis or c64-emulator skill.
+---
+
+# c64-basic
+
+## Purpose
+
+Decode a C64 BASIC V2 program. Find the handoff from BASIC to machine code.
+
+This skill does not run the program and does not change project knowledge.
+
+## Inputs
+
+- The program: a PRG file, relative to the project directory.
+
+## Tools / execution path
+
+The script sends the program to the host runtime. The host decodes it with petcat and finds the handoffs.
+
+```
+node <skill>/scripts/basic.ts extracted/game.prg
+```
+
+The script prints one JSON object. Addresses are `$` and four hex digits.
+
+## 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.
+
+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.
+
+## Knowledge
+
+Automatic write:
+- none.
+
+Do not store:
+- the listing.
+
+The entry point of the machine code can be durable knowledge. The c64-reverse-engineering skill decides that and records it with the c64-knowledge skill.
+
+## Result
+
+The listing and the handoff addresses. Or `decoded: false` with a reason when the file is not a BASIC program.
+
+The exit status is 0 for a listing. The exit status is 1 for `decoded: false` and for an error. The exit status is 2 for a wrong argument.
+
+## 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.
+- 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`.
+- `not-found` or `invalid-input`: the path or an argument is wrong. Read the message and correct the call.
+
+## Handoffs
+
+- Machine code at the handoff address → c64-static-analysis
+- Run the program to the handoff → c64-emulator
+- Record the entry point → c64-knowledge

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

@@ -0,0 +1,46 @@
+// The c64-basic script: decodes a project C64 BASIC V2 program with petcat
+// through the Host Runtime and reports its machine-code handoffs.
+
+import { statSync } from "node:fs";
+import { parseArgs } from "node:util";
+
+import { formatC64Address } from "#src/c64.ts";
+import { decodeBasic } from "#src/host-client/tools.ts";
+import { resolveProjectPath } from "#src/project.ts";
+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
+JSON object. Addresses are $ and four hex digits.`;
+
+async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }> {
+  const { values, positionals } = parseArgs({ args: argv, strict: true, allowPositionals: true, options: { help: { type: "boolean" } } });
+  if (values.help) throw new UsageError("");
+  if (positionals.length !== 1) throw new UsageError("give one program");
+  const program = positionals[0]!;
+  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);
+  return {
+    output: {
+      decoded: true,
+      loadRange: { start: formatC64Address(result.loadAddress), end: formatC64Address(end) },
+      // From here to the end of the load range, the file holds no BASIC (often machine code).
+      basicEnd: result.basicEnd <= end ? formatC64Address(result.basicEnd) : null,
+      listing: result.listing,
+      handoffs: result.handoffs.map((handoff) => ("address" in handoff ? { ...handoff, address: formatC64Address(handoff.address) } : handoff)),
+    },
+    failed: false,
+  };
+}
+
+await runScript(
+  async () => {
+    const { output, failed } = await run(process.argv.slice(2));
+    if (failed) process.exitCode = 1;
+    return output;
+  },
+  { usage: USAGE },
+);

package/skills/c64-disk/SKILL.md

@@ -0,0 +1,79 @@
+---
+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.
+---
+
+# c64-disk
+
+## Purpose
+
+Examine a C64 disk image. Extract a file from the image 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.
+- For one file: the file name as the directory shows it.
+- To extract a file: the output path, relative to the project directory.
+
+## 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.
+
+```
+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 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 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}'`.
+
+## 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.
+
+## Knowledge
+
+Automatic write:
+- none.
+
+Do not store:
+- the directory list
+- sector chains.
+
+A downstream skill records the meaning of the extracted content.
+
+## Result
+
+The directory, the BAM, an entry or a sector chain as JSON. Or the extracted file in the project at the output path.
+
+The exit status is 0 for a result with the file. The exit status is 1 for `found: false` and for an error. The exit status is 2 for a wrong argument.
+
+## Failure and conflicts
+
+- `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`.
+- `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.
+
+## Handoffs
+
+- BASIC program → c64-basic
+- Packed program → c64-unpacker
+- Machine code → c64-static-analysis
+- Run the program → c64-emulator

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

@@ -0,0 +1,65 @@
+// The c64-disk script: inspects a project disk image with c1541 through the
+// Host Runtime and extracts files into the project.
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parseArgs } from "node:util";
+
+import { inspectDisk } from "#src/host-client/tools.ts";
+import { resolveProjectPath } from "#src/project.ts";
+import { runScript, UsageError } from "#src/script.ts";
+
+const USAGE = `disk.ts <action> <image> [name] [--out <file>]
+
+  directory <image>                 disk name, id, free blocks and the files
+  bam <image>                       free and used sectors of each track
+  entry <image> <name>              the directory entry of one file
+  chain <image> <name>              the track and sector of each block of one file
+  read <image> <name> --out <file>  write the bytes of one file into the project
+
+<image> is a .d64, .d71, .d81 or .g64 file, relative to the project directory.
+<name> is the file name as the directory shows it. Write a byte that has no
+character as {$xx}, for example {$c1}. The result is one JSON object.`;
+
+const ACTIONS = ["directory", "bam", "entry", "chain", "read"] as const;
+type Action = (typeof ACTIONS)[number];
+
+async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }> {
+  const { values, positionals } = parseArgs({ args: argv, strict: true, allowPositionals: true, options: { out: { type: "string" }, help: { type: "boolean" } } });
+  if (values.help) throw new UsageError("");
+  const [action, image, name, ...extra] = positionals;
+  if (!ACTIONS.includes(action as Action)) throw new UsageError(`the action must be one of ${ACTIONS.join(", ")}`);
+  if (image === undefined) throw new UsageError("the disk image is necessary");
+  const named = action === "entry" || action === "chain" || action === "read";
+  if (named && name === undefined) throw new UsageError(`${action} needs a file name`);
+  if ((!named && name !== undefined) || extra.length > 0) throw new UsageError("too many arguments");
+  if (action === "read" && values.out === undefined) throw new UsageError("read needs --out <file>");
+  if (action !== "read" && values.out !== undefined) throw new UsageError("only read takes --out");
+  let outPath: string | undefined;
+  if (values.out !== undefined) {
+    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}`);
+    }
+  }
+
+  const result = await inspectDisk({ image, action: action as Action, ...(name === undefined ? {} : { name }) });
+  if ("found" in result && !result.found) return { output: { found: false }, failed: true };
+  if (result.action === "read" && result.found) {
+    mkdirSync(dirname(outPath!), { recursive: true });
+    writeFileSync(outPath!, result.data!);
+    return { output: { found: true, name: result.name, bytes: result.bytes, output: values.out }, failed: false };
+  }
+  const { action: _action, ...output } = result;
+  return { output, failed: false };
+}
+
+await runScript(
+  async () => {
+    const { output, failed } = await run(process.argv.slice(2));
+    if (failed) process.exitCode = 1;
+    return output;
+  },
+  { usage: USAGE },
+);

package/skills/c64-emulator/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: c64-emulator
+description: Use this skill to operate and debug the live C64 emulator through the c64-re-tools MCP tools, whose names start with c64_. It loads programs and disks, controls and steps the CPU, and sets breakpoints and watchpoints. It reads and writes memory and registers, types keys, moves a joystick, advances frames and captures the screen. Do not use it for static analysis, project knowledge, assembly or disk inspection.
+---
+
+# c64-emulator
+
+## Purpose
+
+Operate and debug the one live C64 that belongs to this MCP session. Get runtime evidence and runtime state from it.
+
+This skill does not analyse code statically. It does not write project knowledge. It does not assemble source code.
+
+## Inputs
+
+- The machine action or the runtime question.
+- The target address, state or condition, when the question needs one.
+- The project path of the program or disk to load, when the question needs one.
+
+Addresses are four hex digits after a dollar sign, for example `$c000`. Resolve a symbol name to its address before you use a tool. The c64-knowledge skill gives the address of a known symbol.
+
+## Tools / execution path
+
+Use only the MCP tools. Each MCP session has its own C64. Nothing else can change that C64.
+
+| Need | Tool |
+|---|---|
+| Run state, video standard, warp mode, window | `c64_status` |
+| Reset, power cycle | `c64_reset` |
+| Fast emulation | `c64_warp` |
+| Show the C64 to the user in a window, hide it again | `c64_window` |
+| Stop, start, step, step over, step out, exact frames | `c64_execution` |
+| Run until an address, a memory value or a raster position | `c64_run_until` |
+| Stop on an instruction address | `c64_breakpoint` |
+| Stop on a memory read or write | `c64_watchpoint` |
+| Memory | `c64_memory_read`, `c64_memory_write`, `c64_memory_search`, `c64_memory_compare` |
+| CPU registers | `c64_registers` |
+| Code as it is in memory now | `c64_disassemble` |
+| Executed instructions, call chain | `c64_cpu_history`, `c64_backtrace` |
+| Where the CPU spends cycles, which memory it uses | `c64_profile`, `c64_memmap` |
+| Cycle count between two points | `c64_timing` |
+| Video chip, sprites, CIAs, sound chip | `c64_vicii`, `c64_sprite`, `c64_cia`, `c64_sid` |
+| Screen image, screen compare | `c64_screen` |
+| Several of these from one moment | `c64_observe` |
+| Keys, joystick | `c64_keyboard`, `c64_joystick` |
+| Program and disk media | `c64_autostart`, `c64_program_load`, `c64_disk_attach` |
+| Machine state to go back to | `c64_snapshot` |
+
+Each memory and register tool has a `space`. Use `c64` for the computer. Use `drive8` for the CPU of the 1541 disk drive. The memory `view` is `cpu` or `ram`. With `cpu`, you see what the CPU sees now, with ROM and I/O where the memory configuration puts them. With `ram`, you see the RAM under them.
+
+## Workflow
+
+1. Read the project knowledge for the addresses in the question. Use the c64-knowledge skill.
+2. Get the machine state with `c64_status`.
+3. Load the subject if it is not loaded. Use `c64_autostart` to start it as a user does. Use `c64_program_load` to put a PRG in memory with no start.
+4. Set the stop condition. Use a breakpoint, a watchpoint or a `c64_run_until` target. Add a typed condition when the stop must occur only in one state. The `list` result shows the condition of each breakpoint and each watchpoint.
+5. Run, step or give input. Prefer `c64_run_until` and `advance-frames` to waits. They stop at the same emulated time on every run.
+6. Read only the state that answers the question. To read several things from one moment, use `c64_observe`.
+7. Interpret the evidence. Keep the observed facts apart from your conclusions.
+
+Write operations need a stopped CPU. Stop the CPU with `c64_execution` action `pause` first.
+
+`c64_reset` with `run` false stops the CPU at the first instruction of the reset routine. The result gives that address in `pc`.
+
+Step, next and until-return work only in space `c64`. The emulator cannot stop the disk drive CPU after one instruction. To find when the drive executes an address, use `c64_run_until` with an address target in space `drive8`, or a breakpoint in space `drive8`. The drive can execute a few more instructions before it stops. The computer completes its current instruction. The `pc` in the result is the drive address where it stopped.
+
+`c64_keyboard` puts keys in the keyboard queue of the KERNAL. A program that reads the keyboard hardware directly does not see them. Many games do this. For such a program, use `c64_joystick`, or open the window and ask the user to press the key.
+
+Before a risky experiment, save the state with `c64_snapshot`. Restore it to try again from the same point.
+
+The emulator has no window. When the user must type, play or look at the C64, do these steps:
+
+1. Open the window with `c64_window` action `open`.
+2. Tell the user that the window is open and what to do in it.
+3. Wait until the user tells you that they finished.
+4. Close the window with `c64_window` action `close`.
+
+The machine, the disk in drive 8, the breakpoints, the watchpoints, the joysticks, warp mode and `c64_timing` stay the same. The CPU stays running or stopped. The result field `notCarried` names the data that the move clears. A second `open` or `close` changes nothing.
+
+A read does not change the run state. A running machine continues to run after a read.
+
+## Knowledge
+
+Read:
+- the current knowledge for each address and range that the question touches.
+
+Automatic write:
+- none.
+
+Write after interpretation:
+- a symbol, a region or a comment that the runtime evidence justifies. Record it with the c64-knowledge skill.
+
+Do not store:
+- breakpoints or watchpoints
+- memory reads
+- temporary machine state
+- a screen capture, unless the user asks for it as an artifact
+
+## Result
+
+The result is the runtime state or evidence that the question asks for.
+
+If you cannot get the machine into the necessary state, say which state you could not get. Say what you tried.
+
+## Failure and conflicts
+
+- `machine-state-lost` and the message says that the VICE window closed: the window closed before `c64_window` action `close`. The emulator has no window again. The machine state is the same as at the time when the window opened. The breakpoints and the watchpoints stay. Do not use results from the window time. Read the machine state again, then continue.
+- `machine-unavailable` and the message says that the VICE window closed: the session starts the emulator again. Wait a few seconds. Then do the operation again.
+- `machine-state-lost` with a different message: the emulator stopped and its state is gone. Do not continue with results from before. Tell the user to restart the MCP server.
+- `machine-unavailable` and the message names a pause or a dialog in the emulator window: this occurs only while the window is open. Do not send more operations. Tell the user to resume the emulator (Pause, Alt+P) or to close the dialog in the VICE window. Then do the operation again. The machine state does not change.
+- `machine-unavailable` with a different message: the host runtime does not run, or it does not answer. Tell the user to start the host runtime with `npx -y --package=@henols/c64-re-tools@latest c64-re-tools-host`.
+- `machine-running`: stop the CPU first, then try again.
+- `installation-incomplete`: tell the user the message. Do not try to repair the installation.
+- `c64_run_until` with `stopReason` `timeout`: the target did not occur in the frame limit. This is evidence too. Report it.
+- `c64_run_until` with `stopReason` `jam`: the CPU executed a JAM opcode and stopped. Report the address.
+
+If the runtime evidence does not agree with the current knowledge, do not change the knowledge. Report the conflict and hand it to c64-knowledge.
+
+## Handoffs
+
+- Static explanation of code → c64-static-analysis
+- Durable conclusion or a knowledge conflict → c64-knowledge
+- Comparison or assertion between runs → c64-testing
+- Meaning of a C64 address or register → c64-memory-map

package/skills/c64-knowledge/SKILL.md

@@ -0,0 +1,102 @@
+---
+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.
+---
+
+# 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.
+
+This skill is the only write path for conclusions of the user and the LLM. It does not run an emulator or an analyzer.
+
+## Inputs
+
+One of these:
+
+- an address, a range or a symbol name to look up
+- text to search for
+- a change to a symbol, a region, a comment or a reference, with a short reason
+- a request to see the history or a revision.
+
+## 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]
+```
+
+The script prints one JSON object. An error prints `{"error": {"code": ..., "message": ...}}`. Addresses are `$` and four hex digits. Quote them in a shell, for example `'$2100'`.
+
+| Need | Command |
+|---|---|
+| Everything known at one address | `at '$2100'` |
+| Find names and comment text | `search player` |
+| Lists in a range | `symbols`, `regions`, `comments`, `references` with `--start` and `--end` |
+| Name the symbol at an address | `rename '$2100' update_player --kind routine` |
+| Remove a symbol | `remove-symbol '$2100'` |
+| Classify memory | `classify '$3000' '$303f' sprite` |
+| Make memory unknown again | `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 ...` |
+| History | `history '$2100'`, `history --name update_player`, `revisions`, `revision 12` |
+| Go back to an earlier state | `revert 12` |
+
+Symbol kinds are `label`, `routine`, `variable`, `data` and `vector`. Region types are `code`, `bytes`, `words`, `addresses`, `addresses-split`, `petscii`, `screen`, `bitmap` and `sprite`. Reference kinds are `call`, `jump`, `read`, `write` and `reference`.
+
+## Workflow
+
+Read:
+
+1. Use `at` for the addresses in the question before other work.
+2. Use `history` when the current knowledge is surprising or disputed.
+
+Write:
+
+1. Read the current value with `at`. Note the `revision` in the result.
+2. Decide the change. Keep observed facts apart from your conclusions.
+3. Write it with `--reason` and `--expect-revision` set to the revision you read.
+4. Read the result. A `revision` of `null` means that nothing changed.
+
+Each write is one revision. A classification inside a region splits that region, so regions never overlap.
+
+## Knowledge
+
+Write after interpretation:
+
+- a symbol name that tells what a routine or a variable does
+- a region type that the evidence supports
+- a comment that explains behavior that a name cannot show
+- a reference that the evidence supports.
+
+Do not store:
+
+- temporary investigation state
+- a guess, only because a routine needs a temporary name
+- confidence or status words in comment text.
+
+The script records the origin `llm`. Use `--origin user` only when the user decides the change.
+
+## Result
+
+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.
+
+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.
+
+## Failure and conflicts
+
+- `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.
+
+A revert makes a new revision. The history stays complete.
+
+## Handoffs
+
+- Runtime evidence → c64-emulator
+- Static evidence → c64-static-analysis