@creeperhost/modlens-mcp 1.6.18 → 1.6.20

package/README.md

@@ -49,6 +49,80 @@ npm run start   # start the server
 
 ---
 
+## Gradle project environments
+
+ModLens can import the **actual compile classpath** of a Gradle project. The ModDevGradle adapter also exports the matching prepared Minecraft sources and hashes of the AT files used by its artifact task. This lets the AI see project-specific access changes, loader patches and mapped names.
+
+Imports are private, immutable snapshots, separate from the shared vanilla/mod caches and database. Re-export and import after changing ATs, dependencies or mappings. The returned `environmentId` selects the new snapshot; earlier IDs still describe their original inputs. This is compile-time context, not a simulation of runtime mixins/coremods.
+
+### Export from Gradle
+
+In a checkout, run your mod project's wrapper with the supplied init script:
+
+```bash
+./gradlew -I /path/to/modlens-mcp/scripts/gradle/modlens.init.gradle :modlensExport
+```
+
+For an installed package, locate its script first:
+
+```bash
+npx @creeperhost/modlens-mcp --gradle-init-script
+# Pass the printed path to your project's ./gradlew -I command.
+```
+
+On Windows, use `gradlew.bat -I "H:\Git\modlens-mcp\scripts\gradle\modlens.init.gradle" :modlensExport`.
+
+The task produces `build/modlens/main/environment.zip` and creates a persistent private key at `.gradle/modlens/project-key.txt` in the selected project. The key is not included in the bundle or printed. Keep it out of source control and share it only with clients that should access this project.
+
+Use `:subproject:modlensExport` for a module, and `-PmodlensSourceSet=client` to select a different source set. The task runs the classpath's prerequisite tasks, including Minecraft artifact preparation, without launching the game. Referenced project/source-set outputs may need compilation. It does not support Gradle's configuration cache; use `--no-configuration-cache` if necessary.
+
+Supported adapter: **ModDevGradle 2.x**, exercised with 2.0.141 / NeoForge 21.1.209 / Minecraft 1.21.1 and Gradle 8.14. Other Java projects can export their resolved compile classpath, including directory dependencies. Automatic source discovery for ForgeGradle/NeoGradle/Loom is not implemented; absent supplied sources, individual classes are decompiled from the exported binaries on demand. Do not interpret generic exports as proof that runtime-only transformations have been applied.
+
+Optional metadata overrides: `-PmodlensMinecraftVersion=...`, `-PmodlensMappings=...`. The exporter also reads the common `minecraft_version`, `neo_version` and `forge_version` properties. It exports artifact names/content hashes and selected version metadata, not the project's entire Gradle configuration, repository credentials or absolute dependency paths.
+
+### Import locally or remotely
+
+Local import and query examples:
+
+```bash
+npx @creeperhost/modlens-mcp --project import-local build/modlens/main/environment.zip --key-file=.gradle/modlens/project-key.txt
+npx @creeperhost/modlens-mcp --project list --key-file=.gradle/modlens/project-key.txt
+npx @creeperhost/modlens-mcp --project members --environment-id=<returned-id> --class-name=net.minecraft.world.level.Level --key-file=.gradle/modlens/project-key.txt
+```
+
+From a checkout, the equivalent is `node dist/cli.js project ...`.
+
+For a remote server, run the uploader **on the developer's machine**, where the bundle exists:
+
+```bash
+npx @creeperhost/modlens-mcp --project-upload https://modlens.example/mcp build/modlens/main/environment.zip .gradle/modlens/project-key.txt
+# Checkout equivalent:
+node /path/to/modlens-mcp/scripts/project-upload.mjs https://modlens.example/mcp build/modlens/main/environment.zip .gradle/modlens/project-key.txt
+```
+
+Set `MODLENS_AUTH_TOKEN` if the deployment's reverse proxy requires a bearer token. Remote uploads require HTTPS; loopback HTTP is supported for local testing. The uploader transfers 1 MiB chunks, verifies the full bundle hash, retries acknowledged chunks safely and prints the imported snapshot metadata. The remote server never runs Gradle or needs the developer's local paths. Host-local import is disabled when `MCP_PORT` is set.
+
+Configure the AI to use the MCP **`project` tool** with `projectKey` (the key file's contents) and `environmentId`. Use `project` source/member/search queries for this environment; the existing `mc_source` and `mod` tools continue to describe their shared inputs. Key possession grants access to that project's snapshots; use the deployment's normal authentication to control access to the service and its upload resources.
+
+| Action | Additional arguments | Result |
+| --- | --- | --- |
+| `list` | none | Snapshots belonging to this project key only |
+| `info` | `environmentId` | Versions, artifacts, counts and snapshot provenance |
+| `classes` | `environmentId`, optional `query`, `offset`, `limit` | Classes in compile classpath order of precedence |
+| `source` | `environmentId`, `className`, optional `startLine`, `maxLines` | Supplied Gradle source or an on-demand binary decompile |
+| `members` / `bytecode` | `environmentId`, `className` | Inspection of the project's prepared binary |
+| `search` | `environmentId`, `query`, optional `limit` | Literal, case-insensitive search of supplied sources and cached decompiles |
+| `import_local` | `bundlePath` | Import an absolute host-local ZIP path (stdio only) |
+| `upload_begin` | `size`, `sha256` | Upload ID and chunk size |
+| `upload_chunk` | `uploadId`, `offset`, `data` | Next offset; `data` is base64 |
+| `upload_finish` / `upload_abort` | `uploadId` | Commit a complete upload or remove upload state |
+
+Search reports its coverage: a missing match does not prove absence from binaries without sources. Duplicate classes follow the first compile classpath entry; sources from shadowed dependencies are excluded. Multi-release JARs use the compile Java release, with stale base sources excluded when a versioned class overrides them. Limits are 512 MiB per bundle, 1 GiB expanded content, 2 MiB per Java source, and four unfinished uploads per project. Abandoned uploads expire after 24 hours and are cleaned up when the next upload begins. Snapshot files live under `MODLENS_CACHE_ROOT/projects` and work with all database backends.
+
+Contributor validation: `npm run test:project:http` exercises the real uploader and HTTP transport. Set `JAVA_HOME` and `MODLENS_TEST_GRADLE_HOME`, then run `npm run test:project:gradle` for a Java dependency fixture, or `npm run test:project:gradle -- moddev` for a real AT before/after check. The Gradle tests use disposable projects and may download build dependencies; they never launch Minecraft.
+
+Minecraft compatibility validation: `npm run test:minecraft:eras` exercises the local MCP server across Beta 1.7.3 through 26.1.2, plus real legacy Forge, Fabric and NeoForge mods, using temporary databases and caches. See [TESTING.md](TESTING.md) for the version matrix, offline format coverage and upstream gaps.
+
 ## Prerequisites
 
 | Requirement | Notes |
@@ -63,7 +137,7 @@ npm run start   # start the server
 
 | Variable | Purpose |
 |----------|---------|
-| `CURSEFORGE_API_KEY` | CurseForge platform sync (`sync_curseforge` action) |
+| `CURSEFORGE_API_KEY` | Optional direct fingerprint lookup and authenticated CurseForge downloads; normal metadata/sync uses modpacks.ch |
 | `MODRINTH_TOKEN` | Modrinth API — increases rate limit for batch operations |
 | `JAVA_HOME` | Override Java discovery (falls back to PATH if not set) |
 
@@ -154,10 +228,24 @@ node dist/cli.js backfill-embeddings
 node dist/cli.js backfill-embeddings --type source --version 26.1.2
 ```
 
-After this, the `docs` and `primers` MCP tools will have a `semantic_search` action, and the `mc_source` tool will have `search_semantic` and `index_semantic`. Semantic search is **opt-in** — if `OLLAMA_URL` is not reachable, tools fall back to keyword search automatically.
+After this, the `docs` and `primers` MCP tools provide `semantic_search`, and `mc_source` provides `search_semantic` and `index_semantic`. Semantic search requires a reachable Ollama service and the configured embedding model. Keyword search remains available separately. SQLite uses the bundled `sqlite-vec` dependency; `db:vector` above is for PostgreSQL.
 
 > **Note:** The `npm run db:vector` script is safe to re-run. It creates the `pgvector` extension and `embedding` columns using `IF NOT EXISTS` guards.
 
+## Data sources and shared bundles
+
+ModLens uses [modpacks.ch](https://modpacks.ch/api/openapi.json) for supported mod and pack searches, provider records, release histories, hash lookups, parsed pack manifests and loader versions. Maven artifacts and metadata come from [CreeperHost Maven](https://maven.creeperhost.net/). Download URLs supplied by modpacks.ch may point to the original provider's CDN. An API failure or missing result does not silently switch to another metadata service.
+
+When a mod file has no loader label, loader-filtered searches, version listings and update checks automatically download and inspect its JAR. Existing modpacks.ch labels take precedence. Inspection supports Forge/FML, Fabric, Quilt and NeoForge, including multiple loader declarations in one JAR; unknown or mismatched loaders are excluded. Recovered labels report `loaderSource: "jar"`. The first lookup can download several candidate files; subsequent queries and ingestion reuse the artifact cache. `mod_info` defaults to the latest 20 matches and reports `versionLimit`; increase `limit` (CLI: `--limit`) for more history. Download, checksum and unreadable-JAR failures are reported as errors.
+
+Existing sources remain for capabilities these services do not cover: Mojang manifests, game files and official mappings; mcmeta's extracted data and history; RetroMCP legacy mappings; Adoptium runtime provisioning; the ModLens indexer release; metadata-provided source repositories; and the selected GitHub graph and embedding registries. Existing local Java installations are preferred.
+
+`mod graph_build` can build a class and inheritance graph directly from the mod JAR, without Graphify or an AI service. Set `backend=ast-only` to select this mode explicitly. `graph_enrich_next` and `graph_enrich_submit` add relationships supplied by the client. Automatic semantic extraction still needs a configured Graphify backend.
+
+`graph_export` and `embed_export` produce portable gzip bundles. Pass the resulting `bundlePath` to `graph_submit` or `embed_submit` to propose the bundle and its index entry together in a draft pull request. The defaults are [Mattabase/modlens-graphs](https://github.com/Mattabase/modlens-graphs) and [Mattabase/modlens-embeddings](https://github.com/Mattabase/modlens-embeddings). Submissions require `MODLENS_REGISTRY_TOKEN` or `GITHUB_TOKEN` with access to write the branch and open the pull request; a personal fork is used when the account cannot push to the registry. Submission does not merge the pull request.
+
+Custom registries use `MODLENS_GRAPH_REGISTRY_URL` or `MODLENS_EMBED_REGISTRY_URL`. For submission, the corresponding `MODLENS_GRAPH_REGISTRY_REPO` / `MODLENS_EMBED_REGISTRY_REPO`, `_BRANCH` and `_INDEX_PATH` settings override the destination inferred from a GitHub raw-content URL.
+
 ---
 
 ## MCP Configuration
@@ -456,10 +544,10 @@ Run without arguments (or `--help`) to print the full command list. Every MCP to
 | `modpacks manifest <packId> <verId>` | Pack manifest |
 | MCP `modpacks_ch action=resolve_pack` | Resolve FTB/CurseForge/Modrinth/Feed The Beast pack names, IDs, version IDs, or version names |
 | MCP `modpacks_ch action=list_versions` | List remote pack versions and optionally mark matches for a short `versionRef` like `7.1` |
-| MCP `modpacks_ch action=ingest_pack` | Download and ingest a resolved pack version from modpacks.ch, Modrinth, or the official Feed The Beast API |
+| MCP `modpacks_ch action=ingest_pack` | Resolve metadata through modpacks.ch, then download and ingest the selected pack version |
 | `modpacks list-versions` | Pack version list |
 | `modpacks list-files` | Pack file list |
-| `modpacks ftb-mod-info <modId>` | FTB mod info |
+| `modpacks mod-info <modId>` | Mod metadata from modpacks.ch (`ftb-mod-info` remains an alias) |
 | `modpacks find-mod` | Find a mod across packs |
 
 **Diagnostics**
@@ -568,8 +656,8 @@ All tool actions have been consolidated into **24 grouped tools** to stay within
 
 | action | Key params | Description |
 |--------|-----------|-------------|
-| `sync_modrinth` | dbId | SHA-512 lookup → store project ID + source URL |
-| `sync_curseforge` | dbId | Murmur2 fingerprint lookup (needs `CURSEFORGE_API_KEY`) |
+| `sync_modrinth` | dbId | Resolve a known project or JAR SHA-1 through modpacks.ch; store project ID and source URL |
+| `sync_curseforge` | dbId | Resolve a known project or JAR SHA-1 through modpacks.ch; no CurseForge API key required |
 | `check_updates` | dbId | Check both platforms for newer version |
 | `batch_sync` | syncModrinth, syncCurseforge, downloadSources, modIdFilter, limit | Bulk sync all unmatched mods |
 | `download_source` | dbId | Download GitHub/GitLab source ZIP |
@@ -630,13 +718,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 |
@@ -836,7 +934,7 @@ modpacks_ch  action=ingest_pack  namespace=modrinth  packRef=<slug-or-project-id
 modpacks_ch  action=ingest_pack  namespace=modrinth  packRef="https://modrinth.com/modpack/fabulously-optimized"  versionRef=6.4.0
 
 # Official Feed The Beast API packs use namespace=feedthebeast.
-# Use namespace=ftb for the modpacks.ch FTB namespace; use feedthebeast for api.feed-the-beast.com.
+# Both use modpacks.ch: namespace=ftb selects /modpack; feedthebeast selects /ftb.
 modpacks_ch  action=list_versions  namespace=feedthebeast  packRef="Architect's"  versionRef=1.1
 modpacks_ch  action=ingest_pack  namespace=feedthebeast  packRef="Architect's"  versionRef=1.1
 
@@ -942,16 +1040,16 @@ node dist/cli.js check-updates 2
 
 ### Services & APIs
 - **[CreeperHost](https://www.creeperhost.net)** — for the free [modpacks.ch](https://www.modpacks.ch) public API powering modpack search, sync, and mod downloads.
-- **[Feed The Beast](https://www.feed-the-beast.com)** — for the public Feed The Beast modpack API powering official FTB pack lookup and ingest.
+- **[Feed The Beast](https://www.feed-the-beast.com)** — for the official FTB pack catalog, accessed through modpacks.ch.
 - **[Modrinth](https://modrinth.com)** — for the free [Modrinth API](https://docs.modrinth.com) powering mod search, metadata lookup, and version sync.
-- **[CurseForge](https://www.curseforge.com)** — for the [CurseForge API](https://docs.curseforge.com) powering mod and modpack browsing and sync.
+- **[CurseForge](https://www.curseforge.com)** — for mod and modpack hosting; metadata and release history are accessed through modpacks.ch.
 - **[misode](https://github.com/misode)** — for [mcmeta](https://github.com/misode/mcmeta), the version-controlled Minecraft data repository that powers the `mc_data`, `mc_files`, and `mc_registry` tools.
 - **[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).
@@ -977,4 +1075,3 @@ node dist/cli.js check-updates 2
 ### Special thanks
 
 A heartfelt thank you to all the members of the **ForgeCraft Discord and Minecraft server** for being a genuinely great community, for your feedback, and for supporting my development endeavours over the years. This project wouldn't be what it is without you.
-

package/TESTING.md

@@ -0,0 +1,69 @@
+# Compatibility testing
+
+Run the deterministic regressions with `npm test`. Run `npm run build` before the MCP and package checks below.
+
+`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
+
+`npm run test:minecraft:eras` starts a local MCP server with a fresh temporary SQLite database, home and cache. It downloads public artifacts using the application's configured source policy. Every interaction with game/mod source goes through MCP. Results and the server log are retained in the printed temporary directory.
+
+The vanilla checks verify named class discovery, decompiled source, methods/fields, bytecode and inheritance:
+
+| Mapping generation | Minecraft versions |
+| --- | --- |
+| RetroMCP, separate client/server namespaces | Beta 1.7.3, 1.2.5 |
+| RetroMCP, joined mappings | 1.5.2 |
+| Legacy SRG, with MCP member names where available | 1.6.4, 1.7.10, 1.8.9, 1.12.2 |
+| MCPConfig TSRG | 1.13.2 |
+| Official Mojang mappings | 1.16.5, 1.18.2, 1.20.1, 1.20.6, 1.21.1 |
+| Unobfuscated game artifacts | 26.1.2 |
+
+The 1.5.2 checks also verify the explicit `MinecraftServer.tick` and `IntegratedServer.tickIntegrated` mappings. This catches differences between the joined mapping's declared names and TinyRemapper's inherited-name guesses.
+
+Real-mod checks cover metadata resolution, the compatibility action alias, download/ingestion, database identity, language discovery, indexing, members, bytecode and single-class decompilation:
+
+| Mod | Minecraft / loader |
+| --- | --- |
+| Waila | 1.6.4 Forge, 1.7.10 Forge |
+| JEI | 1.8.9 Forge, 1.12.2 Forge, 1.16.5 Forge, 1.20.1 Forge, 1.21.1 NeoForge |
+| Sodium | 1.16.5 Fabric |
+
+Select individual game versions or run only the mod checks:
+
+```sh
+npm run test:minecraft:eras -- b1.7.3 1.7.10 1.12.2
+npm run test:minecraft:eras -- --mods
+```
+
+Set `JAVA_HOME` for the Java runtime used by remapping. Public services must be reachable. Optional `MODLENS_TEST_TOOL_CACHE` and `MODLENS_TEST_ARTIFACT_CACHE` directories are read-only seeds: the harness copies their files into its temporary cache. Credentials, live database settings, MCP server settings and automatic graph/embedding settings are removed from the test server environment. The harness retains evidence and never starts Minecraft gameplay.
+
+## Offline format regressions
+
+The unit suite builds small disposable JARs and mapping archives. Assertions cover the behavior that changed between eras:
+
+- `mcmod.info` arrays, wrapper objects and bare objects from 1.2.5 through 1.12.2.
+- Java 6/7/8 Forge annotations, accepted Minecraft ranges, required versus optional dependencies, version bounds and duplicate declarations.
+- Legacy `FMLAT` files and folded JAR manifest headers.
+- Forge `mods.toml`, JAR implementation-version substitution, early NeoForge `mods.toml` and later `neoforge.mods.toml` dependency types.
+- Fabric declared mixin filenames, optional dependencies, array predicates and access wideners; Quilt metadata, dependencies and its `mixin` key.
+- SRG/TSRG archives, MCP CSV names, object descriptors, CRLF mappings and consistency between version listing and source access.
+- Pre-1.13 resources under `assets/`, later data packs under `data/`, and the 1.21 plural-to-singular directory changes.
+- Legacy `.lang` files, JSON translations, namespace filtering and resource deduplication.
+- Automatic loader inspection for unlabeled files, provider-label precedence, multiple loader declarations, pagination after filtering, artifact reuse, forced refresh, checksum failures and range-filtered update checks.
+
+## Package validation
+
+`npm run test:package` installs the packed npm artifact into an isolated consumer. It checks setup, the MCP handshake, SQLite bootstrap, database types, transactions and restart persistence. Run this after changes to public commands, packaging or database setup.
+
+## Current coverage and upstream gaps
+
+The 2026-09-13 housekeeping and loader-fallback passes verified the matrix above. These are selected compatibility boundaries, not an exhaustive test of every Minecraft release or mod.
+
+Clean-install validation on 2026-09-13 passed `npm ci` → `npm test` (523 tests across 28 files) → `npm run build` on Ubuntu 24.04 and Windows using Node 22.21.1. The SQLite suite also passed in shuffled order, and the schema-repair test passed on its own.
+
+The final mod matrix passed 116 MCP checks across all eight builds, including filtered search, mismatch rejection and database isolation. The installed npm-consumer checks also passed.
+
+Some modpacks.ch historical file records, including the tested Waila releases and JEI 1.8.9, include the Minecraft version but omit the loader target. The matrix now supplies the loader filter for every release. ModLens keeps the API's version order, uses supplied loader labels, and downloads and inspects unlabeled candidate JARs before accepting a match. Result limits apply after filtering, including across pages. This also recovers a newer unlabeled file when older labeled versions exist.
+
+The fallback is automatic for mod searches, details, downloads and provider update checks. Recovered labels carry `loaderSource: "jar"`; the artifact cache is shared with ingestion. `mod_info` returns up to 20 matches by default; its `limit` parameter allows a larger history. The MCP matrix also checks loader-filtered Waila search, rejects Waila for Fabric, and verifies that metadata inspection does not ingest candidates into the database. JARs with no recognised loader are excluded, and failed downloads or unreadable artifacts produce errors. API errors still surface, and no other metadata service supplies replacement records. Upstream labels can be populated later; they take precedence immediately when present.

package/dist/cli.js

@@ -23,13 +23,14 @@ import { getModGradleFiles, searchGradleFiles, compareGradleDeps } from "./tools
 import { generateReport } from "./tools/reports.js";
 import { findAssetConflicts, findVanillaOverrides, analyzeModSidedness, analyzePackSidedness, computeModComplexity, computePackChangelog, findDataConflicts } from "./tools/packtools.js";
 import { indexKubeJsScripts, searchKubeJsScripts } from "./tools/kubejs.js";
-import { searchPacksAction, featuredPacksAction, packInfoAction, packManifestAction, ftbModInfoAction, listPackVersionsAction, listPackFilesAction, findModInPacksAction, } from "./tools/modpacks-ch.js";
+import { searchPacksAction, featuredPacksAction, packInfoAction, packManifestAction, modInfoAction, listPackVersionsAction, listPackFilesAction, findModInPacksAction, } from "./tools/modpacks-ch.js";
 import { analyzeCrashLog, findMissingDeps } from "./tools/diagnostics.js";
 import { checkModCompat } from "./tools/compat-check.js";
 import { listModJarFiles, getModJarFile, getModLang, getModSounds, getModAtlas, getModManifest, listModConfigs, getModConfig, listModData, getModData, listModDataTags, getModDataTag, getModModel as getModModelData, diffModData, traceRecipeChain, } from "./tools/mod-data.js";
 import { mcPaths } from "./minecraft.js";
 import { findModById } from "./repositories/mod.js";
 import { CACHE_ROOT } from "./cache.js";
+import { projectAction } from "./tools/project.js";
 import { getDb, disconnect } from "./db.js";
 import { readdir, readFile } from "fs/promises";
 import { join, resolve } from "path";
@@ -211,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
@@ -291,6 +294,10 @@ MOD TAGS (cross-mod data-pack tags)
   mod-tags search <query>            Search tags  [--registry=] [--limit=]
 
 GRADLE
+  project import-local <bundle.zip> --key-file=<file>  Import a private Gradle environment
+  project list --key-file=<file>                      List this project's snapshots
+  project info|classes|source|search|members|bytecode --key-file=<file> --environment-id=<id>
+      [--class-name=<name>] [--query=<text>] [--limit=20] [--offset=0] [--start-line=1] [--max-lines=200]
   gradle get-files <modId>           Extract Gradle build files
   gradle search <query>              Search Gradle files across mods  [--mod-id-filter=] [--limit=]
   gradle compare-deps                Compare dependency versions across mods  [--group-filter=] [--mod-id-filter=]
@@ -327,7 +334,7 @@ MODPACKS.CH
   modpacks manifest <packId> <verId> Pack manifest  [--namespace=]
   modpacks list-versions             Pack version list  [--namespace=] [--pack-id=]
   modpacks list-files                Pack file list  [--namespace=] [--pack-id=] [--version-id=] [--file-type=]
-  modpacks ftb-mod-info <modId>      FTB mod info  [--mc-version=] [--loader=]
+  modpacks mod-info <modId>          Mod metadata  [--mc-version=] [--loader=] [--limit=20]
   modpacks find-mod                  Find a mod across packs  [--mod-db-id=] [--cf-project=]
 
 DIAGNOSTICS
@@ -862,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;
@@ -1144,6 +1169,16 @@ try {
             break;
         }
         // ── Gradle ────────────────────────────────────────────────────────────
+        case "project": {
+            const action = requireArg(positional[0], "project action").replace(/-/g, "_");
+            const keyFile = requireArg(typeof flags.keyFile === "string" ? flags.keyFile : undefined, "--key-file=/path/to/project-key.txt");
+            const projectKey = (await readFile(resolve(keyFile), "utf8")).trim();
+            const { keyFile: ignored, ...options } = flags;
+            out(await projectAction({ ...options, action, projectKey,
+                ...(action === "import_local" ? { bundlePath: resolve(requireArg(positional[1], "bundle.zip")) } : {}),
+            }));
+            break;
+        }
         case "gradle": {
             const sub = requireArg(positional[0], "gradle action");
             switch (sub) {
@@ -1253,14 +1288,15 @@ try {
                 case "list-files":
                     out(await listPackFilesAction({ namespace: flags.namespace, packId: flags.packId, versionId: flags.versionId, fileType: flags.fileType }));
                     break;
-                case "ftb-mod-info":
-                    out(await ftbModInfoAction(modIdArg(positional[1], "modId"), { mcVersion: flags.mcVersion, loader: flags.loader }));
+                case "mod-info":
+                case "ftb-mod-info": // Compatibility with older CLI clients.
+                    out(await modInfoAction(modIdArg(positional[1], "modId"), { mcVersion: flags.mcVersion, loader: flags.loader, limit: flags.limit }));
                     break;
                 case "find-mod":
                     out(await findModInPacksAction({ modDbId: flags.modDbId, cfProject: flags.cfProject }));
                     break;
                 default:
-                    die(`Unknown modpacks action: ${sub}. Use: search|featured|info|manifest|list-versions|list-files|ftb-mod-info|find-mod`);
+                    die(`Unknown modpacks action: ${sub}. Use: search|featured|info|manifest|list-versions|list-files|mod-info|find-mod`);
             }
             break;
         }