Select an import-list doc block as module description only on an explicit @module marker, and re-attach the eight wedged schema comments (#13794)

* Select an import-list doc block as module description only on an explicit @module marker

Route 1 of #13334: inside the import list — imports before the block, an
import the first thing after it — no positional signal separates a genuine
module header from one schema's detached comment (the card measured every
signal; only the prose differs). The selector now asks the author instead:
only a block carrying @module on a prose line selects there, in both
directions, with the one exception of plumbing that runs to EOF (a pure
re-export module has no symbol the block could have been torn from).

The two genuine headers in that position, shared/mapping and system/cache,
each gain the one-line marker — the repo's existing spelling, fourteen
headers above their imports already open with it. No other source is touched.

Measured over all 208 corpus sources, old selector vs new: 200 verdicts
byte-identical, exactly the 8 misattributed openings flip SELECTED->null,
0 change to a different block.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PBjwYLS6BciTQW3c9xQiD2

* Move the eight wedged doc blocks back to the declarations they document

Route 2 of #13334. The lazify codemod's injected import had wedged itself
between each block and its symbol; the injected imports move up into the
import block and each comment moves back against its subject — verbatim, a
position fix, not a rewrite. Editor hover is restored for the four symbols
that had no attached doc at all: AIModelConfigSchema, DriverType,
ActionParamSchema, PageRegionSchema. In the other four modules (data/hook,
security/permission, ui/app, ui/component) the documented symbol or family
head already carries its own richer JSDoc, so the moved block sits directly
above it as a section lead and hover was already correct — a refinement of
the card's reading, recorded in the PR.

Regenerated: 10 reference pages (8 lose the misattributed opening, 2 gain
their @module line) and 4 published skill indexes (8 pointer rows fall back
to the honest export list). Changeset included; no schema behavior changes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PBjwYLS6BciTQW3c9xQiD2

* regenerate ui/component reference page on the merged tree

Discharges the os-regen deferral recorded by the merge commit. The page now
carries main's section-group-reference body and no longer opens with the
misattributed 'Empty Properties Schema' block, which is this branch's route-1
gate acting on the merged tree.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PBjwYLS6BciTQW3c9xQiD2

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-warren

.changeset/module-doc-block-selection.md

@@ -0,0 +1,15 @@
+---
+'@objectstack/spec': patch
+---
+
+Reference pages and skill indexes no longer open with one schema's comment: a
+doc block sitting inside a module's import list is selected as the module
+description only when it carries an explicit `@module` marker. The two genuine
+headers in that position (`shared/mapping`, `system/cache`) now carry the
+marker; the eight modules whose "description" was a detached symbol comment
+(`ai/agent`, `data/datasource`, `data/hook`, `security/permission`,
+`ui/action`, `ui/app`, `ui/component`, `ui/page`) had the comment moved back to
+the declaration it documents — restoring editor hover for
+`AIModelConfigSchema`, `DriverType`, `ActionParamSchema` and
+`PageRegionSchema` — and their pages honestly print no module description
+instead of a wrong one. No schema behavior changes.

content/docs/references/ai/agent.mdx

@@ -5,8 +5,6 @@ description: Agent protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
-AI Model Configuration
-
 <Callout type="info">
 **Source:** `packages/spec/src/ai/agent.zod.ts`
 </Callout>

content/docs/references/data/datasource.mdx

@@ -5,9 +5,6 @@ description: Datasource protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
-Driver Identifier
-Can be a built-in driver or a plugin-contributed driver (e.g., "com.vendor.snowflake").
-
 <Callout type="info">
 **Source:** `packages/spec/src/data/datasource.zod.ts`
 </Callout>

content/docs/references/data/hook.mdx

@@ -5,9 +5,6 @@ description: Hook protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
-Hook Lifecycle Events
-Defines the interception points in the ObjectQL execution pipeline.
-
 <Callout type="info">
 **Source:** `packages/spec/src/data/hook.zod.ts`
 </Callout>

content/docs/references/security/permission.mdx

@@ -5,14 +5,6 @@ description: Permission protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
-Entity (Object) Level Permissions
-Defines CRUD + VAMA (View All / Modify All) + Lifecycle access.
-
-Refined with enterprise data lifecycle controls:
-- Transfer (Ownership change)
-- Restore (Soft delete recovery)
-- Purge (Hard delete / Compliance)
-
 <Callout type="info">
 **Source:** `packages/spec/src/security/permission.zod.ts`
 </Callout>

content/docs/references/shared/mapping.mdx

@@ -5,6 +5,8 @@ description: Mapping protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
+@module shared/mapping
+
 Base Field Mapping Protocol
 
 Shared by: Connector

content/docs/references/system/cache.mdx

@@ -5,6 +5,8 @@ description: Cache protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
+@module system/cache
+
 Application-Level Cache Protocol
 
 Multi-tier caching strategy for application data.

content/docs/references/ui/action.mdx

@@ -5,39 +5,6 @@ description: Action protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
-Action Parameter Schema
-
-Defines inputs required before executing an action.
-
-Two declaration modes:
-
-1. **Field-backed** (preferred) — reference an existing object field; the
-   runtime resolves the field's label (i18n), type, validation rules,
-   options, placeholder, help text, and widget mapping from object
-   metadata. Cross-object references use `objectOverride`.
-
-   ```ts
-   params: [
-     { field: 'email' },                                 // same object
-     { field: 'role', objectOverride: 'sys_member' },    // different object
-   ]
-   ```
-
-2. **Inline** (legacy / bespoke) — declare `name`, `label`, `type` etc.
-   inline when no matching object field exists. Inline values may also be
-   used alongside `field` to override individual properties. A `lookup` /
-   `master_detail` param declared this way MUST name its target object via
-   `reference` — there is no field to inherit it from:
-
-   ```ts
-   params: [
-     { name: 'inspector', label: 'Inspector', type: 'lookup', reference: 'sys_user' },
-   ]
-   ```
-
-`name` is required unless `field` is provided (in which case it defaults
-to the field name and is used as the request-body key).
-
 <Callout type="info">
 **Source:** `packages/spec/src/ui/action.zod.ts`
 </Callout>

content/docs/references/ui/app.mdx

@@ -5,21 +5,6 @@ description: App protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
-Base Navigation Item Schema
-Shared properties for all navigation types.
-
-**NAMING CONVENTION:**
-Navigation item IDs are used in URLs and configuration and must be lowercase snake_case.
-
-@example Good IDs
-- 'menu_accounts'
-- 'page_dashboard'
-- 'nav_settings'
-
-@example Bad IDs (will be rejected)
-- 'MenuAccounts' (PascalCase)
-- 'Page Dashboard' (spaces)
-
 <Callout type="info">
 **Source:** `packages/spec/src/ui/app.zod.ts`
 </Callout>

content/docs/references/ui/component.mdx

@@ -5,8 +5,6 @@ description: Component protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
-Empty Properties Schema
-
 <Callout type="info">
 **Source:** `packages/spec/src/ui/component.zod.ts`
 </Callout>