@stigmer/cli 3.18.1-dev.20260919070736 → 3.19.1-dev.20260920100552

package/src/local/bootstrap.test.ts

@@ -1,9 +1,7 @@
-// Pins the local bootstrap's shape: prepare, then run, then retire, over one
-// client; a preparation failure skips the run and the retire together, and a
-// run that cannot start skips the retire (nothing is deleted before its
-// replacement is in place); a default that failed to land is one warning
-// naming `stigmer bootstrap` and holds the retire back with a line saying so;
-// a retire failure is contained by its own warning; nothing throws past the
+// Pins the local bootstrap's shape: prepare, then run, over one client; a
+// preparation failure skips the run with one warning naming the retry; a
+// run that cannot start is one warning; a default that failed to land is one
+// warning per default naming `stigmer bootstrap`; nothing throws past the
 // bootstrap.
 
 import { describe, expect, it } from "vitest";
@@ -24,9 +22,9 @@ function converged(): BootstrapResult {
 }
 
 describe("bootstrapLocalBackend", () => {
-  it("prepares, runs, then retires, over the same client and home", async () => {
+  it("prepares, then runs, over the same client", async () => {
     const order: string[] = [];
-    await bootstrapLocalBackend("/home/x", {
+    await bootstrapLocalBackend({
       client,
       say: () => {},
       prepare: async () => {
@@ -39,20 +37,14 @@ describe("bootstrapLocalBackend", () => {
         order.push("run");
         return converged();
       },
-      retire: async (s, home) => {
-        expect(s).toBe(stigmer);
-        expect(home).toBe("/home/x");
-        order.push("retire");
-      },
     });
-    expect(order).toEqual(["prepare", "run", "retire"]);
+    expect(order).toEqual(["prepare", "run"]);
   });
 
-  it("skips the run and the retire when preparation fails, with one warning", async () => {
+  it("skips the run when preparation fails, with one warning", async () => {
     const said: string[] = [];
-    let retired = 0;
     let ran = 0;
-    await bootstrapLocalBackend("/home/x", {
+    await bootstrapLocalBackend({
       client,
       say: (line) => said.push(line),
       prepare: async () => {
@@ -62,41 +54,31 @@ describe("bootstrapLocalBackend", () => {
         ran += 1;
         return converged();
       },
-      retire: async () => {
-        retired += 1;
-      },
     });
     expect(ran).toBe(0);
-    expect(retired).toBe(0);
     expect(said).toEqual([
-      "Warning: could not prepare the default plugins, so the local backend was not bootstrapped and nothing was retired. Run 'stigmer up' again to retry.",
+      "Warning: could not prepare the default plugins, so the local backend was not bootstrapped. Run 'stigmer up' again to retry.",
     ]);
   });
 
-  it("skips the retire when the run cannot even start, with one warning naming the retry", async () => {
+  it("contains a run that cannot start in one warning naming the retry", async () => {
     const said: string[] = [];
-    let retired = 0;
-    await bootstrapLocalBackend("/home/x", {
+    await bootstrapLocalBackend({
       client,
       say: (line) => said.push(line),
       prepare: async () => prepared,
       run: async () => {
         throw new Error("backend unreachable");
       },
-      retire: async () => {
-        retired += 1;
-      },
     });
-    expect(retired).toBe(0);
     expect(said).toEqual([
-      "Warning: failed to bootstrap the local backend, so nothing was retired. Run 'stigmer up' again to retry.",
+      "Warning: failed to bootstrap the local backend. Run 'stigmer up' again to retry.",
     ]);
   });
 
-  it("holds the retire back when a default did not land, naming the default and saying why", async () => {
+  it("names each default that did not land and the verb that retries it", async () => {
     const said: string[] = [];
-    let retired = 0;
-    await bootstrapLocalBackend("/home/x", {
+    await bootstrapLocalBackend({
       client,
       say: (line) => said.push(line),
       prepare: async () => prepared,
@@ -109,35 +91,9 @@ describe("bootstrapLocalBackend", () => {
           failed: ["assistant"],
         },
       }),
-      retire: async () => {
-        retired += 1;
-      },
     });
-    expect(retired).toBe(0);
     expect(said).toEqual([
       "Warning: failed to install default plugin 'assistant'. Run 'stigmer bootstrap' to retry.",
-      "Nothing was retired: the resources an older release installed stay until every default plugin is in place.",
-    ]);
-  });
-
-  it("contains a retire that threw in one warning, after the run succeeded", async () => {
-    const said: string[] = [];
-    let ran = 0;
-    await bootstrapLocalBackend("/home/x", {
-      client,
-      say: (line) => said.push(line),
-      prepare: async () => prepared,
-      run: async () => {
-        ran += 1;
-        return converged();
-      },
-      retire: async () => {
-        throw new Error("project read failed");
-      },
-    });
-    expect(ran).toBe(1);
-    expect(said).toEqual([
-      "Warning: failed to retire the resources an older release installed. Run 'stigmer up' again to retry.",
     ]);
   });
 });

package/src/local/bootstrap.ts

@@ -6,29 +6,20 @@
 // lane. One definition, so a laptop, a container and the hosted platform
 // cannot drift in what "ready" means.
 //
-// Two phases, and the order matters (a third, `up`'s retire, follows them):
+// Two phases, and the order matters:
 //
 //   1. prepare: resolve the official marketplace (acquiring `@stigmer/plugins`
 //      at the CLI's version on a release's first run) and prepare every
 //      default. No backend is touched.
 //   2. run: ensure the system org, then push the prepared defaults, each
-//      skipped when the backend already holds it at the same digest.
+//      skipped when the backend already holds it at the same digest. The
+//      push adopts a system-content row it replaces in place (a default
+//      agent an earlier release seeded keeps its id, its instances and every
+//      conversation bound to them), so nothing here ever deletes a row.
 //
-// `stigmer up` adds a third phase after them: retiring the seedpack an
-// older release installed. That step deletes rows, so it runs only once
-// every default has LANDED, not merely been prepared: the plugin push adopts
-// the system-content rows it replaces in place (the seedpack's `assistant`
-// keeps its id, its instances and every conversation bound to them), and a
-// row that is now a plugin's member is never a candidate for the retire. A
-// user who upgrades offline and cannot fetch the new catalogue, or whose
-// backend refused a default, keeps the old rows for another day instead of
-// losing them and getting nothing back. The retire lives here and not in
-// `stigmer bootstrap` on purpose: a verb a scheduled lane runs against the
-// platform must never be able to delete rows.
-//
-// Inside `up` every phase is best-effort with its own warning naming the
-// retry, because the stack is already serving by the time any of them runs
-// and a seeding failure must never tear it down. Both `up` shapes (detached
+// Inside `up` both phases are best-effort with their own warning naming the
+// retry, because the stack is already serving by the time either runs and a
+// seeding failure must never tear it down. Both `up` shapes (detached
 // and foreground) call this one function, and both seed the local server
 // `up` just started, never the active backend context: a CLI pointed at
 // cloud still gets its local stack seeded, and never has system resources
@@ -44,7 +35,6 @@ import type {
   InstallingVerb,
   PreparedDefault,
 } from "./plugins/defaults.js";
-import { dataDir } from "./paths.js";
 import { type EnsureSystemOrgOutcome, SYSTEM_ORG } from "./system-org.js";
 
 export type Say = (line: string) => void;
@@ -116,7 +106,6 @@ export interface BootstrapDeps {
   readonly client?: BackendClient;
   readonly say?: Say;
   readonly prepare?: () => Promise<PreparedBootstrap>;
-  readonly retire?: (stigmer: Stigmer, home: string, say: Say) => Promise<void>;
   readonly run?: (
     stigmer: Stigmer,
     prepared: PreparedBootstrap,
@@ -130,7 +119,6 @@ const sayToStderr: Say = (line) => {
 
 /** What `stigmer up` does once the local server answers. Never throws past its own warnings. */
 export async function bootstrapLocalBackend(
-  home: string,
   deps: BootstrapDeps = {},
 ): Promise<void> {
   const client = deps.client ?? (await freshLocalClient());
@@ -142,7 +130,7 @@ export async function bootstrapLocalBackend(
   } catch (err) {
     log.warn("bootstrap preparation failed", { error: String(err) });
     say(
-      "Warning: could not prepare the default plugins, so the local backend was not bootstrapped and nothing was retired. Run 'stigmer up' again to retry.",
+      "Warning: could not prepare the default plugins, so the local backend was not bootstrapped. Run 'stigmer up' again to retry.",
     );
     return;
   }
@@ -157,7 +145,7 @@ export async function bootstrapLocalBackend(
   } catch (err) {
     log.warn("bootstrap failed", { error: String(err) });
     say(
-      "Warning: failed to bootstrap the local backend, so nothing was retired. Run 'stigmer up' again to retry.",
+      "Warning: failed to bootstrap the local backend. Run 'stigmer up' again to retry.",
     );
     return;
   }
@@ -165,24 +153,9 @@ export async function bootstrapLocalBackend(
     org: result.org,
     outcomes: result.plugins.outcomes,
   });
-  if (result.plugins.failed.length > 0) {
-    for (const name of result.plugins.failed) {
-      say(
-        `Warning: failed to install default plugin '${name}'. Run 'stigmer bootstrap' to retry.`,
-      );
-    }
-    say(
-      "Nothing was retired: the resources an older release installed stay until every default plugin is in place.",
-    );
-    return;
-  }
-
-  try {
-    await (deps.retire ?? retireSeedpack)(client.stigmer, home, say);
-  } catch (err) {
-    log.warn("seedpack retire failed", { error: String(err) });
+  for (const name of result.plugins.failed) {
     say(
-      "Warning: failed to retire the resources an older release installed. Run 'stigmer up' again to retry.",
+      `Warning: failed to install default plugin '${name}'. Run 'stigmer bootstrap' to retry.`,
     );
   }
 }
@@ -197,20 +170,6 @@ function runLocalBootstrap(
   return runBootstrap(stigmer, prepared, say, "stigmer up");
 }
 
-// The retire step in the shape the seam expects; the module is loaded only
-// inside `up`, the one place a retire may run.
-async function retireSeedpack(
-  stigmer: Stigmer,
-  home: string,
-  say: Say,
-): Promise<void> {
-  const { retireSeedpack: retire, renderRetireReport } = await import(
-    "./seedpack-retire.js"
-  );
-  const result = await retire(stigmer, { markerDir: dataDir(home) });
-  renderRetireReport(result, say);
-}
-
 async function freshLocalClient(): Promise<BackendClient> {
   const [{ createBackendClient }, { getDefault }] = await Promise.all([
     import("../client/index.js"),

package/src/local/daemon/launch.ts

@@ -72,7 +72,7 @@ export async function up(options: UpOptions = {}, home: string = homedir()): Pro
 
   await waitForTcp({ port: SERVER_PORT, timeoutMs: READY_TIMEOUT_MS, label: "stigmer-server" });
 
-  await bootstrapLocalBackend(home);
+  await bootstrapLocalBackend();
 
   saveStartupConfig(data, buildStartupConfig(data, logs, temporalAddress, daemonPid, options));
 }
@@ -83,8 +83,8 @@ export interface UpForegroundDeps {
   runDaemon?: (deps: InternalDaemonDeps) => Promise<number>;
   /** Resolves when the stack should shut down (default: the first SIGTERM/SIGINT). */
   waitForShutdown?: () => Promise<void>;
-  /** Post-readiness bootstrap (default: `bootstrapLocalBackend`: prepare the defaults, retire an older release's seedpack, ensure the org, install). */
-  bootstrap?: (home: string) => Promise<void>;
+  /** Post-readiness bootstrap (default: `bootstrapLocalBackend`: prepare the defaults, ensure the org, install). */
+  bootstrap?: () => Promise<void>;
   /** Receives each line the server and runner write (default: a `[component]`-prefixed stdout mirror). */
   mirror?: OutputMirror;
   /** Invoked once the stack is serving and seeded — the moment a detached `up` would have returned. */
@@ -118,7 +118,7 @@ export async function upForeground(
     host: new NodeProcessHost({ mirror: deps.mirror ?? mirrorToStdout }),
     waitForShutdown: deps.waitForShutdown ?? waitForShutdownSignal,
     onStarted: async () => {
-      await bootstrap(home);
+      await bootstrap();
       saveStartupConfig(data, buildStartupConfig(data, logs, temporalAddress, process.pid, options));
       await deps.onReady?.();
     },

package/src/local/plugins/defaults.test.ts

@@ -49,8 +49,8 @@ let pushes: PushPluginRequest[];
 let refusing: Set<string>;
 
 let official: string;
-let thermosDigest: string;
-let githubDigest: string;
+let warmerDigest: string;
+let codeforgeDigest: string;
 
 function pluginRow(
   slug: string,
@@ -75,15 +75,15 @@ beforeAll(async () => {
     JSON.stringify({
       name: "stigmer",
       plugins: [
-        { name: "thermos", source: "./thermos" },
-        { name: "github", source: "./third_party/github" },
+        { name: "warmer", source: "./warmer" },
+        { name: "codeforge", source: "./third_party/codeforge" },
       ],
-      defaults: ["thermos", "github"],
+      defaults: ["warmer", "codeforge"],
     }),
   );
-  thermosDigest = (await preparePluginPush(join(official, "thermos"))).digest;
-  githubDigest = (
-    await preparePluginPush(join(official, "third_party", "github"))
+  warmerDigest = (await preparePluginPush(join(official, "warmer"))).digest;
+  codeforgeDigest = (
+    await preparePluginPush(join(official, "third_party", "codeforge"))
   ).digest;
 
   const routes = (router: ConnectRouter) => {
@@ -92,7 +92,7 @@ beforeAll(async () => {
         pushes.push(req);
         // The archive names the plugin: the backend knows the two trees by their digests.
         const slug =
-          digestOf(req.artifact) === thermosDigest ? "thermos" : "github";
+          digestOf(req.artifact) === warmerDigest ? "warmer" : "codeforge";
         if (refusing.has(slug))
           throw new ConnectError(`refused ${slug}`, Code.FailedPrecondition);
         const row = pluginRow(
@@ -159,8 +159,8 @@ describe("prepareDefaultPlugins", () => {
   it("prepares every default in the marketplace's order without touching the backend", async () => {
     const prepared = await prepareDefaultPlugins({ repoDir: () => official });
     expect(prepared.map((entry) => [entry.name, entry.push.digest])).toEqual([
-      ["thermos", thermosDigest],
-      ["github", githubDigest],
+      ["warmer", warmerDigest],
+      ["codeforge", codeforgeDigest],
     ]);
     expect(pushes).toHaveLength(0);
   });
@@ -189,8 +189,8 @@ describe("installPreparedDefaults", () => {
   it("installs every default in order, public, with the invoking verb in the message, on a fresh backend", async () => {
     const result = await run();
     expect(result.outcomes.map((o) => [o.name, o.action])).toEqual([
-      ["thermos", "installed"],
-      ["github", "installed"],
+      ["warmer", "installed"],
+      ["codeforge", "installed"],
     ]);
     expect(result.failed).toEqual([]);
     expect(pushes.map((p) => p.org)).toEqual(["stigmer", "stigmer"]);
@@ -202,13 +202,13 @@ describe("installPreparedDefaults", () => {
     expect(pushes[0]?.message).toMatch(
       /^default plugin, installed by stigmer bootstrap \(/,
     );
-    expect(digestOf(pushes[0]!.artifact)).toBe(thermosDigest);
-    expect(digestOf(pushes[1]!.artifact)).toBe(githubDigest);
+    expect(digestOf(pushes[0]!.artifact)).toBe(warmerDigest);
+    expect(digestOf(pushes[1]!.artifact)).toBe(codeforgeDigest);
   });
 
   it("pushes nothing when every default is already held at the same digest, READY and public", async () => {
-    held.set("thermos", pluginRow("thermos", thermosDigest));
-    held.set("github", pluginRow("github", githubDigest));
+    held.set("warmer", pluginRow("warmer", warmerDigest));
+    held.set("codeforge", pluginRow("codeforge", codeforgeDigest));
     const result = await run();
     expect(result.outcomes.map((o) => o.action)).toEqual([
       "up-to-date",
@@ -218,8 +218,8 @@ describe("installPreparedDefaults", () => {
   });
 
   it("pushes again on a changed digest, a non-READY state, or a non-public visibility", async () => {
-    held.set("thermos", pluginRow("thermos", "f".repeat(64)));
-    held.set("github", pluginRow("github", githubDigest, PluginState.FAILED));
+    held.set("warmer", pluginRow("warmer", "f".repeat(64)));
+    held.set("codeforge", pluginRow("codeforge", codeforgeDigest, PluginState.FAILED));
     expect((await run()).outcomes.map((o) => o.action)).toEqual([
       "installed",
       "installed",
@@ -228,15 +228,15 @@ describe("installPreparedDefaults", () => {
 
     pushes = [];
     held.set(
-      "thermos",
+      "warmer",
       pluginRow(
-        "thermos",
-        thermosDigest,
+        "warmer",
+        warmerDigest,
         PluginState.READY,
         ApiResourceVisibility.visibility_private,
       ),
     );
-    held.set("github", pluginRow("github", githubDigest));
+    held.set("codeforge", pluginRow("codeforge", codeforgeDigest));
     expect((await run()).outcomes.map((o) => o.action)).toEqual([
       "installed",
       "up-to-date",
@@ -256,16 +256,16 @@ describe("installPreparedDefaults", () => {
   });
 
   it("one default failing does not stop the next, and the failure is named", async () => {
-    refusing.add("thermos");
+    refusing.add("warmer");
     const result = await run();
     expect(result.outcomes.map((o) => [o.name, o.action])).toEqual([
-      ["thermos", "failed"],
-      ["github", "installed"],
+      ["warmer", "failed"],
+      ["codeforge", "installed"],
     ]);
-    expect(result.failed).toEqual(["thermos"]);
+    expect(result.failed).toEqual(["warmer"]);
     const failed = result.outcomes[0];
     expect(failed?.action === "failed" && failed.error).toMatch(
-      /refused thermos/,
+      /refused warmer/,
     );
   });
 });

package/src/local/plugins/defaults.ts

@@ -10,8 +10,8 @@
 // release defect, not a condition to install around. Installing pushes the
 // prepared archives and is best-effort per entry: one default failing to
 // land does not stop the next, and the caller decides how to surface the
-// failures. The split lets `stigmer up` hold every replacement in hand
-// before it retires what the replacement supersedes (local/bootstrap.ts).
+// failures. The split keeps every network read (the catalogue, the
+// archives) ahead of the first write to the backend (local/bootstrap.ts).
 //
 // Idempotent by the server's own identity, not a marker file: before each
 // push the org's plugin of that name is read back; when its digest equals the

package/src/marketplace/__fixtures__/cursor-marketplace.ts

@@ -4,7 +4,11 @@
 // is missing, so every suite sees an offered list and a dropped entry. It
 // names itself `acme-plugins`: the vendors' own names are built into every
 // client, so a fixture under one of them would meet the reserved-name
-// refusal instead of being added.
+// refusal instead of being added. Its plugins carry names no real catalogue
+// offers (`warmer`, `codeforge`): a bare-name install searches the official
+// catalogue too, which in a checkout is the live `plugins/` tree, and a
+// fixture named after a real plugin would collide with it as the catalogue
+// grows.
 
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -24,41 +28,41 @@ export function writeCursorMarketplace(root: string): void {
       metadata: { description: "A test catalogue" },
       plugins: [
         {
-          name: "thermos",
-          source: "thermos",
+          name: "warmer",
+          source: "warmer",
           description: "Keeps things warm.",
         },
-        { name: "github", source: "third_party/github" },
+        { name: "codeforge", source: "third_party/codeforge" },
         { name: "ghost", source: "ghost", description: "Listed, not present." },
       ],
     }),
   );
   write(
-    "thermos/.cursor-plugin/plugin.json",
+    "warmer/.cursor-plugin/plugin.json",
     JSON.stringify({
-      name: "thermos",
+      name: "warmer",
       version: "1.0.0",
-      description: "The thermos plugin.",
+      description: "The warmer plugin.",
       skills: "./skills/",
     }),
   );
   write(
-    "thermos/skills/warm/SKILL.md",
+    "warmer/skills/warm/SKILL.md",
     "---\nname: warm\ndescription: Warms.\n---\nKeep it warm.\n",
   );
   write(
-    "third_party/github/.cursor-plugin/plugin.json",
+    "third_party/codeforge/.cursor-plugin/plugin.json",
     JSON.stringify({
-      name: "github",
+      name: "codeforge",
       version: "2.1.0",
       mcpServers: "./mcp.json",
     }),
   );
   write(
-    "third_party/github/mcp.json",
+    "third_party/codeforge/mcp.json",
     JSON.stringify({
       mcpServers: {
-        github: { type: "http", url: "https://api.githubcopilot.com/mcp/" },
+        codeforge: { type: "http", url: "https://api.githubcopilot.com/mcp/" },
       },
     }),
   );

package/src/marketplace/config.test.ts

@@ -48,26 +48,18 @@ function writeConfig(yaml: string): void {
   writeFileSync(configPath(), yaml);
 }
 
-const BUILT_IN_NAMES = [
-  OFFICIAL_MARKETPLACE_NAME,
-  "cursor-plugins",
-  "claude-code-plugins",
-  "codex-plugins",
-];
+const BUILT_IN_NAMES = [OFFICIAL_MARKETPLACE_NAME];
 
 describe("listMarketplaces", () => {
-  it("is the built-in sources alone on a fresh machine, the official one first", () => {
+  it("is the built-in source alone on a fresh machine, the official catalogue", () => {
     const listing = listMarketplaces();
     expect(listing.known.map((m) => m.name)).toEqual(BUILT_IN_NAMES);
     expect(listing.known[0]?.source).toEqual({ type: "official" });
-    expect(listing.known[1]?.source).toEqual({
-      type: "github",
-      repo: "cursor/plugins",
-    });
+    expect(listing.known).toHaveLength(1);
     expect(listing.unreadable).toEqual([]);
   });
 
-  it("lists configured entries after the built-ins, in file order, names the unreadable ones, and lets a built-in win over a same-named entry", () => {
+  it("lists configured entries after the built-in, in file order, names the unreadable ones, and lets the built-in win over a same-named entry", () => {
     writeConfig(
       [
         "backend:",
@@ -76,8 +68,8 @@ describe("listMarketplaces", () => {
         "  acme:",
         "    type: github",
         "    repo: acme/plugins",
-        // Written before the vendors were built in: the built-in wins, the entry stays in the file.
-        "  cursor-plugins:",
+        // A hand edit under the built-in's name: the built-in wins, the entry stays in the file.
+        "  stigmer:",
         "    type: github",
         "    repo: someone/fork",
         "  pinned:",
@@ -102,23 +94,20 @@ describe("listMarketplaces", () => {
       "pinned",
       "team",
     ]);
-    expect(listing.known[4]?.source).toEqual({
+    expect(listing.known[0]?.source).toEqual({ type: "official" });
+    expect(listing.known[1]?.source).toEqual({
       type: "github",
       repo: "acme/plugins",
     });
-    expect(listing.known[5]?.source).toEqual({
+    expect(listing.known[2]?.source).toEqual({
       type: "github",
       repo: "anthropics/claude-code",
       ref: "v1.2.3",
     });
-    expect(listing.known[6]?.source).toEqual({
+    expect(listing.known[3]?.source).toEqual({
       type: "local",
       path: "/srv/plugins",
     });
-    expect(listing.known[1]?.source).toEqual({
-      type: "github",
-      repo: "cursor/plugins",
-    });
     expect(listing.unreadable).toEqual([
       {
         name: "broken",
@@ -173,13 +162,11 @@ describe("addMarketplace and removeMarketplace", () => {
     });
   });
 
-  it("refuses every built-in name, a duplicate, an unknown removal, and a built-in removal", () => {
+  it("refuses the built-in name, a duplicate, an unknown removal, and the built-in's removal; a vendor's name is free", () => {
     expect(() =>
       addMarketplace("stigmer", { type: "local", path: "/x" }),
     ).toThrow(/'stigmer' is a built-in source and cannot be added or replaced/);
-    expect(() =>
-      addMarketplace("cursor-plugins", { type: "local", path: "/x" }),
-    ).toThrow(/'cursor-plugins' is a built-in source/);
+    addMarketplace("cursor-plugins", { type: "github", repo: "cursor/plugins" });
     addMarketplace("team", { type: "local", path: "/srv/plugins" });
     expect(() =>
       addMarketplace("team", { type: "local", path: "/other" }),
@@ -190,9 +177,6 @@ describe("addMarketplace and removeMarketplace", () => {
     expect(() => removeMarketplace("stigmer")).toThrow(
       /'stigmer' is a built-in source and cannot be removed/,
     );
-    expect(() => removeMarketplace("codex-plugins")).toThrow(
-      /'codex-plugins' is a built-in source and cannot be removed/,
-    );
   });
 
   it("refuses under --standalone instead of writing a default file over the user's", () => {

package/src/marketplace/config.ts

@@ -1,14 +1,17 @@
-// The sources a CLI knows: the built-in ones (the official catalogue and the
-// three vendors' public ones, the same list the console ships), and the ones
-// a user added under the `marketplaces` key of ~/.stigmer/config.yaml.
+// The sources a CLI knows: the built-in one (the official catalogue, the same
+// list the console ships) and the ones a user added under the `marketplaces`
+// key of ~/.stigmer/config.yaml.
 //
 // A source is client-side configuration, never a server resource: the
 // server only ever sees the plugin archive a client pushes. That is why the
 // list lives beside the named backends and the context, and why `stigmer
-// marketplace` is a noun group like `config` and `auth`. The built-ins are
-// code, not config: they cannot be added over or removed, so `stigmer
-// install cursor-plugins/thermos` works on a fresh machine and the CLI's
-// list never drifts from the console's.
+// marketplace` is a noun group like `config` and `auth`. The built-in is
+// code, not config: it cannot be added over or removed, so `stigmer install
+// assistant` works on a fresh machine and the CLI's list never drifts from
+// the console's. A vendor's public repository is a source the user adds by
+// name (`stigmer marketplace add cursor/plugins`), never one on offer by
+// default: the official catalogue already carries what Stigmer can offer of
+// it, curated (`plugins/README.md`).
 //
 // The config module keeps the on-disk entry loose (`MarketplaceEntryConfig`,
 // every field optional) so a hand-edited entry this CLI cannot read survives
@@ -82,8 +85,9 @@ export function listMarketplaces(
   const known: KnownMarketplace[] = [...BUILT_IN_SOURCES];
   const unreadable: UnreadableMarketplace[] = [];
   for (const [name, entry] of Object.entries(config.marketplaces ?? {})) {
-    // A config written before the vendors were built in may name one; the
-    // built-in wins and the entry is left in the file untouched.
+    // A config may name the built-in (a hand edit, or a file written by a
+    // CLI whose built-ins differed); the built-in wins and the entry is left
+    // in the file untouched.
     if (isBuiltInMarketplaceName(name)) continue;
     const narrowed = narrowEntry(entry);
     if (narrowed.ok) known.push({ name, source: narrowed.source });