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

package/docs/guides/routing.md

@@ -0,0 +1,202 @@
+# Static Router authoring
+
+Use `Router` when an application has several method/path entry points or needs compile-time middleware. It is a static authoring marker from `@pulse-compute/runtime`, not a JavaScript runtime dispatcher. The shared async/static restrictions are defined in [Managed handler TypeScript and JavaScript](../reference/handler-authoring.md); target claims live in the [compatibility matrix](../reference/compatibility-matrix.md).
+
+<!-- pulse-doc-source: examples/09-router-lowering/src/index.ts -->
+```ts
+import { Router } from '@pulse-compute/runtime'
+
+interface User {
+  id: number
+  name: string
+}
+
+const users = new Router()
+const api = new Router()
+const app = new Router()
+
+app.use(async (ctx, next) => {
+  if (ctx.req.header('x-pulse-deny') === '1') {
+    return ctx.json(
+      { error: 'denied by middleware' },
+      { status: 401 },
+    )
+  }
+  return next()
+})
+
+api.use(async (ctx, next) => {
+  if (ctx.req.header('x-api-state') === 'closed') {
+    return ctx.text('api closed', { status: 503 })
+  }
+  return next()
+})
+
+users.get('/:id', async (ctx) => {
+  const id = ctx.param('id')
+  const user = await ctx
+    .fetch('https://users.example.test/users/' + id)
+    .json<User>()
+  return ctx.json({ route: 'user', id, user })
+})
+
+api.get('/health', async (ctx, next) => {
+  if (ctx.req.header('x-health-handler') === 'fallback') {
+    return next()
+  }
+  return ctx.json({ ok: true, handler: 'primary' })
+})
+api.get('/health', async (ctx) => ctx.json({ ok: true, handler: 'fallback' }))
+api.head('/health', async (ctx) => ctx.text('', {
+  status: 204,
+  headers: [['x-pulse-route', 'health']],
+}))
+api.post('/users', async (ctx) => ctx.json(
+  { route: 'create', method: ctx.req.method },
+  { status: 201 },
+))
+api.get('/files/*', async (ctx) => ctx.text(ctx.req.path))
+api.get('/failure', async (ctx, next) => next('documented-failure'))
+
+api.mount('/users', users)
+app.mount('/api', api)
+
+app.error(async (error, ctx, next) => {
+  if (error === 'documented-failure') {
+    return ctx.json({ error: 'handled' }, { status: 418 })
+  }
+  return next(error)
+})
+
+export default app
+```
+<!-- /pulse-doc-source -->
+
+## Supported v2 surface
+
+- `new Router()` with a default-exported root router;
+- `use(handler)` and `use(path, handler)` middleware;
+- `get`, `head`, `post`, `put`, `patch`, and `delete` registrations;
+- exact paths, named `:parameters`, and a trailing `*` wildcard;
+- static acyclic `mount` composition;
+- named or inline async-shaped route handlers using `(ctx)` or `(ctx, next)`;
+- async-shaped middleware using `(ctx, next)`;
+- async-shaped error middleware using `(error, ctx, next)`;
+- `ctx.param('name')` for a parameter declared by the matched route;
+- first-match order, explicit route fallthrough, and compiler-owned 404/500 exhaustion.
+
+Every Router handler uses the normal canonical context. Fetches, schemas, config, secrets, KV, opaque responses, and trusted package effects lower into the same native execution plan as single-handler authoring.
+
+`Pulse` inherits the same route registration methods. Each registration matches
+its exact HTTP method; a method mismatch advances the route cursor and normal
+exhaustion remains `404`. There is no automatic `OPTIONS` or `405` response.
+Ingress route methods do not widen the separate outbound `ctx.fetch` contract.
+
+The `catalog-router-parity` conformance task exercises the original Catalog
+consumer probe and all 14 of its PUT/PATCH/DELETE operations with their existing
+methods and paths. Its shared cases check mounted parameters, request text,
+middleware state, exact method misses, registration order, terminal fallthrough,
+404 exhaustion and handled errors on Node/Fastly JavaScript and Native. Native
+lanes execute compiled Wasm; Fastly evidence uses local provider emulation and
+the target ABI mock host, not a deployed service. The fixtures establish routing
+acceptance only; they do not implement Catalog persistence or authorization.
+
+```sh
+node wasm/scripts/run-wasm-tests.cjs --task catalog-router-parity --no-report
+```
+
+## `next()` is a terminal transfer
+
+`next()` is not an onion-style callback. It is a compiler-visible control transfer:
+
+```ts
+app.use(async (ctx, next) => {
+  if (!authorized(ctx)) return ctx.text('unauthorized', { status: 401 })
+  return next()
+})
+```
+
+After `return next()`, the current handler is finished permanently. The Router cursor advances to the next applicable middleware or route. The handler never resumes and `next()` has no downstream response value.
+
+These forms are rejected:
+
+```ts
+next()
+return ctx.text('too late')
+```
+
+```ts
+const response = next()
+return response
+```
+
+Use `return next(error)` to enter the error lane:
+
+```ts
+app.get('/account', async (ctx, next) => {
+  if (!ctx.req.header('x-account')) return next('missing-account')
+  return ctx.text('ok')
+})
+
+app.error(async (error, ctx, next) => {
+  if (error === 'missing-account') return ctx.text('account required', { status: 400 })
+  return next(error)
+})
+```
+
+If the normal lane is exhausted, Pulse returns `404 Not Found`. If the error lane is exhausted, Pulse returns `500 Internal Server Error`.
+
+## Middleware scope and effects
+
+A path-scoped `use('/api', handler)` applies only to that subtree. Middleware declared on a mounted child Router is naturally limited to the mounted subtree.
+
+Middleware may request normal canonical effects before transferring control:
+
+```ts
+app.use(async (ctx, next) => {
+  const access = await ctx.fetch('https://auth.example.test/check').json<{ allowed: boolean }>()
+  if (!access.allowed) return ctx.text('denied', { status: 403 })
+  return next()
+})
+```
+
+Pulse owns suspension and resumption for the effect. `pulse inspect` attributes the effect and continuation to the middleware entry and then resumes the same flat Router execution graph.
+
+
+Use `ctx.parallel({ ... })` inside any managed route or middleware when named
+operations must begin together on both JavaScript and Native targets. Its fixed
+object-literal property order owns effect identity and result reconstruction, and
+the group settles completely before Router execution continues. Separate awaits
+retain ordinary sequential JavaScript behavior; Native may additionally group
+adjacent eligible effects as an optimization.
+
+
+## Deliberately outside v2
+
+Canonical Router v2 does not support onion-style post-`next()` work, assigning or awaiting `next()`, user-authored `throw` as Router transfer, post-response hooks, realtime lifecycle registrations, channels, timeout scopes, `ctx.resolve`, or `ctx.resolved`.
+
+Observability and explicit post-response work should use dedicated future contracts such as trace or defer effects rather than hidden middleware unwinding.
+
+## Inspect the lowering
+
+```bash
+pulse inspect examples/09-router-lowering --json
+```
+
+Look at:
+
+```text
+compiler.authoring.kind
+compiler.routing.entries
+compiler.routing.semantics
+compiler.effects[*].routerEntryStableId
+compiler.continuations[*].routerEntryStableId
+compiler.native.planHash
+```
+
+The same project can then be compiled or built normally:
+
+```bash
+pulse compile examples/09-router-lowering
+pulse build examples/09-router-lowering
+```

package/docs/guides/troubleshooting.md

@@ -0,0 +1,47 @@
+# Troubleshooting
+
+Start with the command that owns the workflow:
+
+```bash
+pulse doctor --json
+```
+
+Then use:
+
+```bash
+pulse inspect --json
+```
+
+The diagnostic `code` is the stable diagnostic code and identifier. `category`, `remediation`, and `docs` are included in CLI JSON, failed doctor checks, configured expected test errors, and local development error responses.
+
+See [Managed handler TypeScript and
+JavaScript](../reference/handler-authoring.md) for source-form boundaries and
+the [compatibility matrix](../reference/compatibility-matrix.md) for
+target-selection boundaries, then use the [diagnostics
+reference](../reference/diagnostics.md) for exit codes and common failures.
+
+## Compilation failures
+
+Read nested diagnostics under `error.diagnostics`. Fix the first concrete source/schema diagnostic rather than the top-level `PULSE_PROJECT_COMPILE_FAILED` wrapper. A Native eligibility failure never causes an automatic JavaScript retry; select a JavaScript profile deliberately only when that is the intended target.
+
+## Provider failures
+
+Use `pulse inspect --json` to compare compiler requirements with provider bindings. Fastly Native builds realize compact direct-host-ABI Wasm, while Fastly JavaScript builds produce a distinct source/deployment closure. External Fastly reality execution still requires the Fastly CLI and remains a separate environment-dependent gate. See [Fastly deployment candidates](./deploying-fastly.md).
+
+## Runtime failures
+
+Use a configured `pulse test` case to reproduce schema errors, fetch failures, and timeout behavior without relying on a live origin.
+
+## Event eligibility and harness failures
+
+Use `pulse inspect --json` to compare event registrations and emission
+callsites with `events.targetSupport`. Node JavaScript and Native expose the
+bounded reference adapter; Fastly event projects fail before output with
+`PULSE_FASTLY_EVENT_INGRESS_UNSUPPORTED` or
+`PULSE_FASTLY_EVENT_EMIT_UNSUPPORTED`. Pulse will not translate the event plane
+through HTTP or GRIP and will not switch targets.
+
+For `PULSE_TEST_EVENT_INVALID`, check the explicit `kind: 'event'`
+discriminant, use exactly one `schema` field, include payload only for a
+non-null schema, and keep `expect.emitted` as an ordered array. See [Static
+events and outbound emission](./events.md).

package/docs/maintainers/README.md

@@ -0,0 +1,60 @@
+<!-- pulse-doc-meta:start
+owner: maintainer-council
+status: active
+last-reviewed: 2026-07-25
+review-by: 2027-01-25
+pulse-doc-meta:end -->
+
+# Maintainer documentation
+
+This index is the entry point for repository governance, release operations,
+publication, deployment, and evidence procedures. These are maintainer
+artifacts, not application-author reference material.
+
+## Governance and support
+
+- [Maintainer charter](./maintainer-charter.md) — division of responsibility between Codex and the human architecture/release authority.
+- [Scope policy](./scope-policy.md) — change classes, protected boundaries, and the pull-request declaration.
+- [Codex maintainer operation](./codex-maintainer.md) — how native review and the manual policy review workflow are used safely.
+- [Repository setup](./repository-setup.md) — GitHub team, ruleset, protected environments, action allowlist, labels, Codex, npm, Object Storage, and Fastly configuration that cannot be committed as files.
+- [Support and triage](./support-and-triage.md) — issue intake, response posture, escalation, and quiet-launch operating rules.
+- [Generated maintenance policy](./maintenance-policy.md) — exact classes, boundaries, checks, action pins, environments, and forms.
+
+## Release and publication
+
+- [Release manifest and package policy](./release-manifest.md) — synchronized version, package set, support tiers, and target inventory.
+- [Testing Pulse](./testing.md) — focused tasks, profiles, dependency restoration, and evidence expectations.
+- [Release packages and clean-consumer acceptance](./release-acceptance.md) — package construction, packed-consumer checks, and seal evidence.
+- [npm publishing](./npm-publishing.md) — sealed tarballs, trusted publishing, dependency-safe retries, and registry verification.
+
+## Documentation operations
+
+- [Documentation system and release workflow](./documentation-system.md) — canonical sources, synchronization, ownership, and release snapshots.
+- [Public site and documentation presentation](./public-site.md) — editorial manifest, navigation, rendering, accessibility, and site validation.
+- [Documentation versions](./documentation-versioning.md) — exact snapshots, the moving alias, search, and installed copies.
+- [Documentation deployment](./documentation-deployment.md) — immutable Object Storage releases, root/latest promotion, and Fastly VCL delivery.
+
+## Protected implementation boundaries
+
+- [Public plugin API readiness](./plugin-readiness.md) — the explicit boundary around first-party lowerers and provider bootstrap.
+- [Contributor extension guides](../contributing/) — first-party package lowerers, providers, and Pulse-aware package authoring.
+
+## Authority model
+
+Pulse uses a resident-maintainer control plane to keep the public Beta
+supportable without transferring product authority to automation. The control
+plane combines machine-readable scope policy, deterministic path
+classification, repository-local Codex instructions, GitHub ownership, and
+human approval.
+
+The system is deliberately asymmetric:
+
+```text
+repository invariants and deterministic checks
+                    ↓
+       Codex analysis and patch preparation
+                    ↓
+        human architecture and release authority
+```
+
+Codex is a resident maintainer, not a repository principal. It may inspect, classify, reproduce, review, document, and prepare bounded changes. It may not merge, publish, change repository settings, or approve a change to a protected boundary.

package/docs/maintainers/codex-maintainer.md

@@ -0,0 +1,71 @@
+<!-- pulse-doc-meta:start
+owner: maintainer-council
+status: active
+last-reviewed: 2026-07-16
+review-by: 2027-01-16
+pulse-doc-meta:end -->
+
+# Codex resident maintainer
+
+Pulse supports two complementary Codex paths. Both remain advisory, inherit repository-local constraints, and stay subordinate to deterministic checks and human approval.
+
+## Repository instructions
+
+Codex reads `AGENTS.md` from the repository root toward the file being inspected. The root file defines product invariants and authority. Nested files add compiler, CLI, provider, documentation, release, and GitHub-specific constraints.
+
+The machine-readable source remains `release/maintenance-policy.json`. It owns change classes, protected boundaries, path classification, reviewed GitHub Action pins, the protected environment name, and the authority model. `AGENTS.md` explains how to apply that policy; it does not replace the policy or release gates.
+
+## Native GitHub code review
+
+A repository owner may connect the repository to Codex and enable code review in Codex settings. Review can then be requested through the connected GitHub integration, or automatic review can be enabled for pull requests.
+
+Native review is useful for normal correctness findings. It does not approve a protected-boundary decision and does not replace the deterministic scope check, CODEOWNER approval, or repository validation.
+
+## Manual policy review workflow
+
+The **Codex maintainer review** Actions workflow is deliberately manual. It can run only when dispatched from the repository's default branch, and the review job is attached to the protected `codex-maintainer` environment. A trusted maintainer supplies a pull-request number and optional focus.
+
+The workflow:
+
+1. checks out GitHub's pull-request merge ref without persisting credentials;
+2. obtains and sanitizes pull-request metadata through GitHub's API;
+3. verifies that the merge-ref parents match the API-reported base and head commits;
+4. creates a nested Git checkout fixed at the trusted base commit, removes its remote, and exposes the proposed base, head, and merge objects only through local review refs;
+5. places untrusted pull-request metadata in `.pulse-maintainer-review/` inside that trusted checkout, then removes the outer proposed working tree from the Actions workspace;
+6. runs the base commit's deterministic classifier against a precomputed NUL-delimited changed-file list;
+7. invokes the reviewed, full-commit-pinned `openai/codex-action` with the trusted checkout as its working directory, the built-in `:read-only` permission profile, and privilege dropping;
+8. uses the base commit's prompt and generated JSON Schema; and
+9. uses a separate, narrowly privileged job to update one marked pull-request comment.
+
+The Codex job has read-only repository permissions. It cannot post, push, merge, approve, publish, or alter repository settings. The posting job does not receive the OpenAI secret, run Codex, or check out pull-request code. It receives only the schema-constrained review result and pull-request number.
+
+## Trust boundary and prompt injection
+
+The working tree visible to Codex is the trusted base. Proposed `AGENTS.md`, policy, prompt, schema, source, fixture, workflow, generated artifact, commit message, and pull-request text remain review material. They can be inspected through the local head ref, but they do not become governing instructions for the same review.
+
+The workflow prompt requires Codex to:
+
+- read the trusted root and nearest nested `AGENTS.md` files;
+- compare the proposed diff with the deterministic scope report;
+- treat all proposed content as untrusted evidence;
+- avoid checking out or executing the proposed head;
+- focus on concrete containment, authority, correctness, release, and scope failures;
+- avoid network access and file modification;
+- produce only schema-valid structured output; and
+- state uncertainty rather than invent findings.
+
+This separation is important because Codex automatically discovers repository instructions. Running from a nested trusted-base checkout prevents a pull request from supplying the instructions that govern its own privileged review.
+
+## Secret and environment protection
+
+Store `OPENAI_API_KEY` as an environment secret on `codex-maintainer`, not as a general repository secret. Restrict that environment to the default branch and, when appropriate for the repository plan, require a human reviewer before the job receives the secret.
+
+Every external GitHub Action used by the repository is pinned to a reviewed full commit SHA. The version comment beside the SHA is documentation only; it is not the executable reference.
+
+## Asking Codex to prepare a patch
+
+Patch preparation should happen through an explicit maintainer task or normal Codex cloud task, not inside the read-only review workflow. The task should include the issue or reproduction, intended change class, and any approved protected boundaries. Codex must still run the repository checks and leave merge and release decisions to a human.
+
+## Failure behavior
+
+Codex availability is not a required status check. If the API, action, protected environment, or connected review service is unavailable, deterministic classification and repository validation continue to protect the branch. This keeps the repository operable without making an external model service part of release correctness.

package/docs/maintainers/documentation-deployment.md

@@ -0,0 +1,147 @@
+<!-- pulse-doc-meta:start
+owner: maintainer-council
+status: active
+last-reviewed: 2026-07-25
+review-by: 2027-01-25
+pulse-doc-meta:end -->
+
+# Documentation deployment
+
+Pulse documentation is generated static output. It is not deployed as a Pulse Compute application. The production path stores exact-version and moving-alias objects in Fastly Object Storage, then serves them through a small VCL delivery layer.
+
+```text
+source documentation + release catalogs
+→ generated site
+→ sealed object manifest
+→ immutable exact-version upload
+→ matching npm release verification
+→ root/latest promotion
+→ public verification through Fastly
+```
+
+The machine-readable deployment contract is `release/documentation-deployment.json`. The production workflow is `.github/workflows/documentation-deploy.yml`. Reviewed VCL templates and the operating guide live under `infra/fastly/documentation/`.
+
+## Validation and production are separate
+
+The **Documentation** workflow runs for pull requests and `main`. It validates generated documentation, builds the exact-version site, seals a preview object manifest, and uploads a short-lived Actions artifact. It has no storage secret and no deployment job.
+
+The **Documentation deployment** workflow is dispatched **from the exact release tag**, and its `release_tag` input must name the same tag. A branch-dispatched run fails before candidate construction. The candidate job builds and seals the site without credentials. Its `deploy` job is attached to the protected `documentation-production` environment, reuses the same tagged tooling and source identity, and receives credentials only after a human release/infrastructure authority approves the environment.
+
+GitHub Pages deployment is no longer part of the repository workflow. The release catalog's current public origin must be changed to the final Fastly-served hostname before production activation; the deployment verifier rejects an environment-provided public origin that differs from `release/pulse-release-manifest.json`.
+
+## Object classes
+
+The `1.0.0-beta.2` layout is:
+
+```text
+<bucket>/pulse/
+  index.html                         mutable
+  404.html                           mutable
+  latest/**                          mutable
+  versions.json                      mutable
+  site-manifest.json                 mutable
+  public-site-manifest.json          mutable
+  v1.0.0-beta.2/**                         immutable
+  deployments/v1.0.0-beta.2.json           immutable receipt
+```
+
+The exact-version tree is the archival release. Root and `latest` are convenience surfaces promoted only after exact-version verification and matching npm package verification.
+
+The deployment workflow and script never delete objects. Historical versions and unrelated bucket content are not candidates for synchronization. For an immutable key:
+
+```text
+missing
+  → upload
+
+present with matching bytes, content type, and cache policy
+  → accept as idempotent
+
+present with different bytes or metadata
+  → fail before promotion
+```
+
+Mutable objects may be replaced during a deliberate promotion. Their cache lifetime is short; exact-version objects are published with one-year immutable caching.
+
+## Sealed deployment candidate
+
+Build and inspect locally:
+
+```bash
+npm run docs:site
+npm run docs:deployment:prepare
+npm run docs:deployment:verify
+```
+
+`.pulse-documentation-deployment/documentation-deployment-manifest.json` records every object key, local source, byte length, SHA-256, content type, cache class, mutability, source commit, public documentation route, and independent storage prefix. Its deterministic deployment receipt records the complete generated-site digest and the exact-version object inventory and tree digest for `deployments/v1.0.0-beta.2.json`. Candidate verification rejects any root or site file outside that sealed inventory.
+
+A local adapter exercised by `npm run publication:check` proves:
+
+- first immutable upload;
+- idempotent retry;
+- rejection of an altered immutable object;
+- npm-gated mutable promotion; and
+- preservation of unrelated objects without any delete operation.
+
+## Object Storage credentials
+
+Use separate bucket-limited credentials:
+
+| Principal | Required scope | Repository location |
+|---|---|---|
+| GitHub deployment workflow | read/write | `documentation-production` environment secrets |
+| Fastly private origin | read-only | protected Fastly service configuration |
+
+The GitHub environment provides:
+
+```text
+Secrets
+  FASTLY_OBJECT_STORAGE_ACCESS_KEY_ID
+  FASTLY_OBJECT_STORAGE_SECRET_ACCESS_KEY
+
+Variables
+  FASTLY_OBJECT_STORAGE_BUCKET
+  FASTLY_OBJECT_STORAGE_REGION
+  FASTLY_OBJECT_STORAGE_ENDPOINT
+  PULSE_DOCUMENTATION_ORIGIN
+  PULSE_DOCUMENTATION_BASE_PATH
+```
+
+The deployer supplies only these bucket credentials to AWS CLI v2. It clears ambient profiles, session tokens, web-identity roles, container-credential endpoints, and generic AWS endpoint overrides, and points AWS config and shared-credential lookup at the platform null device. This prevents unrelated runner credentials from influencing Object Storage requests.
+
+The workflow requires AWS CLI v2, maps the two secrets to its standard credential variables and sends S3-compatible requests to the selected Fastly regional endpoint. Fastly Object Storage rejects the AWS CLI's optional request-checksum behavior, so both the protected deployment job and the deployment adapter set `AWS_REQUEST_CHECKSUM_CALCULATION=when_required`. Storage reads likewise use `AWS_RESPONSE_CHECKSUM_VALIDATION=when_required`. These are fixed compatibility settings, not repository environment variables or credentials.
+
+The read-only VCL origin key must never be reused as the deployment key, and the read/write deployment key must never be embedded in VCL.
+
+## VCL delivery boundary
+
+The VCL service owns delivery concerns, not content generation:
+
+- host or path routing;
+- GET and HEAD admission;
+- directory `index.html` normalization and canonical slash redirects;
+- private Object Storage SigV4 origin signing;
+- bucket and object-prefix rewriting;
+- immutable versus moving-alias cache policy;
+- branded 404 behavior;
+- content and security headers; and
+- removal of storage-specific response headers.
+
+The checked-in snippets contain protected credential placeholders and are not activated automatically. A human infrastructure/release owner must create and configure the Fastly service, test a non-production service version, and activate it.
+
+## Promotion and public verification
+
+The production workflow performs these steps in order:
+
+1. verify the downloaded documentation candidate and its exact release-tag identity;
+2. upload or verify every immutable exact-version object and immutable release receipt;
+3. query npm for all 18 matching package versions and configured dist-tags;
+4. upload mutable manifests, error pages, and alias payloads using that npm verification report, then write `latest/index.html` and root `index.html` last as the release-owned publication points;
+5. verify the mutable objects directly in Object Storage;
+6. request homepage, latest, getting started, the moving site manifest, exact version, CSS, and a missing path through the configured Fastly public origin; and
+7. retain object, registry, and HTTP evidence as workflow artifacts.
+
+Public verification checks that the moving routes and `site-manifest.json` expose the new release version. It retries within the release-owned window so the one-minute alias cache can converge without a privileged CDN purge token.
+
+No bucket-wide synchronization or delete operation is used. Mutable promotion is resumable and idempotent, but it is not presented as a cross-object atomic transaction. Writing the two publication points last minimizes partially visible promotions; a failed run is rerun against the same sealed candidate.
+
+Codex may diagnose a failed deployment and prepare a patch. It may not approve `documentation-production`, supply credentials, alter the public origin, activate VCL, or promote documentation independently of human release authority.

package/docs/maintainers/documentation-system.md

@@ -0,0 +1,58 @@
+<!-- pulse-doc-meta:start
+owner: maintainer-council
+status: active
+last-reviewed: 2026-07-16
+review-by: 2027-01-16
+pulse-doc-meta:end -->
+
+# Documentation system and release workflow
+
+Pulse documentation and the public product site have three synchronized delivery forms:
+
+1. repository Markdown for review and source-bound examples;
+2. installed Markdown, references, schemas, examples, and completions in the CLI package;
+3. a generated public homepage plus a searchable, versioned static-site artifact under `.pulse-docs-site/`, with committed immutable exact-version archives for prior releases.
+
+## Canonical owners
+
+- `release/pulse-release-manifest.json` owns the release version, hosted documentation route, runtime targets, package set, support tiers, and supported entry points.
+- `release/documentation-site.json` owns editable homepage copy, named document destinations, public navigation grouping and order, and homepage composition.
+- `release/maintenance-policy.json` owns change classes, protected boundaries, validation selection, CODEOWNERS/label generation, and the resident-maintainer authority model.
+- `wasm/packages/cli/src/command-spec.js` owns public commands and options; it generates help, the CLI reference, and shell completions.
+- `wasm/packages/cli/src/project-config-schema.js` owns core config fields, defaults, and runtime constraints.
+- `packages/provider-fastly/src/config-schema.json` owns Fastly provider defaults.
+- the diagnostic and environment catalogs own their generated references.
+- `release/documentation-versions.json` owns the version selector and latest alias.
+- `scripts/documentation-site/` owns shared presentation tokens, the vendored Starry Night dark theme, components, browser behavior, the favicon, and the deterministic decorative Pulse field.
+
+Do not hand-edit generated copies under `wasm/packages/cli/docs`, `wasm/packages/cli/completions`, or `.pulse-docs-site`. Edit the editorial manifest, canonical catalogs, Markdown, or shared site assets instead. The site directory is an ignored build artifact, not a source tree. Prior exact releases are the exception: `release/documentation-site-archives/v<version>/` contains a byte-preserved site subtree created while that release is still current.
+
+## Update loop
+
+```bash
+npm run maintainer:sync
+pnpm docs:sync
+pnpm docs:check
+pnpm docs:site:check
+node scripts/documentation-release.cjs
+```
+
+`maintainer:sync` refreshes generated governance outputs. `docs:sync` refreshes references, package metadata, shell completions, installed documentation, ownership metadata, and source-bound examples. `docs:check` fails when any checked-in generated surface is stale. `docs:site:check` builds and validates the hosted artifact in a temporary directory; `docs:site` writes `.pulse-docs-site/` for inspection or deployment.
+
+For local presentation work, `pnpm docs:preview` performs the synchronization and build, mounts the artifact at `/`, and serves it at `http://127.0.0.1:4173/`. The preview adapter does not rewrite production HTTPS origins or release manifests. `pnpm docs:preview -- --smoke` exercises the local HTTP surface and exits, while `--watch` rebuilds when documentation or presentation sources change. Preview roots are symlink-checked and carry a generator ownership marker; populated unowned directories are rejected, and `--no-build` can only reuse a complete owned artifact.
+
+## Publishing the site
+
+The Pages workflow builds `.pulse-docs-site/` for pull requests and main-branch changes, but those events are validation-only. The base route is a generated product homepage; `latest` remains a documentation redirect tree. Publication requires an explicit manual dispatch or a `v<version>` tag that exactly matches `release/pulse-release-manifest.json`. The canonical documentation release lives under `/v<version>/`; `/latest/` contains redirects to the version marked latest. The homepage uses the current release’s exact-version CSS and JavaScript so its shipped presentation is archived with that release. Every exact subtree owns its HTML, assets, search index, release manifest, and version-site manifest.
+
+Before changing the release version, run `pnpm docs:site -- --snapshot` while the old release is still current and commit the resulting `release/documentation-site-archives/v<version>/` directory. Add the new version entry only after the archive exists. The builder imports and validates every non-current archive; missing or mismatched history is a release error rather than a Pages deployment that drops old URLs.
+
+## Ownership and review dates
+
+Contributor and handwritten maintainer pages carry a generated
+`pulse-doc-meta` block. The
+release gate requires a known owner, status, last-reviewed date, and non-expired
+review-by date. Update the ownership catalog and review the page content
+together; do not merely extend a date without verifying the document.
+
+The detailed editing contract, navigation rules, hero motion requirements, and presentation-specific gates are documented in [Public site and documentation presentation](./public-site.md).

package/docs/maintainers/documentation-versioning.md

@@ -0,0 +1,65 @@
+<!-- pulse-doc-meta:start
+owner: maintainer-council
+status: active
+last-reviewed: 2026-07-16
+review-by: 2027-01-16
+pulse-doc-meta:end -->
+
+# Documentation versions, search, and installed copies
+
+Pulse publishes a generated product homepage at the configured base path, exact documentation snapshots, and a moving `latest` alias.
+
+## Public product homepage
+
+The base route for this repository is:
+
+```text
+https://pulsecompute.io/
+```
+
+It is a generated product homepage, not an alias or redirect. Its copy, named actions, section order, and navigation come from `release/documentation-site.json`; release facts and runtime targets come from `release/pulse-release-manifest.json`; CLI workflow summaries come from the public command specification. The homepage links into `latest` for browsing, while diagnostics and package metadata continue to use exact-version URLs.
+
+The homepage and exact current documentation load the same assets under `/v<version>/assets/`. This keeps the visual system consistent and ensures a release snapshot retains the CSS, JavaScript, favicon, no-JavaScript fallback, and hero-graph implementation it shipped with.
+
+## Exact release URLs
+
+The canonical URL for this release begins with:
+
+```text
+https://pulsecompute.io/v1.0.0-beta.2/
+```
+
+Diagnostics, package status blocks, and package metadata use exact-version URLs. This prevents a diagnostic emitted by an older CLI from silently opening instructions for a newer contract.
+
+Each exact release subtree carries its HTML, release-local search data, public machine-readable references, design tokens, CSS, JavaScript, favicon, editorial site manifest, and version manifest under the same `v<version>/` segment. The release remains renderable and searchable without mutable assets. A small root `versions.json` index may refresh the cross-version selector as newer releases are added; it cannot change the archived page content, styling, or search index.
+
+## The `latest` alias
+
+`/latest/` redirects to the release marked current in `release/documentation-versions.json`. It is convenient for browsing, but tools and emitted diagnostics should use the exact release segment.
+
+## Search
+
+Every published release has its own generated `search-index.json`. Navigation grouping, breadcrumbs, previous/next order, and the on-page outline are generated from the same editorial navigation model. Search runs locally in the browser and never mixes pages from different release versions. Page titles, headings, text, owner, and review status are indexed.
+
+## Installed and offline documentation
+
+`@pulse-compute/cli` ships the public Markdown hierarchy, examples, schemas, command specification, release manifest, version manifest, and shell-completion files. Installed copies remain usable when the hosted site is unavailable. Hosted links are preferred when a stable anchor or cross-package destination is required.
+
+## Adding a documentation version
+
+Before changing the release manifest, snapshot the still-current exact site:
+
+```bash
+pnpm docs:site -- --snapshot
+```
+
+This writes `release/documentation-site-archives/v<current-version>/`. Commit that directory unchanged. Then:
+
+1. add the new release to `release/documentation-versions.json` and leave the old entry in place;
+2. update `release/pulse-release-manifest.json` with the new version and exact segment;
+3. run the generated-documentation and site gates;
+4. publish the combined site artifact.
+
+The builder copies every non-current version from `release/documentation-site-archives/` and validates its version manifest, release manifest, public-site manifest, search index, pages, and versioned assets before deployment. The moving root homepage is regenerated for the current release; the archived exact subtree preserves the old release’s presentation and routes. A version bump therefore fails rather than silently dropping or rebuilding an older exact release. Existing archive directories are never overwritten unless the snapshot command is given `--force` deliberately.
+
+The release gate also rejects a current release that is missing from the versions manifest or whose version segment does not match the release manifest.