@adhisang/minecraft-modding-mcp 7.0.0 → 7.1.0

package/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project aims to follow [Semantic Versioning](https://semver.org/spec/v2
 
 ## [Unreleased]
 
+## [7.1.0] - 2026-09-19
+
+### Added
+
+- `batch-class-source` and `batch-class-members` accept `target: { "kind": "artifact", "artifactId": "..." }`, the same target `get-class-source` and `get-class-members` accept, so a batch can reuse an artifact that an earlier call already resolved instead of resolving it again from its jar, version, or coordinate. This target was previously rejected with `ERR_INVALID_INPUT`. With it, `summary.sharedArtifactProvenance` is omitted, and an unknown `artifactId` fails each entry with `ERR_SOURCE_NOT_FOUND` rather than failing the whole batch.
+- `compare-minecraft` with `task="migration-overview"` reports which libraries shipped with Minecraft itself were added or removed between the two versions, such as LWJGL's GLFW binding being replaced by SDL, which class and registry diffs do not show. At `detail: "standard"` or `"full"`, the new `migration.libraries` block lists added and removed libraries as `group:artifact:version` and counts libraries whose version changed; `summary.counts.librariesAdded` and `librariesRemoved` carry the same counts at every detail level. A version bump or a per-platform native jar of a library already present is not reported as an addition or removal. When the version details cannot be fetched, or not within 5 seconds, the block is left out with a warning and the rest of the result is unchanged.
+- `provenance.unobfuscatedRuntime: true` marks an artifact whose runtime ships Mojang names (Minecraft 26.1+): version targets, Minecraft runtime coordinates, and jar targets proven to be a 26.1+ runtime jar. `resolve-artifact`, `get-class-source`, `get-class-members`, and the batch tools' `sharedArtifactProvenance` carry it; `provenance` itself is returned only with `include: ["provenance"]` or a fuller `detail` level. `mappingApplied` still reports the mapping you asked for, so `"obfuscated"` on such an artifact means the names as shipped, which are already Mojang names.
+
+### Changed
+
+- `validate-project` with `task="project-summary"` infers an omitted `version` from the project's `gradle.properties` (`minecraft_version`, `mc_version`, or `minecraftVersion`) and names the inferred version in `warnings`; it previously returned `status: "blocked"`. To keep the previous behavior, pass `preferProjectVersion: false`: a call without `version` then returns `blocked`, and the retry suggestions of an invalid-input error keep that explicit `false`. When files are found but no version can be inferred, the blocked reply asks for an explicit `version` instead of suggesting the same call again.
+
+### Performance
+
+- The first tool call after the server starts no longer stalls on a full consistency check of the local cache database. The check on open now uses SQLite's `quick_check` instead of `integrity_check`: on a 3.6 GB cache it takes about 2 s instead of about 19 s. A damaged cache file is still detected at startup, backed up and rebuilt. Rarer damage that the lighter check misses can surface later during a tool call; a call that hits it directly now fails with `ERR_DB_FAILURE` and restart guidance instead of `ERR_INTERNAL`, and the next start runs the full `integrity_check`. If the server cannot schedule that check, the error explains how to reset the cache by hand. A call where the damage surfaces inside another step may still report that step's own error.
+
+### Fixed
+
+- `validate-project` with `task="project-summary"`: a run that finds no Mixin configs, access wideners, or access transformers now reports `Nothing to validate: …`, naming only the file kinds it searched, with a warning that nothing was validated, instead of "Validated 0 mixin config(s), 0 access widener(s), and 0 access transformer(s)." `status` stays `"ok"`.
+- Minecraft 26.x snapshot, pre-release and release-candidate ids such as `26.3-snapshot-6`, `26.2-pre-6`, `26.2-rc-2` and `26.1.2-rc-1` are recognized as unobfuscated. They were treated as obfuscated legacy versions, so `mapping: "mojang"` was refused on them, `intermediary` and `yarn` did not fall back to `obfuscated`, and symbol checks did not use the runtime jar. Previously only weekly ids such as `26w14a` and unhyphenated forms such as `26.1-rc1`, which Mojang does not publish, were recognized.
+- `mapping: "mojang"` is accepted on a `target.kind: "jar"` that points at a Minecraft 26.1+ runtime jar, such as a jar from the Loom cache; it was refused with `ERR_MAPPING_NOT_APPLIED` and a hint to switch to `obfuscated`. A jar counts as a 26.1+ runtime jar when it has a top-level `version.json` with a 26.1+ `id`, contains `net/minecraft/SharedConstants.class`, and has no `.java` sources. Such a jar reports that `id` as its version and falls back from `intermediary` or `yarn` to `obfuscated` like a version target. A jar indexed by an earlier release has its version recorded on its next resolve, after which calls by `artifactId` accept `mojang` as well.
+- On Minecraft 26.1+ artifacts, class-not-found errors from `get-class-source` and `get-class-members`, and `find-class` misses, lead with the nearest class-name suggestion instead of telling you to retry with `mapping="mojang"`. When `mapping: "mojang"` is refused on a jar that is not a proven runtime jar, the error explains that `mapping: "obfuscated"` reads the names as shipped, and in a 26.1+ project it no longer suggests repeating the refused request. Hints for 1.x versions are unchanged.
+- `resolve-workspace-symbol` and `analyze-symbol` with `task="workspace"` resolve symbols in a Minecraft 26.1+ Loom project that declares no `mappings` line by checking the name against the runtime jar; they returned `mapping_unavailable` (`partial` in `analyze-symbol`). A class that is not in the Minecraft jar returns `not_found`, and a lookup that could not be checked returns `mapping_unavailable` with the reason. A path without a Gradle build script behaves as before.
+- On Minecraft 26.1+, `compare-minecraft` with `task="class-diff"` (and `diff-class-signatures`) and `trace-symbol-lifecycle` with `mapping: "mojang"` no longer mark every member as unmapped with "Could not remap" or "Could not map" warnings.
+- `check-symbol-exists` on Minecraft 26.1+ finds constructors: a method query named `<init>` with an existing descriptor resolves instead of returning `not_found`.
+
+### Documentation
+
+- The tool reference documents a known issue: on Minecraft 26.1+, responses label the runtime's Mojang names `obfuscated`, for example `mappingApplied: "obfuscated"`, whenever a request omits `mapping` or asks for `obfuscated`. The label stays until a future major release corrects it. Until then, `provenance.unobfuscatedRuntime: true` marks an artifact whose names are Mojang names, and `mapping: "mojang"` returns the same names labelled `mojang`.
+
 ## [7.0.0] - 2026-09-13
 
 ### Fixed

package/README.md

@@ -170,7 +170,8 @@ These notes cover high-frequency decisions during onboarding. For the full pitfa
 - `trace-symbol-lifecycle` expects `Class.method` in `symbol`. Keep exact overload matching in the separate `descriptor` field.
 - For unobfuscated releases such as `26.1+`, `check-symbol-exists` and `analyze-symbol task="exists"` validate `mojang` lookups against runtime bytecode when no mapping graph exists, and return `mapping_unavailable` when the runtime JAR itself is unreachable.
 - `analyze-mod` and `validate-project` require structured `subject` objects and canonical `include` groups; stale string-subject or domain-include payloads return `ERR_INVALID_INPUT` with a retryable `suggestedCall`.
-- `validate-project task="project-summary"` propagates `preferProjectVersion=true` across discovered Mixin, Access Widener, and Access Transformer checks. If no version can be resolved from the request or `gradle.properties`, the summary returns recovery guidance instead of guessing.
+- `validate-project task="project-summary"` infers an omitted `version` from `gradle.properties` and names the inferred version in `warnings`; pass `preferProjectVersion: false` to turn inference off, in which case a call without `version` returns `status: "blocked"`. The resolved version is passed to every discovered Mixin, Access Widener, and Access Transformer check. If files were discovered but no version can be inferred, the summary returns `status: "blocked"` with a retry that asks for an explicit `version` instead of guessing.
+- When `validate-project task="project-summary"` discovers no files, `status` stays `"ok"` but the headline reads `Nothing to validate: ...` and `warnings` states that nothing was validated, so an `"ok"` status alone does not mean any file passed.
 - `validate-mixin` and `validate-project` keep `mapping-health` lightweight for `obfuscated` and `mojang` validation, avoiding full Tiny mapping graph loads unless `intermediary` or `yarn` namespaces are requested.
 - `validate-project task="project-summary"` uses a lightweight artifact probe for `tasks["minecraft.artifact.resolved"]`; it does not decompile Minecraft or rebuild the source index just to report per-probe status. It does read the runtime jar's bytes to derive the `artifactId` it reports, and repeat probes of the same jar in one process reuse that digest. Set `VALIDATE_PROJECT_TASKS_OFF=1` to omit the additive `tasks` field.
 - `validate-project` has a supervisor-owned end-to-end deadline of 120 seconds, including queue time. Set `MCP_VALIDATE_PROJECT_TIMEOUT_MS` to an ASCII-decimal value from `10000` through `600000` to override it. A timeout returns `ERR_TOOL_TIMEOUT`; a running timeout restarts the isolated worker before queued calls resume, while a queue timeout leaves the current worker untouched.
@@ -301,7 +302,7 @@ Tools for browsing Minecraft versions, resolving source artifacts, and reading o
 
 `find-class` accepts either an `artifactId` or the shared object `target` shape. For a workspace-relative dependency, pass `target: { kind: "dependency", group, name, versionFromProject: true }` with top-level `projectPath`. Fabric-style umbrella JARs are searched through their nested `.class` inventories; a top-level class match can then be passed to `get-class-source` or `get-class-members`, which resolve the containing nested JAR. Dotted inner-class matches are also readable through `get-class-source`. An empty result still means that the requested class name is absent from the resolved dependency version.
 
-For unobfuscated releases such as `26.1+`, `mapping="mojang"` uses the runtime/decompile path directly and skips Loom source-jar discovery, while `intermediary` and `yarn` fall back to `obfuscated` with a warning.
+For unobfuscated releases such as `26.1+`, `obfuscated` names the runtime jar's names as shipped, which are already Mojang names: both `obfuscated` and `mojang` are accepted, `mappingApplied` reports the label you asked for, and `provenance.unobfuscatedRuntime: true` marks the artifact. `mapping="mojang"` uses the runtime/decompile path directly and skips Loom source-jar discovery, while `intermediary` and `yarn` fall back to `obfuscated` with a warning. This applies to version targets, Minecraft runtime coordinates, and JAR targets whose own contents (a top-level `version.json` with a 26.1+ `id`, `net/minecraft/SharedConstants.class`, and no `.java` sources) prove a 26.1+ Minecraft runtime jar; see [docs/tool-reference.md → Lookup Rules](docs/tool-reference.md#lookup-rules). Labelling these Mojang names `obfuscated` is a known issue, kept unchanged for compatibility until a future major release corrects it; see [docs/tool-reference.md → Known issue: obfuscated label on unobfuscated runtimes](docs/tool-reference.md#known-issue-obfuscated-label-on-unobfuscated-runtimes).
 
 ### Version Comparison & Symbol Tracking
 

package/dist/entry-tools/analyze-mod-service.d.ts

@@ -40,9 +40,9 @@ export declare const analyzeModShape: {
         apply: "apply";
     }>>;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;
@@ -88,9 +88,9 @@ export declare const analyzeModSchema: z.ZodObject<{
         apply: "apply";
     }>>;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;

package/dist/entry-tools/analyze-symbol-service.d.ts

@@ -62,9 +62,9 @@ export declare const analyzeSymbolShape: {
     maxRows: z.ZodOptional<z.ZodNumber>;
     maxCandidates: z.ZodDefault<z.ZodNumber>;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;
@@ -132,9 +132,9 @@ export declare const analyzeSymbolSchema: z.ZodObject<{
     maxRows: z.ZodOptional<z.ZodNumber>;
     maxCandidates: z.ZodDefault<z.ZodNumber>;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;

package/dist/entry-tools/batch-class-members-service.d.ts

@@ -1,6 +1,7 @@
 import { type ResponseDetailLevel } from "../response-utils.js";
 import type { GetClassMembersInput, GetClassMembersOutput, ResolveArtifactInput, ResolveArtifactOutput } from "../source-service.js";
-import type { ArtifactScope, MappingSourcePriority, ResolveArtifactTargetInput, SourceMapping } from "../types.js";
+import type { ArtifactScope, MappingSourcePriority, SourceMapping } from "../types.js";
+import type { SourceLookupTargetInput } from "../tool-schemas.js";
 import type { MemberProjection } from "../source/class-source/members-builder.js";
 import { type BatchOutput } from "./batch-runner.js";
 export type BatchClassMembersDeps = {
@@ -16,7 +17,7 @@ export type BatchClassMembersEntry = {
     maxMembers?: number;
 };
 export type BatchClassMembersInput = {
-    target: ResolveArtifactTargetInput;
+    target: SourceLookupTargetInput;
     mapping?: SourceMapping;
     sourcePriority?: MappingSourcePriority;
     allowDecompile?: boolean;

package/dist/entry-tools/batch-class-members-service.js

@@ -16,6 +16,16 @@ export class BatchClassMembersService {
             concurrency,
             failFast,
             resolveSharedArtifact: async () => {
+                // target.kind === "artifact" reuses an already-resolved artifactId,
+                // short-circuiting resolution exactly as get-class-members's own
+                // `kind:"artifact"` target does (src/index.ts normalizeSourceLookupTarget).
+                // No provenance is invented for a reused artifact: an unknown id is left
+                // to surface per-entry (the same SOURCE_NOT_FOUND getClassMembers raises
+                // for an unknown artifactId), since resolveSharedArtifact has no way to
+                // validate existence without calling deps.resolveArtifact.
+                if (input.target.kind === "artifact") {
+                    return { artifactId: input.target.artifactId };
+                }
                 const resolved = await this.deps.resolveArtifact({
                     target: input.target,
                     mapping: input.mapping,
@@ -49,12 +59,16 @@ export class BatchClassMembersService {
                 const raw = (await this.deps.getClassMembers({
                     artifactId: sharedArtifact.artifactId,
                     // This artifactId is OURS, not the caller's: the shared target was
-                    // resolved above and every entry is dispatched by the result. Without
-                    // saying so, get-class-members reads the bare presence of an
-                    // artifactId as the caller having named the artifact, and reports a
-                    // missing binary jar as their mistake - once per entry - though
-                    // `target` here cannot name an artifact at all. Only a jar the caller
-                    // named themselves is genuinely their choice.
+                    // resolved (or, for target.kind==="artifact", reused) above and every
+                    // entry is dispatched by the result. Without saying so, get-class-members
+                    // reads the bare presence of an artifactId as the caller having named
+                    // the artifact, and reports a missing binary jar as their mistake - once
+                    // per entry. A `kind:"artifact"` target is a resolved-id handle, not a
+                    // caller choice either (mirrors resolveClassArtifactReference's
+                    // artifactSelectedByFor in inspect-minecraft/handlers/class-members.ts):
+                    // it says nothing about whether the artifact carries a binary jar and
+                    // cannot be re-resolved into one that does. Only a jar the caller named
+                    // themselves is genuinely their choice.
                     artifactSelectedBy: input.target.kind === "jar" ? "caller" : "tool",
                     className: entry.className,
                     access: entry.access,

package/dist/entry-tools/batch-class-source-service.d.ts

@@ -1,6 +1,7 @@
 import { type ResponseDetailLevel } from "../response-utils.js";
 import type { GetClassSourceInput, GetClassSourceOutput, ResolveArtifactInput, ResolveArtifactOutput } from "../source-service.js";
-import type { ArtifactScope, MappingSourcePriority, ResolveArtifactTargetInput, SourceMapping } from "../types.js";
+import type { ArtifactScope, MappingSourcePriority, SourceMapping } from "../types.js";
+import type { SourceLookupTargetInput } from "../tool-schemas.js";
 import { type BatchOutput } from "./batch-runner.js";
 type SourceMode = "metadata" | "snippet" | "full";
 export type BatchClassSourceEntry = {
@@ -13,7 +14,7 @@ export type BatchClassSourceEntry = {
     outputFile?: string;
 };
 export type BatchClassSourceInput = {
-    target: ResolveArtifactTargetInput;
+    target: SourceLookupTargetInput;
     mapping?: SourceMapping;
     sourcePriority?: MappingSourcePriority;
     allowDecompile?: boolean;

package/dist/entry-tools/batch-class-source-service.js

@@ -16,6 +16,16 @@ export class BatchClassSourceService {
             concurrency,
             failFast,
             resolveSharedArtifact: async () => {
+                // target.kind === "artifact" reuses an already-resolved artifactId,
+                // short-circuiting resolution exactly as get-class-source's own
+                // `kind:"artifact"` target does (src/index.ts normalizeSourceLookupTarget).
+                // No provenance is invented for a reused artifact: an unknown id is left
+                // to surface per-entry (the same SOURCE_NOT_FOUND getClassSource raises
+                // for an unknown artifactId), since resolveSharedArtifact has no way to
+                // validate existence without calling deps.resolveArtifact.
+                if (input.target.kind === "artifact") {
+                    return { artifactId: input.target.artifactId };
+                }
                 const resolved = await this.deps.resolveArtifact({
                     target: input.target,
                     mapping: input.mapping,

package/dist/entry-tools/compare-minecraft-service.d.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import type { DiffClassSignaturesOutput } from "../source-service.js";
-import type { CompareVersionsOutput } from "../version-diff-service.js";
+import { type CompareVersionsOutput } from "../version-diff-service.js";
 import type { GetRegistryDataOutput } from "../registry-service.js";
 export declare const compareMinecraftShape: {
     task: z.ZodOptional<z.ZodEnum<{
@@ -38,9 +38,9 @@ export declare const compareMinecraftShape: {
         registry: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>], "kind">;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;
@@ -86,9 +86,9 @@ export declare const compareMinecraftSchema: z.ZodObject<{
         registry: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>], "kind">;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;
@@ -122,10 +122,33 @@ type CompareMinecraftDeps = {
         includeData?: boolean;
         maxEntriesPerRegistry?: number;
     }) => Promise<GetRegistryDataOutput>;
+    /**
+     * Raw `libraries[].name` coordinates for one version, used only by
+     * migration-overview to surface library swaps (e.g. LWJGL GLFW replaced by
+     * SDL) that a class/registry diff cannot see. Optional so existing callers
+     * that do not wire it keep working: migration-overview simply omits the
+     * libraries block when this is absent.
+     */
+    getVersionLibraries?: (input: {
+        version: string;
+    }) => Promise<string[]>;
+};
+export type CompareMinecraftOptions = {
+    /**
+     * Deadline in milliseconds for fetching both sides' library lists during
+     * migration-overview, so a restart with cached jars but no network access
+     * fails fast instead of waiting the full underlying fetch timeout. On
+     * expiry the libraries block is omitted and a warning is added; the
+     * in-flight fetch is left to continue in the background (it may still
+     * warm the version-detail cache). Test-only injection point — never read
+     * from an environment variable.
+     */
+    libraryDiffDeadlineMs?: number;
 };
 export declare class CompareMinecraftService {
     private readonly deps;
-    constructor(deps: CompareMinecraftDeps);
+    private readonly libraryDiffDeadlineMs;
+    constructor(deps: CompareMinecraftDeps, options?: CompareMinecraftOptions);
     execute(input: CompareMinecraftInput): Promise<Record<string, unknown> & {
         warnings?: string[];
     }>;

package/dist/entry-tools/compare-minecraft-service.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { diffLibraries } from "../version-diff-service.js";
 import { createError, ERROR_CODES } from "../errors.js";
 import { buildIncludeSchema, detailSchema, positiveIntSchema } from "./entry-tool-schema.js";
 import { buildEntryToolMeta, buildEntryToolResult, createNextAction, createSummarySubject, createTruncationMeta } from "./response-contract.js";
@@ -42,10 +43,37 @@ export const compareMinecraftSchema = z.object(compareMinecraftShape);
 function compareStatusFromCounts(changedCount) {
     return changedCount > 0 ? "changed" : "unchanged";
 }
+/** Default bound on migration-overview's library enrichment (see `libraryDiffDeadlineMs`). */
+const DEFAULT_LIBRARY_DIFF_DEADLINE_MS = 5000;
+class LibraryDiffTimeoutError extends Error {
+}
+/**
+ * Races `promise` against a `ms` timer. The timer is always cleared (on
+ * either settlement) and unref'd so it can never keep the process alive.
+ */
+function withDeadline(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new LibraryDiffTimeoutError(`timed out after ${ms}ms`));
+        }, ms);
+        if (typeof timer.unref === "function") {
+            timer.unref();
+        }
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
 export class CompareMinecraftService {
     deps;
-    constructor(deps) {
+    libraryDiffDeadlineMs;
+    constructor(deps, options) {
         this.deps = deps;
+        this.libraryDiffDeadlineMs = options?.libraryDiffDeadlineMs ?? DEFAULT_LIBRARY_DIFF_DEADLINE_MS;
     }
     async execute(input) {
         const task = input.task && input.task !== "auto"
@@ -362,6 +390,32 @@ export class CompareMinecraftService {
                 const registrySignals = compare.registry?.summary.registriesChanged ?? 0;
                 const status = compareStatusFromCounts(classSignals + registrySignals);
                 const representativeClassName = compare.classes?.added[0] ?? compare.classes?.removed[0];
+                // Library changes (e.g. LWJGL GLFW replaced by SDL) never show up in the
+                // class/registry diff above, so fetch and diff them separately. This must
+                // never fail the whole migration-overview: a missing dependency wiring, a
+                // fetch failure, or a deadline expiry (e.g. offline after a restart, with
+                // only cached jars) just omits the block and adds a warning. On a
+                // timeout, the in-flight fetch is left running — it may still warm the
+                // version-detail cache for a later call — we simply stop waiting on it.
+                let librariesResult;
+                const libraryWarnings = [];
+                if (this.deps.getVersionLibraries) {
+                    try {
+                        const [fromLibraries, toLibraries] = await withDeadline(Promise.all([
+                            this.deps.getVersionLibraries({ version: subject.fromVersion }),
+                            this.deps.getVersionLibraries({ version: subject.toVersion })
+                        ]), this.libraryDiffDeadlineMs);
+                        librariesResult = diffLibraries(fromLibraries, toLibraries);
+                    }
+                    catch (error) {
+                        if (error instanceof LibraryDiffTimeoutError) {
+                            libraryWarnings.push(`Library comparison between ${subject.fromVersion} and ${subject.toVersion} timed out after ${this.libraryDiffDeadlineMs}ms.`);
+                        }
+                        else {
+                            libraryWarnings.push(`Could not compare libraries between ${subject.fromVersion} and ${subject.toVersion}: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                    }
+                }
                 const nextActions = representativeClassName
                     ? [
                         createNextAction("compare-minecraft", {
@@ -399,7 +453,13 @@ export class CompareMinecraftService {
                             }),
                             counts: {
                                 classSignals,
-                                registrySignals
+                                registrySignals,
+                                ...(librariesResult
+                                    ? {
+                                        librariesAdded: librariesResult.addedCount,
+                                        librariesRemoved: librariesResult.removedCount
+                                    }
+                                    : {})
                             },
                             nextActions
                         },
@@ -413,11 +473,12 @@ export class CompareMinecraftService {
                                         : registrySignals > 0
                                             ? "registry"
                                             : "minimal",
-                                nextActions
+                                nextActions,
+                                ...(librariesResult ? { libraries: librariesResult } : {})
                             }
                         }
                     }),
-                    warnings: compare.warnings
+                    warnings: [...compare.warnings, ...libraryWarnings]
                 };
             }
             default:

package/dist/entry-tools/entry-tool-schema.d.ts

@@ -1,8 +1,8 @@
 import { z } from "zod";
 export declare const detailSchema: z.ZodEnum<{
+    full: "full";
     summary: "summary";
     standard: "standard";
-    full: "full";
 }>;
 export declare const includeGroupSchema: z.ZodEnum<{
     workspace: "workspace";
@@ -17,6 +17,7 @@ export declare const includeGroupSchema: z.ZodEnum<{
     samples: "samples";
     timings: "timings";
     matrix: "matrix";
+    artifact: "artifact";
     provenance: "provenance";
     descriptors: "descriptors";
     diff: "diff";
@@ -27,7 +28,6 @@ export declare const includeGroupSchema: z.ZodEnum<{
     paths: "paths";
     owners: "owners";
     cacheEntries: "cacheEntries";
-    artifact: "artifact";
     classes: "classes";
 }>;
 export declare const executionModeSchema: z.ZodEnum<{

package/dist/entry-tools/inspect-minecraft-service.d.ts

@@ -251,9 +251,9 @@ export declare const inspectMinecraftShape: {
     }, z.core.$strip>], "kind">>;
     includeSnapshots: z.ZodDefault<z.ZodBoolean>;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;
@@ -512,9 +512,9 @@ export declare const inspectMinecraftSchema: z.ZodObject<{
     }, z.core.$strip>], "kind">>;
     includeSnapshots: z.ZodDefault<z.ZodBoolean>;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;

package/dist/entry-tools/manage-cache-service.d.ts

@@ -40,9 +40,9 @@ export declare const manageCacheShape: {
         projectPath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;
@@ -94,9 +94,9 @@ export declare const manageCacheSchema: z.ZodObject<{
         projectPath: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     detail: z.ZodOptional<z.ZodEnum<{
+        full: "full";
         summary: "summary";
         standard: "standard";
-        full: "full";
     }>>;
     include: z.ZodOptional<z.ZodArray<z.ZodEnum<{
         [x: string]: string;

package/dist/entry-tools/validate-project/cases/project-summary.js

@@ -15,6 +15,40 @@ async function safeEmit(emitter, stage, payload) {
         // swallow telemetry failure
     }
 }
+const DISCOVER_KIND_LABELS = [
+    ["mixins", "mixin configs"],
+    ["access-wideners", "access wideners"],
+    ["access-transformers", "access transformers"]
+];
+function joinWithOr(items) {
+    if (items.length <= 2) {
+        return items.join(" or ");
+    }
+    return `${items.slice(0, -1).join(", ")}, or ${items[items.length - 1]}`;
+}
+// A run that discovered no files keeps status "ok" (nothing failed), so the
+// headline and a warning must say that nothing was checked; otherwise the
+// result reads as a pass. Only the kinds subject.discover searched are named.
+function describeNothingToValidate(discover, projectPath) {
+    const searched = DISCOVER_KIND_LABELS
+        .filter(([kind]) => discover.includes(kind))
+        .map(([, label]) => label);
+    const notOk = "so status \"ok\" does not mean any file passed validation.";
+    const accessTransformerHint = discover.includes("access-transformers")
+        ? ""
+        : " Access Transformer files are searched only when subject.discover includes \"access-transformers\".";
+    if (searched.length === 0) {
+        return {
+            headline: "Nothing to validate: subject.discover selected no file kinds to search.",
+            warning: `Nothing was validated: subject.discover selected no file kinds to search, ${notOk}${accessTransformerHint}`
+        };
+    }
+    const list = joinWithOr(searched);
+    return {
+        headline: `Nothing to validate: no ${list} were found.`,
+        warning: `Nothing was validated: no ${list} were found under ${projectPath}, ${notOk}${accessTransformerHint}`
+    };
+}
 export async function handleProjectSummary(deps, input, detail, include, options = {}) {
     // Forwarded emitter for nested validators and probes; same swallow contract
     // as safeEmit so a rejecting raw emitter cannot leak into their outcomes.
@@ -27,7 +61,9 @@ export async function handleProjectSummary(deps, input, detail, include, options
             message: "task=project-summary requires subject.kind=workspace."
         });
     }
-    if (!input.version && !input.preferProjectVersion) {
+    // An omitted version is inferred from the project below; only an explicit
+    // preferProjectVersion=false opts out of that inference.
+    if (!input.version && input.preferProjectVersion === false) {
         const baseResult = buildEntryToolResult({
             task: "project-summary",
             detail,
@@ -52,7 +88,7 @@ export async function handleProjectSummary(deps, input, detail, include, options
                     }
                 ],
                 notes: [
-                    "Pass version explicitly, or retry with preferProjectVersion=true when gradle.properties declares the Minecraft version. The suggested retry sets preferProjectVersion=true for you."
+                    "Version inference was suppressed by preferProjectVersion=false. Pass version explicitly, or retry without preferProjectVersion=false to infer it from gradle.properties. The suggested retry sets preferProjectVersion=true for you."
                 ]
             },
             blocks: {
@@ -79,10 +115,21 @@ export async function handleProjectSummary(deps, input, detail, include, options
         projectPath,
         discover
     });
-    const detectedProjectVersion = input.preferProjectVersion
+    // preferProjectVersion=true overrides an explicit version; an omitted version is
+    // inferred (the explicit-false opt-out returned above).
+    const detectedProjectVersion = input.preferProjectVersion === true || !input.version
         ? await deps.detectProjectMinecraftVersion?.(projectPath)
         : undefined;
     const resolvedVersion = detectedProjectVersion ?? input.version;
+    const versionInferred = !input.version && Boolean(detectedProjectVersion);
+    // An inferred version is a project-version resolution: sub-validators and the
+    // artifact probe see exactly what an explicit preferProjectVersion=true run sees.
+    const effectivePreferProjectVersion = versionInferred ? true : input.preferProjectVersion;
+    const versionInferenceWarnings = versionInferred
+        ? [
+            `version was inferred from the workspace: ${detectedProjectVersion} (source: projectPath:gradle.properties (${projectPath})).`
+        ]
+        : [];
     const [mixinConfigs, accessWideners, accessTransformers] = await Promise.all([
         discover.includes("mixins")
             ? deps.discoverMixins(projectPath, input.configPaths)
@@ -111,17 +158,20 @@ export async function handleProjectSummary(deps, input, detail, include, options
                     sourcePriority: input.sourcePriority,
                     scope: input.scope
                 }),
+                // Retrying without a version would infer, fail, and block again, so the
+                // recovery asks for an explicit version instead.
                 nextActions: [
                     {
                         tool: "validate-project",
                         params: {
                             task: "project-summary",
-                            subject: input.subject
+                            subject: input.subject,
+                            version: "<minecraft-version>"
                         }
                     }
                 ],
                 notes: [
-                    "Pass version explicitly, or make sure gradle.properties declares the Minecraft version before using preferProjectVersion=true."
+                    "The Minecraft version could not be inferred from gradle.properties (minecraft_version, mc_version, or minecraftVersion). Retry with version set explicitly: replace \"<minecraft-version>\" in the suggested call with the project's Minecraft version, or declare it in gradle.properties."
                 ]
             },
             blocks: {
@@ -150,14 +200,16 @@ export async function handleProjectSummary(deps, input, detail, include, options
             ]
         };
     }
+    // Reached only when discovery found nothing (the branch above handles found files).
     if (!resolvedVersion) {
+        const nothingToValidate = describeNothingToValidate(discover, projectPath);
         const baseResult = buildEntryToolResult({
             task: "project-summary",
             detail,
             include,
             summary: {
                 status: "ok",
-                headline: `Validated ${mixinConfigs.length} mixin config(s), ${accessWideners.length} access widener(s), and ${accessTransformers.length} access transformer(s).`,
+                headline: nothingToValidate.headline,
                 subject: createSummarySubject({
                     task: "project-summary",
                     kind: input.subject.kind,
@@ -187,11 +239,11 @@ export async function handleProjectSummary(deps, input, detail, include, options
         return {
             ...baseResult,
             ...(tasks ? { tasks } : {}),
-            warnings: []
+            warnings: [nothingToValidate.warning]
         };
     }
     const validationVersion = resolvedVersion;
-    const warnings = [];
+    const warnings = [...versionInferenceWarnings];
     const mixinDurationStart = Date.now();
     let validMixins = 0;
     let partialMixins = 0;
@@ -288,7 +340,7 @@ export async function handleProjectSummary(deps, input, detail, include, options
                 projectPath,
                 gradleUserHome,
                 scope: input.scope,
-                preferProjectVersion: input.preferProjectVersion
+                preferProjectVersion: effectivePreferProjectVersion
             });
             if (output.valid) {
                 validAw += 1;
@@ -337,7 +389,7 @@ export async function handleProjectSummary(deps, input, detail, include, options
                 projectPath,
                 gradleUserHome,
                 scope: input.scope,
-                preferProjectVersion: input.preferProjectVersion
+                preferProjectVersion: effectivePreferProjectVersion
             });
             if (output.valid) {
                 validAt += 1;
@@ -361,13 +413,20 @@ export async function handleProjectSummary(deps, input, detail, include, options
     const invalidCount = invalidMixins + invalidAw + invalidAt;
     const partialCount = partialMixins;
     const status = invalidCount > 0 ? "invalid" : partialCount > 0 ? "partial" : "ok";
+    const nothingToValidate = mixinConfigs.length === 0 && accessWideners.length === 0 && accessTransformers.length === 0
+        ? describeNothingToValidate(discover, projectPath)
+        : undefined;
+    if (nothingToValidate) {
+        warnings.push(nothingToValidate.warning);
+    }
     const baseResult = buildEntryToolResult({
         task: "project-summary",
         detail,
         include,
         summary: {
             status,
-            headline: `Validated ${mixinConfigs.length} mixin config(s), ${accessWideners.length} access widener(s), and ${accessTransformers.length} access transformer(s).`,
+            headline: nothingToValidate?.headline ??
+                `Validated ${mixinConfigs.length} mixin config(s), ${accessWideners.length} access widener(s), and ${accessTransformers.length} access transformer(s).`,
             subject: createSummarySubject({
                 task: "project-summary",
                 kind: input.subject.kind,
@@ -416,7 +475,7 @@ export async function handleProjectSummary(deps, input, detail, include, options
         sourcePriority: input.sourcePriority,
         gradleUserHome,
         scope: input.scope,
-        preferProjectVersion: input.preferProjectVersion,
+        preferProjectVersion: effectivePreferProjectVersion,
         mixinDiscoveryCount: mixinConfigs.length,
         mixinCaughtErrors,
         mixinCounts: { ok: validMixins, partial: partialMixins, invalid: invalidMixins },