@reticlehq/init 3.8.1 → 3.9.0

package/LICENSE

@@ -1,105 +1,202 @@
-# Functional Source License, Version 1.1, ALv2 Future License
 
-## Abbreviation
-
-FSL-1.1-ALv2
-
-## Notice
-
-Copyright 2026 Reticle Labs
-
-## Terms and Conditions
-
-### Licensor ("We")
-
-The party offering the Software under these Terms and Conditions.
-
-### The Software
-
-The "Software" is each version of the software that we make available under
-these Terms and Conditions, as indicated by our inclusion of these Terms and
-Conditions with the Software.
-
-### License Grant
-
-Subject to your compliance with this License Grant and the Patents,
-Redistribution and Trademark clauses below, we hereby grant you the right to
-use, copy, modify, create derivative works, publicly perform, publicly display
-and redistribute the Software for any Permitted Purpose identified below.
-
-### Permitted Purpose
-
-A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
-means making the Software available to others in a commercial product or
-service that:
-
-1. substitutes for the Software;
-
-2. substitutes for any other product or service we offer using the Software
-   that exists as of the date we make the Software available; or
-
-3. offers the same or substantially similar functionality as the Software.
-
-Permitted Purposes specifically include using the Software:
-
-1. for your internal use and access;
-
-2. for non-commercial education;
-
-3. for non-commercial research; and
-
-4. in connection with professional services that you provide to a licensee
-   using the Software in accordance with these Terms and Conditions.
-
-### Patents
-
-To the extent your use for a Permitted Purpose would necessarily infringe our
-patents, the license grant above includes a license under our patents. If you
-make a claim against any party that the Software infringes or contributes to
-the infringement of any patent, then your patent license to the Software ends
-immediately.
-
-### Redistribution
-
-The Terms and Conditions apply to all copies, modifications and derivatives of
-the Software.
-
-If you redistribute any copies, modifications or derivatives of the Software,
-you must include a copy of or a link to these Terms and Conditions and not
-remove any copyright notices provided in or with the Software.
-
-### Disclaimer
-
-THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
-PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
-
-IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
-SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
-EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
-
-### Trademarks
-
-Except for displaying the License Details and identifying us as the origin of
-the Software, you have no right under these Terms and Conditions to use our
-trademarks, trade names, service marks or product names.
-
-## Grant of Future License
-
-We hereby irrevocably grant you an additional license to use the Software under
-the Apache License, Version 2.0 that is effective on the second anniversary of
-the date we make the Software available. On or after that date, you may use the
-Software under the Apache License, Version 2.0, in which case the following
-will apply:
-
-Licensed under the Apache License, Version 2.0 (the "License"); you may not use
-this file except in compliance with the License.
-
-You may obtain a copy of the License at
-
-http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software distributed
-under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
-CONDITIONS OF ANY KIND, either express or implied. See the License for the
-specific language governing permissions and limitations under the License.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Reticle Labs
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+Reticle
+Copyright 2026 Reticle Labs
+
+This product includes software developed at Reticle Labs.
+Licensed under the Apache License, Version 2.0.

package/README.md

@@ -26,4 +26,4 @@ const result = runInit(
 
 ## License
 
-FSL-1.1-ALv2 — free for any Permitted Purpose, converts to Apache-2.0 two years after release. See [LICENSE](./LICENSE).
+Apache-2.0. See [LICENSE](./LICENSE).

package/dist/gather-plan-input.js

@@ -24,7 +24,7 @@ import { tanstackStartConnectPath } from './patch/tanstack-start.js';
 import { installedViteMajor } from './patch/vite-owning-config.js';
 import { PRETTIERIGNORE_PATH } from './patch/prettier-ignore.js';
 import { RETICLE_CONFIG_FILE } from './plan/plan.js';
-import { claudeAvailableProbe, claudeHasReticle, codexAvailableProbe } from './register/mcp.js';
+import { claudeAvailableProbe, claudeHasReticle, claudeUserEntryIsFloating, claudePluginInstalled, codexAvailableProbe, } from './register/mcp.js';
 import { nextUsesTypeScript, reticleDevLocation } from './patch/next-patch.js';
 import { scanTestids, storeHints, scanStores } from './detect/capabilities.js';
 import { CLAUDE_PROJECT_CONFIG, CURSOR_PROJECT_MARKER, McpClient } from './register/mcp-clients.js';
@@ -265,6 +265,10 @@ export function gatherPlanInput(options, io, pkg) {
     const claudeCli = options.mcp ? io.probe(availableProbe.command, availableProbe.args) : false;
     // Read from Claude's config, never `claude mcp get`: that launches the server — see claudeHasReticle.
     const mcpExists = claudeCli ? claudeHasReticle(io, io.cwd()) : false;
+    // The plugin brings its own server; a user-scope entry next to it is a duplicate.
+    const claudePlugin = options.mcp ? claudePluginInstalled(io) : false;
+    const claudeUserEntry = claudePlugin ? claudeHasReticle(io, undefined) : false;
+    const claudeUserEntryFloating = mcpExists && !claudePlugin && claudeUserEntryIsFloating(io);
     // Every MCP client this machine shows evidence of. Conservative and one-directional: we write
     // into a config a client ALREADY has, and never create ~/.gemini or ~/.codeium for somebody who
     // does not use them.
@@ -325,6 +329,9 @@ export function gatherPlanInput(options, io, pkg) {
         prettierIgnoreSource: io.readFile(PRETTIERIGNORE_PATH),
         claudeCli,
         mcpExists,
+        claudePlugin,
+        claudeUserEntry,
+        claudeUserEntryFloating,
         insideClaudeCode: io.host.insideClaudeCode(),
         claudeProjectConfig: options.mcp ? io.readFile(agentFile(CLAUDE_PROJECT_CONFIG)) : undefined,
         platform: process.platform,
@@ -432,6 +439,7 @@ export function gatherPlanInput(options, io, pkg) {
             const bin = io.host.hookBin?.();
             return bin === undefined ? {} : { hookBin: bin };
         })(),
+        mcpLauncher: io.host.mcpLauncher?.(),
         ...(agentRoot === undefined
             ? {}
             : {

package/dist/host.d.ts

@@ -55,6 +55,12 @@ export interface InitHost {
      * where a direct command is not wanted (Windows shells), and the hooks use npx alone.
      */
     hookBin?(): string | undefined;
+    /**
+     * The installed CLI's bin, as an absolute path, for the MCP registration (`node <bin> mcp`).
+     * Undefined when this CLI runs from a run-once copy such as npx's cache: the registration then
+     * names the pinned npx command. See `installedLauncher`.
+     */
+    mcpLauncher?(): string | undefined;
 }
 /**
  * A host that does nothing, for callers that drive `init`'s file surface without running an install

package/dist/index.d.ts

@@ -46,8 +46,8 @@ export { reticleConfigContent } from './patch/snippets.js';
  * the same detection `init` uses — a second copy would be a second answer to "which agents are
  * here", and the two would disagree the first time a client was added to one of them.
  */
-export { McpClient, ConfigScope, MCP_CLIENTS, ClientMergeStatus, clientSpec, mergeClientConfig, } from './register/mcp-clients.js';
-export { claudeAddCommand, claudeAvailableProbe, claudeHasReticle, codexAddCommand, codexAvailableProbe, } from './register/mcp.js';
+export { McpClient, ConfigScope, MCP_CLIENTS, ClientMergeStatus, ConfigFormat, clientSpec, mergeClientConfig, type ClientSpec, } from './register/mcp-clients.js';
+export { claudeAddCommand, claudeAvailableProbe, claudeHasReticle, claudePluginInstalled, claudeRemoveUserCommand, claudeReticleEntries, claudeStaleEntryNote, claudeUserEntryIsFloating, codexAddCommand, codexAvailableProbe, installedLauncher, isReticleLauncher, isReticleRegistration, serverInvocation, } from './register/mcp.js';
 export { codexNamesOurServer } from './register/codex-toml.js';
 export { detectMcpClients, type DetectedClient } from './register/detect-clients.js';
 /**

package/dist/index.js

@@ -46,15 +46,17 @@ export { reticleConfigContent } from './patch/snippets.js';
  * the same detection `init` uses — a second copy would be a second answer to "which agents are
  * here", and the two would disagree the first time a client was added to one of them.
  */
-export { McpClient, ConfigScope, MCP_CLIENTS, ClientMergeStatus, clientSpec, mergeClientConfig, } from './register/mcp-clients.js';
+export { McpClient, ConfigScope, MCP_CLIENTS, ClientMergeStatus, ConfigFormat, clientSpec, mergeClientConfig, } from './register/mcp-clients.js';
 export { claudeAddCommand, 
 // The two probes `run.ts` uses to decide about Claude Code. Exported because `reticle setup mcp`
 // asks the same question and had no way to ask it: Claude Code keeps no config file, so the
 // file-reading detector cannot see it, and the installer silently skipped the commonest client.
-claudeAvailableProbe, claudeHasReticle, 
+claudeAvailableProbe, claudeHasReticle, claudePluginInstalled, claudeRemoveUserCommand, claudeReticleEntries, claudeStaleEntryNote, claudeUserEntryIsFloating, 
 // Codex keeps its registration behind `codex mcp add`, like Claude. `reticle setup mcp` needs the
 // command, the probe and the "is the entry already there, in any shape" check to do the same.
-codexAddCommand, codexAvailableProbe, } from './register/mcp.js';
+codexAddCommand, codexAvailableProbe, 
+// The MCP launch rule, for `reticle setup` (other agents) and `reticle doctor` (a launcher gone).
+installedLauncher, isReticleLauncher, isReticleRegistration, serverInvocation, } from './register/mcp.js';
 export { codexNamesOurServer } from './register/codex-toml.js';
 export { detectMcpClients } from './register/detect-clients.js';
 /**

package/dist/plan/plan-types.d.ts

@@ -125,6 +125,12 @@ export interface PlanInput {
     claudeCli: boolean;
     /** Whether an `reticle` MCP server is already registered with Claude (any scope) — idempotency. */
     mcpExists: boolean;
+    /** The Reticle Claude Code plugin is installed, and it brings its own `reticle` server. */
+    claudePlugin?: boolean | undefined;
+    /** A user-scope `reticle` entry exists too. Next to the plugin, that is a duplicate. */
+    claudeUserEntry?: boolean | undefined;
+    /** The user-scope `reticle` entry is the floating npx form. Reported, never replaced. */
+    claudeUserEntryFloating?: boolean | undefined;
     /**
      * Whether `init` is running inside Claude Code itself, which is the one case where writing its
      * project-scope `.mcp.json` is known to be wanted. See `CLAUDE_PROJECT_SPEC`.
@@ -372,6 +378,8 @@ export interface PlanInput {
     promptHooks?: readonly PromptHookTarget[] | undefined;
     /** See `InitHost.hookBin`. */
     hookBin?: string | undefined;
+    /** See `InitHost.mcpLauncher`. Absent: the MCP registration uses the pinned npx command. */
+    mcpLauncher?: string | undefined;
     /**
      * Absolute directory the AGENT runs in, when that is not the app's directory.
      *

package/dist/plan/plan.js

@@ -3,7 +3,7 @@
  * contents, produce an ordered list of steps — each marked apply / manual / already / skip. The
  * runner performs the `write` side-effects; this module decides *what* should happen.
  */
-import { claudeAddCommand, claudeProjectMcpJson, codexAddCommand, mcpManual, } from '../register/mcp.js';
+import { claudeAddCommand, claudeProjectMcpJson, claudeRemoveUserCommand, claudeStaleEntryNote, codexAddCommand, mcpManual, } from '../register/mcp.js';
 import { codexNamesOurServer } from '../register/codex-toml.js';
 import { mergeClientConfig, ClientMergeStatus, clientSnippet, clientSpec, CLAUDE_PROJECT_CONFIG, CLAUDE_PROJECT_SPEC, McpClient, } from '../register/mcp-clients.js';
 import { CLAUDE_COMMAND_PATH, CURSOR_COMMAND_PATH, SLASH_COMMAND_BODY, SLASH_COMMAND_SIGNATURE, } from '../register/slash-command.js';
@@ -39,7 +39,47 @@ function agentFile(input, relPath) {
     return root === undefined || 0 === root.length ? relPath : join(root, relPath);
 }
 const CLAUDE_MCP_TITLE = 'MCP server (Claude, global)';
+/**
+ * The Reticle plugin brings its own `reticle` server. A user-scope entry next to it gives Claude
+ * Code two servers with the same tools, so none is added. An old one is named, not removed.
+ */
+function claudePluginStep(input) {
+    if (true === input.claudeUserEntry) {
+        return {
+            title: CLAUDE_MCP_TITLE,
+            target: MCP_TARGET,
+            status: StepStatus.MANUAL,
+            detail: `the Reticle plugin is active and a user-scope reticle server is registered too, so Claude Code has two. Remove the user-scope one: ${claudeRemoveUserCommand()}`,
+        };
+    }
+    return {
+        title: CLAUDE_MCP_TITLE,
+        target: MCP_TARGET,
+        status: StepStatus.ALREADY,
+        detail: 'the Reticle plugin is active and gives Claude Code its server; no user-scope entry added',
+    };
+}
+/**
+ * The floating npx entry, kept and named. A NOTICE after the Claude Code step, so the step that
+ * decides the closing hint still reads ALREADY.
+ */
+function claudeFloatingSteps(input) {
+    if (true !== input.claudeUserEntryFloating) {
+        return [];
+    }
+    return [
+        {
+            title: 'Old MCP entry (Claude, global)',
+            target: MCP_TARGET,
+            status: StepStatus.NOTICE,
+            detail: claudeStaleEntryNote(input.mcpLauncher),
+        },
+    ];
+}
 function claudeMcpStep(input) {
+    if (true === input.claudePlugin) {
+        return claudePluginStep(input);
+    }
     if (!input.claudeCli) {
         return null;
     }
@@ -51,7 +91,7 @@ function claudeMcpStep(input) {
             detail: 'reticle already registered (install once, used by every project)',
         };
     }
-    const cmd = claudeAddCommand();
+    const cmd = claudeAddCommand(input.mcpLauncher);
     return {
         title: CLAUDE_MCP_TITLE,
         target: MCP_TARGET,
@@ -71,7 +111,7 @@ function otherClientSteps(input) {
     return (input.detectedClients ?? []).map((detected) => {
         const spec = clientSpec(detected.id);
         return (codexCliStep(spec, detected.configPath, detected.existing, input) ??
-            clientStep(spec, detected.configPath, detected.existing));
+            clientStep(spec, detected.configPath, detected.existing, input.mcpLauncher));
     });
 }
 /**
@@ -90,7 +130,7 @@ function codexCliStep(spec, configPath, existing, input) {
     if (codexNamesOurServer(existing, spec.serversKey)) {
         return null;
     }
-    const cmd = codexAddCommand();
+    const cmd = codexAddCommand(input.mcpLauncher);
     return {
         title: `MCP server (${spec.label})`,
         target: configPath,
@@ -100,8 +140,8 @@ function codexCliStep(spec, configPath, existing, input) {
     };
 }
 /** One client's step: already-correct is left alone, an unparseable file gets a paste-able block. */
-function clientStep(spec, configPath, existing) {
-    const merged = mergeClientConfig(spec, existing);
+function clientStep(spec, configPath, existing, launcher) {
+    const merged = mergeClientConfig(spec, existing, launcher);
     const title = `MCP server (${spec.label})`;
     if (merged.status === ClientMergeStatus.ALREADY) {
         return {
@@ -118,7 +158,7 @@ function clientStep(spec, configPath, existing) {
             title,
             target: configPath,
             status: StepStatus.MANUAL,
-            detail: `add this to ${configPath} by hand:\n${clientSnippet(spec)}`,
+            detail: `add this to ${configPath} by hand:\n${clientSnippet(spec, launcher)}`,
         };
     }
     return {
@@ -136,11 +176,11 @@ function clientStep(spec, configPath, existing) {
  * they get the notice instead.
  */
 function claudeProjectStep(input) {
-    if (input.claudeCli || true !== input.insideClaudeCode) {
+    if (input.claudeCli || true !== input.insideClaudeCode || true === input.claudePlugin) {
         return null;
     }
     const path = agentFile(input, CLAUDE_PROJECT_CONFIG);
-    return clientStep(CLAUDE_PROJECT_SPEC, path, input.claudeProjectConfig ?? null);
+    return clientStep(CLAUDE_PROJECT_SPEC, path, input.claudeProjectConfig ?? null, input.mcpLauncher);
 }
 /** One global registration per detected agent (Claude + Cursor). Falls back to a manual note. */
 function mcpSteps(input) {
@@ -163,6 +203,7 @@ function mcpSteps(input) {
     const claudeProject = claudeProjectStep(input);
     const steps = [
         ...stepsForAgents(input, (a) => a.mcpStep),
+        ...claudeFloatingSteps(input),
         ...(null === claudeProject ? [] : [claudeProject]),
         ...otherClientSteps(input),
     ];
@@ -173,7 +214,7 @@ function mcpSteps(input) {
                 title: 'MCP server (global)',
                 target: MCP_TARGET,
                 status: StepStatus.MANUAL,
-                detail: mcpManual(),
+                detail: mcpManual(input.mcpLauncher),
             },
         ];
     }
@@ -191,7 +232,10 @@ function mcpSteps(input) {
      * to register, so nothing has silently vanished — and leaving that path untouched keeps every
      * pristine scaffold in the install baseline reading exactly as it did.
      */
-    if (!input.claudeCli && null === claudeProject && steps.length > 0) {
+    if (!input.claudeCli &&
+        true !== input.claudePlugin &&
+        null === claudeProject &&
+        steps.length > 0) {
         steps.push({
             title: CLAUDE_MCP_TITLE,
             target: MCP_TARGET,
@@ -200,7 +244,7 @@ function mcpSteps(input) {
             // which would turn an informational line into a gate failure on any machine that happens to
             // have another agent's config. A notice prints in full exactly like a manual step.
             status: StepStatus.NOTICE,
-            detail: `no \`claude\` on PATH, so it could not be registered from here. Inside a Claude Code VS Code extension session the CLI is genuinely absent while the editor is not — add ${claudeProjectMcpJson()}`,
+            detail: `no \`claude\` on PATH, so it could not be registered from here. Inside a Claude Code VS Code extension session the CLI is genuinely absent while the editor is not — add ${claudeProjectMcpJson(input.mcpLauncher)}`,
         });
     }
     const windowsNote = windowsMcpNoteStep(input);

package/dist/register/mcp-clients.d.ts

@@ -32,8 +32,8 @@ export interface ClientSpec {
     format: ConfigFormat;
     /** The object key holding the server map — `mcpServers`, `servers`, or `mcp`. */
     serversKey: string;
-    /** Our entry, in THIS client's shape. */
-    entry: () => unknown;
+    /** Our entry, in THIS client's shape. `launcher`: see `serverInvocation`. */
+    entry: (launcher?: string) => unknown;
     /** Where the shape came from, so the next person can re-check it rather than trust this file. */
     docs: string;
 }
@@ -74,14 +74,14 @@ interface ClientMergeResult {
  * already has the table is a warning they must not act on, and the setup contract makes a `⚠`
  * blocking (#681). Detection is read-only and cannot corrupt anything.
  */
-export declare function mergeClientConfig(spec: ClientSpec, existing: string | null): ClientMergeResult;
+export declare function mergeClientConfig(spec: ClientSpec, existing: string | null, launcher?: string): ClientMergeResult;
 /**
  * A block the user can paste, for a client we could not write.
  *
  * Every client gets one, including the ones we CAN write: when a merge comes back MANUAL because the
  * file could not be parsed, the snippet is the only actionable thing left to give.
  */
-export declare function clientSnippet(spec: ClientSpec): string;
+export declare function clientSnippet(spec: ClientSpec, launcher?: string): string;
 /**
  * The path whose existence means "this user has this client".
  *

package/dist/register/mcp-clients.js

@@ -18,7 +18,7 @@
  * an install that reports success and registers nothing, which is the exact failure class this
  * repo's install gate exists to catch.
  */
-import { NPX, MCP_SERVER_NAME, npxServerArgs, isReticleRegistration } from './mcp.js';
+import { MCP_SERVER_NAME, isReticleRegistration, serverInvocation } from './mcp.js';
 import { codexServerTokens } from './codex-toml.js';
 export const McpClient = {
     CLAUDE_CODE: 'claude-code',
@@ -43,15 +43,16 @@ export const ConfigFormat = {
     CLI: 'cli',
 };
 /** The `{ command, args }` entry Cursor, Windsurf, Gemini and VS Code all take. */
-function commandArgsEntry() {
-    return { command: NPX, args: npxServerArgs() };
+function commandArgsEntry(launcher) {
+    const [command, ...args] = serverInvocation(launcher);
+    return { command, args };
 }
 /**
  * OpenCode's entry. `command` is a single ARRAY containing the executable and its arguments, and
  * `enabled` is explicit — a server registered but disabled is the quietest possible failure.
  */
-function openCodeEntry() {
-    return { type: 'local', command: [NPX, ...npxServerArgs()], enabled: true };
+function openCodeEntry(launcher) {
+    return { type: 'local', command: serverInvocation(launcher), enabled: true };
 }
 /**
  * Claude Code's project-scope MCP config, which needs no CLI on PATH.
@@ -189,8 +190,9 @@ export const MCP_CLIENTS = [
 ];
 export function clientSpec(id) {
     const found = MCP_CLIENTS.find((spec) => spec.id === id);
-    if (found === undefined)
+    if (found === undefined) {
         throw new Error(`no MCP client spec for '${id}'`);
+    }
     return found;
 }
 export const ClientMergeStatus = {
@@ -199,15 +201,17 @@ export const ClientMergeStatus = {
     MANUAL: 'manual',
 };
 function parseConfig(existing) {
-    if (null === existing || 0 === existing.trim().length)
+    if (null === existing || 0 === existing.trim().length) {
         return { ok: true, config: {} };
+    }
     try {
         const parsed = JSON.parse(existing);
         // Valid JSON that is not a PLAIN OBJECT — `[]`, `3`, `"x"`, `null` — must not fall through to an
         // empty config, because the file then gets rewritten wholesale. Unparseable JSON was always
         // handled conservatively; this adjacent case destroyed the file instead.
-        if (typeof parsed !== 'object' || null === parsed || Array.isArray(parsed))
+        if (typeof parsed !== 'object' || null === parsed || Array.isArray(parsed)) {
             return { ok: false };
+        }
         return { ok: true, config: parsed };
     }
     catch {
@@ -228,11 +232,13 @@ function parseConfig(existing) {
  * not repair the thing an upgrade exists to repair — and a WRONG one, naming a Reticle package that
  * has no MCP server in it (see isReticleRegistration).
  */
-function leaveEntryAlone(existing, spec) {
-    if (JSON.stringify(existing) === JSON.stringify(spec.entry()))
+function leaveEntryAlone(existing, spec, launcher) {
+    if (JSON.stringify(existing) === JSON.stringify(spec.entry(launcher))) {
         return true;
-    if (typeof existing !== 'object' || null === existing)
+    }
+    if (typeof existing !== 'object' || null === existing) {
         return true;
+    }
     const record = existing;
     // Both shapes carry the package name somewhere in a string; find it without assuming which field.
     const tokens = [record.command, record.args].flat().filter((v) => 'string' === typeof v);
@@ -246,14 +252,23 @@ function leaveEntryAlone(existing, spec) {
  * drifted from what we would write, and when the shape was not one the scanner reads — every one of
  * those keeps today's MANUAL answer, and the snippet is then the actionable thing to print.
  */
-function tomlEntryIsSettled(spec, existing) {
+/** `@reticlehq/server@3.8.2` → `@reticlehq/server`. Every other string is returned as it is. */
+const unpinned = (token) => token.replace(/^(@reticlehq\/server)@.*$/, '$1');
+function tomlEntryIsSettled(spec, existing, launcher) {
     const tokens = codexServerTokens(existing, spec.serversKey);
-    if (0 === tokens.length)
+    if (0 === tokens.length) {
         return false;
-    const expected = [NPX, ...npxServerArgs()];
+    }
     // Same strings, and no others: an entry carrying an extra flag is not the one we would write.
-    if (tokens.length === expected.length && expected.every((t) => tokens.includes(t)))
+    const same = (a, b) => a.length === b.length && b.every((t) => a.includes(t));
+    if (same(tokens, serverInvocation(launcher))) {
         return true;
+    }
+    // An npx entry of an older version still starts Reticle. TOML is never written by us, so asking
+    // for a hand edit at each release is a warning with no defect behind it.
+    if (same(tokens.map(unpinned), serverInvocation().map(unpinned))) {
+        return true;
+    }
     // Not ours to touch. Somebody pointing `reticle` at their own local build made a deliberate
     // choice, and telling them to hand-edit it back is the same wrong answer as overwriting it.
     return !isReticleRegistration(tokens);
@@ -269,29 +284,30 @@ function tomlEntryIsSettled(spec, existing) {
  * already has the table is a warning they must not act on, and the setup contract makes a `⚠`
  * blocking (#681). Detection is read-only and cannot corrupt anything.
  */
-export function mergeClientConfig(spec, existing) {
+export function mergeClientConfig(spec, existing, launcher) {
     if (spec.format !== ConfigFormat.JSON) {
-        if (ConfigFormat.TOML === spec.format && tomlEntryIsSettled(spec, existing)) {
+        if (ConfigFormat.TOML === spec.format && tomlEntryIsSettled(spec, existing, launcher)) {
             return { status: ClientMergeStatus.ALREADY, content: existing ?? '' };
         }
         return { status: ClientMergeStatus.MANUAL, content: existing ?? '' };
     }
     const parsed = parseConfig(existing);
-    if (!parsed.ok)
+    if (!parsed.ok) {
         return { status: ClientMergeStatus.MANUAL, content: existing ?? '' };
+    }
     const config = parsed.config;
     const current = config[spec.serversKey];
     const servers = 'object' === typeof current && null !== current && !Array.isArray(current)
         ? current
         : {};
     if (Object.prototype.hasOwnProperty.call(servers, MCP_SERVER_NAME) &&
-        leaveEntryAlone(servers[MCP_SERVER_NAME], spec)) {
+        leaveEntryAlone(servers[MCP_SERVER_NAME], spec, launcher)) {
         return { status: ClientMergeStatus.ALREADY, content: existing ?? '' };
     }
     // Only OUR key is replaced; every other server and top-level key is carried through untouched.
     const merged = {
         ...config,
-        [spec.serversKey]: { ...servers, [MCP_SERVER_NAME]: spec.entry() },
+        [spec.serversKey]: { ...servers, [MCP_SERVER_NAME]: spec.entry(launcher) },
     };
     return { status: ClientMergeStatus.APPLY, content: `${JSON.stringify(merged, null, 2)}\n` };
 }
@@ -301,17 +317,17 @@ export function mergeClientConfig(spec, existing) {
  * Every client gets one, including the ones we CAN write: when a merge comes back MANUAL because the
  * file could not be parsed, the snippet is the only actionable thing left to give.
  */
-export function clientSnippet(spec) {
+export function clientSnippet(spec, launcher) {
+    const [command, ...rest] = serverInvocation(launcher);
     if (spec.format === ConfigFormat.TOML) {
-        const args = npxServerArgs()
-            .map((a) => `"${a}"`)
-            .join(', ');
-        return `[mcp_servers.${MCP_SERVER_NAME}]\ncommand = "${NPX}"\nargs = [${args}]\n`;
+        // JSON string escapes are valid TOML basic-string escapes, so a Windows path stays valid.
+        const args = rest.map((a) => JSON.stringify(a)).join(', ');
+        return `[mcp_servers.${MCP_SERVER_NAME}]\ncommand = ${JSON.stringify(command)}\nargs = [${args}]\n`;
     }
     if (spec.format === ConfigFormat.CLI) {
-        return `claude mcp add -s user ${MCP_SERVER_NAME} -- ${NPX} ${npxServerArgs().join(' ')}\n`;
+        return `claude mcp add -s user ${MCP_SERVER_NAME} -- ${[command, ...rest].join(' ')}\n`;
     }
-    return `${JSON.stringify({ [spec.serversKey]: { [MCP_SERVER_NAME]: spec.entry() } }, null, 2)}\n`;
+    return `${JSON.stringify({ [spec.serversKey]: { [MCP_SERVER_NAME]: spec.entry(launcher) } }, null, 2)}\n`;
 }
 /**
  * The path whose existence means "this user has this client".
@@ -326,11 +342,13 @@ export function clientSnippet(spec) {
  * because a fresh Cursor profile has not written `~/.cursor` yet.
  */
 export function clientMarkerRelPath(spec) {
-    if (spec.scope === ConfigScope.CLI)
+    if (spec.scope === ConfigScope.CLI) {
         return '';
+    }
     // Antigravity also creates ~/.gemini. The shared parent is not evidence of Gemini CLI.
-    if (spec.id === McpClient.GEMINI)
+    if (spec.id === McpClient.GEMINI) {
         return spec.relPath;
+    }
     const parts = spec.relPath.split('/');
     return parts.length > 1 ? parts.slice(0, -1).join('/') : spec.relPath;
 }

package/dist/register/mcp.d.ts

@@ -5,7 +5,7 @@
  * hand-editing `~/.claude.json` (a large stateful file). When the `claude` CLI is absent we print a
  * manual instruction instead.
  *
- * The registration is intentionally PORTLESS — `npx @reticlehq/server mcp`, never `--port N`. A single
+ * The registration is intentionally PORTLESS — it never carries `--port N`. A single
  * global entry serves every project, so baking a port into it would pin every project to one port
  * and defeat per-project isolation. Instead `reticle mcp` resolves the port at runtime from the
  * project's `.reticle.json` in its CWD (see cli-port.ts). The port belongs to the project, not the
@@ -26,23 +26,26 @@ export { MCP_SERVER_NAME } from '@reticlehq/core';
  */
 export declare const NPX = "npx";
 /**
- * Args after `npx` that launch the bridge: `@reticlehq/server mcp`. Portless — the port comes from
- * the project's `.reticle.json` at runtime, so one global entry works for every project.
+ * Args after `npx` that launch the bridge: `@reticlehq/server@<this version> mcp`. Portless — the
+ * port comes from the project's `.reticle.json` at runtime, so one global entry works for every
+ * project.
  *
- * DELIBERATELY UNPINNED, and the trade is worth stating. `reticle init` pins the SDK to the CLI's
- * exact version, so on release day the app can be on the new one while npx serves a cached older
- * build — a real skew, reported from the field. Pinning this entry would remove that window.
- *
- * It would also freeze the agent's MCP server at whatever version was installed the day `init` ran,
- * for as long as that entry survives — and `reticle update` upgrades the CLI, not a global agent
- * config. A permanent pin trades a window that lasts until the next npx cache miss for one that
- * lasts forever.
- *
- * So it stays unpinned, and the skew is handled where it actually shows up: the contract fingerprint
- * makes a real mismatch loud on the next tool result (see version-skew), and a stale entry of our own
- * shape is now repaired on re-run rather than reported "already registered" (see mcp-clients.ts).
+ * PINNED to one exact version. With a floating `@reticlehq/server`, npx asks the registry on every
+ * start. A fresh sandbox (an empty npm cache) downloaded about 131 MB before the MCP server
+ * answered: 3.9 s to 5.6 s on each boot, against 0.6 s warm. With an exact version, an image that
+ * ran it once uses its cache again. A re-run of `init` or `reticle setup mcp` writes the new
+ * version into a stale entry of our own shape (see mcp-clients.ts), and the contract fingerprint
+ * makes a real mismatch loud on the next tool result (see version-skew).
  */
 export declare function npxServerArgs(): string[];
+/** Is this string the bin of an installed `@reticlehq/server`? */
+export declare function isReticleLauncher(token: string): boolean;
+/**
+ * The bin to register, when the CLI that runs now is an install that stays on disk: a global
+ * install, or one in a project's `node_modules`. `undefined` for a run-once copy and for a source
+ * checkout. Registration then uses the pinned npx command.
+ */
+export declare function installedLauncher(bin: string | undefined): string | undefined;
 /**
  * Is this existing registration one WE are responsible for?
  *
@@ -58,6 +61,11 @@ export declare function npxServerArgs(): string[];
  * @param tokens every string in the entry's command + args, in any of the client shapes.
  */
 export declare function isReticleRegistration(tokens: readonly string[]): boolean;
+/**
+ * The command that starts the MCP server: `node <launcher> mcp` for an installed copy, else the
+ * pinned npx command. `node` is a real executable on Windows too, so it needs no `cmd /c`.
+ */
+export declare function serverInvocation(launcher?: string): string[];
 interface CliAddCommand {
     command: string;
     args: string[];
@@ -65,7 +73,7 @@ interface CliAddCommand {
     display: string;
 }
 /** `claude mcp add reticle -s user -- npx @reticlehq/server mcp` — registers globally for all projects (portless). */
-export declare function claudeAddCommand(): CliAddCommand;
+export declare function claudeAddCommand(launcher?: string): CliAddCommand;
 /**
  * Is a `reticle` server already registered with Claude Code, in any scope this project sees?
  *
@@ -84,6 +92,33 @@ export declare function claudeHasReticle(io: {
     readFile(path: string): string | null;
     homeDir(): string;
 }, projectDir: string | undefined, configDir?: string | undefined): boolean;
+/** The `reticle` entries Claude Code has, in the scopes `claudeHasReticle` reads. */
+export declare function claudeReticleEntries(io: {
+    readFile(path: string): string | null;
+    homeDir(): string;
+}, projectDir: string | undefined, configDir?: string | undefined): unknown[];
+/**
+ * Is the Reticle Claude Code plugin installed? The plugin brings its own `reticle` MCP server, so a
+ * `claude mcp add` next to it gives Claude Code two servers with the same tools. An unreadable
+ * record reads as "not installed".
+ */
+export declare function claudePluginInstalled(io: {
+    readFile(path: string): string | null;
+    homeDir(): string;
+}, configDir?: string | undefined): boolean;
+/** The one command that removes a user-scope `reticle` entry left next to the plugin. */
+export declare function claudeRemoveUserCommand(): string;
+/**
+ * Claude Code's user-scope `reticle` entry is the floating npx form that registration wrote before
+ * it pinned a version or used the installed launcher. `claudeHasReticle` reads it as registered, so
+ * nothing replaced it. Reported only: a Claude Code entry is changed only by the person.
+ */
+export declare function claudeUserEntryIsFloating(io: {
+    readFile(path: string): string | null;
+    homeDir(): string;
+}, configDir?: string | undefined): boolean;
+/** The one sentence about a floating entry, and the commands that replace it. */
+export declare function claudeStaleEntryNote(launcher?: string): string;
 /** Probe args for whether the `claude` CLI is installed at all. */
 export declare function claudeAvailableProbe(): {
     command: string;
@@ -96,7 +131,7 @@ export declare function claudeAvailableProbe(): {
  * It REPLACES an existing entry of the same name and still exits 0, so callers run it only when the
  * config names no `reticle` server at all (see `codexNamesOurServer`).
  */
-export declare function codexAddCommand(): CliAddCommand;
+export declare function codexAddCommand(launcher?: string): CliAddCommand;
 /** Probe args for whether the `codex` CLI is installed at all. */
 export declare function codexAvailableProbe(): {
     command: string;
@@ -116,5 +151,5 @@ export declare function mcpWindowsNote(): string;
  * session the `claude` binary is not on PATH, so every CLI-based route is shut and `.mcp.json` in
  * the project root is the one that still works.
  */
-export declare function claudeProjectMcpJson(): string;
-export declare function mcpManual(): string;
+export declare function claudeProjectMcpJson(launcher?: string): string;
+export declare function mcpManual(launcher?: string): string;

package/dist/register/mcp.js

@@ -5,14 +5,14 @@
  * hand-editing `~/.claude.json` (a large stateful file). When the `claude` CLI is absent we print a
  * manual instruction instead.
  *
- * The registration is intentionally PORTLESS — `npx @reticlehq/server mcp`, never `--port N`. A single
+ * The registration is intentionally PORTLESS — it never carries `--port N`. A single
  * global entry serves every project, so baking a port into it would pin every project to one port
  * and defeat per-project isolation. Instead `reticle mcp` resolves the port at runtime from the
  * project's `.reticle.json` in its CWD (see cli-port.ts). The port belongs to the project, not the
  * global agent config.
  */
 import { join } from 'node:path';
-import { RETICLE_NPM_PACKAGE } from '../version.js';
+import { RETICLE_NPM_PACKAGE, RETICLE_VERSION } from '../version.js';
 // The name is a wire identity and lives in the contract; re-exported here so the registration writers
 // below (and their tests) keep reading it from the module that USES it.
 export { MCP_SERVER_NAME } from '@reticlehq/core';
@@ -40,25 +40,40 @@ const CODEX_CLI = 'codex';
 /** Windows `cmd /c` — the spawn that PowerShell's execution policy does not gate. */
 const WINDOWS_SHELL = 'cmd';
 const WINDOWS_SHELL_C = '/c';
+const NODE = 'node';
 /**
- * Args after `npx` that launch the bridge: `@reticlehq/server mcp`. Portless — the port comes from
- * the project's `.reticle.json` at runtime, so one global entry works for every project.
+ * Args after `npx` that launch the bridge: `@reticlehq/server@<this version> mcp`. Portless — the
+ * port comes from the project's `.reticle.json` at runtime, so one global entry works for every
+ * project.
  *
- * DELIBERATELY UNPINNED, and the trade is worth stating. `reticle init` pins the SDK to the CLI's
- * exact version, so on release day the app can be on the new one while npx serves a cached older
- * build — a real skew, reported from the field. Pinning this entry would remove that window.
- *
- * It would also freeze the agent's MCP server at whatever version was installed the day `init` ran,
- * for as long as that entry survives — and `reticle update` upgrades the CLI, not a global agent
- * config. A permanent pin trades a window that lasts until the next npx cache miss for one that
- * lasts forever.
- *
- * So it stays unpinned, and the skew is handled where it actually shows up: the contract fingerprint
- * makes a real mismatch loud on the next tool result (see version-skew), and a stale entry of our own
- * shape is now repaired on re-run rather than reported "already registered" (see mcp-clients.ts).
+ * PINNED to one exact version. With a floating `@reticlehq/server`, npx asks the registry on every
+ * start. A fresh sandbox (an empty npm cache) downloaded about 131 MB before the MCP server
+ * answered: 3.9 s to 5.6 s on each boot, against 0.6 s warm. With an exact version, an image that
+ * ran it once uses its cache again. A re-run of `init` or `reticle setup mcp` writes the new
+ * version into a stale entry of our own shape (see mcp-clients.ts), and the contract fingerprint
+ * makes a real mismatch loud on the next tool result (see version-skew).
  */
 export function npxServerArgs() {
-    return [RETICLE_PACKAGE, MCP_SUBCOMMAND];
+    return [`${RETICLE_PACKAGE}@${RETICLE_VERSION}`, MCP_SUBCOMMAND];
+}
+/** `<…>/@reticlehq/server/bin/reticle.js`, with either separator. */
+const LAUNCHER_TAIL = /[\\/]@reticlehq[\\/]server[\\/]bin[\\/]reticle\.js$/;
+/** A copy that a runner can delete at any time: npx `_npx`, pnpm `dlx`, yarn `dlx-*`, `bunx-*`. */
+const RUN_ONCE_COPY = /[\\/](?:_npx|dlx(?:-[^\\/]*)?|bunx-[^\\/]*)[\\/]/;
+/** Is this string the bin of an installed `@reticlehq/server`? */
+export function isReticleLauncher(token) {
+    return LAUNCHER_TAIL.test(token);
+}
+/**
+ * The bin to register, when the CLI that runs now is an install that stays on disk: a global
+ * install, or one in a project's `node_modules`. `undefined` for a run-once copy and for a source
+ * checkout. Registration then uses the pinned npx command.
+ */
+export function installedLauncher(bin) {
+    if (bin === undefined || !isReticleLauncher(bin) || RUN_ONCE_COPY.test(bin)) {
+        return undefined;
+    }
+    return bin;
 }
 /** The npm scope every Reticle package shares — the marker of a registration we are entitled to fix. */
 const RETICLE_SCOPE = '@reticlehq/';
@@ -77,30 +92,44 @@ const RETICLE_SCOPE = '@reticlehq/';
  * @param tokens every string in the entry's command + args, in any of the client shapes.
  */
 export function isReticleRegistration(tokens) {
+    if (tokens.some(isReticleLauncher)) {
+        return true;
+    }
     return tokens.includes(NPX) && tokens.some((t) => t.includes(RETICLE_SCOPE));
 }
-/** The full `npx …` invocation — the tail after `claude mcp add … --`. */
-function serverInvocation() {
-    return [NPX, ...npxServerArgs()];
+/**
+ * The command that starts the MCP server: `node <launcher> mcp` for an installed copy, else the
+ * pinned npx command. `node` is a real executable on Windows too, so it needs no `cmd /c`.
+ */
+export function serverInvocation(launcher) {
+    if (launcher === undefined) {
+        return [NPX, ...npxServerArgs()];
+    }
+    return [NODE, launcher, MCP_SUBCOMMAND];
 }
 /** `claude mcp add reticle -s user -- npx @reticlehq/server mcp` — registers globally for all projects (portless). */
-export function claudeAddCommand() {
-    const tail = serverInvocation();
+export function claudeAddCommand(launcher) {
+    const tail = serverInvocation(launcher);
     const args = [MCP_SUBCOMMAND, 'add', MCP_SERVER_NAME, '-s', 'user', '--', ...tail];
     return { command: CLAUDE_CLI, args, display: `${CLAUDE_CLI} ${args.join(' ')}` };
 }
 /** Where Claude Code keeps its state: `$CLAUDE_CONFIG_DIR/.claude.json`, else `~/.claude.json`. */
 const CLAUDE_STATE_FILE = '.claude.json';
 /** `mcpServers` holds a `reticle` entry. */
-function namesReticle(scope) {
-    if ('object' !== typeof scope || null === scope)
-        return false;
+function reticleEntry(scope) {
+    if ('object' !== typeof scope || null === scope) {
+        return undefined;
+    }
     const servers = scope.mcpServers;
-    return 'object' === typeof servers && null !== servers && MCP_SERVER_NAME in servers;
+    if ('object' !== typeof servers || null === servers) {
+        return undefined;
+    }
+    return servers[MCP_SERVER_NAME];
 }
 function parsed(source) {
-    if (null === source)
+    if (null === source) {
         return undefined;
+    }
     try {
         return JSON.parse(source);
     }
@@ -123,19 +152,80 @@ function parsed(source) {
  * which costs at worst a `claude mcp add` that reports the entry already exists.
  */
 export function claudeHasReticle(io, projectDir, configDir = process.env['CLAUDE_CONFIG_DIR']) {
+    return 0 < claudeReticleEntries(io, projectDir, configDir).length;
+}
+/** The `reticle` entries Claude Code has, in the scopes `claudeHasReticle` reads. */
+export function claudeReticleEntries(io, projectDir, configDir = process.env['CLAUDE_CONFIG_DIR']) {
     const state = parsed(io.readFile(join(configDir ?? io.homeDir(), CLAUDE_STATE_FILE)));
-    if (namesReticle(state))
-        return true;
-    if (projectDir === undefined)
-        return false;
-    const projects = 'object' === typeof state && null !== state
-        ? state.projects
+    const scopes = [state];
+    if (projectDir !== undefined) {
+        const projects = 'object' === typeof state && null !== state
+            ? state.projects
+            : undefined;
+        if ('object' === typeof projects && null !== projects) {
+            scopes.push(projects[projectDir]);
+        }
+        scopes.push(parsed(io.readFile(join(projectDir, CLAUDE_PROJECT_CONFIG))));
+    }
+    return scopes.map(reticleEntry).filter((entry) => entry !== undefined);
+}
+/** Claude Code's plugin install record, under `$CLAUDE_CONFIG_DIR`, else `~/.claude`. */
+const CLAUDE_PLUGINS_FILE = join('plugins', 'installed_plugins.json');
+const CLAUDE_CONFIG_HOME = '.claude';
+/** A plugin key is `<name>@<marketplace>`. */
+const RETICLE_PLUGIN_PREFIX = `${MCP_SERVER_NAME}@`;
+/**
+ * Is the Reticle Claude Code plugin installed? The plugin brings its own `reticle` MCP server, so a
+ * `claude mcp add` next to it gives Claude Code two servers with the same tools. An unreadable
+ * record reads as "not installed".
+ */
+export function claudePluginInstalled(io, configDir = process.env['CLAUDE_CONFIG_DIR']) {
+    const dir = configDir ?? join(io.homeDir(), CLAUDE_CONFIG_HOME);
+    const record = parsed(io.readFile(join(dir, CLAUDE_PLUGINS_FILE)));
+    const plugins = 'object' === typeof record && null !== record
+        ? record.plugins
         : undefined;
-    if ('object' === typeof projects && null !== projects) {
-        if (namesReticle(projects[projectDir]))
-            return true;
+    if ('object' !== typeof plugins || null === plugins) {
+        return false;
+    }
+    return Object.keys(plugins).some((key) => key.startsWith(RETICLE_PLUGIN_PREFIX));
+}
+/** The one command that removes a user-scope `reticle` entry left next to the plugin. */
+export function claudeRemoveUserCommand() {
+    return `${CLAUDE_CLI} ${MCP_SUBCOMMAND} remove ${MCP_SERVER_NAME} -s user`;
+}
+/** `x.y.z`, or `x.y.z-pre`: one exact version. `latest`, a range or nothing is not one. */
+const EXACT_VERSION = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const PACKAGE_AT = `${RETICLE_PACKAGE}@`;
+/** Every string in an entry's `command` and `args`. */
+function entryTokens(entry) {
+    if ('object' !== typeof entry || null === entry) {
+        return [];
+    }
+    const { command, args } = entry;
+    return [command, args].flat().filter((v) => 'string' === typeof v);
+}
+/** The npx form of `@reticlehq/server` with no exact version: npx starts whatever its cache holds. */
+function isFloatingNpx(tokens) {
+    if (!tokens.includes(NPX) || tokens.some(isReticleLauncher)) {
+        return false;
     }
-    return namesReticle(parsed(io.readFile(join(projectDir, CLAUDE_PROJECT_CONFIG))));
+    return tokens.some((t) => RETICLE_PACKAGE === t ||
+        (t.startsWith(PACKAGE_AT) && !EXACT_VERSION.test(t.slice(PACKAGE_AT.length))));
+}
+/**
+ * Claude Code's user-scope `reticle` entry is the floating npx form that registration wrote before
+ * it pinned a version or used the installed launcher. `claudeHasReticle` reads it as registered, so
+ * nothing replaced it. Reported only: a Claude Code entry is changed only by the person.
+ */
+export function claudeUserEntryIsFloating(io, configDir = process.env['CLAUDE_CONFIG_DIR']) {
+    return claudeReticleEntries(io, undefined, configDir).some((e) => isFloatingNpx(entryTokens(e)));
+}
+/** The one sentence about a floating entry, and the commands that replace it. */
+export function claudeStaleEntryNote(launcher) {
+    return (`the user-scope reticle entry runs \`${NPX} ${RETICLE_PACKAGE}\` with no version, so it can ` +
+        `start a different Reticle version. Run: ${claudeRemoveUserCommand()}, then ` +
+        claudeAddCommand(launcher).display);
 }
 /** Probe args for whether the `claude` CLI is installed at all. */
 export function claudeAvailableProbe() {
@@ -148,8 +238,8 @@ export function claudeAvailableProbe() {
  * It REPLACES an existing entry of the same name and still exits 0, so callers run it only when the
  * config names no `reticle` server at all (see `codexNamesOurServer`).
  */
-export function codexAddCommand() {
-    const args = [MCP_SUBCOMMAND, 'add', MCP_SERVER_NAME, '--', ...serverInvocation()];
+export function codexAddCommand(launcher) {
+    const args = [MCP_SUBCOMMAND, 'add', MCP_SERVER_NAME, '--', ...serverInvocation(launcher)];
     return { command: CODEX_CLI, args, display: `${CODEX_CLI} ${args.join(' ')}` };
 }
 /** Probe args for whether the `codex` CLI is installed at all. */
@@ -166,7 +256,7 @@ export function mcpWindowsNote() {
 on this system" — a PowerShell execution policy), register it through cmd instead, which that policy
 does not gate:
 
-  "${MCP_SERVER_NAME}": { "command": "${WINDOWS_SHELL}", "args": ${JSON.stringify([WINDOWS_SHELL_C, NPX, ...serverInvocation().slice(1)])} }`;
+  "${MCP_SERVER_NAME}": { "command": "${WINDOWS_SHELL}", "args": ${JSON.stringify([WINDOWS_SHELL_C, NPX, ...npxServerArgs()])} }`;
 }
 /** Printed when the `claude` CLI isn't available — register Reticle globally once, by hand. */
 /**
@@ -176,23 +266,24 @@ does not gate:
  * session the `claude` binary is not on PATH, so every CLI-based route is shut and `.mcp.json` in
  * the project root is the one that still works.
  */
-export function claudeProjectMcpJson() {
-    const [command, ...args] = serverInvocation();
+export function claudeProjectMcpJson(launcher) {
+    const [command, ...args] = serverInvocation(launcher);
     return `${CLAUDE_PROJECT_CONFIG} (project root):
 
   { "mcpServers": { "${MCP_SERVER_NAME}": { "command": "${command ?? NPX}", "args": ${JSON.stringify(args)} } } }`;
 }
-export function mcpManual() {
-    const tail = serverInvocation().join(' ');
+export function mcpManual(launcher) {
+    const [command, ...args] = serverInvocation(launcher);
+    const tail = [command, ...args].join(' ');
     return `Register the Reticle MCP server ONCE, globally (so every project gets it):
 
   ${CLAUDE_CLI} ${MCP_SUBCOMMAND} add ${MCP_SERVER_NAME} -s user -- ${tail}
 
-Or, in Claude Code with no \`claude\` on PATH (a VS Code extension session), write ${claudeProjectMcpJson()}
+Or, in Claude Code with no \`claude\` on PATH (a VS Code extension session), write ${claudeProjectMcpJson(launcher)}
 
 Or, for another agent, add this to its global MCP config (e.g. Cursor's ~/.cursor/mcp.json):
 
-  "${MCP_SERVER_NAME}": { "command": "${NPX}", "args": ${JSON.stringify(serverInvocation().slice(1))} }
+  "${MCP_SERVER_NAME}": { "command": "${command ?? NPX}", "args": ${JSON.stringify(args)} }
 
 ${mcpWindowsNote()}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reticlehq/init",
-  "version": "3.8.1",
+  "version": "3.9.0",
   "description": "Reticle project scaffolder — detects the framework, writes the config, patches the build and registers the MCP server. The build-time half of `reticle init`.",
   "type": "module",
   "main": "./dist/index.js",
@@ -13,9 +13,9 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@reticlehq/core": "3.8.1"
+    "@reticlehq/core": "3.9.0"
   },
-  "license": "FSL-1.1-ALv2",
+  "license": "Apache-2.0",
   "author": "Reticle contributors",
   "repository": {
     "type": "git",
@@ -27,7 +27,8 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "NOTICE"
   ],
   "sideEffects": false,
   "keywords": [