@creeperhost/modlens-mcp 1.6.19 → 1.6.21

package/ATTRIBUTION.md

@@ -6,4 +6,11 @@ If ModLens substantially powers an end-user-facing feature in your product or se
 
 Suggested wording:
 
-Powered by ModLens by CreeperHost
+Powered by ModLens by CreeperHost
+
+## Third-party license reference data
+
+The hosted mod license matcher includes selected standard license texts from
+[SPDX License List Data 3.27.0](https://github.com/spdx/license-list-data/tree/v3.27.0),
+whose data is dedicated to the public domain under CC0-1.0. These reference
+texts identify grants; they do not themselves license any Minecraft or mod code.

package/README.md

@@ -4,6 +4,33 @@ MCP server and CLI for browsing, decompiling, and analyzing Minecraft mod JARs.
 
 Store mod metadata, class indexes, mixin targets, AT/AW entries, and decompiled source in a local database — **embedded SQLite by default** (zero setup), or PostgreSQL/PGlite if you want them. Query everything via AI (MCP) or command line (CLI).
 
+## Optional live development client
+
+The `runtime` MCP tool can prepare and launch a **Minecraft 26.3 / Java 25** dev
+client, detect IntelliJ launches, monitor JVM failures and memory pressure, and
+control input without desktop automation. It supports normal, visible watch-only,
+and hidden windows. Ask the AI to call `runtime` with `action:"help"` or set it up
+for your mod project. With remote MCP, Codex runs the local `--runtime` helper;
+with local stdio MCP, the tools execute directly. No second MCP connection is needed.
+See [runtime setup, examples, and compatibility limits](RUNTIME.md).
+
+## Reporting an issue from your coding agent
+
+Ask your agent to **report a ModLens issue on GitHub**. The `report_issue` MCP tool
+works locally and remotely: `action:"help"` explains the workflow, and
+`action:"prepare"` produces a draft from a title, summary, reproduction steps,
+expected/actual behavior, environment and an optional sanitized diagnostic excerpt.
+It includes the ModLens server version automatically.
+
+The tool directs the agent to check for duplicates and submit to
+[CreeperHost/modlens-mcp](https://github.com/CreeperHost/modlens-mcp/issues) using
+its existing GitHub connector or `gh issue create --body-file`. Without GitHub
+access, it returns a draft and a manual submission link. ModLens needs no GitHub
+credentials and does not publish the report itself; `executed:false` means only
+the draft was prepared. Remove credentials, private source and personal details
+before supplying diagnostic excerpts. Reports are submitted when the user requests
+it, rather than automatically for every error.
+
 ## Installation
 
 ### Option A — npx (recommended, no clone required)
@@ -718,13 +745,23 @@ All tool actions have been consolidated into **24 grouped tools** to stay within
 | action | Key params | Description |
 |--------|-----------|-------------|
 | `ingest` | entries[] | Add migration guide entries |
-| `seed` | — | Populate built-in NeoForge/Forge/Fabric guides |
-| `get` | id | Get primer by DB id |
-| `by_version` | fromVersion, toVersion, modloader | All guides covering a version span |
+| `seed` | fetchContent=true | Populate the official Minecraft/Forge/NeoForge primer catalogue and cache missing guide bodies |
+| `get` | id, startLine=1, maxLines=400, fetchContent=true, refresh=false | Read cached Markdown; fetch missing content automatically |
+| `by_version` | fromVersion, toVersion, modloader, includeContent=false, maxChars=60000, cursor, fetchContent=true | Ordered migration steps; optionally bundle their Markdown, including vanilla changes for the selected loader |
 | `search` | query, modloader, fromVersion, toVersion, limit | Full-text search |
 | `list` | modloader, limit | List all primers |
 | `delete` | id | Remove by DB id |
 
+Start with `{"action":"seed"}` on a fresh database, then use `{"action":"by_version","fromVersion":"1.21.1","toVersion":"1.21.5","modloader":"neoforge"}`. This returns the vanilla and NeoForge guides for the intervening transitions. Call `{"action":"get","id":<returned id>}` for each guide, following `nextStartLine` until it is null. Guides retain headings, tables, links and code blocks; pagination does not truncate the cached document. The catalogue contains the steps published upstream, so a result is not a guarantee of coverage for every release or loader.
+
+To read a whole migration range, request `{"action":"by_version","fromVersion":"1.21.1","toVersion":"26.1","modloader":"neoforge","includeContent":true}`. The server fetches missing bodies and returns the original Markdown with each guide's ID, title, source URL, loader and version boundaries. Small ranges fit in one response. Larger ranges return `nextCursor`; repeat the same request with `cursor` set to that value until it is null. `count` is the total number of matching guides; `primers` contains the current page. Existing calls without `includeContent` retain their metadata-only response.
+
+Bundled pages share a `maxChars` text budget (1,000–200,000, default 60,000) and contain at most 20 guides. Long guides may span pages: concatenate `content` chunks for the same ID directly, without inserting separators. `startOffset`, `endOffset` (exclusive), `totalChars` and `contentChars` count UTF-16 code units; pagination preserves Unicode characters. Each guide reports `contentStatus` and `truncated`; the outer `truncated` reports whether another page remains. Cursors detect changes to the selected catalogue or partly read content and ask you to restart. `fetchContent:false` reads only cached bodies and reports missing ones with `contentStatus:"missing"` and a page-level `missing` count. Fetch failures retain successful guides, report `contentStatus:"fetch_failed"` and an error per failed guide, and set the page-level `failed` count and MCP error flag. Retry those IDs with `get`. The CLI equivalent is `primers by-version 1.21.1 26.1 --modloader=neoforge --include-content`, with optional `--max-chars=`, `--cursor=` and `--fetch-content=false`; fetch failures set a nonzero exit code after printing the page.
+
+`get` and `seed` fetch missing content on the MCP server and store it in its configured database, so this also works with a remote server. Cached reads work without Internet access. Use `fetchContent:false` for metadata-only reads/seeding, or `refresh:true` on `get` to replace cached content. Fetch failures return an error; failed refreshes preserve the previous content. `ingest` still accepts supplied content or an explicit `entries[].fetchContent:true`, and reports failed entries without saving them. The CLI equivalents are `primers seed --fetch-content=false` and `primers get <id> --refresh --start-line=401`.
+
+Existing installations repair the old built-in placeholder URLs on the first primer operation; no database reset is needed. IDs are retained where possible, and obsolete duplicates or placeholders are marked superseded with replacement guides. Custom entries and existing content are preserved.
+
 ### 10. `mc_registry` — MC Registry & Meta Data
 
 | action | Key params | Description |
@@ -1026,6 +1063,46 @@ node dist/cli.js check-updates 2
 
 ---
 
+## Hosted access limits
+
+HTTP MCP (`MCP_PORT`) enables hosted limits by default. Local stdio retains its existing access. Hosted developers can browse source in pages, search, inspect bytecode and members, compare versions, inspect mixins and data, and upload their private Gradle environments. Bulk decompile/index commands, source/graph/embedding exports, raw JAR reads, host paths and filesystem administration are reserved for the local operator. KubeJS directory access and compatibility checks using host-local JAR paths are also local-only.
+
+| Setting | Default | Scope |
+| --- | --- | --- |
+| `MODLENS_HOSTED_SOURCE_LINES` | 200 | Source/bytecode lines per response, shared across search snippets |
+| `MODLENS_HOSTED_RESPONSE_BYTES` | 131072 (128 KiB) | Serialized text content per tool response |
+| `MODLENS_HOSTED_DAILY_BYTES` | 5242880 (5 MiB) | Delivered tool content per account per UTC day |
+| `MODLENS_HOSTED_PERIOD_BYTES` | 52428800 (50 MiB) | Delivered tool content per account per fixed 30-day period |
+| `MODLENS_HOSTED_DAILY_REQUESTS` | 1000 | Tool calls per account per UTC day |
+| `MODLENS_HOSTED_MINUTE_REQUESTS` | 120 | Tool calls per account per minute |
+
+The byte allowance includes all successful tool content, including metadata, search snippets and bytecode. It measures UTF-8 JSON content before transport compression. Cached files and inbound upload bytes are excluded. Each source text field has a 32 KiB cap. Searches with `limit`/`top` are capped at 50 results; responses exceeding the byte limit require a narrower query.
+
+Use `startLine` (1-based) and `maxLines` for `mc_source get_source/bytecode`, `mod source/decompile_class`, `mod_bytecode bytecode`, and `project source/bytecode`. A range may start anywhere; the hosted cap bounds its length. Prepare shared indexes and ingest mods through the operator's local interface; hosted clients can upload their own Gradle environment through `project`.
+
+### Mod source access
+
+Hosted mod source responses include licence and attribution notices. Use `mod_license` with `action=check` and `modId`/`dbId` to check availability. For uploaded projects, supply `projectKey`, `environmentId` and `className` instead.
+
+When hosted source is unavailable, `action=local_plan` provides instructions for decompiling your local JAR with your explicit consent. Run the returned request on your computer:
+
+```bash
+npx -y @creeperhost/modlens-mcp --local-mod --request-file local-request.json
+```
+
+### Bind allowances to authenticated accounts
+
+For public HTTP access, put an authenticated HTTPS gateway in front of the server. Set `MODLENS_HOSTED_PROXY_SECRET` to a random secret of at least 32 characters. The gateway must remove caller-provided `x-modlens-*` headers and inject:
+
+- `x-modlens-proxy-secret`: the server's secret, never sent to clients.
+- `x-modlens-user-id`: a stable, verified account identifier selected by the gateway. Reconnecting, rotating tokens, or using another client must retain this identifier.
+
+Restrict network access to the origin to that gateway and protect the gateway-to-server connection. The server checks the secret and account on every MCP request and binds each session to its account. The gateway manages authentication and account access. Multiple login methods for one account must use the same identifier.
+
+Without the proxy secret, callers share a single global allowance, regardless of self-asserted user IDs or tokens. This fallback provides limits, **not authentication**, and one caller can exhaust it for everyone. `MODLENS_HOSTED_LIMITS=0` disables these controls and gateway-secret checking entirely; use it only for trusted private HTTP deployments.
+
+Usage persists in `hosted_usage` in the configured database. Checks and updates are atomic, including parallel calls; reconnects and server restarts do not reset usage. All replicas must use the same persistent database and account mapping. The 30-day periods align to Unix-epoch boundaries, rather than rolling with each request. Restoring an older database restores its older counters. Database failures reject hosted tool calls before releasing output.
+
 ## Acknowledgements
 
 ### Services & APIs
@@ -1037,9 +1114,9 @@ node dist/cli.js check-updates 2
 - **[Mojang](https://www.minecraft.net)** — for publishing official Mojmap mappings and the Piston Meta API used for version discovery and JAR downloads.
 
 ### Modloader teams
-- **[NeoForged team](https://github.com/neoforged/NeoForge)** — for NeoForge, the [NeoForge documentation](https://docs.neoforged.net) seeded into the docs database, and the migration changelogs seeded into the primers database.
+- **[NeoForged team](https://github.com/neoforged/NeoForge)** — for NeoForge, the [NeoForge documentation](https://docs.neoforged.net) seeded into the docs database, and the [migration primer catalogue](https://docs.neoforged.net/primer/docs/) used by the primers tool.
 - **[FabricMC team](https://github.com/FabricMC)** — for the [Fabric Wiki](https://fabricmc.net/wiki) and [Yarn mappings](https://github.com/FabricMC/yarn) seeded into the docs database, Intermediary mappings used by the `mappings` tool, and [mcsrc.dev](https://mcsrc.dev) whose source browsing and class analysis features inspired our `mc_source` tool.
-- **[MinecraftForge team](https://github.com/MinecraftForge)** — for the pre-fork Forge migration changelogs (1.18.2 → 1.20.1) seeded into the primers database.
+- **[MinecraftForge team](https://github.com/MinecraftForge)** — for Forge and the API changes documented in the Forge migration primers.
 
 ### Community contributors
 - **[MCPHackers](https://mcphackers.org/)** — for [RetroMCP](https://github.com/MCPHackers/RetroMCP-Java), providing the Tiny v2 mappings that enable decompilation of legacy Minecraft versions (Alpha, Beta, and pre-1.7.10 releases).

package/RUNTIME.md

@@ -0,0 +1,262 @@
+# Optional live Minecraft development runtime
+
+ModLens can launch or detect a **Minecraft Java 26.3 / Java 25** development client,
+observe JVM health and failures, and send inputs directly through LWJGL's SDL3
+bindings. Desktop automation and an IntelliJ plugin are not required. This is an
+initial 26.3 adapter, not a claim of compatibility with older versions or every modpack.
+
+## Let the AI set it up
+
+Use your existing **remote or local** ModLens MCP connection and ask:
+
+> Set up ModLens runtime monitoring for this 26.3 mod project. Let me launch it
+> from IntelliJ, and keep the client visible but watch-only while you control it.
+
+The always-discoverable `runtime` MCP tool describes this workflow. The AI calls:
+
+```json
+{"action":"setup","projectDir":"F:/Git/my-mod","mcVersion":"26.3","mode":"observe","gradleTask":"runClient"}
+```
+
+With local stdio, that tool call executes directly. With remote MCP, it returns
+`executed:false` and a **local execution plan**. Codex writes the supplied JSON
+request to a local file and invokes the version-matched helper through its local
+terminal tools. A returned plan is not a completed setup or game action.
+
+For example, save the setup JSON above as `runtime-request.json`, then run on the
+Minecraft PC (use the package version returned by your remote MCP):
+
+```sh
+npx -y @creeperhost/modlens-mcp@<version> --runtime --request-file runtime-request.json
+```
+
+For this unpublished source build, use the built checkout instead:
+
+```sh
+node /path/to/modlens-mcp/dist/launcher.js --runtime --request-file runtime-request.json
+```
+
+The helper automatically starts an authenticated loopback companion. It stays
+running between commands, detects configured IntelliJ launches, and collects
+events while Codex is doing other work. It requires Node.js and the same Minecraft
+JDK as the direct MCP workflow; it does not bootstrap a source database or modify
+MCP configuration. There is no second local MCP connection, Cloudflare dependency,
+public runtime endpoint, or automatic upload of diagnostics to remote ModLens.
+Codex must have local terminal/file access on the Minecraft PC; a cloud-only shell
+does not provide that access.
+
+All JSON requests in this document work through the helper. Short commands are
+also available:
+
+```sh
+modlens-mcp --runtime help
+modlens-mcp --runtime sessions
+modlens-mcp --runtime status
+modlens-mcp --runtime stop
+```
+
+Use the same `npx ...` or `node .../dist/launcher.js` prefix if the command is not
+installed globally. The companion stores its private credentials and journal in
+`<MODLENS_CACHE_ROOT>/runtime` (by default `~/.modlens-cache/runtime`). Stop ends
+monitoring, leaving running game processes alive; held inputs expire on connection
+loss. Switch to interactive mode first if you want to continue playing manually.
+The next helper request starts it again. An existing local stdio bridge and the
+helper cannot own the same runtime cache simultaneously; stop the current owner
+before switching between these two arrangements.
+Stop and restart the companion when switching package versions so it runs the
+helper code and bundled agent from the selected installation.
+
+Successful local setup copies the bundled agent into the project and creates **ModLens Client** in
+IntelliJ's run configurations. Select that configuration and press Run. The AI can
+also call `runtime` with `action:"launch"` and the returned `projectId`; supply
+`javaHome` if the server's `JAVA_HOME` does not select a suitable JDK.
+
+For multi-project builds, select the actual client task, e.g. `:fabric:runClient`.
+The task must extend Gradle `JavaExec`. A generated init script adds the agent to
+that task only. Custom launch plugins which don't expose a JavaExec task get an
+actionable error. Setup also returns `vmOptions` for the actual game JVM in an
+existing Application run configuration. Add every entry, including
+`-XX:StackShadowPages=32`: the 26.3 client needs this setting independently of the
+agent. The generated Gradle/IntelliJ launch supplies it automatically, only to the
+selected client task. **Do not put these options on IntelliJ itself or the Gradle
+daemon.** Quote each whole VM option if it contains spaces. The singular `vmOption`
+field remains available for callers that only need the agent argument.
+
+Setup only creates `.modlens/runtime/` and `.run/ModLens Client.run.xml`. It does
+not edit existing run configurations or build files, and refuses to overwrite a
+non-ModLens run configuration. `.modlens/runtime/` contains a local `.gitignore`:
+its connection token and runtime files must stay private. Published npm releases
+include the compiled agent; end users do not need to compile it.
+
+## Modes
+
+| Mode | Display | Input |
+| --- | --- | --- |
+| `interactive` | Visible game window | Human controls; MCP input rejected |
+| `observe` | Visible game window | MCP controls; physical game input filtered |
+| `hidden` | Hidden game window | MCP controls; physical game input filtered |
+
+Switch a connected client with:
+
+```json
+{"action":"command","sessionId":"<id>","command":{"type":"mode","mode":"hidden"}}
+```
+
+Observe mode uses the actual game window as a watch-only display. OS window
+management, including closing it, remains available. Hidden mode still uses a
+graphics device and desktop/display environment; it is not a GPU-free server.
+Input interception covers the normal SDL paths. Mods using another native input
+path need a separate adapter. This is a development convenience, not an OS security
+boundary. Switching to interactive returns control; click the game to resume mouse
+capture normally.
+
+## AI workflow and tool examples
+
+1. `help` / `status`: discover setup, configured projects, and whether the JAR is packaged.
+2. `setup`: prepare a specific project (explicitly opts it in).
+3. `launch`, or let the developer use IntelliJ.
+4. `sessions`: discover client session IDs, PID, connection status and capabilities.
+5. `status` with a session ID: read metrics, mode, screen, world state and coordinates.
+6. `events` with `afterCursor` and `waitMs:30000`: wait for new events without flooding context.
+7. `command`: send input or request diagnostic artifacts; `artifact` reads the result.
+
+```json
+{"action":"command","sessionId":"<id>","command":{"type":"key","key":"W","down":true,"holdMs":500}}
+{"action":"command","sessionId":"<id>","command":{"type":"mouse_move","x":20,"y":-5,"relative":true}}
+{"action":"command","sessionId":"<id>","command":{"type":"mouse_button","button":1,"down":true,"holdMs":100}}
+{"action":"command","sessionId":"<id>","command":{"type":"text","text":"Hello"}}
+{"action":"command","sessionId":"<id>","command":{"type":"screenshot"}}
+{"action":"artifact","sessionId":"<id>","artifactName":"<returned artifact name>"}
+```
+
+Key names include A–Z, 0–9, SPACE, ENTER, ESCAPE, TAB, arrows, modifiers and F1–F12.
+Numeric strings outside single digits represent SDL scancodes. Mouse buttons are
+1=left, 2=middle, 3=right. Coordinates are **window pixels**, not scaled GUI units;
+relative movements are deltas. Text sends text-input events independently of keys.
+`scroll` accepts `x` and `y`. Inputs are delivered to the event loop; they do not
+guarantee a particular gameplay result. Observe state or take a screenshot afterward.
+
+Held keys/buttons expire within 10 seconds, and are released when the bridge has
+been unreachable for five seconds (as soon as the game event loop runs). Use
+`release_all` to cancel held inputs. Commands have deadlines and aren't replayed
+automatically after uncertain delivery. A timeout means execution is unknown;
+inspect state before retrying an action.
+
+Screenshots use 26.3's own renderer-independent screenshot API, after
+`state.observation.gameLoaded` becomes true. PNGs are returned as MCP image content
+by `artifact` over local stdio MCP. The CLI returns the local PNG path for Codex's
+image viewer instead of base64 in terminal text. `threads` writes a thread dump including detected deadlock IDs;
+`recording` writes the recent JFR recording. Files live under
+`.modlens/runtime/sessions/<sessionId>/`. Diagnostic artifacts are local and may
+contain application data; delete old session directories when finished.
+
+## Monitoring and failure semantics
+
+The agent samples heap/non-heap usage, thread counts and GC counters every second,
+keeps a bounded two-minute/16 MiB JFR recording, captures uncaught exceptions while
+chaining the previous handler, and hooks the game's fatal crash reporting path.
+It does not intercept every logged/caught exception or exceptions consumed by a
+custom per-thread handler. The optional Minecraft crash hook covers the normal
+client fatal-report path independently of the default uncaught handler.
+Memory-pressure alerts combine sustained collection activity with heap pressure.
+Collection time can include concurrent GC work: it is **not** a stop-the-world
+pause percentage or proof of a memory leak.
+
+For allocation churn in your own mod, request a report and read its returned
+artifact through MCP:
+
+```json
+{"action":"command","sessionId":"<id>","command":{"type":"allocations","packagePrefix":"com.example.mymod","windowSeconds":30,"limit":20}}
+{"action":"artifact","sessionId":"<id>","artifactName":"<returned artifact name>"}
+```
+
+The JSON report groups JFR allocation samples by allocated class and matching
+caller, with sample weights and example stacks. Filtering matches callers in the
+package, so allocations made inside Java/Minecraft libraries on behalf of the mod
+can appear too. Omit the filter to inspect all sampled allocation sites. These are
+statistical estimates of allocation pressure, not exact byte counts or retained
+object sizes. Empty or sparse samples are inconclusive; reproduce the workload
+and compare reports alongside heap/GC metrics. Reports use the bounded rolling JFR
+recording, which may contain less history than the requested 5–120 seconds.
+No heap dump or full-GC operation is requested. Retaining paths and GC roots are
+outside this first version. See the [JFR sample-weight definition](https://github.com/openjdk/jdk/blob/jdk-25-ga/src/hotspot/share/jfr/metadata/metadata.xml).
+
+The bridge keeps bounded event history with cursors, deduplicates agent replays,
+and persists a rolling journal. A new JVM gets a new session ID. Connection loss
+is reported separately from a crash; native failures/OOM may prevent in-process
+delivery. The generated Gradle run redirects JVM fatal-error logs into
+`.modlens/runtime/`. Commands and telemetry never use Minecraft's network protocol.
+
+An active AI task can monitor using bounded event waits. Capturing an event does
+not guarantee an idle Codex task wakes up; host scheduling is separate from MCP.
+
+## Scope and maintenance
+
+- Source-analysis use starts no runtime listener. An explicit local helper command
+  starts its loopback companion; only setup opts a project in, and only launch
+  starts a client process.
+- A previously configured local project reconnects when its ModLens server starts.
+- One local bridge owns a runtime cache at a time; a second connection reports the
+  existing owner instead of stealing active clients. Multiple game sessions are
+  supported through that bridge.
+- HTTP MCP returns explicit local execution plans. The local helper performs
+  runtime actions on the Minecraft PC using the same request schema and dispatcher
+  as local stdio MCP. HTTP handlers never execute user-supplied local paths.
+- The agent connects only to authenticated loopback HTTP; no browser control routes.
+- SDL events, keyboard state and mouse state are kept consistent. Input/window code
+  lives in `SdlAdapter`; optional game APIs live in `Minecraft263`.
+- Exact transformation descriptors live in `Transformer`. It uses Java 25's
+  standard Class-File API and an isolated bootstrap bridge, with no ASM/Gson or
+  native agent dependencies to collide with mod loaders.
+- Setup accepts `minecraftHooks:false` to isolate compatibility problems. SDL
+  controls and JVM diagnostics remain available; screenshots and structured game
+  state require the Minecraft adapter. A GLFW backend belongs to a future backport:
+  vanilla 26.3 uses SDL3.
+- Capability presence and validation are distinct. Tests cover selected environments;
+  Fabric/NeoForge launchers and rendering replacements still require their own runs.
+
+## Building and testing
+
+The initial validation ran on Windows with Java 25, LWJGL 3.4.3, Gradle 9.6 and
+vanilla Minecraft 26.3 using OpenGL. It includes a real hidden client screenshot
+and input delivery, native SDL controls/diagnostics, the Gradle launch path, and a
+fresh npm-package MCP installation. World gameplay and the full mod-loader/rendering
+matrix have not been validated yet.
+
+```sh
+npm ci
+npm run build
+# JAVA_HOME must point to JDK 25 or later:
+npm run build:agent
+npm test
+```
+
+The optional agent build is separate so source-analysis-only development and Docker
+builds retain their existing Java requirements. The npm release workflow builds and
+ships the agent. `npm run test:runtime:native` exercises an actual hidden SDL window;
+set `JAVA_HOME` and `MODLENS_SDL_CLASSPATH` to LWJGL 3.4.3 core/SDL Java and native
+JARs for your platform. It checks input delivery, polling consistency, hardware-like
+event suppression, key expiry, Unicode text, diagnostics and uncaught exceptions.
+
+`node scripts/test-runtime-minecraft.mjs` validates an isolated hidden vanilla 26.3
+demo client without reading accounts or worlds. Set `JAVA_HOME`,
+`MODLENS_TEST_MC_MANIFEST`, `MODLENS_TEST_MC_CLIENT`, `MODLENS_TEST_MC_ASSETS`,
+`MODLENS_TEST_MC_ASSET_INDEX` and `MODLENS_TEST_MAVEN_CACHE`. It uses supplied cached
+artifacts and downloads missing libraries with manifest checksum verification.
+Evidence is retained in the printed temporary directory. The test includes the
+required `-XX:StackShadowPages=32` setting and checks a Minecraft allocation report
+alongside screenshots and input. Use `--baseline` to compare startup without the
+agent while retaining the required client JVM options; this baseline can show a
+normal game window.
+
+`node scripts/test-runtime-remote.mjs` tests an isolated HTTP MCP server returning
+plans which local CLI processes execute against a real instrumented SDL JVM. It
+checks setup, session persistence, input, allocation reports, crash events, helper
+restart/reconnection, and shutdown without creating a local source database. Set the same JDK/SDL variables
+as the native test. Add `--helper` to the Minecraft or Gradle tests to exercise
+their complete workflows through the CLI companion too.
+
+`node scripts/test-runtime-gradle.mjs` tests the generated launch path in a
+disposable JavaExec project, including paths with spaces and exclusion of unrelated
+tasks. Set `JAVA_HOME` and `MODLENS_TEST_GRADLE_HOME` (Gradle 9.6). This tests the
+Gradle integration; it does not replace mod-loader-specific client tests.

package/TESTING.md

@@ -2,6 +2,14 @@
 
 Run the deterministic regressions with `npm test`. Run `npm run build` before the MCP and package checks below.
 
+For a package that includes live runtime support, also run `npm run build:agent`
+with JDK 25 before `npm run test:package`. The npm release workflow does this
+automatically. Runtime protocol tests are part of `npm test`; native SDL and real
+26.3 client checks are described in [RUNTIME.md](RUNTIME.md).
+The packaged-consumer test also exercises the persistent `--runtime` helper.
+`node scripts/test-runtime-remote.mjs` validates HTTP MCP guidance followed by local
+CLI execution against a real Java agent; Minecraft and Gradle tests accept `--helper`.
+
 `npm test` works directly after `npm ci`, before a build. Vitest generates the SQLite client before importing the tests. SQLite integration tests create a temporary template from the Prisma schema, use a fresh database for each test, and isolate their artifact cache. They do not depend on `dist/`, the packaged `template.db`, or earlier test results.
 
 ## Minecraft era matrix

package/dist/cli.js

@@ -212,9 +212,11 @@ DOCS
   docs semantic-search <query>       Semantic search (requires Ollama)  [--limit=10]
 
 PRIMERS (version migration guides)
-  primers seed                       Seed built-in porting primers
-  primers get <id>                   Get primer by ID
+  primers seed                       Seed and fetch built-in primers  [--fetch-content=false]
+  primers get <id>                   Read cached/fetched Markdown  [--refresh] [--fetch-content=false]
+                                     [--start-line=1] [--max-lines=400]
   primers by-version <from> <to>     Get primers for a version range  [--modloader=]
+                                     [--include-content] [--max-chars=60000] [--cursor=] [--fetch-content=false]
   primers search <query>             Keyword search  [--modloader=] [--limit=]
   primers list                       List all primers  [--modloader=] [--limit=]
   primers delete <id>                Delete a primer by ID
@@ -867,15 +869,33 @@ try {
         case "primers": {
             const sub = requireArg(positional[0], "primers action");
             switch (sub) {
-                case "seed":
-                    out(await seedDefaultPrimers());
+                case "seed": {
+                    const seeded = await seedDefaultPrimers(flags.fetchContent !== "false" && flags.fetchContent !== false);
+                    out(seeded);
+                    if (seeded.failed)
+                        process.exitCode = 1;
                     break;
+                }
                 case "get":
-                    out(await getPrimer(numArg(positional[1], "id")));
-                    break;
-                case "by-version":
-                    out(await getPrimersByVersionRange(requireArg(positional[1], "fromVersion"), requireArg(positional[2], "toVersion"), flags.modloader));
+                    out(await getPrimer(numArg(positional[1], "id"), {
+                        fetchContent: flags.fetchContent !== "false" && flags.fetchContent !== false,
+                        refresh: flags.refresh === true || flags.refresh === "true",
+                        startLine: flags.startLine,
+                        maxLines: flags.maxLines,
+                    }));
+                    break;
+                case "by-version": {
+                    const range = await getPrimersByVersionRange(requireArg(positional[1], "fromVersion"), requireArg(positional[2], "toVersion"), flags.modloader, {
+                        includeContent: flags.includeContent === true || flags.includeContent === "true",
+                        fetchContent: flags.fetchContent !== "false" && flags.fetchContent !== false,
+                        maxChars: flags.maxChars,
+                        cursor: flags.cursor,
+                    });
+                    out(range);
+                    if ("failed" in range && range.failed)
+                        process.exitCode = 1;
                     break;
+                }
                 case "search":
                     out(await searchPrimers(requireArg(positional[1], "query"), flags.modloader, undefined, undefined, flags.limit));
                     break;