From f70d77b0bd681283b9def19b8b127749d6b6fa8a Mon Sep 17 00:00:00 2001
From: Vincent Koc <vincentkoc@ieee.org>
Date: Sat, 25 Apr 2026 04:48:18 -0700
Subject: [PATCH] docs(plugins): clarify registry-derived relocations

---
 src/cli/plugins-location-bridges.ts | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/src/cli/plugins-location-bridges.ts b/src/cli/plugins-location-bridges.ts
index 5a173bb3cd9..9b569c1e8d2 100644
--- a/src/cli/plugins-location-bridges.ts
+++ b/src/cli/plugins-location-bridges.ts
@@ -5,6 +5,9 @@ import type { InstalledPluginIndexRecord } from "../plugins/installed-plugin-ind
 function buildBridgeFromPersistedBundledRecord(
   record: InstalledPluginIndexRecord,
 ): ExternalizedBundledPluginBridge | null {
+  // Relocation is derived from the previous persisted registry, not a hardcoded
+  // table. A plugin moving from bundled to npm keeps the same plugin id; the old
+  // registry row is the proof that this user actually had it bundled/enabled.
   if (record.origin !== "bundled" || record.enabled === false) {
     return null;
   }
@@ -24,6 +27,9 @@ export async function listPersistedBundledPluginLocationBridges(options: {
   workspaceDir?: string;
   env?: NodeJS.ProcessEnv;
 }): Promise<readonly ExternalizedBundledPluginBridge[]> {
+  // This intentionally reads the pre-update registry. The current build may no
+  // longer contain the bundled plugin, so normal discovery cannot recover its
+  // package install hint.
   const index = await readPersistedInstalledPluginIndex(options);
   if (!index) {
     return [];