@metaobjectsdev/cli 1.0.0-rc.4 → 1.0.0-rc.6

package/src/commands/init.ts

@@ -8,13 +8,14 @@ import {
   assemble, resolveAgentContextRoot, planScaffold,
   AGENT_CONTEXT_MANIFEST_PATH, type Manifest, type Stack,
 } from "@metaobjectsdev/sdk/agent-context";
-import { resolveStack } from "../lib/detect-stack.js";
+import { assertKnownStackValues, resolveStack } from "../lib/detect-stack.js";
+import { reportIgnoredScaffold } from "../lib/ignored-scaffold-check.js";
 import { parseInitArgs } from "../lib/args.js";
 import { log } from "../lib/log.js";
 import { cliVersion } from "../lib/version.js";
 import { declaredDependencyNames, type PackageManifest } from "../lib/package-manifest.js";
 import { findWranglerConfig, parseWranglerConfig } from "@metaobjectsdev/migrate-ts";
-import { readReferenceTemplate, type ReferenceGeneratorName } from "@metaobjectsdev/codegen-ts";
+import { DEFAULT_DOCS_DIR, readReferenceTemplate, type ReferenceGeneratorName } from "@metaobjectsdev/codegen-ts";
 
 // ADR-0034 scaffold-and-own — `meta init` copies the codegen reference templates into
 // the consumer's repo so they OWN them; metaobjects.config.ts imports them locally.
@@ -138,9 +139,17 @@ export default defineConfig({
     barrel(),
   ],
   docs: {
-    outDir:   "./docs",        // model + api surfaces both land here (run: meta docs)
+    outDir:   "${DEFAULT_DOCS_DIR}",  // every surface lands here (run: meta docs).
+                               // A SUB-directory on purpose: these pages are regenerated
+                               // and overwritten, and docs/ itself is usually yours.
     layout:   "flat",          // or "package" for multi-package models
-    surfaces: ["model", "api"],
+    // surfaces defaults to ["model", "api", "requirements", "agent"] — all four.
+    // Deliberately NOT narrowed here: the requirements and agent surfaces emit ZERO
+    // files for a project that has nothing for them to describe, and the always-on
+    // agent context points at the agent/ pages by name. Scaffolding a narrower list
+    // turned that pointer into a pointer at nothing. Narrow it yourself if you want
+    // fewer docs — but note it says what your docs ARE, not which of them you commit
+    // (a page you do not commit is exempt from verify --docs once it is git-ignored).
   },
 });
 `;
@@ -474,6 +483,57 @@ async function writeOwnedGenerators(opts: InitOptions, result: InitResult): Prom
     await writeFile(abs, readReferenceTemplate(name), "utf8");
     result.created.push(rel);
   }
+  await writeCodegenTsconfig(opts, result);
+}
+
+/** The owned codegen tier's own tsconfig — see writeCodegenTsconfig. */
+const CODEGEN_TSCONFIG_REL = "tsconfig.codegen.json";
+
+const CODEGEN_TSCONFIG_BODY = `{
+  // The owned codegen tier typechecks itself.
+  //
+  // \`meta gen\` loads metaobjects.config.ts and ./codegen/** through jiti, which
+  // TRANSPILES WITHOUT TYPECHECKING. So a generator here can import a symbol the
+  // engine no longer exports, or call a method that does not exist, and every gate
+  // stays green until the import is evaluated — which for a generator you have not
+  // wired into \`generators: [...]\` may be never.
+  //
+  // A project's app tsconfig usually covers src/ and tests/ and NOT this tier, so
+  // without this file nothing compiles the code your build depends on. Run it with:
+  //   npx tsc -p tsconfig.codegen.json --noEmit
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true
+  },
+  "include": ["metaobjects.config.ts", "codegen/**/*.ts"]
+}
+`;
+
+/**
+ * Scaffold a tsconfig that covers the tier `meta init` just handed the adopter.
+ *
+ * Reported from an estate that found TWO real defects the moment one existed: a
+ * generator importing `CODEGEN_ATTR_EMIT_ROUTES` (retired with the `@emit*` family,
+ * and invisible because that generator was not in `generators: [...]`), and a wired
+ * generator carrying five type errors including `ownFields()` on a node that has no
+ * such method. Both found on the first run.
+ *
+ * Written only when absent, like every other scaffolded file — an adopter who has
+ * their own arrangement keeps it, and it is reported as preserved rather than
+ * silently skipped.
+ */
+async function writeCodegenTsconfig(opts: InitOptions, result: InitResult): Promise<void> {
+  const abs = join(opts.cwd, CODEGEN_TSCONFIG_REL);
+  if (await fileExists(abs)) {
+    result.preserved.push(CODEGEN_TSCONFIG_REL);
+    return;
+  }
+  await writeFile(abs, CODEGEN_TSCONFIG_BODY, "utf8");
+  result.created.push(CODEGEN_TSCONFIG_REL);
 }
 
 /**
@@ -543,6 +603,16 @@ async function writeConfigFile(opts: InitOptions, result: InitResult, agentDir:
 }
 
 export async function init(opts: InitOptions): Promise<InitResult> {
+  // Refused HERE, in the shared function, before anything is written — NOT at one CLI
+  // entry point. It was at `initCommand`'s arg parse only, and `meta agent-docs` calls
+  // this directly: `meta init --docs-only --server klingon` exited 2 with the message
+  // while `meta agent-docs --server klingon` exited 0, reported "11 files", and recorded
+  // `"servers": []`. That is the worse of the two doors to miss — `agent-docs` is the
+  // canonical redirect target for every language port, so the ports used the unguarded
+  // one. A non-empty override array suppresses both the prior manifest's stack AND
+  // detection, so a dropped value does not degrade, it inverts three statements in the
+  // generated context.
+  assertKnownStackValues({ servers: opts.servers ?? [], clients: opts.clients ?? [] });
   const result: InitResult = { created: [], preserved: [], removed: [], warnings: [] };
   const agentDir = join(opts.cwd, DEFAULT_METAOBJECTS_DIR);
   const metaobjectsDir = join(opts.cwd, DEFAULT_METADATA_DIR);
@@ -607,6 +677,7 @@ export async function init(opts: InitOptions): Promise<InitResult> {
     );
     result.created.push(".metaobjects/AGENTS.md", ".metaobjects/CLAUDE.md", ".claude/skills/metaobjects-*", AGENT_CONTEXT_MANIFEST_PATH);
     for (const name of SCAFFOLDED_GENERATOR_NAMES) result.created.push(`${OWNED_GENERATORS_DIR}/${name}.ts`);
+    result.created.push(CODEGEN_TSCONFIG_REL);
     result.created.push("metaobjects.config.ts", DB_STUB_REL_PATH, ".gitignore");
     return result;
   }
@@ -713,7 +784,7 @@ export async function init(opts: InitOptions): Promise<InitResult> {
     result.preserved.push(".gitignore");
   }
 
-  await ensureEsmPackageType(opts.cwd, result);
+  await prepareManifestForScaffold(opts.cwd, result);
 
   return result;
 }
@@ -734,8 +805,13 @@ export async function init(opts: InitOptions): Promise<InitResult> {
  * So set it — but never silently take a real CommonJS project with it. A project
  * that has actual CJS sources gets a loud, specific warning instead of an edit,
  * because changing a module system out from under working code is not ours to do.
+ *
+ * IT ALSO DECLARES WHAT THE SCAFFOLD AND THE GENERATED OUTPUT IMPORT, and the name it used
+ * to carry (`ensureEsmPackageType`) is why that went wrong: a function named for one job
+ * accreted a second, and the second silently inherited the first's early returns. The
+ * declarations are unconditional on a readable manifest — see the comment at that point.
  */
-async function ensureEsmPackageType(cwd: string, result: InitResult): Promise<void> {
+async function prepareManifestForScaffold(cwd: string, result: InitResult): Promise<void> {
   const pkgPath = join(cwd, "package.json");
   if (!(await fileExists(pkgPath))) {
     // No package.json at all: say what is needed rather than inventing a manifest
@@ -760,39 +836,59 @@ async function ensureEsmPackageType(cwd: string, result: InitResult): Promise<vo
     return;
   }
 
-  if (pkg.type === "module") return;   // already correct — nothing to do, nothing to say
-
-  if (await hasCommonJsSources(cwd)) {
-    result.warnings.push(
-      'this project has CommonJS sources, so `"type": "module"` was NOT set for you — ' +
-        "but the scaffolded generators and all generated code are ESM and will not " +
-        "compile without it. Either migrate the project to ESM, or keep the generated " +
-        "code in a sub-directory with its own package.json declaring `\"type\": \"module\"`.",
-    );
-    return;
+  // TWO INDEPENDENT JOBS FROM HERE, and they must not share an exit.
+  //
+  // The module system is one; declaring what the scaffold and the generated output import
+  // is the other, and it is true of every project with a readable manifest — including the
+  // one that already had `"type": "module"` and needs no module-system edit at all. Those
+  // two were folded together, below this function's early returns, and the consequence was
+  // that the adopter who had set their project up CORRECTLY got no declarations and no
+  // warning: `meta gen` worked (the CLI aliases those specifiers for itself) while `tsc`
+  // reported TS2307 on all five files `meta init` had just written. Under a strict
+  // installer that is every one of them; npm's hoisting hid roughly half.
+  //
+  // `moduleSystemNote` is computed first and applied last so the two jobs share ONE write
+  // of the manifest, rather than one job's early return deciding the other's fate.
+  let moduleSystemNote: string | undefined;
+
+  if (pkg.type !== "module") {
+    if (await hasCommonJsSources(cwd)) {
+      // `"type": "module"` is NOT set — changing a module system out from under working
+      // CJS code is not ours to do. The dependency declarations below still apply: they
+      // are about what the generated code imports, not about how it is loaded.
+      result.warnings.push(
+        'this project has CommonJS sources, so `"type": "module"` was NOT set for you — ' +
+          "but the scaffolded generators and all generated code are ESM and will not " +
+          "compile without it. Either migrate the project to ESM, or keep the generated " +
+          "code in a sub-directory with its own package.json declaring `\"type\": \"module\"`.",
+      );
+    } else {
+      const declaredType = pkg.type;   // read BEFORE the mutation below overwrites it
+      pkg.type = "module";
+      // Past tense, deliberately: this reports an edit already made. The imperative
+      // ("set `\"type\": \"module\"`") read as a TODO on the one line a newcomer sees
+      // last, so a scaffold that had just done the right thing looked like it had failed.
+      //
+      // And it must not claim the manifest was SILENT on the point: `npm init -y` writes
+      // `"type": "commonjs"` explicitly (npm 11.x), which is the dominant first-touch path,
+      // so "declared no module system" was false exactly where it is read most. Report what
+      // was actually there.
+      const previous = typeof declaredType === "string" ? declaredType : undefined;
+      moduleSystemNote =
+        `package.json ${previous === undefined ? "declared no module system" : `declared "type": "${previous}"`} — ` +
+        'set `"type": "module"` for you, because MetaObjects scaffolds and generates ESM, ' +
+        "which a CommonJS project cannot compile.";
+    }
   }
 
-  const declaredType = pkg.type;   // read BEFORE the mutation below overwrites it
-  pkg.type = "module";
   const added = addScaffoldDevDependencies(pkg);
   const addedRuntime = addScaffoldRuntimeDependencies(pkg);
-  // Preserve the file's existing indentation rather than reformatting someone's manifest.
-  const indent = /\n(\s+)"/.exec(raw)?.[1] ?? "  ";
-  await writeFile(pkgPath, `${JSON.stringify(pkg, null, indent)}\n`, "utf8");
-  // Past tense, deliberately: this reports an edit already made. The imperative
-  // ("set `\"type\": \"module\"`") read as a TODO on the one line a newcomer sees
-  // last, so a scaffold that had just done the right thing looked like it had failed.
-  //
-  // And it must not claim the manifest was SILENT on the point: `npm init -y` writes
-  // `"type": "commonjs"` explicitly (npm 11.x), which is the dominant first-touch path,
-  // so "declared no module system" was false exactly where it is read most. Report what
-  // was actually there.
-  const previous = typeof declaredType === "string" ? declaredType : undefined;
-  result.warnings.push(
-    `package.json ${previous === undefined ? "declared no module system" : `declared "type": "${previous}"`} — ` +
-      'set `"type": "module"` for you, because MetaObjects scaffolds and generates ESM, ' +
-      "which a CommonJS project cannot compile.",
-  );
+  if (moduleSystemNote !== undefined || added.length > 0 || addedRuntime.length > 0) {
+    // Preserve the file's existing indentation rather than reformatting someone's manifest.
+    const indent = /\n(\s+)"/.exec(raw)?.[1] ?? "  ";
+    await writeFile(pkgPath, `${JSON.stringify(pkg, null, indent)}\n`, "utf8");
+  }
+  if (moduleSystemNote !== undefined) result.warnings.push(moduleSystemNote);
   if (added.length > 0) {
     result.warnings.push(
       `added ${added.join(" + ")} to devDependencies — the scaffolded ` +
@@ -807,6 +903,22 @@ async function ensureEsmPackageType(cwd: string, result: InitResult): Promise<vo
         "installed. Run your package manager's install before `meta gen`.",
     );
   }
+  // Never degrade in silence. The first version of this returned `{}` on any failure to
+  // read runtime-ts's peer ranges and skipped the three packages that come from them —
+  // which is exactly what happened against the published package, and the run looked
+  // successful while leaving the project with the six TS2307s this code exists to
+  // prevent. A fallback that cannot be observed is indistinguishable from a bug.
+  const undeclarable = SCAFFOLD_OUTPUT_PEERS.filter(
+    (name) => !declaredDependencyNames(pkg as PackageManifest).has(name),
+  );
+  if (undeclarable.length > 0) {
+    result.warnings.push(
+      `could NOT declare ${undeclarable.join(" + ")} — the version ranges are read from ` +
+        "@metaobjectsdev/runtime-ts's own peerDependencies and that manifest could not be " +
+        "read. Generated code imports them, so add them to dependencies by hand or " +
+        "`npx tsc` will report TS2307 on files `meta gen` writes.",
+    );
+  }
 }
 
 /**
@@ -904,13 +1016,39 @@ function scaffoldRuntimeDependencies(): Record<string, string> {
   return wanted;
 }
 
-/** `@metaobjectsdev/runtime-ts`'s declared peer ranges, or `{}` if it cannot be read. */
+/**
+ * `@metaobjectsdev/runtime-ts`'s declared peer ranges, or `{}` if they cannot be read.
+ *
+ * Resolves the package's ENTRY and walks up to the nearest package.json, rather than
+ * asking for `"@metaobjectsdev/runtime-ts/package.json"` directly. That direct form is
+ * the obvious one and it is WRONG: a package's `exports` map gates every subpath, and
+ * runtime-ts's exports are `.` / `./drivers` / `./fastify` / `./drizzle-fastify` /
+ * `./hono` — no `./package.json`. Under real Node it throws
+ * ERR_PACKAGE_PATH_NOT_EXPORTED. It appeared to work here only because the workspace
+ * runs this under bun against a symlinked source tree; against the published package it
+ * failed on the first try, silently, and `meta init` declared one package instead of
+ * four. Resolving the entry is never gated — `.` is the one subpath every package
+ * exports — so this form works under npm, pnpm, bun and a linked checkout alike.
+ */
 function runtimeTsPeerRanges(): Record<string, string> {
   try {
     const req = createRequire(import.meta.url);
-    const manifestPath = req.resolve("@metaobjectsdev/runtime-ts/package.json");
-    const manifest = JSON.parse(readFileSyncWrap(manifestPath, "utf8")) as PackageManifest;
-    return (manifest.peerDependencies ?? {}) as Record<string, string>;
+    let dir = dirname(req.resolve("@metaobjectsdev/runtime-ts"));
+    // The entry sits under dist/; the manifest is at the package root above it.
+    for (let hops = 0; hops < 8; hops++) {
+      const candidate = join(dir, "package.json");
+      if (existsSyncWrap(candidate)) {
+        const manifest = JSON.parse(readFileSyncWrap(candidate, "utf8")) as PackageManifest & { name?: string };
+        // Guard against stopping at a nested manifest that is not the package itself.
+        if (manifest.name === "@metaobjectsdev/runtime-ts") {
+          return (manifest.peerDependencies ?? {}) as Record<string, string>;
+        }
+      }
+      const up = dirname(dir);
+      if (up === dir) break;
+      dir = up;
+    }
+    return {};
   } catch {
     return {};
   }
@@ -1010,6 +1148,9 @@ export async function initCommand(args: string[], cwd: string): Promise<number>
   let flags;
   try {
     flags = parseInitArgs(args);
+    // Also here, so a bad value is a USAGE error (exit 2) rather than the exit 1 an
+    // init failure gets. `init()` refuses it too, which is what covers every other door.
+    assertKnownStackValues({ servers: flags.servers ?? [], clients: flags.clients ?? [] });
   } catch (err) {
     log.error((err as Error).message);
     return 2;
@@ -1038,6 +1179,14 @@ export async function initCommand(args: string[], cwd: string): Promise<number>
     }
 
     if (!flags.quiet) {
+      // A count is not a guarantee that the files reached the repository. Many projects
+      // git-ignore `.claude/` under a comment about credentials — a common and defensible
+      // convention — and eight of the eleven files land there. Ignored, they exist only on
+      // the machine that ran this: not committed, absent from CI and from a fresh clone,
+      // invisible to a teammate, while `.agent-context.json` (which IS committed) tracks
+      // them. That silently voids the whole downstream agent-context design, and the answer
+      // was available from the outputs this command had just written.
+      reportIgnoredScaffold(cwd, result.created);
       if (flags.docsOnly) {
         log.info(`Scaffolded the MetaObjects agent context (${result.created.length} files): .metaobjects/AGENTS.md + .claude/skills/metaobjects-*.`);
         for (const w of result.warnings) log.info(`  ${w}`);

package/src/commands/migrate.ts

@@ -58,8 +58,16 @@ import {
 } from "../lib/wrangler.js";
 import { buildProjectionViews } from "@metaobjectsdev/codegen-ts";
 import { tokensToAllowOptions, describeChange } from "../lib/allow.js";
+import { reportLoadError } from "../lib/load-error.js";
 
-const MIGRATE_HELP_TEXT = `meta migrate — diff metadata vs live DB; emit migration SQL files
+/**
+ * Print a load failure with everything the loader's ADR-0009 envelope carried — the stable
+ * code, the file, the json path, and the loader's own next steps — instead of the bare
+ * `err.message` five commands used to print. See `lib/load-error.ts`.
+ */
+
+
+export const MIGRATE_HELP_TEXT = `meta migrate — diff metadata vs live DB; emit migration SQL files
 
 USAGE:
   meta migrate [baseline|apply-pending] [flags]
@@ -628,7 +636,7 @@ export async function migrateCommand(
       ...postgresLoadOptions,
     });
   } catch (err) {
-    log.error(`failed to load metadata: ${(err as Error).message}`);
+    reportLoadError(log, "failed to load metadata", err);
     return 2;
   }
 
@@ -1056,7 +1064,7 @@ export async function runBaseline(
         ...baselineLoadOptions,
       });
     } catch (err) {
-      log.error(`migrate baseline: failed to load metadata: ${(err as Error).message}`);
+      reportLoadError(log, "migrate baseline: failed to load metadata", err);
       return 2;
     }
     const baselineViews = buildProjectionViews(metadata, { dialect: config.dialect, columnNamingStrategy: baselineStrategy });
@@ -1195,7 +1203,7 @@ export async function runOfflineGenerate(
       ...offlineLoadOptions,
     });
   } catch (err) {
-    log.error(`migrate: failed to load metadata: ${(err as Error).message}`);
+    reportLoadError(log, "migrate: failed to load metadata", err);
     return 2;
   }
 
@@ -1460,7 +1468,7 @@ async function runD1Migrate(
       ...d1LoadOptions,
     });
   } catch (err) {
-    log.error(`migrate: failed to load metadata: ${(err as Error).message}`);
+    reportLoadError(log, "migrate: failed to load metadata", err);
     return 2;
   }
 

package/src/commands/prompt-snapshot.ts

@@ -14,6 +14,7 @@ import { parsePromptSnapshotArgs } from "../lib/args.js";
 import { log } from "../lib/log.js";
 import { FileProvider } from "../lib/file-provider.js";
 import { snapshotPaths, unifiedDiff } from "../lib/snapshot.js";
+import { reportLoadError } from "../lib/load-error.js";
 import { loadMemoryOptionsFrom, loadMetaobjectsConfig, resolveGenConfigDir } from "../lib/load-metaobjects-config.js";
 import { loadMemory, resolveCollection } from "@metaobjectsdev/sdk";
 import { TYPE_TEMPLATE, TEMPLATE_ATTR_TEXT_REF, TEMPLATE_ATTR_FORMAT } from "@metaobjectsdev/metadata";
@@ -78,7 +79,7 @@ export async function promptSnapshotCommand(args: string[], cwd: string): Promis
       ...configLoadOptions,
     });
   } catch (err) {
-    log.error(`failed to load metadata: ${(err as Error).message}`);
+    reportLoadError(log, "failed to load metadata", err);
     return 1;
   }
 

package/src/commands/types.ts

@@ -20,8 +20,8 @@
 // The `--json` flag this once advertised in its own --help, twice, is not coming back: the
 // CLI rejects a bare `--json` before a command ever sees its args (index.ts, `formatAlias`),
 // on purpose — one global spelling for all three formats.
-import { composeRegistry, coreProviders, buildVocabularyCatalog } from "@metaobjectsdev/metadata";
-import { forgeTypesProvider } from "@metaobjectsdev/sdk";
+import { composeRegistry, buildVocabularyCatalog } from "@metaobjectsdev/metadata";
+import { defaultLoadMemoryProviders } from "@metaobjectsdev/sdk";
 import { log } from "../lib/log.js";
 import { emitStructured, type OutputFormat } from "../lib/format.js";
 
@@ -226,7 +226,16 @@ export async function typesCommand(args: string[], fmt: OutputFormat = "text"):
   // @sortable, @dbColumnType), `view.textarea` with none (no @rows), and the eight
   // documentation commonAttrs — @title among them — were absent entirely. This is the same
   // provider set the loader composes, so what this prints is what the loader accepts.
-  const registry = composeRegistry([...coreProviders, forgeTypesProvider], { validate: true });
+  // `defaultLoadMemoryProviders` — THE composition, not a second spelling of it. This read
+  // `[...coreProviders]`, which is what that constant happens to equal today, so the claim
+  // above ("the same provider set the loader composes") was true by coincidence and the gate
+  // that pins the default composition against the canonical manifest had no jurisdiction
+  // here: add or drop a provider in the default set and `meta types` would silently print a
+  // vocabulary the loader does not accept, with nothing failing. `forgeTypesProvider` was
+  // once in this list, and printing it as registered vocabulary was part of how a TS-only
+  // registration read as cross-port: `meta types forge --all` listed 20 attrs no other port
+  // has. One composition, one door.
+  const registry = composeRegistry([...defaultLoadMemoryProviders], { validate: true });
   const catalog = buildVocabularyCatalog(registry);
 
   // Flatten the catalog into searchable entries.

package/src/commands/upgrade.ts

@@ -21,7 +21,13 @@
 import { readFile, writeFile } from "node:fs/promises";
 import { extname, relative } from "node:path";
 import { resolveCollection } from "@metaobjectsdev/sdk";
-import { rewriteDocument } from "@metaobjectsdev/metadata";
+import {
+  rewriteDocument,
+  composeRegistry,
+  coreProviders,
+  SUBTYPE_BASE,
+  retirementSuggestions,
+} from "@metaobjectsdev/metadata";
 import { log } from "../lib/log.js";
 
 /** YAML authoring (ADR-0006). Rewritten by the `yaml`-backed arm, loaded on demand below. */
@@ -96,7 +102,29 @@ export async function upgradeCommand(args: string[], cwd: string): Promise<numbe
     ? (await import("@metaobjectsdev/metadata/vocabulary-rewrite-yaml")).rewriteYamlDocument
     : undefined;
 
-  const opts = flags.maxVersion !== undefined ? { maxVersion: flags.maxVersion } : {};
+  // Which types have an ABSTRACT ANCHOR at `<type>.base`, derived from the core registry
+  // rather than listed here: `base` is an anchor exactly when the type registers some OTHER
+  // subtype for it to anchor. The rewriter is registry-free on purpose, so the caller — this
+  // command, which can build a registry — supplies the fact.
+  //
+  // Without it, `meta upgrade` answered "nothing to rewrite" on an estate whose
+  // `{"object.base": …}` the loader refuses (ERR_ABSTRACT_SUBTYPE_AUTHORED) — the change
+  // §10A of the 1.0 guide LEADS WITH. The one command whose job is "what does the new
+  // version need me to change?" said "nothing", and the adopter then hit the load failure.
+  const registry = composeRegistry(coreProviders);
+  // `allTypes()` yields one TypeId per registered type.subType pair, so take the distinct
+  // TYPE names off it.
+  const abstractAnchorTypes = [...new Set(registry.allTypes().map((id) => id.type))]
+    .filter((t) => {
+      const subs = registry.allSubTypesOf(t);
+      return subs.includes(SUBTYPE_BASE) && subs.some((sub) => sub !== SUBTYPE_BASE);
+    })
+    .sort();
+
+  const opts = {
+    abstractAnchorTypes,
+    ...(flags.maxVersion !== undefined ? { maxVersion: flags.maxVersion } : {}),
+  };
 
   for (const file of files) {
     const rel = relative(projectRoot, file);
@@ -120,10 +148,22 @@ export async function upgradeCommand(args: string[], cwd: string): Promise<numbe
     log.info(`\n${rel}`);
     for (const c of r.changes) log.info(`  ${c.line}: @${c.from} → ${c.to}`);
     for (const f of r.refusals) {
+      // The WHY and the replacement both print, and the guide is not an alternative to
+      // them. This used to read `Retired in <since>. See <guide>` — dropping `why`
+      // whenever a guide existed, which is almost always, and dropping `replacedBy`
+      // unconditionally. For the `@forge*` entries that removed the only actionable
+      // sentence there is ("opt the provider in explicitly"), and for an authored
+      // `<type>.base` it announced a retirement of something that was never authorable —
+      // telling the reader they used to have a working feature. Hence "no longer accepted
+      // as of", which is true of both, with the carefully-written `why` beside it.
       log.warn(
-        `  ${f.line}: ${f.subject}${f.value !== undefined ? `: ${f.value}` : ""} — needs a decision. ` +
-          `Retired in ${f.since}. ${f.migration !== undefined ? `See ${f.migration}` : f.why}`,
+        `  ${f.line}: ${f.subject}${f.value !== undefined ? `: ${f.value}` : ""} — needs a decision ` +
+          `(no longer accepted as of ${f.since}).`,
       );
+      log.warn(`      ${f.why}`);
+      // The same suggestion list every OTHER door prints for a retirement, rather than a
+      // second rendering of the same note that can drift from it.
+      for (const line of retirementSuggestions(f)) log.warn(`      ${line}`);
     }
 
     totalChanges += r.changes.length;