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

package/docs/maintainers/release-acceptance.md

@@ -0,0 +1,250 @@
+<!-- pulse-doc-meta:start
+owner: maintainer-council
+status: active
+last-reviewed: 2026-07-16
+review-by: 2027-01-16
+pulse-doc-meta:end -->
+
+# Release packages and clean-consumer acceptance
+
+The current Beta candidate contains eighteen publishable packages
+synchronized at version `1.0.0-beta.1`. The product-facing packages are:
+
+```text
+@pulse-compute/pulse
+@pulse-compute/runtime
+@pulse-compute/cli
+@pulse-compute/provider-fastly
+@pulse-compute/grip
+@pulse-compute/assets
+@pulse-compute/crypto
+@pulse-compute/jwt
+@pulse-compute/entities
+```
+
+The CLI and providers depend on additional `@pulse-compute/wasm-*`
+implementation packages. Those packages are installable transitive
+dependencies, not the handler authoring surface. The generated
+[package support policy](../packages/README.md) defines the tier, audience,
+direct-install guidance, and supported entry points for all 18 artifacts.
+
+## Event experimental candidate
+
+Before changing release identity or package composition, the event surface has
+its own evidence-only package and consumer seal:
+
+```bash
+node wasm/scripts/run-wasm-tests.cjs --task events-candidate-seal --no-report
+```
+
+That task packs `@pulse-compute/pulse`, `@pulse-compute/runtime`, and their
+public contract dependency, installs the exact tarballs without network access,
+type-checks both application and host-maintainer event consumers, checks legal
+and dependency closure, and compares a second pack byte-for-byte. It also emits
+the event candidate decision and a blocker ledger under `wasm/.test-results`.
+
+Passing this focused seal means the event-facing package closure is internally
+consistent. It does not authorize publication or claim Fastly/browser/ESP32
+event support.
+
+## Check documentation release integrity
+
+```bash
+pnpm docs:check
+node scripts/documentation-release.cjs
+```
+
+The documentation checks verify:
+
+- generated documentation/package files and source-bound Markdown blocks are synchronized;
+- canonical repository, installed-package, and exact-version hosted links and anchors resolve;
+- every package has one generated status block and required repository metadata derived from the release manifest;
+- each advertised supported package entry point exists in `exports` or `bin`;
+- every public diagnostic has one real anchor and an exact-version docs URL;
+- installed help, the public reference, the machine-readable command specification, and three shell completions agree on the public command and option set;
+- public project, schema, development, test, and Fastly configuration fields and runtime rules agree with the shared schema and runtime normalization;
+- the Fastly provider schema agrees with provider defaults and the compiled package payload;
+- recognized environment variables agree with their generated scope reference;
+- public plugin claims remain blocked until all six trust, discovery, compatibility, loading, and security prerequisites are implemented;
+- contributor and governance pages carry valid owner, status, review, and stale-date metadata;
+- the exact-version documentation site contains release banners, local search, and version navigation.
+
+Maintainer-only task and report controls remain available to repository truth suites but are absent from installed help and the public CLI reference.
+
+## Pack a release candidate
+
+From the source workspace:
+
+```bash
+pnpm release:pack
+```
+
+This builds the workspace and writes eighteen package tarballs plus `pulse-release-manifest.json` under `.pulse-release/`. It prepares release artifacts; it does not publish them to a registry.
+
+Packing fails when:
+
+- a package is private or versions diverge;
+- a packed dependency retains `workspace:`;
+- repository-only tests or internal documentation leak into a tarball;
+- required API/CLI reference files are absent;
+- a Markdown link or anchor is dead after extraction;
+- a link escapes its package root;
+- an exact-version Pulse documentation URL does not map to a real file and anchor in the packed release set.
+
+`@pulse-compute/runtime` ships its canonical API and preview-scope references.
+`@pulse-compute/cli` ships the public documentation hierarchy,
+API/CLI/config/diagnostic/package references, bounded compatibility material,
+and runnable example sources.
+
+## Clean-consumer acceptance
+
+```bash
+node wasm/scripts/run-wasm-tests.cjs --task clean-machine-acceptance --no-report
+```
+
+The release task creates an isolated npm home and cache, installs exact packed candidates rather than workspace links, and validates:
+
+```text
+install
+→ pulse init
+→ npm install
+→ pulse doctor
+→ pulse inspect
+→ pulse test
+→ pulse dev --once
+→ pulse build
+```
+
+It runs that workflow for new Native and JavaScript Node/Fastly projects,
+verifies a real Fastly Native `bin/main.wasm`, and installs/builds the canonical
+GRIP and Router examples from the packed package set. The two JavaScript
+projects prove packed `inspect`, passing `doctor`, `test`, one-request `dev`,
+provider-neutral `compile`, and deterministic `build`. Their executable source
+packages contain exact reachable dependencies, no Native planning artifacts,
+and `automaticFallback: false`. The Node target satisfies all 12 support gates;
+the Fastly target satisfies all six support gates, emits source/deployment
+manifests with provider reality and deployment still false, and does not install
+the downstream Fastly compiler into an ordinary Pulse consumer.
+
+## Offline deployment candidates
+
+```bash
+npm run release:candidates
+```
+
+This gate builds the representative Fastly Native and Fastly JavaScript targets
+twice from the same output location. Native output, including `bin/main.wasm`,
+must be byte-identical. Fastly JavaScript source, deployment metadata, and exact
+toolchain closure must be byte-identical; one closure is then compiled by the
+pinned `@fastly/js-compute` runtime compiler into `bin/main.wasm`.
+
+The downstream Wizer snapshot is recorded by exact SHA-256 but is not presented
+as byte-reproducible. The candidate report distinguishes that toolchain-owned
+property from Pulse-owned deterministic input and metadata. It also records zero
+provider-reality runs, zero deployments, and zero publications.
+
+The task owns the eighteen publishable Pulse packages, not the packages in the
+development installation. It installs every exact Pulse tarball into clean
+consumer projects and verifies the installed name, version, and real path. An
+ephemeral server bound to `127.0.0.1` is the fail-closed registry for the
+`@pulse-compute` scope, so an undeclared or missing Pulse candidate cannot fall
+through to a previously published package. Third-party dependencies resolve
+from the canonical npm registry according to the packed manifests; the release
+gate does not repack or assume ownership of `assemblyscript`, `long`, `esbuild`,
+or other external packages. Lockfile and dependency evidence remain separate
+workspace inputs.
+
+External Fastly Compute execution is also separate:
+
+```bash
+PULSE_FASTLY_BIN=/path/to/fastly \
+node wasm/scripts/run-wasm-tests.cjs --task provider-fastly-compute-reality --no-report
+```
+
+The task records the Fastly CLI version, invokes `fastly compute serve --file`, and lets the CLI own its local Compute engine. It then sends real HTTP requests through the generated native module. `PULSE_VICEROY_BIN` remains available only as an explicit lower-level reproduction override. The fixture covers schemas, configuration, secrets, KV persistence, named-backend fetch, opaque bytes, repeated headers, and GRIP hold/publish. It does not deploy or activate a Fastly service.
+
+The aggregate candidate seal is:
+
+```bash
+npm run release:seal
+```
+
+It restores dependencies, validates the repository and generated documentation, runs the complete release profile, and adds the external Fastly task when the Fastly CLI can start its managed local Compute lifecycle. Use `--require-fastly` to make that host proof mandatory.
+
+The seal also regenerates the production vulnerability and installed-platform
+license closure. It does not depend on mutable npm trusted-publisher settings,
+GitHub publication environments, public repository administration, or the
+production documentation origin. Those remain blocking at publication or
+documentation deployment, where the corresponding authority is actually used.
+
+With a clean passing seal, create the release evidence delivery:
+
+```bash
+npm run release:evidence -- \
+  --base <accepted-source-ref> \
+  --head HEAD \
+  --label <delivery-name> \
+  --out <new-output-directory>
+```
+
+The evidence authority checks that all reports belong to the exact head
+revision, aggregates sixteen passing shards, creates source and binary-patch
+artifacts, independently applies the patch to the accepted source archive, and
+compares path, mode, and bytes with the sealed head. The resulting bundle is
+offline evidence only; merge, tagging, deployment, activation, and publication
+remain human-authority operations.
+
+## Publication workflow
+
+After all dependency-bound acceptance passes, seal the exact tarballs:
+
+```bash
+npm run release:candidate
+npm run release:verify-bundle
+npm run publication:check
+```
+
+Production publication is performed only by the manually dispatched **npm
+publication** workflow at the exact release tag. Its protected `npm-publish` job
+uses npm trusted publishing through GitHub OIDC, publishes the tarballs from
+`.pulse-publication` in dependency-safe order, accepts an already-published
+version only when registry integrity matches, and verifies every configured
+dist-tag. A separate job installs the published CLI in a clean prefix and
+completes init, install, doctor, test, and build smoke checks.
+
+Before the first trusted publication, every package name must exist and authorize the exact repository, `npm-publish.yml` workflow, and `npm-publish` environment. Use the package-name audit and a one-time human 2FA bootstrap for any missing names. No long-lived npm token is part of the normal workflow.
+
+## Publication hold points
+
+Before publication, confirm the repository, final documentation host/base path, package policy, and issue-tracker values centralized in `release/pulse-release-manifest.json`. Pulse is licensed under Apache-2.0: the release gate requires the exact root `LICENSE`, SPDX metadata in the workspace and all eighteen publishable packages, and the same license text in every npm tarball. A dependency-license audit and its dispositions remain separate release evidence.
+
+A human release authority must approve `npm-publish`. Codex may diagnose or prepare a patch but cannot publish, approve the environment, bootstrap package names, or mutate dist-tags.
+
+## Versioned documentation artifact
+
+The release owns a versioned hosted-documentation gate:
+
+```bash
+pnpm docs:site:check
+```
+
+The check builds the exact `v1.0.0-beta.1` site and `latest` tree in a temporary directory, creates one search entry per public page, validates local hosted links, verifies release/version manifests, and requires the search, version, owner, and review UI on every page.
+
+The **Documentation** workflow repeats those checks for pull requests and `main`, seals a preview deployment manifest, and uploads artifacts without production credentials. It does not deploy to GitHub Pages.
+
+Production delivery uses the manually dispatched **Documentation deployment** workflow and Fastly Object Storage. The workflow:
+
+```text
+build and seal
+→ upload/verify v1.0.0-beta.1 and its receipt immutably
+→ verify all matching npm packages and configured dist-tags
+→ promote root and latest
+→ verify representative URLs through Fastly
+```
+
+The deployment never deletes bucket objects. A pre-existing immutable key with different SHA-256 fails before promotion. The `documentation-production` environment, Object Storage credentials, VCL service, final public origin, and service activation remain under human release/infrastructure authority.
+
+Release packing also checks the installed CLI command specification,
+configuration schema bundle, release/version manifests, shell completions,
+current architecture and plugin-readiness records, maintenance policy, and
+publication/deployment references.

package/docs/maintainers/release-manifest.md

@@ -0,0 +1,88 @@
+# Release manifest and generated package policy
+
+<!-- Generated by wasm/scripts/sync-reference-docs.cjs. Edit the source catalog, not this file. -->
+
+`release/pulse-release-manifest.json` is the canonical owner of the synchronized release version, documentation origin and exact segment, repository metadata, support tiers, package roles, direct-install guidance, supported entry points, and stability promises.
+
+## Beta candidate
+
+- **Candidate:** Pulse 1.0.0-beta.1 — Beta
+- **Version:** `1.0.0-beta.1`
+- **Activation stage:** `documentation-release`
+- **License:** `Apache-2.0`
+- **Supported Node:** `^22.14.0 || ^24.0.0`
+- **Minimum Node:** `22.14.0`
+- **Release seal Node:** `^24.0.0`; the exact patch used is recorded in seal evidence
+- **Reproducible publication toolchain:** Node `24.18.0` with npm `11.15.0`
+- **Readiness register:** `release/release-preflight.json`
+- **Documentation inventory:** `release/documentation-inventory.json`
+- **Exact documentation:** `https://pulsecompute.io/v1.0.0-beta.1/`
+- **Runtime targets:** 3
+- **Packages:** 18
+
+The installed CLI ships the same machine-readable data as
+`release-manifest.json`. The atomic snapshot transaction aligns
+the Beta label, `beta` channel,
+release date, package metadata, and exact-version documentation inputs. Tooling
+can read [the hosted JSON copy](../reference/release-manifest.json) without scraping
+package READMEs.
+
+## Generated consumers
+
+The manifest drives:
+
+- all package README status blocks;
+- the [package support table](../packages/README.md) and tier pages;
+- package repository, homepage, and bug metadata;
+- supported-entry-point release checks;
+- release prerequisites and documentation classification;
+- exact-version documentation URLs;
+- the homepage target pipeline and release badge;
+- the hosted version banner and release search index.
+
+## Runtime targets
+
+| ID | Label | Mode | Contract |
+|---|---|---|---|
+| `node` | Node | `execute` | Explicit Native and generally available JavaScript execution over one canonical application contract. |
+| `fastly` | Fastly Compute | `execute-and-build` | Explicit Native direct-host-ABI Wasm and generally available JavaScript source/deployment candidates. |
+| `none` | Compile only | `compile` | Compilation and inspection without a runnable provider target. |
+
+The target list is consumed by the public homepage and must stay aligned with
+the built-in provider support catalog and project configuration schema.
+Project-owned provider packages do not become official release targets merely
+because a project selects them through the namespace convention or an exact
+scoped package name.
+
+## Support tiers
+
+| ID | Label | Promise |
+|---|---|---|
+| `canonical-application` | Canonical application surface | Fully documented and supported as the Pulse application authoring or workflow contract. |
+| `supported-extension` | Supported provider/extension surface | Documented entry points are supported; implementation and toolchain subpaths are explicitly excluded. |
+| `implementation` | Implementation/transitive surface | Installable as part of the synchronized release set, without an application-author compatibility guarantee. |
+
+## Synchronized packages
+
+| Package | Support tier | Canonical guide | Direct installation |
+|---|---|---|---|
+| `@pulse-compute/runtime` | Canonical application surface | [Guide](../packages/runtime.md) | Yes. Install it in every Pulse application. |
+| `@pulse-compute/pulse` | Canonical application surface | [Guide](../packages/pulse.md) | Yes. Install it in every conventional Pulse project. |
+| `@pulse-compute/cli` | Canonical application surface | [Guide](../packages/cli.md) | Yes. Install the package globally or as a project development dependency. |
+| `@pulse-compute/provider-fastly` | Supported provider/extension surface | [Guide](../packages/provider-fastly.md) | Yes, for Fastly projects. Node-only projects do not need to import it directly. |
+| `@pulse-compute/grip` | Supported provider/extension surface | [Guide](../packages/grip.md) | Yes, only when the application uses GRIP/Fanout behavior. |
+| `@pulse-compute/assets` | Supported provider/extension surface | [Guide](../packages/assets.md) | Yes, only when the application uses the assets capability. |
+| `@pulse-compute/crypto` | Supported provider/extension surface | [Guide](../packages/crypto.md) | Yes, when an application uses the crypto verification surface directly; JWT applications receive it transitively. |
+| `@pulse-compute/jwt` | Supported provider/extension surface | [Guide](../packages/jwt.md) | Yes, when an application verifies JWTs. |
+| `@pulse-compute/entities` | Supported provider/extension surface | [Guide](../packages/entities.md) | Yes, when an application declares entity operations. |
+| `@pulse-compute/wasm-build-support` | Implementation/transitive surface | [Guide](../packages/implementation-packages.md) | No for application projects; it is installed transitively where required. |
+| `@pulse-compute/wasm-compiler` | Implementation/transitive surface | [Guide](../packages/implementation-packages.md) | No for application projects; use the pulse CLI. |
+| `@pulse-compute/wasm-guest-link` | Implementation/transitive surface | [Guide](../packages/implementation-packages.md) | No for application projects; it is an internal synchronized compiler dependency. |
+| `@pulse-compute/wasm-contracts` | Implementation/transitive surface | [Guide](../packages/implementation-packages.md) | Provider toolchain authors may install it for the versioned bootstrap contract; application projects receive it transitively. |
+| `@pulse-compute/wasm-host-runtime` | Implementation/transitive surface | [Guide](../packages/implementation-packages.md) | No for application projects; it is installed transitively. |
+| `@pulse-compute/wasm-library-kit` | Implementation/transitive surface | [Guide](../packages/implementation-packages.md) | No for application projects; it is installed transitively. |
+| `@pulse-compute/provider-node` | Implementation/transitive surface | [Guide](../packages/implementation-packages.md) | No for application projects; select provider: node through the CLI. |
+| `@pulse-compute/wasm-runtime-core-as` | Implementation/transitive surface | [Guide](../packages/implementation-packages.md) | No for application projects; it is installed transitively. |
+| `@pulse-compute/wasm-schema-json` | Implementation/transitive surface | [Guide](../packages/implementation-packages.md) | No for application projects; declare schemas in the selected .pulse/config.ts profile. |
+
+A package export that is absent from its manifest entry is not promoted to a supported application-author API merely because Node or npm can resolve it.

package/docs/maintainers/repository-setup.md

@@ -0,0 +1,145 @@
+<!-- pulse-doc-meta:start
+owner: maintainer-council
+status: active
+last-reviewed: 2026-07-25
+review-by: 2027-01-25
+pulse-doc-meta:end -->
+
+# Repository setup
+
+Files in this repository define the desired control plane, but GitHub teams, rulesets, environments, secrets, connected services, security settings, and production delivery configuration live outside Git. A repository owner must apply these steps after cloning or transferring the repository.
+
+## 1. Create the maintainer team
+
+Create a visible organization team with the slug:
+
+```text
+pulse-compute/pulse-maintainers
+```
+
+Give the team write access to the repository and add the human architecture and release authority. The generated `.github/CODEOWNERS` file assigns protected areas to `@pulse-compute/pulse-maintainers`; GitHub cannot request that team until it exists, is visible, and has repository access.
+
+## 2. Restrict Actions and synchronize labels
+
+In the repository's Actions settings, allow only GitHub-authored actions and the explicitly required external action, or use an equivalent organization allowlist. Every checked-in action reference is pinned to a reviewed full commit SHA recorded in `release/maintenance-policy.json`.
+
+Run the manual **Maintainer labels** workflow from the default branch. It creates or updates the labels generated in `.github/labels.yml` from `release/maintenance-policy.json`.
+
+Labels classify intake and review state. They do not authorize implementation or merge.
+
+## 3. Create a branch ruleset for `main`
+
+Create a ruleset targeting the default branch and require pull requests. Recommended settings are:
+
+- at least one approving review;
+- approval from code owners;
+- dismissal of stale approvals after new commits;
+- conversation resolution;
+- blocked force pushes and deletion;
+- no Codex, Actions-token, or automation-account bypass; and
+- these exact status checks from `release/maintenance-policy.json`:
+  - `Maintainer scope / scope`
+  - `Repository validation / maintenance`
+  - `Repository validation / node-floor`
+  - `Repository validation / portable`
+  - `Documentation / build`
+
+Keep workflow, CODEOWNERS, `AGENTS.md`, release-policy, and governance changes under CODEOWNER review. The deterministic scope workflow executes the classifier from an archive of the pull request's trusted base commit rather than running the proposed classifier.
+
+The portable validation job installs the lockfile-pinned workspace graph with lifecycle scripts disabled, builds the workspace outputs needed by tests, and runs the unit, native, JavaScript, and conformance profiles. It does not replace provider, CLI, package, clean-consumer, or external-host evidence in the aggregate release seal.
+
+## 4. Create the protected Codex environment
+
+Create a GitHub Actions environment named:
+
+```text
+codex-maintainer
+```
+
+Configure it to allow deployment only from the default branch. When supported by the repository plan and desired operating model, require a human reviewer before the job starts.
+
+Add this environment secret:
+
+```text
+OPENAI_API_KEY
+```
+
+Do not add the key as a broadly available repository secret. GitHub releases an environment secret to a job only after the configured environment protection rules pass.
+
+The manual **Codex maintainer review** workflow also checks that it was dispatched from the default branch. It checks out the pull-request merge ref only to obtain the Git objects, then runs Codex from a separate nested checkout fixed at the trusted base commit. The proposed head is available through local review refs and cannot replace the `AGENTS.md`, policy, prompt, schema, or classifier governing that run. Before Codex starts, the workflow removes the outer proposed working tree so only the trusted nested checkout remains in the Actions workspace.
+
+## 5. Configure Codex
+
+Connect the repository in Codex cloud. Enable native code review when useful and choose whether review should be automatic or explicitly requested. Native review remains advisory and does not replace the repository's required checks.
+
+For the policy-specific review, manually dispatch **Codex maintainer review** from the default branch and supply a pull-request number. The workflow uses the `codex-maintainer` environment and the `OPENAI_API_KEY` environment secret. It does not run on `pull_request_target`, forks, issue comments, pushes, or arbitrary untrusted triggers.
+
+## 6. Enable security intake
+
+Enable private vulnerability reporting and GitHub security advisories. The public security page directs reporters to the repository's private advisory form rather than a normal issue.
+
+## 7. Configure npm trusted publishing
+
+Create a protected GitHub Actions environment named:
+
+```text
+npm-publish
+```
+
+Allow deployment only from release tags and require a human release-authority reviewer. Do not add `NPM_TOKEN` or `NODE_AUTH_TOKEN` to the repository or environment.
+
+For every package in `release/pulse-release-manifest.json`, first confirm that the package name exists under the intended npm owner. Missing names need a one-time human 2FA-protected bootstrap publication. Then configure npm trusted publishing with the exact repository, `npm-publish.yml` workflow filename, and `npm-publish` environment.
+
+Select the exact `v<releaseVersion>` tag as the workflow ref, then run **npm
+publication** manually. Confirm that the protected job receives OIDC only after
+approval, the registry integrity report covers every package in the sealed
+release catalog, the configured dist-tags point to the synchronized version,
+and the clean published-CLI smoke test passes.
+
+## 8. Configure documentation delivery
+
+Create a protected GitHub Actions environment named:
+
+```text
+documentation-production
+```
+
+Allow deployment only from release tags and require a human release/infrastructure reviewer. Add bucket-limited read/write Object Storage credentials as environment secrets:
+
+```text
+FASTLY_OBJECT_STORAGE_ACCESS_KEY_ID
+FASTLY_OBJECT_STORAGE_SECRET_ACCESS_KEY
+```
+
+Add these environment variables:
+
+```text
+FASTLY_OBJECT_STORAGE_BUCKET
+FASTLY_OBJECT_STORAGE_REGION
+FASTLY_OBJECT_STORAGE_ENDPOINT
+PULSE_DOCUMENTATION_ORIGIN
+PULSE_DOCUMENTATION_BASE_PATH
+```
+
+Create a separate bucket-limited read-only key for the Fastly VCL private origin. Do not expose that key to GitHub Actions, and do not place the read/write deployment key in VCL.
+
+Install the checked-in snippets under `infra/fastly/documentation/` in a non-production Fastly service version, configure the regional Object Storage backend and protected origin credentials, then verify GET, HEAD, directory indexes, exact-version caching, root/latest caching, branded 404s, and security headers before manual activation.
+
+The **Documentation** workflow now validates pull requests and `main` and uploads preview artifacts only. Select the exact release tag as the workflow ref, then manually dispatch **Documentation deployment**. It uploads and verifies immutable exact-version objects, verifies the matching npm catalog, promotes root/latest, and verifies the final route through Fastly. Before activation, change the release-owned documentation origin from the old Pages hostname to the final Fastly-served origin; the workflow rejects a mismatch.
+
+## 9. Verify the installation
+
+Open a test pull request that changes one documentation file. Keep the declaration block and set:
+
+```text
+Change class: documentation
+Scope: inside-developer-preview
+Protected boundaries: none
+Human decision: not-required
+```
+
+Confirm that all four required checks report. Then change a control-plane file and confirm that CODEOWNER review is requested and the scope report names `maintenance-control-plane`.
+
+Finally, manually run the Codex maintainer review from the default branch against the test pull request. Confirm that the environment protection activates, that one marked structured comment is created or updated, and that no secret is exposed to the posting job.
+
+Repository settings are not validated from a source archive. Record completion in the release checklist or repository administration log.

package/docs/maintainers/scope-policy.md

@@ -0,0 +1,93 @@
+<!-- pulse-doc-meta:start
+owner: maintainer-council
+status: active
+last-reviewed: 2026-07-25
+review-by: 2027-01-25
+pulse-doc-meta:end -->
+
+# Scope policy
+
+The maintenance control plane separates routine work from product decisions. The exact catalog is generated in the [maintenance policy reference](./maintenance-policy.md); this page explains how to use it.
+
+## Classify the intent
+
+Every issue and pull request begins with one change class:
+
+- **Defect** — documented or tested supported behavior is broken.
+- **Hardening** — reliability, security, performance, diagnostics, or evidence improves without widening behavior.
+- **Documentation** — explanation, examples, generated references, or presentation changes only.
+- **Evidence** — a reproduction, fixture, benchmark, or experiment records information without creating a promise.
+- **Scope expansion** — new syntax, capability, provider, effect, public export, or compatibility promise.
+- **Architecture** — a trust boundary, execution contract, ownership rule, or governance mechanism changes.
+- **Release** — publication, package composition, version, channel, deployment, signing, or provenance changes.
+
+The first four classes can normally move to implementation and human review. The last three require a separate human decision before implementation is treated as approved direction.
+
+## Declare affected boundaries
+
+Path rules conservatively infer protected boundaries, including the public API, effects and capabilities, continuations, lowerer trust, provider registry, configuration contract, compatibility surface, package publication, maintenance control plane, and release authority.
+
+A path match does not claim that every edit changes the contract. It requires the pull request to name the boundary so reviewers can distinguish a mechanical edit from a semantic one.
+
+## Pull-request declaration
+
+Every pull request keeps this comment in its body:
+
+```text
+<!-- pulse-maintainer-declaration:start -->
+Change class: defect
+Scope: inside-developer-preview
+Protected boundaries: none
+Human decision: not-required
+<!-- pulse-maintainer-declaration:end -->
+```
+
+Use comma-separated boundary IDs, or `none`. Use `required` when scope, architecture, or release authority needs an explicit decision.
+
+The `Maintainer scope / scope` check compares the declaration with changed paths. It has three outcomes:
+
+- **pass** — the declaration is present and consistent with the conservative path inference;
+- **decision-required** — the declaration is consistent and a separate human decision is correctly exposed;
+- **fail** — the declaration is missing, uses unknown values, omits inferred boundaries, or contradicts the required decision state.
+
+A decision-required result is not an agent approval or denial. Branch rules and CODEOWNER review remain the authority gate.
+
+## Update current contracts
+
+For each protected boundary, the maintenance policy records whether an approved
+architecture or release change requires a current contract update. When it
+does, edit the canonical present-tense architecture, concept, contributor,
+governance, or release owner and update its executable evidence. Do not add a
+chronological decision file instead of repairing current truth.
+
+The [current architecture contracts](../architecture/current-contracts.md)
+provide the ownership map. Git history and sealed checkpoints preserve the
+superseded state.
+
+## Select validation
+
+The classifier returns required checks from the path policy. Portable checks can run in a source snapshot without the complete release dependency bundle. Dependency-bound checks remain mandatory before publication when their affected contract is touched.
+
+Run the classifier locally with a pull-request body saved to a file:
+
+```bash
+node scripts/maintainer-scope.cjs \
+  --base origin/main \
+  --head HEAD \
+  --declaration-file /tmp/pulse-pr-body.md \
+  --check
+```
+
+Run the control-plane validation independently:
+
+```bash
+npm run maintainer:check
+```
+
+## Scope requests are evidence first
+
+A request for a new provider, npm compatibility, streaming primitive, lowerer
+API, agent facility, or host capability is not rejected merely because it is
+outside the Beta. It is labeled and retained as evidence.
+Implementation begins only when the human authority chooses the product and
+architectural direction.

package/docs/maintainers/support-and-triage.md

@@ -0,0 +1,74 @@
+<!-- pulse-doc-meta:start
+owner: maintainer-council
+status: active
+last-reviewed: 2026-07-25
+review-by: 2027-01-25
+pulse-doc-meta:end -->
+
+# Support and triage
+
+Pulse can launch quietly while still giving users a predictable way to report problems. The support posture favors high-signal evidence and bounded maintenance over an implied service-level agreement.
+
+## Intake routes
+
+Use the repository forms for:
+
+- supported-behavior defects;
+- documentation problems;
+- scope or architecture proposals;
+- usage questions and support requests.
+
+Report suspected vulnerabilities privately through GitHub security advisories. Do not include credentials, proprietary source, private URLs, customer data, or exploitable details in a public issue.
+
+## First response
+
+A maintainer or Codex should establish:
+
+1. release and package versions;
+2. host operating system and Node version;
+3. target provider;
+4. the smallest reproducible project or fixture;
+5. exact command and diagnostic code;
+6. whether the behavior is documented as supported;
+7. whether the report suggests a protected-boundary change.
+
+Then classify the report as defect, hardening, documentation, evidence, scope expansion, architecture, or release.
+
+## Quiet-launch posture
+
+The Beta makes no response-time or compatibility guarantee beyond
+its documented release contract. Normal maintenance priority is:
+
+1. containment, secret exposure, artifact escape, or release-integrity failures;
+2. regressions in supported examples and canonical CLI behavior;
+3. incorrect diagnostics, packaging, provider realization, or documentation;
+4. hardening and usability friction;
+5. scope requests retained as evidence.
+
+A popular request is not automatically a product decision. Repeated evidence should be summarized for the human maintainer, including the affected architectural boundary and the smallest coherent option.
+
+## Patch posture
+
+Codex may prepare a patch for an in-scope defect or hardening issue after reproduction. The patch should:
+
+- repair the canonical owner;
+- add the smallest contract evidence;
+- preserve explicit rejection and host authority;
+- update diagnostics and documentation when the user-visible contract changes;
+- run the policy-selected portable checks;
+- list dependency-bound checks still required;
+- avoid unrelated cleanup.
+
+Scope, architecture, and release proposals remain analysis until the human authority approves direction.
+
+## Closing issues
+
+Close an issue with one of four clear outcomes:
+
+- fixed in a named release or commit;
+- documented as expected Beta behavior;
+- retained as evidence for a future decision;
+- declined because it conflicts with a stated invariant.
+
+Avoid vague “won't fix” responses. Explain the boundary and point to the
+relevant preview-scope, concept, reference, or maintenance-policy page.