@metaobjectsdev/codegen-ts 0.24.4 → 0.25.0

package/src/constants.ts

@@ -1,28 +1,103 @@
 // Local constants for codegen-ts.
 
-/** The marker that says "codegen owns this file" — drives the overwrite policy. */
+/**
+ * The header line every emitter puts at the top of a generated file.
+ *
+ * Informational ON THIS PORT. It used to be documented here as the thing that "drives
+ * the overwrite policy", and it does not: `overwrite-policy.ts` decides from the
+ * `.gen-state` snapshot body and the committed hash manifest and never reads this
+ * string (grep it — no non-template module imports it). Deleting the header from a
+ * generated file does not take ownership of it here; it just changes the content, so
+ * the hash stops matching and the file is refused like any other edit.
+ *
+ * The JVM ports are the opposite: there the marker IS the decision
+ * (`GeneratedFileWriter`), and deleting it is exactly how you take ownership. Both
+ * behaviours are stated in `docs/features/own-your-codegen.md` — do not collapse them
+ * into one sentence, because the gesture that protects a file differs per port.
+ */
 export const GENERATED_HEADER = "@generated by @metaobjectsdev/codegen-ts";
 
-/** Suffix for sibling user extension files (codegen never touches these). */
-export const EXTRA_SUFFIX = ".extra";
+// `EXTRA_SUFFIX = ".extra"` was removed here. It was a public export of this package
+// wired to nothing: no generator, orphan sweep or write path ever compared a path
+// against it, so its presence implied tool support for a name that is pure convention.
+// A `<Entity>.extra.ts` sibling is safe because codegen only writes the paths it
+// records in `.gen-state/.hashes.json` — not because of its name — and the generated
+// barrel is built from the model, so it does not re-export it. Say that in prose;
+// do not re-add a constant that suggests the engine knows the name.
 
 /** Default outDir used by tests + as a sane default for generate(). */
 export const DEFAULT_OUT_DIR = "./src/db/entities";
 
 // ---------------------------------------------------------------------------
-// Codegen-control attributes.
+// Retired codegen-control attributes.
 //
-// These are per-entity opt-in/opt-out flags read by generators (NOT metamodel
-// vocabulary — they tune codegen, not the model). Named here so the literals
-// aren't scattered as magic strings across the generator packages (compile-time
-// typo safety), matching the metadata package's constants discipline.
+// `@emitRoutes` / `@emitTanstack` / `@emitForm` / `@emitGrid` / `@emitAngular`
+// were read off metadata by generator filters and were NEVER registered
+// metamodel vocabulary. The strict loader rejects every one of them with
+// ERR_UNKNOWN_ATTR — and `meta verify` loads strict — while `meta gen` loads
+// non-strict and honoured them. So an adopter who authored the documented
+// per-entity opt-out got the behaviour AND a red `meta verify`: half-working,
+// which is worse than either half, and exactly the class ADR-0023 §2 names.
+//
+// Registering them was refused. That moves `metamodelVersion` and forces a
+// four-registry publish for a TypeScript-only generator kill switch that four
+// of five ports would never read. The replacement already exists and is
+// verified end to end: decide per generator what you consume — wire only the
+// generators whose output you actually import, and narrow one with its
+// `filter` option. The one clause that was opt-IN rather than opt-out (a TPH
+// subtype's own per-subtype grid) cannot be a `filter`, since a filter is
+// ANDed with the built-in gates and can only NARROW; it is the
+// `tphSubtypeGrids` option on tanstackGrid()/tanstackGridHook() instead.
+//
+// No generator reads any of these names now. They survive HERE and nowhere
+// else, so `meta gen` can recognise a stale one still sitting in an adopter's
+// metadata and say what replaced it (see retired-codegen-attrs.ts). Keeping
+// the name and its replacement in ONE record is the point: a warning whose
+// text lives apart from the list it is warning about drifts from it.
 // ---------------------------------------------------------------------------
 
-/** `@emitTanstack: false` — skip the TanStack hooks + grid generators for an entity. */
-export const CODEGEN_ATTR_EMIT_TANSTACK = "emitTanstack";
-/** `@emitGrid: true` — opt a TPH subtype IN to its own per-subtype grid (default: the polymorphic base grid is the single source). */
-export const CODEGEN_ATTR_EMIT_GRID = "emitGrid";
-/** `@emitForm: false` — skip the React form generator for an entity. */
-export const CODEGEN_ATTR_EMIT_FORM = "emitForm";
-/** `@emitRoutes: false` — skip the Fastify routes generator for an entity. */
-export const CODEGEN_ATTR_EMIT_ROUTES = "emitRoutes";
+/** One retired codegen-control attribute, paired with what an adopter does instead. */
+export interface RetiredCodegenAttr {
+  /** The bare attribute name, as it appears in metadata (no `@` sigil). */
+  readonly name: string;
+  /** What to do instead, phrased as an instruction and naming a real API. */
+  readonly replacement: string;
+}
+
+/** Every retired codegen-control attribute. Read ONLY by the `meta gen` warning. */
+export const RETIRED_CODEGEN_ATTRS: readonly RetiredCodegenAttr[] = [
+  {
+    name: "emitRoutes",
+    replacement:
+      'drop routesFile() / routesFileHono() from `generators` in metaobjects.config.ts if ' +
+      'you do not consume REST routes, or narrow it — routesFile({ filter: (e) => e.name !== "Ledger" })',
+  },
+  {
+    name: "emitTanstack",
+    replacement:
+      'drop tanstackQuery() / tanstackGrid() / tanstackGridHook() from `generators` in ' +
+      'metaobjects.config.ts if you do not consume their output, or narrow one — ' +
+      'tanstackQuery({ filter: (e) => e.name !== "InternalAudit" })',
+  },
+  {
+    name: "emitForm",
+    replacement:
+      'drop formFile() from `generators` in metaobjects.config.ts if you do not consume ' +
+      'generated forms, or narrow it — formFile({ filter: (e) => e.name !== "InternalAudit" })',
+  },
+  {
+    name: "emitGrid",
+    replacement:
+      'pass the `tphSubtypeGrids` option — tanstackGrid({ tphSubtypeGrids: (e) => e.name === ' +
+      '"CopayAuth" }) — and pass the SAME predicate to tanstackGridHook(), or the emitted ' +
+      '<Sub>.grid.ts has no <Sub>.columns.tsx to import. This one is an opt-IN, so a `filter` ' +
+      'cannot express it: a filter is ANDed with the built-in gates and can only narrow',
+  },
+  {
+    name: "emitAngular",
+    replacement:
+      'drop angularServiceFile() / angularFormFile() / angularGridFile() from `generators` in ' +
+      'metaobjects.config.ts if you do not consume Angular output, or narrow one — ' +
+      'angularServiceFile({ filter: (e) => e.name !== "InternalAudit" })',
+  },
+] as const;

package/src/db-emitting.ts

@@ -0,0 +1,31 @@
+// Which objects make a project a DATABASE project — and therefore require a `dialect`.
+//
+// THIS IS THE ONE ANSWER, and it is hoisted here because two commands need it and a second
+// copy would be a second answer. `runGen` throws when a model emits database code and the
+// config declares no dialect (see `missingDialectMessage`), and it throws BEFORE
+// `normalizeConfig` fills its defaults on purpose: `DEFAULT_DIALECT` is INERT, existing
+// only so a value-object-only project need not name one. A DB project that forgot it gets
+// a named error rather than silently-defaulted output — "a Postgres project quietly
+// emitting sqlite", as the runner's own comment puts it.
+//
+// `meta docs` needs the same answer for `agent/schema.md`. Reading `?? DEFAULT_DIALECT`
+// there instead would document a sqlite schema for a project `meta gen` refuses to build
+// — asserting an answer the toolchain never gave.
+
+import type { MetaObject } from "@metaobjectsdev/metadata";
+import { hasAnyRdbSource } from "./source-detect.js";
+
+/** The concrete objects a run would emit database code for. Empty ⇒ no dialect needed. */
+export function dbEmittingObjects(entities: readonly MetaObject[]): MetaObject[] {
+  return entities.filter((e) => !e.isAbstract && hasAnyRdbSource(e));
+}
+
+/** The one wording for "this model needs a dialect and the config has none". */
+export function missingDialectMessage(dbEmitting: readonly MetaObject[]): string {
+  const names = dbEmitting.map((e) => e.name).join(", ");
+  return (
+    `codegen config is missing dialect — required because this model ` +
+    `generates database code for: ${names}. Set dialect in ` +
+    `metaobjects.config.ts. (A model of only value objects and/or sourceless projections may omit it.)`
+  );
+}

package/src/generator-registry.ts

@@ -25,6 +25,7 @@ import {
   routesFile,
   routesFileHono,
   barrel,
+  namesFile,
   mermaidErDiagram,
   promptRender,
   outputParser,
@@ -111,6 +112,12 @@ export const generatorRegistry: Record<string, GeneratorRegistryEntry> = {
     factory: () => barrel(),
     options: "target?",
   },
+  names: {
+    name: "names",
+    description: "Per-entity physical database name constants (table/view, schema, columns).",
+    tier: "native",
+    factory: () => namesFile(),
+  },
   "prompt-render": {
     name: "prompt-render",
     description: "Per-template prompt-render helper over the render engine.",

package/src/generator.ts

@@ -63,6 +63,11 @@ export interface Generator {
    *  that Hono routes are actually being emitted and document them — rather than
    *  silently omitting the Hono CRUD registrars whenever the variant is wired. */
   emitsHonoRoutes?: boolean;
+  /** §A6 — marks the generator that emits the <Entity>Names artifact. The runner
+   *  aggregates this across the suite into ResolvedGenConfig.includeNames, which the
+   *  entity generator reads to decide whether it may reference those constants.
+   *  Same mechanism as emitsHonoRoutes/includeHonoRoutes. */
+  emitsNames?: boolean;
 }
 
 export type GeneratorFactory<TOpts = void> = TOpts extends void

package/src/generators/agent-docs-file.ts

@@ -0,0 +1,297 @@
+// agentDocsFile() — the `agent` docs surface.
+//
+// Three pages under `agent/`, each one an agent reads BEFORE touching a tier:
+//
+//   • `agent/schema.md`       — before touching persistence
+//   • `agent/ui.md`           — before touching a form or a grid
+//   • `agent/requirements.md` — before adding a capability
+//
+// (`api/AGENT-API.md`, the fourth file the always-on pointer names, is the api surface's
+// and is emitted by `apiDocsFile()`. It is not duplicated here.)
+//
+// EVERY PAGE IS DERIVED FROM AN EXISTING BUILDER, and that is the design constraint
+// rather than an implementation detail. A documentation surface an agent is told to
+// TRUST has to be true, and the only way to keep three more pages true is to give them
+// no derivation of their own:
+//
+//   schema        ← the expected-schema snapshot `meta migrate` diffs and emits from
+//                   (injected; see agent-schema-input.ts for why codegen-ts refuses to
+//                   compute it) + `resolveObjectNames`, the field→column resolver the
+//                   names artifact and the DDL already share
+//   ui            ← `buildEntityUiDescriptor`, the same derivation emitted as the
+//                   `<Entity>` const that `useEntityForm` reads at runtime
+//   requirements  ← `walkRequirements` + `requirementRows`, the same walk the ledger
+//                   surface and the generated test stubs are built on
+//
+// CONFIG-GATED, like the api surface. Physical names, the dialect and view dispatch all
+// depend on the gen config, so `meta docs` only selects this surface when it has one.
+// The NEUTRAL model surface stays neutral (ADR-0020); this is a different surface with a
+// different contract, not a relaxation of that one.
+//
+// AN EMPTY PAGE IS NO FILE. Each renderer returns "" when its tier has nothing to
+// describe — no physical schema, no UI, no ledger — and an empty render emits nothing.
+// That is what makes the surface safe to leave on: a headless project with no ledger sees
+// no `agent/` directory rather than three pages of headings.
+//
+// These files are READ, never imported. There is no three-way merge and no hand-edit
+// preservation to think about: regenerate and the page is current.
+
+import {
+  CARDINALITY_MANY,
+  CARDINALITY_ONE,
+  FIELD_SUBTYPE_ENUM,
+  ORIGIN_AGGREGATE_ATTR_AGG,
+  ORIGIN_AGGREGATE_ATTR_OF,
+  ORIGIN_AGGREGATE_ATTR_VIA,
+  ORIGIN_ATTR_ORDER_BY,
+  ORIGIN_PASSTHROUGH_ATTR_FROM,
+  ORIGIN_PASSTHROUGH_ATTR_VIA,
+  ORIGIN_SUBTYPE_AGGREGATE,
+  ORIGIN_SUBTYPE_COMPUTED,
+  ORIGIN_SUBTYPE_FIRST,
+  ORIGIN_SUBTYPE_PASSTHROUGH,
+  RELATIONSHIP_ATTR_CARDINALITY,
+  RELATIONSHIP_ATTR_OBJECT_REF,
+  RELATIONSHIP_ATTR_ON_DELETE,
+  RELATIONSHIP_ATTR_THROUGH,
+  PHYSICAL_NAME_ATTR_BY_KIND,
+  SOURCE_ROLE_PRIMARY,
+  TYPE_ORIGIN,
+  resolveColumnName,
+} from "@metaobjectsdev/metadata";
+import type { ColumnNamingStrategy, MetaField, MetaObject } from "@metaobjectsdev/metadata";
+import type { EmittedFile, Generator, GeneratorFactory } from "../generator.js";
+import { resolveObjectNames } from "../names.js";
+import { isAbstract } from "../instance-artifacts.js";
+import { enumValues, intValueMapOf } from "../enum-meta.js";
+import { renderAgentSchemaPage } from "./agent-schema-page.js";
+import { renderAgentUiPage } from "./agent-ui-page.js";
+import { renderAgentRequirementsPage } from "./agent-requirements-page.js";
+import type { AgentSchemaInput } from "./agent-schema-input.js";
+
+/** All three pages live here, under the docs root. */
+const DEFAULT_AGENT_DIR = "agent";
+
+export interface AgentDocsFileOpts {
+  /** Output prefix for the agent pages. Default `agent`. */
+  subDir?: string;
+  /** Optional named output target (registry key). */
+  target?: string;
+  /**
+   * The physical schema, with its resolvers injected by whoever owns them. ABSENT is a
+   * supported state — `meta docs` runs without a dialect, and a project with no physical
+   * schema gets no schema page rather than a page of unknowns.
+   */
+  schema?: AgentSchemaInput;
+  /** The project's column naming strategy, for the field→column mapping. */
+  columnNamingStrategy?: ColumnNamingStrategy;
+}
+
+/** One `origin.*` child rendered as a lineage phrase. `origin.*` NEVER inherits, so the
+ *  own-accessor read here is the correct one rather than an ADR-0039 slip. */
+function lineageOf(field: MetaField): string | undefined {
+  const origin = field.ownChildren().find((c) => c.type === TYPE_ORIGIN);
+  if (origin === undefined) return undefined;
+  const str = (name: string): string | undefined => {
+    const v = origin.attr(name);
+    return typeof v === "string" && v !== "" ? v : undefined;
+  };
+  switch (origin.subType) {
+    case ORIGIN_SUBTYPE_PASSTHROUGH: {
+      const from = str(ORIGIN_PASSTHROUGH_ATTR_FROM);
+      const via = str(ORIGIN_PASSTHROUGH_ATTR_VIA);
+      return `passthrough from \`${from ?? "?"}\`${via === undefined ? "" : ` via \`${via}\``}`;
+    }
+    case ORIGIN_SUBTYPE_AGGREGATE: {
+      const agg = str(ORIGIN_AGGREGATE_ATTR_AGG) ?? "?";
+      const of = str(ORIGIN_AGGREGATE_ATTR_OF);
+      const via = str(ORIGIN_AGGREGATE_ATTR_VIA);
+      return `\`${agg}\`${of === undefined ? "" : ` of \`${of}\``}${via === undefined ? "" : ` via \`${via}\``}`;
+    }
+    case ORIGIN_SUBTYPE_FIRST: {
+      const of = str(ORIGIN_AGGREGATE_ATTR_OF);
+      const via = str(ORIGIN_AGGREGATE_ATTR_VIA);
+      const order = str(ORIGIN_ATTR_ORDER_BY);
+      return `first${of === undefined ? "" : ` \`${of}\``}${via === undefined ? "" : ` via \`${via}\``}` +
+        `${order === undefined ? "" : ` ordered by \`${order}\``}`;
+    }
+    case ORIGIN_SUBTYPE_COMPUTED:
+      // The @expr tree is structured; naming it is enough to route a reader to the
+      // declaration, and rendering a tree into a cell would be a second SQL lowering.
+      return "computed from a declared `@expr`";
+    default:
+      return `\`origin.${origin.subType}\``;
+  }
+}
+
+/**
+ * The cardinality phrase, from the DECLARING object's side.
+ *
+ * `@cardinality: one` does NOT mean one-to-one. It means this object holds the foreign
+ * key — many rows of it point at one target row — which is what `relation-resolver.ts`
+ * builds a belongs-to `one()` relation from. Rendering it as "one-to-one" told a reader
+ * the target row is claimed by at most one row here, which is the direction that makes
+ * someone write a lookup expecting a single result.
+ *
+ * `@cardinality` is OPTIONAL vocabulary (min 0), and ABSENT is its own answer: no
+ * navigation is generated at all. Folding that into "one-to-one" invented a shape the
+ * model never declared.
+ */
+function cardinalityPhrase(cardinality: unknown, through: unknown): string {
+  if (cardinality === CARDINALITY_MANY) {
+    return typeof through === "string" && through !== "" ? "many-to-many" : "one-to-many";
+  }
+  if (cardinality === CARDINALITY_ONE) return "many-to-one";
+  return "cardinality not declared";
+}
+
+/** `- \`Order.lines\` — one-to-many → \`OrderLine\`` */
+function relationshipLines(objects: readonly MetaObject[]): string[] {
+  const out: string[] = [];
+  for (const obj of objects) {
+    for (const rel of obj.relationships()) {
+      const cardinality = rel.attr(RELATIONSHIP_ATTR_CARDINALITY);
+      const target = rel.attr(RELATIONSHIP_ATTR_OBJECT_REF);
+      const through = rel.attr(RELATIONSHIP_ATTR_THROUGH);
+      const onDelete = rel.attr(RELATIONSHIP_ATTR_ON_DELETE);
+      // The FQN, not the short name: this line is an ADDRESS a reader searches for.
+      const parts = [`\`${obj.resolutionKey()}.${rel.name}\``, `\`${rel.subType}\``];
+      parts.push(
+        `${cardinalityPhrase(cardinality, through)} → \`${String(target ?? "?")}\``,
+      );
+      if (typeof through === "string" && through !== "") parts.push(`through \`${through}\``);
+      if (typeof onDelete === "string" && onDelete !== "") parts.push(`on delete \`${onDelete}\``);
+      out.push(`- ${parts.join(" · ")}`);
+    }
+  }
+  return out;
+}
+
+/**
+ * `| \`Order.status\` | OPEN, CLOSED | string-backed |`
+ *
+ * `objects` IS ONLY THE TABLE-BACKED SUBSET OF THE MODEL — the caller scopes it to the
+ * objects the snapshot actually holds as tables. This section sits on the SCHEMA page, so
+ * every row it prints is read as a statement about a column. Walking every loaded object
+ * printed rows for abstract bases, for `object.value`s that have no column anywhere, and
+ * for projections whose "column" is a view expression — three kinds of thing the physical
+ * schema does not contain.
+ *
+ * It also says nothing about a `CHECK`. Whether the database constrains the members is
+ * `table.checks`, which is already on this page from the snapshot, and an `@isArray`
+ * enum deliberately gets none (`migrate-ts` skips it) — so asserting one here was a
+ * SECOND derivation of a fact the page already carries correctly, in the direction that
+ * promises the database will refuse a value it will accept.
+ */
+function enumLines(objects: readonly MetaObject[]): string[] {
+  const rows: string[] = [];
+  for (const obj of objects) {
+    for (const field of obj.fields()) {
+      if (field.subType !== FIELD_SUBTYPE_ENUM) continue;
+      const members = enumValues(field);
+      if (members === undefined || members.length === 0) continue;
+      const intMap = intValueMapOf(field);
+      const backing =
+        intMap === undefined
+          ? "string-backed"
+          : `int-backed (${members.map((m) => `${m}=${intMap[m]}`).join(", ")})`;
+      rows.push(
+        `| \`${obj.resolutionKey()}.${field.name}\` | ${members.map((m) => `\`${m}\``).join(", ")} | ${backing} |`,
+      );
+    }
+  }
+  if (rows.length === 0) return [];
+  return ["| Field | Members | Storage |", "|---|---|---|", ...rows];
+}
+
+export const agentDocsFile = function agentDocsFile(opts?: AgentDocsFileOpts): Generator {
+  const dir = (opts?.subDir ?? DEFAULT_AGENT_DIR).replace(/\/$/, "");
+
+  const generator: Generator = {
+    name: "agent-docs",
+    generate(ctx) {
+      const objects = ctx.loadedRoot.objects();
+      const files: EmittedFile[] = [];
+
+      // ---- schema.md
+      if (opts?.schema !== undefined) {
+        const schema = opts.schema;
+        // The qualified names the snapshot actually holds. An object whose physical name
+        // is not one of these contributes nothing to the physical schema (an abstract
+        // base, a sourceless value, an `@unmanaged` object) and must not appear on a page
+        // describing it — `buildExpectedSchema`'s Pass 1 owns those skip rules and this
+        // reads its answer rather than re-deriving them.
+        const tableNames = new Set(schema.tables.map((t) => schema.qualify(t)));
+        const viewNames = new Set(schema.views.map((v) => schema.qualify(v)));
+        // The objects backed by a TABLE in the snapshot — the enum section's scope, since
+        // a row there is read as a statement about a column.
+        const tableBacked: MetaObject[] = [];
+        // column → declaring field, per qualified table name. `resolveObjectNames` is the
+        // ONE field→column resolver — the same one the names artifact and the DDL use —
+        // so this mapping cannot disagree with the column it labels.
+        const declaredBy = new Map<string, Map<string, { field: string; type: string }>>();
+        const viewLineage = new Map<string, string[]>();
+        for (const obj of objects) {
+          const names = resolveObjectNames(obj, opts.columnNamingStrategy);
+          // The PRIMARY source's physical name and schema — `names.name` is the object's
+          // metamodel name since 0.25.0, which would match nothing in the snapshot.
+          const primary = names?.sources[SOURCE_ROLE_PRIMARY];
+          const physical = primary === undefined
+            ? undefined
+            : primary[(PHYSICAL_NAME_ATTR_BY_KIND.get(primary.kind) ?? "") as keyof typeof primary];
+          if (typeof physical !== "string") continue;
+          const key = schema.qualify({ name: physical, schema: primary?.schema });
+          const isTable = tableNames.has(key);
+          if (!isTable && !viewNames.has(key)) continue;
+          // ABSTRACT BASES ARE EXCLUDED, and being in the snapshot does not exempt them:
+          // an abstract base that declares the `source.rdb` its concrete child inherits
+          // resolves to that child's table, so the qualified-name test admits it and the
+          // page printed the base's enum a second time under a different owner.
+          // `buildExpectedSchema`'s Pass 1 skips abstracts; this reads the same rule.
+          if (isTable && !isAbstract(obj)) tableBacked.push(obj);
+          let map = declaredBy.get(key);
+          if (map === undefined) {
+            map = new Map();
+            declaredBy.set(key, map);
+          }
+          const lineage: string[] = [];
+          for (const field of obj.fields()) {
+            const column = resolveColumnName(field, opts.columnNamingStrategy);
+            // A TPH base and its subtypes share one table: first writer wins, so the
+            // base's own column keeps its label rather than being relabelled by whichever
+            // subtype was walked last.
+            if (!map.has(column)) {
+              map.set(column, { field: field.name, type: `${field.type}.${field.subType}` });
+            }
+            const line = lineageOf(field);
+            if (line !== undefined) lineage.push(`| \`${column}\` | ${line} |`);
+          }
+          if (lineage.length > 0) viewLineage.set(key, lineage);
+        }
+        const content = renderAgentSchemaPage(schema, {
+          declaredBy,
+          viewLineage,
+          relationships: relationshipLines(objects),
+          enums: enumLines(tableBacked),
+        });
+        if (content !== "") files.push({ path: `${dir}/schema.md`, content });
+      }
+
+      // ---- ui.md
+      // The apiPrefix is the project's, from the render context the runner built — the
+      // same value `routes-file.ts` emits as the SERVER mount prefix. Without it the page
+      // names an address nothing serves. (The client descriptor no longer carries it: a
+      // browser's base URL is supplied at runtime by the provider's `baseUrl`.)
+      const ui = renderAgentUiPage(ctx.loadedRoot, ctx.renderContext?.apiPrefix ?? "");
+      if (ui !== "") files.push({ path: `${dir}/ui.md`, content: ui });
+
+      // ---- requirements.md
+      const requirements = renderAgentRequirementsPage(ctx.loadedRoot);
+      if (requirements !== "") files.push({ path: `${dir}/requirements.md`, content: requirements });
+
+      return files;
+    },
+  };
+  if (opts?.target) generator.target = opts.target;
+  return generator;
+} as GeneratorFactory<AgentDocsFileOpts>;