fix(spec): the @module marker line is machinery, not the opening line of a reference page (#14464)

* fix(spec): drop the `@module` marker line from generated reference pages

The `@module <path>` tag selects a module's doc block (#13334) but is
machinery for the selector, not prose. `renderFileDescription` emitted it
verbatim, so fourteen published reference pages opened on the literal text
`@module ui/sharing` instead of on their first sentence. `check:docs` could
not see it: it compares the artifact against the source, and the artifact
reproduced the marker faithfully.

Mirrors the existing `os:check` marker drop in the same function — a
prose-level filter applied before the render classification — rather than
inventing a second convention, and matches the filter
`build-skill-references.ts` has always had on the skill-index surface. The
marker stays in the source and `findModuleDocBlock` still reads it.

Scope is `@module` alone, not `^@\w+`: `@example <caption>` and
`@category <value>` carry prose a line-drop would take off the page.

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

* docs(spec): regenerate the fourteen reference pages the marker opened

`pnpm --filter @objectstack/spec gen:docs` after the renderer fix. Every page
loses exactly two lines — its `@module <path>` marker and the blank line under
it — and none gains any, so no page loses prose.

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

---------

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

Author: claude[bot]

.changeset/module-marker-not-page-prose.md

@@ -0,0 +1,14 @@
+---
+'@objectstack/spec': patch
+---
+
+Reference pages no longer open with the `@module` marker line. That tag is what
+tells the docs generator which doc block describes the module, but it is
+machinery for the selector, not prose — and the renderer emitted it verbatim, so
+fourteen published pages opened on the literal text `@module ui/sharing` instead
+of on their first sentence. `renderFileDescription` now drops the marker at prose
+level, exactly as it already drops the `check:skill-examples` opt-in marker, and
+as the skill-index extractor has always done. The marker stays in the source and
+still selects the block; only `@module` is dropped, because `@example` and
+`@category` carry prose a line-drop would take off the page. No schema behavior
+changes.

content/docs/references/automation/bpmn-interop.mdx

@@ -5,8 +5,6 @@ description: Bpmn Interop 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 automation/bpmn-interop
-
 BPMN XML Interoperability Protocol
 
 Defines the specification for importing and exporting BPMN 2.0 XML

content/docs/references/automation/builtin-node-config.mdx

@@ -5,8 +5,6 @@ description: Builtin Node Config 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 automation/builtin-node-config
-
 Config contracts for the remaining flat builtins — the CRUD quartet
 (`get_record` / `create_record` / `update_record` / `delete_record`),
 `screen`, and `map` (#4045). Sibling of `io-node-config.zod.ts`

content/docs/references/automation/control-flow.mdx

@@ -5,8 +5,6 @@ description: Control Flow 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 automation/control-flow
-
 Structured control-flow constructs (ADR-0031) — the **native + AI-authored**
 flow model: a `loop` **container**, a `parallel` **block**, and structured
 `try/catch/retry`. Unlike BPMN's gateway/boundary/token graph (kept in the

content/docs/references/automation/flow-function.mdx

@@ -5,8 +5,6 @@ description: Flow Function 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 automation/flow-function
-
 The contract for a **named handler function a `script` node invokes** —
 contributed by `defineStack({ functions })` and resolved by name at execute
 time (#1870).

content/docs/references/automation/io-node-config.mdx

@@ -5,8 +5,6 @@ description: Io Node Config 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 automation/io-node-config
-
 Config contracts for the flat IO builtins — `notify` and `http` (#4045).
 
 ## Provenance — written from the executors, not from the forms

content/docs/references/automation/node-executor.mdx

@@ -5,8 +5,6 @@ description: Node Executor 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 automation/node-executor
-
 Node Executor Plugin Protocol — Wait Node Pause/Resume
 
 Defines the specification for node executor plugins, with a focus on

content/docs/references/automation/schemaless-node-config.mdx

@@ -5,8 +5,6 @@ description: Schemaless Node Config 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 automation/schemaless-node-config
-
 Config contracts for the **descriptor-schemaless** builtins whose designer
 form lives ONLY in objectui's hand-written `FLOW_NODE_CONFIG` table —
 `script`, `subflow` and `decision` (#4278).

content/docs/references/automation/state-machine.mdx

@@ -5,8 +5,6 @@ description: State Machine 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 automation/state-machine
-
 XState-inspired State Machine Protocol — hierarchical states, guarded
 transitions, entry/exit actions. Used to declare strict business-logic
 constraints and lifecycle management, so an AI author cannot "hallucinate" a

content/docs/references/shared/mapping.mdx

@@ -5,8 +5,6 @@ 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