@pulse-compute/cli 0.0.0 → 1.0.0-beta.2

package/docs/maintainers/maintenance-policy.md

@@ -0,0 +1,124 @@
+# Maintenance policy reference
+
+<!-- Generated by scripts/maintenance-policy.cjs. Edit release/maintenance-policy.json instead. -->
+
+Pulse uses a machine-readable maintenance policy so repository automation and Codex receive the same scope boundaries. The policy is advisory about product direction and mandatory about process: Codex may analyze, review, and prepare bounded patches, while a human retains architecture, merge, repository-setting, and release authority.
+
+- **Policy schema:** `pulse.maintenance-policy.v2`
+- **Policy version:** `7`
+- **Release:** `1.0.0-beta.2`
+- **Reviewed:** `2026-09-13`
+- **Resident maintainer:** Codex
+- **Merge authority:** human-only
+- **Release authority:** human-only
+- **Protected Codex environment:** `codex-maintainer`
+- **Codex secret:** `OPENAI_API_KEY`
+
+## Protected environments
+
+| Environment | Approval authority | Allowed refs | Secrets | Variables |
+|---|---|---|---|---|
+| `codex-maintainer` | human-maintainer | `default-branch` | `OPENAI_API_KEY` | None |
+| `npm-publish` | human-release | `release-tags` | None | None |
+| `documentation-production` | human-release-infrastructure | `release-tags` | `FASTLY_OBJECT_STORAGE_ACCESS_KEY_ID`, `FASTLY_OBJECT_STORAGE_SECRET_ACCESS_KEY` | `FASTLY_OBJECT_STORAGE_BUCKET`, `FASTLY_OBJECT_STORAGE_REGION`, `FASTLY_OBJECT_STORAGE_ENDPOINT`, `PULSE_DOCUMENTATION_ORIGIN`, `PULSE_DOCUMENTATION_BASE_PATH` |
+
+Production environments are release-control boundaries. Codex may inspect failures and prepare patches, but it cannot approve an environment, receive production credentials outside the declared job, publish packages, promote documentation, or activate infrastructure.
+
+## Change classes
+
+| ID | Meaning | Codex posture | Separate human decision | Boundary |
+|---|---|---|---:|---|
+| `defect` | Defect | May prepare implementation | No | Supported behavior does not match the documented or tested contract. |
+| `hardening` | Hardening | May prepare implementation | No | Reliability, security, diagnostics, performance, or test strength improves without widening supported behavior. |
+| `documentation` | Documentation | May prepare implementation | No | Documentation, examples, generated references, or presentation change without runtime behavior expansion. |
+| `evidence` | Evidence | May prepare implementation | No | A reproduction, benchmark, fixture, experiment, or usage report records information without creating a product promise. |
+| `scope-expansion` | Scope expansion | Analysis only until approved | Yes | New authoring syntax, capability, provider, effect, public entry point, compatibility promise, or product behavior is proposed. |
+| `architecture` | Architecture | Analysis only until approved | Yes | A protected boundary, trust assumption, ownership rule, execution contract, or governance mechanism changes. |
+| `release` | Release | Analysis only until approved | Yes | Versioning, publication, signing, provenance, package composition, or release-channel behavior changes. |
+
+A normal human code review is still required for every merge. “Separate human decision” means the change also alters scope, architecture, or release authority and must be acknowledged before implementation is treated as approved direction.
+
+## Protected boundaries
+
+| ID | Boundary | Decision kind | Current contract update | Meaning |
+|---|---|---|---:|---|
+| `public-authoring-api` | Public authoring API | architecture | Required | The provider-neutral TypeScript handler and exported application types. |
+| `effect-capability-model` | Effect and capability model | architecture | Required | The explicit operations a guest can request and the authority a host can realize. |
+| `continuation-runtime` | Continuation runtime | architecture | Required | Suspension, resumption, timeout, identity, and lifecycle semantics between effects. |
+| `lowerer-trust` | Lowerer trust boundary | architecture | Required | Discovery and execution of package-owned lowerers and the first-party trust restriction. |
+| `provider-registry` | Provider registry | architecture | Required | Provider namespace resolution, exact scoped-package bootstrap, provider contracts, host bindings, and target realization. |
+| `configuration-contract` | Configuration contract | architecture | When affected | Public project configuration fields, defaults, precedence, and runtime constraints. |
+| `runtime-target-fluidity` | Runtime target fluidity | architecture | Required | The stable runtime authoring contract and the explicit boundary between native, JavaScript, and future sidecar execution targets. |
+| `package-publication` | Package publication contract | release | When affected | Published package set, exports, support tiers, exact versions, and packed payloads. |
+| `maintenance-control-plane` | Maintenance control plane | architecture | Required | Agent authority, scope policy, repository workflows, ownership, and review gates. |
+| `documentation-deployment` | Documentation deployment contract | release | When affected | Immutable version objects, mutable promotion surfaces, Object Storage delivery, public routing, and production activation. |
+| `release-authority` | Release authority | release | When affected | Version, channel, publication, deployment, signing, and provenance decisions. |
+
+Path classification is intentionally conservative. Touching a protected path does not prove that a contract changed; it ensures the pull request names the boundary and receives deliberate review.
+
+## Validation catalog
+
+| Check ID | Availability | Command |
+|---|---|---|
+| `maintenance-policy` | Portable | `node scripts/validate-maintainer-control-plane.cjs` |
+| `publication-control-plane` | Portable | `node scripts/validate-publication-workflows.cjs` |
+| `release-preflight` | Portable | `node scripts/release-preflight.cjs --check` |
+| `documentation` | Portable | `npm run docs:check` |
+| `unit` | Portable | `node wasm/scripts/run-wasm-tests.cjs --profile unit --no-report` |
+| `native` | Portable | `node wasm/scripts/run-wasm-tests.cjs --profile native --no-report` |
+| `javascript` | Portable | `node wasm/scripts/run-wasm-tests.cjs --profile javascript --no-report` |
+| `conformance` | Portable | `node wasm/scripts/run-wasm-tests.cjs --profile conformance --no-report` |
+| `cli` | Portable | `node wasm/scripts/run-wasm-tests.cjs --profile cli --no-report` |
+| `providers` | Dependency-bound | `node wasm/scripts/run-wasm-tests.cjs --profile providers --no-report` |
+| `build` | Dependency-bound | `pnpm build` |
+| `release` | Dependency-bound | `npm run release:seal` |
+
+Portable checks use the normal lockfile-pinned workspace installation and do not require the release-only dependency bundle or external provider credentials. Dependency-bound checks remain required before publication when their affected paths are touched.
+
+## Reviewed GitHub Actions
+
+Every external action used by a checked-in workflow is pinned to a full reviewed commit SHA. The human-readable version is retained as a comment, but tags do not determine execution.
+
+| Action | Reviewed version | Commit SHA |
+|---|---|---|
+| `actions/checkout` | `v7.0.0` | `9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0` |
+| `actions/setup-node` | `v6.4.0` | `48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e` |
+| `actions/upload-artifact` | `v7.0.1` | `043fb46d1a93c77aae656e7c1c64a875d1fc6a0a` |
+| `actions/download-artifact` | `v8.0.1` | `3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c` |
+| `actions/github-script` | `v9.0.0` | `3a2844b7e9c422d3c10d287c895573f7108da1b3` |
+| `openai/codex-action` | `v1.11` | `52fe01ec70a42f454c9d2ebd47598f9fd6893d56` |
+
+## Pull-request declaration
+
+Every pull request includes a machine-readable Markdown comment with:
+
+```text
+<!-- pulse-maintainer-declaration:start -->
+Change class: defect
+Scope: inside-developer-preview
+Protected boundaries: none
+Human decision: not-required
+<!-- pulse-maintainer-declaration:end -->
+```
+
+The deterministic scope gate compares that declaration with changed paths. It fails only for a missing or contradictory declaration; a correctly declared architecture, scope, or release decision remains visible and relies on CODEOWNER/branch-rule approval rather than pretending an agent can approve it.
+
+## Issue intake
+
+| Form | Initial class | Labels |
+|---|---|---|
+| `bug.yml` | `defect` | `type:defect`, `status:needs-reproduction` |
+| `documentation.yml` | `documentation` | `type:documentation`, `area:documentation` |
+| `scope-proposal.yml` | `scope-expansion` | `type:scope-proposal`, `decision:human-required` |
+| `support.yml` | `evidence` | `type:support` |
+
+Labels are synchronized by the manual **Maintainer labels** workflow. Issue labels classify incoming evidence; they do not authorize implementation or widen the Beta contract.
+
+## Codex operation
+
+The repository supports two complementary paths:
+
+1. Native Codex GitHub review can be enabled in Codex settings and follows the nearest `AGENTS.md` file.
+2. The manual **Codex maintainer review** workflow runs from the protected `codex-maintainer` environment, uses the policy-specific prompt in a read-only permission profile, validates its output against the generated maintainer-review schema, and posts a structured review to the selected pull request.
+
+Neither path can merge, publish, change repository settings, or approve a protected-boundary decision. The environment secret is released only after the repository owner's configured protection rules pass.

package/docs/maintainers/npm-publishing.md

@@ -0,0 +1,154 @@
+<!-- pulse-doc-meta:start
+owner: maintainer-council
+status: active
+last-reviewed: 2026-07-25
+review-by: 2027-01-25
+pulse-doc-meta:end -->
+
+# npm publishing
+
+Pulse publishes the exact tarballs produced by `pnpm release:pack`. Publication does not run recursively from workspace directories and does not repack a package after acceptance.
+
+The release path is:
+
+```text
+exact v<version> tag
+→ dependency-complete build and acceptance
+→ .pulse-release tarballs
+→ sealed .pulse-publication bundle
+→ protected human approval
+→ npm trusted publishing
+→ registry integrity and configured dist-tag verification
+→ clean published-CLI smoke test
+```
+
+The machine-readable publication contract is the `publication` object in `release/pulse-release-manifest.json`. The production workflow is `.github/workflows/npm-publish.yml`.
+
+## Prepare release identity
+
+Use the manifest-owned preparation policy instead of repository-wide version replacement:
+
+```bash
+pnpm release:prepare -- 1.0.0-beta.2 --channel beta --replace-unpublished
+```
+
+`--replace-unpublished` replaces the current candidate without inventing release history. After a version has actually shipped, use `--archive-current`; that mode requires the committed immutable documentation snapshot. The command updates only catalogued JSON, package, guest-metadata, and current-documentation owners, runs named generators, rejects newly changed paths outside its allowlist, and writes an ignored stale-version-token report for review.
+
+Release preparation never creates a Git tag and never contacts npm. A human release authority creates the exact `v<version>` tag from the reviewed, sealed commit as a separate action.
+
+## Authority and trigger
+
+The workflow is manually dispatched **from the exact release tag**, and the `release_tag` input must name that same tag. Candidate construction, publication tooling, GitHub's native source identity, and npm provenance therefore all refer to one commit. A branch-dispatched run fails before artifacts are built. The candidate job has no publication authority. The `publish` job is attached to the protected `npm-publish` environment and is the only job granted `id-token: write`.
+
+For example:
+
+```bash
+gh workflow run npm-publish.yml \
+  --ref v1.0.0-beta.2 \
+  -f release_tag=v1.0.0-beta.2 \
+  -f operation=audit
+```
+
+Use `operation=publish` only after the audit and external package settings are complete.
+
+A human release authority must approve that environment. Codex may inspect failures and prepare bounded patches, but it may not dispatch the release, approve the environment, publish a package, change a dist-tag, or rotate registry credentials.
+
+## Trusted publishing
+
+Pulse uses npm trusted publishing through GitHub Actions OIDC. No `NPM_TOKEN` or `NODE_AUTH_TOKEN` is provided. Published packages support `^22.14.0 || ^24.0.0`; local development supports pnpm `>=10 <11`. Release packing, CI, and the portable dependency bundle select the exact pnpm version in the release manifest (currently 10.0.0). Local release seals accept Node `^24.0.0` and record the exact patch used. The protected publication workflow remains reproducibly pinned to Node 24.18.0 and npm 11.15.0, and `scripts/release-publication.cjs` rejects a different Node patch, a different npm version, or known long-lived npm credential variables in that job.
+
+Every manifest-owned npm package setting must authorize exactly:
+
+```text
+repository: pulse-compute/pulse
+workflow:   npm-publish.yml
+environment: npm-publish
+```
+
+The workflow publishes public packages directly under the dist-tag in the
+release manifest. OIDC is deliberately not combined with a post-publication
+`npm dist-tag` mutation. The protected script verifies the native GitHub tag ref
+and SHA against the sealed candidate before the first publish.
+
+## One-time package bootstrap
+
+An npm trusted publisher can be configured only after the package name exists under the intended owner. Before enabling production publication, run:
+
+```bash
+npm run release:audit-npm
+```
+
+The command derives every package name from the release manifest and writes a timestamped, manifest-digest-bound report to `.pulse-release-preflight/npm-catalog-audit.json`. That report is ignored source evidence: it never rewrites the canonical preflight policy and it performs no registry mutation. The audit is ready only when every name exists, `bootstrap` points to `0.0.0`, and `latest` is either absent or still points to the same inert `0.0.0` placeholder. A different `latest` target remains blocking and any required dist-tag remediation is an explicit human registry action.
+
+Any missing package name requires a one-time human, 2FA-protected bootstrap publication through `scripts/npm_bootstrap.sh <package-name>`. After all names exist:
+
+1. configure the trusted publisher on every package;
+2. select the exact release tag as the manual workflow ref;
+3. confirm OIDC publication succeeds;
+4. remove any temporary bootstrap credential; and
+5. prohibit ordinary publish tokens for routine releases.
+
+The production workflow fails rather than silently performing first publication with a broader credential.
+
+## Sealed candidate
+
+After `pnpm release:pack`, prepare the candidate:
+
+```bash
+npm run release:candidate
+npm run release:verify-bundle
+```
+
+`.pulse-publication/pulse-publication-manifest.json` records:
+
+- release version, tag, channel, registry, workflow, and protected environment;
+- source commit and ref;
+- the exact publication order;
+- every tarball path, byte length, SHA-256, and npm SHA-512 integrity;
+- Pulse package dependencies used to derive the topological order; and
+- checksums for the source catalog and packed-release manifest.
+
+The bundle includes the exact tarballs. GitHub artifact transfer does not create a second npm package payload.
+
+## Dependency-safe, resumable publication
+
+Publication orders internal `dependencies` and `optionalDependencies` before dependants. Peer dependencies are validated by release packing but do not introduce an ordering edge. Stable role/name ordering makes retries deterministic.
+
+For each package:
+
+```text
+version absent
+  → publish the sealed tarball with --access public --tag <release dist-tag>
+
+version present with identical SHA-512 integrity
+  → record already-published and continue
+
+version present with different integrity
+  → stop with a critical immutable-version conflict
+```
+
+This is resumable after a partially completed synchronized-package release without pretending npm publication is transactional. A same-version integrity mismatch cannot be repaired by overwriting the registry artifact; the human release authority must investigate and choose a new version if necessary.
+
+## Verification
+
+The protected publish job verifies each package immediately. A separate unprivileged job then confirms:
+
+- every manifest-owned `name@version` record exists;
+- registry `dist.integrity` equals the sealed tarball integrity;
+- the configured dist-tag points to the release version; and
+- the published canonical CLI installs in a clean prefix and completes version, init, install, doctor, test, and Node build smoke checks.
+
+The registry report uses schema `pulse.npm-publication-verification.v1`. The documentation deployment accepts that schema as evidence that matching packages are publicly available before it promotes root and `latest`.
+
+## Local commands
+
+These commands do not publish unless the explicit `publish` command is used from the protected GitHub environment:
+
+```bash
+pnpm release:pack
+npm run release:candidate
+npm run release:verify-bundle
+npm run publication:check
+```
+
+Actual publication remains a human-approved workflow action, not a normal local maintenance command. The CLI does not expose a non-GitHub publication bypass; production publication requires the trusted GitHub/OIDC environment. The release validator exercises planning and failure behavior with in-process registry fixtures and never invokes `npm publish`.

package/docs/maintainers/plugin-readiness.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": "pulse.plugin-readiness.v1",
+  "releaseVersion": "1.0.0-beta.2",
+  "publicPluginApi": false,
+  "decision": "deferred",
+  "requirements": {
+    "trustModel": false,
+    "packageDiscovery": false,
+    "versionNegotiation": false,
+    "securityPolicy": false,
+    "compatibilityContract": false,
+    "isolatedPackageLoading": false
+  },
+  "currentExtensionBoundary": {
+    "lowerers": "trusted first-party release packages only",
+    "providers": "explicit package selection through pulse.provider-toolchain.v1; bare host IDs use the @pulse-compute/provider-<id> convention, scoped names are exact, and none is internal; no scanning or self-registration"
+  },
+  "designRule": "The explicit provider toolchain contract does not imply general plugin discovery, isolated loading, or lowerer extensibility. Do not publish a general third-party plugin API design until every readiness requirement is implemented and release-gated."
+}

package/docs/maintainers/plugin-readiness.md

@@ -0,0 +1,31 @@
+# Public plugin API readiness
+
+<!-- Generated by wasm/scripts/sync-reference-docs.cjs. Edit the source catalog, not this file. -->
+
+> **Decision:** Deferred. No public third-party plugin API is available in this release.
+
+Pulse 1.0.0-beta.2 keeps general plugin discovery and package lowering inside the synchronized trusted release. Provider bootstrap is explicit and exact. The current boundaries are:
+
+- **Lowerers:** trusted first-party release packages only.
+- **Providers:** explicit package selection through pulse.provider-toolchain.v1; bare host IDs use the @pulse-compute/provider-<id> convention, scoped names are exact, and none is internal; no scanning or self-registration.
+
+## Readiness requirements
+
+| Requirement | Status |
+|---|---|
+| `trustModel` | **Not implemented** |
+| `packageDiscovery` | **Not implemented** |
+| `versionNegotiation` | **Not implemented** |
+| `securityPolicy` | **Not implemented** |
+| `compatibilityContract` | **Not implemented** |
+| `isolatedPackageLoading` | **Not implemented** |
+
+The explicit provider toolchain contract does not imply general plugin discovery, isolated loading, or lowerer extensibility. Do not publish a general third-party plugin API design until every readiness requirement is implemented and release-gated.
+
+The machine-readable readiness record and release validation enforce this
+boundary. Contributor guides explain how to add a [first-party
+lowerer](../contributing/adding-first-party-lowerer.md) or [provider
+toolchain](../contributing/adding-core-provider.md); neither process uses
+package scanning or self-registration.
+
+Machine-readable status is published as [`plugin-readiness.json`](./plugin-readiness.json).

package/docs/maintainers/public-site.md

@@ -0,0 +1,158 @@
+<!-- pulse-doc-meta:start
+owner: maintainer-council
+status: active
+last-reviewed: 2026-07-25
+review-by: 2027-01-25
+pulse-doc-meta:end -->
+
+# Public site and documentation presentation
+
+Pulse has one generated public-site system for the product homepage and versioned documentation. The homepage is an editorial product surface; the documentation remains layered technical content. They share release facts, routes, navigation metadata, design tokens, components, accessibility behavior, and validation rather than maintaining separate hand-written sites.
+
+## Canonical inputs
+
+The generator separates facts from presentation:
+
+| Source | Owns |
+|---|---|
+| `release/pulse-release-manifest.json` | Release version, channel, documentation base path, repository metadata, runtime targets, package policy, and exact-version routes. |
+| `release/documentation-versions.json` | Available versions and the moving `latest` alias. |
+| `release/documentation-site.json` | Product copy, named document destinations, header/footer links, navigation sections and ordering, homepage section order, and checked fixture selection. |
+| Repository Markdown | Tutorials, concepts, package guides, references, architecture, and contributor content. |
+| CLI and configuration catalogs | Public command workflow, diagnostics, schemas, environment variables, and other generated reference material. |
+| `scripts/documentation-site/` | Shared design tokens, dark syntax theme, layout and component styles, browser behavior, favicon, and the decorative Pulse field animation. |
+
+Do not copy release versions, provider names, CLI command descriptions, package roles, or canonical routes into templates. Add or change the owning catalog and let the site builder consume it.
+
+## Editorial manifest
+
+`release/documentation-site.json` uses the `pulse.public-site.v1` schema. Its
+document map assigns stable IDs such as `getting-started` and `preview-scope` to
+Markdown sources. Homepage and header actions refer to those IDs, never
+handwritten URLs. The generator resolves each action to the current exact
+release or the `latest` alias as appropriate. `sourceAliases` maps
+repository-only landing files to their canonical hosted document; `routeAliases`
+preserves intentional redirects after a public route is renamed without
+creating a second content owner.
+
+Navigation sections classify every public page exactly once. Explicit `sources`
+take precedence over directory `prefixes`; `navigation.overrides` controls
+concise labels, order, and whether a page is hidden from the flat sidebar
+without adding front matter to generated or installed Markdown. A hidden page
+remains generated, versioned, and link-checked, and the builder requires it to
+remain linked from visible documentation. `hiddenInSearch` is reserved for a
+hidden compatibility page that should remain reachable without competing in
+task search. Section `searchPriority` gives Start, Guide, Concept, Package, and
+Reference material a deterministic ranking boost over contributor material. A
+section may instead set `hiddenInNavigation` and `hiddenInSearch` to classify a
+gated audience namespace without rendering that category in the sidebar or
+general search. The Reference overview is the discovery gate for the hidden
+Maintainers section. A new public Markdown page that
+matches no section, matches more than one section, or has a duplicate route
+fails the site build. Alias sources are excluded from hosted navigation, and
+stale overrides or aliases fail the release gate.
+
+The installed CLI exposes the same machine-readable value as `@pulse-compute/cli/documentation-site.json`, and the hosted build emits it as `public-site-manifest.json`. The editorial manifest owns copy and composition, not release identity or provider contracts. The homepage may choose which parts of the product story deserve emphasis, while version, channel, package, and provider facts remain release-owned.
+
+## Shared presentation layer
+
+The homepage and documentation shell load the same exact-version assets:
+
+- `tokens.css` — colors, typography, spacing, radii, shadows, content widths, breakpoints, and motion values;
+- `syntax-dark.css` — the vendored Starry Night dark syntax theme;
+- `site.css` — reusable header, buttons, terminal, content, navigation, search, table-of-contents, and responsive layouts;
+- `site.js` — search, version selection, mobile navigation, code copying, and table-of-contents state;
+- `network-field.js` — the release-local decorative canvas animation used by the homepage;
+- `favicon.svg` — the Pulse mark.
+
+Fenced code is highlighted during site generation by `scripts/highlight-code-blocks.mjs` with `@wooorm/starry-night`. The generated HTML contains token spans and uses release-local CSS; no browser highlighter, CDN stylesheet, or runtime grammar download is required. Unknown fence languages remain safely escaped and readable.
+
+The source assets live under `scripts/documentation-site/`. The builder copies them into `v<version>/assets/`; both the root homepage and exact documentation use those release-local copies. Historical exact releases therefore retain the presentation they shipped with instead of inheriting future root CSS or JavaScript.
+
+Style refinements should usually start with tokens or a shared component. Avoid page-specific inline CSS and avoid duplicating a component between homepage and documentation templates.
+
+## Homepage generation
+
+The public base path, `/`, is a product homepage rather than a redirect. It is generated from:
+
+- product positioning, the Router example, and homepage sections in the editorial manifest;
+- candidate display information in the release manifest;
+- the quick-start commands;
+- a checked `pulse inspect` fixture;
+- named routes resolved through the document map.
+
+The current story leads with the application rather than the compiler: a
+minimal hero, a primary Router example, a secondary quick-start strip, a
+gradual path toward Native execution, practical containment principles, a
+collapsed compiler inspection proof, and the explicit Beta scope.
+Package inventories, target matrices, and full references remain in
+documentation.
+
+The hero Pulse field is deterministic and dependency-free. It restores the earlier restrained visual treatment: a dense, low-opacity network with sparse travelling pulses and no embedded compiler labels. It pauses while offscreen or while the document is hidden, offers a visible pause/resume control, caps device-pixel ratio, and honors `prefers-reduced-motion`. When reduced motion is requested, the decorative canvas and motion control are not started; the hero copy remains complete without them. The animation is decorative; all meaning remains in the surrounding copy.
+
+The Router example follows the hero as the primary product proof. The install commands then live in a separate full-width quick-start card so long package names remain readable without competing with the application model.
+
+## Documentation shell
+
+Each exact-version page receives generated:
+
+- product header, release selector, and release-local search;
+- breadcrumbs;
+- grouped and ordered left navigation;
+- mobile off-canvas navigation that does not precede article content;
+- an “On this page” list from level-two and level-three headings;
+- previous/next links from the same navigation order;
+- owner, status, review date, and canonical source metadata;
+- a shared footer and exact-version assets.
+
+The Markdown renderer folds an explicit anchor immediately before a heading into that heading ID. This preserves generated diagnostic and environment anchors while preventing duplicate HTML IDs.
+
+## Build and inspect
+
+```bash
+pnpm docs:sync
+pnpm docs:site
+pnpm docs:site:check
+node scripts/documentation-release.cjs
+```
+
+`pnpm docs:site` writes `.pulse-docs-site/`. `docs:site:check` builds into a temporary directory and validates the complete route graph.
+
+For normal local development, use the preview adapter instead of manually reproducing the production mount:
+
+```bash
+pnpm docs:preview
+```
+
+The command refreshes generated documentation, builds directly into `.pulse-docs-preview/`, serves it over HTTP, and prints `http://127.0.0.1:4173/`. Production canonical metadata remains HTTPS and byte-identical; localhost changes only the transport used to inspect the artifact. Useful variants include:
+
+```bash
+pnpm docs:preview -- --port 8080
+pnpm docs:preview -- --host 0.0.0.0
+pnpm docs:preview -- --open
+pnpm docs:preview -- --watch
+pnpm docs:preview -- --no-build
+pnpm docs:preview -- --smoke
+```
+
+`--smoke` uses an ephemeral port, verifies the root-mounted homepage, version root, search index, shared assets, the isolated compatibility fixture, output-marker isolation, and the branded 404, then exits. When `--preview-root` is supplied explicitly, the smoke artifact is retained for inspection; otherwise its temporary output is removed.
+
+Preview generation writes `.pulse-docs-preview-root.json` at the selected output root. A populated custom directory without that ownership marker is never replaced, symlinked roots are rejected, and `--no-build` serves only a marker-owned artifact with a complete site manifest. These checks keep the convenience command from becoming a general recursive-delete surface.
+
+## Release gates
+
+Public-site validation rejects:
+
+- stale or invalid public-site manifests;
+- missing named document sources or actions;
+- unclassified, multiply classified, or duplicate public routes;
+- missing shared assets or required no-JavaScript fallbacks;
+- handwritten homepage release facts that disagree with canonical catalogs;
+- missing homepage sections, the Router example, motion controls, quick-start commands, or inspect fixtures;
+- duplicate HTML IDs, broken base-path routes, or missing anchors;
+- a root homepage that regresses to a redirect;
+- documentation pages without search, version selection, mobile navigation, breadcrumbs, table of contents, or previous/next structure;
+- exact pages that depend on mutable root presentation assets;
+- archived versions that no longer satisfy their own version manifest.
+
+The generated site is a release artifact. Edit the manifests, Markdown, catalogs, and shared source assets; never hand-edit `.pulse-docs-site/` or a published exact-version subtree.