esp-modkit 0.1.0

data/lib/esp/cli/refs.rb

@@ -0,0 +1,137 @@
+require 'json'
+require 'thor'
+require 'fileutils'
+
+module Esp
+  class CLI < Thor
+    class Refs < Thor
+      include Support
+
+      MASTERS = %w[Morrowind Tribunal Bloodmoon].freeze
+
+      # Detection of the vanilla Data Files directory now lives on
+      # Esp::Mw::DataFiles so `esp install --to-data-files` can reuse it.
+      # Refs keeps the names for back-compat with anything that imported
+      # them directly.
+      def self.data_candidates = Esp::Mw::DataFiles.candidates
+      def self.default_data = Esp::Mw::DataFiles.default
+
+      def self.exit_on_failure? = true
+
+      class_option :json, type: :boolean, desc: 'Output structured JSON instead of human text'
+      class_option :references_dir, type: :string,
+                                    desc: 'Override the references directory ' \
+                                          '(default: $ESP_REFERENCES_DIR or $ESP_DATA_DIR/references)'
+
+      desc 'unpack', 'Convert vanilla ESMs to JSON under the per-user references directory'
+      option :data, type: :string,
+                    desc: 'Data Files directory (default: $MORROWIND_DATA or the detected install)'
+      def unpack
+        data = options[:data] || ENV['MORROWIND_DATA'] || self.class.default_data
+        out = resolved_references_dir
+        FileUtils.mkdir_p(out)
+        unpacked = []
+        skipped = []
+        MASTERS.each do |name|
+          src = File.join(data, "#{name}.esm")
+          if File.exist?(src)
+            dst = File.join(out, "#{name}.esm.json")
+            Esp::Mw::Tes3conv.convert(src, dst)
+            unpacked << { name: name, source: src, output: dst }
+          else
+            skipped << { name: name, source: src, reason: 'not found' }
+          end
+        end
+        respond({ unpacked: unpacked, skipped: skipped, references_dir: out }) do
+          unpacked.each { |u| say t('refs.unpack.done', name: u[:name], output: u[:output]) }
+          skipped.each  { |s| say t('refs.unpack.skip', source: s[:source], reason: s[:reason]) }
+        end
+      end
+
+      desc 'index', 'Build/refresh the SQLite index over the per-user references directory'
+      def index
+        idx = Esp::Mw::ReferenceIndex.new(source_dir: resolved_references_dir)
+        n = idx.rebuild!
+        respond({ indexed: n, db_path: idx.db_path, source_dir: idx.source_dir }) do
+          say t('refs.index.indexing', dir: idx.source_dir, db: idx.db_path)
+          say t('refs.index.indexed', count: n)
+        end
+      rescue RuntimeError => e
+        fail_with(e.message)
+      end
+
+      desc 'find [QUERY]', 'Find vanilla records — substring match on id + name by default'
+      option :type,  type: :string,  desc: 'Filter by record type (e.g. Npc, Cell, Script)'
+      option :like,  type: :string,  desc: "SQL LIKE pattern on id (e.g. 'Fargoth%')"
+      option :exact, type: :boolean, desc: 'Match QUERY as an exact id instead of a substring'
+      option :show,  type: :boolean, desc: 'Print full JSON of each match'
+      option :limit, type: :numeric, default: 100, desc: 'Max rows to print'
+      def find(query = nil)
+        fail_with(t('refs.find.usage')) unless any_filter?(query)
+        idx = require_index!
+        criteria = { query: query, type: options[:type], like: options[:like], exact: options[:exact] }
+        rows = idx.find(**criteria, limit: options[:limit])
+        total = idx.count_matching(**criteria)
+        options[:show] ? respond_show(idx, rows, total) : respond_match(rows, total)
+      end
+
+      no_commands do
+        def any_filter?(query)
+          query || options[:type] || options[:like]
+        end
+
+        # The references directory this invocation operates on. Precedence:
+        # --references-dir flag (per-call override for power users / CI) →
+        # the ReferenceIndex default ($ESP_REFERENCES_DIR / $ESP_DATA_DIR /
+        # ~/.config/esp).
+        def resolved_references_dir
+          override = options[:references_dir]
+          override.nil? || override.to_s.empty? ? Esp::Mw::ReferenceIndex.default_source_dir : override
+        end
+
+        def require_index!
+          idx = Esp::Mw::ReferenceIndex.new(source_dir: resolved_references_dir)
+          fail_with(t('errors.no_index', db: idx.db_path)) unless File.exist?(idx.db_path)
+
+          idx
+        end
+
+        def respond_match(rows, total)
+          respond({ matches: rows, count: rows.size, total: total }) do
+            if rows.empty?
+              say(t('refs.find.no_matches'))
+            else
+              render_table(rows)
+              say(truncation_note(rows.size, total))
+            end
+          end
+        end
+
+        def respond_show(idx, rows, total)
+          records = rows.map { |r| idx.fetch_record(r['source_esm'], r['record_index']) }
+          respond({ records: records, count: records.size, total: total }) do
+            records.each_with_index do |rec, i|
+              puts '---' if i.positive?
+              puts JSON.pretty_generate(rec)
+            end
+            say(truncation_note(records.size, total))
+          end
+        end
+
+        def truncation_note(shown, total)
+          return total == 1 ? t('refs.find.total_one') : t('refs.find.total', total: total) if shown >= total
+
+          t('refs.find.truncated', shown: shown, total: total)
+        end
+
+        def render_table(rows)
+          src_w  = [12, *rows.map { |r| r['source_esm'].length }].max
+          type_w = [4,  *rows.map { |r| r['type'].length }].max
+          rows.each do |r|
+            puts "#{r['source_esm'].ljust(src_w)}  #{r['type'].ljust(type_w)}  #{r['id']}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/esp/cli/support.rb

@@ -0,0 +1,87 @@
+require 'json'
+require 'thor'
+
+module Esp
+  class CLI < Thor
+    # Helpers shared by the root CLI and every subcommand. Kept in one module
+    # rather than copy-pasted per class. They're private, and Thor only
+    # registers methods defined directly in a command class as commands, so
+    # these never become commands either way.
+    module Support
+      private
+
+      # Tool-UI string lookup (see Esp::UI).
+      def t(key, **vars)
+        Esp.t(key, **vars)
+      end
+
+      # JSON when --json is set, otherwise yield to the block for human text.
+      # Both branches see the same payload.
+      def respond(payload)
+        if options[:json]
+          $stdout.puts(JSON.generate(payload))
+        elsif block_given?
+          yield(payload)
+        end
+      end
+
+      # Error path: {"error": msg} on stderr in JSON mode, else a plain line.
+      def fail_with(message)
+        warn(options[:json] ? JSON.generate(error: message) : "error: #{message}")
+        exit(1)
+      end
+
+      # The project root this invocation operates on. Precedence (step 23.5
+      # slice 3 full chain):
+      #
+      #   1. --root flag (explicit per-call override).
+      #   2. $ESP_PROJECT_ROOT (per-shell default).
+      #   3. cwd walk-up to the nearest .esp/project.json (git-style
+      #      discovery; legacy .espresso/project.json accepted).
+      #   4. Esp::ROOT (toolchain repo) as last-resort fallback. Emits a
+      #      one-line stderr warning naming the fallback + a suggested
+      #      `esp init`, so a user is never confused why the build went to
+      #      this dir.
+      def resolve_root
+        explicit = options[:root]
+        return File.expand_path(explicit) if explicit && !explicit.to_s.empty?
+
+        env = ENV.fetch('ESP_PROJECT_ROOT', nil)
+        return File.expand_path(env) if env && !env.to_s.empty?
+
+        walked = Esp::ProjectMarker.find_walking_up(Dir.pwd)
+        return walked if walked
+
+        warn_no_project_context
+        Esp::ROOT
+      end
+
+      # Merge the resolved `root` into a params hash for `Esp::Operations.dispatch`.
+      # Always sets `root` (resolve_root always returns something) so the op
+      # never has to re-derive the precedence chain on the server side.
+      def params_with_root(params = {})
+        params.merge('root' => resolve_root)
+      end
+
+      # Backward-compatible helper for slice-1 callers that only wanted the
+      # explicit --root flag without firing the full resolution. Today no
+      # CLI command uses it; kept for tooling that imports Support directly.
+      def project_root
+        explicit = options[:root]
+        explicit.nil? || explicit.to_s.empty? ? nil : File.expand_path(explicit)
+      end
+
+      # Print the fallback warning at most once per invocation. Goes to
+      # stderr so JSON callers' stdout stays clean; respects ESP_QUIET=1
+      # for scripted invocations that know they're inside the toolchain
+      # repo and don't want noise.
+      def warn_no_project_context
+        return if @no_project_context_warned
+        return if ENV['ESP_QUIET'] == '1'
+
+        @no_project_context_warned = true
+        warn t('cli.no_project_context', root: Esp::ROOT)
+      end
+    end
+  end
+end

data/lib/esp/cli.rb

@@ -0,0 +1,317 @@
+require 'json'
+require 'thor'
+require 'fileutils'
+
+module Esp
+  class CLI < Thor
+    include Support
+
+    def self.exit_on_failure? = true
+
+    class_option :json, type: :boolean, desc: 'Output structured JSON instead of human text'
+    class_option :root, type: :string,
+                        desc: 'Project root (defaults to the active project or the toolchain repo)'
+
+    map 'extract-scripts' => :extract_scripts
+    map 'new' => :new_mod
+
+    desc 'version', 'Print esp version'
+    def version
+      respond({ version: Esp::VERSION }) { |p| say p[:version] }
+    end
+
+    desc 'doctor', 'Check install prerequisites (Ruby, tes3conv, references index)'
+    def doctor
+      ruby_ok = Gem::Version.new(RUBY_VERSION) >= Gem::Version.new(Esp::MINIMUM_RUBY_VERSION)
+      tes3conv = tes3conv_path
+      refs_db = Esp::Mw::ReferenceIndex.default_db_path
+      refs_present = File.exist?(refs_db)
+      problems = [!ruby_ok, tes3conv.nil?].count(true)
+
+      payload = {
+        ruby: { version: RUBY_VERSION, required: Esp::MINIMUM_RUBY_VERSION, ok: ruby_ok },
+        esp: Esp::VERSION,
+        tes3conv: { found: !tes3conv.nil?, path: tes3conv },
+        references_index: { present: refs_present, path: refs_db },
+        problems: problems
+      }
+      respond(payload) { print_doctor(payload) }
+      exit(1) if problems.positive?
+    end
+
+    desc 'init [NAME]',
+         'Bootstrap an esp project here (or in NAME subdir) — writes .esp/project.json + git init'
+    option :game, type: :string, default: 'mw',
+                  desc: 'Game plugin (default: mw; pass --game ob etc. once those plugins exist)'
+    option :force, type: :boolean, desc: 'Re-initialise even if .esp/project.json already exists'
+    def init(name = nil)
+      target = File.expand_path(name ? File.join(Dir.pwd, name) : Dir.pwd)
+      game = options[:game].to_s
+
+      unless Esp::Plugins.known?(game)
+        fail_with(t('errors.plugins.unknown_game',
+                    game: game, known: Esp::Plugins.ids.join(', ')))
+      end
+
+      if Esp::ProjectMarker.find_in(target) && !options[:force]
+        fail_with(t('cli.init.already_initialised', path: target))
+      end
+
+      FileUtils.mkdir_p(File.join(target, 'mods'))
+      FileUtils.mkdir_p(File.join(target, 'dist'))
+      Esp::Vcs.run_git_init(target) unless File.directory?(File.join(target, '.git'))
+      ensure_default_gitignore(target)
+      Esp::ProjectMarker.write(target, name: File.basename(target), game: game)
+
+      respond({ root: target, game: game }) do
+        say t('cli.init.created', path: target, game: game)
+        say t('cli.init.next')
+      end
+    end
+
+    desc 'setup', 'Configure git diff driver + tracked pre-commit hooks'
+    def setup
+      configured = []
+      Dir.chdir(Esp::ROOT) do
+        { 'diff.tes3.textconv' => 'tes3conv',
+          'diff.tes3.binary' => 'true',
+          'core.hooksPath' => '.githooks' }.each do |key, value|
+          system('git', 'config', key, value, exception: true)
+          configured << { key: key, value: value }
+        end
+      end
+      respond({ configured: configured }) do
+        say t('cli.setup.diff_driver')
+        say t('cli.setup.hooks_path')
+      end
+    end
+
+    desc 'new MOD', 'Scaffold a new mod folder under mods/<MOD>/'
+    option :format, type: :string, default: 'json',
+                    desc: 'Source format: json | rb | py | js | mjs | ts'
+    option :author, type: :string, desc: 'Author name (default: git config user.name)'
+    option :description, type: :string, desc: 'Plugin description'
+    option :force, type: :boolean, desc: 'Overwrite an existing mod folder'
+    def new_mod(mod)
+      root = resolve_root
+      result = Esp::Mw::Scaffolder.create(
+        mod,
+        format: options[:format],
+        author: options[:author],
+        description: options[:description],
+        force: options[:force],
+        root: root
+      )
+      relative = ->(p) { p.sub("#{root}/", '') }
+      payload = {
+        mod: result.mod,
+        format: result.format,
+        source: relative.call(result.source),
+        readme: relative.call(result.readme)
+      }
+      respond(payload) do
+        say t('cli.new.created', path: payload[:source])
+        say t('cli.new.created', path: payload[:readme])
+        say t('cli.new.next', mod: result.mod)
+      end
+    rescue ArgumentError => e
+      fail_with(e.message)
+    end
+
+    desc 'unpack PLUGIN [NAME]', 'Import a plugin (a path, or an installed plugin NAME) to mods/<name>/'
+    option :config, type: :string, desc: 'openmw.cfg to resolve a bare plugin NAME against'
+    def unpack(plugin, name = nil)
+      params = params_with_root('plugin' => plugin, 'name' => name, 'config' => options[:config]).compact
+      result = Esp::Operations.dispatch(:unpack, params)
+      respond(result) do
+        say t('cli.unpack.done', plugin: result[:plugin], output: result[:output])
+      end
+    rescue Esp::Operations::InputError, Esp::Mw::Tes3conv::ConvertFailed, Esp::Mw::Tes3conv::NotFound => e
+      fail_with(e.message)
+    end
+
+    desc 'build [MOD]', 'Build mods/<MOD>/<MOD>.{json,rb,py,js,mjs,ts} -> dist/<MOD>[.locale].esp'
+    option :all,     type: :boolean, desc: 'Build every mod in mods/'
+    option :install, type: :boolean, desc: 'After building, register the mod(s) with openmw.cfg'
+    option :config,  type: :string,  desc: 'openmw.cfg to register with (implies --install target)'
+    option :locale,  type: :string,
+                     desc: 'Build with this locale (suffixes the output: dist/<MOD>.<locale>.esp)'
+    def build(mod = nil)
+      fail_with(t('cli.build.usage')) if !options[:all] && mod.nil?
+
+      root = resolve_root
+      mods = options[:all] ? Esp::Mw::Builder.discover_mods(root: root) : [mod]
+      results = mods.map { |m| build_one(m, locale: options[:locale], root: root) }
+      installs = options[:install] ? mods.map { |m| install_one(m) } : []
+      respond({ results: results, installs: installs }) do
+        results.each do |r|
+          r[:logs].each { |line| say(line) }
+          say t('cli.build.done', mod: r[:mod], output: r[:output])
+        end
+        installs.each { |ins| say_install_actions(ins) }
+      end
+    end
+
+    desc 'install MOD', "Register dist/<MOD>.esp with OpenMW's openmw.cfg (and/or copy to Data Files)"
+    option :copy_to, type: :string,
+                     desc: 'Also copy the built .esp into PATH ' \
+                           '(original-engine users: Morrowind/Data Files/)'
+    option :to_data_files, type: :boolean,
+                           desc: 'Also copy to the auto-detected Morrowind Data Files dir ' \
+                                 '(MORROWIND_DATA env override)'
+    option :register_openmw, type: :boolean, default: true,
+                             desc: 'Register with openmw.cfg (default: true; --no-register-openmw skips)'
+    def install(mod)
+      params = params_with_root(
+        'mod' => mod,
+        'copy_to' => options[:copy_to],
+        'to_data_files' => options[:to_data_files],
+        'register_openmw' => options[:register_openmw]
+      ).compact
+      result = Esp::Operations.dispatch(:install, params)
+      respond(result) do
+        Array(result[:actions]).each do |a|
+          say(t(a[:added] ? 'cli.install.added' : 'cli.install.present', line: a[:line]))
+        end
+        say t('cli.install.copied', path: result[:copied_to]) if result[:copied_to]
+        say t('cli.install.done')
+      end
+    rescue Esp::Operations::InputError => e
+      fail_with(e.message)
+    end
+
+    desc 'lint MOD', 'Find dangling refs and missing-master issues using the reference index'
+    def lint(mod)
+      result = Esp::Operations.dispatch(:lint, params_with_root('mod' => mod))
+      issues = result[:issues]
+      respond(result) do
+        if issues.empty?
+          say t('cli.lint.ok')
+        else
+          issues.each { |raw| say(format_issue(Esp::Mw::Linter::Issue.new(**raw))) }
+          say t('cli.lint.summary', errors: result[:errors], warnings: result[:warnings])
+        end
+      end
+      exit(1) if result[:errors].positive?
+    rescue Esp::Operations::InputError, Esp::Mw::Loader::LoadError => e
+      fail_with(e.message)
+    end
+
+    desc 'watch MOD', 'Rebuild MOD on any change under mods/<MOD>/. Blocks until Ctrl-C.'
+    option :locale, type: :string, desc: 'Build with this locale on each change'
+    def watch(mod)
+      root = resolve_root
+      Esp::Watcher.new(mod, locale: options[:locale], root: root).start
+    rescue Esp::Mw::Loader::LoadError => e
+      fail_with(e.message)
+    end
+
+    desc 'serve', 'Start the HTTP API on localhost (mirrors the CLI; same payload shapes)'
+    option :port, type: :numeric, default: Esp::HttpServer::DEFAULT_PORT,
+                  desc: 'TCP port to bind on localhost'
+    def serve
+      server = Esp::HttpServer.new(port: options[:port])
+      say t('cli.serve.listening', port: options[:port])
+      say t('cli.serve.routes')
+      server.start
+    end
+
+    desc 'extract-scripts MOD',
+         "Move every Script record's inline text into mods/<MOD>/scripts/<id>.mwscript"
+    def extract_scripts(mod)
+      result = Esp::Operations.dispatch(:extract_scripts, params_with_root('mod' => mod))
+      respond(result) do
+        result[:extracted].each { |id| say t('cli.extract_scripts.extracted', id: id) }
+        result[:skipped].each   { |id| say t('cli.extract_scripts.skipped', id: id) }
+        say t('cli.extract_scripts.done', extracted: result[:extracted].size, skipped: result[:skipped].size)
+      end
+    rescue ArgumentError, Esp::Mw::Loader::LoadError, Esp::Operations::InputError => e
+      fail_with(e.message)
+    end
+
+    desc 'plugins SUBCOMMAND', 'Inspect installed OpenMW plugins'
+    subcommand 'plugins', Plugins
+
+    desc 'refs SUBCOMMAND', 'Manage vanilla ESM references'
+    subcommand 'refs', Refs
+
+    desc 'i18n SUBCOMMAND', 'Translation catalogue tools'
+    subcommand 'i18n', I18nCli
+
+    desc 'docs SUBCOMMAND', 'Generate / introspect reference documentation'
+    subcommand 'docs', Docs
+
+    desc 'mcp SUBCOMMAND', 'Model Context Protocol server for AI tools'
+    subcommand 'mcp', Mcp
+
+    no_commands do
+      def format_issue(issue)
+        label = issue.severity == :error ? 'ERROR' : 'WARN '
+        field = "#{issue.record_id}.#{issue.field}"
+        "#{label}  #{issue.record_type.to_s.ljust(10)}  #{field}  ->  #{issue.ref_id}: #{issue.message}"
+      end
+
+      def build_one(mod, locale: nil, root: nil)
+        root ||= resolve_root
+        result = Esp::Mw::Builder.build(mod, locale: locale, root: root)
+        { mod: mod, output: result.output.sub("#{root}/", ''), logs: result.logs }
+      rescue Esp::Mw::Preflight::ValidationError, Esp::Mw::Loader::LoadError, ArgumentError,
+             Esp::Mw::Tes3conv::ConvertFailed, Esp::Mw::Tes3conv::NotFound => e
+        fail_with(e.message)
+      end
+
+      # Write a minimal .gitignore on first init. mods/ stays tracked
+      # (source!); dist/ does not (build artifacts). Skips an existing
+      # .gitignore so we don't clobber a user's choices.
+      def ensure_default_gitignore(target)
+        path = File.join(target, '.gitignore')
+        return if File.exist?(path)
+
+        File.write(path, "dist/\n")
+      end
+
+      def install_one(mod)
+        Esp::Operations.dispatch(:install, params_with_root('mod' => mod, 'config' => options[:config]))
+      rescue Esp::Operations::InputError => e
+        fail_with(e.message)
+      end
+
+      def say_install_actions(install)
+        install[:actions].each do |a|
+          say t(a[:added] ? 'cli.install.added' : 'cli.install.present', line: a[:line])
+        end
+      end
+
+      # Resolve tes3conv the same way Esp::Mw::Tes3conv will at build time:
+      # honour $TES3CONV (may be an absolute path), else search PATH. Returns
+      # the resolved absolute path, or nil if not found.
+      def tes3conv_path
+        bin = Esp::Mw::Tes3conv::BIN
+        return File.expand_path(bin) if bin.include?(File::SEPARATOR) && File.executable?(bin)
+
+        ENV.fetch('PATH', '').split(File::PATH_SEPARATOR).each do |dir|
+          candidate = File.join(dir, bin)
+          return candidate if File.executable?(candidate) && !File.directory?(candidate)
+        end
+        nil
+      end
+
+      def print_doctor(payload)
+        say t('cli.doctor.header')
+        say t('cli.doctor.esp', version: payload[:esp])
+        ruby = payload[:ruby]
+        say t(ruby[:ok] ? 'cli.doctor.ruby_ok' : 'cli.doctor.ruby_old',
+              version: ruby[:version], required: ruby[:required])
+        t3 = payload[:tes3conv]
+        say t(t3[:found] ? 'cli.doctor.tes3conv_found' : 'cli.doctor.tes3conv_missing', path: t3[:path])
+        refs = payload[:references_index]
+        say t(refs[:present] ? 'cli.doctor.refs_present' : 'cli.doctor.refs_missing', path: refs[:path])
+        if payload[:problems].positive?
+          say t('cli.doctor.problems', count: payload[:problems])
+        else
+          say t('cli.doctor.ok')
+        end
+      end
+    end
+  end
+end

data/lib/esp/docs_generator.rb

@@ -0,0 +1,148 @@
+require 'fileutils'
+require 'stringio'
+
+module Esp
+  # 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.
+  module DocsGenerator
+    AUTO_OPEN = '<!-- esp:auto — regenerated by `esp docs build`; edits here are overwritten -->'.freeze
+    AUTO_CLOSE = '<!-- /esp:auto — write durable docs below this line; they survive rebuilds -->'.freeze
+    LEGACY_AUTO_CLOSE = '<!-- /mw:auto — write durable docs below this line; they survive rebuilds -->'.freeze
+
+    class << self
+      def build(output_dir:)
+        api_dir = File.join(output_dir, 'api')
+        FileUtils.mkdir_p(api_dir)
+
+        write_doc(File.join(output_dir, 'commands.md'), render_commands)
+        module_docs = Esp::Introspection.module_docs
+        module_docs.each do |mod|
+          write_doc(File.join(api_dir, "#{slug_for(mod[:name])}.md"), render_module(mod))
+        end
+        write_doc(File.join(api_dir, 'index.md'), render_api_index(module_docs))
+
+        { commands: File.join(output_dir, 'commands.md'),
+          api_index: File.join(api_dir, 'index.md'),
+          api_modules: module_docs.map { |m| File.join(api_dir, "#{slug_for(m[:name])}.md") } }
+      end
+
+      # Write the regenerated auto block, then re-attach the file's existing
+      # hand-written tail (everything after AUTO_CLOSE) verbatim — or scaffold
+      # one if the file is new.
+      def write_doc(path, body)
+        File.write(path, "#{AUTO_OPEN}\n\n#{body.strip}\n\n#{AUTO_CLOSE}#{manual_tail(path)}")
+      end
+
+      def render_commands
+        out = StringIO.new
+        tree = Esp::Introspection.command_tree
+        out.puts '# Command reference'
+        out.puts
+        out.puts 'Every command accepts `--json` for structured output to stdout.'
+        out.puts 'Errors print as `{"error": "..."}` to stderr with a non-zero exit.'
+        out.puts
+        out.puts '## Top-level commands'
+        out.puts
+        tree[:commands].each { |cmd| render_command(out, cmd) }
+        tree[:subcommands].each { |sub| render_subcommand_section(out, sub) }
+        out.string
+      end
+
+      def render_module(mod)
+        <<~MD
+          # #{mod[:name]}
+
+          **Source:** `#{mod[:source]}`
+
+          #{mod[:description]}
+        MD
+      end
+
+      def render_api_index(modules)
+        out = StringIO.new
+        out.puts '# API reference'
+        out.puts
+        out.puts 'Core library modules. Shell modules are `Esp::<Name>`;'
+        out.puts 'Morrowind-plugin modules are `Esp::Mw::<Name>`.'
+        out.puts
+        modules.each do |mod|
+          out.puts "- [`#{mod[:name]}`](#{slug_for(mod[:name])}.md)"
+        end
+        out.string
+      end
+
+      private
+
+      # The hand-written region of an existing file is everything after the
+      # AUTO_CLOSE marker; preserve it verbatim so rebuilds never touch it. A
+      # new (or pre-marker) file gets just a trailing newline — the close
+      # marker already invites authors to write below it.
+      def manual_tail(path)
+        return "\n" unless File.exist?(path)
+
+        existing = File.read(path)
+        if (marker = existing.index(AUTO_CLOSE))
+          existing[(marker + AUTO_CLOSE.length)..]
+        elsif (legacy = existing.index(LEGACY_AUTO_CLOSE))
+          existing[(legacy + LEGACY_AUTO_CLOSE.length)..]
+        else
+          "\n"
+        end
+      end
+
+      def render_command(out, cmd)
+        full = ['esp', *cmd[:path]].join(' ')
+        out.puts "### `#{full}`"
+        out.puts
+        out.puts cmd[:description] if cmd[:description] && !cmd[:description].empty?
+        out.puts
+        out.puts "Usage: `esp #{cmd[:usage]}`"
+        out.puts
+        render_options(out, cmd[:options])
+        out.puts
+      end
+
+      def render_subcommand_section(out, sub)
+        out.puts "## `esp #{sub[:name]}` subcommand group"
+        out.puts
+        out.puts sub[:description] if sub[:description]
+        out.puts
+        sub[:commands].each { |cmd| render_command(out, cmd) }
+      end
+
+      def render_options(out, options)
+        return if options.empty?
+
+        out.puts 'Options:'
+        options.uniq { |o| o[:name] }.each { |opt| out.puts option_line(opt) }
+      end
+
+      def option_line(opt)
+        type_label = opt[:type] == :boolean ? '' : " #{opt[:type].to_s.upcase}"
+        desc = opt[:description] || '(no description)'
+        "- `--#{opt[:name]}#{type_label}` — #{desc}"
+      end
+
+      # 'Esp::Builder'        → 'builder'
+      # 'Esp::Mw::Builder'    → 'mw-builder'
+      # 'Esp::ReferenceIndex' → 'reference-index'
+      def slug_for(constant_name)
+        constant_name
+          .sub(/\AEsp::/, '')
+          .gsub('::', '-')
+          .gsub(/([a-z])([A-Z])/, '\1-\2')
+          .downcase
+      end
+    end
+  end
+end