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

package/skills/c64-emulator/SKILL.md

@@ -0,0 +1,134 @@
+---
+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, also in a later session | `c64_snapshot` (with `out` and `file`) |
+
+Each memory and register tool has a `space`. Use `c64` for the computer. Use `drive8` for the CPU of the 1541 disk drive. The memory `view` is `cpu` or `ram`. With `cpu`, you see what the CPU sees now, with ROM and I/O where the memory configuration puts them. With `ram`, you see the RAM under them.
+
+For a large result, give `out` with a path in the project. `c64_memory_read`, `c64_disassemble`, `c64_cpu_history` and `c64_screen` then write the result to that file. The answer gives only the file, the number of bytes and a SHA-256. Use it for a memory dump of more than a few hundred bytes, a long listing, or a screen that the user wants to keep.
+
+`c64_memmap` 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.
+
+## 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`. A reset and `c64_autostart` set `c64_timing` to zero.
+
+A cartridge from `c64_autostart` stays in the C64 through every reset, as on a real C64. `c64_status` gives `cartridge: true` while the C64 has it, and `cartridge: false` when it does not. `c64_autostart` of a file that is not a cartridge removes the cartridge first. `c64_autostart` also sets both joysticks to the center first. `joysticksCentred` gives the ports that it changed.
+
+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. The emulator has no command that presses one key of the keyboard matrix. For such a program:
+
+- After `c64_window` or a snapshot restore, the profiler of VICE keeps the routines that ran before the restore. Then `c64_profile` can give the cycles of the program to such a routine, for example `$fd50`. Do not trust the routine addresses of `c64_profile` after a restore.
+- VICE 3.10 and older have a known flaw: bits 5-7 of `$DC00` and `$DC01` are always 0. Then `emulatorFlaw` in the result of `c64_keyboard` and `c64_joystick` gives the flaw. With this flaw, a wait for any key that reads all keyboard columns at one time ends without a key. A wait for one specific key, or a compare of the full byte of a joystick port, never ends. Tell the user about the flaw. The next VICE release and the VICE nightly builds do not have it. Joystick port 1 uses the same lines as the keyboard.
+- For one specific key, for example F1 or RUN/STOP, open the window and ask the user to press the key.
+- Do not change the program to make it accept a 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 connection to the host runtime was lost, and the machine state is gone. Do not continue with results from before. The next call starts a new machine when the host runtime runs. Load the program again, and set the breakpoints and the watchpoints again. If the next call gives `machine-unavailable` with a message that the host runtime does not run, obey the rule for that message.
+- `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-running`: stop the CPU first, then try again.
+- `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. 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,166 @@
+---
+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` |
+| Only some origins | add `--origin semantic`, `--origin analyzer` (dxa, ghidra and heuristic), or `--origin user,llm` |
+| All knowledge in one file | `export --out exports/knowledge.json` |
+| Name the symbol at an address | `rename '$2100' update_player --kind routine` |
+| 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 |
+| 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'` |
+| 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` |
+
+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`.
+
+Region types:
+
+| Type | Meaning |
+|---|---|
+| `code` | Instructions. |
+| `bytes`, `words`, `petscii`, `screen`, `bitmap`, `sprite` | Data of that form. |
+| `addresses`, `addresses-split` | A table of addresses: one table of 16-bit values, or a low-byte table and then a high-byte table. |
+| `rts-addresses`, `rts-addresses-split` | The same, with each value the target minus 1, for a PHA, PHA, RTS dispatch. |
+| `jumps` | A table of `JMP abs` instructions. Each 3-byte entry is an entry point. It is code. |
+| `workspace` | RAM that the program writes at run time. Its bytes in the image do not matter. |
+| `unused` | Bytes that nothing executes or reads. |
+| `dual-use` | Code at one time and data or a vector at another time. No analyzer finding conflicts with it. |
+
+`--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`.
+
+## 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. Each row gives the `reason` and the `evidence` of the revision that wrote it.
+
+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. Add `--evidence` for each thing that the change rests on: `coverage:<file>`, `test:<file>`, `file:<file>` or `note:<text>`. The script keeps the SHA-256 of each file.
+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.
+
+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:
+
+```json
+[
+  { "op": "rename", "address": "$2100", "name": "update_player", "kind": "routine" },
+  { "op": "classify", "start": "$3000", "end": "$303b", "type": "bytes", "element": 6 },
+  { "op": "comment", "address": "$2100", "placement": "line", "text": "Reads joystick 2." }
+]
+```
+
+The ops and their fields:
+
+| op | Fields |
+|---|---|
+| `rename` | `address`, `name`, `kind` (optional) |
+| `remove-symbol` | `address` |
+| `classify` | `start`, `end`, `type`, `element` (optional) |
+| `unclassify` | `start`, `end` |
+| `comment` | `address`, `placement` (`line` or `side`), `text` |
+| `uncomment` | `address`, `placement` |
+| `reference`, `unreference` | `from`, `to`, `kind` |
+| `module` | `start`, `file`, `title` (optional) |
+| `unmodule` | `start` |
+
+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.
+
+## 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.
+
+## 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.
+
+- `suppressions` lists the blocked places with the reason of each removal. `at` and `history` also show them.
+- A `rename`, `classify` or `reference` at a blocked place ends the block there, because your own fact is at the place then.
+- A `revert` to a revision before the removal also ends the block.
+
+## 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. 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.
+
+## 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
+- Source from the knowledge → c64-source