fix(spec-docs): a module header's headings start at the page's section level (#12551)

The 38 generated pages under `content/docs/references/**` rendered two
`<h1>`. The second one was never in the MDX: it came from a JSDoc file
header in `packages/spec/src/**`, which `build-docs.ts` copied verbatim
into the page. A `.zod.ts` header is written as if it were a standalone
document, so its author opens a section with `# ` — embedded under a page
whose `<h1>` is already its frontmatter `title`, that compiles to a second
one. 43 headings across the 38 pages.

`renderFileDescription` now renumbers the fragment so its SHALLOWEST
heading sits at `ctx.sectionLevel`, which `build-docs.ts` supplies as the
level its own `## TypeScript Usage` and `## <SchemaName>` sections use.

Renumbering rather than rewriting every `# ` to `## `, for three reasons
the pins carry: 26 described modules already start at level 2 and a
blanket shift would regenerate 26 pages that were never wrong; a block
mixing `#` and `##` would collide two source levels into one; and — the
load-bearing one — the shift is scoped to `prose` lines, so a
`# Install pnpm globally` inside a fence is left alone. That last is why
this lives beside `classifyLines` instead of running as a regex over the
emitted string: a fence-blind pass corrupts working snippets to satisfy a
rule about HTML those lines never produce.

With the tree clean, `scripts/check-docs-single-h1.mjs` goes
`DEAD-EXCLUSION` on its own carve-out, so that entry is deleted here. The
gate's judged population grows from 356 to 394 pages.


Claude-Session: https://claude.ai/code/session_01E5LFCYBJ3q2s6yW6oMLxwy

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

Author: huangyiirene

content/docs/references/api/dispatcher.mdx

@@ -5,7 +5,7 @@ description: Dispatcher protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
-# HttpDispatcher Protocol
+## HttpDispatcher Protocol
 
 Defines how the ObjectStack HttpDispatcher routes incoming API requests
 to the correct kernel service based on URL prefix matching.

content/docs/references/api/package-api.mdx

@@ -5,7 +5,7 @@ description: Package Api protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
-# Package API Protocol
+## Package API Protocol
 
 REST API endpoint schemas for package lifecycle management.
 

content/docs/references/api/versioning.mdx

@@ -5,7 +5,7 @@ description: Versioning protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
-# API Versioning Protocol
+## API Versioning Protocol
 
 Defines how API versions are negotiated between client and server.
 Supports multiple versioning strategies and deprecation lifecycle management.

content/docs/references/cloud/app-store.mdx

@@ -5,22 +5,22 @@ description: App Store protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
-# App Store Protocol (Customer Experience)
+## App Store Protocol (Customer Experience)
 
 Defines schemas for the end-customer experience when browsing, evaluating,
 installing, and managing marketplace apps from within ObjectOS.
 
-## Architecture Alignment
+### Architecture Alignment
 - **Salesforce AppExchange (Customer)**: Browse apps, read reviews, 1-click install
 - **Shopify App Store (Merchant)**: App evaluation, trial, install, manage subscriptions
 - **Apple App Store (User)**: Ratings, reviews, featured collections, personalized recs
 
-## Customer Journey
+### Customer Journey
 ```
 Discover → Evaluate → Install → Configure → Use → Rate/Review → Manage
 ```
 
-## Key Concepts
+### Key Concepts
 - **Reviews & Ratings**: User-submitted ratings and reviews with moderation
 - **Collections & Recommendations**: Personalized discovery and curated picks
 - **Subscription Management**: Manage licenses, billing, and renewals

content/docs/references/cloud/developer-portal.mdx

@@ -5,7 +5,7 @@ description: Developer Portal protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
-# Developer Portal Protocol
+## Developer Portal Protocol
 
 Defines schemas for the developer-facing side of the marketplace ecosystem.
 Covers the complete developer journey:
@@ -14,12 +14,12 @@ Covers the complete developer journey:
 Register → Create App → Develop → Validate → Build → Submit → Monitor → Iterate
 ```
 
-## Architecture Alignment
+### Architecture Alignment
 - **Salesforce Partner Portal**: ISV registration, AppExchange publishing, Trialforce
 - **Shopify Partner Dashboard**: App management, analytics, billing
 - **VS Code Marketplace Management**: Extension publishing, statistics, tokens
 
-## Identity Integration (better-auth)
+### Identity Integration (better-auth)
 Authentication, organization management, and API keys are handled by the
 Identity module (`@objectstack/spec` Identity namespace), which follows the
 better-auth specification. This module only defines marketplace-specific
@@ -35,7 +35,7 @@ extensions on top of the shared identity layer:
   There is no `Identity.ApiKeySchema` — #8715 retired it (it documented
   better-auth's apiKey plugin, which this platform does not load)
 
-## Key Concepts
+### Key Concepts
 - **Publisher Profile**: Links an Identity Organization to a marketplace publisher
 - **App Listing Management**: CRUD for marketplace listings (draft → published)
 - **Version Channels**: alpha / beta / rc / stable release channels

content/docs/references/cloud/environment-artifact.mdx

@@ -5,7 +5,7 @@ description: Environment Artifact protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
-# Environment Artifact Envelope — re-export (#4740, #4535 C10)
+## Environment Artifact Envelope — re-export (#4740, #4535 C10)
 
 The envelope has exactly ONE declaration:
 `../system/environment-artifact.zod` (maintainer route A′ on #4740 —

content/docs/references/cloud/environment-package.mdx

@@ -5,7 +5,7 @@ description: Environment Package protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
-# Environment Package Installation Protocol
+## Environment Package Installation Protocol
 
 Models `sys_package_installation` — the pairing between an Environment and
 a specific, immutable `sys_package_version` snapshot.

content/docs/references/cloud/environment.mdx

@@ -5,7 +5,7 @@ description: Environment protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
-# Environment Protocol (runtime container)
+## Environment Protocol (runtime container)
 
 An **Environment** is the runtime container of an organization's data.
 It owns a physically isolated database, a canonical hostname, a plan/quota

content/docs/references/cloud/marketplace-admin.mdx

@@ -5,17 +5,17 @@ description: Marketplace Admin protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
-# Marketplace Administration Protocol
+## Marketplace Administration Protocol
 
 Defines schemas for the platform (Cloud) side of marketplace operations.
 Covers the administrative workflows for managing and governing the marketplace.
 
-## Architecture Alignment
+### Architecture Alignment
 - **Salesforce AppExchange Admin**: Security review, ISV monitoring, partner management
 - **Apple App Store Connect Review**: Human review process, guidelines, rejection reasons
 - **Google Play Console**: Policy enforcement, quality gates, content moderation
 
-## Key Concepts
+### Key Concepts
 - **Review Process**: Structured workflow for submission review (automated + manual)
 - **Curation**: Featured apps, curated collections, editorial picks
 - **Governance**: Policy enforcement, takedown, compliance

content/docs/references/cloud/marketplace.mdx

@@ -5,7 +5,7 @@ description: Marketplace protocol schemas
 
 {/* ⚠️  AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}
 
-# Marketplace Protocol
+## Marketplace Protocol
 
 Defines the core schemas for the plugin marketplace ecosystem, covering:
 - **Developer Side**: Package publishing, submission, and version releases
@@ -14,13 +14,13 @@ Defines the core schemas for the plugin marketplace ecosystem, covering:
 This protocol defines the contract between plugin developers, the marketplace
 platform, and customers who install plugins.
 
-## Architecture Alignment
+### Architecture Alignment
 - **Salesforce AppExchange**: Security review, managed packages, listing profiles
 - **VS Code Marketplace**: Extension publishing, ratings, verified publishers
 - **npm Registry**: Package publishing, versioning, scoped packages
 - **Shopify App Store**: App review process, billing integration, merchant installs
 
-## Developer Publishing Flow
+### Developer Publishing Flow
 ```
 1. Develop   → Build the project locally using ObjectStack CLI
 2. Validate  → Run `os validate` (schema + security checks)
@@ -30,7 +30,7 @@ platform, and customers who install plugins.
 6. Publish   → Approved listing goes live on marketplace
 ```
 
-## Platform Management Flow
+### Platform Management Flow
 ```
 1. Receive   → Accept submissions from verified publishers
 2. Scan      → Automated security scan and compatibility check