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

* docs(spec): let the solution-blueprint module header speak for itself

`findModuleDocBlock()` rejects a header-zone doc block that is immediately
followed by a declaration — TSDoc's own attachment rule, read back: such a
block documents that symbol. In `ai/solution-blueprint.zod.ts` a single blank
line separated the module header from `const SNAKE_CASE`, so the header was
read as that regex constant's documentation and disqualified. The generators
then fell through to the export-list fallback, and the published skill-index
row stated a true fact about the file while saying nothing about its subject:

  - `.../ai/solution-blueprint.zod.ts` — Exports: BlueprintConditionSchema, ...

Give `SNAKE_CASE` the one-line doc it always deserved. That is a comment, not
a declaration, so the preamble now ends there and the header — plan-first
authoring, the `apply_blueprint` expansion — becomes the module's own block.

The selector is untouched: it was deciding correctly under its own rule.

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

* test(spec): pin the blueprint pointer row to its subject, and regenerate

The published row and the reference page both regain the file's own sentence:

  - `.../ai/solution-blueprint.zod.ts` — Solution Blueprint Schema (ADR-0033 §4 — plan-first authoring)

Neither generator can see this class on its own — `check:skill-refs` and
`check:docs` compare the artifact against the generator, and the generator
reproduces the selector faithfully, so a generator-only check passes on the
defect. The pin asserts the fact the artifact must state instead.

Two legs that fail differently: the SOURCE leg reds the moment the separator
between the header and `SNAKE_CASE` goes away; the CORPUS leg stays green
through that and reds once an index is regenerated from a file whose header no
longer qualifies. Both directions measured.

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

* chore(spec): declare the new pin's escaping reads, and add the changeset

The pin reads `skills/*/references/_index.md` — outside its own package — so it
belongs in `vitest.repo-tests.json` and runs under the `repo` project, whose
hash moves with what it actually reads. Left undeclared it would run under
`@objectstack/spec#test`, invisible to both the affected-subset filter and the
turbo cache: green on every PR while red on main, which is the one failure this
pin exists to refuse.

`packages/spec` ships `src/**/*.zod.ts`, and `npm pack --dry-run` confirms the
edited source is in the tarball (206 such entries ship; scripts/, skills/ and
content/ ship none), so the change publishes and takes a patch changeset.

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

* chore(spec): move the pointer-row pin to its own branch

The pin and its `vitest.repo-tests.json` declaration are a change to
`packages/spec/scripts/`, i.e. to the generator side of this repo. Carried here
they defeat the generated-artifact exception that would otherwise lift the
`skills/**` path on this PR: the recompute that certifies the regenerated index
would be running a tree that also modifies the generator it is trusting, so it
cannot certify itself.

What is left here is a pure `gen:skill-refs` / `gen:docs` regeneration beside
the one-line source fix. The pin lands separately and is not weakened.

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

---------

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

Author: claude[bot]

.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