From 8dd1d8447146b9962ec7ab2f245b0fe47d3ddf44 Mon Sep 17 00:00:00 2001
From: Kaoru0822 <aisakamimaki@gmail.com>
Date: Mon, 5 Oct 2026 22:50:08 -0700
Subject: [PATCH] docs(installation): pin manual MCP registration to the
 release version (#658)

---
 docs/installation.md                           | 13 +++++++++----
 release-please-config.json                     |  1 +
 tests/conformance/readmeConsistency.test.ts    |  2 +-
 tests/conformance/releaseConfiguration.test.ts | 10 +++++++---
 4 files changed, 18 insertions(+), 8 deletions(-)

diff --git a/docs/installation.md b/docs/installation.md
index 65983bc6c5..5817f66c7c 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -323,17 +323,22 @@ server through `npx` with the `mcp` command.
 
 For a client that requires manual configuration, use:
 
+<!-- x-release-please-start-version -->
+
 ```json
 {
   "mcpServers": {
     "rea": {
       "command": "npx",
-      "args": ["-y", "rea-agents@latest", "mcp"]
+      "args": ["-y", "rea-agents@4.0.1", "mcp"]
     }
   }
 }
 ```
 
-Use an exact `rea-agents@VERSION` in the arguments when a reproducible client
-configuration is required. `rea setup` writes the same package-runner shape and
-pins it to the exact version that performed setup.
+<!-- x-release-please-end -->
+
+Persistent registrations should use one exact package version. `rea setup`
+writes the same package-runner shape and pins it to the exact version that
+performed setup. Run current setup to refresh an older registration, then
+restart the client.
diff --git a/release-please-config.json b/release-please-config.json
index 967f7f3ba2..c1ac99aa0a 100644
--- a/release-please-config.json
+++ b/release-please-config.json
@@ -21,6 +21,7 @@
         { "type": "generic", "path": "README_ja.md" },
         { "type": "generic", "path": "README_ko.md" },
         { "type": "generic", "path": "README_ar.md" },
+        { "type": "generic", "path": "docs/installation.md" },
         {
           "type": "generic",
           "path": "src/generatedPackageMetadata.ts"
diff --git a/tests/conformance/readmeConsistency.test.ts b/tests/conformance/readmeConsistency.test.ts
index 8f0d913bbb..7ff09e4097 100644
--- a/tests/conformance/readmeConsistency.test.ts
+++ b/tests/conformance/readmeConsistency.test.ts
@@ -95,7 +95,7 @@ describe("localized README product facts", () => {
         mcpServers: expect.objectContaining({
           rea: expect.objectContaining({
             command: "npx",
-            args: ["-y", "rea-agents@latest", "mcp"],
+            args: ["-y", PRODUCT_IDENTITY.registrationPackageSpecifier, "mcp"],
           }),
         }),
       }),
diff --git a/tests/conformance/releaseConfiguration.test.ts b/tests/conformance/releaseConfiguration.test.ts
index dc6a3ef87b..6988de6f94 100644
--- a/tests/conformance/releaseConfiguration.test.ts
+++ b/tests/conformance/releaseConfiguration.test.ts
@@ -7,12 +7,13 @@ import { SUPPORTED_NODE_VERSION_RANGE } from "../../src/domain/runtimeVersion.js
 const readJson = async (path: string): Promise<unknown> =>
   JSON.parse(await readFile(path, "utf8")) as unknown;
 
-const readmes = [
+const versionedDocumentation = [
   "README.md",
   "README_zh.md",
   "README_ja.md",
   "README_ko.md",
   "README_ar.md",
+  "docs/installation.md",
 ] as const;
 
 describe("release configuration", () => {
@@ -29,7 +30,10 @@ describe("release configuration", () => {
       packages: {
         ".": {
           "extra-files": [
-            ...readmes.map((path) => ({ type: "generic", path })),
+            ...versionedDocumentation.map((path) => ({
+              type: "generic",
+              path,
+            })),
             {
               type: "generic",
               path: "src/generatedPackageMetadata.ts",
@@ -55,7 +59,7 @@ describe("release configuration", () => {
     });
   });
 
-  it.each(readmes)(
+  it.each(versionedDocumentation)(
     "marks the versioned package example in %s",
     async (path) => {
       const content = await readFile(path, "utf8");