docs(spec): offer the property-reference title rung only to a page with a Properties table

An enum-only module (data/feed) rendered no Properties table yet took the
'property reference' rung. The rung now reads rendersPropertiesTable(), the
section renderer's own condition, shared through declaresProperties(); a
page without a table starts at the next rung. Pinned in page-title.test.ts,
including agreement with renderSchemaSection per schema shape.

Claude-Session: https://claude.ai/code/session_01ARcDurZ5j34RdqsGgc4jgH
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

packages/spec/scripts/build-docs.ts

@@ -61,7 +61,7 @@ import {
 } from './lib/schema-index';
 import { schemaNameFromExportKey } from './lib/schema-name';
 import { formatSplitEntryCoverage, splitEntryCoverage } from './lib/split-entries';
-import { renderSchemaSection } from './lib/schema-section';
+import { renderSchemaSection, rendersPropertiesTable } from './lib/schema-section';
 import {
   categoryIndexDescription,
   modulePageDescription,
@@ -517,10 +517,17 @@ function generateZodFileMarkdown(zodFile: string, schemas: Array<{name: string,
   descriptionSources[description.from]++;
 
   // The search-facing title follows the docs title rule; `zodTitle`, the title
-  // this page carried before it, stays the sidebar label as `navTitle`.
+  // this page carried before it, stays the sidebar label as `navTitle`. A page
+  // is called a `property reference` only when one of its sections renders a
+  // `### Properties` table — the renderer's own condition, asked of the same
+  // schemas the loop below renders.
   const titles = pageTitleOrExit(() =>
     modulePageTitle(
-      { name: zodTitle, categoryTitle: CATEGORIES[category] },
+      {
+        name: zodTitle,
+        categoryTitle: CATEGORIES[category],
+        documentsProperties: schemas.some(s => rendersPropertiesTable(s.name, s.content)),
+      },
       path.relative(REPO_ROOT, path.join(DOCS_ROOT, category, `${zodFile}.mdx`)),
     ),
   );

packages/spec/scripts/lib/page-title.ts

@@ -35,6 +35,7 @@
  * the first candidate inside the band:
  *
  *   module page       `<Name> schema — <Category> property reference`   (name + category + 29)
+ *                       (offered only when the page renders a `### Properties` table)
  *                     `<Name> schema — <Category> reference`            (name + category + 20)
  *                     `<Name> — <Category> reference`                   (name + category + 13)
  *                     `<Name> — <Category>`                             (name + category + 3)
@@ -49,6 +50,18 @@
  * is 25. The category keeps two same-named modules apart (`Plugin` is both a
  * `kernel` and a `studio` page), so no two generated titles collide.
  *
+ * The first module rung is CONDITIONAL. `property reference` is a claim about
+ * the page, and a page that renders no `### Properties` table — an enum-only
+ * module such as `data/feed`, whose two schemas render `### Allowed Values`
+ * only — would be misdescribed by it. So that rung is offered only when at
+ * least one of the page's schemas renders a property table
+ * (`rendersPropertiesTable` in `lib/schema-section.ts`, the renderer's own
+ * condition); otherwise the page starts at the second rung. Without the first
+ * rung the ladder covers name + category lengths from 16 to 43 rather than 7:
+ * the shortest property-less pair on the tree is 17 (`Feed` in `Data
+ * Protocol`), and a shorter one would be refused by name — the remedy is a rung
+ * here, the same as for any page no rung fits.
+ *
  * A page no rung fits is REFUSED, never truncated: a cut title is an invented
  * one, and a title outside the band is the defect this module exists to end.
  * The refusal names the page and the candidates, and the remedy is a rung
@@ -119,12 +132,18 @@ export interface ModuleTitleInput {
   name: string;
   /** The category's declared title — `AI Protocol`. */
   categoryTitle: string;
+  /**
+   * Whether the page renders at least one `### Properties` table — required,
+   * never defaulted: the `property reference` rung is a claim about the page,
+   * and a caller that does not know must not get it by omission.
+   */
+  documentsProperties: boolean;
 }
 
-/** The module-page ladder, longest first. */
-export function modulePageTitleCandidates({ name, categoryTitle }: ModuleTitleInput): string[] {
+/** The module-page ladder, longest first; the first rung only for a page with a property table. */
+export function modulePageTitleCandidates({ name, categoryTitle, documentsProperties }: ModuleTitleInput): string[] {
   return [
-    `${name} schema${TITLE_SEPARATOR}${categoryTitle} property reference`,
+    ...(documentsProperties ? [`${name} schema${TITLE_SEPARATOR}${categoryTitle} property reference`] : []),
     `${name} schema${TITLE_SEPARATOR}${categoryTitle} reference`,
     `${name}${TITLE_SEPARATOR}${categoryTitle} reference`,
     `${name}${TITLE_SEPARATOR}${categoryTitle}`,

packages/spec/scripts/lib/schema-section.ts

@@ -90,6 +90,39 @@ export function selectRootDef(schemaName: string, schema: any): any {
   return mainDef;
 }
 
+/**
+ * Whether a node renders as a `### Properties` table: an object that declares
+ * its properties. The ONE spelling of that condition — {@link renderSchemaSection}
+ * branches on it for the schema root and for each union arm, and
+ * {@link rendersPropertiesTable} asks it for the page title.
+ */
+export function declaresProperties(node: any): boolean {
+  return node?.type === 'object' && !!node.properties;
+}
+
+/**
+ * Whether {@link renderSchemaSection} gives this schema at least one
+ * `### Properties` table — at its root, or in an arm of its `### Union Options`.
+ *
+ * Read by the page title (`lib/page-title.ts`, #15403): a module page is titled
+ * a `property reference` only when one of its schemas really renders a property
+ * table. An enum-only module (`data/feed`: two string enums, `### Allowed Values`
+ * only) documents no property, and a title saying it does misdescribes the page.
+ *
+ * Same branch order as the renderer: an object root with properties renders its
+ * table; a string enum renders `### Allowed Values` and nothing else, even when
+ * it also carries a union; a union renders a table for each arm that declares
+ * properties; every other root renders one type line. `page-title.test.ts` holds
+ * this answer equal to what the renderer emits, shape by shape.
+ */
+export function rendersPropertiesTable(schemaName: string, schema: any): boolean {
+  const mainDef = selectRootDef(schemaName, schema);
+  if (declaresProperties(mainDef)) return true;
+  if (mainDef.type === 'string' && mainDef.enum) return false;
+  const variants = mainDef.anyOf || mainDef.oneOf;
+  return Array.isArray(variants) && variants.some(declaresProperties);
+}
+
 /**
  * Character budget for a default value spelled inside the Required cell.
  *
@@ -555,7 +588,7 @@ export function renderSchemaSection(schemaName: string, schema: any, ctx: Sectio
       return t;
   };
 
-  if (mainDef.type === 'object' && mainDef.properties) {
+  if (declaresProperties(mainDef)) {
     md += renderProperties(mainDef.properties, new Set(mainDef.required || []));
 
   } else if (mainDef.type === 'string' && mainDef.enum) {
@@ -571,9 +604,7 @@ export function renderSchemaSection(schemaName: string, schema: any, ctx: Sectio
      // branch below calls `renderProperties`, and only `renderProperties`
      // emits `### Nested Shape:` / `### Allowed Values:` headings. An `enum`,
      // `$ref` or scalar arm prints one line and can collide with nothing.
-     const emitsHeadings: boolean[] = variants.map(
-       (variant: any) => variant?.type === 'object' && !!variant.properties,
-     );
+     const emitsHeadings: boolean[] = variants.map(declaresProperties);
      const emitters = emitsHeadings.filter(Boolean).length;
      // Fewer than two and there is nothing to tell apart: a lone object arm's
      // headings are already unique on the page, so it keeps the exact bytes it
@@ -588,7 +619,7 @@ export function renderSchemaSection(schemaName: string, schema: any, ctx: Sectio
          md += `#### ${variantTitle}\n\n`;
          if (variant.description) md += `${escapeMdxDescription(variant.description)}\n\n`;
 
-         if (variant.type === 'object' && variant.properties) {
+         if (declaresProperties(variant)) {
               if (variant.properties.type && variant.properties.type.const) {
                   md += `**Type:** \`${variant.properties.type.const}\`\n\n`;
               }

packages/spec/scripts/page-title.test.ts

@@ -2,7 +2,8 @@
 
 /**
  * Pin for the frontmatter `title` / `navTitle` of generated reference pages
- * (#15403).
+ * (#15403), and for the one page fact the title reads besides names: whether
+ * the page renders a `### Properties` table.
  *
  * `check:docs` compares the regenerated tree with the committed one, so it
  * holds the OUTPUT still but says nothing about the rule: a regression that
@@ -15,6 +16,7 @@
 import { describe, expect, it } from 'vitest';
 
 import { CATEGORY_TITLES } from './lib/category-title';
+import { declaresProperties, renderSchemaSection, rendersPropertiesTable } from './lib/schema-section';
 import {
   RENDERED_TITLE_MAX,
   ROOT_INDEX_NAV_TITLE,
@@ -57,69 +59,153 @@ describe('the band', () => {
 });
 
 /**
- * Real `(module name, category title)` pairs from `content/docs/references/**`
- * at `862b6ce8`, the name being the page's title before this rule — two per
- * rung of the module ladder, including the tree's shortest name (`Mcp`, 3) and
- * its two longest pairs (`Expression Bindable Text Keys` in UI, name 29;
- * `Schemaless Node Config` in Automation, name + category 41).
+ * Real `(module name, category title, renders a Properties table)` triples from
+ * `content/docs/references/**`, the name being the page's title before this
+ * rule — two per rung of the module ladder, including the tree's shortest name
+ * (`Mcp`, 3), its two longest pairs (`Expression Bindable Text Keys` in UI, name
+ * 29; `Schemaless Node Config` in Automation, name + category 41), and
+ * `data/feed`, the one page the first rung reached without a property table.
  */
-const MODULE_PAGES: Array<[name: string, categoryTitle: string, title: string]> = [
-  ['Mcp', 'AI Protocol', 'Mcp schema — AI Protocol property reference'],
-  ['Agent', 'AI Protocol', 'Agent schema — AI Protocol property reference'],
-  ['Object', 'Data Protocol', 'Object schema — Data Protocol reference'],
-  ['Flow', 'Automation Protocol', 'Flow schema — Automation Protocol reference'],
-  ['Plugin Registry', 'Kernel Protocol', 'Plugin Registry — Kernel Protocol reference'],
-  ['Package Api Assembled', 'API Protocol', 'Package Api Assembled — API Protocol reference'],
-  ['Metadata Protection', 'Kernel Protocol', 'Metadata Protection — Kernel Protocol'],
-  ['Expression Bindable Text Keys', 'UI Protocol', 'Expression Bindable Text Keys — UI Protocol'],
-  ['Schemaless Node Config', 'Automation Protocol', 'Schemaless Node Config — Automation Protocol'],
+const MODULE_PAGES: Array<[name: string, categoryTitle: string, documentsProperties: boolean, title: string]> = [
+  ['Mcp', 'AI Protocol', true, 'Mcp schema — AI Protocol property reference'],
+  ['Agent', 'AI Protocol', true, 'Agent schema — AI Protocol property reference'],
+  ['Feed', 'Data Protocol', false, 'Feed schema — Data Protocol reference'],
+  ['Object', 'Data Protocol', true, 'Object schema — Data Protocol reference'],
+  ['Flow', 'Automation Protocol', true, 'Flow schema — Automation Protocol reference'],
+  ['Plugin Registry', 'Kernel Protocol', true, 'Plugin Registry — Kernel Protocol reference'],
+  ['Package Api Assembled', 'API Protocol', true, 'Package Api Assembled — API Protocol reference'],
+  ['Metadata Protection', 'Kernel Protocol', false, 'Metadata Protection — Kernel Protocol'],
+  ['Expression Bindable Text Keys', 'UI Protocol', false, 'Expression Bindable Text Keys — UI Protocol'],
+  ['Schemaless Node Config', 'Automation Protocol', true, 'Schemaless Node Config — Automation Protocol'],
 ];
 
 describe('modulePageTitle', () => {
-  it.each(MODULE_PAGES)('%s (%s) → %s', (name, categoryTitle, title) => {
-    const out = modulePageTitle({ name, categoryTitle }, `references/x/${name}.mdx`);
+  it.each(MODULE_PAGES)('%s (%s, properties: %s) → %s', (name, categoryTitle, documentsProperties, title) => {
+    const out = modulePageTitle({ name, categoryTitle, documentsProperties }, `references/x/${name}.mdx`);
     expect(out).toEqual({ title, navTitle: name });
     expectRuleShaped(out.title);
   });
 
   it('takes the LONGEST rung inside the band', () => {
     // `Agent` fits the first rung (45) and the second (36): the first wins.
-    const candidates = modulePageTitleCandidates({ name: 'Agent', categoryTitle: 'AI Protocol' });
+    const agent = { name: 'Agent', categoryTitle: 'AI Protocol', documentsProperties: true };
+    const candidates = modulePageTitleCandidates(agent);
     expect(candidates.filter(titleInBand)).toHaveLength(2);
-    expect(modulePageTitle({ name: 'Agent', categoryTitle: 'AI Protocol' }, 'p').title).toBe(candidates[0]);
+    expect(modulePageTitle(agent, 'p').title).toBe(candidates[0]);
+  });
+
+  it('offers `property reference` only to a page that renders a Properties table', () => {
+    // The same name and category, the one fact flipped: `data/feed` renders two
+    // enums (`### Allowed Values`) and no property, so it starts at the second rung.
+    const feed = { name: 'Feed', categoryTitle: 'Data Protocol' };
+    const withTable = modulePageTitleCandidates({ ...feed, documentsProperties: true });
+    const withoutTable = modulePageTitleCandidates({ ...feed, documentsProperties: false });
+    expect(withTable[0]).toBe('Feed schema — Data Protocol property reference');
+    expect(withoutTable.some(c => c.includes('property'))).toBe(false);
+    expect(withoutTable).toEqual(withTable.slice(1));
+    expect(modulePageTitle({ ...feed, documentsProperties: false }, 'p').title).toBe('Feed schema — Data Protocol reference');
   });
 
   it('keeps the rungs longest first, so the first fit is the longest fit', () => {
-    const lengths = modulePageTitleCandidates({ name: 'N', categoryTitle: 'C' }).map(c => c.length);
-    expect([...lengths].sort((a, b) => b - a)).toEqual(lengths);
+    for (const documentsProperties of [true, false]) {
+      const lengths = modulePageTitleCandidates({ name: 'N', categoryTitle: 'C', documentsProperties }).map(c => c.length);
+      expect([...lengths].sort((a, b) => b - a)).toEqual(lengths);
+    }
   });
 
   it('is total for every declared category and every name that can fit beside it', () => {
-    // The ladder's rungs overlap end to end: every name + category length from
-    // 7 to 43 lands in the band. Swept over the real category titles, with
-    // every name length up to the limit that category leaves.
+    // With a Properties table the rungs overlap end to end from name + category
+    // 7 to 43; without one, from 16 to 43. Swept over the real category titles,
+    // with every name length up to the limit that category leaves.
     for (const categoryTitle of Object.values(CATEGORY_TITLES)) {
       for (let n = 1; categoryTitle.length + n <= 43; n++) {
-        expectRuleShaped(modulePageTitle({ name: 'N'.repeat(n), categoryTitle }, 'p').title);
+        expectRuleShaped(modulePageTitle({ name: 'N'.repeat(n), categoryTitle, documentsProperties: true }, 'p').title);
+        if (categoryTitle.length + n >= 16) {
+          expectRuleShaped(modulePageTitle({ name: 'N'.repeat(n), categoryTitle, documentsProperties: false }, 'p').title);
+        }
       }
     }
   });
 
+  it('refuses a property-less page too short for the second rung, naming it', () => {
+    // name + category 15: the second rung is 35, one under the band.
+    expect(() =>
+      modulePageTitle({ name: 'Abcd', categoryTitle: 'AI Protocol', documentsProperties: false }, 'content/docs/references/ai/abcd.mdx'),
+    ).toThrow(/content\/docs\/references\/ai\/abcd\.mdx/);
+  });
+
   it('keeps two same-named modules in different categories apart', () => {
-    const kernel = modulePageTitle({ name: 'Plugin', categoryTitle: 'Kernel Protocol' }, 'p').title;
-    const studio = modulePageTitle({ name: 'Plugin', categoryTitle: 'Studio Protocol' }, 'p').title;
+    const kernel = modulePageTitle({ name: 'Plugin', categoryTitle: 'Kernel Protocol', documentsProperties: true }, 'p').title;
+    const studio = modulePageTitle({ name: 'Plugin', categoryTitle: 'Studio Protocol', documentsProperties: true }, 'p').title;
     expect(kernel).not.toBe(studio);
   });
 
   it('refuses, naming the page, when no rung fits — never a truncated title', () => {
-    const tooLong = { name: 'An Exceedingly Long Module Display Name', categoryTitle: 'Integration Protocol' };
+    const tooLong = { name: 'An Exceedingly Long Module Display Name', categoryTitle: 'Integration Protocol', documentsProperties: true };
     expect(modulePageTitleCandidates(tooLong).some(titleInBand)).toBe(false);
     expect(() => modulePageTitle(tooLong, 'content/docs/references/integration/long.mdx')).toThrow(
       /content\/docs\/references\/integration\/long\.mdx/,
     );
   });
 });
 
+/**
+ * The fact the first module rung reads — whether a schema renders a
+ * `### Properties` table — held equal to what the renderer really emits, one
+ * JSON Schema shape per branch of `renderSchemaSection`. If a branch changes
+ * what it renders and the predicate does not follow, this goes red instead of
+ * a title quietly claiming a table its page lacks.
+ */
+const SECTION_SHAPES: Array<[shape: string, name: string, schema: any, rendersTable: boolean]> = [
+  ['object root with properties', 'Agent', { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] }, true],
+  ['string enum (data/feed FeedFilterMode)', 'FeedFilterMode', { type: 'string', enum: ['all', 'comments_only', 'changes_only', 'tasks_only'] }, false],
+  ['string enum (data/feed FeedItemType)', 'FeedItemType', { type: 'string', enum: ['comment', 'field_change', 'task'] }, false],
+  [
+    'union with an object arm',
+    'Trigger',
+    { anyOf: [{ type: 'object', properties: { type: { type: 'string', const: 'cron' }, expr: { type: 'string' } } }, { type: 'string' }] },
+    true,
+  ],
+  ['oneOf with an object arm', 'Source', { oneOf: [{ type: 'object', properties: { url: { type: 'string' } } }, { type: 'number' }] }, true],
+  ['union of an enum and a scalar', 'Mode', { anyOf: [{ type: 'string', enum: ['a', 'b'] }, { type: 'number' }] }, false],
+  [
+    'string enum that also carries a union (the enum branch wins)',
+    'Kind',
+    { type: 'string', enum: ['a'], anyOf: [{ type: 'object', properties: { x: { type: 'string' } } }] },
+    false,
+  ],
+  ['bare scalar', 'ObjectName', { type: 'string', description: 'Machine name' }, false],
+  ['record map (additionalProperties, no properties)', 'Labels', { type: 'object', additionalProperties: { type: 'string' } }, false],
+  ['array of objects', 'Rows', { type: 'array', items: { type: 'object', properties: { id: { type: 'string' } } } }, false],
+  [
+    'definitions entry under its own name',
+    'Wrapped',
+    { $ref: '#/definitions/Wrapped', definitions: { Wrapped: { type: 'object', properties: { a: { type: 'number' } } } } },
+    true,
+  ],
+];
+
+describe('rendersPropertiesTable', () => {
+  it.each(SECTION_SHAPES)('%s → %s', (_shape, name, schema, rendersTable) => {
+    expect(rendersPropertiesTable(name, schema)).toBe(rendersTable);
+    // The renderer's own output agrees, whatever the expectation above says.
+    expect(/^### Properties$/m.test(renderSchemaSection(name, schema))).toBe(rendersTable);
+  });
+
+  it('answers the data/feed page as having no property table', () => {
+    const feed = SECTION_SHAPES.filter(([shape]) => shape.includes('data/feed'));
+    expect(feed).toHaveLength(2);
+    expect(feed.some(([, name, schema]) => rendersPropertiesTable(name, schema))).toBe(false);
+  });
+
+  it('declaresProperties is the object-with-properties test and nothing wider', () => {
+    expect(declaresProperties({ type: 'object', properties: { a: { type: 'string' } } })).toBe(true);
+    expect(declaresProperties({ type: 'object' })).toBe(false);
+    expect(declaresProperties({ properties: { a: {} } })).toBe(false);
+    expect(declaresProperties(undefined)).toBe(false);
+  });
+});
+
 describe('categoryIndexTitle', () => {
   it.each([
     ['AI Protocol', 'AI Protocol — complete schema reference'],