docs: align MCP discovery and skill guidance with the stable catalog (#664)

CONTRIBUTING.md

@@ -20,7 +20,7 @@ Turbo. Turbo caches deterministic builds and static checks across Git
 worktrees. After a package, lockfile, or managed-skill version change, run
 `npm run metadata:generate` before building.
 
-Keep dependencies flowing inward through the existing domain, contracts, provider, application, server, and adapter layers. Parse unknown values at process and protocol boundaries, model expected failures with `Result`, and preserve the canonical tool inventory defined by `TOOL_CONTRACTS` unless a deliberate contract change updates every verifier, generated catalog artifact, and snapshot. Prefer capability- and session-scoped tool advertisement over schema truncation.
+Keep dependencies flowing inward through the existing domain, contracts, provider, application, server, and adapter layers. Parse unknown values at process and protocol boundaries, model expected failures with `Result`, and preserve the canonical tool inventory defined by `TOOL_CONTRACTS` unless a deliberate contract change updates every verifier, generated catalog artifact, and snapshot. Keep tool discovery complete and report capability- and session-scoped availability through `binary_session`.
 
 ## Development feedback and PR verification
 

docs/mcp-contracts.md

@@ -8,15 +8,19 @@ registrations, reports their command vectors as aligned, stale, missing, or
 invalid, and keeps live-server state `unknown` unless the active connection
 supplies identity.
 
-Canonical tool names remain stable, while `tools/list` advertises only the
-operations callable for the current target, provider, host, and
-negotiated client capabilities. `binary_session.tool_availability` remains the
-complete inventory: it explains advertised and hidden operations with stable
-availability reasons and remediation. Each entry also reports required and
-optional negotiated client features plus the currently missing features.
-Opening or closing a target or observing a provider health transition emits
+`tools/list` returns the complete canonical tool inventory, including tools that
+are currently unavailable. Opening or closing a target or observing a provider
+health transition leaves that catalog unchanged and does not emit
 `notifications/tools/list_changed`.
 
+Call `binary_session` with `{}` and read `result.tool_availability` to choose a
+callable operation for the current target, provider, host, and negotiated client
+capabilities. The default result includes the complete inventory with each
+tool's availability, reason, and remediation. Each entry also reports required
+and optional negotiated client features plus the currently missing features.
+The optional inputs `expected_package_version`, `expected_catalog_digest`, and
+`expected_server_path` compare the live session with the caller's expectations.
+
 `binary_session.analysis_provider_candidates` is authoritative for deep-engine
 discovery. Target-free discovery is sorted by provider ID, reports host
 availability and `unknown` target support, and does not create an analysis

docs/product-catalog.json

@@ -7,7 +7,7 @@
       "client": "2.3.1",
       "core": "2.3.1"
     },
-    "skill_version": "24"
+    "skill_version": "25"
   },
   "tools": {
     "total": 116,

docs/verification/managed-conformance-manifest.json

@@ -1,5 +1,5 @@
 {
-  "manifest_id": "ecm_7da021af56cf2eb25489ed7ce494bfe92244e791fa3b5ad5a238a5eb14a23d9a",
+  "manifest_id": "ecm_6f5a77c85a58f9980ef709b832b5ccb5207c137d40e181b1ea209afa3de60c67",
   "verifier": {
     "id": "rea-managed-conformance",
     "version": "1"
@@ -13,7 +13,7 @@
   "skill_digests": [
     {
       "skill_id": "reverse-engineer-anything",
-      "sha256": "411d5b61e237e3b9b2cb9b3a987d83a36134a2ea1810ddd8d9f695dc05709f5b"
+      "sha256": "08b7039f48babaeda3660d9f62fa1066a6e9f72cf522a3f35201e59634253537"
     }
   ],
   "claims": [

skills/reverse-engineer-anything/SKILL.md

@@ -2,7 +2,7 @@
 name: reverse-engineer-anything
 description: Reverse engineer native, managed, Electron/JavaScript, packaged, and browser applications with REA. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
 metadata:
-  version: "24"
+  version: "25"
   tool_count: 116
   catalog_digest: "5bb3f994a3c4d0c87a34ff5aab4e28141b5fa6f3a98b5ae7e95686d85d9d983e"
 ---
@@ -37,10 +37,11 @@ name to one clear installed artifact when possible; ask only when matches are
 ambiguous. Never choose an example app on the user's behalf.
 
 In a target-free session, use `open_binary` to bind any archive/package or
-native target whose analysis tool operates on the active target. Do not call a
-tool hidden from `tools/list`; inspect `binary_session` with
-`detail: "capabilities"` for the exact remediation when a desired capability
-is unavailable.
+native target whose analysis tool operates on the active target. `tools/list`
+includes the complete catalog, including unavailable tools. When choosing a
+capability, call `binary_session` with no arguments and read the desired tool's
+entry in `result.tool_availability`. Follow its availability reason and
+remediation before calling an unavailable operation.
 
 ## Work summary-first
 

skills/reverse-engineer-anything/references/native-and-artifacts.md

@@ -9,10 +9,11 @@ cross-references. Addresses and recovered pseudocode are analysis observations,
 not original source. Provider unavailability and unsupported metadata remain
 unknown rather than false.
 
-Use `binary_session` with its default summary to check the open target, selected
-provider, alignment, and recommended remediation. Request the capabilities view
-with a family filter and page bounds only when choosing a tool. Request the full
-view only for an explicit session-diagnostic need.
+Use `binary_session` with no arguments to check the open target, selected
+provider, and alignment. Its default `result.tool_availability` includes the
+complete tool inventory with availability reasons and remediation. When choosing
+a tool, use its entry in that result; `tools/list` retains the complete catalog
+when the target or provider state changes.
 
 ## Managed PE/CLI
 

src/generatedPackageMetadata.ts

@@ -5,5 +5,5 @@ export const PACKAGE_METADATA = {
   serverSdkVersion: "2.3.1",
   clientSdkVersion: "2.3.1",
   coreSdkVersion: "2.3.1",
-  skillVersion: "24",
+  skillVersion: "25",
 } as const;

tests/boundary/filesystem/setupSkill.test.ts

@@ -8,6 +8,7 @@ import {
   installCanonicalSkill,
 } from "../../../src/application/SetupSkill.js";
 import { TOOL_CONTRACTS } from "../../../src/contracts/toolContracts.js";
+import { PRODUCT_IDENTITY } from "../../../src/identity.js";
 
 describe("canonical skill transaction", () => {
   it("backs up and upgrades a stale managed skill without touching siblings", async () => {
@@ -34,7 +35,18 @@ describe("canonical skill transaction", () => {
       "stale managed skill\n",
     );
     const installedSkill = await readFile(destination, "utf8");
-    expect(installedSkill).toContain('version: "24"');
+    expect(installedSkill).toBe(
+      await readFile(
+        new URL(
+          "../../../skills/reverse-engineer-anything/SKILL.md",
+          import.meta.url,
+        ),
+        "utf8",
+      ),
+    );
+    expect(installedSkill).toContain(
+      `version: "${PRODUCT_IDENTITY.skillVersion}"`,
+    );
     expect(installedSkill).toContain("call available analysis tools");
     expect(installedSkill).toContain("obtain approval before setup writes");
     expect(await readFile(`${nativeGuide}.rea.backup`, "utf8")).toBe(