@stigmer/cli 3.19.0 → 3.20.0

package/src/commands/apply.ts

@@ -1,18 +1,23 @@
 // `stigmer apply` — deploy resources to the backend.
 //
 //   File mode (-f):     apply individual YAML resource files (or a directory)
-//   Declarative mode:   a stigmer.yaml project directory (scan + reconcile)
-//   Plugin track:       a directory holding a plugin manifest (either flag,
+//   Plugin track:       a directory holding a plugin manifest (the -f path,
 //                       or the working directory) installs as a plugin — the
 //                       same read, zip and push as `push plugin <dir>`, so the
 //                       two verbs are one code path
 //
+// A bare `stigmer apply` in a directory that is neither prints what the
+// command can do. A `stigmer.yaml` there is the retired Project format, and
+// the guidance says so: a folder of resources that belong together is a
+// plugin.
+//
 // Resources marshal strictly from YAML to full protos and apply through the raw
 // command controllers (preserving metadata.id so updates aren't misrouted as
 // creates). Heavy modules are lazy-imported so `--help` stays fast (DD-001).
+import { existsSync } from "node:fs";
+import { join } from "node:path";
 import type { Command } from "commander";
 import { ensureAuthenticated, resolveOrganization } from "../config/index.js";
-import { UsageError } from "../errors/index.js";
 import {
   CommandResult,
   type OutputFlags,
@@ -21,23 +26,22 @@ import {
 } from "../output/index.js";
 import { addResultFlags, globalOrg, resultFormat } from "./shared.js";
 
+/**
+ * The manifest file the retired Project format kept at a directory's root.
+ * Read only to recognise an old repository and say what happened to it.
+ */
+const RETIRED_PROJECT_FILE = "stigmer.yaml";
+
 interface ApplyFlags extends OutputFlags {
   file?: string;
-  config?: string;
-  prune?: boolean;
   dryRun?: boolean;
 }
 
 export function registerApply(program: Command): void {
   const apply = program
     .command("apply")
-    .description("apply resources from files or a project directory")
-    .option("-f, --file <path>", "path to a YAML file or directory")
-    .option("--config <path>", "path to a project directory (declarative mode)")
-    // S1: Go plumbs --prune but never sends it — the server always reconciles
-    // orphans by member set-difference. We reproduce the flag (default on) for
-    // parity; it is intentionally a no-op client-side. Tracked as a Go follow-up.
-    .option("--prune", "delete orphaned resources (declarative mode)", true)
+    .description("apply resources from files or a plugin directory")
+    .option("-f, --file <path>", "path to a YAML file, a directory of YAML files, or a plugin directory")
     .option("--dry-run", "validate without applying")
     .action((options: ApplyFlags, command: Command) =>
       runApply(options, command),
@@ -56,9 +60,7 @@ async function runApply(options: ApplyFlags, command: Command): Promise<void> {
   const target =
     options.file !== undefined && options.file !== ""
       ? options.file
-      : options.config !== undefined && options.config !== ""
-        ? options.config
-        : process.cwd();
+      : process.cwd();
   const { isPluginDirectory } = await import("../resources/plugin.js");
   if (isPluginDirectory(target)) {
     await runPluginApply(target, orgOverride, options.dryRun === true, format);
@@ -75,7 +77,7 @@ async function runApply(options: ApplyFlags, command: Command): Promise<void> {
     return;
   }
 
-  await runDeclarativeApply(options, orgOverride, format);
+  renderResult(buildGuidance(target), format);
 }
 
 // Plugin track: install or upgrade the plugin folder as one unit through the
@@ -130,123 +132,6 @@ async function runPluginApply(
   );
 }
 
-// Declarative mode: detect stigmer.yaml (walk up). Absent → atomic guidance.
-// entry_point set → SDK/project synthesis track. Otherwise scan the project and
-// reconcile membership. Both project tracks converge on the shared reconciler.
-async function runDeclarativeApply(
-  options: ApplyFlags,
-  orgOverride: string | undefined,
-  format: OutputFormat,
-): Promise<void> {
-  const { detectTrack, applyDeclarative, previewDeclarative } =
-    await import("../resources/apply/declarative.js");
-
-  const startDir =
-    options.config !== undefined && options.config !== ""
-      ? options.config
-      : process.cwd();
-  const detect = detectTrack(startDir);
-
-  if (detect.track === "atomic") {
-    renderResult(buildAtomicGuidance(), format);
-    return;
-  }
-
-  if (detect.track === "project") {
-    await runProjectApply(detect, orgOverride, format, options.dryRun === true);
-    return;
-  }
-
-  if (options.dryRun === true) {
-    const { results, summary } = previewDeclarative(detect, {
-      controller: throwingController,
-      warn: (line) => emitWarning(line),
-    });
-    for (const result of results) renderResult(result, format);
-    renderResult(summary, format);
-    return;
-  }
-
-  const { connectBackend } = await import("../backend.js");
-  const client = connectBackend();
-  ensureAuthenticated(client.config);
-  const org = resolveDeclarativeOrg(
-    client.config,
-    detect.project?.metadata?.org,
-    orgOverride,
-  );
-
-  const result = await applyDeclarative(detect, {
-    controller: client.controller,
-    stigmer: client.stigmer,
-    org,
-    info: (line) => process.stderr.write(`${line}\n`),
-    warn: (line) => emitWarning(line),
-  });
-  renderResult(result, format);
-}
-
-// Project (SDK synthesis) track: run the user's entry_point, read the `.pb`
-// output, and reconcile membership through the same reconciler the declarative
-// track uses. Lazy-imported to preserve the DD-001 boundary (`--help` stays
-// fast).
-async function runProjectApply(
-  detect: import("../resources/apply/declarative.js").DetectResult,
-  orgOverride: string | undefined,
-  format: OutputFormat,
-  dryRun: boolean,
-): Promise<void> {
-  const { applyProjectTrack, previewProjectTrack } =
-    await import("../resources/apply/synth/project-track.js");
-
-  if (dryRun) {
-    renderResult(previewProjectTrack(detect), format);
-    return;
-  }
-
-  const { connectBackend } = await import("../backend.js");
-  const client = connectBackend();
-  ensureAuthenticated(client.config);
-  const org = resolveDeclarativeOrg(
-    client.config,
-    detect.project?.metadata?.org,
-    orgOverride,
-  );
-
-  const result = await applyProjectTrack(detect, {
-    controller: client.controller,
-    stigmer: client.stigmer,
-    org,
-    info: (line) => process.stderr.write(`${line}\n`),
-    warn: (line) => emitWarning(line),
-  });
-  renderResult(result, format);
-}
-
-// Org precedence mirrors Go's resolveApplyOrganization: --org flag, then
-// metadata.org in stigmer.yaml, then the configured context. Empty → a clear
-// "set your org" usage error.
-function resolveDeclarativeOrg(
-  config: import("../config/index.js").Config,
-  projectOrg: string | undefined,
-  override: string | undefined,
-): string {
-  const resolved = resolveOrganization(
-    config,
-    override ?? (projectOrg !== "" ? projectOrg : undefined),
-  );
-  if (resolved === "") {
-    throw new UsageError(
-      "organization not set\n\n" +
-        "Specify organization in one of these ways:\n" +
-        "  1. Set metadata.org in stigmer.yaml\n" +
-        "  2. Use --org flag: stigmer apply --org <org>\n" +
-        "  3. Set context: stigmer context set --org <org>",
-    );
-  }
-  return resolved;
-}
-
 async function runFileApply(
   path: string,
   orgOverride: string | undefined,
@@ -298,24 +183,24 @@ async function runFileApply(
   );
 }
 
-function buildAtomicGuidance(): CommandResult {
-  const result = CommandResult.warning(
-    "No stigmer.yaml found in current directory or parents",
-  );
+// What a bare `stigmer apply` says when the target holds no plugin manifest:
+// the two things the command does, and, when a `stigmer.yaml` sits there,
+// what that file was and where its resources go now.
+function buildGuidance(target: string): CommandResult {
+  const result = CommandResult.warning(`No plugin manifest in ${target}`);
   result
-    .addSection("")
-    .item(
-      "The 'stigmer apply' command (without -f) requires a project with stigmer.yaml",
-    )
-    .item("This enables resource discovery and project-based reconciliation");
-  result
-    .addSection("For single-resource deployment, use file mode")
-    .item("stigmer apply -f agent.yaml")
-    .item("stigmer apply -f workflow.yaml")
-    .item("stigmer apply -f mcpserver.yaml");
-  result.hint(
-    "To create a project: add a stigmer.yaml with your project name, then run 'stigmer apply'",
-  );
+    .addSection("What 'stigmer apply' does")
+    .item("stigmer apply -f <file>        apply a resource file (agent, workflow, MCP server, ...)")
+    .item("stigmer apply -f <dir>         apply every YAML file in a directory")
+    .item("stigmer push skill <dir>       publish a skill folder")
+    .item("stigmer push plugin <dir>      install a folder of resources as one plugin");
+  if (existsSync(join(target, RETIRED_PROJECT_FILE))) {
+    result
+      .addSection(`About the ${RETIRED_PROJECT_FILE} here`)
+      .item(
+        "It is the Project format, which Stigmer no longer has. A folder of resources that belong together is a plugin: run `stigmer push plugin <dir>`, or apply each resource file with `stigmer apply -f`.",
+      );
+  }
   return result;
 }
 

package/src/commands/validate.ts

@@ -23,7 +23,7 @@ import {
   type OutputFlags,
   renderResult,
 } from "../output/index.js";
-import { defaultRegistry, Verb } from "../registry/index.js";
+import { defaultRegistry, unknownKindError, Verb } from "../registry/index.js";
 import { loadDocuments, resolveYamlFiles } from "../resources/documents.js";
 import { addResultFlags, resultFormat } from "./shared.js";
 
@@ -70,9 +70,7 @@ async function runValidate(options: ValidateFlags): Promise<CommandResult> {
     // Validate stays lenient (default) — strict parsing is reserved for apply.
     for (const { kind, document } of loadDocuments(file)) {
       const info = registry.getByYamlKind(kind);
-      if (info === undefined) {
-        throw new UsageError(`unknown resource kind '${kind}' in ${file}`);
-      }
+      if (info === undefined) throw unknownKindError(kind, file);
       if (!info.supportedVerbs.has(Verb.Validate)) {
         throw new UsageError(
           `${info.displayName} does not support validation (in ${file})`,

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.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/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",