@metaobjectsdev/cli 0.24.5 → 0.25.0

package/src/commands/docs.ts

@@ -22,6 +22,7 @@ import {
   makeRenderContext,
   buildPkMap,
   buildRelationMap,
+  buildProjectionViews,
   resolveDocsConfig,
   apiLabel,
 } from "@metaobjectsdev/codegen-ts";
@@ -30,11 +31,28 @@ import type {
   EmittedFile,
   ResolvedDocsConfig,
   DocsSurface,
+  Dialect,
+  ColumnNamingStrategy,
 } from "@metaobjectsdev/codegen-ts";
-import { docsFile, apiDocsFile, requirementsFile } from "@metaobjectsdev/codegen-ts/generators";
-import { composeRegistry, coreProviders, renderCoreMetamodelDocs } from "@metaobjectsdev/metadata";
-import type { MetaDataTypeProvider } from "@metaobjectsdev/metadata";
+import { docsFile, apiDocsFile, requirementsFile, agentDocsFile } from "@metaobjectsdev/codegen-ts/generators";
+import {
+  composeRegistry,
+  coreProviders,
+  DEFAULT_COLUMN_NAMING_STRATEGY,
+  renderCoreMetamodelDocs,
+} from "@metaobjectsdev/metadata";
+import { dbEmittingObjects, DEFAULT_DIALECT, missingDialectMessage } 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
+// injected — codegen-ts deliberately owns none of it (see agent-schema-input.ts). THIS is
+// where the two packages meet: `meta docs` already depends on both.
+import {
+  buildExpectedSchemaWithProvenance,
+  columnTypeSql,
+  qualifiedDbName,
+} from "@metaobjectsdev/migrate-ts";
+import type { AgentSchemaInput, SchemaColumnLike } from "@metaobjectsdev/codegen-ts";
 
 type DocsLayout = "flat" | "package";
 
@@ -106,6 +124,7 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
   let wantModel = false;
   let wantApi = false;
   let wantRequirements = false;
+  let wantAgent = false;
   let wantMetamodel = false;
   let wantSite = false;
   let wantScaffoldSite = false;
@@ -133,6 +152,8 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
       wantApi = true;
     } else if (a === "--requirements") {
       wantRequirements = true;
+    } else if (a === "--agent") {
+      wantAgent = true;
     } else if (a === "--metamodel") {
       wantMetamodel = true;
     } else if (a === "--site") {
@@ -175,6 +196,7 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
   if (wantModel) surfaces.push("model");
   if (wantApi) surfaces.push("api");
   if (wantRequirements) surfaces.push("requirements");
+  if (wantAgent) surfaces.push("agent");
   return {
     // `<project-root>` is the project root that CONTAINS the metadata; default
     // cwd (mirrors how migrate/gen treat the working directory as the root).
@@ -197,7 +219,99 @@ function parseDocsArgs(argv: string[], cwd: string): DocsFlags {
   };
 }
 
-export async function docsCommand(args: string[], cwd: string): Promise<number> {
+/**
+ * How a caller other than the CLI wants `meta docs` to behave.
+ *
+ * `verify --docs` runs this exact command into a temp directory and diffs the result, so
+ * that the gate and the door can never be two implementations of "what the docs are". The
+ * only thing it needs differently is silence: a verify run announcing "meta docs — wrote 8
+ * entity pages" in the middle of its own report describes work the user is not getting.
+ */
+export interface DocsCommandOptions {
+  /** Suppress the informational output. Warnings and errors still print — a docs run that
+   *  degraded is something a verify caller must see, not something to swallow. */
+  silent?: boolean;
+}
+
+/**
+ * The physical schema `agent/schema.md` renders from, built by the package that OWNS it
+ * (`migrate-ts`) with its own resolvers handed across — see codegen-ts's
+ * agent-schema-input.ts for why the docs generator refuses to compute any of this itself.
+ *
+ * Returns undefined, after warning, when the page is to be SKIPPED — and a skipped page is
+ * not a silent pass: `verify --docs` convicts a committed `agent/<page>.md` that a fresh
+ * run no longer emits (see lib/docs-drift.ts), so a page describing the previous schema
+ * fails the gate rather than surviving it on exactly the change it most needs to flag.
+ */
+function buildAgentSchemaInput(
+  root: MetaRoot,
+  configured: Dialect | undefined,
+  strategy: ColumnNamingStrategy,
+): AgentSchemaInput | undefined {
+  // THE RUNNER'S OWN GUARD DECIDES THIS, not a default applied here.
+  //
+  // `DEFAULT_DIALECT` is INERT: `runGen` throws when a model emits database code and the
+  // config declares no dialect, and it throws BEFORE `normalizeConfig` fills that default
+  // in, precisely so a DB project that forgot one gets a named error instead of
+  // "a Postgres project quietly emitting sqlite". So a persisted model with no dialect is
+  // not a sqlite project — it is a project `meta gen` REFUSES. Documenting it as sqlite
+  // would state an answer the toolchain never gave, about a schema it will not build.
+  //
+  // Two wrong answers were tried here before this one, and both were ASSERTIONS. First a
+  // hardcoded `?? "sqlite"`; then a skip whenever `dialect` was absent, on the theory that
+  // an undeclared dialect is an unknown one. The compute answer is to ask the predicate
+  // `runGen` asks — `dbEmittingObjects` — and skip only when that guard would fire. A model
+  // with no persisted object needs no dialect and renders an empty schema page anyway, so
+  // the inert default is correct for exactly the projects the guard lets through.
+  const dbEmitting = dbEmittingObjects(root.objects());
+  if (dbEmitting.length > 0 && configured === undefined) {
+    log.warn(
+      `docs: agent/schema.md skipped — ${missingDialectMessage(dbEmitting)} ` +
+        `('meta gen' refuses this model for the same reason.)`,
+    );
+    return undefined;
+  }
+  const dialect = configured ?? DEFAULT_DIALECT;
+  try {
+    const built = buildExpectedSchemaWithProvenance(root, {
+      dialect,
+      columnNamingStrategy: strategy,
+      // Views come from codegen-ts (migrate-ts never generates view DDL), exactly as
+      // `verify --db` threads them.
+      views: buildProjectionViews(root, { dialect, columnNamingStrategy: strategy }),
+    });
+    return {
+      dialect,
+      tables: built.snapshot.tables,
+      views: built.snapshot.views,
+      provenance: built.provenance,
+      // The structural `SchemaColumnLike` is migrate-ts's own ColumnDescriptor,
+      // narrowed to what the page reads; the cast hands the full descriptor back to
+      // the renderer that produced it.
+      columnType: (c: SchemaColumnLike) => columnTypeSql(c as never, dialect),
+      qualify: qualifiedDbName,
+    };
+  } catch (err) {
+    // A model the schema builder refuses is a real condition (a primary-key move, a
+    // duplicate physical name) that `meta migrate` will report properly. Docs must not
+    // be the command that fails on it, so the schema page is skipped and the other two
+    // agent pages still emit.
+    log.warn(
+      `docs: agent/schema.md skipped — the expected schema could not be built ` +
+        `(${(err as Error).message}). Run 'meta migrate' for the full diagnosis.`,
+    );
+    return undefined;
+  }
+}
+
+export async function docsCommand(
+  args: string[],
+  cwd: string,
+  opts?: DocsCommandOptions,
+): Promise<number> {
+  // Informational output only. `log.warn` / `log.error` are deliberately NOT routed
+  // through this: a skipped surface or a failed render is a finding either way.
+  const info = opts?.silent === true ? (_m: string): void => {} : log.info;
   let flags: DocsFlags;
   try {
     flags = parseDocsArgs(args, cwd);
@@ -211,6 +325,33 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
   // NEITHER a user's metadata NOR a config — there is nothing to load. It writes
   // the renderer's files under <out>/metamodel/ (default ./docs/metamodel).
   if (flags.metamodel) {
+    // `--site` builds HTML from a MODEL — docs-site's own loader and templates over the
+    // user's metadata. The metamodel surface is a different renderer entirely, over the
+    // registry, and it emits markdown; there is no renderer here to bridge them. The flag
+    // used to be parsed, accepted and then dropped by this very return: the command wrote
+    // sixteen markdown files, printed a success line and exited 0, so asking for a site
+    // produced no site and no complaint.
+    //
+    // It refuses rather than growing an HTML renderer, which would put a markdown-
+    // rendering dependency into a published package for one surface. The website renders
+    // it instead, keeping that dependency dev-only and giving the pages the metaobjects.dev
+    // look rather than the docs-site adopter theme.
+    // `--scaffold-site` is here for the same reason and was missed the first time: it is
+    // the OTHER flag that asks for files to be written, and this same early return dropped
+    // it identically — `--metamodel --scaffold-site` wrote 16 markdown pages, scaffolded no
+    // theme anywhere, and exited 0. Fixing one of a matched pair leaves the defect wearing
+    // a different flag name.
+    const dropped = [
+      ...(flags.site ? ["--site"] : []),
+      ...(flags.scaffoldSite ? ["--scaffold-site"] : []),
+    ];
+    if (dropped.length > 0) {
+      log.error(
+        `docs: ${dropped.join(" and ")} ${dropped.length > 1 ? "are" : "is"} not supported ` +
+        "with --metamodel. The metamodel reference is markdown; the rendered form is " +
+        "published at https://metaobjects.dev/reference");
+      return 2;
+    }
     return metamodelDocsCommand(cwd, flags.out);
   }
 
@@ -376,6 +517,13 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
     loadedRoot: root,
     outDir,
     dbImport: "",
+    // The project's own prefix, not the "" default. `agent/ui.md` documents an ENDPOINT,
+    // and the routes generator mounts every one of them inside
+    // `fastify.register(…, { prefix: apiPrefix })` — so a project configuring "/api" is
+    // served at /api/authors and was being told, by the page whose whole job is to be
+    // right about addresses, that it was /authors. `meta gen` threads this (runner.ts);
+    // `meta docs` is the OTHER door onto the same page and did not.
+    apiPrefix: loadedConfig?.apiPrefix ?? "",
     pkMap: buildPkMap(root),
     relationMap: buildRelationMap(root),
   });
@@ -498,16 +646,46 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
       // Surfaces owned by other ports: link only, with a pointer to where they
       // get produced.
       for (const s of labeled.filter((s) => s.lang !== "ts")) {
-        log.info(
+        info(
           `meta docs: api surface '${s.lang}' (${s.subDir}) is produced by that port's docs command — run it to populate those pages.`,
         );
       }
     } else if (hasConfig) {
       // Config present but failed to load — already warned above; don't claim an
       // api surface we couldn't build.
-      log.info("meta docs: api surface skipped — metaobjects.config.ts failed to load.");
+      info("meta docs: api surface skipped — metaobjects.config.ts failed to load.");
+    } else {
+      info("meta docs: api surface skipped — no metaobjects.config.ts (nothing generated to document).");
+    }
+  }
+
+  // AGENT surface — three pages an agent reads BEFORE touching a tier (`agent/schema.md`
+  // before persistence, `agent/ui.md` before a form or grid, `agent/requirements.md`
+  // before adding a capability). The fourth file the always-on pointer names,
+  // `api/AGENT-API.md`, belongs to the api surface above.
+  //
+  // Gated on a loadable gen config exactly as `api` is, and for a stronger reason: the
+  // physical schema depends on the project's DIALECT and column-naming strategy, and the
+  // neutral model surface above runs on a placeholder because it documents no SQL at all.
+  // The dialect here is the project's own, resolved by the same default `meta gen` and
+  // `meta migrate` apply — see `buildAgentSchemaInput`.
+  if (docsCfg.surfaces.includes("agent")) {
+    if (loadedConfig !== undefined) {
+      const strategy = loadedConfig.columnNamingStrategy ?? DEFAULT_COLUMN_NAMING_STRATEGY;
+      const schema = buildAgentSchemaInput(root, loadedConfig.dialect, strategy);
+      emit.push(
+        ...(await agentDocsFile({
+          ...(schema !== undefined && { schema }),
+          columnNamingStrategy: strategy,
+        }).generate(ctx)),
+      );
+    } else if (hasConfig) {
+      info("meta docs: agent surface skipped — metaobjects.config.ts failed to load.");
     } else {
-      log.info("meta docs: api surface skipped — no metaobjects.config.ts (nothing generated to document).");
+      info(
+        "meta docs: agent surface skipped — no metaobjects.config.ts (the physical schema " +
+          "and the generated UI are what it describes).",
+      );
     }
   }
 
@@ -548,7 +726,15 @@ export async function docsCommand(args: string[], cwd: string): Promise<number>
   // did not run — the opposite of the silence the empty-ledger guard exists to produce.
   const requirementFiles = emit.filter((f) => f.path.startsWith("requirements.")).length;
   const reqSummary = requirementFiles > 0 ? `; ${requirementFiles} requirement file(s)` : "";
-  log.info(`meta docs — wrote ${modelSummary}; ${apiSummary}${reqSummary} → ${outDir}`);
+  // Same rule as the requirements line: NAMED rather than counted, and only when written.
+  // Each agent page is skipped when its tier has nothing to describe, so "3 agent pages"
+  // would leave a reader unable to tell which three — and the pages are the thing the
+  // always-on agent context points at by name.
+  const agentPages = emit
+    .filter((f) => f.path.startsWith("agent/"))
+    .map((f) => basename(f.path));
+  const agentSummary = agentPages.length > 0 ? `; agent/${agentPages.sort().join(" + agent/")}` : "";
+  info(`meta docs — wrote ${modelSummary}; ${apiSummary}${reqSummary}${agentSummary} → ${outDir}`);
   return 0;
 }
 

package/src/commands/eject.ts

@@ -1,6 +1,6 @@
 // FR-040 §4.2(a) — `meta eject <generator>` takes ownership of any reference-template
 // generator, in any package, at any time after `meta init`. ADR-0034 scaffold-and-own
-// has `init` copy four of them eagerly (entity, queries, routes, barrel); this is the
+// has `init` copy five of them eagerly (entity, queries, routes, barrel, names); this is the
 // SAME copy operation, generalised to every ejectable name and callable on demand — for
 // a generator you skipped at init time, or one a package gained since.
 import { mkdir, writeFile, stat, readFile } from "node:fs/promises";
@@ -147,7 +147,7 @@ function requiredPackages(templateSource: string): string[] {
  * declared dependencies or their `tsc` reports TS2307 on the file we just told them
  * they own — and under a strict (pnpm/npm) node_modules layout `meta gen` cannot
  * resolve it either. `meta init` already calls this out by ADDING the two packages its
- * four scaffolded generators need; the on-demand templates import two more
+ * five scaffolded generators need; the on-demand templates import two more
  * (codegen-ts-react, codegen-ts-tanstack) that nothing declares.
  *
  * This REPORTS rather than edits: init is a scaffolder writing a whole project and has
@@ -255,7 +255,7 @@ export async function ejectCommand(args: string[], cwd: string): Promise<number>
     //
     // But eject reads no config, so it cannot know WHICH of the three states this project
     // is in, and stating one of them as fact is wrong in the other two — including for the
-    // four `meta init` scaffolds, whose config already imports from ./codegen/generators/,
+    // five `meta init` scaffolds, whose config already imports from ./codegen/generators/,
     // which is precisely the `meta eject <name> --force` re-sync case. Name the goal, then
     // the three branches; the reader knows which one they are looking at.
     log.info(`In metaobjects.config.ts, "${result.exportName}" must resolve to this file:`);

package/src/commands/gen.ts

@@ -9,6 +9,10 @@ import { log } from "../lib/log.js";
 import { warnIfAgentContextStale } from "../lib/agent-context-staleness.js";
 import { warnIfManifestIgnored } from "../lib/manifest-ignored-check.js";
 import { scanSourceForAntiPatterns } from "../lib/anti-patterns.js";
+import {
+  antiPatternRows, ranSection, skippedSection, warnCapped,
+  type AdvisoryFindingRow, type AdvisorySection,
+} from "../lib/advisory.js";
 import { loadMemory, resolveCollection } from "@metaobjectsdev/sdk";
 import { runGen, listGenerators } from "@metaobjectsdev/codegen-ts";
 import type { WriteStatus } from "@metaobjectsdev/codegen-ts";
@@ -149,12 +153,23 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
     (forgeConfig.targets ? Object.values(forgeConfig.targets).map((t) => t.outDir) : [])
       .concat([forgeConfig.outDir]),
   ));
+
+  // The advisory verify-as-teacher pass now runs BEFORE the result is rendered,
+  // because its findings ride IN the result. It used to run after the payload was
+  // printed and write only to stderr as text, so `meta gen --format json` on a run
+  // with hundreds of findings emitted a document that mentioned none of them — the
+  // structured output being the documented default for an agent on a pipe.
+  // Warnings ONLY — nothing here reaches the exit code (bias to under-flagging).
+  const antiPatterns = runAntiPatternScan(
+    projectRoot, cliConfig.dryRun, flags.noAntipatterns, forgeConfig.verify?.antiPatternIgnore);
+
   const genResult = {
     files,
     outDir: targetDirs.length > 1 ? targetDirs.join(", ") : forgeConfig.outDir,
     dialect: forgeConfig.dialect,
     dryRun: cliConfig.dryRun,
     warnings: [],
+    antiPatterns,
   };
   const output =
     fmt === "toon" ? formatGenResultToon(genResult)
@@ -175,31 +190,51 @@ export async function genCommand(args: string[], cwd: string, fmt: OutputFormat
     );
   }
 
-  // Advisory verify-as-teacher pass (same as `meta verify`): on a real write run,
-  // surface authored source that hand-rolls what the metadata could model. `gen`
-  // is the command an agent always runs, so this is where the teaching actually
-  // reaches it. Warnings ONLY — never affects the exit code. Suppress with
-  // --no-antipatterns or META_NO_ANTIPATTERNS=1 (both opt-outs work on `meta gen`
-  // and `meta verify`).
-  if (!cliConfig.dryRun && !flags.noAntipatterns && process.env.META_NO_ANTIPATTERNS !== "1") {
-    try {
-      const findings = scanSourceForAntiPatterns(projectRoot);
-      if (findings.length > 0) {
-        const CAP = 10;
-        log.warn(
-          `\nmeta gen — ${findings.length} place(s) hand-roll what MetaObjects can model ` +
-            `(advisory — declaring the construct lets codegen own it):`,
-        );
-        for (const f of findings.slice(0, CAP)) log.warn(`  ${f.message}`);
-        if (findings.length > CAP) log.warn(`  …and ${findings.length - CAP} more.`);
-      }
-    } catch { /* never let an advisory scan break gen */ }
+  // The human-readable half of the advisory pass, printed after the file listing
+  // where a reader expects it. Capped for a terminal; the structured payload above
+  // already carried every finding, and the tail line says so.
+  if (antiPatterns.total > 0) {
+    log.warn(
+      `\nmeta gen — ${antiPatterns.total} place(s) hand-roll what MetaObjects can model ` +
+        `(advisory — declaring the construct lets codegen own it):`,
+    );
+    warnCapped(antiPatterns.rows.map((r) => `  ${r.message}`), flags.limit, { structured: fmt !== "text" });
   }
 
   const hasFailure = files.some((f) => f.status === "conflict" || f.status === "refused");
   return hasFailure ? 1 : 0;
 }
 
+/**
+ * Run the advisory verify-as-teacher scan (same pass `meta verify` runs): surface
+ * authored source that hand-rolls what the metadata could model. `gen` is the
+ * command an agent always runs, so this is where the teaching actually reaches it.
+ *
+ * Returns the section EITHER WAY — a skip is reported with its reason rather than
+ * dropped, so a reader can tell "found nothing" from "never looked". Warnings only;
+ * it can never affect the exit code. Suppress with --no-antipatterns or
+ * META_NO_ANTIPATTERNS=1 (both opt-outs work on `meta gen` and `meta verify`).
+ */
+function runAntiPatternScan(
+  projectRoot: string,
+  dryRun: boolean,
+  noAntipatterns: boolean,
+  ignore: readonly string[] | undefined,
+): AdvisorySection<AdvisoryFindingRow> {
+  // A --dry-run writes nothing, so it teaches nothing; the scan is skipped, as it
+  // always has been. The payload now says that instead of looking clean.
+  if (dryRun) return skippedSection("skipped on --dry-run (the advisory pass runs on a real write run)");
+  if (noAntipatterns) return skippedSection("suppressed by --no-antipatterns");
+  if (process.env.META_NO_ANTIPATTERNS === "1") return skippedSection("suppressed by META_NO_ANTIPATTERNS=1");
+  try {
+    return ranSection(antiPatternRows(scanSourceForAntiPatterns(
+      projectRoot, ignore !== undefined ? { ignore } : undefined)));
+  } catch (err) {
+    // Never let an advisory scan break gen — but never claim it found nothing either.
+    return skippedSection(`the scan failed: ${(err as Error).message}`);
+  }
+}
+
 /**
  * `meta gen --list` — print the stable-name generator registry (ADR-0021 D3).
  *

package/src/commands/init.ts

@@ -1,4 +1,4 @@
-import { mkdir, writeFile, readFile, readdir, stat } from "node:fs/promises";
+import { mkdir, writeFile, readFile, readdir, stat, rm } from "node:fs/promises";
 import { join } from "node:path";
 import { basename, dirname } from "node:path";
 import { existsSync as existsSyncWrap, readFileSync as readFileSyncWrap } from "node:fs";
@@ -19,7 +19,7 @@ import { readReferenceTemplate, type ReferenceGeneratorName } from "@metaobjects
 // the consumer's repo so they OWN them; metaobjects.config.ts imports them locally.
 const OWNED_GENERATORS_DIR = "codegen/generators";
 
-// The FOUR reference generators `meta init` copies EAGERLY — deliberately an explicit
+// The FIVE reference generators `meta init` copies EAGERLY — deliberately an explicit
 // literal, not derived from @metaobjectsdev/codegen-ts's REFERENCE_GENERATOR_NAMES (the
 // full list of everything `meta eject` can copy). Looping over that array unconditionally
 // used to mean init scaffolded whatever it contained: when a later task registered
@@ -28,7 +28,13 @@ const OWNED_GENERATORS_DIR = "codegen/generators";
 // scaffolded metaobjects.config.ts's import list (buildMetaobjectsConfigBody below) made
 // explicit and checkable — anything else is eject-on-demand via `meta eject <name>`, which
 // exists exactly so eager copying isn't the only way to take ownership of a template.
-const SCAFFOLDED_GENERATOR_NAMES: readonly ReferenceGeneratorName[] = ["entity", "queries", "routes", "barrel"];
+//
+// "names" joined this list by spec §A5's ruling, not by falling out of the general rule
+// above: TypeScript is opt-in by construction under ADR-0034 (meta gen runs the adopter's
+// copy, so a packaged change to a generator can never reach anyone who has ejected), so
+// the honest maximum for the names artifact is every NEW `meta init` getting it and every
+// existing project adding one config line by hand.
+export const SCAFFOLDED_GENERATOR_NAMES: readonly ReferenceGeneratorName[] = ["entity", "queries", "routes", "barrel", "names"];
 
 // The scaffolded config's outDir + dbImport, as named constants so the throwing-stub
 // path below is DERIVED from the same values the config template embeds rather than
@@ -105,6 +111,7 @@ function buildMetaobjectsConfigBody(dialect: "sqlite" | "postgres" | "d1" = "sql
 import { entityFile } from "./codegen/generators/entity.js";
 import { queriesFile } from "./codegen/generators/queries.js";
 import { routesFile } from "./codegen/generators/routes.js";
+import { namesFile } from "./codegen/generators/names.js";
 import { barrel } from "./codegen/generators/barrel.js";
 
 export default defineConfig({
@@ -126,6 +133,7 @@ export default defineConfig({
     entityFile(),
     queriesFile(),
     routesFile(),
+    namesFile(),   // <Entity>Names — physical table/column constants (spec §A1/§A5)
     barrel(),
   ],
   docs: {
@@ -246,6 +254,8 @@ export interface InitOptions {
 export interface InitResult {
   created: string[];
   preserved: string[];
+  /** agent-context files deleted because this stack no longer assembles them. */
+  removed: string[];
   warnings: string[];
 }
 
@@ -324,6 +334,12 @@ async function writeUnlessDryRun(cwd: string, dryRun: boolean, path: string, con
   await writeFile(abs, contents, "utf8");
 }
 
+/** Delete twin of writeUnlessDryRun — a dry run must not remove anything either. */
+async function removeUnlessDryRun(cwd: string, dryRun: boolean, path: string): Promise<void> {
+  if (dryRun) return;
+  await rm(join(cwd, path), { force: true });
+}
+
 /** "would be VERBED" during a dry run, plain VERBED otherwise — the one tense
  *  marker every reported write shares, so each call site states only its own
  *  past participle instead of writing out both tenses of the whole sentence. */
@@ -387,8 +403,21 @@ async function writeAgentContext(opts: InitOptions, result: InitResult): Promise
   );
   result.created.push(AGENT_CONTEXT_MANIFEST_PATH);
 
+  // A fragment this stack no longer assembles. `prunes` are ones we wrote that nobody has
+  // touched — deleting is exactly as safe as the overwrite the same hash predicate already
+  // authorises above, and leaving them contradicts every SKILL.md footer, which tells the
+  // reader to read every references/*.md "one per server language in this project's stack".
+  for (const orphan of decision.prunes) {
+    await removeUnlessDryRun(opts.cwd, dryRun, orphan);
+    result.removed.push(orphan);
+  }
+  // Hand-edited ones are never deleted — losing an adopter's writing is worse than leaving
+  // a stale file behind — so they are named, with the reason and the remedy.
   for (const orphan of decision.removed) {
-    result.warnings.push(`${orphan} is no longer part of this stack; orphaned (safe to delete).`);
+    result.warnings.push(
+      `${orphan} is no longer part of this stack but appears hand-edited, so it was kept; ` +
+      "delete it yourself once you have salvaged anything you want from it.",
+    );
   }
 
   if (opts.wireRoot) await wireRootMemory(opts.cwd, result, dryRun);
@@ -426,7 +455,7 @@ async function wireRootMemory(cwd: string, result: InitResult, dryRun = false):
  * so a re-run with --force never clobbers a hand-edited generator. The scaffolded
  * metaobjects.config.ts imports these local copies (not the package `/generators` export).
  *
- * Copies SCAFFOLDED_GENERATOR_NAMES only — the four the scaffolded config actually
+ * Copies SCAFFOLDED_GENERATOR_NAMES only — the five the scaffolded config actually
  * wires — not every name @metaobjectsdev/codegen-ts happens to register. Anything else
  * (routes-hono, and any UI-tier template from codegen-ts-react/-tanstack) is reached with
  * `meta eject <name>`, not by eager copying.
@@ -513,7 +542,7 @@ async function writeConfigFile(opts: InitOptions, result: InitResult, agentDir:
 }
 
 export async function init(opts: InitOptions): Promise<InitResult> {
-  const result: InitResult = { created: [], preserved: [], warnings: [] };
+  const result: InitResult = { created: [], preserved: [], removed: [], warnings: [] };
   const agentDir = join(opts.cwd, DEFAULT_METAOBJECTS_DIR);
   const metaobjectsDir = join(opts.cwd, DEFAULT_METADATA_DIR);