@henols/c64-re-tools 2.0.0-rc.11 → 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.11",
+  "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,7 +39,7 @@ 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 ...` |
@@ -51,8 +49,11 @@ The script prints one JSON object. An error prints `{"error": {"code": ..., "mes
 | 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`.
 
@@ -73,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:
@@ -89,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
 [
@@ -117,6 +125,8 @@ The ops and their fields:
 
 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.
@@ -181,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.
 
@@ -190,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

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

@@ -1,5 +1,6 @@
-// The c64-knowledge script: reads and writes .c64-re-tools/knowledge.db in the
-// project directory (the working directory) and prints one compact JSON result.
+// The c64-knowledge script: reads and writes .c64-re-tools/knowledge/ in the
+// project folder (--project, or the one found from the working directory) and
+// prints one compact JSON result.
 
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
@@ -9,6 +10,7 @@ import { parseArgs } from "node:util";
 import { formatC64Address, parseC64Address } from "#src/c64.ts";
 import { ImageError, readImage } from "#src/host-client/image.ts";
 import { readProjectFile, writeProjectFile } from "#src/host-client/transfer.ts";
+import { CONFLICT_RULES, conflicts, type Conflict } from "#src/knowledge/conflicts.ts";
 import { KnowledgeError, openForRead, withWrite } from "#src/knowledge/database.ts";
 import { operandText } from "#src/knowledge/expression.ts";
 import { historyAt, historyNamed, revision, revisionNote, revisions, type HistoryEntry } from "#src/knowledge/history.ts";
@@ -53,6 +55,7 @@ import {
   addReference,
   applyBatch,
   classifyRegion,
+  mergeConflicts,
   removeComment,
   removeModule,
   removeOperand,
@@ -66,6 +69,7 @@ import {
   unclassifyRegion,
   type BatchOperation,
   type Evidence,
+  type MergeChoice,
   type OperandImage,
   type WriteContext,
 } from "#src/knowledge/write.ts";
@@ -86,8 +90,8 @@ Read (no database needed):
   operands [--start A --end A --origin O]  operand expressions of instructions
   spaces                              the address spaces that hold knowledge
   history <address> | history --name <name>
-  revisions [--limit N --before N]
-  revision <id>
+  revisions [--limit N --before R]
+  revision <revision>
   export --out <file> [--start A --end A --origin O]   all current knowledge to a project file
 
 Every command takes --space S: c64 (the default), drive8 for code in the 1541
@@ -97,7 +101,7 @@ own space.
 Read option --origin O: user, llm, dxa, ghidra, heuristic, semantic (user and
 llm) or analyzer (dxa, ghidra and heuristic), or a comma list. search takes it too.
 
-Write (one revision each; creates the database when needed):
+Write (one revision each; creates .c64-re-tools/knowledge/ when needed):
   rename <address> <name> [--kind K]
   remove-symbol <address>
   classify <start> <end> <type> [--element N]
@@ -117,6 +121,9 @@ Write (one revision each; creates the database when needed):
                            or PRG); give a negative offset as --offset=-1
   unoperand <address>
   revert <revision>
+  merge                    decide the conflicts that a git merge of two
+                           computers' work left: of the rows of one conflict,
+                           the newest stays; one revision for all
   apply <file>             many writes from a JSON file ('-' reads standard input),
                            all as one revision, or none when one is refused;
                            operand writes need --image <file>
@@ -125,10 +132,12 @@ Write options:
   --reason <text>          why, kept with the revision
   --evidence <kind:ref>    what the change rests on: coverage:<file>, test:<file>,
                            file:<file> or note:<text> (repeatable)
-  --expect-revision <N>    refuse the write if knowledge changed after revision N
+  --expect-revision <R>    refuse the write if knowledge changed after revision R
   --origin user|llm        who decided (default llm)
 
-Addresses are $ and four hex digits; quote them in a shell: '$2100'.`;
+Addresses are $ and four hex digits; quote them in a shell: '$2100'.
+A revision is its id, for example 20261015T214501.123-k3f9qz, or a start of
+the id that only one revision has; 0 is the knowledge before every revision.`;
 
 function address(value: string | undefined, what = "address"): number {
   if (value === undefined) throw new UsageError(`${what} is missing`);
@@ -205,9 +214,19 @@ function historyEntry(entry: HistoryEntry) {
   return { entity: entry.entity, ...row, fromRevision: entry.from, ...(entry.to === undefined ? {} : { toRevision: entry.to }) };
 }
 
+/** A conflict of a git merge (D69): what is wrong, and the rows, oldest first. */
+function showConflict(conflict: Conflict) {
+  return { conflict: CONFLICT_RULES[conflict.rule], ...spaceOf(conflict), rows: conflict.rows.map(historyEntry) };
+}
+
+/** What merge decided for one conflict: the row that stays and the rows it closed. */
+function showChoice(choice: MergeChoice) {
+  return { conflict: CONFLICT_RULES[choice.rule], ...spaceOf(choice), kept: historyEntry(choice.kept), closed: choice.closed.map(historyEntry) };
+}
+
 /** The reason of each revision that wrote one of the rows. */
-function reasonsOf(db: DatabaseSync | undefined, rows: SuppressionRow[]): Map<number, string> {
-  const reasons = new Map<number, string>();
+function reasonsOf(db: DatabaseSync | undefined, rows: SuppressionRow[]): Map<string, string> {
+  const reasons = new Map<string, string>();
   const query = db?.prepare("SELECT description FROM revisions WHERE id = ?");
   for (const { revision } of rows) {
     if (query === undefined || reasons.has(revision)) continue;
@@ -254,7 +273,7 @@ function run(argv: string[]): unknown {
   const space = values.space ?? DEFAULT_SPACE;
 
   const read = new Set(["at", "search", "symbols", "regions", "comments", "references", "suppressions", "modules", "operands", "spaces", "history", "revisions", "revision", "export"]);
-  const write = new Set(["rename", "remove-symbol", "classify", "unclassify", "comment", "uncomment", "reference", "unreference", "module", "unmodule", "operand", "unoperand", "revert", "apply"]);
+  const write = new Set(["rename", "remove-symbol", "classify", "unclassify", "comment", "uncomment", "reference", "unreference", "module", "unmodule", "operand", "unoperand", "revert", "apply", "merge"]);
   // Refuse a mistyped command before anything opens, so no database appears by accident.
   if (!read.has(command) && !write.has(command)) throw new UsageError(`unknown command: ${command}`);
   if (read.has(command)) {
@@ -262,83 +281,10 @@ function run(argv: string[]): unknown {
     if (command === "export" && values.out === undefined) throw new UsageError("export needs --out <file>");
     const db = openForRead();
     try {
-      switch (command) {
-        case "at": {
-          const known = at(db, address(args[0]), space);
-          return {
-            ...(space === DEFAULT_SPACE ? {} : { space }),
-            address: formatC64Address(known.address),
-            ...(known.symbol === undefined ? {} : { symbol: symbol(known.symbol) }),
-            ...(known.region === undefined ? {} : { region: region(known.region) }),
-            comments: known.comments.map(comment),
-            referencesFrom: known.referencesFrom.map(reference),
-            referencesTo: known.referencesTo.map(reference),
-            ...(known.operand === undefined ? {} : { operand: operand(known.operand) }),
-            ...(known.suppressions.length === 0 ? {} : { suppressions: known.suppressions.map(suppression) }),
-            revision: known.revision,
-          };
-        }
-        case "search": {
-          if (args[0] === undefined || args[0] === "") throw new UsageError("search needs text");
-          const found = search(db, args[0], values.limit === undefined ? 50 : integer(values.limit, "--limit"), origins, space);
-          return { symbols: found.symbols.map(symbol), comments: found.comments.map(comment) };
-        }
-        case "symbols":
-          return { symbols: listSymbols(db, range, values.kind === undefined ? undefined : oneOf(SYMBOL_KINDS, values.kind, "--kind"), origins, space).map(symbol) };
-        case "regions":
-          return { regions: listRegions(db, range, values.type === undefined ? undefined : oneOf(REGION_TYPES, values.type, "--type"), origins, space).map(region) };
-        case "comments":
-          return { comments: listComments(db, range, origins, space).map(comment) };
-        case "references":
-          return { references: listReferences(db, range, values.kind === undefined ? undefined : oneOf(REFERENCE_KINDS, values.kind, "--kind"), origins, space).map(reference) };
-        case "export": {
-          const exported = {
-            revision: currentRevision(db),
-            ...(space === DEFAULT_SPACE ? {} : { space }),
-            symbols: listSymbols(db, range, undefined, origins, space).map(symbol),
-            regions: listRegions(db, range, undefined, origins, space).map(region),
-            comments: listComments(db, range, origins, space).map(comment),
-            references: listReferences(db, range, undefined, origins, space).map(reference),
-            suppressions: listSuppressions(db, range, space).map(suppression),
-            modules: listModules(db, range, origins, space).map(module),
-            operands: listOperands(db, range, origins, space).map(operand),
-          };
-          const bytes = Buffer.from(`${JSON.stringify(exported, null, 2)}\n`, "utf8");
-          writeProjectFile(values.out!, bytes, { what: "--out" });
-          return {
-            out: values.out,
-            bytes: bytes.length,
-            counts: { symbols: exported.symbols.length, regions: exported.regions.length, comments: exported.comments.length, references: exported.references.length, suppressions: exported.suppressions.length, modules: exported.modules.length, operands: exported.operands.length },
-            revision: exported.revision,
-          };
-        }
-        case "suppressions": {
-          const rows = listSuppressions(db, range, space);
-          const reasons = reasonsOf(db, rows);
-          return { suppressions: rows.map((row) => ({ ...suppression(row), ...(reasons.has(row.revision) ? { reason: reasons.get(row.revision) } : {}) })) };
-        }
-        case "modules":
-          return { modules: listModules(db, range, origins, space).map(module) };
-        case "operands":
-          return { operands: listOperands(db, range, origins, space).map(operand) };
-        case "spaces":
-          return { spaces: listSpaces(db) };
-        case "history":
-          // Each row with the reason and the evidence of the revision that wrote it (F-26).
-          return {
-            history: (values.name === undefined ? historyAt(db, address(args[0]), space) : historyNamed(db, values.name, space)).map((entry) => ({ ...historyEntry(entry), ...revisionNote(db, entry.from) })),
-          };
-        case "revisions": {
-          const options: { limit?: number; before?: number } = {};
-          if (values.limit !== undefined) options.limit = integer(values.limit, "--limit");
-          if (values.before !== undefined) options.before = integer(values.before, "--before");
-          return { revisions: revisions(db, options) };
-        }
-        default: {
-          const changes = revision(db, integer(args[0], "revision"));
-          return { revision: changes.revision, added: changes.added.map(historyEntry), closed: changes.closed.map(historyEntry) };
-        }
-      }
+      const answer = readAnswer(db, command, args, values, range, origins, space);
+      const found = conflicts(db);
+      // A git merge can leave conflicts: every read shows them until merge decides them (D69).
+      return found.length === 0 ? answer : { ...answer, conflicts: found.map(showConflict) };
     } finally {
       db?.close();
     }
@@ -346,7 +292,7 @@ function run(argv: string[]): unknown {
 
   const context: WriteContext = { origin: values.origin === undefined ? "llm" : oneOf(["user", "llm"] as const, values.origin, "--origin") };
   if (values.reason !== undefined) context.description = values.reason;
-  if (values["expect-revision"] !== undefined) context.expectedRevision = integer(values["expect-revision"], "--expect-revision");
+  if (values["expect-revision"] !== undefined) context.expectedRevision = values["expect-revision"];
   if (values.evidence !== undefined) context.evidence = values.evidence.map(evidenceOf);
   // Every argument is checked before the database opens: a refused write creates no database.
   if (values.title !== undefined && command !== "module") throw new UsageError("--title works only with module");
@@ -363,6 +309,90 @@ function run(argv: string[]): unknown {
   return withWrite(operation);
 }
 
+type ReadValues = { kind?: string | undefined; type?: string | undefined; name?: string | undefined; limit?: string | undefined; before?: string | undefined; out?: string | undefined };
+
+/** The answer of one read command. */
+function readAnswer(db: DatabaseSync | undefined, command: string, args: string[], values: ReadValues, range: { start: number; end: number }, origins: Origin[] | undefined, space: string): Record<string, unknown> {
+  switch (command) {
+    case "at": {
+      const known = at(db, address(args[0]), space);
+      return {
+        ...(space === DEFAULT_SPACE ? {} : { space }),
+        address: formatC64Address(known.address),
+        ...(known.symbol === undefined ? {} : { symbol: symbol(known.symbol) }),
+        ...(known.region === undefined ? {} : { region: region(known.region) }),
+        comments: known.comments.map(comment),
+        referencesFrom: known.referencesFrom.map(reference),
+        referencesTo: known.referencesTo.map(reference),
+        ...(known.operand === undefined ? {} : { operand: operand(known.operand) }),
+        ...(known.suppressions.length === 0 ? {} : { suppressions: known.suppressions.map(suppression) }),
+        revision: known.revision,
+      };
+    }
+    case "search": {
+      if (args[0] === undefined || args[0] === "") throw new UsageError("search needs text");
+      const found = search(db, args[0], values.limit === undefined ? 50 : integer(values.limit, "--limit"), origins, space);
+      return { symbols: found.symbols.map(symbol), comments: found.comments.map(comment) };
+    }
+    case "symbols":
+      return { symbols: listSymbols(db, range, values.kind === undefined ? undefined : oneOf(SYMBOL_KINDS, values.kind, "--kind"), origins, space).map(symbol) };
+    case "regions":
+      return { regions: listRegions(db, range, values.type === undefined ? undefined : oneOf(REGION_TYPES, values.type, "--type"), origins, space).map(region) };
+    case "comments":
+      return { comments: listComments(db, range, origins, space).map(comment) };
+    case "references":
+      return { references: listReferences(db, range, values.kind === undefined ? undefined : oneOf(REFERENCE_KINDS, values.kind, "--kind"), origins, space).map(reference) };
+    case "export": {
+      const exported = {
+        revision: currentRevision(db),
+        ...(space === DEFAULT_SPACE ? {} : { space }),
+        symbols: listSymbols(db, range, undefined, origins, space).map(symbol),
+        regions: listRegions(db, range, undefined, origins, space).map(region),
+        comments: listComments(db, range, origins, space).map(comment),
+        references: listReferences(db, range, undefined, origins, space).map(reference),
+        suppressions: listSuppressions(db, range, space).map(suppression),
+        modules: listModules(db, range, origins, space).map(module),
+        operands: listOperands(db, range, origins, space).map(operand),
+      };
+      const bytes = Buffer.from(`${JSON.stringify(exported, null, 2)}\n`, "utf8");
+      writeProjectFile(values.out!, bytes, { what: "--out" });
+      return {
+        out: values.out,
+        bytes: bytes.length,
+        counts: { symbols: exported.symbols.length, regions: exported.regions.length, comments: exported.comments.length, references: exported.references.length, suppressions: exported.suppressions.length, modules: exported.modules.length, operands: exported.operands.length },
+        revision: exported.revision,
+      };
+    }
+    case "suppressions": {
+      const rows = listSuppressions(db, range, space);
+      const reasons = reasonsOf(db, rows);
+      return { suppressions: rows.map((row) => ({ ...suppression(row), ...(reasons.has(row.revision) ? { reason: reasons.get(row.revision) } : {}) })) };
+    }
+    case "modules":
+      return { modules: listModules(db, range, origins, space).map(module) };
+    case "operands":
+      return { operands: listOperands(db, range, origins, space).map(operand) };
+    case "spaces":
+      return { spaces: listSpaces(db) };
+    case "history":
+      // Each row with the reason and the evidence of the revision that wrote it (F-26).
+      return {
+        history: (values.name === undefined ? historyAt(db, address(args[0]), space) : historyNamed(db, values.name, space)).map((entry) => ({ ...historyEntry(entry), ...revisionNote(db, entry.from) })),
+      };
+    case "revisions": {
+      const options: { limit?: number; before?: string } = {};
+      if (values.limit !== undefined) options.limit = integer(values.limit, "--limit");
+      if (values.before !== undefined) options.before = values.before;
+      return { revisions: revisions(db, options) };
+    }
+    default: {
+      if (args[0] === undefined) throw new UsageError("revision is missing");
+      const changes = revision(db, args[0]);
+      return { revision: changes.revision, added: changes.added.map(historyEntry), closed: changes.closed.map(historyEntry) };
+    }
+  }
+}
+
 /** --origin for reads: one origin, semantic (user and llm), analyzer (dxa and ghidra), or a comma list. */
 function originFilter(value: string): Origin[] {
   const origins = new Set<Origin>();
@@ -601,8 +631,17 @@ function writeOperation(command: string, args: string[], kind: string | undefine
       const request = { space, address: address(args[0]) };
       return (db) => ({ revision: removeOperand(db, context, request).revision });
     }
+    case "merge": {
+      if (args.length > 0) throw new UsageError("merge takes no arguments");
+      const platform = new Map(platformNames().map((entry) => [entry.name, entry.address]));
+      return (db) => {
+        const merged = mergeConflicts(db, context, platform);
+        return { revision: merged.revision, choices: merged.current.map(showChoice) };
+      };
+    }
     case "revert": {
-      const request = { revision: integer(args[0], "revision") };
+      if (args[0] === undefined) throw new UsageError("revision is missing");
+      const request = { revision: args[0] };
       return (db) => ({ revision: revert(db, context, request).revision });
     }
     default:
@@ -610,4 +649,4 @@ function writeOperation(command: string, args: string[], kind: string | undefine
   }
 }
 
-await runScript(() => run(process.argv.slice(2)), { usage: USAGE, refusals: [KnowledgeError] });
+await runScript((argv) => run(argv), { usage: USAGE, refusals: [KnowledgeError] });