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

package/src/marketplace/install.test.ts

@@ -33,9 +33,9 @@ afterAll(() => {
 describe("prepareEntry", () => {
   it("prepares an offered entry exactly as push plugin would prepare its directory", async () => {
     const tree = readMarketplaceTree(root);
-    const viaMarketplace = await prepareEntry(tree, "github");
-    const viaFolder = await preparePluginPush(join(root, "third_party", "github"));
-    expect(viaMarketplace.plugin.name).toBe("github");
+    const viaMarketplace = await prepareEntry(tree, "codeforge");
+    const viaFolder = await preparePluginPush(join(root, "third_party", "codeforge"));
+    expect(viaMarketplace.plugin.name).toBe("codeforge");
     expect(viaMarketplace.digest).toBe(viaFolder.digest);
     expect(
       Buffer.from(viaMarketplace.archive).equals(
@@ -57,15 +57,15 @@ describe("prepareEntry", () => {
 
 describe("assertVersion", () => {
   it("passes without a pin or with the offered version, refuses another naming the offered one", async () => {
-    const prepared = await prepareEntry(readMarketplaceTree(root), "thermos");
-    expect(() => assertVersion(prepared, undefined, "thermos")).not.toThrow();
+    const prepared = await prepareEntry(readMarketplaceTree(root), "warmer");
+    expect(() => assertVersion(prepared, undefined, "warmer")).not.toThrow();
     expect(() =>
-      assertVersion(prepared, "1.0.0", "thermos@1.0.0"),
+      assertVersion(prepared, "1.0.0", "warmer@1.0.0"),
     ).not.toThrow();
     expect(() =>
-      assertVersion(prepared, "9.9.9", "acme-plugins/thermos@9.9.9"),
+      assertVersion(prepared, "9.9.9", "acme-plugins/warmer@9.9.9"),
     ).toThrow(
-      /pins version 9\.9\.9, but the marketplace offers 'thermos' at 1\.0\.0\n\nInstall it as 'acme-plugins\/thermos@1\.0\.0'/,
+      /pins version 9\.9\.9, but the marketplace offers 'warmer' at 1\.0\.0\n\nInstall it as 'acme-plugins\/warmer@1\.0\.0'/,
     );
   });
 });
@@ -104,10 +104,10 @@ describe("locateEntry", () => {
   const remoteFiles = {
     "marketplace.json": JSON.stringify({
       name: "remote",
-      plugins: [{ name: "thermos", source: "./thermos" }],
+      plugins: [{ name: "warmer", source: "./warmer" }],
     }),
-    "thermos/plugin.json": JSON.stringify({
-      name: "thermos",
+    "warmer/plugin.json": JSON.stringify({
+      name: "warmer",
       version: "3.0.0",
     }),
   };
@@ -122,7 +122,7 @@ describe("locateEntry", () => {
       source: { type: "local", path: root } as const,
     };
     const located = await locateEntry(
-      parseInstallRef("acme-plugins/thermos"),
+      parseInstallRef("acme-plugins/warmer"),
       listing(local),
     );
     try {
@@ -132,7 +132,7 @@ describe("locateEntry", () => {
       located.open.dispose();
     }
     await expect(
-      locateEntry(parseInstallRef("nowhere/thermos"), listing(local)),
+      locateEntry(parseInstallRef("nowhere/warmer"), listing(local)),
     ).rejects.toThrow(/no marketplace named 'nowhere' is configured/);
   });
 
@@ -142,7 +142,7 @@ describe("locateEntry", () => {
       source: { type: "local", path: root } as const,
     };
     const located = await locateEntry(
-      parseInstallRef("github"),
+      parseInstallRef("codeforge"),
       listing(local),
     );
     try {
@@ -178,11 +178,11 @@ describe("locateEntry", () => {
     };
     const before = countTempTrees();
     await expect(
-      locateEntry(parseInstallRef("thermos"), listing(local, remote), {
+      locateEntry(parseInstallRef("warmer"), listing(local, remote), {
         fetchImpl: servingZipOf(remoteFiles),
       }),
     ).rejects.toThrow(
-      /offered by more than one marketplace: acme-plugins, remote\n\nName the one you mean: acme-plugins\/thermos or remote\/thermos/,
+      /offered by more than one marketplace: acme-plugins, remote\n\nName the one you mean: acme-plugins\/warmer or remote\/warmer/,
     );
     expect(countTempTrees()).toBe(before);
   });
@@ -197,8 +197,8 @@ describe("locateEntry", () => {
       source: { type: "github", repo: "a/b" } as const,
     };
     const requests: string[] = [];
-    // `github` is offered by the local fixture alone: the remote is peeked, not downloaded.
-    const located = await locateEntry(parseInstallRef("github"), listing(local, remote), {
+    // `codeforge` is offered by the local fixture alone: the remote is peeked, not downloaded.
+    const located = await locateEntry(parseInstallRef("codeforge"), listing(local, remote), {
       fetchImpl: servingZipOf(remoteFiles, "r-HEAD", requests),
     });
     located.open.dispose();
@@ -241,7 +241,7 @@ describe("locateEntry", () => {
       source: { type: "github", repo: "a/b" } as const,
     };
     const located = await locateEntry(
-      parseInstallRef("remote/thermos"),
+      parseInstallRef("remote/warmer"),
       listing(remote),
       {
         fetchImpl: servingZipOf(remoteFiles),

package/src/marketplace/read.test.ts

@@ -27,8 +27,8 @@ describe("readMarketplaceTree", () => {
     expect(tree.marketplace.name).toBe("acme-plugins");
     expect(tree.marketplace.dialect).toBe("cursor");
     expect(tree.marketplace.plugins.map((entry) => entry.name)).toEqual([
-      "thermos",
-      "github",
+      "warmer",
+      "codeforge",
     ]);
     expect(tree.warnings).toHaveLength(1);
     expect(tree.warnings[0]?.kind).toBe("entry-directory-missing");
@@ -71,10 +71,10 @@ describe("readMarketplaceTree", () => {
 describe("findEntry and entryDirectory", () => {
   it("resolves an offered entry to its absolute directory and an unknown name to undefined", () => {
     const tree = readMarketplaceTree(root);
-    const github = findEntry(tree.marketplace, "github");
-    expect(github?.dir).toBe("third_party/github");
-    expect(entryDirectory(tree, github!)).toBe(
-      join(root, "third_party", "github"),
+    const codeforge = findEntry(tree.marketplace, "codeforge");
+    expect(codeforge?.dir).toBe("third_party/codeforge");
+    expect(entryDirectory(tree, codeforge!)).toBe(
+      join(root, "third_party", "codeforge"),
     );
     expect(findEntry(tree.marketplace, "ghost")).toBeUndefined();
   });

package/src/marketplace/render.ts

@@ -5,7 +5,6 @@
 // same kind of thing: client-side configuration, not a server collection.
 
 import { readPluginPackage } from "@stigmer/plugin-package";
-import { isBuiltInMarketplaceName } from "@stigmer/plugin-package/client";
 import { CommandResult } from "../output/index.js";
 import { count, readPluginDirectory } from "../resources/plugin.js";
 import {
@@ -27,15 +26,7 @@ export function renderMarketplaceList(
         );
   const section = result.addSection("Sources");
   for (const marketplace of listing.known) {
-    // A built-in reads "built in" beside where it comes from, so the user
-    // knows which names `remove` will refuse.
-    section.field(
-      marketplace.name,
-      isBuiltInMarketplaceName(marketplace.name) &&
-        marketplace.source.type !== "official"
-        ? `${describeSource(marketplace.source)} (built in)`
-        : describeSource(marketplace.source),
-    );
+    section.field(marketplace.name, describeSource(marketplace.source));
   }
   for (const marketplace of listing.unreadable) {
     section.field(marketplace.name, `cannot be read: ${marketplace.reason}`);

package/src/registry/index.ts

@@ -7,12 +7,18 @@ export {
   toKebabCase,
   toSnakeCase,
 } from "./aliases.js";
-export { CLI_RELEVANT_KINDS, type KindMeta, KIND_META } from "./metadata.js";
+export {
+  CLI_RELEVANT_KINDS,
+  type KindMeta,
+  KIND_META,
+  RETIRED_KINDS,
+} from "./metadata.js";
 export {
   defaultRegistry,
   type Registry,
   supportsVerb,
   type TypeInfo,
+  unknownKindError,
 } from "./registry.js";
 export {
   ALL_VERBS,

package/src/registry/metadata.ts

@@ -46,10 +46,6 @@ export const KIND_META: ReadonlyMap<ApiResourceKind, KindMeta> = new Map([
     ApiResourceKind.mcp_server,
     { name: "McpServer", displayName: "MCP Server", idPrefix: "mcp" },
   ],
-  [
-    ApiResourceKind.project,
-    { name: "Project", displayName: "Project", idPrefix: "prj" },
-  ],
   [
     ApiResourceKind.api_key,
     { name: "ApiKey", displayName: "API Key", idPrefix: "key" },
@@ -122,7 +118,6 @@ export const CLI_RELEVANT_KINDS: readonly ApiResourceKind[] = [
   ApiResourceKind.skill,
   ApiResourceKind.plugin,
   ApiResourceKind.mcp_server,
-  ApiResourceKind.project,
   ApiResourceKind.api_key,
   ApiResourceKind.identity_provider,
   ApiResourceKind.oauth_app,
@@ -135,3 +130,18 @@ export const CLI_RELEVANT_KINDS: readonly ApiResourceKind[] = [
   ApiResourceKind.workflow_instance,
   ApiResourceKind.session,
 ];
+
+/**
+ * YAML kinds the platform once served and no longer does. A manifest that
+ * still carries one is an old file, not a typo, so the refusal it meets
+ * says what happened and what to do instead of "unknown kind"; the
+ * registry's `unknownKindError` reads this table before falling back to the
+ * generic sentence. The key is the YAML `kind` value as the retired proto
+ * declared it; the value is the sentence that follows the kind's name.
+ */
+export const RETIRED_KINDS: ReadonlyMap<string, string> = new Map([
+  [
+    "Project",
+    "is no longer a Stigmer resource. A folder of resources that belong together is a plugin: run `stigmer push plugin <dir>` to install it as one, or apply each resource file with `stigmer apply -f <file>`.",
+  ],
+]);

package/src/registry/registry.test.ts

@@ -241,13 +241,7 @@ describe("registry — verb/dispatch conformance", () => {
       label: "apply",
       verb: Verb.Apply,
       wired: new Set(APPLY_HANDLERS.keys()),
-      specialCases: new Map([
-        [
-          ApiResourceKind.project,
-          "the stigmer.yaml declarative/synthesis track (resources/apply/declarative.ts); " +
-            "file mode refuses with a pointer there (resolveHandlerForKind)",
-        ],
-      ]),
+      specialCases: new Map(),
     },
     {
       label: "get",

package/src/registry/registry.ts

@@ -5,8 +5,9 @@
 // removed in the TypeScript migration — stigmer/stigmer#203.)
 
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { UsageError } from "../errors/index.js";
 import { generateAliases, normalizeAlias } from "./aliases.js";
-import { CLI_RELEVANT_KINDS, KIND_META } from "./metadata.js";
+import { CLI_RELEVANT_KINDS, KIND_META, RETIRED_KINDS } from "./metadata.js";
 import { Verb } from "./verbs.js";
 import { verbsForKind } from "./verb-support.js";
 
@@ -34,6 +35,21 @@ export function supportsVerb(info: TypeInfo, verb: Verb): boolean {
   return info.supportedVerbs.has(verb);
 }
 
+/**
+ * The one refusal for a YAML `kind` the registry does not know, shared by
+ * every path that reads a kind from a file (`apply -f`, `validate -f`) so
+ * the wording lives in one place. A kind the platform retired gets its own
+ * sentence (RETIRED_KINDS): the file is old, not wrong, and the user
+ * deserves the reason and the way. `where` names the file for the message.
+ */
+export function unknownKindError(yamlKind: string, where: string): UsageError {
+  const retired = RETIRED_KINDS.get(yamlKind);
+  if (retired !== undefined) {
+    return new UsageError(`kind '${yamlKind}' in ${where} ${retired}`);
+  }
+  return new UsageError(`unknown resource kind '${yamlKind}' in ${where}`);
+}
+
 export interface Registry {
   /** Look up a type by its proto kind. */
   getByKind(kind: ApiResourceKind): TypeInfo | undefined;

package/src/registry/verb-support.ts

@@ -66,19 +66,6 @@ export const VERB_SUPPORT: ReadonlyMap<
       Verb.Delete,
     ]),
   ],
-  // Project apply is the stigmer.yaml declarative/synthesis track, not
-  // `apply -f project.yaml` — resolveHandlerForKind carries the teaching
-  // refusal, and the conformance test documents it as a special case.
-  [
-    ApiResourceKind.project,
-    new Set<Verb>([
-      Verb.Apply,
-      Verb.Validate,
-      Verb.Get,
-      Verb.List,
-      Verb.Delete,
-    ]),
-  ],
   [ApiResourceKind.api_key, new Set<Verb>([Verb.Get, Verb.List, Verb.Delete])],
   // agent_execution is special — uses dedicated AgentExecutionQueryController
   // RPCs, not the unified SearchService. delete maps to cancel.

package/src/resources/apply/apply.integration.test.ts

@@ -268,12 +268,24 @@ describe("file-mode apply — channel app (#353)", () => {
   });
 });
 
-describe("file-mode apply — project special case", () => {
-  it("refuses a Project manifest with a pointer to the stigmer.yaml flow", () => {
+describe("file-mode apply — kinds the registry does not know", () => {
+  it("refuses a retired kind with what happened and what to run instead", () => {
     const dir = mkdtempSync(join(tmpdir(), "apply-it-"));
     try {
       writeYaml(dir, "project.yaml", ["kind: Project", "metadata:", "  name: Demo", "  slug: demo", ""].join("\n"));
-      expect(() => resolveApplyItems(dir)).toThrow(/stigmer\.yaml/);
+      expect(() => resolveApplyItems(dir)).toThrow(
+        /kind 'Project' in .*project\.yaml is no longer a Stigmer resource.*stigmer push plugin <dir>/,
+      );
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("refuses a kind that never existed with the plain unknown-kind sentence", () => {
+    const dir = mkdtempSync(join(tmpdir(), "apply-it-"));
+    try {
+      writeYaml(dir, "thing.yaml", ["kind: Widget", "metadata:", "  name: Demo", ""].join("\n"));
+      expect(() => resolveApplyItems(dir)).toThrow(/^unknown resource kind 'Widget' in .*thing\.yaml$/);
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }

package/src/resources/apply/apply.ts

@@ -18,7 +18,7 @@ import {
 } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
 import { UsageError } from "../../errors/index.js";
 import { CommandResult } from "../../output/index.js";
-import { defaultRegistry, Verb } from "../../registry/index.js";
+import { defaultRegistry, unknownKindError, Verb } from "../../registry/index.js";
 import { loadDocuments, resolveYamlFiles } from "../documents.js";
 import { decodeWorkflowTaskConfigs } from "../task-configs.js";
 import { type ApplyHandler, APPLY_HANDLERS, type ControllerFn } from "./handlers.js";
@@ -36,9 +36,9 @@ export interface ApplyOutcome {
   /** Optional org-mismatch warning to surface on stderr. */
   readonly warning?: string;
   /**
-   * The applied resource message (absent in dry-run). Carries the server's
-   * authoritative metadata (id/slug) — the reconciler reads this to register
-   * project membership, so membership matches what the backend stored.
+   * The applied resource message (absent in dry-run), as the server stored
+   * it: authoritative metadata (id, slug, visibility) for anything that
+   * runs after the apply.
    */
   readonly applied?: Message;
 }
@@ -60,22 +60,14 @@ export function resolveApplyItems(path: string): ApplyItem[] {
 
 /**
  * Resolve a YAML `kind` to its apply handler, enforcing the verb-support gate.
- * Shared by file mode and declarative mode so the lookup + error wording lives
- * in exactly one place. `where` is woven into errors for a precise location.
+ * The unknown-kind wording is the registry's (`unknownKindError`), shared
+ * with `validate -f`, so a retired kind is refused with the same sentence on
+ * both paths. `where` is woven into errors for a precise location.
  */
 export function resolveHandlerForKind(kind: string, where: string): ApplyHandler {
   const info = defaultRegistry().getByYamlKind(kind);
-  if (info === undefined) throw new UsageError(`unknown resource kind '${kind}' in ${where}`);
+  if (info === undefined) throw unknownKindError(kind, where);
   if (!info.supportedVerbs.has(Verb.Apply)) throw new UsageError(`${info.displayName} does not support 'apply'`);
-  if (info.kind === ApiResourceKind.project) {
-    // Project's Apply verb is the stigmer.yaml track, deliberately not a
-    // manifest handler: a file-mode apply would create a second, member-less
-    // way to apply a project, bypassing the membership reconciler.
-    throw new UsageError(
-      `a Project is not applied from a resource manifest (${where}): ` +
-        "run `stigmer apply` in the directory containing stigmer.yaml and the project is reconciled from its members",
-    );
-  }
   const handler = APPLY_HANDLERS.get(info.kind);
   if (handler === undefined) throw new UsageError(`apply not implemented for ${info.displayName}`);
   return handler;
@@ -109,16 +101,15 @@ export async function applyItem(
 
 /**
  * Strict YAML→proto marshal for one item, with a precise location in the error.
- * Split out from {@link applyItem} so the declarative reconciler can marshal
- * without immediately applying (it batches messages, then reconciles).
+ * Split out from {@link applyItem} so marshalling can be exercised and reused
+ * apart from the apply it feeds.
  */
 export function marshalItem(item: ApplyItem): Message {
   try {
     const message = fromJson(item.handler.schema, item.document, { ignoreUnknownFields: false });
     // Workflow task_config blocks live inside an open Struct the top-level
-    // decode cannot see into; decode them per kind so a dry-run (and the
-    // reconciler's marshal) rejects exactly what a real apply rejects
-    // (stigmer/stigmer#778).
+    // decode cannot see into; decode them per kind so a dry-run rejects
+    // exactly what a real apply rejects (stigmer/stigmer#778).
     if (item.handler.kind === ApiResourceKind.workflow) {
       decodeWorkflowTaskConfigs(message as Workflow);
     }
@@ -130,11 +121,9 @@ export function marshalItem(item: ApplyItem): Message {
 
 /**
  * Apply a fully-marshalled resource message: inject org, then dry-run preview or
- * drive the controller's `apply` RPC. This is the single apply core shared by
- * both tracks — the declarative/file track feeds messages marshalled from YAML
- * (`marshalItem`), the synthesis track feeds messages decoded from `.pb`
- * (`fromBinary`). One core means one place where org injection, create/update
- * detection, and result shaping live (DD-009 §6).
+ * drive the controller's `apply` RPC. The single apply core behind file mode,
+ * taking the message rather than the YAML so org injection, create/update
+ * detection and result shaping live in one place whatever produced the message.
  */
 export async function applyMessage(
   controller: ControllerFn,

package/src/resources/apply/handlers.ts

@@ -1,6 +1,6 @@
-// Apply-handler registry for `apply -f` (file mode) and the synthesis track.
+// Apply-handler registry for `apply -f` (file mode).
 //
-// The declarative manifest kinds come from the SDK's manifest registry
+// The manifest kinds come from the SDK's manifest registry
 // (`manifestKinds()` in @stigmer/sdk) — the one table binding a kind to its
 // proto schema, its raw command-controller `apply` RPC, and its dependency
 // apply order. The CLI consumes that table instead of keeping a copy: the

package/src/resources/connect/oauth.test.ts

@@ -112,7 +112,7 @@ describe("runOAuthFlow", () => {
       log: () => {},
     });
     expect(openBrowser).toHaveBeenCalledWith(
-      "https://app.stigmer.ai/acme/mcp-servers/github",
+      "https://app.stigmer.ai/library/mcp-servers/acme/github",
     );
   });
 
@@ -152,7 +152,7 @@ describe("runOAuthFlow", () => {
       log: () => {},
     });
     expect(openBrowser).toHaveBeenCalledWith(
-      "http://localhost:7234/acme/mcp-servers/github",
+      "http://localhost:7234/library/mcp-servers/acme/github",
     );
   });
 });

package/src/resources/connect/oauth.ts

@@ -60,7 +60,10 @@ export async function runOAuthFlow(deps: OAuthFlowDeps): Promise<void> {
 
   const slug = deps.server.metadata?.slug ?? "";
   const name = deps.server.metadata?.name ?? slug;
-  const pageURL = `${consoleURL}/${deps.org}/mcp-servers/${slug}`;
+  // The route both consoles serve (`/library/mcp-servers/<org>/<slug>`);
+  // the Go-era `/<org>/mcp-servers/<slug>` answered 404 in the TypeScript
+  // console and sent the user to a dead page.
+  const pageURL = `${consoleURL}/library/mcp-servers/${deps.org}/${slug}`;
 
   log(`OAuth authentication required for '${name}'.`);
   log("Opening web console to complete authentication...");

package/src/resources/delete.ts

@@ -82,7 +82,6 @@ export const DELETE_HANDLERS: ReadonlyMap<ApiResourceKind, DeleteFn> = new Map<
     ApiResourceKind.mcp_server,
     (c, id, force) => c.mcpServer.delete({ resourceId: id, force }),
   ],
-  [ApiResourceKind.project, (c, id) => c.project.delete(id)],
   [
     ApiResourceKind.environment,
     (c, id, force) => c.environment.delete({ resourceId: id, force }),

package/src/resources/get-bindings.ts

@@ -17,7 +17,6 @@ import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/a
 import { WorkflowInstanceSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/api_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { ApiKeySchema } from "@stigmer/protos/ai/stigmer/iam/apikey/v1/api_pb";
-import { ProjectSchema } from "@stigmer/protos/ai/stigmer/tenancy/project/v1/api_pb";
 import type { Stigmer } from "@stigmer/sdk";
 import { UsageError } from "../errors/index.js";
 import type { ParsedReference } from "./reference.js";
@@ -64,10 +63,6 @@ export const GET_BINDINGS: ReadonlyMap<ApiResourceKind, Getter> = new Map([
     ApiResourceKind.mcp_server,
     refGetter(ApiResourceKind.mcp_server, McpServerSchema, (c) => c.mcpServer),
   ],
-  [
-    ApiResourceKind.project,
-    refGetter(ApiResourceKind.project, ProjectSchema, (c) => c.project),
-  ],
   [
     ApiResourceKind.environment,
     refGetter(

package/src/resources/list.ts

@@ -55,7 +55,6 @@ export const SEARCH_KINDS: ReadonlySet<ApiResourceKind> =
     ApiResourceKind.agent,
     ApiResourceKind.workflow,
     ApiResourceKind.mcp_server,
-    ApiResourceKind.project,
     ApiResourceKind.skill,
     ApiResourceKind.plugin,
     ApiResourceKind.environment,

package/src/resources/plugin.test.ts

@@ -2,8 +2,13 @@
 // sorted sized entries, the ignore matcher applied (defaults, .gitignore,
 // .stigmerignore), symlinks never followed, and the JSON projection that
 // reduces overlay documents to their paths; then the prepared push (the
-// deterministic archive and its SHA-256, the server's own digest) and the
-// install summary renderer.
+// deterministic archive and its SHA-256, the server's own digest), the
+// install summary renderer (only the kinds installed are counted; the Next
+// section says what each server still needs), and `readNextSteps` against an
+// in-memory backend: a sign-in for an OAuth server without a grant, "signed
+// in" with one, the variables an API-key server wants and where they are
+// asked, the agent an MCP-only plugin still needs, and no line for a server
+// the CLI cannot read.
 
 import {
   mkdirSync,
@@ -260,3 +265,115 @@ describe("renderPushOutcome", () => {
     expect(text).toContain("runs on the session's model");
   });
 });
+
+describe("readNextSteps", () => {
+  it("reads what each server still needs, best-effort, and names the agent an MCP-only plugin lacks", async () => {
+    const { readNextSteps, renderPushOutcome } = await import("./plugin.js");
+    const { create } = await import("@bufbuild/protobuf");
+    const { Code, ConnectError, createRouterTransport } =
+      await import("@connectrpc/connect");
+    const { Stigmer } = await import("@stigmer/sdk");
+    const { McpServerQueryController } =
+      await import("@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb");
+    const { McpServerSchema } =
+      await import("@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb");
+    const { GetOAuthGrantStatusOutputSchema, OAuthConnectionHealth } =
+      await import("@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb");
+    const { McpServerAuthSchema, McpServerSpecSchema } =
+      await import("@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb");
+    const { EnvVarDeclarationSchema } =
+      await import("@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb");
+    const { PluginSchema } =
+      await import("@stigmer/protos/ai/stigmer/agentic/plugin/v1/api_pb");
+    const { PluginMemberSchema } =
+      await import("@stigmer/protos/ai/stigmer/agentic/plugin/v1/io_pb");
+    const { ApiResourceKind } =
+      await import("@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb");
+    const { renderResult } = await import("../output/command-result.js");
+
+    const shapes: Record<string, "oauth" | "oauth-granted" | "api-key" | "open" | "missing"> = {
+      linear: "oauth",
+      notion: "oauth-granted",
+      warmth: "api-key",
+      weather: "open",
+      ghost: "missing",
+    };
+    const transport = createRouterTransport(({ service }) => {
+      service(McpServerQueryController, {
+        getByReference: (ref) => {
+          const shape = shapes[ref.slug];
+          if (shape === undefined || shape === "missing")
+            throw new ConnectError("no server", Code.NotFound);
+          const spec = create(McpServerSpecSchema);
+          if (shape === "oauth" || shape === "oauth-granted") {
+            spec.auth = create(McpServerAuthSchema, { targetEnvVar: "TOKEN", oauthOnly: true });
+            spec.env = { TOKEN: create(EnvVarDeclarationSchema, { isSecret: true }) };
+          }
+          if (shape === "api-key") spec.env = { API_TOKEN: create(EnvVarDeclarationSchema, { isSecret: true }) };
+          return create(McpServerSchema, { metadata: { id: `mcp_${ref.slug}`, org: "acme", slug: ref.slug }, spec });
+        },
+        getOAuthGrantStatus: (input) => {
+          const granted = input.resourceId === "mcp_notion";
+          return create(GetOAuthGrantStatusOutputSchema, {
+            connected: granted,
+            connectionHealth: granted
+              ? OAuthConnectionHealth.OAUTH_CONNECTION_HEALTH_HEALTHY
+              : OAuthConnectionHealth.OAUTH_CONNECTION_HEALTH_NO_GRANT,
+          });
+        },
+      });
+    });
+    const client = new Stigmer({ baseUrl: "/", getAccessToken: () => "t", customTransport: transport });
+    const member = (slug: string) =>
+      create(PluginMemberSchema, { kind: ApiResourceKind.mcp_server, id: `mcp_${slug}`, slug, name: slug });
+
+    const next = await readNextSteps(client, "acme", Object.keys(shapes).map(member));
+    expect(next).toEqual([
+      { kind: "sign-in", server: "linear", command: "stigmer connect mcp-server linear" },
+      { kind: "signed-in", server: "notion" },
+      {
+        kind: "api-key",
+        server: "warmth",
+        variables: ["API_TOKEN"],
+        askedAt: "connect",
+        command: "stigmer connect mcp-server warmth --env API_TOKEN=...",
+      },
+      { kind: "add-to-agent", servers: ["linear", "notion", "warmth", "weather", "ghost"] },
+    ]);
+
+    // With an agent, the variables are the agent's to ask and no agent is missing.
+    const withAgent = await readNextSteps(client, "acme", [
+      member("warmth"),
+      create(PluginMemberSchema, { kind: ApiResourceKind.agent, id: "agt_1", slug: "thermos", name: "thermos" }),
+    ]);
+    expect(withAgent).toEqual([
+      { kind: "api-key", server: "warmth", variables: ["API_TOKEN"], askedAt: "agent" },
+    ]);
+
+    // The renderer names only the kinds installed and prints the Next section.
+    const plugin = create(PluginSchema, {
+      metadata: { id: "plg_1", slug: "linear" },
+      status: { materialized: { skills: 0, mcpServers: 1, agents: 0, workflows: 0 } },
+    });
+    const result = renderPushOutcome(
+      { plugin, members: [member("linear")], archiveBytes: 10 },
+      { next: next.slice(0, 1) },
+    );
+    const lines: string[] = [];
+    const original = process.stderr.write.bind(process.stderr);
+    process.stderr.write = ((chunk: string | Uint8Array) => {
+      lines.push(String(chunk));
+      return true;
+    }) as typeof process.stderr.write;
+    try {
+      renderResult(result, "human");
+    } finally {
+      process.stderr.write = original;
+    }
+    const text = lines.join("");
+    expect(text).toContain("Installed plugin 'linear' (1 MCP server)");
+    expect(text).not.toContain("0 skills");
+    expect(text).toContain("Next");
+    expect(text).toContain("Sign in to linear:  stigmer connect mcp-server linear");
+  });
+});