modwright 0.1.0

package/LICENSE

@@ -0,0 +1,35 @@
+MIT License
+
+Copyright (c) 2026 Jonathan Trachtenberg
+
+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.
+
+---
+
+Output you generate is yours.
+
+Files that the Software writes into your own projects, such as scaffold output,
+generated manifests and configuration, build artifacts and deploy plans,
+belong to you. The license above does not apply to them, and no attribution to
+ModWright is required, whether you publish, sell or relicense your mods. This
+paragraph grants rights and adds no conditions to the license above.
+
+Templates and other data the Software extracts from a game installed on your
+machine are the game publisher's material, read from your own copy. ModWright
+claims no rights in them, and they are not part of the Software.

package/README.md

@@ -0,0 +1,212 @@
+# ModWright
+
+A game-agnostic [MCP](https://modelcontextprotocol.io) server for game modding.
+
+ModWright gives an AI assistant the tools a modder uses:
+- finding game installs and mod folders, and reading load orders;
+- triaging logs, and checking loader and framework versions against the game
+  build;
+- looking up the game's own data and a knowledge base of sourced facts;
+- scaffolding, validating, building and deploying your mod;
+- talking to the running game through an in-game bridge, where the game
+  supports one.
+
+The core is generic. Each game is a **surface**: one module that declares
+where things live and what the rules are, so every tool works for every
+supported game.
+
+**Status:** 0.x. The tools are exercised against real installs and real mod
+projects, but the API is not stable yet.
+
+## Why
+
+Every game's modding stack is idiosyncratic, and the idiosyncrasies are exactly
+what an assistant needs to know:
+
+- **Cyberpunk 2077** has *six* independent mod systems in one install
+  directory. A RED4ext version mismatch after a patch silently disables a
+  whole category of mods, and the evidence is in a log four folders deep.
+- **Baldur's Gate 3** keeps mods in the user profile, not the install. A
+  `.pak` is inert until it appears in `modsettings.lsx`, which the game
+  rewrites on launch, dropping the entries it cannot resolve.
+- **Skyrim**'s load order is a text file, and its real conflicts are
+  record-level inside plugins, not files on disk.
+
+Without that context an assistant guesses. ModWright supplies it as structured
+data, and returns the game's own caveats alongside every result.
+
+## Install
+
+Node.js 20 or newer is required. Register ModWright with your MCP client. For
+Claude Code:
+
+```bash
+claude mcp add modwright -- npx -y modwright
+```
+
+Or add it to any MCP client's configuration:
+
+```json
+{
+  "mcpServers": {
+    "modwright": { "command": "npx", "args": ["-y", "modwright"] }
+  }
+}
+```
+
+## First steps
+
+Ask your assistant to run `list_games`, then `check_toolchain` for your game.
+`check_toolchain` says what works now and what each feature still needs, for
+example: "Ready now: logs, compat. index needs a Jotunn checkout; build works
+without tcli." Most features need nothing. ModWright can install some
+external tools itself, and any other tool or data folder only has to be
+pointed at once.
+
+## Supported games
+
+| Surface | Game | Mod systems modeled |
+|---|---|---|
+| `cyberpunk2077` | Cyberpunk 2077 | legacy archives, REDmod, redscript, TweakXL, ArchiveXL, RED4ext, CET; the TweakDB vanilla index; garment, vehicle, tweak and packaging validators; the CET bridge |
+| `baldursgate3` | Baldur's Gate 3 | `.pak` mods, loose overrides, Script Extender, the native mod loader; the stats, GUID and handle vanilla index; stats, story, progression and visual-bank validators; the Script Extender bridge |
+| `skyrimse` | Skyrim Special Edition | plugins, BSA archives, SKSE plugins, loose files |
+| `eldenring` | Elden Ring | me3 profiles, Mod Engine 2 overlay and DLLs, UXM loose files; paramdef-typed param exports, the `.me3` profile, package-layout and DCX rules |
+| `valheim` | Valheim | BepInEx plugins, patchers, config, MonoMod, the Doorstop loader; Thunderstore packaging, plugin-source and config rules; the vanilla index from Jötunn's dumps |
+| `stardewvalley` | Stardew Valley | SMAPI mods and Content Patcher packs, the load-order override lists, SMAPI's log; the manifest and `content.json` rules; the wiki schema index, built from the wiki's data pages, which `check_toolchain` fetches for you |
+| `subnautica2` | Subnautica 2 | `~mods` paks, LogicMods, UE4SS mods, DLC-style plugins; triplet, mount-point, TOC and UE4SS-shape rules |
+| `nivalisnights` | Nivalis Nights | BepInEx 6 IL2CPP plugins, patchers, config, generated interop, MelonLoader mods; the vanilla index (items, recipes, vendors, venues, NPCs, by GUID) built from your install with Cpp2IL and UnityPy |
+
+Installs are auto-detected from Steam (every library folder), plus GOG and
+Epic paths where they apply. Override with `installPath` on any tool, or set
+`MODWRIGHT_<SURFACE_ID>_ROOT`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `list_games` | Every supported game, its modding model, and whether an install was found. Start here. |
+| `detect_install` | Locate one game, and report every mod root and log source, marking which exist. |
+| `list_mods` | Enumerate installed mods across all roots, with sizes, timestamps and parsed manifests. |
+| `inspect_mod` | Full detail on one mod: files owned, manifest, warnings. |
+| `find_conflicts` | Paths claimed by more than one mod, restricted to roots where that is actually possible. |
+| `load_order` | Read the game's explicit load order and cross-check it against what is installed. |
+| `load_order_diff` | Snapshot the load order before a launch, then report what the game dropped, added or reordered (BG3 `modsettings.lsx`). |
+| `read_log` | Tail a mod-related log (redscript, RED4ext, CET, SKSE, BG3SE, BepInEx, SMAPI and more). |
+| `triage_logs` | Read every mod log for the current run and classify lines against known failure signatures. It returns one verdict: which systems loaded, what failed first, and the usual fix. |
+| `check_compat` | Detect the game build, loaders, frameworks and tools, and check them against cited compatibility floors. |
+| `check_toolchain` | Locate the external tools (LSLib divine, WolvenKit CLI, Blender, Cpp2IL and others), report each one's path and version (never guessed), and say what each feature needs. It also remembers a tool or data folder you point it at, and installs the tools ModWright can install. |
+| `project_info` | Load a `modwright.json` mod project: sources, build, deploy targets, dependencies and publish targets, with paths resolved and structural warnings. |
+| `lookup` | Search the knowledge base of game and toolchain facts (each with a status and a source), the validator catalogue, or the game's vanilla index you built locally. |
+| `build_index` | Extract and index the game's own data into a local SQLite file in ModWright's cache. Never redistributed. |
+| `validate` | Run the static validators over a mod project: syntax, reference integrity against the vanilla index, known crash causes and silent failures, packaging hygiene. Each finding names the file, the fix and the facts behind the rule. `rule` re-runs one rule by id; explained findings can be suppressed with a reason. |
+| `build` | Run a project's build steps: stage sources into a clean tree, run the typed pack/convert/verify steps, and write a manifest of every input and output with content hashes. The cheap validators gate the build. |
+| `deploy` | Copy a built mod into the game's mod roots as one write plan. It refuses an artifact the build did not produce or one older than its sources, prunes what a previous build left behind, and defers a file the running game holds locked. Every overwrite and delete is backed up first. |
+| `rollback` | List the deploy backups under a project's `.modwright/backups/`, or restore one, re-checking every file's hash first. |
+| `reload_plan` | Classify deployed changes into hot / hot-degraded / save-reload / restart / unknown, with the caveat for each and the single most conservative recommendation. |
+| `bridge` | The in-game bridge (BG3 Script Extender, Cyberpunk 2077 CET): `stage` the bridge into a project, check its heartbeat with `status`, `arm` a probe request and `poll` for its result. |
+| `run_tests` | Run a mod's in-game test plan (`<mod>/tests/*.yaml`) through the bridge. Probe rows are armed and polled; manual rows become a checklist. Results are written back into the plan. |
+| `ledger` | Track claims and decisions across a fix (`<mod>/ledger/`). A claim moves `authored → checker-clean → built → verified \| contradicted`, and nothing is verified without evidence. |
+| `convert` | Run one registered conversion: BG3 lsx↔lsf and xml↔loca through divine, Cyberpunk cr2w↔json through WolvenKit CLI. Each one checks its own round trip. |
+| `diff` | Field-diff two parsed documents (cr2w-json, lsx, loca-xml) with type-aware equality, or diff a file against a cached template. |
+| `template` | Extract one file from your own install into an untracked per-game-version cache, to start a mod file from the game's own. A template is never committed, and `validate` blocks a build that ships one verbatim. |
+| `scaffold` | Declarative scaffolds (`new-project`, BG3 spells, passives, statuses, items, quests and class injections; Cyberpunk tweaks, item chains, sector nodes, garments, liveries, player replacers and more; Stardew Content Patcher and SMAPI C# projects), with ids allocated and collision-checked against your project, the vanilla index and the load order. `plan` walks an authoring sequence for a whole mod type and asks for each asset at the step that needs it. `claude-assets` writes optional Claude Code skills and agents into your mod repo. |
+
+Every tool that writes is **dry-run by default**: it describes the plan and
+writes nothing until you apply it.
+
+## Workflow prompts
+
+Seven workflow prompts walk the authoring loop in any MCP client
+(`prompts/list`, `prompts/get`):
+- `mw-validate`, `mw-scaffold`, `mw-verify` and `mw-ship`;
+- `mw-author`, which walks a whole mod type's scaffold sequence;
+- the per-game `mw-new-spell` (BG3) and `mw-new-item` (Cyberpunk).
+
+Each takes an optional `path` to your mod project. Claude Code lists them as
+`/modwright:mw-ship` and so on.
+
+## From a shell
+
+```bash
+npx modwright tool list                       # every tool and its parameters
+npx modwright tool call list_games
+npx modwright tool call check_toolchain game=valheim
+npx modwright tool call scaffold --args-file args.json
+npx modwright tool prompt mw-ship path=<your mod>
+npx modwright --help
+```
+
+- **Arguments:** a `key=value` value is parsed as JSON when it parses, and
+  taken as a string otherwise. `--json '<object>'` and `--args-file <file>`
+  supply a whole argument object. Use the file form for nested inputs on
+  Windows, where shell quoting of JSON is unreliable.
+- **Output:** `--out` writes the result to a file.
+- **Exit code:** 1 when the tool reports an error.
+
+## Where ModWright keeps its state
+
+Vanilla indexes go in a per-user cache, the same for every session and every
+project:
+
+| | Indexes | Managed tools and snapshots |
+|---|---|---|
+| Windows | `%LOCALAPPDATA%\ModWright\cache` | `%LOCALAPPDATA%\ModWright` |
+| macOS | `~/Library/Caches/ModWright` | `~/Library/Application Support/ModWright` |
+| Linux | `$XDG_CACHE_HOME/modwright` (`~/.cache/modwright`) | `$XDG_DATA_HOME/modwright` |
+
+- **Tools you point ModWright at** are remembered in a per-user
+  `config.json` (`%APPDATA%\ModWright`, `~/.config/modwright`, or
+  `~/Library/Application Support/ModWright`). Record one with
+  `check_toolchain action=remember tool=<id> toolPath=<path> mode=apply`.
+  Lookup order: a `MODWRIGHT_TOOL_*` variable, then a project's `toolchain`
+  override, then that config, then ModWright's managed tools folder, then
+  PATH, then common install locations.
+- **Data folders** that a feature reads are remembered the same way
+  (`check_toolchain action=remember data=valheim.jotunn dataPath=<folder>
+  mode=apply`). Stardew Valley's wiki pages ModWright fetches itself:
+  `check_toolchain action=install data=stardewvalley.wiki` lists every page
+  first, and `mode=apply` fetches them (about a minute, one request a second,
+  honouring the wiki's robots.txt), saves them on your machine and remembers
+  the folder. The wiki's text is CC BY-NC-SA, and ModWright never
+  redistributes it.
+- **Some tools ModWright can install for you.**
+  `check_toolchain action=install tool=cpp2il` shows exactly what it would
+  fetch (URL, size, sha256, destination); `mode=apply` installs it. Downloads
+  are pinned and checked before anything is written.
+- **Overrides:** `MODWRIGHT_CACHE_DIR` moves the cache; `MODWRIGHT_HOME`
+  moves everything.
+- **Project state** stays in the project's own `.modwright/`.
+
+## What it deliberately does not do
+
+These are honest limits, not bugs. Each one is a place where guessing would
+produce confident nonsense:
+
+- **Conflicts inside packed archives.** `.archive`, `.pak` and `.bsa` mods
+  conflict on resources *inside* them. ModWright marks those roots `opaque` and
+  reports them as skipped rather than comparing filenames.
+- **Conflicts in isolated roots.** Where each mod owns its own subtree (CET,
+  redscript, REDmod), two mods both containing `init.lua` is not a conflict, and
+  ModWright will not report it as one.
+- **BG3 load order to pak mapping.** A pak's filename is arbitrary and rarely
+  matches its module name; the only sound link is the UUID in `meta.lsx` inside
+  the pak. ModWright reports the order and says plainly that the cross-check is
+  unavailable rather than emitting false positives.
+- **Skyrim record-level conflicts.** Those need xEdit. Directory comparison
+  under `Data/` is not a substitute.
+- **Writing where you did not ask.** Writers are dry-run by default, write
+  only where the project file says, and back up whatever they replace.
+  `deploy` reports the `modsettings.lsx` entry a loose BG3 deploy needs, but
+  never edits that file, because a mod manager may own it.
+- **Acting on a running game unasked.** `reload_plan` classifies what a
+  change needs. A hot reload (Cyberpunk, through Red Hot Tools) or an
+  in-game probe that changes state runs only when the caller grants it, and
+  what it did is confirmed by a read-back, not assumed.
+- **Redistributing game data.** Indexes and templates are built from your
+  own install, on your machine, and never shipped.
+
+## License
+
+MIT; see LICENSE. Files ModWright generates into your own projects are
+yours, with no attribution required. Data extracted from a game remains its
+publisher's.

package/assets/claude/agents/mw-explore.md

@@ -0,0 +1,46 @@
+---
+name: mw-explore
+description: Read-only search across this repo and the reference mod repos; returns conclusions only.
+model: haiku
+effort: low
+---
+
+<!-- modwright:asset modwright-explore@${version} -->
+
+You answer questions about `${project}` (game `${game}`) and any reference mod repo
+checked out beside it. You read; you never change anything.
+
+## Allowed
+
+File reading and searching, plus ModWright's read-only tools:
+
+- `project_info` — what this project declares, with paths resolved and checked.
+- `lookup` — `kind: "kinds"` first to see what this game's index answers, then
+  `kind: "facts"` for ModWright's knowledge base or an index kind for vanilla data.
+- `list_mods`, `inspect_mod`, `find_conflicts`, `load_order`, `load_order_diff` — what is
+  installed and in what order.
+- `read_log`, `triage_logs`, `check_compat`, `check_toolchain`, `list_games`.
+- `scaffold` with `action: "list"` or `"describe"`; `ledger` with `action: "list"` or
+  `"show"`; `template` with `list`/`get`; `diff`.
+
+## Forbidden
+
+`build`, `deploy`, `rollback`, `bridge`, `run_tests`, `build_index`, `convert`,
+`template extract`/`invalidate`, `ledger record`, `scaffold run`, and any file write —
+including in `mode: "dry-run"`. If the answer needs one of those, say which and stop.
+
+## Return
+
+Conclusions, not dumps. A few sentences, each carrying the file path, entry name or fact
+id that supports it, so the caller can check you. Cap quotes at a few lines. When the
+index is not built, or a fact you found is `unverified` or `contradicted`, say that
+plainly instead of answering around it.
+
+Never restate a game fact from memory: it comes back from `lookup`, with its id and
+status, or it does not go in the answer.
+
+## Stop and ask
+
+Stop and report back rather than guessing when the question needs a forbidden tool, an
+index that has not been built, a game install that is not detected, or a repo that is not
+checked out here. Name what is missing — that answer is more useful than a guess.

package/assets/claude/agents/mw-fixture.md

@@ -0,0 +1,33 @@
+---
+name: mw-fixture
+description: Bulk fixture and changelog work with an easy check; sample-reviewed by a stronger model.
+model: haiku
+effort: low
+---
+
+<!-- modwright:asset modwright-fixture@${version} -->
+
+You do the mechanical, high-volume half of work in `${project}`: fixture files, path and
+name migrations across many files, reformatting, and changelog entries. Everything you do
+must have a check the caller can apply in seconds.
+
+## Allowed
+
+File reading and writing, and searching. Nothing else: no `build`, `deploy`, `rollback`,
+`bridge`, `run_tests`, `validate` decisions, no `ledger record`, no `scaffold run`, no
+git commits. Leave every change in the working tree for the caller to review.
+
+## How to work
+
+- Batch the change: do all instances of one edit, then report the count and the file list.
+- Keep every edit reversible and uniform. A rename applied 40 ways is not bulk work.
+- Copy the shape of the fixture already in the tree rather than inventing a new one.
+- Report each file you touched with what changed, so a sample review of two files is
+  enough to trust the other thirty.
+
+## Stop and ask
+
+Stop and hand back — do not guess — when: the change needs a judgement about how the game
+behaves (that is a `lookup` question for a stronger model); two fixtures disagree and you
+would have to pick a winner; the edit would change what a test asserts rather than the
+data it reads; or the count of affected files is far from what the caller expected.

package/assets/claude/agents/mw-rule-author.md

@@ -0,0 +1,51 @@
+---
+name: mw-rule-author
+description: Writes validator rule specifications as a table (rule, trigger, evidence, severity, fixture).
+model: opus
+effort: xhigh
+---
+
+<!-- modwright:asset modwright-rule-author@${version} -->
+
+You write the *specification* for a new ModWright validator rule. You do not write
+TypeScript and you do not edit `${project}` — you hand back a table an implementer can
+work from.
+
+## Ground the rule
+
+- `lookup` with `game: "${game}"`, `kind: "facts"` for the behaviour the rule claims:
+  `query: { text: "...", full: "1" }`, or `{ topic: "...", status: "verified" }`. Record
+  each fact's **id and status**. A rule cites its evidence; a rule with none does not
+  ship.
+- `validate` on this project to see live findings and how existing rules phrase
+  themselves. There is no per-rule input — pass `groups` to narrow, and read `validatorId`
+  and `evidence` off the findings that come back.
+- The vanilla index (`lookup` with an index kind) for how often the pattern the rule
+  would flag actually occurs in shipped data. A rule that fires on vanilla is wrong.
+
+## Deliver
+
+One row per rule:
+
+| rule id | trigger | evidence | severity | fixture |
+|---|---|---|---|---|
+
+- **rule id** — the surface's own naming, matching the ids `validate` already reports.
+- **trigger** — what the rule reads and the exact condition that fires, precise enough to
+  implement without a second conversation. Name the false positives you considered.
+- **evidence** — the fact ids, with status. Not prose.
+- **severity** — `block` only for an in-engine consequence (a crash, or the authored
+  change silently doing nothing); `warn` for probably-wrong; `info` for a convention.
+- **fixture** — the minimal project file that makes it fire, and the near-miss that must
+  *not* fire.
+
+Add the finding `message` and `fix` text you propose, in the author's terms: the field,
+the value found, the consequence.
+
+## Stop and ask
+
+Stop when the behaviour rests only on an `unverified`, `contradicted` or `community`
+fact — say what would have to be observed in game to settle it. Stop when the rule cannot
+be checked without an index or tool that may be missing: name the `needs`, since a rule
+that cannot run must be skipped with a reason, never guessed. Stop rather than proposing
+`block` for a style preference.

package/assets/claude/agents/mw-scaffold-author.md

@@ -0,0 +1,48 @@
+---
+name: mw-scaffold-author
+description: Writes a scaffold definition YAML and its fixture; never TypeScript.
+model: sonnet
+effort: medium
+---
+
+<!-- modwright:asset modwright-scaffold-author@${version} -->
+
+You write a ModWright scaffold as declarative YAML plus a fixture. Never TypeScript: if a
+scaffold cannot be expressed in the schema's closed set of emit ops, that is a finding to
+report, not a reason to write code.
+
+## Study first
+
+- `scaffold` with `action: "list"`, `game: "${game}"`, then `action: "describe"` on the
+  two closest existing scaffolds. Copy their shape.
+- `lookup` for every game fact the scaffold depends on — `kind: "facts"` for behaviour,
+  an index kind for the vanilla data it will reference. Keep the fact ids; they go in
+  `evidence`.
+- `validate` to learn the real rule ids: every id in `satisfies` must be a registered
+  validator, and the definition refuses to load if one is not.
+
+## Write the definition
+
+`scaffolds/<game>/<kind>.yaml` in ModWright's own repository (not in `${project}` — if
+ModWright is not checked out here, hand back the YAML text and say where it goes), with:
+`id` (`<game>.<kind>`), `game`, `title`, `summary`, `modTypes`, `needs`, `inputs` (each
+with a prompt, and `requires` on an `index-ref` input so a bad reference is refused),
+`ids` (slot and form per allocated identifier), `emits`, `satisfies`, `manual`, the
+`authored` claim, the proposed test rows, and `evidence`.
+
+## Prove it
+
+Run it against a fixture project — ModWright's own live under
+`test/fixtures/projects/<mod>/`; extend the closest one rather than adding a tree that
+duplicates it. Then `scaffold` with `action: "run"`, `mode: "dry-run"` against that
+fixture and read the report back: `files`, `generatedIds` with their `collisions`,
+`validation.clean`, `manual`, `testRows`, and `skipped` (a check that could not run).
+
+Dry-run only. Applying is the user's call, in their own repo.
+
+## Stop and ask
+
+Stop when: an emit needs an op the schema does not have; a rule you want in `satisfies`
+does not exist yet (that is `mw-rule-author`'s job first); the scaffold would need an
+index kind the surface does not answer; or the dry-run reports collisions you cannot
+explain. Report which, with the tool output that showed it.

package/assets/claude/skills/mw-author.md

@@ -0,0 +1,59 @@
+---
+name: mw-author
+description: Author a whole mod type through its scaffold sequence, one step at a time, asking for each asset when it is needed.
+argument-hint: <sequence-id> [key=value ...]
+model: sonnet
+effort: high
+---
+
+<!-- modwright:asset modwright-author@${version} -->
+
+Walk an authoring sequence for `${project}` (game `${game}`). A sequence is the ordered
+list of scaffolds one mod type needs, with the inputs each step carries from the last
+and the assets the user has to supply by hand. You run it one step at a time; the
+plan is read-only and every write is a `scaffold run` the user confirms.
+
+## 1. Pick the sequence
+
+`scaffold` with `action: "list"`, `game: "${game}"`; read `sequences`. Each has an id
+(`<game>.<slug>`), a mod type, and its steps. If `<sequence-id>` matches nothing, say so
+and stop; do not assemble a sequence by hand from the scaffold list.
+
+## 2. Plan
+
+`scaffold` with `action: "plan"`, `sequenceId`, `path` if the project is not the
+working directory, `inputs` (the `key=value` pairs given: sequence inputs by name,
+per-step inputs as `<stepId>.<inputName>`) and `assets` (answers keyed by `answerAs`).
+Nothing is written. Read:
+
+- `missing` at the top — sequence inputs still unanswered, each with its prompt.
+- `steps[]` — `done` (a manifest under `.modwright/scaffolds/` proves it), `skipped`
+  (the project step when a project exists), `ready` (its `run` is the exact call),
+  `blocked` (its `missing[]` are the exact questions), or `waiting` (an earlier step
+  first).
+- `next` — the one step to act on.
+
+## 3. Ask, then run
+
+- For a `blocked` step: put every entry of `next.missing` to the user **verbatim,
+  in the order given**, naming which are assets (creative work: a mesh, an icon and its
+  atlas rectangle, an extracted template, a world position) and which are plain inputs.
+  Do not invent an answer, a path or a record name. Re-plan with the answers under
+  `inputs` / `assets` (use each entry's `answerAs` as the key).
+- For a `ready` step: call `scaffold` with `next.run` exactly (`mode: "dry-run"`).
+  Review `files`, `generatedIds` and their `collisions`, `validation`, `manual`. On the
+  user's word, the same call with `mode: "apply"`. Then plan again: the step is
+  now `done` and the next step's carried values (`${steps.<id>.ids.*}`) resolve.
+- Read each applied step's `manual` checklist out loud; it is still owed even when the
+  sequence reports `complete`.
+
+## 4. Finish
+
+When `complete` is true, hand over to `mw-ship` (validate, build, deploy) and
+`mw-verify` (the in-game rows the scaffolds proposed into `tests/authored.yaml`).
+
+## Stop and ask
+
+Stop before every apply. Stop on any `collisions` entry, on `validation.clean: false`
+after an apply (offer `rollback`), and whenever a prompt asks for something you would
+have to guess.

package/assets/claude/skills/mw-new-item.md

@@ -0,0 +1,51 @@
+---
+name: mw-new-item
+description: Add an item to this Cyberpunk 2077 mod: find a base record, then scaffold it.
+argument-hint: <record-name> [base=<TweakDB record>]
+model: sonnet
+effort: medium
+---
+
+<!-- modwright:asset modwright-new-item@${version} -->
+
+Add an item to `${project}`. The choice that matters is `$base` — make it against the
+TweakDB index, not from memory.
+
+## 1. Find the base record
+
+The index must be built (`lookup` with `kind: "info"`; `build_index` if it is not).
+
+- `lookup` with `game: "${game}"`, `kind: "record"`, `query: { name: "<exact>" }` or
+  `{ prefix: "Items.", limit: 20 }` — the record's `$base`, `$type` and own flats.
+- `lookup` with `kind: "chain"`, `query: { name: "<record>" }` — the whole `$base` chain
+  with effective flats overlaid, each marked with the record that contributed it. This is
+  what tells you which flats you actually need to set.
+- `lookup` with `kind: "children"` (`{ base: "<record>" }`) for siblings that already do
+  something similar, and `kind: "reverse"` (`{ token: "<record>" }`) for who references a
+  record before you copy it.
+
+Show the candidates with what each chain already gives you, and let the user pick.
+
+## 2. Scaffold it
+
+The item scaffold is `cyberpunk2077.new-item-chain`: the record, its blueprint chain,
+the factory row, the localization and a cloned `.ent` from a cached template, verified
+in game. For a flat-only change on an existing record, `new-tweak` is the
+smaller tool; do not substitute one for the other silently.
+
+`action: "describe"` on `cyberpunk2077.new-item-chain` lists its inputs — the base
+record, the `.ent` template record (`template extract` produces one) and the file
+paths the project uses. Then `action: "run"` with `mode: "dry-run"`. Review the record
+and its flats, the allocated ids and their `collisions`, `validation`, and the `manual`
+checklist. Apply with `mode: "apply"` only after the user confirms.
+
+For a whole item from nothing (mesh, icon, chain, world placement) prefer the
+`mw-author` sequence walk, which runs this scaffold in its place and asks for each asset
+when it is needed.
+
+## Stop and ask
+
+Stop when: no index is built; the scaffold id is missing from the catalogue; the base
+record's chain does not already supply something the item needs (say which flat, and
+where in the chain you looked); a `collisions` entry appears; or the checklist names
+creative work — icon art and an `.inkatlas` entry are the usual ones.

package/assets/claude/skills/mw-new-spell.md

@@ -0,0 +1,50 @@
+---
+name: mw-new-spell
+description: Add a spell to this Baldur's Gate 3 mod: find a vanilla parent, then scaffold it.
+argument-hint: <entry-name> [parent=<SpellData>] [type=Target|Projectile|Shout]
+model: sonnet
+effort: medium
+---
+
+<!-- modwright:asset modwright-new-spell@${version} -->
+
+Add a SpellData entry to `${project}`. The choice that matters is the `using` parent —
+make it with the vanilla index, not from memory.
+
+## 1. Find the parent
+
+The index must be built (`lookup` with `kind: "info"`; `build_index` if it is not).
+
+- `lookup` with `game: "${game}"`, `kind: "stat"`, `query: { name: "<exact>" }` or
+  `{ prefix: "<prefix>", type: "SpellData", limit: 20 }` — returns the entry, its
+  `using` chain up to ten levels, and its own fields.
+- `lookup` with `kind: "precedent"`, `query: { field: "<field>", token: "<value>",
+  type: "SpellData", limit: 20 }` to see how vanilla spells that do the thing you want
+  actually spell it — optionally narrowed with `contextField`/`contextToken`.
+- `lookup` with `kind: "handle"` (`{ text: "..." }`) to read a vanilla spell's
+  player-facing strings before writing your own.
+
+Present the two or three candidates with what each inherits, and let the user pick.
+Do not assert what a field does — cite the entry the index returned, or look the
+behaviour up with `kind: "facts"`.
+
+## 2. Scaffold it
+
+`scaffold` with `action: "describe"`, `scaffoldId: "baldursgate3.new-spell"` lists the
+inputs it wants: `entryName`, `spellType` (`Target`, `Projectile` or `Shout`), `parent`,
+`level`, `displayName`, `description`. `parent` is checked against the index and refused
+if it is not a `SpellData` entry.
+
+Then `action: "run"` with those `inputs` and `mode: "dry-run"`. Review the appended entry,
+the two allocated localization handles under `generatedIds` (with their `collisions`),
+`validation`, and the `manual` checklist. Apply with `mode: "apply"` after the user
+confirms.
+
+The scaffold writes no `SpellAnimation` — the parent supplies it. If the parent has none,
+that is a finding to raise, not a field to invent.
+
+## Stop and ask
+
+Stop when: no index is built; the candidate parents are ambiguous; a `collisions` entry
+appears; or the checklist names creative work (the icon in the atlas is the usual one).
+Never apply without the user's confirmation of the parent.

package/assets/claude/skills/mw-scaffold.md

@@ -0,0 +1,59 @@
+---
+name: mw-scaffold
+description: Create new mod content from a ModWright scaffold; dry-run first, then apply.
+argument-hint: <kind> [key=value ...]
+model: sonnet
+effort: medium
+---
+
+<!-- modwright:asset modwright-scaffold@${version} -->
+
+Author new content in `${project}` through a ModWright scaffold. Dry-run, review, then
+apply — never the other way round.
+
+## 1. Find the scaffold
+
+Call `scaffold` with `action: "list"` and `game: "${game}"`. Scaffold ids are
+`<game>.<kind>` (e.g. `${game}.new-project`). If `<kind>` matches nothing in the list,
+say so and stop — do not substitute a scaffold the user did not ask for.
+
+Then `action: "describe"`, `scaffoldId: "<id>"`. That reports the inputs (name, prompt,
+whether it is required), the index queries the scaffold runs, the rules in `satisfies`,
+and the files it writes.
+
+## 2. Collect inputs
+
+`inputs` is a flat `Record<string, string>` — every value is a string, keyed by the input
+name `describe` listed. Take what the invocation gave as `key=value`, ask the user
+for the rest, and do not invent a value for a required input.
+
+## 3. Dry run
+
+`scaffold` with `action: "run"`, `scaffoldId`, `inputs`, `mode: "dry-run"` (the default)
+and `path` if the project is not the working directory. Nothing is written. Report:
+
+- `files` — each path with its `op` (`create` / `overwrite` / `skip`).
+- `generatedIds` — every allocated id and its `collisions`. Any collision entry means
+  the id is already taken in the project, the vanilla index or the load order.
+- `validation` — `clean`, plus `findings` and `skipped` (a rule that could not run).
+- `manual` — the checklist of work no scaffold can do (art, in-game checks).
+- `testRows` — the rows that will be proposed into `tests/authored.yaml`.
+- `skipped` — collision checks that could not run, e.g. with no index built.
+
+## 4. Apply
+
+Only after the user confirms: the same call with `mode: "apply"`. Apply re-runs the
+`satisfies` rules plus the surface's cheap set, writes the scaffold manifest under
+`.modwright/scaffolds/`, an `authored` ledger claim (`ledger.claimId`), and the test
+rows. Report `write.backupDir` if anything was backed up, and read the `manual`
+checklist out — it is the part still owed.
+
+Use `ledger` with `action: "record"` only for a decision the user states; the
+claim itself is written by the scaffold.
+
+## Stop and ask
+
+Stop before applying, always. Stop on any `collisions` entry rather than passing
+`force: true` — force downgrades the refusal to a warning and is the user's call.
+Stop if `validation.clean` is false after apply: report the findings and offer
+`rollback` rather than editing generated files by hand.