Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

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

N0zoM1z039db9fe4245c
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2924e3d45..b7eb53157 100644
--- a/CONTRIBUTING.md
+++ b/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
diff --git a/docs/mcp-contracts.md b/docs/mcp-contracts.md
index 5d6250947..ee4550fe2 100644
--- a/docs/mcp-contracts.md
+++ b/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
diff --git a/docs/product-catalog.json b/docs/product-catalog.json
index 3c49b4016..b5136f003 100644
--- a/docs/product-catalog.json
+++ b/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,
diff --git a/docs/verification/managed-conformance-manifest.json b/docs/verification/managed-conformance-manifest.json
index 85faa9e6d..33a881d20 100644
--- a/docs/verification/managed-conformance-manifest.json
+++ b/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": [
diff --git a/skills/reverse-engineer-anything/SKILL.md b/skills/reverse-engineer-anything/SKILL.md
index 59e4caee2..f9f169dd8 100644
--- a/skills/reverse-engineer-anything/SKILL.md
+++ b/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
diff --git a/skills/reverse-engineer-anything/references/native-and-artifacts.md b/skills/reverse-engineer-anything/references/native-and-artifacts.md
index 384256144..1423645df 100644
--- a/skills/reverse-engineer-anything/references/native-and-artifacts.md
+++ b/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
diff --git a/src/generatedPackageMetadata.ts b/src/generatedPackageMetadata.ts
index 10d72aa23..b7fcf6b1e 100644
--- a/src/generatedPackageMetadata.ts
+++ b/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;
diff --git a/tests/boundary/filesystem/setupSkill.test.ts b/tests/boundary/filesystem/setupSkill.test.ts
index a2ec56993..a28e49eea 100644
--- a/tests/boundary/filesystem/setupSkill.test.ts
+++ b/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(