@henols/c64-re-tools 2.0.0-rc.11 → 2.0.0-rc.13

package/skills/c64-static-analysis/scripts/analyze.ts

@@ -1,7 +1,7 @@
 // The c64-static-analysis script: analyzes a project program with DXA (fast
 // first pass) or Ghidra (deeper), which it runs itself, seeded from
 // current knowledge, and imports the structural findings into
-// .c64-re-tools/knowledge.db.
+// .c64-re-tools/knowledge/.
 
 import { createHash } from "node:crypto";
 import { mkdirSync, writeFileSync } from "node:fs";
@@ -18,20 +18,21 @@ import { localToolContext } from "#src/native/local.ts";
 import { GHIDRA_LIMITS } from "#src/native/types.ts";
 import { KnowledgeError, openForRead, withWrite } from "#src/knowledge/database.ts";
 import { importFindings, runProvenance, type Analyzer, type ImportConflict, type ImportContext, type ImportResult, type NormalizedFindings } from "#src/knowledge/import.ts";
-import { currentRevision, listRegions } from "#src/knowledge/read.ts";
+import { currentRevision, listMacros, listMacroUses, listPatches, listReferences, listRegions, listSymbols } from "#src/knowledge/read.ts";
 import { DEFAULT_SPACE, SPACE } from "#src/knowledge/schema.ts";
 import { platformNames } from "#src/platform.ts";
 import { resolveProjectPath } from "#src/project.ts";
 import { runScript, UsageError } from "#src/script.ts";
-import { codeEntries, coverageConflicts, coverageEntries, imageReader, readCoverageMaps } from "./coverage.ts";
+import { codeEntries, coverageConflicts, coverageEntries, imageReader, readCoverageMaps, type ImageByte } from "./coverage.ts";
 import { dxaFindings, ghidraFindings, seedsFromKnowledge } from "./findings.ts";
 import { findIdioms } from "./idioms.ts";
 import { instructionList } from "./instructions.ts";
+import { CATALOGUE, findMacroUses, type MacroCandidate } from "./macros.ts";
 import { findPointers, type PointerCandidate } from "./pointers.ts";
 
 const USAGE = `analyze.ts <image> [options]
 
-  <image>                 a PRG file, relative to the project directory
+  <image>                 a PRG file, relative to the project folder
   --analyzer <name>       dxa (fast first pass) or ghidra (deeper, the default)
   --flat64k               the image is 64 KiB of memory from $0000, not a PRG
   --entry <address>       an entry point, for example '$080d' (repeatable)
@@ -46,6 +47,8 @@ const USAGE = `analyze.ts <image> [options]
                           all labels and functions
   --space <space>         the knowledge space of the image: c64 (the default), drive8
                           for 1541 drive code, or bank0 to bank255 for a cartridge bank
+  --macro-batch <file>    write the macro candidates as an apply batch of c64-knowledge
+                          (the macros and their uses) to this project file
 
 Routine symbols in knowledge are entry points too. Ghidra needs at least one
 entry point; dxa finds the SYS of a BASIC start by itself. The result is one
@@ -67,6 +70,73 @@ function showPointer(candidate: PointerCandidate) {
   return { kind: candidate.kind, to: hex(candidate.to), target: hex(candidate.target), low: hex(candidate.low), high: hex(candidate.high) };
 }
 
+/** A macro candidate with $ addresses and its source line (D73). */
+function showMacro(candidate: MacroCandidate) {
+  return { macro: candidate.macro, start: formatC64Address(candidate.start), end: formatC64Address(candidate.end), args: candidate.args, text: `+${candidate.macro} ${candidate.args.join(", ")}` };
+}
+
+/**
+ * The macro candidates (D73) in the current code regions of every origin,
+ * with the names of the knowledge in their args. A candidate is left out when
+ * a name or a reference target is inside it, or a patch or a use overlaps it:
+ * c64-source would write its instructions. The same use in the knowledge is
+ * known. With `batchPath`, the candidates go to an apply batch with the
+ * macros they need; a macro of the catalogue that the knowledge has with
+ * another body leaves its candidates out of the batch.
+ */
+function macroCandidates(space: string, image: string, byteAt: ImageByte, batchPath: string | undefined) {
+  const db = openForRead();
+  try {
+    const platform = space === DEFAULT_SPACE ? new Map(platformNames().map((entry) => [entry.address, entry.name])) : new Map<number, string>();
+    const semantic = new Map(listSymbols(db, undefined, undefined, ["user", "llm"], space).map((symbol) => [symbol.address, symbol.name]));
+    const code = listRegions(db, undefined, "code", undefined, space);
+    const found = findMacroUses(byteAt, code, (address) => semantic.get(address) ?? platform.get(address));
+    const named = new Set([...listSymbols(db, undefined, undefined, undefined, space).map((symbol) => symbol.address), ...listReferences(db, undefined, undefined, undefined, space).map((reference) => reference.to)]);
+    const patches = listPatches(db, undefined, undefined, undefined, space);
+    const uses = listMacroUses(db, undefined, undefined, undefined, space);
+    const overlaps = (a: { start: number; end: number }, b: { start: number; end: number }) => a.start <= b.end && b.start <= a.end;
+    const candidates: MacroCandidate[] = [];
+    let known = 0;
+    let leftOut = 0;
+    for (const candidate of found) {
+      const same = uses.find((use) => use.start === candidate.start && use.end === candidate.end && use.macro === candidate.macro && use.args.join(",") === candidate.args.join(","));
+      if (same !== undefined) known++;
+      else if ([...named].some((address) => address > candidate.start && address <= candidate.end) || patches.some((patch) => overlaps(patch, candidate)) || uses.some((use) => overlaps(use, candidate))) leftOut++;
+      else candidates.push(candidate);
+    }
+    if (batchPath === undefined) return { candidates, known, leftOut };
+    // A macro of the catalogue goes into the batch unless the knowledge has it; with another body, its uses stay out.
+    const macros = new Map(listMacros(db, undefined, space).map((macro) => [macro.name, macro]));
+    const batch: Array<Record<string, unknown>> = [];
+    const batched: MacroCandidate[] = [];
+    const other = new Set<string>();
+    for (const idiom of CATALOGUE.filter((item) => candidates.some((candidate) => candidate.macro === item.name))) {
+      const existing = macros.get(idiom.name);
+      if (existing === undefined) batch.push({ op: "macro", name: idiom.name, params: idiom.params, body: idiom.body, comment: idiom.comment, ...(space === DEFAULT_SPACE ? {} : { space }) });
+      else if (existing.params.join(",") !== idiom.params.join(",") || existing.body !== idiom.body) other.add(idiom.name);
+    }
+    for (const candidate of candidates) {
+      if (other.has(candidate.macro)) continue;
+      batched.push(candidate);
+      batch.push({ op: "use", start: formatC64Address(candidate.start), end: formatC64Address(candidate.end), macro: candidate.macro, args: candidate.args, ...(space === DEFAULT_SPACE ? {} : { space }) });
+    }
+    if (batch.length > 0) writeProjectFile(batchPath, Buffer.from(`${JSON.stringify(batch, null, 1)}\n`), { what: "--macro-batch" });
+    return {
+      candidates,
+      known,
+      leftOut,
+      batch: {
+        out: batchPath,
+        writes: batch.length,
+        ...(other.size === 0 ? {} : { otherMacros: [...other].map((name) => `The knowledge has another macro ${name}: its candidates are not in the batch.`) }),
+        ...(batch.length === 0 ? {} : { apply: `knowledge.ts apply ${batchPath} --image ${image} --reason "macro uses of 6502 idioms"` }),
+      },
+    };
+  } finally {
+    db?.close();
+  }
+}
+
 /** A decompiler that did not start gets the remedy: Ghidra ships no native decompiler for macOS. */
 function withRemedy(reason: string): string {
   return reason.startsWith("the Ghidra decompiler did not start")
@@ -104,10 +174,10 @@ function showConflict(conflict: ImportConflict, analyzer: Analyzer): Record<stri
 
 /**
  * Imports one analyzer's findings as one revision, refused when knowledge
- * changed since the seeds were read. A refused import creates no knowledge.db.
+ * changed since the seeds were read. A refused import creates no knowledge.
  * The revision records the image hash and the analyzer version.
  */
-function record(findings: NormalizedFindings, revision: number, description: string, provenance: Pick<ImportContext, "inputHash" | "toolVersion" | "evidence">) {
+function record(findings: NormalizedFindings, revision: string, description: string, provenance: Pick<ImportContext, "inputHash" | "toolVersion" | "evidence">) {
   let imported: ImportResult;
   try {
     imported = withWrite((db) => importFindings(db, findings, { expectedRevision: revision, description, ...provenance }));
@@ -139,6 +209,7 @@ async function run(argv: string[]): Promise<unknown> {
       coverage: { type: "string", multiple: true },
       instructions: { type: "string" },
       space: { type: "string" },
+      "macro-batch": { type: "string" },
       help: { type: "boolean" },
     },
   });
@@ -161,7 +232,15 @@ async function run(argv: string[]): Promise<unknown> {
     try {
       listingPath = resolveProjectPath(values.listing);
     } catch {
-      throw new UsageError(`--listing must be a path relative to the project directory that stays inside it, not ${values.listing}`);
+      throw new UsageError(`--listing must be a path relative to the project folder that stays inside it, not ${values.listing}`);
+    }
+  }
+
+  if (values["macro-batch"] !== undefined) {
+    try {
+      resolveProjectPath(values["macro-batch"]);
+    } catch {
+      throw new UsageError(`--macro-batch must be a path relative to the project folder that stays inside it, not ${values["macro-batch"]}`);
     }
   }
 
@@ -206,6 +285,8 @@ async function run(argv: string[]): Promise<unknown> {
   /** Imports the idioms as their own revision, after the analyzer's, and gives their part of the result. */
   const idiomsResult = () => {
     const imported = withWrite((db) => importFindings(db, { ...idioms.findings, space }, { description: `Idioms in ${image}` }));
+    // The macro candidates read the code regions after both imports (D73).
+    const macros = macroCandidates(space, image, byteAt, values["macro-batch"]);
     return {
       idioms: {
         ...idioms.counts,
@@ -217,6 +298,12 @@ async function run(argv: string[]): Promise<unknown> {
           dop: listed(idioms.candidates.dop, max, formatC64Address, "a larger --max-listed"),
           selfModified: listed(idioms.candidates.selfModified, max, formatC64Address, "a larger --max-listed"),
           pointers: listed(pointers, max, showPointer, "a larger --max-listed"),
+          macros: {
+            ...listed(macros.candidates, max, showMacro, "a larger --max-listed, or --macro-batch <file>"),
+            ...(macros.known === 0 ? {} : { known: macros.known }),
+            ...(macros.leftOut === 0 ? {} : { leftOut: macros.leftOut }),
+            ...(macros.batch === undefined ? {} : { batch: macros.batch }),
+          },
         },
       },
     };
@@ -290,4 +377,4 @@ async function run(argv: string[]): Promise<unknown> {
   };
 }
 
-await runScript(() => run(process.argv.slice(2)), { usage: USAGE, refusals: [KnowledgeError] });
+await runScript((argv) => run(argv), { usage: USAGE, refusals: [KnowledgeError] });

package/skills/c64-static-analysis/scripts/macros.ts

@@ -0,0 +1,233 @@
+// Macro candidates (D73): runs of instructions that are a known 6502 idiom,
+// such as a 16-bit increment, and that a macro can write as one line. They
+// are only reported, never written: the LLM applies them as macro uses with
+// c64-knowledge, and c64-source writes a use only when it gives the bytes of
+// the image.
+//
+// The catalogue is fixed, so each candidate has a name and a body that is
+// known to be correct. A search for any repeated sequence was weighed and not
+// chosen: it gives many candidates without a name (D73).
+
+import { instructionLength } from "#src/c64.ts";
+import type { ImageByte } from "./coverage.ts";
+
+/** A macro of the catalogue: its params and its ACME body, which names a param with a dot. */
+export interface MacroIdiom {
+  name: string;
+  params: string[];
+  body: string;
+  comment: string;
+}
+
+export const CATALOGUE: readonly MacroIdiom[] = [
+  { name: "inc16", params: ["dst"], body: ["        inc .dst", "        bne +", "        inc .dst+1", "+"].join("\n"), comment: "Adds 1 to the 16-bit value at dst." },
+  { name: "dec16", params: ["dst"], body: ["        lda .dst", "        bne +", "        dec .dst+1", "+       dec .dst"].join("\n"), comment: "Subtracts 1 from the 16-bit value at dst. It changes A." },
+  {
+    name: "add16_8",
+    params: ["dst", "value"],
+    body: ["        clc", "        lda .dst", "        adc #.value", "        sta .dst", "        bcc +", "        inc .dst+1", "+"].join("\n"),
+    comment: "Adds the 8-bit value to the 16-bit value at dst. It changes A.",
+  },
+  {
+    name: "add16",
+    params: ["dst", "value"],
+    body: ["        clc", "        lda .dst", "        adc #<.value", "        sta .dst", "        lda .dst+1", "        adc #>.value", "        sta .dst+1"].join("\n"),
+    comment: "Adds the 16-bit value to the 16-bit value at dst. It changes A.",
+  },
+  {
+    name: "sub16",
+    params: ["dst", "value"],
+    body: ["        sec", "        lda .dst", "        sbc #<.value", "        sta .dst", "        lda .dst+1", "        sbc #>.value", "        sta .dst+1"].join("\n"),
+    comment: "Subtracts the 16-bit value from the 16-bit value at dst. It changes A.",
+  },
+  {
+    name: "set16",
+    params: ["dst", "value"],
+    body: ["        lda #<.value", "        sta .dst", "        lda #>.value", "        sta .dst+1"].join("\n"),
+    comment: "Puts the 16-bit value at dst. It changes A.",
+  },
+  {
+    name: "mov16",
+    params: ["dst", "src"],
+    body: ["        lda .src", "        sta .dst", "        lda .src+1", "        sta .dst+1"].join("\n"),
+    comment: "Copies the 16-bit value at src to dst. It changes A.",
+  },
+  { name: "wait_line", params: ["line"], body: ["        lda #.line", "-       cmp $d012", "        bne -"].join("\n"), comment: "Waits until the raster line (bits 0-7) is line. It changes A." },
+];
+
+/** A run of instructions that one macro of the catalogue can write, with its args as ACME expressions. */
+export interface MacroCandidate {
+  macro: string;
+  start: number;
+  end: number;
+  args: string[];
+}
+
+/** One instruction: its opcode, its length and its operand value. */
+interface Instruction {
+  opcode: number;
+  length: number;
+  value: number;
+}
+
+/** An address operand: zero page or absolute, of the same memory in one idiom. */
+interface Operand {
+  value: number;
+  absolute: boolean;
+}
+
+/** Opcodes by mnemonic, zero page first, then absolute. */
+const MEMORY = {
+  lda: [0xa5, 0xad],
+  sta: [0x85, 0x8d],
+  inc: [0xe6, 0xee],
+  dec: [0xc6, 0xce],
+} as const;
+const IMMEDIATE = { lda: 0xa9, adc: 0x69, sbc: 0xe9 } as const;
+const CLC = 0x18;
+const SEC = 0x38;
+const BNE = 0xd0;
+const BCC = 0x90;
+const CMP_ABSOLUTE = 0xcd;
+
+/**
+ * Names the args of a candidate: `address` gives the name of an address in
+ * the knowledge, or undefined. An absolute operand below $0100 keeps four
+ * digits, so ACME writes the absolute form again.
+ */
+export type Namer = (address: number) => string | undefined;
+
+const hex2 = (value: number) => `$${value.toString(16).padStart(2, "0")}`;
+const hex4 = (value: number) => `$${value.toString(16).padStart(4, "0")}`;
+
+function addressArg(operand: Operand, name: Namer): string {
+  const named = name(operand.value);
+  // A name of a zero-page address gives the zero-page form: an absolute operand there keeps its number.
+  if (named !== undefined && (operand.value >= 0x100 || !operand.absolute)) return named;
+  return operand.absolute ? hex4(operand.value) : hex2(operand.value);
+}
+
+/** The memory operand of `instruction` when it is one of the opcodes of the mnemonic. */
+function memory(instruction: Instruction | undefined, mnemonic: keyof typeof MEMORY): Operand | undefined {
+  if (instruction === undefined) return undefined;
+  const index = (MEMORY[mnemonic] as readonly number[]).indexOf(instruction.opcode);
+  return index < 0 ? undefined : { value: instruction.value, absolute: index === 1 };
+}
+
+const same = (a: Operand | undefined, b: Operand | undefined, offset = 0): boolean => a !== undefined && b !== undefined && a.absolute === b.absolute && b.value === a.value + offset;
+const immediate = (instruction: Instruction | undefined, opcode: number) => (instruction?.opcode === opcode ? instruction.value : undefined);
+/** A branch past the next instruction only: its distance is the length of that instruction. */
+const skips = (branch: Instruction | undefined, opcode: number, next: Instruction | undefined) => branch?.opcode === opcode && next !== undefined && branch.value === next.length;
+
+/** Each idiom: how many instructions it takes, and its args when the instructions match. */
+const MATCHERS: Record<string, { count: number; match: (run: Instruction[], name: Namer) => string[] | undefined }> = {
+  inc16: {
+    count: 3,
+    match: ([low, branch, high], name) => {
+      const dst = memory(low, "inc");
+      return same(dst, memory(high, "inc"), 1) && skips(branch, BNE, high) ? [addressArg(dst!, name)] : undefined;
+    },
+  },
+  dec16: {
+    count: 4,
+    match: ([load, branch, high, low], name) => {
+      const dst = memory(load, "lda");
+      return same(dst, memory(low, "dec")) && same(dst, memory(high, "dec"), 1) && skips(branch, BNE, high) ? [addressArg(dst!, name)] : undefined;
+    },
+  },
+  add16_8: {
+    count: 6,
+    match: ([clc, load, add, store, branch, high], name) => {
+      const dst = memory(load, "lda");
+      const value = immediate(add, IMMEDIATE.adc);
+      const ok = clc?.opcode === CLC && value !== undefined && same(dst, memory(store, "sta")) && same(dst, memory(high, "inc"), 1) && skips(branch, BCC, high);
+      return ok ? [addressArg(dst!, name), hex2(value)] : undefined;
+    },
+  },
+  add16: { count: 7, match: (run, name) => wide(run, name, CLC, IMMEDIATE.adc) },
+  sub16: { count: 7, match: (run, name) => wide(run, name, SEC, IMMEDIATE.sbc) },
+  set16: {
+    count: 4,
+    match: ([loadLow, storeLow, loadHigh, storeHigh], name) => {
+      const low = immediate(loadLow, IMMEDIATE.lda);
+      const high = immediate(loadHigh, IMMEDIATE.lda);
+      const dst = memory(storeLow, "sta");
+      if (low === undefined || high === undefined || !same(dst, memory(storeHigh, "sta"), 1)) return undefined;
+      const value = low | (high << 8);
+      return [addressArg(dst!, name), name(value) ?? hex4(value)];
+    },
+  },
+  mov16: {
+    count: 4,
+    match: ([loadLow, storeLow, loadHigh, storeHigh], name) => {
+      const src = memory(loadLow, "lda");
+      const dst = memory(storeLow, "sta");
+      if (!same(src, memory(loadHigh, "lda"), 1) || !same(dst, memory(storeHigh, "sta"), 1)) return undefined;
+      return [addressArg(dst!, name), addressArg(src!, name)];
+    },
+  },
+  wait_line: {
+    count: 3,
+    match: ([load, compare, branch]) => {
+      const line = immediate(load, IMMEDIATE.lda);
+      // BNE back to the CMP: 5 bytes back from the end of the BNE.
+      return line !== undefined && compare?.opcode === CMP_ABSOLUTE && compare.value === 0xd012 && branch?.opcode === BNE && branch.value === 0xfb ? [hex2(line)] : undefined;
+    },
+  },
+};
+
+/** add16 and sub16: the carry, then the low and the high byte, each with an immediate of the 16-bit value. */
+function wide([carry, loadLow, low, storeLow, loadHigh, high, storeHigh]: Instruction[], name: Namer, carryOpcode: number, opcode: number): string[] | undefined {
+  const dst = memory(loadLow, "lda");
+  const lowValue = immediate(low, opcode);
+  const highValue = immediate(high, opcode);
+  const ok =
+    carry?.opcode === carryOpcode && lowValue !== undefined && highValue !== undefined && same(dst, memory(storeLow, "sta")) && same(dst, memory(loadHigh, "lda"), 1) && same(dst, memory(storeHigh, "sta"), 1);
+  return ok ? [addressArg(dst!, name), hex4(lowValue | (highValue << 8))] : undefined;
+}
+
+/** The instruction at `at`, or undefined when a byte of it is outside the range or the image. */
+function instructionAt(byteAt: ImageByte, at: number, end: number): Instruction | undefined {
+  const opcode = byteAt(at);
+  if (opcode === undefined) return undefined;
+  const length = instructionLength(opcode);
+  if (at + length - 1 > end) return undefined;
+  const bytes = Array.from({ length: length - 1 }, (_, offset) => byteAt(at + 1 + offset));
+  if (bytes.some((byte) => byte === undefined)) return undefined;
+  return { opcode, length, value: length === 1 ? 0 : length === 2 ? bytes[0]! : bytes[0]! | (bytes[1]! << 8) };
+}
+
+/**
+ * Finds the macro candidates in code regions. Each region is read as
+ * instructions from its start; at each instruction the idioms of the
+ * catalogue are tried in order, and a match is a candidate. Candidates do not
+ * overlap: the scan goes on after the end of a match.
+ */
+export function findMacroUses(byteAt: ImageByte, regions: ReadonlyArray<{ start: number; end: number }>, name: Namer): MacroCandidate[] {
+  const candidates: MacroCandidate[] = [];
+  for (const region of [...regions].sort((a, b) => a.start - b.start)) {
+    const run: Array<Instruction & { at: number }> = [];
+    for (let at = region.start; at <= region.end; ) {
+      const instruction = instructionAt(byteAt, at, region.end);
+      if (instruction === undefined) break;
+      run.push({ ...instruction, at });
+      at += instruction.length;
+    }
+    for (let index = 0; index < run.length; ) {
+      const found = CATALOGUE.flatMap((idiom) => {
+        const matcher = MATCHERS[idiom.name]!;
+        const part = run.slice(index, index + matcher.count);
+        const args = part.length === matcher.count ? matcher.match(part, name) : undefined;
+        return args === undefined ? [] : [{ idiom, count: matcher.count, args }];
+      })[0];
+      if (found === undefined) {
+        index++;
+        continue;
+      }
+      const last = run[index + found.count - 1]!;
+      candidates.push({ macro: found.idiom.name, start: run[index]!.at, end: last.at + last.length - 1, args: found.args });
+      index += found.count;
+    }
+  }
+  return candidates;
+}

package/skills/c64-testing/SKILL.md

@@ -50,12 +50,19 @@ The run file gives where to start (a program, or a snapshot file), the steps, an
 
 See [references/scenario-format.md](references/scenario-format.md), section Runs. The script prints one JSON object. The exit status is 0 when all steps ran, 1 when a step did not reach its target, and 2 for a bad call. A long run can need more time than one shell call. Then run it in the background.
 
+### 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. Write the scenario file. Start the steps with a frame count, for example `{ "frames": 150 }`. Each side starts at the reset vector, and the C64 needs these frames to start.
 2. Use symbol names, for example `player_x`, not fixed addresses. Each side finds the name in its own symbols. Use a `$` address only when both programs use the same address.
 3. Make each checkpoint a condition, for example `runUntil` at a routine. Do not wait for a time.
-4. Save the c64-assembler output of the rebuild to the symbol file: `assemble.ts ... > build/game.json`.
+4. Save the c64-assembler output of the rebuild to the symbol file, for example `build/game.json` in the project folder. From the folder above the project, write `assemble.ts --project <folder> ... > <folder>/build/game.json`.
 5. Run the test script.
 6. Read the result:
    - `PASS`: all observations are equal, or the differences are in the allowed tolerance.

package/skills/c64-testing/references/scenario-format.md

@@ -23,7 +23,7 @@ A scenario is one JSON object in a project file.
 
 `original` and `rebuild` each have:
 
-- `program`: a PRG file, relative to the project directory.
+- `program`: a PRG file, relative to the project folder.
 - `symbols`: where the names come from:
   - `knowledge`: the project knowledge.
   - A JSON file: the output of the c64-assembler skill, or an object of names and `$` addresses.

package/skills/c64-testing/scripts/checklist.ts

@@ -44,8 +44,8 @@ function run(argv: string[]): string {
 }
 
 await runScript(
-  () => {
-    process.stdout.write(run(process.argv.slice(2)));
+  (argv) => {
+    process.stdout.write(run(argv));
   },
   { usage: USAGE },
 );

package/skills/c64-testing/scripts/run.ts

@@ -19,7 +19,7 @@ import { loadSymbols } from "./scenario.ts";
 
 const USAGE = `run.ts <run.json> --out <dir>
 
-<run.json> is a run file relative to the project directory: where to start,
+<run.json> is a run file relative to the project folder: where to start,
 optional symbols, and the steps. See references/scenario-format.md, section
 Runs. The files that the steps write, and results.json, go into <dir>. The
 result is one JSON object.`;
@@ -171,15 +171,15 @@ async function runFile(path: string, out: string): Promise<{ output: Record<stri
 }
 
 await runScript(
-  async () => {
-    const { values, positionals } = parseArgs({ args: process.argv.slice(2), strict: true, allowPositionals: true, options: { out: { type: "string" }, help: { type: "boolean" } } });
+  async (argv) => {
+    const { values, positionals } = parseArgs({ args: argv, strict: true, allowPositionals: true, options: { out: { type: "string" }, help: { type: "boolean" } } });
     if (values.help) throw new UsageError("");
     if (positionals.length !== 1) throw new UsageError("give one run file");
     if (values.out === undefined) throw new UsageError("run needs --out <dir>");
     try {
       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}`);
     }
     const { output, failed } = await runFile(positionals[0]!, values.out);
     if (failed) process.exitCode = 1;

package/skills/c64-testing/scripts/scenario.ts

@@ -51,7 +51,7 @@ export type Step = StepBody & { side?: Side };
 
 export interface Subject {
   program: string;
-  /** "knowledge" for knowledge.db, a project JSON file (c64-assembler output or a name → "$xxxx" map), or "none". */
+  /** "knowledge" for the project knowledge, a project JSON file (c64-assembler output or a name → "$xxxx" map), or "none". */
   symbols: string;
 }
 

package/skills/c64-testing/scripts/test.ts

@@ -12,7 +12,7 @@ import { readScenario, runScenario, ScenarioError, type ScenarioResult } from ".
 
 const USAGE = `test.ts <scenario.json> [--out <dir>]
 
-<scenario.json> is a scenario file relative to the project directory. See
+<scenario.json> is a scenario file relative to the project folder. See
 references/scenario-format.md. With --out, a FAIL writes both screens, the
 difference image and memory.json with each differing byte into <dir>. The
 result is one JSON object.`;
@@ -27,7 +27,7 @@ async function run(argv: string[]): Promise<ScenarioResult> {
     try {
       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}`);
     }
   }
   try {
@@ -56,8 +56,8 @@ async function runScenarioFile(path: string, out: string | undefined): Promise<S
 }
 
 await runScript(
-  async () => {
-    const result = await run(process.argv.slice(2));
+  async (argv) => {
+    const result = await run(argv);
     process.exitCode = EXIT[result.result];
     return result;
   },

package/skills/c64-unpacker/SKILL.md

@@ -13,7 +13,7 @@ This skill 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.
 - For a capture: the address where the unpacked program starts, and the directory for the result.
 
 ## Tools / execution path
@@ -22,8 +22,8 @@ This skill does not change project knowledge.
 node <skill>/scripts/unpack.ts inspect original/game.prg
 node <skill>/scripts/unpack.ts trace original/game.prg
 node <skill>/scripts/unpack.ts capture original/game.prg --until '$c000' --out unpacked
-node <skill>/scripts/unpack.ts stages original/game.prg --steps input.json
-node <skill>/scripts/unpack.ts loads original/game.d64 --steps parts.json --out parts --drive
+node <skill>/scripts/unpack.ts stages original/game.prg --steps .c64-re-tools/local/input.json
+node <skill>/scripts/unpack.ts loads original/game.d64 --steps .c64-re-tools/local/parts.json --out parts --drive
 ```
 
 `inspect` examines the file locally. `trace` and `capture` start their own emulator through the host runtime and start the program. `trace` runs the program and finds the memory that the program wrote and then executed. `capture` stops the program when the CPU gets to the `--until` address. `stages` runs the program and finds each stage: a decruncher, an intro, a copier, and then the program. For each stage it gives the entry, the frames, the written memory (`wrote`) and the entry of the next stage (`next`). In `stages` and `capture`, a `frames` step and a `runUntil` step with only `at` count as run time. `stages` refuses a `runUntil` step with `raster` or `memory`.
@@ -31,7 +31,7 @@ node <skill>/scripts/unpack.ts loads original/game.d64 --steps parts.json --out
 | Option | Meaning |
 |---|---|
 | `--until '$c000'` | The address where the unpacked program starts. The capture stops there after the steps. To capture a later arrival at the address, add a `runUntil` step to an address after the first arrival. |
-| `--out unpacked/game.prg` | Where to write the result, relative to the project directory. |
+| `--out unpacked/game.prg` | Where to write the result, relative to the project folder. |
 | `--range '$c000' '$cfff'` | Write this range as a PRG. Without it, the script writes all 64 KiB of RAM as a flat file. |
 | `--timeout-frames 3000` | How many frames the program can run before the capture stops (default 3000). |
 | `--frames 3000` | `trace` only: how many frames the program runs (default 3000). |
@@ -51,6 +51,13 @@ A steps file has the steps `write`, `registers`, `joystick`, `type`, `frames` an
 
 A `type` step puts keys in the keyboard queue of the KERNAL. A program that reads the keyboard hardware does not see them. A step cannot press one specific key of the keyboard matrix. A wait for any key that reads all keyboard columns can end without a key.
 
+### 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 `inspect`. Read `basicStart` and `packing`. `basicStart` gives the first SYS line and its address. When the SYS argument needs values at run time, `sys` is null and `expression` gives the argument. Then `trace`, `stages` and `capture` stop at the first instruction after the BASIC text:

package/skills/c64-unpacker/scripts/unpack.ts

@@ -636,7 +636,7 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
     try {
       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}`);
     }
     const minBlock = values["min-block"] === undefined ? 64 : Number(values["min-block"]);
     if (!Number.isInteger(minBlock) || minBlock < 1 || minBlock > 0x10000) throw new UsageError("--min-block must be from 1 to 65536");
@@ -655,7 +655,7 @@ async function run(argv: string[]): Promise<{ output: unknown; failed: boolean }
   try {
     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}`);
   }
   const timeoutFrames = values["timeout-frames"] === undefined ? 3000 : Number(values["timeout-frames"]);
   if (!Number.isInteger(timeoutFrames) || timeoutFrames < 1 || timeoutFrames > 30_000) throw new UsageError("--timeout-frames must be from 1 to 30000");
@@ -674,8 +674,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/src/cli/main.ts

@@ -27,10 +27,12 @@ Usage:
 
 Harnesses: claude, codex, pi, opencode, gemini, copilot, cursor, windsurf
 (comma-separated; default: all). Without --global the files go into the
-current project; with --global into your home directory.
+current folder; with --global into your home directory.
 
-Run it in the project: npx -y ${PACKAGE.name}@${PACKAGE.tag} install. The VICE
-MCP declaration starts the latest c64-re-tools-mcp through npx. The Host
+Run it once at the root of the repository:
+npx -y ${PACKAGE.name}@${PACKAGE.tag} install. Each project folder below
+the root uses that install; a project is a folder with .c64-re-tools/. The
+VICE MCP declaration starts the latest c64-re-tools-mcp through npx. The Host
 Runtime runs on the machine with VICE: start it there with
 npx -y --package=${PACKAGE.name}@${PACKAGE.tag} c64-re-tools-host.
 It runs VICE and the tools that come with it (c1541, petcat). The skill

package/src/host-client/image.ts

@@ -23,7 +23,7 @@ export interface Image {
   statePath?: string;
 }
 
-/** Reads an image.json or a PRG, relative to the project directory. */
+/** Reads an image.json or a PRG, relative to the project folder. */
 export function readImage(path: string): Image {
   const { bytes } = readProjectFile(path);
   if (!path.endsWith(".json")) {