docs(spec): publish the solution-blueprint module header instead of its export list

.changeset/solution-blueprint-module-header.md

@@ -0,0 +1,23 @@
+---
+"@objectstack/spec": patch
+---
+
+`ai/solution-blueprint.zod.ts` publishes its own sentence again, instead of a list of the symbols it happens to export.
+
+The file always carried a real module header — ADR-0033 §4 plan-first authoring, and how the `apply_blueprint` tool expands each entry into a proper metadata body. But only a blank line separated that header from `const SNAKE_CASE`, and TSDoc's own attachment rule says a block belongs to the declaration it immediately precedes. The header-zone selector reads that rule back, so the header counted as the regex constant's documentation and was disqualified as the module's. Both generators then fell through to their export-list fallback, and the row published into the `objectstack-ai` skill index read:
+
+```
+- `…/ai/solution-blueprint.zod.ts` — Exports: BlueprintConditionSchema, BlueprintSummaryOperationsSchema, …
+```
+
+A true statement about the file that says nothing about its subject — on the one row whose job is to send an agent to this source for exact field shapes.
+
+`SNAKE_CASE` now carries the one-line doc it always deserved. A comment is not a declaration, so the preamble ends there and the header becomes the module's own block. The published row and the public reference page both open on it:
+
+```
+- `…/ai/solution-blueprint.zod.ts` — Solution Blueprint Schema (ADR-0033 §4 — plan-first authoring)
+```
+
+The selector is untouched. Under its own rule it was deciding correctly, and a census of every source under `packages/spec/src` found this file to be the only one of its kind: 19 shipped `*.zod.ts` sources have a header-zone block sitting against a declaration, and in the other 18 that block genuinely documents the symbol it sits against (`Transport Protocol Enum` against `TransportProtocol`, `Shared history for this file` against `AGENT_HISTORY`). Only here did a module header sit against a constant it says nothing about.
+
+Neither generator can see this class — each compares its artifact against itself, and each reproduced the selector faithfully, so a generator-only check passes on the defect. A pin now asserts the content of the published row directly.

content/docs/references/ai/solution-blueprint.mdx

@@ -5,6 +5,20 @@ description: Solution Blueprint protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
+Solution Blueprint Schema (ADR-0033 §4 — plan-first authoring)
+
+The structured-output target an AI agent emits for a *high-level* goal
+("build me a project-management system") instead of transcribing a field
+list. It is a **simplified proposal shape** — deliberately lighter than the
+full `ObjectSchema` / `ViewSchema` / `DashboardSchema`.
+The `apply_blueprint` tool expands each entry into a proper metadata body
+and stages it as a draft (so the per-type Zod schema still validates the
+real artifact at write time).
+
+The blueprint is **never persisted on its own**: the agent presents it for
+conversational confirmation/edit (cheap), and only on human approval does it
+batch-draft. This is the safety valve for low-specificity input.
+
 <Callout type="info">
 **Source:** `packages/spec/src/ai/solution-blueprint.zod.ts`
 </Callout>

packages/spec/src/ai/solution-blueprint.zod.ts

@@ -21,6 +21,7 @@ import { FilterConditionSchema } from '../data/filter.zod';
  * batch-draft. This is the safety valve for low-specificity input.
  */
 
+/** Machine-name pattern every object, field and option name in a blueprint must match. */
 const SNAKE_CASE = /^[a-z_][a-z0-9_]*$/;
 
 /**

skills/objectstack-ai/references/_index.md

@@ -13,7 +13,7 @@ from `node_modules` — there is no local copy in the skill bundle.
 - `node_modules/@objectstack/spec/src/ai/knowledge-source.zod.ts` — Knowledge Source — declarative metadata describing what to index and
 - `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/solution-blueprint.zod.ts` — Exports: BlueprintConditionSchema, BlueprintSummaryOperationsSchema, BlueprintFieldSchema, BlueprintObjectSchema, BlueprintViewSchema
+- `node_modules/@objectstack/spec/src/ai/solution-blueprint.zod.ts` — Solution Blueprint Schema (ADR-0033 §4 — plan-first authoring)
 - `node_modules/@objectstack/spec/src/ai/tool.zod.ts` — Exports: ToolSchema
 
 ## Transitive dependencies