esp-modkit 0.1.0

data/docs/getting-started.md

@@ -0,0 +1,183 @@
+# Getting started
+
+## Install
+
+Install the gem (puts `esp` on your `PATH`):
+
+```sh
+gem install esp-modkit
+esp doctor                     # confirm Ruby, tes3conv, and the references index
+```
+
+Native extensions (`sqlite3`, `zstd-ruby`) compile on install, so a C
+toolchain is required. To hack on the toolchain itself, work from a clone
+instead and put `bin/esp` on your `PATH`:
+
+```sh
+git clone git@github.com:ninjacazaam/esp-modkit.git
+cd esp-modkit
+bundle install
+bin/esp setup                  # git diff driver + pre-commit hook for this repo
+```
+
+You also need [tes3conv] on `PATH`. It is **not on Homebrew**; install
+via a release binary or Cargo:
+
+```sh
+# Option A — release binary (no Rust toolchain required)
+# Download the macOS build from:
+#   https://github.com/Greatness7/tes3conv/releases
+# then put `tes3conv` somewhere on PATH (e.g. /opt/homebrew/bin/).
+
+# Option B — build from source with Rust
+cargo install --git https://github.com/Greatness7/tes3conv
+```
+
+Optional, only if you want to author mods in those languages:
+
+```sh
+brew install python deno      # python3 + deno (TypeScript)
+nvm install --lts             # node (JavaScript)
+```
+
+[tes3conv]: https://github.com/Greatness7/tes3conv
+
+## Index the vanilla data (one-time)
+
+Lint, `refs find`, and the AI tools need a fast lookup table of vanilla
+records. Build it once, **per user** — the index lives at
+`$ESP_DATA_DIR/references/` (default: `~/.config/esp/references/`), so
+a single index serves every project you author.
+
+```sh
+esp refs unpack                # unpack Morrowind/Tribunal/Bloodmoon to JSON
+esp refs index                 # build the SQLite index (~70k records, ~3s)
+```
+
+You only need to re-run these if you upgrade Morrowind.
+
+## First project, first mod
+
+A **project** is any directory with a `.esp/project.json` marker. Make
+one anywhere on disk; `esp` discovers it by walking up from wherever you
+run the command.
+
+```sh
+mkdir -p ~/morrowind/MyFirstMod && cd ~/morrowind/MyFirstMod
+esp init                       # writes .esp/project.json + git init + mods/ + dist/
+
+esp new MyMod                  # mods/MyMod/MyMod.json + README
+$EDITOR mods/MyMod/MyMod.json  # author the records
+
+esp lint MyMod                 # check refs against vanilla data
+esp build MyMod                # -> dist/MyMod.esp (in this project, not the toolchain)
+esp install MyMod              # registers with openmw.cfg
+```
+
+Launch OpenMW; enable `MyMod.esp` in the launcher's content list.
+
+`esp new` picks `json` by default. Use `--format rb|py|js|mjs|ts` for any
+other authoring language; the scaffold drops in a working starter that
+prints (or returns) one TES3 Header record. Author defaults to your
+`git config user.name`; override with `--author "Some Name"`.
+
+### Picking which project to operate on
+
+`esp` resolves the project root, in order:
+
+1. `--root PATH` flag on the command.
+2. `ESP_PROJECT_ROOT` environment variable.
+3. Walking up from the current directory to find a `.esp/project.json`
+   (git-style discovery — works from any subdirectory of the project).
+4. As a last resort, the toolchain repo itself (with a one-line warning
+   on stderr explaining how to make this directory a project).
+
+So `cd` into your project and run commands; or pass `--root` when
+scripting across projects; or `export ESP_PROJECT_ROOT=~/morrowind/MyFirstMod`
+to pin a default for a shell.
+
+## Installing the built plugin
+
+`esp install MyMod` registers the project's `dist/` directory with OpenMW
+via `data=` + `content=` in `openmw.cfg`. Nothing is copied; OpenMW reads
+your build output in place.
+
+The original engine (Steam / GOG Morrowind) doesn't have that
+`data=` mechanism — it loads `.esp` files from one fixed directory.
+For those installations, pass `--copy-to` (explicit path) or
+`--to-data-files` (auto-detects the Morrowind install):
+
+```sh
+esp install MyMod --to-data-files            # copy to Morrowind/Data Files/
+esp install MyMod --copy-to /some/path       # copy to an explicit dir
+esp install MyMod --no-register-openmw       # skip the openmw.cfg part
+```
+
+The two install paths compose — by default `--to-data-files` *also*
+registers with OpenMW, so a multi-engine user gets both at once.
+
+## Paths on macOS
+
+| Thing | Default location |
+|---|---|
+| Vanilla references (per-user) | `~/.config/esp/references/` (override: `$ESP_REFERENCES_DIR` or `$ESP_DATA_DIR`) |
+| Morrowind data | `~/Library/Application Support/Steam/steamapps/common/Morrowind/Data Files/` |
+| OpenMW config | `~/Library/Preferences/openmw/openmw.cfg` |
+| tes3conv binary | wherever `which tes3conv` points (Homebrew default: `/opt/homebrew/bin/tes3conv`) |
+
+Override the Morrowind data path with `MORROWIND_DATA=/custom/path esp refs unpack`.
+
+## Wiring esp into an AI client (MCP)
+
+`esp` ships a [Model Context Protocol](https://modelcontextprotocol.io) server
+so an AI assistant can author, build, lint, and query a mod project as native
+tools. The server speaks JSON-RPC over stdio — you never run it by hand; the
+client launches it.
+
+Register it with one command:
+
+```sh
+esp mcp install                          # Claude Code (writes .mcp.json in cwd)
+esp mcp install --client claude-desktop  # Claude Desktop
+```
+
+- **Claude Code** writes a project-scoped `.mcp.json` in the current
+  directory with an absolute path to `bin/esp`; the server connects on
+  next launch (Claude Code prompts to approve a changed `.mcp.json`).
+  Run `esp mcp install` from your project root so the marker lands
+  beside `.esp/project.json`. The path is machine-specific —
+  `${CLAUDE_PROJECT_DIR}` is *not* an option here, since it's unset when
+  the config is parsed, so a server using it silently fails to launch.
+- **Claude Desktop** merges into
+  `~/Library/Application Support/Claude/claude_desktop_config.json`,
+  also with an absolute path. Fully quit and restart Claude Desktop to
+  pick it up.
+
+Re-running is idempotent (reports `unchanged`); other servers and keys
+in the config are preserved. The by-hand equivalent for Claude Code is
+`claude mcp add --transport stdio esp -- /path/to/bin/esp mcp serve`.
+
+The MCP tools mirror the CLI's payloads byte-for-byte. They include
+project management (`open_project`, `active_project`, `projects_new`,
+`projects_recent`) so an AI client outside the toolchain repo — Claude
+Desktop especially — can target an arbitrary project directory at runtime.
+
+- **Discover** — `commands`, `version`.
+- **Open a project** — `open_project`, `active_project`, `projects_recent`,
+  `projects_new`.
+- **Author** — `scaffold`, `records_read`, `record_write`, `dialogue_write`,
+  `extract_scripts`.
+- **Validate & build** — `lint`, `build`, `build_all`.
+- **Vanilla data** — `refs_find`.
+- **Game integration** — `unpack`, `install`, `plugins_list`.
+
+The server also exposes **resources**: the `esp docs introspect` surface
+and the generated reference docs, so a client can read the full
+capability map without a tool call.
+
+## Where to go next
+
+- [Authoring guide](authoring-guide.md) — every source format, scripts, i18n.
+- [Architecture](architecture.md) — how the pipeline fits together.
+- [Command reference](reference/commands.md) — every flag, auto-generated.
+- [API reference](reference/api/index.md) — library modules, auto-generated.

data/docs/reference/api/active-project.md

@@ -0,0 +1,22 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::ActiveProject
+
+**Source:** `lib/esp/active_project.rb`
+
+Process-scoped state for "which project is the user currently working in"
+(step 23). Swapped in by ESPresso's POST /open-project; helpers that need
+a working-tree root (vcs_root for diff/approve/reject today; more later)
+consult this before falling back to Esp::ROOT.
+
+Step 22.5 slice 2: also tracks the project's game id (`mw` today, future
+`ob`/`sr`) so the plugin registry knows which Operations module owns each
+op for the current request. Missing game on a project read defaults to
+`mw` for backward compat (every pre-rename project is Morrowind).
+
+Stored module-globally rather than per-request because the WEBrick backend
+is single-tenant per-instance (one ESPresso ↔ one esp serve), so a global
+is the right shape; the mutex guards against the thread-per-request model
+racing a concurrent set + read.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/agent.md

@@ -0,0 +1,24 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Agent
+
+**Source:** `lib/esp/agent.rb`
+
+A hand-rolled tool-use loop. The agent authors mods by calling the same
+curated tool surface MCP exposes (Esp::McpServer::TOOLS), each tool
+dispatched to Esp::Operations.public_send(op, …) — so the in-house agent
+and external MCP clients share one tool definition.
+
+The LLM is reached through an injected **provider** (see Esp::Providers), so
+the loop is provider-agnostic and fully testable with a stub and no live
+key. When none is given, the default provider is built from the registry
+(Esp::Providers.default_id). See .claude/roadmap/19-agent-workspace.md.
+
+Transcript shape (neutral, owned by Agent; providers translate it to their
+native wire format):
+  { role: :user,      text: String }
+  { role: :assistant, text: String, tool_calls: [{id:, name:, input:}],
+                      raw: <provider-native message, opaque to Agent> }
+  { role: :tool,      results: [{id:, content: String, is_error: bool}] }
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/docs-generator.md

@@ -0,0 +1,20 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::DocsGenerator
+
+**Source:** `lib/esp/docs_generator.rb`
+
+Renders the data from Esp::Introspection into markdown files under
+docs/reference/. Each file is split into two regions: an `esp:auto`
+block (regenerated by `esp docs build`, enforced fresh by lefthook so
+it can't drift) and a hand-written tail below it that survives rebuilds.
+write_doc rewrites only the auto block and preserves the tail verbatim,
+so an unchanged source reproduces the file byte-for-byte — that
+idempotence is what lets the freshness hook keep diffing the whole file.
+
+The marker literal kept the `mw:auto` token for one release so existing
+generated files migrate cleanly: manual_tail accepts both the new
+`esp:auto` marker and the legacy `mw:auto` one. After the next regen,
+every file carries the new marker and the fallback is dead code.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/http-server.md

@@ -0,0 +1,46 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::HttpServer
+
+**Source:** `lib/esp/http_server.rb`
+
+Localhost HTTP API mirroring the CLI surface. A thin WEBrick shell over
+Esp::Operations — same operations as `bin/esp` and `esp mcp serve`, same
+payload shapes, different transport. Intended as the backing store for
+the GUI. WEBrick is thread-per-request, so the long-lived /agent stream
+doesn't block other routes.
+
+Routes:
+  POST /agent             — body: { prompt, provider?, model? } → text/event-stream
+  GET  /up                — { status, version }  (liveness)
+  GET  /version           — { version }
+  GET  /commands          — full Esp::Introspection.command_tree
+  GET  /providers         — { providers:[{id,default_model,configured}], default }
+  GET  /active-project    — { root: String|null }
+  POST /open-project      — body: { root } → { root }  (sets active project)
+  GET  /projects/recent   — { projects: [{root,name,opened_at}, ...] }
+  POST /projects/new      — body: { project, mod, format?, author? } → { root, mod, source }
+  GET  /preferences       — { mods_home, ... } (merged over defaults)
+  POST /preferences       — body: { mods_home?, ... } → resolved prefs
+  POST /build             — body: { mod, locale? }
+  POST /build-all         — body: { locale? }
+  POST /unpack            — body: { plugin, name? }
+  POST /install           — body: { mod }
+  POST /lint              — body: { mod }
+  POST /i18n/check        — body: { mod }
+  POST /scaffold          — body: { mod, format?, author?, description?, force? }
+  POST /extract-scripts   — body: { mod }
+  POST /records/read      — body: { mod }
+  POST /records/write     — body: { mod, record }
+  POST /dialogue/write    — body: { mod, spec }
+  GET  /plugins           — query: config?
+  GET  /refs/find         — query: q, type, like, limit, show
+  POST /refs/resolve      — body: { ids: [String] } → { types: {id => type} }
+  GET  /ollama/models     — { models: [String] } from Ollama's /api/tags
+  GET  /diff              — query: scope?, root?  (working-tree changes + diffs)
+  POST /approve           — body: { paths, root? }  (git add)
+  POST /reject            — body: { paths, root? }  (restore/delete — destructive)
+
+CORS is wide open (Access-Control-Allow-Origin: *) — dev-only tool.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/index.md

@@ -0,0 +1,38 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# API reference
+
+Core library modules. Shell modules are `Esp::<Name>`;
+Morrowind-plugin modules are `Esp::Mw::<Name>`.
+
+- [`Esp::ActiveProject`](active-project.md)
+- [`Esp::Agent`](agent.md)
+- [`Esp::DocsGenerator`](docs-generator.md)
+- [`Esp::HttpServer`](http-server.md)
+- [`Esp::Introspection`](introspection.md)
+- [`Esp::McpInstaller`](mcp-installer.md)
+- [`Esp::McpServer`](mcp-server.md)
+- [`Esp::Operations`](operations.md)
+- [`Esp::Plugins`](plugins.md)
+- [`Esp::Preferences`](preferences.md)
+- [`Esp::ProjectMarker`](project-marker.md)
+- [`Esp::Providers`](providers.md)
+- [`Esp::Recents`](recents.md)
+- [`Esp::Ui`](ui.md)
+- [`Esp::Vcs`](vcs.md)
+- [`Esp::Watcher`](watcher.md)
+- [`Esp::Mw::Builder`](mw-builder.md)
+- [`Esp::Mw::DataFiles`](mw-data-files.md)
+- [`Esp::Mw::DialogueDsl`](mw-dialogue-dsl.md)
+- [`Esp::Mw::I18n`](mw-i18n.md)
+- [`Esp::Mw::Linter`](mw-linter.md)
+- [`Esp::Mw::Loader`](mw-loader.md)
+- [`Esp::Mw::OpenmwConfig`](mw-openmw-config.md)
+- [`Esp::Mw::Operations`](mw-operations.md)
+- [`Esp::Mw::Preflight`](mw-preflight.md)
+- [`Esp::Mw::ReferenceIndex`](mw-reference-index.md)
+- [`Esp::Mw::Scaffolder`](mw-scaffolder.md)
+- [`Esp::Mw::ScriptBlob`](mw-script-blob.md)
+- [`Esp::Mw::ScriptExtractor`](mw-script-extractor.md)
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/introspection.md

@@ -0,0 +1,17 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Introspection
+
+**Source:** `lib/esp/introspection.rb`
+
+Builds a structured snapshot of the CLI command tree and the core
+library modules. Two consumers:
+
+- `esp docs build` renders this into markdown under docs/reference/.
+- `esp docs introspect` emits it as JSON so AI tools, ESPresso,
+  and the MCP server can discover capabilities at runtime.
+
+The introspection is read-only and cheap — it just walks Thor's
+metadata and reads each lib/esp/{,mw/}*.rb header comment block.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/mcp-installer.md

@@ -0,0 +1,26 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::McpInstaller
+
+**Source:** `lib/esp/mcp_installer.rb`
+
+Registers `esp mcp serve` with a local MCP client by merging a stdio
+server entry into that client's config JSON, preserving any other servers
+and top-level keys already there.
+
+Deliberately kept out of Esp::Operations: rewriting a user's AI-client
+config is a CLI/operator action, never something an agent should be able
+to drive over MCP itself.
+
+The two clients share the `mcpServers` / stdio shape and an identical
+server entry; they differ only in where the config lives. The command is
+an absolute path to `bin/esp` — note `${CLAUDE_PROJECT_DIR}` looks tempting
+for a portable Claude Code entry but is unset when `.mcp.json` is parsed
+(it's a hooks-only variable), so the server silently fails to launch. The
+cost is a machine-specific path in the config.
+
+Step-22.5 migration: the install action quietly drops any existing entry
+named `mw` (the historical pre-rename name) when it writes the new `esp`
+entry, so a re-install after the rename leaves a single, current entry.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/mcp-server.md

@@ -0,0 +1,27 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::McpServer
+
+**Source:** `lib/esp/mcp_server.rb`
+
+Model Context Protocol server over stdio, so AI assistants (Claude Code,
+Claude Desktop, …) can author, build, lint, and query a mod project as
+native tools. It is a thin shell over Esp::Operations — the same service
+layer the HTTP API uses — so every tool returns the same payload the CLI
+`--json` mode and `esp serve` already emit.
+
+Transport is the MCP stdio convention: newline-delimited JSON-RPC 2.0,
+one message per line, no embedded newlines. Requests carry an `id` and
+get a response; notifications (no `id`) get none. The protocol stream
+owns stdout, so all diagnostics go to stderr.
+
+Operation errors (missing mod, no index, bad source) come back as a
+tool result with `isError: true` — the model sees the message and can
+recover. Only malformed protocol traffic (bad JSON, unknown method,
+unknown tool) uses a JSON-RPC error response.
+
+Alongside tools, the server exposes read-only **resources**
+(`resources/list` + `resources/read`): the command-tree introspection
+and the narrative docs, so an agent can pull context without a tool call.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/mw-builder.md

@@ -0,0 +1,14 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Mw::Builder
+
+**Source:** `lib/esp/mw/builder.rb`
+
+Orchestrates mods/<Mod>/<Mod>.json -> dist/<Mod>.esp:
+  1. Load source JSON.
+  2. Run Esp::Mw::Preflight to inline text_source files and regenerate
+     Script record blobs.
+  3. Hand the canonical JSON to tes3conv via a tempfile (whose
+     extension must be .json — tes3conv sniffs by extension).
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/mw-data-files.md

@@ -0,0 +1,20 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Mw::DataFiles
+
+**Source:** `lib/esp/mw/data_files.rb`
+
+Where Morrowind keeps its vanilla data files (`Morrowind.esm` and
+friends, plus user-installed `.esp` plugins for the original engine).
+Engine-agnostic — OpenMW reads them via `data=` in openmw.cfg; the
+original engine reads them in place. The same set of probe paths
+serves both:
+
+- `esp refs unpack` reads the vanilla ESMs out of here.
+- `esp install --to-data-files` copies a built plugin into here so
+  the original engine's launcher picks it up.
+
+Detection is best-effort, per-OS Steam/GOG defaults. Anything
+non-default is overridable via $MORROWIND_DATA or an explicit flag.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/mw-dialogue-dsl.md

@@ -0,0 +1,58 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Mw::DialogueDsl
+
+**Source:** `lib/esp/mw/dialogue_dsl.rb`
+
+Block-style DSL for emitting Dialogue (DIAL) and DialogueInfo (INFO)
+records without the bookkeeping. Used inside Ruby mod sources via the
+loader-exposed `dialogue { ... }` helper.
+
+The contract: a `dialogue` block returns a flat Array of records
+that the author splats into their mod's records array. The DSL
+handles:
+
+- One DIAL record per `topic`, with `dialogue_type` carried through.
+- INFO records under each topic, chained via prev_id/next_id in
+  author order — Morrowind evaluates filters top-down, so author
+  order is filter precedence.
+- Speaker scoping via `speaker "Name" do ... end`. Nested blocks
+  inherit; an explicit `speaker:` on an info wins.
+- i18n: a `t("key")` helper is available inside the block when the
+  loader passes an Esp::Mw::I18n instance.
+
+Example:
+
+  dialogue do
+    speaker "Hrisskar Flat-Foot" do
+      topic "Flat-Foot" do
+        info t("hrisskar.flat_foot.intro")
+        info t("hrisskar.flat_foot.legion"), pc_faction: "Imperial Legion"
+      end
+    end
+
+    topic "AFSN_Tracker", type: :journal do
+      info "Stage 10 text", journal_index: 10
+      info "Stage 20 text", journal_index: 20
+    end
+  end
+
+Supported info kwargs:
+  speaker:           speaker_id filter (overrides surrounding scope)
+  race:              speaker_race filter
+  class:             speaker_class filter (note the keyword clash —
+                     use the string key or the `class_:` alias)
+  faction:           speaker_faction filter
+  cell:              speaker_cell filter
+  sex:               :any | :female | :male
+  pc_faction:        player_faction filter
+  pc_rank:           player_rank filter
+  speaker_rank:      NPC rank filter
+  disposition:       minimum disposition
+  sound:             sound_path
+  result_script:     inline MWScript text to run on activation
+  result_script_source: path to .mwscript file (resolved relative to
+                        the mod source dir at preflight time)
+  journal_index:     for Journal-type topics — maps to data.disposition
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/mw-i18n.md

@@ -0,0 +1,20 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Mw::I18n
+
+**Source:** `lib/esp/mw/i18n.rb`
+
+Locale-aware string lookup. Two interfaces:
+
+- `t(key)` returns the resolved string (with default-locale fallback)
+  and tracks misses. Used directly from the Ruby DSL.
+- `resolve!(value)` walks any data structure and replaces
+  `"@t:<key>"` sentinel strings via `t`. Used post-load for JSON or
+  subprocess-loader output (Python/JS/TS) where in-process helpers
+  can't reach.
+
+Catalogues are nested-hash YAML files at
+`mods/<Mod>/i18n/<locale>.yaml`. Lookup is dot-pathed:
+`t("activator.stump")` reads `{activator: {stump: "..."}}`.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/mw-linter.md

@@ -0,0 +1,18 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Mw::Linter
+
+**Source:** `lib/esp/mw/linter.rb`
+
+Checks a mod's records for dangling references and missing-master
+coverage. Uses Esp::Mw::ReferenceIndex for vanilla lookups and the mod's
+own records for self-references.
+
+Severity model:
+- :error   — the ref points at nothing the mod or any indexed ESM defines.
+- :warning — the ref resolves in a vanilla ESM that isn't listed in
+             the mod's TES3 Header.masters. OpenMW will load the mod
+             but log warnings; the mod author probably forgot to add
+             the dependency.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/mw-loader.md

@@ -0,0 +1,26 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Mw::Loader
+
+**Source:** `lib/esp/mw/loader.rb`
+
+Loads a mod's source records from one of the supported formats.
+
+The contract: every loader returns an Array of record hashes shaped
+for tes3conv. Keys are normalised to strings so downstream code
+(preflight, builder) doesn't have to care which format the source
+was authored in.
+
+Supported source files (per mod folder, exactly one):
+  mods/<Mod>/<Mod>.json   — straight JSON
+  mods/<Mod>/<Mod>.rb     — Ruby file; last expression is the Array
+  mods/<Mod>/<Mod>.py     — Python script; prints JSON Array to stdout
+  mods/<Mod>/<Mod>.js     — Node script; same contract
+  mods/<Mod>/<Mod>.mjs    — Node ES module; same contract
+  mods/<Mod>/<Mod>.ts     — Deno TypeScript; same contract
+
+For subprocess loaders (py/js/mjs/ts) the interpreter runs with cwd
+set to the mod's source directory, so relative file reads from the
+script just work. The script's own path is passed as the last arg.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/mw-openmw-config.md

@@ -0,0 +1,15 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Mw::OpenmwConfig
+
+**Source:** `lib/esp/mw/openmw_config.rb`
+
+Reads and edits OpenMW's openmw.cfg. Knows the per-OS location of the
+*user* config (the one OpenMW's launcher edits) and can parse the
+data=/content= lines to enumerate installed plugins.
+
+v1 targets the single user config; OPENMW_CONFIG (or an explicit path)
+overrides it. The full global/local/user hierarchy and ?token? data
+paths are not merged/expanded yet — see roadmap/17.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/mw-operations.md

@@ -0,0 +1,24 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Mw::Operations
+
+**Source:** `lib/esp/mw/operations.rb`
+
+The Morrowind plugin's half of the service layer. Same contract as
+Esp::Operations (string-keyed params hash in, plain Hash out) — these
+are the ops that decode TES3 records, drive tes3conv, or otherwise know
+what a "mod" is. Frontends never call this module directly; they route
+through Esp::Operations.dispatch(op, input).
+
+Every op resolves the project root from `Esp::ActiveProject.resolve`
+(step 23.5 slice 1) so an `open_project` request actually moves where
+build/lint/etc. operate — they no longer silently target Esp::ROOT.
+Precedence: explicit `root:` in params > active project > Esp::ROOT.
+
+InputError is aliased from the shell so plugin ops raise the same class
+the frontends rescue. Loader / Preflight / Tes3conv error classes are
+registered with Esp::Operations::ERROR_CODES at the bottom of this file
+— they couldn't be in the shell table because the plugin hadn't loaded
+yet when that table was built.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/mw-preflight.md

@@ -0,0 +1,17 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Mw::Preflight
+
+**Source:** `lib/esp/mw/preflight.rb`
+
+Resolves text_source into inline text and regenerates Script-record
+subrecords (SCHD header + SCVR vars + SCDT bytecode placeholder) into
+the form tes3conv expects. Mutates records in place.
+
+Validation rules:
+- Source must be pure ASCII (MWScript's compiler is silent on UTF-8).
+- Variable identifiers must be <= 20 chars (MWScript truncates ~20-23).
+- Warn (don't fail) when a script's `Begin <name>` doesn't match its
+  record id; vanilla often disagrees so this is intentionally soft.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->

data/docs/reference/api/mw-reference-index.md

@@ -0,0 +1,21 @@
+<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->
+
+# Esp::Mw::ReferenceIndex
+
+**Source:** `lib/esp/mw/reference_index.rb`
+
+SQLite index over the unpacked vanilla ESM JSONs. Replaces "grep over
+200MB of JSON" with a millisecond keyed lookup.
+
+Schema is intentionally narrow: just enough to answer "where is this
+record defined?" and "what's its full JSON?". Full-record retrieval
+falls back to reading the source ESM at the stored array index.
+
+Storage location (step 23.5 slice 2): vanilla data is *not* per-project
+— it's identical for every user, and ~150 MB of it. It lives at
+`$ESP_REFERENCES_DIR` (explicit override), else
+`$ESP_DATA_DIR/references/`, else `~/.config/esp/references/`. One
+index across every project. The defaults resolve at call time, not at
+require, so an env-var change between invocations takes effect.
+
+<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->