objectstack-ai · os-trump · Aug 25, 2026 · Aug 25, 2026 · Aug 25, 2026
diff --git a/.changeset/skill-refs-module-docblock.md b/.changeset/skill-refs-module-docblock.md
@@ -0,0 +1,33 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): publish each skill reference's own module doc block, not the first doc block in the file
+
+`build-skill-references.ts` derived every `_index.md` pointer description from
+the first doc block anywhere in the source file. That is a rule about ORDERING,
+not about descriptions: whichever declaration happened to sit nearest the top of
+a `.zod.ts` donated its comment to a customer-facing page, and moving a helper
+up a file silently rewrote published text.
+
+This is the defect the docs-site generator fixed by converging on
+`findModuleDocBlock()` — the block must start at column 0, precede the first
+declaration, and document no symbol. The skill-references generator was never
+converted, so the two generators disagreed about the same sources. It now
+imports the same selector rather than restating the rule, and `skills/**` is
+loaded whole into customer agent context windows, so it was paying the higher
+price for the same defect.
+
+Thirteen pointer rows across seven skills change. The live victim named on the
+issue is `system/translation.zod.ts`, whose `objectstack-i18n` entry opened with
+"Shared history sentence for every shape in this file." — the comment on a
+private `TRANSLATION_HISTORY` string constant, meaningless to the reader and not
+a description of the Translation protocol. Twelve rows in that class now fall
+through to the existing `Exports: …` line, and one gains a real module
+description (`shared/metadata-types.zod.ts`), which also brings it into
+agreement with the docs page for the same file.
+
+Falling back rather than refusing is deliberate: an export list states a true
+fact about the file, where the wrong block asserted a false one about its
+subject. Whether a `.zod.ts` on this surface should be required to carry a
+module doc block at all is a separate authoring question, left open here.
diff --git a/packages/spec/scripts/build-skill-references.ts b/packages/spec/scripts/build-skill-references.ts
@@ -16,7 +16,7 @@
  * 2. Recursively resolves local `import … from` dependencies (so the index
  * surfaces shared schemas an agent will need to follow)
  * 3. Writes `skills/{name}/references/_index.md` with pointers + one-line
- * descriptions extracted from each file's leading JSDoc comment
+ * descriptions taken from each file's own MODULE doc block
  *
  * Usage:
  * tsx scripts/build-skill-references.ts # write
@@ -25,6 +25,7 @@
 
 import fs from 'fs';
 import path from 'path';
+import { findModuleDocBlock } from './lib/file-description';
 import { createSink, type Owns } from './lib/generated-output';
 
 // ── Paths ────────────────────────────────────────────────────────────────────
@@ -192,13 +193,31 @@ function resolveAll(entryFiles: string[]): { files: string[]; missing: string[]
  return { files: shipped.sort(), missing };
 }
 
-// ── JSDoc description extractor ──────────────────────────────────────────────
+// ── Module description extractor ─────────────────────────────────────────────
 
+/**
+ * The pointer row's one-line description: the first sentence of the module's
+ * OWN doc block, or `Exports: …` when the module has none.
+ *
+ * WHICH block that is comes from the shared `findModuleDocBlock()` — the same
+ * selector `build-docs.ts` uses, imported rather than restated so one rule
+ * serves both surfaces. This generator used to take the first doc block
+ * anywhere in the file: a rule about ORDERING, not about descriptions, so
+ * whichever declaration sat nearest the top donated its comment to a
+ * customer-facing page (`system/translation.zod.ts` published the comment on
+ * its private `TRANSLATION_HISTORY` const). `check:skill-refs` cannot see that
+ * — it compares the artifact against the generator, which reproduced the wrong
+ * block faithfully.
+ *
+ * A module with no doc block of its own falls through to the export list
+ * rather than refusing: that line states a true fact about the file, where the
+ * wrong block asserted a false one about its subject.
+ */
 function extractDescription(filePath: string): string {
  const content = fs.readFileSync(filePath, 'utf-8');
- const jsdocMatch = content.match(/\/\*\*\s*\n([\s\S]*?)\*\//);
- if (jsdocMatch) {
- const lines = jsdocMatch[1]
+ const moduleBlock = findModuleDocBlock(content);
+ if (moduleBlock !== null) {
+ const lines = moduleBlock
  .split('\n')
  .map((line) => line.replace(/^\s*\*\s?/, '').trim())
  .filter((line) => line && !line.startsWith('@') && !line.startsWith('```'));

diff --git a/skills/objectstack-ai/references/_index.md b/skills/objectstack-ai/references/_index.md
@@ -17,7 +17,7 @@ from `node_modules` — there is no local copy in the skill bundle.
 - `node_modules/@objectstack/spec/src/ai/mcp.zod.ts` — Model Context Protocol (MCP) — Reference & Binding Primitives
 - `node_modules/@objectstack/spec/src/ai/model-registry.zod.ts` — AI Model Registry Protocol
 - `node_modules/@objectstack/spec/src/ai/skill.zod.ts` — Skill Trigger Condition Schema
-- `node_modules/@objectstack/spec/src/ai/tool.zod.ts` — Retired `ToolSchema` keys — the rejection carries the upgrade prescription,
+- `node_modules/@objectstack/spec/src/ai/tool.zod.ts` — Exports: ToolSchema
 - `node_modules/@objectstack/spec/src/ai/usage.zod.ts` — AI Usage Primitives
 
 ## Transitive dependencies

diff --git a/skills/objectstack-api/references/_index.md b/skills/objectstack-api/references/_index.md
@@ -13,14 +13,14 @@ from `node_modules` — there is no local copy in the skill bundle.
 - `node_modules/@objectstack/spec/src/api/batch.zod.ts` — Batch Operations API
 - `node_modules/@objectstack/spec/src/api/endpoint.zod.ts` — API Mapping Schema
 - `node_modules/@objectstack/spec/src/api/errors.zod.ts` — Standardized Error Codes Protocol
-- `node_modules/@objectstack/spec/src/api/realtime.zod.ts` — Transport Protocol Enum
+- `node_modules/@objectstack/spec/src/api/realtime.zod.ts` — Exports: TransportProtocol, RealtimeEventType, SubscriptionEventSchema, SubscriptionSchema, RealtimePresenceSchema
 - `node_modules/@objectstack/spec/src/api/rest-server.zod.ts` — REST API Server Protocol
 - `node_modules/@objectstack/spec/src/api/versioning.zod.ts` — API Versioning Protocol
 - `node_modules/@objectstack/spec/src/api/websocket.zod.ts` — WebSocket Event Protocol
 
 ## Transitive dependencies
 
-- `node_modules/@objectstack/spec/src/api/contract.zod.ts` — Machine-readable semantic code (ADR-0112): a `StandardErrorCode` member or
+- `node_modules/@objectstack/spec/src/api/contract.zod.ts` — Exports: ApiErrorSchema, BaseResponseSchema, RecordDataSchema, CreateRequestSchema, UpdateRequestSchema
 - `node_modules/@objectstack/spec/src/api/error-code-ledger.zod.ts` — Error-Code Ledger (ADR-0112 D3).
 - `node_modules/@objectstack/spec/src/api/realtime-shared.zod.ts` — Realtime Shared Protocol
 - `node_modules/@objectstack/spec/src/data/data-engine.zod.ts` — Data Engine Protocol

diff --git a/skills/objectstack-automation/references/_index.md b/skills/objectstack-automation/references/_index.md
@@ -9,7 +9,7 @@ from `node_modules` — there is no local copy in the skill bundle.
 
 ## Core schemas
 
-- `node_modules/@objectstack/spec/src/automation/approval.zod.ts` — Approval Step Approver Type
+- `node_modules/@objectstack/spec/src/automation/approval.zod.ts` — Exports: ApproverType, DEPRECATED_APPROVER_TYPES, NON_AUTHORABLE_APPROVER_TYPES, ORG_MEMBERSHIP_LEVELS, APPROVER_EXPRESSION_ROOTS
 - `node_modules/@objectstack/spec/src/automation/execution.zod.ts` — Automation Execution Protocol
 - `node_modules/@objectstack/spec/src/automation/flow.zod.ts` — Flow Node Types — **built-in seed set** (ADR-0018).
 - `node_modules/@objectstack/spec/src/automation/node-executor.zod.ts` — Node Executor Plugin Protocol — Wait Node Pause/Resume

diff --git a/skills/objectstack-data/references/_index.md b/skills/objectstack-data/references/_index.md
@@ -33,7 +33,7 @@ from `node_modules` — there is no local copy in the skill bundle.
 - `node_modules/@objectstack/spec/src/data/driver/turso.zod.ts` — Turso / libSQL Driver Protocol.
 - `node_modules/@objectstack/spec/src/data/field-value.zod.ts` — Field runtime VALUE-shape contract (ADR-0104 D1).
 - `node_modules/@objectstack/spec/src/data/filter.zod.ts` — Unified Query DSL Specification
-- `node_modules/@objectstack/spec/src/data/hook-body.zod.ts` — Capability tokens a script body may request.
+- `node_modules/@objectstack/spec/src/data/hook-body.zod.ts` — Exports: HookBodyCapability, ExpressionBodySchema, ScriptBodySchema, HookBodySchema
 - `node_modules/@objectstack/spec/src/data/query.zod.ts` — Sort Node
 - `node_modules/@objectstack/spec/src/kernel/metadata-protection.zod.ts` — Metadata Protection Model — Phase 1 (ADR-0010)
 - `node_modules/@objectstack/spec/src/security/rls.zod.ts` — Row-Level Security (RLS) Protocol

diff --git a/skills/objectstack-i18n/references/_index.md b/skills/objectstack-i18n/references/_index.md
@@ -9,7 +9,7 @@ from `node_modules` — there is no local copy in the skill bundle.
 
 ## Core schemas
 
-- `node_modules/@objectstack/spec/src/system/translation.zod.ts` — Shared history sentence for every shape in this file.
+- `node_modules/@objectstack/spec/src/system/translation.zod.ts` — Exports: LocaleSchema, FieldTranslationSchema, ActionResultDialogTranslationSchema, ObjectTranslationDataSchema, LEGACY_OBJECT_FIRST_KEYS
 - `node_modules/@objectstack/spec/src/ui/i18n.zod.ts` — Display-label and ARIA-label primitives shared by every `ui/` shape.
 
 ## Transitive dependencies

diff --git a/skills/objectstack-platform/references/_index.md b/skills/objectstack-platform/references/_index.md
@@ -12,11 +12,11 @@ from `node_modules` — there is no local copy in the skill bundle.
 - `node_modules/@objectstack/spec/src/data/datasource.zod.ts` — Driver Identifier
 - `node_modules/@objectstack/spec/src/data/seed.zod.ts` — Seed Import Strategy
 - `node_modules/@objectstack/spec/src/kernel/context.zod.ts` — Runtime Mode Enum
-- `node_modules/@objectstack/spec/src/kernel/manifest.zod.ts` — Structured permission grants requested by a plugin (ADR-0025 §3.2).
+- `node_modules/@objectstack/spec/src/kernel/manifest.zod.ts` — Exports: PluginPermissionsSchema, ManifestPermissionsSchema, PluginEnginesSchema, PluginRuntimeSchema, PluginPackagingSchema
 - `node_modules/@objectstack/spec/src/kernel/metadata-plugin.zod.ts` — Metadata Plugin Protocol
 - `node_modules/@objectstack/spec/src/kernel/plugin-capability.zod.ts` — Plugin Capability Protocol
 - `node_modules/@objectstack/spec/src/kernel/plugin-loading.zod.ts` — Plugin Loading Protocol
-- `node_modules/@objectstack/spec/src/kernel/plugin.zod.ts` — Shared Plugin Types
+- `node_modules/@objectstack/spec/src/kernel/plugin.zod.ts` — Exports: PluginContextSchema, CORE_PLUGIN_TYPES, CONSUMER_INSTALLABLE_TYPES, PluginSchema
 - `node_modules/@objectstack/spec/src/kernel/service-registry.zod.ts` — Service Registry Protocol
 
 ## Transitive dependencies
@@ -33,14 +33,14 @@ from `node_modules` — there is no local copy in the skill bundle.
 - `node_modules/@objectstack/spec/src/data/field-value.zod.ts` — Field runtime VALUE-shape contract (ADR-0104 D1).
 - `node_modules/@objectstack/spec/src/data/field.zod.ts` — Field Type Enum
 - `node_modules/@objectstack/spec/src/data/filter.zod.ts` — Unified Query DSL Specification
-- `node_modules/@objectstack/spec/src/data/hook-body.zod.ts` — Capability tokens a script body may request.
+- `node_modules/@objectstack/spec/src/data/hook-body.zod.ts` — Exports: HookBodyCapability, ExpressionBodySchema, ScriptBodySchema, HookBodySchema
 - `node_modules/@objectstack/spec/src/kernel/cluster.zod.ts` — Cluster Protocol
 - `node_modules/@objectstack/spec/src/kernel/metadata-customization.zod.ts` — Metadata Customization Layer Protocol
 - `node_modules/@objectstack/spec/src/kernel/metadata-loader.zod.ts` — Metadata Manager Configuration
 - `node_modules/@objectstack/spec/src/kernel/metadata-protection.zod.ts` — Metadata Protection Model — Phase 1 (ADR-0010)
 - `node_modules/@objectstack/spec/src/shared/expression.zod.ts` — Expression Protocol
 - `node_modules/@objectstack/spec/src/shared/identifiers.zod.ts` — System Identifier Schema
-- `node_modules/@objectstack/spec/src/shared/metadata-types.zod.ts` — Exports: MetadataFormatSchema, BaseMetadataRecordSchema
+- `node_modules/@objectstack/spec/src/shared/metadata-types.zod.ts` — Supported metadata file formats
 - `node_modules/@objectstack/spec/src/shared/protection.zod.ts` — Package-level metadata protection (ADR-0010 §3.7 — Phase 4.3)
 - `node_modules/@objectstack/spec/src/shared/suggestions.zod.ts` — "Did you mean?" Suggestion Utilities
 - `node_modules/@objectstack/spec/src/system/tenant.zod.ts` — Tenant Schema (Multi-Tenant Architecture)

diff --git a/skills/objectstack-ui/references/_index.md b/skills/objectstack-ui/references/_index.md
@@ -18,7 +18,7 @@ from `node_modules` — there is no local copy in the skill bundle.
 - `node_modules/@objectstack/spec/src/ui/page.zod.ts` — Page Region Schema
 - `node_modules/@objectstack/spec/src/ui/report.zod.ts` — Report Type Enum
 - `node_modules/@objectstack/spec/src/ui/view.zod.ts` — HTTP Method Enum & HTTP Request Schema
-- `node_modules/@objectstack/spec/src/ui/widget.zod.ts` — Field Widget Props Schema
+- `node_modules/@objectstack/spec/src/ui/widget.zod.ts` — Exports: FieldWidgetPropsSchema
 
 ## Transitive dependencies
 
@@ -28,7 +28,7 @@ from `node_modules` — there is no local copy in the skill bundle.
 - `node_modules/@objectstack/spec/src/data/field-value.zod.ts` — Field runtime VALUE-shape contract (ADR-0104 D1).
 - `node_modules/@objectstack/spec/src/data/field.zod.ts` — Field Type Enum
 - `node_modules/@objectstack/spec/src/data/filter.zod.ts` — Unified Query DSL Specification
-- `node_modules/@objectstack/spec/src/data/hook-body.zod.ts` — Capability tokens a script body may request.
+- `node_modules/@objectstack/spec/src/data/hook-body.zod.ts` — Exports: HookBodyCapability, ExpressionBodySchema, ScriptBodySchema, HookBodySchema
 - `node_modules/@objectstack/spec/src/data/query.zod.ts` — Sort Node
 - `node_modules/@objectstack/spec/src/kernel/metadata-protection.zod.ts` — Metadata Protection Model — Phase 1 (ADR-0010)
 - `node_modules/@objectstack/spec/src/shared/enums.zod.ts` — Exports: SortDirectionEnum, SortItemSchema, MutationEventEnum, IsolationLevelEnum
@@ -40,7 +40,7 @@ from `node_modules` — there is no local copy in the skill bundle.
 - `node_modules/@objectstack/spec/src/ui/action-params.zod.ts` — The action DISPATCH contract: what the platform validates on the way in, and
 - `node_modules/@objectstack/spec/src/ui/bulk-action.zod.ts` — Bulk Action Schemas
 - `node_modules/@objectstack/spec/src/ui/i18n.zod.ts` — Display-label and ARIA-label primitives shared by every `ui/` shape.
-- `node_modules/@objectstack/spec/src/ui/responsive.zod.ts` — Style Map Schema (ADR-0065)
+- `node_modules/@objectstack/spec/src/ui/responsive.zod.ts` — Exports: StyleMapSchema, ResponsiveStylesSchema
 - `node_modules/@objectstack/spec/src/ui/sharing.zod.ts` — Sharing & Embedding Protocol
 
 ## How to read these