@metaobjectsdev/cli 1.0.0-rc.5 → 1.0.0-rc.7

package/dist/src/lib/wrangler.js

@@ -13,6 +13,55 @@ export function buildWranglerExecuteArgs(opts) {
     }
     return args;
 }
+/**
+ * The reason to report when wrangler exits non-zero.
+ *
+ * **`--json` puts wrangler's error on STDOUT, and warnings on stderr.** This function
+ * exists because the runner used to report stderr alone, so a live D1 gate failing for
+ * want of a `CLOUDFLARE_API_TOKEN` told the adopter its cause was
+ * `▲ [WARNING] … "unsafe" fields are experimental` — a warning, named as the reason a
+ * schema gate failed, with the real cause discarded. Found by running an estate's own
+ * `verify:prod-schema` against production for the first time.
+ *
+ * Order: the structured error wrangler wrote, then stderr, then raw stdout, then the
+ * process's own message. Stderr is still consulted — a genuine wrangler failure that
+ * never reaches stdout must not be swallowed to fix the opposite mistake.
+ */
+export function wranglerFailureReason(stdout, stderr, fallback) {
+    const structured = structuredWranglerError(stdout);
+    if (structured !== undefined)
+        return structured;
+    const err = stderr.trim();
+    if (err.length > 0)
+        return err;
+    const out = stdout.trim();
+    if (out.length > 0)
+        return out;
+    return fallback;
+}
+/** wrangler's two `--json` error shapes: `{error:{text}}` / `{error}` and the
+ *  `[{success:false,error}]` execute envelope. Anything else reads as absent. */
+function structuredWranglerError(stdout) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch {
+        return undefined;
+    }
+    const node = Array.isArray(parsed) ? parsed[0] : parsed;
+    if (node === null || typeof node !== "object")
+        return undefined;
+    const { error } = node;
+    if (typeof error === "string" && error.trim().length > 0)
+        return error.trim();
+    if (error !== null && typeof error === "object") {
+        const { text } = error;
+        if (typeof text === "string" && text.trim().length > 0)
+            return text.trim();
+    }
+    return undefined;
+}
 export const defaultWranglerRunner = async (args, cwd) => {
     try {
         const { stdout, stderr } = await execFile("wrangler", args, { cwd, maxBuffer: 16 * 1024 * 1024 });
@@ -23,8 +72,8 @@ export const defaultWranglerRunner = async (args, cwd) => {
         if (e.code === "ENOENT") {
             throw new Error(`wrangler not found on PATH; install it: 'npm i -D wrangler'`);
         }
-        const stderr = e.stderr ?? "";
-        throw new Error(`wrangler ${args.join(" ")} failed: ${stderr || e.message}`);
+        const reason = wranglerFailureReason(e.stdout ?? "", e.stderr ?? "", e.message);
+        throw new Error(`wrangler ${args.join(" ")} failed: ${reason}`);
     }
 };
 /**

package/dist/src/lib/wrangler.js.map

@@ -1 +1 @@
-{"version":3,"file":"wrangler.js","sourceRoot":"","sources":["../../../src/lib/wrangler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAEtC,MAAM,QAAQ,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;AASvC,MAAM,UAAU,wBAAwB,CAAC,IAA4B;IACnE,MAAM,IAAI,GAAa;QACrB,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,OAAO;QAC7B,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;QACpC,QAAQ;QACR,WAAW,EAAE,IAAI,CAAC,OAAO;KAC1B,CAAC;IACF,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QAClC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACzC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AASD,MAAM,CAAC,MAAM,qBAAqB,GAAmB,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;IACvE,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,QAAQ,CAAC,UAAU,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI,EAAE,CAAC,CAAC;QAClG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC5B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,CAAC,GAAG,GAAmE,CAAC;QAC9E,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;QACjF,CAAC;QACD,MAAM,MAAM,GAAG,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,MAAM,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;IAC/E,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,0BAA0B,CAAC,KAAa;IACtD,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IAC7C,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC7D,OAAO,uCAAuC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC5D,CAAC"}
+{"version":3,"file":"wrangler.js","sourceRoot":"","sources":["../../../src/lib/wrangler.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/cli",
-  "version": "1.0.0-rc.5",
+  "version": "1.0.0-rc.7",
   "description": "CLI for MetaObjects: scaffold, codegen, migrate, and drift-detection commands.",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -51,15 +51,15 @@
     "@biomejs/js-api": "^0.7.0",
     "@biomejs/wasm-nodejs": "^1.9.4",
     "@libsql/kysely-libsql": "^0.4.0",
-    "@metaobjectsdev/codegen-ts": "1.0.0-rc.5",
-    "@metaobjectsdev/codegen-ts-react": "1.0.0-rc.5",
-    "@metaobjectsdev/codegen-ts-tanstack": "1.0.0-rc.5",
-    "@metaobjectsdev/docs-site": "1.0.0-rc.5",
-    "@metaobjectsdev/metadata": "1.0.0-rc.5",
-    "@metaobjectsdev/migrate-ts": "1.0.0-rc.5",
-    "@metaobjectsdev/render": "1.0.0-rc.5",
-    "@metaobjectsdev/runtime-ts": "1.0.0-rc.5",
-    "@metaobjectsdev/sdk": "1.0.0-rc.5",
+    "@metaobjectsdev/codegen-ts": "1.0.0-rc.7",
+    "@metaobjectsdev/codegen-ts-react": "1.0.0-rc.7",
+    "@metaobjectsdev/codegen-ts-tanstack": "1.0.0-rc.7",
+    "@metaobjectsdev/docs-site": "1.0.0-rc.7",
+    "@metaobjectsdev/metadata": "1.0.0-rc.7",
+    "@metaobjectsdev/migrate-ts": "1.0.0-rc.7",
+    "@metaobjectsdev/render": "1.0.0-rc.7",
+    "@metaobjectsdev/runtime-ts": "1.0.0-rc.7",
+    "@metaobjectsdev/sdk": "1.0.0-rc.7",
     "@toon-format/toon": "^2.3.0",
     "jiti": "^2.4.0"
   },

package/src/commands/docs.ts

@@ -29,6 +29,7 @@ import {
 import type {
   GenContext,
   EmittedFile,
+  Generator,
   ResolvedDocsConfig,
   DocsSurface,
   Dialect,
@@ -41,7 +42,7 @@ import {
   DEFAULT_COLUMN_NAMING_STRATEGY,
   renderCoreMetamodelDocs,
 } from "@metaobjectsdev/metadata";
-import { dbEmittingObjects, DEFAULT_DIALECT, missingDialectMessage } from "@metaobjectsdev/codegen-ts";
+import { dbEmittingObjects, DEFAULT_DIALECT, DEFAULT_DOCS_DIR, missingDialectMessage, resolveGenerators, runEmitsHonoRoutes, runEmitsUiTier } from "@metaobjectsdev/codegen-ts";
 import type { MetaDataTypeProvider, MetaRoot } from "@metaobjectsdev/metadata";
 import { generateSite, SITE_TEMPLATE_NAMES, SITE_ASSET_NAMES, readSiteFile } from "@metaobjectsdev/docs-site";
 // The `agent` schema surface takes the physical schema as an ARGUMENT with its resolvers
@@ -53,6 +54,14 @@ import {
   qualifiedDbName,
 } from "@metaobjectsdev/migrate-ts";
 import type { AgentSchemaInput, SchemaColumnLike } from "@metaobjectsdev/codegen-ts";
+import { reportLoadError } from "../lib/load-error.js";
+
+/**
+ * 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`.
+ */
+
 
 type DocsLayout = "flat" | "package";
 
@@ -202,9 +211,14 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
     // cwd (mirrors how migrate/gen treat the working directory as the root).
     projectRoot: projectRoot ?? cwd,
     projectRootProvided: projectRoot !== undefined,
-    // Default out dir, resolved against the project root below. In --metamodel
-    // mode the renderer writes under <out>/metamodel/, default ./docs/metamodel.
-    out: out ?? (wantMetamodel ? "./docs/metamodel" : "./docs"),
+    // Default out dir, resolved against the project root below. ONE spelling of the
+    // default, shared with resolveDocsConfig — two spellings is how a flag default and
+    // a config default come to disagree about where the pages are.
+    //
+    // --metamodel keeps its own sub-path: the renderer writes under <out>/metamodel/,
+    // and it is a different artifact (the metamodel reference, not this project's
+    // pages), so it is not swept into the generated-docs directory.
+    out: out ?? (wantMetamodel ? "./docs/metamodel" : DEFAULT_DOCS_DIR),
     // Default flat preserves today's single-package output (+ existing goldens).
     layout: layout ?? "flat",
     metamodel: wantMetamodel,
@@ -464,7 +478,7 @@ export async function docsCommand(
 
   // Merge the config `docs:` block with CLI overrides over documented defaults.
   // CLI --out/--layout only override when explicitly passed; surfaces/baseUrl
-  // override whenever present. The resolver supplies defaults (outDir ./docs,
+  // override whenever present. The resolver supplies defaults (outDir ./docs/generated,
   // layout = fallback, surfaces = both) so config-less + flag-less runs are
   // unchanged.
   const cliOverrides: Partial<ResolvedDocsConfig> = {
@@ -505,7 +519,7 @@ export async function docsCommand(
       ...configLoadOptions,
     });
   } catch (err) {
-    log.error(`docs: failed to load metadata: ${(err as Error).message}`);
+    reportLoadError(log, "docs: failed to load metadata", err);
     return 2;
   }
 
@@ -527,6 +541,29 @@ export async function docsCommand(
     pkMap: buildPkMap(root),
     relationMap: buildRelationMap(root),
   });
+  // The generator suite, with stable-name STRINGS resolved to the generators they name
+  // (ADR-0021 #1 allows `generators: ["routes-hono"]`). Both aggregations below read a
+  // generator MARKER, and a string carries none — so reading the raw array answered
+  // "no Hono routes / no UI tier" for a project that wires them by name, which is the
+  // same two-doors-one-question defect these flags exist to close. `meta gen` resolves
+  // the identical array through `normalizeConfig`.
+  //
+  // An unknown name throws (the message names it and lists the valid ones). `meta gen`
+  // fails on it; `meta docs` has never had to load the suite at all, so it degrades to
+  // the already-typed entries rather than becoming a new failure — and SAYS it did,
+  // because a page quietly losing a section is exactly what this whole fix is about.
+  let suite: Generator[];
+  try {
+    suite = resolveGenerators(loadedConfig?.generators ?? []);
+  } catch (err) {
+    log.warn(
+      `docs: could not resolve the generator suite (${(err as Error).message}) — the agent ` +
+        `pages fall back to the generators declared as values, so a tier wired by name may ` +
+        `be missing from them.`,
+    );
+    suite = (loadedConfig?.generators ?? []).filter((g): g is Generator => typeof g !== "string");
+  }
+
   const ctx: GenContext = {
     entities: root.objects(),
     loadedRoot: root,
@@ -541,12 +578,14 @@ export async function docsCommand(
       // surface. Aggregate it from the generator set exactly as the gen runner
       // does (a generator opts in via emitsHonoRoutes), so `meta docs` auto-detects
       // routesFileHono() rather than relying on a field users don't normally set.
-      includeHonoRoutes:
-        loadedConfig?.includeHonoRoutes ??
-        (loadedConfig?.generators?.some(
-          (g) => typeof g !== "string" && g.emitsHonoRoutes === true,
-        ) ??
-          false),
+      includeHonoRoutes: loadedConfig?.includeHonoRoutes ?? runEmitsHonoRoutes(suite),
+      // `agent/ui.md` describes forms, grids and the endpoints their hooks call. Whether
+      // any of that is emitted is a GENERATOR fact — the page's own predicate is
+      // metadata-only and answered "could a UI be generated?", so a project with
+      // `generators: []` got a confident page naming endpoints nothing serves. Aggregate
+      // it through the same helper the gen runner uses, so `meta docs` and `meta gen` —
+      // the two doors onto this page — cannot answer it differently.
+      includeUiTier: loadedConfig?.includeUiTier ?? runEmitsUiTier(suite),
     } as never,
     renderContext,
     projectRoot,

package/src/commands/gen.ts

@@ -16,6 +16,14 @@ import {
 import { loadMemory, resolveCollection } from "@metaobjectsdev/sdk";
 import { runGen, listGenerators } from "@metaobjectsdev/codegen-ts";
 import type { WriteStatus } from "@metaobjectsdev/codegen-ts";
+import { reportLoadError } from "../lib/load-error.js";
+
+/**
+ * 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 function mapStatus(s: WriteStatus): GenFileStatus {
   switch (s) {
@@ -28,6 +36,10 @@ export function mapStatus(s: WriteStatus): GenFileStatus {
     case "unchanged":
     case "skipped":   return "unchanged";
     case "refused":   return "refused";
+    // --baseline=adopt — recorded as the merge base, nothing written. Its own word,
+    // for the same reason "overwrite" is not "new": the adopter has to know a manifest
+    // now exists to commit.
+    case "adopted":   return "adopted";
     // FR-038 §8 — a generated file deleted because it is no longer generated.
     // Shown as its own outcome, not folded into "unchanged": a run summary that
     // lists writes but hides deletions is how a silent deletion happens.
@@ -114,7 +126,7 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
       ...loadMemoryOptionsFrom(forgeConfig),
     });
   } catch (err) {
-    log.error(`failed to load metadata: ${(err as Error).message}`);
+    reportLoadError(log, "failed to load metadata", err);
     return 2;
   }
 
@@ -172,6 +184,7 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
     dryRun: cliConfig.dryRun,
     warnings: [],
     antiPatterns,
+    generatorCount: forgeConfig.generators?.length ?? 0,
   };
   const output =
     fmt === "toon" ? formatGenResultToon(genResult)

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,7 +139,9 @@ export default defineConfig({
     barrel(),
   ],
   docs: {
-    outDir:   "./docs",        // every surface lands 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 defaults to ["model", "api", "requirements", "agent"] — all four.
     // Deliberately NOT narrowed here: the requirements and agent surfaces emit ZERO
@@ -600,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);
@@ -1135,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;
@@ -1163,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,6 +58,14 @@ 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";
+
+/**
+ * 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
 
@@ -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,37 @@ 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 } : {}),
+  };
+
+  // One retirement RULE, however many occurrences it has. An estate hit this with 24
+  // `@forge*` attributes, and the per-occurrence rationale turned the output into ~96
+  // lines saying one thing four times over — the wall that buries the instruction it is
+  // made of, which is the exact failure `runGen`'s no-manifest refusal aggregates to
+  // avoid. Keyed by the rendered text, so two rules that happen to read identically
+  // collapse and two that differ anywhere do not.
+  const rules = new Map<string, { why: string; suggestions: string[]; subjects: Set<string> }>();
 
   for (const file of files) {
     const rel = relative(projectRoot, file);
@@ -120,10 +156,24 @@ 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 occurrence line is per-line information: file, line, subject, the value found.
+      // The RATIONALE that goes with it is per RULE and prints once, after the listing —
+      // see `rules` below.
       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}).`,
       );
+      const key = `${f.why}\u0000${retirementSuggestions(f).join("\u0000")}`;
+      const rule = rules.get(key);
+      if (rule === undefined) {
+        rules.set(key, {
+          why: f.why,
+          suggestions: retirementSuggestions(f),
+          subjects: new Set([f.subject]),
+        });
+      } else {
+        rule.subjects.add(f.subject);
+      }
     }
 
     totalChanges += r.changes.length;
@@ -135,6 +185,21 @@ export async function upgradeCommand(args: string[], cwd: string): Promise<numbe
   }
 
   log.info("");
+
+  // The WHY and the options, once per rule. 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"). The subject list is what lets a reader
+  // connect the paragraph back to the lines above it now that it prints away from them.
+  for (const rule of rules.values()) {
+    const subjects = [...rule.subjects].sort().join(", ");
+    log.warn(`\n  ${subjects} — why, and what to do:`);
+    log.warn(`      ${rule.why}`);
+    for (const line of rule.suggestions) log.warn(`      ${line}`);
+  }
+  if (rules.size > 0) log.info("");
+
   if (notChecked.length > 0) {
     log.warn(
       `${notChecked.length} file(s) could not be parsed and were NOT checked — fix these ` +