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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henrik Olsson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,61 +1,214 @@
-# @henols/c64-re-tools
+# c64-re-tools
 
-One-command installer that adds the **C64 reverse-engineering skills** and the
-**VICE emulator MCP server** ([`@henols/vice-mcp`](https://www.npmjs.com/package/@henols/vice-mcp))
-to a project, so an MCP client such as Claude Code can drive a Commodore 64
-emulator for reverse-engineering work.
+An agent-friendly Commodore 64 engineering toolkit for reverse engineering
+unknown applications and for developing, debugging, building and testing new
+C64 applications.
 
-## Usage
+An agent drives a real VICE emulator through an MCP server, and uses skills
+for the rest: disk images, BASIC, static analysis with DXA and Ghidra, a project
+knowledge database, the ACME assembler, unpacking, release comparison and
+functional-equivalence tests.
 
-From the project you want to set up:
+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`.
+The design is in [`docs/redesign/`](docs/redesign/README.md), and
+[`docs/plan.md`](docs/plan.md) tracks the implementation.
+
+## Install and start
+
+Requirements:
+
+- Node.js 24 or newer with npx.
+- On the machine with VICE: VICE 3.9 or later (`x64sc`, `c1541`, `petcat`) with its ROM files.
+- Where the agent runs: ACME, DXA and Ghidra, for the skills that use them.
+
+Everything runs through npx. Nothing is installed globally.
+
+### Release or prerelease
+
+| Channel | Version |
+| --- | --- |
+| `latest` | The current release. |
+| `next` | The current prerelease, for example `2.0.0-rc.1`. |
+
+Until 2.0.0 is released, `latest` is the old 1.1.0. Use `next` until then. In the commands below, replace `<channel>` with `latest` or `next`. Use the same channel on both machines.
+
+### On one machine
+
+Start the Host Runtime in its own terminal. Ctrl+C stops it and every emulator:
+
+```
+npx -y --package=@henols/c64-re-tools@<channel> c64-re-tools-host
+```
+
+Install into the project, check it, and start the agent:
+
+```
+cd my-c64-project
+npx -y @henols/c64-re-tools@<channel> install --target claude
+npx -y @henols/c64-re-tools@<channel> status
+claude
+```
+
+### In a dev container
+
+On the host, start the Host Runtime on the container bridge with a shared secret:
+
+```
+export C64RT_HOST_TOKEN=$(openssl rand -hex 16)
+npx -y --package=@henols/c64-re-tools@<channel> c64-re-tools-host --listen 172.17.0.1
+```
+
+In the container, set the same `C64RT_HOST_TOKEN`, then:
+
+```
+npx -y @henols/c64-re-tools@<channel> install --target claude
+npx -y @henols/c64-re-tools@<channel> status
+claude
+```
+
+The container reaches the host as `host.docker.internal`. `status` must show the Host Runtime as reachable.
+
+### Update and remove
 
-```sh
-npx @henols/c64-re-tools
 ```
+npx -y @henols/c64-re-tools@<channel> update      # the newest skills into the project
+npx -y @henols/c64-re-tools@<channel> uninstall
+```
+
+Restart the Host Runtime after a new release. `--global` installs into your home directory.
+
+### Debugging
+
+See [docs/debugging.md](docs/debugging.md) for the trace and the field test.
+
+### Settings
+
+| Variable | Read by | Meaning |
+| --- | --- | --- |
+| `C64RT_VICE` | host | Full path of `x64sc` when it is not on `PATH`. |
+| `C64RT_C1541`, `C64RT_PETCAT` | host | Full path of the tool when it is not on `PATH`. |
+| `C64RT_ACME`, `C64RT_DXA` | skills, CLI | Full path of the tool when it is not on `PATH`. |
+| `C64RT_GHIDRA` | skills, CLI | The Ghidra installation directory, when `analyzeHeadless` is not on `PATH`. |
+| `C64RT_HOST` | MCP, skills, CLI | `host:port` of the Host Runtime when it is not on 127.0.0.1, `host.docker.internal` or `host.containers.internal` at 6464. |
+| `C64RT_HOST_TOKEN` | host, MCP, skills, CLI | The shared secret for a Host Runtime that listens beyond loopback. |
+| `C64RT_VIDEO` | MCP | `pal` (default) or `ntsc`, fixed for the life of the MCP process. |
+| `C64RT_TRACE` | host, MCP, skills, CLI | A directory for a trace of what the programs do, for a person who debugs a run. See [docs/debugging.md](docs/debugging.md). Nothing of the trace reaches the agent. |
+
+Ghidra runs with its own settings directory for each request. The toolkit
+brings its own NMOS 6510 language (all 256 opcodes); your Ghidra installation
+and settings stay unchanged.
 
-That will:
+## Use it with an agent
 
-1. Copy the bundled skills into `<project>/.claude/skills/`
-2. Add a `vice` server to `<project>/.mcp.json` (existing servers are preserved),
-   launched via `npx -y @henols/vice-mcp`
+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.
+4. Ask for the result you want, in plain words. The agent picks the skills and the `c64_*` tools.
+
+Examples:
+
+```
+Reverse engineer original/game.d64. Find how it starts, unpack it if it is packed,
+and name the main routines in project knowledge.
+
+Find the routine that draws the score, and explain how it works.
+
+Write a program in ACME that scrolls a text at the bottom of the screen.
+Build it, run it in the emulator, and write a test for it.
+
+Show me the emulator window.
+```
 
-Then restart Claude Code in that project.
+The agent keeps what it learns about the program in `.c64-re-tools/knowledge.db`. Commit that file with the project.
 
-### Options
+## Skills
 
-| Option | Effect |
+| Skill | Use |
 | --- | --- |
-| `[targetDir]` | Install into this directory instead of the current one. |
-| `--force` | Overwrite existing skills and an existing `vice` MCP entry. |
-| `--vendor` | Also `npm install -D @henols/vice-mcp` into the project and wire `.mcp.json` to the local copy (pinned / offline), instead of `npx`. |
-| `--dry-run`, `-n` | Show what would change without writing anything. |
-| `--help`, `-h` | Show help. |
+| c64-reverse-engineering | Coordinates an investigation and picks the specialist for the next unknown. |
+| c64-emulator | Runs and observes the program in VICE through the MCP tools. |
+| c64-static-analysis | A fast first pass with DXA and a deeper pass with Ghidra into knowledge, with seeds from knowledge and decompilation. |
+| c64-knowledge | Reads and writes symbols, regions, comments and references, with history. |
+| c64-disk | Directory, BAM, entries, sector chains and extraction of disk images. |
+| 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-assembler | ACME builds with diagnostics and symbols. |
+| c64-testing | Original-against-rebuild scenarios with PASS, FAIL or INCONCLUSIVE. |
+
+## Examples
+
+Reverse engineering, from an unknown disk to a verified rebuild (the commands
+that the skills run for the agent; `<skills>` is the installed skills
+directory):
 
-Re-running is safe: existing skills and an existing `vice` entry are kept unless
-you pass `--force`.
+```
+node <skills>/c64-disk/scripts/disk.ts directory original/game.d64
+node <skills>/c64-disk/scripts/disk.ts read original/game.d64 GAME --out extracted/game.prg
+node <skills>/c64-basic/scripts/basic.ts extracted/game.prg                  # the SYS address, e.g. $080d
+node <skills>/c64-unpacker/scripts/unpack.ts inspect extracted/game.prg
+node <skills>/c64-static-analysis/scripts/analyze.ts extracted/game.prg --analyzer dxa --listing analysis/game.lst
+node <skills>/c64-static-analysis/scripts/analyze.ts extracted/game.prg --entry '$080d'
+node <skills>/c64-knowledge/scripts/knowledge.ts rename '$080d' main --kind routine --reason 'entry from BASIC'
+node <skills>/c64-static-analysis/scripts/analyze.ts extracted/game.prg --entry '$080d' --decompile '$080d'
+node <skills>/c64-assembler/scripts/assemble.ts --source-root src --entry game.a --out build/game.prg > build/game.json
+node <skills>/c64-testing/scripts/test.ts tests/counts.json                   # PASS, FAIL or INCONCLUSIVE
+```
+
+Development: build with the c64-assembler skill, then load and debug with the
+MCP tools (`c64_program_load`, `c64_breakpoint`, `c64_run_until`,
+`c64_memory_read`, `c64_screen`), and test with the c64-testing skill.
+
+## Developing
+
+To work on the toolkit itself, Node 24 or newer and pnpm are required; install pnpm yourself (for example
+`corepack enable pnpm`). `packageManager` in `package.json` pins its version.
+
+```
+pnpm install --frozen-lockfile
+pnpm typecheck     # tsc checks everything; it emits nothing
+pnpm test          # node --test on src/**/*.test.ts and test/**/*.test.ts
+```
+
+Unit tests sit beside their source as `src/**/*.test.ts`; `test/` holds
+integration and end-to-end tests. Node runs the TypeScript directly (type
+stripping), so relative imports name the `.ts` file. Skill scripts import
+`src/` as `#src/...` (the `imports` map in `package.json`); an installed skill
+gets the `src/` modules it reaches and its own `package.json` with that map.
 
-## What gets installed
+Tests that need real tools are opt-in. Without them they are reported as
+skipped, never as passed:
 
-- **Skills** — `acme-build`, `c64-memory-mapping`, `c64-program-recon`,
-  `c64-provenance-diff`, `c64-ram-capture`, `vice-wedge-triage`.
-- **MCP server** — `@henols/vice-mcp`, exposing the `vice` tools.
+```
+C64RT_LIVE_VICE=/usr/bin/x64sc C64RT_GHIDRA=/opt/ghidra pnpm test
+```
 
-## Requirements
+ACME, DXA, c1541 and petcat tests run when the tools are on `PATH`.
 
-- **This installer** runs on Node ≥ 18.
-- **The VICE MCP server** it wires up requires **Node ≥ 24**, and a
-  host with VICE (`x64sc`) reachable from the MCP client. See the
-  [`@henols/vice-mcp`](https://www.npmjs.com/package/@henols/vice-mcp) readme.
+To release, push a tag on a commit of `main`. The tag gives the version:
+
+```
+git tag v2.0.0-rc.2 && git push origin v2.0.0-rc.2   # a prerelease, to npm next
+git tag v2.0.0      && git push origin v2.0.0        # a release, to npm latest
+```
 
-## Alternative: Claude Code plugin
+CI checks and tests the tagged commit, publishes it to npm and makes a GitHub Release. The repository keeps the version `0.0.0-development`.
 
-If you use Claude Code, you can instead install everything as a plugin:
+## Layout
 
 ```
-/plugin marketplace add henols/c64-re-tools
-/plugin install c64-re-tools@c64-re-tools
+src/             # mcp, host, host-client, native, knowledge, cli; unit tests beside the source
+skills/          # the skills: SKILL.md, scripts (TypeScript) and references
+distribution/    # the AP SDK plugin definition: skills with the src/ modules they reach
+test/            # fixtures, integration and end-to-end tests
+docs/redesign/   # the design
 ```
 
 ## License
 
-MIT © Henrik Olsson
+MIT. See [`LICENSE`](./LICENSE).

package/distribution/package.ts

@@ -0,0 +1,36 @@
+// The npm package and the VICE MCP declaration that starts it. This module
+// only reads package.json, so a caller that needs the declaration does not
+// build the plugin.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * The npm dist-tag that a version is published under: a prerelease
+ * (2.0.0-rc.1) goes to "next", a release to "latest".
+ */
+export function channelOf(version: string): "latest" | "next" {
+  return version.includes("-") ? "next" : "latest";
+}
+
+/** The name, version and dist-tag of this npm package, from its package.json. */
+export const PACKAGE = (() => {
+  const metadata = JSON.parse(readFileSync(join(import.meta.dirname, "..", "package.json"), "utf8")) as { name: string; version: string };
+  return { name: metadata.name, version: metadata.version, tag: channelOf(metadata.version) };
+})();
+
+/**
+ * The agent starts the MCP server through npx with the newest version of the
+ * channel it was installed from, so it updates itself and an install from a
+ * prerelease does not start a release; nothing is linked or installed globally.
+ * The entry point is TypeScript, run by tsx: Node does not strip types under
+ * node_modules.
+ */
+export function mcpServerFor(platform: NodeJS.Platform): { command: string; args: string[] } {
+  const npx = ["-y", `--package=${PACKAGE.name}@${PACKAGE.tag}`, "c64-re-tools-mcp"];
+  // On native Windows npx is a .cmd shim, which a harness starts only through cmd /c.
+  return platform === "win32" ? { command: "cmd", args: ["/c", "npx", ...npx] } : { command: "npx", args: npx };
+}
+
+/** The declaration for the machine where install runs: the plugin is evaluated there. */
+export const MCP_SERVER = mcpServerFor(process.platform);

package/distribution/plugin.ts

@@ -0,0 +1,120 @@
+// The portable c64-re-tools plugin for @jalco/ap-sdk: the skills
+// with their TypeScript scripts, the src/ modules those scripts reach, their
+// references, and the VICE MCP declaration. AP SDK maps it to each harness's
+// native layout; nothing at run time depends on it.
+//
+// Nothing is built: an installed skill holds the same .ts files as this
+// repository, and Node runs them by type stripping. Skill scripts import
+// src/ through the "#src/*" subpath import; each installed skill gets a
+// package.json that maps it to its own copy of those modules.
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+import { definePlugin, defineSkill, type Skill } from "@jalco/ap-sdk";
+
+import { MCP_SERVER, PACKAGE } from "./package.ts";
+
+const root = resolve(import.meta.dirname, "..");
+const SOURCE = join(root, "src");
+const SCRIPT_REFERENCE = /scripts\/([a-z][a-z0-9-]*)\.ts/g;
+/**
+ * The modules a file reaches: static and dynamic imports, re-exports, and
+ * new URL("...", import.meta.url) for a module that is spawned or an asset
+ * directory. Only relative and #src specifiers; packages are node: built-ins.
+ */
+const SPECIFIER = /(?:\bfrom\s*|\bimport\s*\(?\s*|\bnew URL\(\s*)(["'])((?:\.\.?\/|#src\/)[^"']*)\1/g;
+
+/**
+ * The package.json of an installed skill: ES modules, #src/* resolved inside
+ * the skill, and the version of c64-re-tools that the copy comes from.
+ */
+export const SKILL_PACKAGE = `${JSON.stringify({ type: "module", version: PACKAGE.version, imports: { "#src/*": "./src/*" } }, null, 2)}\n`;
+
+/** The scripts that a SKILL.md runs, by file name. */
+export function scriptsOf(skillMarkdown: string): string[] {
+  return [...new Set([...skillMarkdown.matchAll(SCRIPT_REFERENCE)].map((match) => match[1]!))].sort();
+}
+
+function filesBelow(directory: string): string[] {
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory, { recursive: true, encoding: "utf8" })
+    .map((path) => join(directory, path))
+    .filter((path) => statSync(path).isFile())
+    .sort();
+}
+
+const inside = (directory: string, path: string) => path === directory || path.startsWith(directory + sep);
+
+/**
+ * Every file that the given scripts reach, transitively: the scripts, their
+ * sibling modules, and the src/ modules and asset directories below them.
+ * A reach out of the skill directory and src/ is an error.
+ */
+export function closureOf(skillDirectory: string, scripts: readonly string[]): string[] {
+  const found = new Set<string>();
+  const pending = [...scripts];
+  while (pending.length > 0) {
+    const file = pending.pop()!;
+    if (found.has(file)) continue;
+    if (!inside(SOURCE, file) && !inside(skillDirectory, file)) throw new Error(`${relative(root, file)} is outside the skill and src/`);
+    if (!existsSync(file)) throw new Error(`${relative(root, file)} does not exist`);
+    if (statSync(file).isDirectory()) {
+      pending.push(...filesBelow(file));
+      continue;
+    }
+    found.add(file);
+    if (!file.endsWith(".ts")) continue;
+    for (const match of readFileSync(file, "utf8").matchAll(SPECIFIER)) {
+      const specifier = match[2]!;
+      pending.push(specifier.startsWith("#src/") ? join(SOURCE, specifier.slice("#src/".length)) : resolve(dirname(file), specifier));
+    }
+  }
+  return [...found].sort();
+}
+
+/** One skill: SKILL.md frontmatter and body, scripts (executable), the src/ modules they reach, and references. */
+function loadSkill(directory: string): Skill {
+  const text = readFileSync(join(directory, "SKILL.md"), "utf8");
+  const frontmatter = /^---\n([\s\S]*?)\n---\n/.exec(text);
+  if (frontmatter === null) throw new Error(`${directory}/SKILL.md has no frontmatter`);
+  const field = (name: string) => {
+    const value = new RegExp(`^${name}: (.+)$`, "m").exec(frontmatter[1]!)?.[1];
+    if (value === undefined) throw new Error(`${directory}/SKILL.md has no ${name}`);
+    return value;
+  };
+  const scripts = scriptsOf(text).map((script) => join(directory, "scripts", `${script}.ts`));
+  const code = closureOf(directory, scripts).map((path) => ({
+    path: (inside(SOURCE, path) ? relative(root, path) : relative(directory, path)).split("\\").join("/"),
+    content: readFileSync(path, "utf8"),
+    ...(scripts.includes(path) ? { executable: true } : {}),
+  }));
+  const references = filesBelow(join(directory, "references")).map((path) => ({ path: relative(directory, path).split("\\").join("/"), content: readFileSync(path, "utf8") }));
+  const resources = [...code, ...references, ...(scripts.length > 0 ? [{ path: "package.json", content: SKILL_PACKAGE }] : [])];
+  return defineSkill({
+    name: field("name"),
+    description: field("description"),
+    instructions: text.slice(frontmatter[0].length).replace(/^\n+/, ""),
+    ...(resources.length > 0 ? { resources } : {}),
+  });
+}
+
+function c64Plugin() {
+  const skills = readdirSync(join(root, "skills"), { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort()
+    .map((name) => loadSkill(join(root, "skills", name)));
+  return definePlugin({
+    id: "c64-re-tools",
+    version: PACKAGE.version,
+    description: "Commodore 64 reverse engineering and development: a live VICE emulator, static analysis, disk and BASIC tools, project knowledge, building and testing.",
+    author: { name: "Henrik Olsson" },
+    homepage: "https://github.com/henols/c64-re-tools",
+    license: "MIT",
+    skills,
+    mcpServers: { "c64-re-tools": MCP_SERVER },
+  });
+}
+
+export default c64Plugin();

package/package.json

@@ -1,55 +1,49 @@
 {
   "name": "@henols/c64-re-tools",
-  "version": "1.1.0",
-  "description": "Installer that adds the C64 reverse-engineering skills and the VICE emulator MCP server (@henols/vice-mcp) to a project.",
+  "version": "2.0.0-rc.2",
+  "description": "Agent-friendly Commodore 64 engineering toolkit for reverse engineering, debugging, development and testing.",
+  "license": "MIT",
+  "author": "Henrik Olsson",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/henols/c64-re-tools.git"
+  },
   "type": "module",
+  "packageManager": "pnpm@12.9.1+sha512.06b055fff5cd20dc12781de173ced3310ce0951bf2ec620211a16045d5444d5c93a663210764ef29a653a610459ba0368f0e74f84d80c54723cf95aae7bc0d6d",
+  "imports": {
+    "#src/*": "./src/*"
+  },
   "bin": {
-    "c64-re-tools": "bin/cli.mjs"
+    "c64-re-tools": "src/cli/main.ts",
+    "c64-re-tools-mcp": "src/mcp/main.ts",
+    "c64-re-tools-host": "src/host/main.ts"
   },
   "files": [
-    "bin/",
+    "src/",
+    "!src/**/*.test.ts",
+    "!src/**/*.testkit.ts",
     "skills/",
-    "README.md",
-    "THIRD-PARTY-NOTICES.md"
+    "distribution/package.ts",
+    "distribution/plugin.ts",
+    "LICENSE",
+    "README.md"
   ],
   "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "license": "MIT",
-  "author": {
-    "name": "Henrik Olsson",
-    "url": "https://github.com/henols"
+    "node": ">=24.0.0"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/henols/c64-re-tools.git",
-    "directory": "installer"
+  "scripts": {
+    "host": "node src/host/main.ts",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test \"src/**/*.test.ts\" \"test/**/*.test.ts\""
   },
-  "homepage": "https://github.com/henols/c64-re-tools#readme",
-  "bugs": {
-    "url": "https://github.com/henols/c64-re-tools/issues"
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "typescript": "7.0.2"
   },
-  "keywords": [
-    "c64",
-    "commodore-64",
-    "vice",
-    "6502",
-    "6510",
-    "acme",
-    "reverse-engineering",
-    "mcp",
-    "claude",
-    "installer"
-  ],
   "dependencies": {
-    "@henols/vice-mcp": "1.1.0"
-  },
-  "scripts": {
-    "sync-skills": "node scripts/sync-skills.mjs",
-    "prepack": "node scripts/sync-skills.mjs",
-    "test": "node --test '*.test.mjs'"
+    "@modelcontextprotocol/sdk": "1.32.0",
+    "zod": "4.6.5",
+    "@jalco/ap-sdk": "0.4.1",
+    "tsx": "4.23.15"
   }
 }

package/skills/c64-assembler/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: c64-assembler
+description: Use this skill to assemble C64 6510 source code with the ACME assembler and write the program (PRG) into the project. It reports source errors with file and line, and the symbols with their addresses or values. Use it to build a rebuilt or new program. Do not use it to run the program. Give the PRG to the c64-emulator skill for that.
+---
+
+# c64-assembler
+
+## Purpose
+
+Assemble C64 source code with ACME. Write the program into the project. Report diagnostics and symbols.
+
+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 entry source: the main file, relative to the source root.
+- The output path: where to write the PRG, relative to the project directory.
+- Optional include directories, symbol definitions and a start address.
+
+## Tools / execution path
+
+The script runs ACME on this machine. It copies the source root to a temporary directory, assembles it there and writes the program into the project. The host runtime is not necessary.
+
+```
+node <skill>/scripts/assemble.ts --source-root src --entry main.a --out build/game.prg
+```
+
+| Option | Meaning |
+|---|---|
+| `--include lib` | An include directory, relative to the source root. Use it again for more directories. |
+| `--define DEBUG=1` | An assembler symbol: an integer, also as `$` hex, or `true` or `false`. Use it again for more symbols. |
+| `--set-pc '$0801'` | The start address when the source does not set one. |
+
+The script copies the full source root. Put all files that the program includes under it. Version control directories stay out.
+
+The script prints one JSON object. The target CPU is the 6510 and the output is always a C64 PRG.
+
+## Workflow
+
+1. Find the source root and the entry source. The entry source sets its own start address with `* = $0801` or similar.
+2. Run the script.
+3. If `assembled` is `true`, the PRG is at `output`. `loadRange` tells where it loads. `symbols` gives each symbol as an `address` or a `value`.
+4. If `assembled` is `false`, read `diagnostics`. Each one has a severity, a file, a line and a message. Correct the source and run the script again.
+5. To run the program, give the PRG path to the c64-emulator skill.
+
+## Knowledge
+
+Automatic write:
+- none.
+
+Do not store:
+- diagnostics
+- build output
+
+A symbol from the rebuilt source can give the address of a routine in the rebuild. Use it to compare runs with the c64-testing skill.
+
+## Result
+
+The PRG in the project at the output path, with its load range and symbols. Or the source diagnostics when the assembly failed.
+
+The exit status is 0 for a PRG. The exit status is 1 for `assembled: false` and for an error. The exit status is 2 for a wrong argument.
+
+## Failure and conflicts
+
+- `assembled: false`: the source has errors. This is a normal result. Correct the source.
+- `installation-incomplete`: ACME is not installed on this machine. Tell the user the message.
+- `invalid-input`: an option or a path is wrong. Read the message and correct the call.
+
+## Handoffs
+
+- Run or debug the program → c64-emulator
+- Compare the rebuild with the original → c64-testing