@metaobjectsdev/codegen-ts 0.24.4 → 0.25.0

package/src/generators/agent-ui-page.ts

@@ -0,0 +1,290 @@
+// `agent/ui.md` — the generated UI surface, for an agent about to touch a form or a grid.
+//
+// The gap this closes is narrow and real: the neutral model entity page renders NO
+// `view.*` or `layout.*` metadata at all, so an agent asked to change a form had nowhere
+// to learn what the form already is and would read the generated TSX — the disposable
+// artifact — as if it were the source.
+//
+// EVERY FIELD ROW COMES FROM `buildEntityUiDescriptor`, the same derivation
+// `renderEntityConstants` emits as the `<Entity>` const in `<Entity>.meta.ts`, which is
+// what `useEntityForm` reads at runtime. One derivation, two renderings: the page cannot
+// describe a control the form does not render, because both answers come from the same
+// call. That is the point of the descriptor extraction, not a nicety.
+//
+// The three columns the descriptor does NOT carry — `@formExclude`, `@filterable` and
+// `@sortable` — are read here from the field, and `@sortable`'s inherit-from-`@filterable`
+// default resolves through `isSortableField`, the SAME predicate the generated
+// `<Entity>SortAllowlist` is built from, so the page cannot say a field is sortable that
+// the endpoint will reject. They are deliberately absent from the descriptor: the
+// descriptor describes how a field is PRESENTED, while those three say whether it appears
+// at all and what the LIST endpoint will accept, which is a different question the form
+// control has no opinion on.
+//
+// THREE THINGS THE DESCRIPTOR ALONE CANNOT ANSWER, each read from the predicate the
+// generator that decides it uses, never re-derived here:
+//
+//   • WHERE the object is served — `restPath`, because a TPH subtype is mounted under its
+//     discriminator base and its own `$path` names nothing;
+//   • WHETHER a form exists at all — `hasGeneratedForm`, the form generator's own filter,
+//     because a discriminator base has a write endpoint and still gets no form;
+//   • WHAT the control is for a `field.object` — `valueObjectFor`, shared with the form
+//     generator, because a resolvable `@objectRef` is rendered as a nested sub-form and
+//     the field's view kind is not consulted.
+
+import {
+  FIELD_ATTR_FILTERABLE,
+  FIELD_ATTR_FORM_EXCLUDE,
+  LAYOUT_DATA_GRID_ATTR_COLUMNS,
+  LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_FIELD,
+  LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_ORDER,
+  LAYOUT_DATA_GRID_ATTR_PAGE_SIZE,
+  LAYOUT_SUBTYPE_DATA_GRID,
+  TYPE_LAYOUT,
+} from "@metaobjectsdev/metadata";
+import type { MetaData, MetaObject, MetaRoot } from "@metaobjectsdev/metadata";
+import { GENERATED_HEADER } from "../constants.js";
+import { hasGeneratedForm, restPath, servedPath, servesReadApi } from "../api-surface.js";
+import {
+  buildEntityUiDescriptor,
+  type UiFieldDescriptor,
+  type UiRule,
+} from "../templates/entity-ui-descriptor.js";
+import { isSortableField } from "../templates/filter-shared.js";
+import { isTphDiscriminatorBase } from "../templates/tph-discriminator.js";
+import { declaresTphDiscriminator } from "../templates/zod-validators.js";
+
+const GENERATED_MARKER = `<!-- ${GENERATED_HEADER} — DO NOT EDIT. -->`;
+
+function mdCell(text: string): string {
+  return text.replace(/\|/g, "\\|");
+}
+
+/** One rule, as a reader wants to see it — the value, not the message. */
+function ruleText(r: UiRule): string {
+  switch (r.kind) {
+    case "required":
+      return "required";
+    case "minLength":
+      return `minLength ${r.value}`;
+    case "maxLength":
+      return `maxLength ${r.value}`;
+    case "pattern":
+      return `pattern \`${mdCell(r.pattern)}\``;
+  }
+}
+
+/**
+ * The CONTROL cell — what the generated form renders, which is not always a `view.*`
+ * subtype.
+ *
+ * A `field.object` whose `@objectRef` resolves is emitted as a nested `<fieldset>`
+ * sub-form (a `useFieldArray` repeatable group when the field is an array), and the form
+ * generator never consults the field's view kind for it. This column used to print that
+ * view kind — `text`, the `defaultViewForSubType` fallback — which said the control was a
+ * free-text input for a field that has no input at all. Same shape as the `field.enum`
+ * descriptor bug, one subtype family over; the predicate is shared with the form
+ * generator (`valueObjectFor`) so the two cannot answer differently again.
+ */
+function controlCell(f: UiFieldDescriptor): string {
+  if (f.nested === undefined) return `\`${f.view}\``;
+  return f.nested.isArray ? "nested sub-form (repeatable)" : "nested sub-form";
+}
+
+/** The HTML type cell — empty for a nested sub-form, which is not an input at all. */
+function htmlTypeCell(f: UiFieldDescriptor): string {
+  if (f.nested !== undefined || f.htmlType === undefined) return "";
+  return `\`${f.htmlType}\``;
+}
+
+/** `yes` / `` — an empty cell reads better than a column of "no". */
+function flag(value: unknown): string {
+  return value === true ? "yes" : "";
+}
+
+/**
+ * The endpoint line under an object's heading.
+ *
+ * THE `apiPrefix` IS PART OF THE ADDRESS. `routes-file.ts` registers every mount inside
+ * `fastify.register(…, { prefix: apiPrefix })`, so a project configuring `/api` serves
+ * `/api/owners` and nothing at `/owners`. This page states that its heading is the address
+ * the routes mount at, so omitting the prefix made that promise false for every project
+ * that sets one — and a reader following it gets a 404.
+ *
+ * `restPath`, NOT `descriptor.path`: a TPH subtype's own `$path` names an address
+ * nothing mounts — the hierarchy is mounted from the discriminator base, each subtype
+ * at `<base>/<segment>` — and this page printed that non-existent address as fact.
+ * Whether a form exists is `hasGeneratedForm` — the form generator's OWN filter —
+ * never `servesWriteApi`. A read-only object (a projection, a view-backed entity) has
+ * no Insert/Update schema; a TPH discriminator BASE has both and still gets no form,
+ * because you cannot create a base and its polymorphic mount is read-only by
+ * construction. Saying so is the difference between "the form is missing" and "there
+ * is deliberately no form"; asking the endpoint question announced one for every base.
+ */
+function endpointLine(obj: MetaObject, root: MetaRoot, apiPrefix: string): string {
+  const endpoint = servedPath(obj, apiPrefix);
+  if (hasGeneratedForm(obj)) return `Endpoint \`${endpoint}\`.`;
+  // `isTphDiscriminatorBase`, which requires at least one CONCRETE subtype — the same
+  // predicate `routes-file.ts` switches on. `@discriminator` with no subtype yet is a
+  // refactor-in-progress shape: the routes generator emits the VANILLA full-CRUD file for
+  // it, so "each concrete subtype below has its own" would name subtypes that do not
+  // exist, on an object that does have a write endpoint.
+  // THREE reasons, not two. `isTphDiscriminatorBase` requires at least one CONCRETE
+  // subtype — the same predicate `routes-file.ts` switches on — and the case it excludes
+  // is real: an object declaring `@discriminator` with no subtype yet gets the VANILLA
+  // full-CRUD routes file, so it is NOT read-only, while the form generator declines it
+  // for declaring `@discriminator` at all. Calling that "read-only" is false in the one
+  // direction that matters, since a reader would conclude it cannot be written to.
+  const reason = isTphDiscriminatorBase(obj, root)
+    ? "for a discriminator base — its own mount is list/get only, and each concrete " +
+      "subtype below has its own form"
+    : declaresTphDiscriminator(obj)
+      ? "— the form generator declines any object declaring `@discriminator`, and this " +
+        "one has no concrete subtype yet. Its routes are the ordinary full CRUD set"
+      : "(read-only)";
+  return (
+    `Endpoint \`${endpoint}\` — **no form is generated** ${reason}. ` +
+    "The fields below describe the grid and the filters."
+  );
+}
+
+/** The `layout.dataGrid` children an object declares. ADR-0039: resolving. */
+function dataGrids(obj: MetaObject): MetaData[] {
+  return obj
+    .children()
+    .filter((c) => c.type === TYPE_LAYOUT && c.subType === LAYOUT_SUBTYPE_DATA_GRID);
+}
+
+/**
+ * True when a UI generator would emit for this object.
+ *
+ * `servesReadApi` — the api-surface predicate the hook, grid and form generators
+ * themselves gate on — NOT "has fields" and never an object-subtype test. A form, a grid
+ * and a hook are all clients of a generated endpoint, so an object with no endpoint has no
+ * UI to document.
+ *
+ * Getting this wrong is not cosmetic. Gating on "has fields" put a prompt payload
+ * (`object.value`, no source, no routes) on the page under a heading that announced an
+ * endpoint derived from its name — an address that does not exist, stated as fact, on the
+ * page an agent is told to trust. Instance artifacts derive from a declared SOURCE; the
+ * UI tier asks the endpoint question and never a storage or subtype one.
+ */
+export function hasUiSurface(obj: MetaObject): boolean {
+  return servesReadApi(obj);
+}
+
+function gridSection(grid: MetaData): string[] {
+  const out: string[] = [];
+  out.push(`**Grid \`${grid.name}\`**`);
+  out.push("");
+  const columns = grid.attr(LAYOUT_DATA_GRID_ATTR_COLUMNS);
+  if (Array.isArray(columns) && columns.length > 0) {
+    out.push(`- columns: ${columns.map((c) => `\`${String(c)}\``).join(", ")}`);
+  }
+  const sortField = grid.attr(LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_FIELD);
+  if (typeof sortField === "string" && sortField !== "") {
+    const order = grid.attr(LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_ORDER);
+    const suffix = typeof order === "string" && order !== "" ? `:${order}` : "";
+    out.push(`- default sort: \`${sortField}${suffix}\``);
+  }
+  const pageSize = grid.attr(LAYOUT_DATA_GRID_ATTR_PAGE_SIZE);
+  if (typeof pageSize === "number") out.push(`- page size: ${pageSize}`);
+  return out;
+}
+
+/**
+ * Render the page. Returns "" when no object in the model has a UI surface — the surface
+ * then emits no FILE, so a headless project sees nothing rather than an empty page.
+ */
+export function renderAgentUiPage(root: MetaRoot, apiPrefix = ""): string {
+  const objects = root.objects();
+  const withUi = objects.filter(hasUiSurface);
+  if (withUi.length === 0) return "";
+
+  const out: string[] = [];
+  out.push(GENERATED_MARKER);
+  out.push("");
+  out.push("# UI");
+  out.push("");
+  out.push(
+    "What the generated forms and grids already are. Read it before changing a form, a " +
+      "grid or a filter — the generated `.tsx` is the disposable artifact, this is what " +
+      "produced it.",
+  );
+  out.push("");
+  out.push(
+    "- Every row here is the SAME derivation the runtime reads — `buildEntityUiDescriptor`, " +
+      "which is emitted as the `<Entity>` const in `<Entity>.meta.ts` and consumed by " +
+      "`useEntityForm`. Changing the metadata changes both. A READ-ONLY projection's const " +
+      "carries the subset that applies to it (no form, so no rules and no HTML type) plus " +
+      "the `dbCol` only a view-backed const has.",
+  );
+  out.push(
+    "- `Control` is what the FORM renders. A field declaring several views is described by " +
+      "the one named `form`; a `field.object` whose `@objectRef` resolves is not an input " +
+      "at all but a nested sub-form over that value object, and says so.",
+  );
+  out.push(
+    "- `Filter` / `Sort` are what the generated LIST endpoint accepts. `@sortable` " +
+      "defaults to `@filterable`, and the resolved answer is what is shown.",
+  );
+  out.push("");
+
+  for (const obj of withUi) {
+    out.push(`## \`${obj.resolutionKey()}\``);
+    out.push("");
+    const descriptor = buildEntityUiDescriptor(obj, root);
+    out.push(endpointLine(obj, root, apiPrefix));
+    out.push("");
+    if (descriptor.fields.length > 0) {
+      // The field nodes, keyed by name, so the three non-descriptor columns can be read
+      // off the field the descriptor row came from.
+      const byName = new Map(obj.fields().map((f) => [f.name, f]));
+      out.push("| Field | Label | Control | HTML type | Rules | Excluded | Filter | Sort |");
+      out.push("|---|---|---|---|---|---|---|---|");
+      for (const f of descriptor.fields) {
+        const node = byName.get(f.name);
+        const cells = [
+          `\`${f.name}\``,
+          mdCell(f.label),
+          controlCell(f),
+          htmlTypeCell(f),
+          f.rules.map(ruleText).join(" · "),
+          node === undefined ? "" : flag(node.attr(FIELD_ATTR_FORM_EXCLUDE)),
+          node === undefined ? "" : flag(node.attr(FIELD_ATTR_FILTERABLE)),
+          node === undefined ? "" : flag(isSortableField(node)),
+        ];
+        out.push(`| ${cells.join(" | ")} |`);
+      }
+      // Which value object a nested field expands into rides below the table: it is the
+      // one thing a reader needs to go and edit, and it does not fit a cell.
+      const nested = descriptor.fields.filter((f) => f.nested !== undefined);
+      if (nested.length > 0) {
+        out.push("");
+        for (const f of nested) {
+          out.push(
+            `- \`${f.name}\` — expands \`${f.nested?.objectRef}\`` +
+              `${f.nested?.isArray === true ? ", one group per element" : ""}. Change the ` +
+              "fields inside it on that value object, not here.",
+          );
+        }
+      }
+      const money = descriptor.fields.filter((f) => f.currency !== undefined);
+      if (money.length > 0) {
+        out.push("");
+        for (const f of money) {
+          out.push(
+            `- \`${f.name}\` — money: \`${f.currency?.currency}\` formatted for ` +
+              `\`${f.currency?.locale}\`. Stored and sent as INTEGER MINOR UNITS; never format it server-side.`,
+          );
+        }
+      }
+    }
+    for (const grid of dataGrids(obj)) {
+      out.push("");
+      out.push(...gridSection(grid));
+    }
+    out.push("");
+  }
+
+  return `${out.join("\n").replace(/\n+$/, "")}\n`;
+}

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

@@ -18,12 +18,16 @@
 // Part 3) — so it appears in `gen --list` and is selectable by its stable name
 // `api-docs`. It is NOT a `meta docs` mode.
 //
-// It is NOT (yet) part of the default `meta gen` scaffold suite: it is
-// registry-listed but not auto-run. Turning it on by default in the scaffold,
-// and surfacing the agent form (AGENT-API.md) to a coding agent via a pointer
-// from the installed `.metaobjects/` context, are tracked as agent-context-
-// coordination follow-ups — deliberately deferred here to avoid colliding with
-// the live agent-context work.
+// It is NOT part of the default `meta gen` scaffold suite: it is registry-listed but not
+// auto-run. `meta docs` is the door that emits it.
+//
+// THE POINTER IS NO LONGER DEFERRED. This header used to record "surfacing the agent form
+// (AGENT-API.md) to a coding agent via a pointer from the installed `.metaobjects/`
+// context" as an agent-context-coordination follow-up. It was deferred, no roadmap item
+// tracked it, and for as long as that held, the page existed and nothing routed an agent
+// to it. `agent-context/templates/always-on.md.mustache` now names this file and the three
+// `agent/` pages, and says when to read each. If you rename or move this artifact, that
+// template is the other half.
 
 import type { MetaObject } from "@metaobjectsdev/metadata";
 import type { Generator, GeneratorFactory, EmittedFile } from "../generator.js";
@@ -95,6 +99,9 @@ export const apiDocsFile = function apiDocsFile(opts?: ApiDocsFileOpts): Generat
         loadedRoot: ctx.loadedRoot,
         outputLayout: layout,
         includeHonoRoutes: ctx.config.includeHonoRoutes ?? false,
+        // The project's prefix, because every route is mounted inside it. Without
+        // this the page documents `/authors` for routes served at `/api/authors`.
+        apiPrefix: ctx.renderContext?.apiPrefix ?? "",
         ...(ctx.renderContext?.pkMap !== undefined && { pkMap: ctx.renderContext.pkMap }),
       });
 

package/src/generators/api-model.ts

@@ -35,7 +35,7 @@
 //                        (templates/routes-file-hono.ts) — the OPT-IN Hono variant
 //                        of the Fastify REST surface. Documented ONLY when the
 //                        adopter wires routesFileHono() (ctx.includeHonoRoutes), and
-//                        gated by the SAME @emitRoutes:false filter.
+//                        gated by the SAME source + TPH rules as the Fastify surface.
 //   • template.prompt (T5):
 //       - prompt       : render<Name> (payload, provider): string — the prompt
 //                        render handle promptRender() emits into a single
@@ -75,10 +75,17 @@
 //     / update<Sub>ById / delete<Sub>ById scoped to the shared table) and the
 //     subtype REST subpaths are NOT YET documented by this builder — that fuller
 //     TPH modeling is a tracked follow-up (under-documentation, allowed).
-//   • @emitRoutes:false entities → the routes generator filters them out
-//     (routes-file.ts: ownAttr(CODEGEN_ATTR_EMIT_ROUTES) !== false), so they get
-//     NO REST symbols here. The queries + validator generators do NOT honor
-//     @emitRoutes, so data-access + validation symbols still apply.
+//
+// NOT modelled here (stated so the gap is known + intentional): a generator's own
+// `filter` option. `routesFile({ filter })` narrows what the routes generator emits,
+// and this builder reads the MODEL, not the wired generator set, so it cannot see
+// that narrowing and will over-document REST for a filtered-out entity. That is
+// under-documentation's opposite and it is a real limitation — but it is inherent to
+// a docs pass that runs off metadata, and it applies equally to every generator's
+// filter. (It used to be dodged for routes ALONE via an @emitRoutes:false metadata
+// read; that attribute was never registered vocabulary, so `meta verify` rejected the
+// very models this builder was reading it from. The read is gone — see
+// constants.ts.)
 
 import {
   type MetaRoot,
@@ -112,8 +119,7 @@ import { isTphSubtype } from "../templates/zod-validators.js";
 import { isTphDiscriminatorBase } from "../templates/tph-discriminator.js";
 import { isCallableEntity } from "../templates/callable-file.js";
 import { hasAnyRdbSource } from "../source-detect.js";
-import { CODEGEN_ATTR_EMIT_ROUTES } from "../constants.js";
-import { resourcePath } from "../templates/entity-constants.js";
+import { servedPath } from "../api-surface.js";
 import { isProjection } from "../projection/projection-detector.js";
 import { buildPkMap } from "../pk-resolver.js";
 import { buildRelationMap, type RelationEntry, type RelationMap } from "../relation-resolver.js";
@@ -263,6 +269,12 @@ export interface ApiModelContext {
    *  run didn't configure). The Fastify REST surface is always documented (it is
    *  the default-suite routes generator). Defaults to false. */
   includeHonoRoutes?: boolean;
+  /** The project's `apiPrefix`. Every generated route is mounted inside
+   *  `fastify.register(…, { prefix: apiPrefix })`, so it is part of the address a
+   *  documented endpoint is served at — a page that omits it is one path segment
+   *  short. Threaded explicitly rather than read off the RenderContext below,
+   *  which is a `{ pkMap }` shim and carries nothing else. Defaults to "". */
+  apiPrefix?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -275,13 +287,14 @@ export function buildApiModel(root: MetaRoot, ctx: ApiModelContext): ApiModel {
   // shim is sufficient (and avoids forcing callers to build a full context).
   const pkCtx = { pkMap } as RenderContext;
   const layout = ctx.outputLayout ?? "flat";
+  const apiPrefix = ctx.apiPrefix ?? "";
   const relationMap = ctx.relationMap ?? buildRelationMap(root);
   const includeHono = ctx.includeHonoRoutes ?? false;
 
   const units: ApiUnitDoc[] = [];
 
   for (const obj of root.objects()) {
-    units.push(buildEntityUnit(obj, pkCtx, root, layout, relationMap, includeHono));
+    units.push(buildEntityUnit(obj, pkCtx, root, layout, relationMap, includeHono, apiPrefix));
   }
 
   for (const tmpl of templateOutputs(root)) {
@@ -353,15 +366,6 @@ function isQueryable(obj: MetaObject): boolean {
   return hasAnyRdbSource(obj) && !isTphSubtype(obj);
 }
 
-/** Whether the routes generator emits REST routes for this entity. It filters
- *  out @emitRoutes:false (routes-file.ts:27), unlike the queries + validator
- *  generators which always emit. So REST symbols are gated separately from the
- *  other queryable kinds. */
-function emitsRoutes(obj: MetaObject): boolean {
-  // ADR-0039: resolving — a concrete entity may inherit @emitRoutes via extends.
-  return obj.attr(CODEGEN_ATTR_EMIT_ROUTES) !== false;
-}
-
 function buildEntityUnit(
   obj: MetaObject,
   ctx: RenderContext,
@@ -369,6 +373,7 @@ function buildEntityUnit(
   layout: OutputLayout,
   relationMap: RelationMap,
   includeHono: boolean,
+  apiPrefix: string,
 ): ApiUnitDoc {
   const name = obj.name;
   const symbols: ApiSymbol[] = [];
@@ -392,13 +397,15 @@ function buildEntityUnit(
   if (isQueryable(obj)) {
     symbols.push(...dataAccessSymbols(obj, ctx, root, layout));
     symbols.push(...validationSymbols(obj, entityMod));
-    // REST is additionally gated: @emitRoutes:false suppresses routes only.
-    if (emitsRoutes(obj)) {
-      symbols.push(...restSymbols(obj, layout));
-      // The OPT-IN Hono variant mounts the SAME CRUD verbs under the SAME
-      // @emitRoutes filter — documented only when the adopter wired it.
-      if (includeHono) symbols.push(...restHonoSymbols(obj, layout));
-    }
+    // REST needs no gate of its own: the routes generator's built-in filter is
+    // `hasAnyRdbSource && !isTphSubtype` — exactly isQueryable — so every queryable
+    // object gets routes. (Its `filter` option can narrow that further; this builder
+    // reads the model, not the wired generator set, and cannot see it. See the module
+    // header.)
+    symbols.push(...restSymbols(obj, layout, root, apiPrefix));
+    // The OPT-IN Hono variant mounts the SAME CRUD verbs under the same rules —
+    // documented only when the adopter wired it.
+    if (includeHono) symbols.push(...restHonoSymbols(obj, layout, apiPrefix));
   }
 
   // --- relation: the drizzle relations() export, when the resolver derives a
@@ -565,15 +572,35 @@ function validationSymbols(obj: MetaObject, entityMod: string): ApiSymbol[] {
  * generator does NOT emit one function per verb — it emits a single
  * `<name>Routes(fastify)` handler that mounts the standard CRUD verb set at the
  * entity's $path via mountCrudRoutes (or the read-only subset via
- * mountReadOnlyCrudRoutes for a projection). We reuse resourcePath() — the same
- * function entity-constants.ts uses to compute $path — so the documented paths
- * match the generated routes exactly. The verb→path mapping mirrors the runtime
- * mountCrudRoutes contract referenced in routes-file.ts's comments.
+ * mountReadOnlyCrudRoutes for a projection). The verb→path mapping mirrors the
+ * runtime mountCrudRoutes contract referenced in routes-file.ts's comments.
+ *
+ * THE DOCUMENTED PATH IS THE ADDRESS THE ROUTES ACTUALLY SERVE, which takes two
+ * things this comment used to claim it got from one. It said it reused
+ * `resourcePath()` — "the same function entity-constants.ts uses to compute
+ * $path" — and both halves of that had stopped being true:
+ *
+ *   • `$path` is `restPath()` now, not `resourcePath()`. A TPH subtype is mounted
+ *     at `<base>/<segment>`, so `resourcePath` named an address nothing serves —
+ *     the defect fixed for `$path` itself, still live here.
+ *   • Every mount sits inside `fastify.register(…, { prefix: apiPrefix })`, so a
+ *     project configuring "/api" was documented one path segment short.
+ *
+ * A TPH DISCRIMINATOR BASE serves only `TPH_POLYMORPHIC_VERBS` at its own path, and that
+ * set is imported rather than restated. `isProjection` alone was the read-only test, so a
+ * base — which is not a projection — was documented with POST/PATCH/DELETE against a mount
+ * `routes-file.ts` builds as `intersectExpose(TPH_POLYMORPHIC_VERBS, expose)`: three verbs
+ * that 404, published in the file an adopter is told to call generated code from, under the
+ * comment three lines above claiming these paths match the routes exactly. The per-subtype
+ * mounts at `<base path>/<segment>`, which is where writes actually live, remain a
+ * documented deferral (see the module header).
  */
-function restSymbols(obj: MetaObject, layout: OutputLayout): ApiSymbol[] {
+function restSymbols(
+  obj: MetaObject, layout: OutputLayout, root: MetaRoot, apiPrefix: string,
+): ApiSymbol[] {
   const name = obj.name;
-  const path = resourcePath(obj);
-  const readOnly = isProjection(obj);
+  const path = servedPath(obj, apiPrefix);
+  const readOnly = isProjection(obj) || isTphDiscriminatorBase(obj, root);
 
   // REST endpoints are not importable functions — to WIRE them an adopter
   // imports the entity's route registrar (`<entity>Routes`) from the routes
@@ -776,13 +803,15 @@ function callableArgsRef(obj: MetaObject, root: MetaRoot): string | undefined {
 /**
  * The OPT-IN Hono CRUD registrar `register<Entity>Routes(app, deps)` the
  * routesFileHono generator emits into `<Entity>.routes.hono.ts`. Parallels the
- * Fastify restSymbols (same verb set, same resourcePath, read-only for
+ * Fastify restSymbols (same verb set, same served address, read-only for
  * projections) but carries the Hono registrar name + import module. Documented
  * only when the adopter opts into the Hono variant (includeHonoRoutes).
  */
-function restHonoSymbols(obj: MetaObject, layout: OutputLayout): ApiSymbol[] {
+function restHonoSymbols(
+  obj: MetaObject, layout: OutputLayout, apiPrefix: string,
+): ApiSymbol[] {
   const name = obj.name;
-  const path = resourcePath(obj);
+  const path = servedPath(obj, apiPrefix);
   const readOnly = isProjection(obj);
 
   const honoMod = entityModulePath(layout, obj, `${name}.routes.hono`);

package/src/generators/callable-file.ts

@@ -33,7 +33,7 @@ export const callableFile = function callableFile(opts?: CallableFileOpts): Gene
           entity.package,
           `${entity.name}.callable.ts`,
         ),
-        content: await formatTs(renderCallableFile(entity)),
+        content: await formatTs(renderCallableFile(entity, ctx.renderContext)),
       };
     }),
   };

package/src/generators/docs-data-builder.ts

@@ -4,6 +4,7 @@
 // markdown structure now lives in templates/docs/entity-page.md.mustache.
 
 import {
+  type MetaData,
   type MetaObject,
   type MetaField,
   type MetaIdentity,
@@ -699,17 +700,60 @@ export function buildEntityDocData(
   //
   // ENTITY-GRAIN. Object coverage is entity-grain, so a claimed value/projection gets
   // nothing — surfacing one would imply a coverage rule the ledger does not have.
+  //
+  // "Entity-grain" is about which PAGE the row lands on, NOT about how deep the claim may
+  // point. A claim is authored at whatever grain the requirement is really about, and an L5
+  // one names a MEMBER — `acme::Subscriber.status` in the shipped showcase. `walkRequirements`
+  // resolves that to the FIELD node, so an identity test against `entity` missed it and the
+  // showcase's only claim produced no "Required by" at all. The claim belongs on the owning
+  // entity's page either way: that is where a reader looks, and the member is named in the row
+  // rather than being the reason the row disappears.
+  //
+  // Hence: match the claimed node OR any ANCESTOR of it up to and including this entity. The
+  // walk stops AT the entity, so a claim on some other object's member cannot reach this page
+  // by climbing past its own root.
+  const memberPathTo = (target: MetaData): string | undefined => {
+    const segments: string[] = [];
+    for (let n: MetaData | undefined = target; n !== undefined; n = n.parent) {
+      if (n === entity) return segments.length > 0 ? segments.reverse().join(".") : "";
+      segments.push(n.name);
+    }
+    return undefined;   // not under this entity at all
+  };
+  /** Dotted-path depth. "" is the entity itself — depth 0, not the 1 a naive split gives. */
+  const memberDepth = (path: string): number => (path === "" ? 0 : path.split(".").length);
   const claimedByMatches: UsedByDoc[] = [];
   if (entity.subType === OBJECT_SUBTYPE_ENTITY) {
     for (const walked of walkRequirements(root)) {
-      if (!walked.targets.some((t) => t.node === entity)) continue;
+      // The SHALLOWEST member path among this requirement's targets that lands on this
+      // entity: "" for an entity-grain claim, "status" for an L5 member claim. undefined
+      // when no target is under this entity.
+      let member: string | undefined;
+      let memberD = Number.POSITIVE_INFINITY;
+      for (const t of walked.targets) {
+        const path = memberPathTo(t.node);
+        if (path === undefined) continue;
+        const d = memberDepth(path);
+        // Shallowest by SEGMENT COUNT, not string length. `path.length` made "a.b" — two
+        // segments, three characters — beat "status", one segment and six, so the row
+        // named the deeper member. Ties break lexicographically so the page does not
+        // depend on the order the requirement walk happens to return targets in.
+        if (member === undefined || d < memberD || (d === memberD && path < member)) {
+          member = path;
+          memberD = d;
+        }
+      }
+      if (member === undefined) continue;
       const v = walked.view;
       const level = v.level === undefined ? "" : ` · **L${v.level}**`;
       const status = v.status === undefined ? "" : ` · status: \`${v.status}\``;
       const statement = walked.node.attr(REQUIREMENT_ATTR_STATEMENT);
       const said = typeof statement === "string" && statement.length > 0 ? ` — ${statement}` : "";
+      // A member-grain claim says WHICH member, so the row is actionable rather than
+      // merely present. An entity-grain claim renders exactly as before (byte-identical).
+      const on = member === "" ? "" : ` · on \`${member}\``;
       claimedByMatches.push({
-        bullet: `\`requirement.${v.subType} ${v.path}\`${level}${status}${said}`,
+        bullet: `\`requirement.${v.subType} ${v.path}\`${level}${status}${on}${said}`,
       });
     }
   }

package/src/generators/docs-data.ts

@@ -264,9 +264,13 @@ export interface EntityDocData {
    *  BYTE-IDENTICAL to its pre-feature output. That is the no-churn contract:
    *  a project with no ledger, or an entity nothing claims, must see no diff.
    *
-   *  ENTITY-GRAIN ONLY. Object coverage is entity-grain (`spec/capability-ledger.md`),
+   *  ENTITY PAGES ONLY. Object coverage is entity-grain (`spec/capability-ledger.md`),
    *  so a claimed `object.value` / `object.projection` gets nothing here — surfacing
-   *  one would imply a coverage rule the ledger does not actually have. */
+   *  one would imply a coverage rule the ledger does not actually have.
+   *
+   *  That governs which PAGE a row lands on, not how deep the CLAIM may point: an L5
+   *  claim names a member, resolves to the FIELD, and still renders on the owning
+   *  entity's page with the member named in the row (`· on \`status\``). */
   claimedBy?: UsedByDoc[];
   /** Present-and-non-empty flag for the claimedBy section. */
   hasClaimedBy?: boolean;

package/src/generators/index.ts

@@ -13,6 +13,7 @@ export { callableFile, type CallableFileOpts } from "./callable-file.js";
 /** @deprecated ADR-0034 — own a copy instead: `import { routesFile } from "./codegen/generators/routes"` (scaffolded by `meta init`). */
 export { routesFile, type RoutesFileOpts } from "./routes-file.js";
 export { routesFileHono, type RoutesFileHonoOpts } from "./routes-file-hono.js";
+export { namesFile } from "./names-file.js";
 /** @deprecated ADR-0034 — own a copy instead: `import { barrel } from "./codegen/generators/barrel"` (scaffolded by `meta init`). */
 export { barrel, type BarrelOpts } from "./barrel.js";
 /** @deprecated ADR-0021 D1 — neutral artifact owned by `meta docs` (ADR-0020); not part of the recommended `meta gen` suite. */
@@ -50,6 +51,15 @@ export { buildTemplateDocData } from "./template-doc-builder.js";
 // behaviour composes its own generator instead of filing an issue here.
 export { requirementTests } from "./requirement-tests.js";
 export { requirementsFile } from "./requirements-file.js";
+// The `agent` docs surface — internal engine of `meta docs --agent`, like docsFile()
+// and apiDocsFile(). Not a `meta gen` config generator.
+export { agentDocsFile, type AgentDocsFileOpts } from "./agent-docs-file.js";
+export type {
+  AgentSchemaInput,
+  SchemaColumnLike,
+  SchemaTableLike,
+  SchemaViewLike,
+} from "./agent-schema-input.js";
 export type { RequirementRow } from "./requirements-view.js";
 export type {
   RequirementTestsOpts,