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

package/docs/maintainers/testing.md

@@ -0,0 +1,288 @@
+<!-- pulse-doc-meta:start
+owner: maintainer-council
+status: active
+last-reviewed: 2026-07-16
+review-by: 2027-01-16
+pulse-doc-meta:end -->
+
+# Testing Pulse
+
+Pulse organizes evidence by product behavior. Every task has one registry entry, a finite timeout, an isolated temporary root, and an optional ephemeral report.
+
+## Workspace checks
+
+```bash
+pnpm build
+pnpm test
+```
+
+These commands cover the TypeScript workspace and package-level unit tests.
+
+## Functional profiles
+
+| Profile | Evidence |
+|---|---|
+| `unit` | package exports, repository boundaries, workspace hygiene, API shape, project graphs, schema registry, and continuation registry |
+| `native` | lowering, canonical runtime behavior, AssemblyScript compilation, and provider-neutral Wasm execution |
+| `javascript` | explicit JavaScript target support, request-owned effects, and package JavaScript realization |
+| `conformance` | Node/Fastly Native/JavaScript Router, fetch, binding, schema, GRIP, logging, and target-integrity parity |
+| `providers` | Fastly Native and JavaScript packaging, runtime, capability, tooling, HTTP, and platform realization |
+| `cli` | commands, diagnostics, clean projects, live development, and executable documentation examples |
+| `release` | every functional profile plus package construction, deterministic artifacts, packed clean-consumer acceptance, evidence authority, and offline deployment candidates |
+
+Run one profile or task:
+
+```bash
+node wasm/scripts/run-wasm-tests.cjs --profile unit
+node wasm/scripts/run-wasm-tests.cjs --profile conformance
+node wasm/scripts/run-wasm-tests.cjs --task schema-codecs
+node wasm/scripts/run-wasm-tests.cjs --list
+```
+
+The event mechanism has focused provider-neutral tasks, plus one project-level
+workflow task included in the `cli` and `release` profiles:
+
+```bash
+node wasm/scripts/run-wasm-tests.cjs --task events-static-topology --no-report
+node wasm/scripts/run-wasm-tests.cjs --task events-javascript-runtime --no-report
+node wasm/scripts/run-wasm-tests.cjs --task events-emit-javascript --no-report
+node wasm/scripts/run-wasm-tests.cjs --task events-native-runtime --no-report
+node wasm/scripts/run-wasm-tests.cjs --task events-node-reference --no-report
+node wasm/scripts/run-wasm-tests.cjs --task events-cli-workflow --no-report
+node wasm/scripts/run-wasm-tests.cjs --task events-conformance --no-report
+node wasm/scripts/run-wasm-tests.cjs --task events-candidate-seal --no-report
+```
+
+`events-native-runtime` proves exact event dispatch, schema payload handles,
+effect/continuation resume, event-only and mixed artifacts, conditional ABI
+shape, two-build reproducibility, and HTTP-only byte identity. It is a
+provider-neutral runtime proof and does not activate provider event transport.
+`events-node-reference` proves Node JavaScript/Native direct parity, Native emit
+suspension/resume, exact accepted frames, bounded FIFO ingress, cancellation,
+failure categories, instance isolation, no loopback, zero JavaScript/Asyncify
+imports, and zero fallback. It does not exercise a public listener or Fastly.
+`events-cli-workflow` proves mixed HTTP/event harness cases, exact emitted-frame
+expectations, Node JavaScript/Native project parity, event catalog packaging,
+compile-only inspection, and the exact Fastly fail-closed eligibility boundary.
+`events-conformance` drives the canonical bounded corpus through Node
+JavaScript and Native and compares every semantic projection exactly, including
+limits, queues, cancellation, redaction, state isolation, completion, and the
+absence of loopback or a call surface. `events-candidate-seal` packs the
+event-facing public package closure, installs it offline, type-checks author and
+host consumers, verifies deterministic tarballs, and emits the EV9 candidate
+decision plus blocker ledger. The candidate seal is evidence-only and does not
+assign a release or publish anything.
+
+Replay the existing Fastly HTTP regression through an explicitly selected
+workspace-local Viceroy 0.20.1 binary; this does not claim Fastly event support:
+
+```bash
+PULSE_VICEROY_BIN=/path/to/viceroy-0.20.1/viceroy \
+node wasm/scripts/run-wasm-tests.cjs \
+  --task provider-fastly-compute-reality \
+  --no-report
+```
+
+Event cases are an explicit harness discriminant; existing request cases remain
+unchanged:
+
+```ts
+export default [
+  {
+    name: 'health',
+    request: { method: 'GET', path: '/health' },
+    expect: { status: 200, text: 'ok' },
+  },
+  {
+    name: 'ingress',
+    kind: 'event',
+    event: {
+      type: 'input.received',
+      schema: 'events.Input',
+      payload: { sequence: 7 },
+    },
+    expect: {
+      status: 'completed',
+      emitted: [{
+        type: 'output.accepted',
+        schema: 'events.Output',
+        payload: { accepted: true, sequence: 7 },
+      }],
+    },
+  },
+]
+```
+
+`expect.emitted` is ordered and exact. It proves host acceptance only; it does
+not imply delivery, automatic loopback, or a public injection command.
+
+The source-bound [`examples/11-events`](../../examples/11-events/) project runs
+the same mixed HTTP/event topology through `doctor`, `inspect`, `test`, and
+`build`. Its `dev` command remains HTTP-only.
+
+Maintainers may bound a diagnostic rerun:
+
+```bash
+node wasm/scripts/run-wasm-tests.cjs --profile release --from cli-project-workflow
+node wasm/scripts/run-wasm-tests.cjs --profile cli --through docs-example-03-fetch-composition
+```
+
+`--from` and `--through` aid investigation. A release claim requires the complete release profile.
+
+## Aggregate release seal
+
+```bash
+npm run release:seal
+```
+
+The seal restores the lockfile-pinned dependency graph, regenerates production
+vulnerability and license evidence, validates maintenance and source publication
+controls, builds and unit-tests the workspace, checks synchronized documentation,
+runs the release profile, and records revision-bound evidence under
+`wasm/.test-results/`. The release profile creates deterministic Fastly
+Native and JavaScript candidate inputs and invokes the pinned downstream
+JavaScript compiler locally. It does not deploy or publish either candidate.
+
+External npm organization settings, trusted publishers, protected publication
+environments, public repository administration, and the production documentation
+origin do not authorize or block candidate construction. They remain explicit
+publication and documentation-deployment gates after the candidate is sealed.
+
+When the Fastly CLI and its managed local Compute engine are available, the same command also runs the external native-host proof. Require that environment explicitly with:
+
+```bash
+npm run release:seal -- --require-fastly
+```
+
+To validate an already restored dependency graph:
+
+```bash
+npm run release:seal -- --skip-install
+```
+
+The Docker-built offline dependency bundle is created and restored with:
+
+```bash
+./scripts/bundle_deps.sh
+./scripts/restore_deps.sh ./pulse-wasm-deps-....tar.zst
+```
+
+The restore script reconstructs the dependency graph only. The release seal owns product validation.
+
+After a clean passing seal, aggregate the persisted reports into the sixteen
+release evidence shards and verify an exact binary patch replay:
+
+```bash
+npm run release:evidence -- \
+  --base <accepted-source-ref> \
+  --head HEAD \
+  --label <delivery-name> \
+  --out <new-output-directory>
+```
+
+The authority creates a source-only archive, binary patch, independent replay,
+four-mode and target-integrity reports, migration ledger, maintainer scope,
+Fastly Native and JavaScript candidates, checksums, and one delivery bundle. It
+requires a clean tree and matching source revisions in every persisted report.
+
+## Executable documentation
+
+Documentation execution belongs to the `cli` profile because every public example is driven through installed command behavior. Separate tasks cover:
+
+- source-bound documentation contracts;
+- clean `pulse init` and live `pulse dev`;
+- each canonical example’s `doctor`, `inspect`, `test`, and `build` flow.
+
+Source-backed blocks use:
+
+```text
+&lt;!-- pulse-doc-source: examples/01-hello-json/src/index.ts --&gt;
+<exact fenced source block>
+&lt;!-- /pulse-doc-source --&gt;
+```
+
+Synchronize or check generated documentation with:
+
+```bash
+pnpm docs:sync
+pnpm docs:check
+```
+
+Command/result blocks use `pulse-doc-run` metadata and compare stable semantic fields rather than durations or absolute paths.
+
+## Package and consumer evidence
+
+The release profile:
+
+- constructs all publishable package tarballs from the canonical release catalog;
+- checks package metadata, exports, exact versions, dependency rewriting, and payload hygiene;
+- builds release packages and the documentation site twice and compares byte identities;
+- installs every exact Pulse candidate while a loopback-only read-only registry keeps the `@pulse-compute` scope fail-closed;
+- resolves third-party dependencies from the canonical npm registry instead of repacking development-install artifacts;
+- exercises fresh Native Node, JavaScript Node, Native Fastly, GRIP, and Router projects without workspace links;
+- builds the representative Fastly JavaScript source closure twice, compiles one exact closure with the pinned runtime toolchain, and records the no-deploy/no-publish boundary.
+
+Run a focused package or consumer proof when diagnosing:
+
+```bash
+node wasm/scripts/run-wasm-tests.cjs --task release-packages --no-report
+node wasm/scripts/run-wasm-tests.cjs --task clean-machine-acceptance --no-report
+node wasm/scripts/run-wasm-tests.cjs --task deployment-candidates --no-report
+```
+
+## JWT and crypto proof seals
+
+The `1.0.0-beta.1` JWT/crypto packages build on the focused crypto seal,
+which replays the
+configuration, JavaScript runtime, Native guest-source, shared cross-target
+corpus, and real Fastly Compute proofs. First record the one phase-boundary
+aggregate replay, then run the seal:
+
+```bash
+node wasm/scripts/run-wasm-tests.cjs \
+  --profile unit \
+  --profile native \
+  --profile javascript \
+  --profile conformance \
+  --profile providers \
+  --report .test-results/crypto-c4/relevant-aggregate.json
+node wasm/scripts/run-wasm-tests.cjs --task crypto-verification-seal --no-report
+```
+
+The seal writes `wasm/.test-results/crypto-c4/phase-c-seal.json` and the shared
+corpus proof writes
+`wasm/.test-results/crypto-c4/crypto-cross-target-conformance.json`. Both
+reports contain status, target realization, toolchain, boundary, and size
+evidence; neither contains keys, messages, authenticators, or ambient backend
+errors. The preserved Phase C seal records the earlier package boundary. JWT
+composition is now sealed in
+`wasm/.test-results/jwt-d4/jwt-phase-d-seal.json`, and the complete four-cell
+target proof is sealed in
+`wasm/.test-results/jwt-e4/jwt-phase-e-seal.json`.
+
+Consolidate those records with the guest-memory decision, guest-link pipeline,
+current documentation, and synchronized package identity using:
+
+```bash
+node wasm/scripts/run-wasm-tests.cjs \
+  --task jwt-evidence-consolidation \
+  --no-report
+```
+
+The task writes
+`wasm/.test-results/jwt-f0/jwt-f0-evidence-consolidation.json`, verifies
+preserved hashes, and proves the JWT/crypto implementation evidence remains
+internally consistent. It does not publish, promote, deploy, or activate
+anything.
+
+## Runner evidence
+
+The runner writes `wasm/.test-results/last-run.json` atomically after every task and stores one log per task. When a task fails, task-owned `*.log` files such as npm debug logs are copied into that run's durable diagnostics directory before the temporary root is removed. On timeout it captures a Node diagnostic report, terminates the entire task process group, and reports any surviving descendants. The directory is ephemeral and should contain only evidence produced from the current tree.
+
+## Redundancy policy
+
+- Add a task once to `wasm/test/suite/registry.cjs`; do not add a package script per test.
+- Prefer the strongest end-to-end oracle that proves the behavior.
+- Keep compiler goldens, runtime traces, provider results, CLI subprocess output, build manifests, and executable docs at their owning boundary.
+- Do not derive expected constants from the implementation being tested.
+- Remove a weaker fixture when a stronger oracle covers the same claim.

package/docs/packages/README.md

@@ -0,0 +1,59 @@
+# Package support policy
+
+<!-- Generated by wasm/scripts/sync-reference-docs.cjs. Edit the source catalog, not this file. -->
+
+Pulse 1.0.0-beta.1 publishes one synchronized 18-package release set. Publication does not make every package an application-author SDK: the support tier and listed entry points define the release promise.
+
+| Package | Support tier | Install directly | Release promise |
+|---|---|---:|---|
+| [`@pulse-compute/runtime`](./runtime.md) | Canonical application surface | Yes | Supported application authoring and execution contract. |
+| [`@pulse-compute/pulse`](./pulse.md) | Canonical application surface | Yes | Supported conventional application, project-configuration, and schema-authoring contract. |
+| [`@pulse-compute/cli`](./cli.md) | Canonical application surface | Yes | Supported Beta workflow and project-configuration contract. |
+| [`@pulse-compute/provider-fastly`](./provider-fastly.md) | Supported provider/extension surface | Yes | The listed entry points are supported for the Beta; all other exported subpaths are implementation-only. |
+| [`@pulse-compute/grip`](./grip.md) | Supported provider/extension surface | Yes | The package root has bounded JavaScript and Native HTTP-framing realization plus configured Node/Fastly broadcast; /pulsewasm remains compatibility-only. |
+| [`@pulse-compute/assets`](./assets.md) | Supported provider/extension surface | Yes | The package root is the supported JavaScript API and canonical Native authoring surface; /pulsewasm remains a compatibility subpath, while manifest/compiler subpaths are toolchain integration. |
+| [`@pulse-compute/crypto`](./crypto.md) | Supported provider/extension surface | Yes | The package root is the supported bounded verification contract; realization and Native integration subpaths remain toolchain-only. |
+| [`@pulse-compute/jwt`](./jwt.md) | Supported provider/extension surface | Yes | The package root is the supported provider-neutral verification contract; provider and compiler integration subpaths are not application APIs. |
+| [`@pulse-compute/entities`](./entities.md) | Supported provider/extension surface | Yes | The package root and first-party JSON-RPC adapter are supported Beta contracts; compiler integration subpaths remain toolchain-only. |
+| [`@pulse-compute/wasm-build-support`](./implementation-packages.md) | Implementation/transitive surface | No | Internal release-set interface; exported modules may change with compiler implementation needs. |
+| [`@pulse-compute/wasm-compiler`](./implementation-packages.md) | Implementation/transitive surface | No | Internal compiler interface; no application-author compatibility guarantee. |
+| [`@pulse-compute/wasm-guest-link`](./implementation-packages.md) | Implementation/transitive surface | No | Internal first-party prebuilt guest-link interface synchronized with the compiler; no application-author or third-party guest compatibility guarantee. |
+| [`@pulse-compute/wasm-contracts`](./implementation-packages.md) | Implementation/transitive surface | No | The provider toolchain contract is versioned and supported for the Beta; other protocol and proof interfaces remain internal. |
+| [`@pulse-compute/wasm-host-runtime`](./implementation-packages.md) | Implementation/transitive surface | No | Internal compiler/runtime interface synchronized with this release set. |
+| [`@pulse-compute/wasm-library-kit`](./implementation-packages.md) | Implementation/transitive surface | No | Internal package-lowering interface synchronized with this release set. |
+| [`@pulse-compute/provider-node`](./implementation-packages.md) | Implementation/transitive surface | No | The listed built-in toolchain entry is synchronized with the Beta bootstrap contract; other canonical Node provider interfaces remain internal. |
+| [`@pulse-compute/wasm-runtime-core-as`](./implementation-packages.md) | Implementation/transitive surface | No | Internal code-generation interface synchronized with this release set. |
+| [`@pulse-compute/wasm-schema-json`](./implementation-packages.md) | Implementation/transitive surface | No | Internal schema compiler interface synchronized with this release set. |
+
+## Tier definitions
+
+### Canonical application surface
+
+Fully documented and supported as the Pulse application authoring or workflow contract.
+
+### Supported provider/extension surface
+
+Documented entry points are supported; implementation and toolchain subpaths are explicitly excluded.
+
+### Implementation/transitive surface
+
+Installable as part of the synchronized release set, without an application-author compatibility guarantee.
+
+## Reading package READMEs
+
+Every packed README begins with a generated status block covering audience, direct-install guidance, supported entry points, and stability. An export that is not listed in that block is not automatically a supported application-author entry point.
+
+## Extension and provider boundary in 1.0.0-beta.1
+
+Pulse supports the documented package-owned assets and GRIP facades and the documented Fastly provider entry points. Their implementation demonstrates the internal contract, but `1.0.0-beta.1` does **not** expose a general third-party plugin registry:
+
+- lowerer manifests are accepted only from trusted first-party release packages;
+- arbitrary external lowerer discovery and execution are not supported;
+- provider selection is limited to `node`, `fastly`, and compile-only `none`;
+- adding a new lowerer or provider currently means changing and testing the synchronized Pulse release set.
+
+Documentation may explain lowering and the internal contract, but it must not promise that an external npm package can self-register a lowerer or provider. A future public plugin API requires an explicit trust model, discovery, version negotiation, security policy, and compatibility contract.
+
+## Installed documentation
+
+`@pulse-compute/runtime` ships its canonical API reference and Beta scope. `@pulse-compute/cli` ships the public documentation hierarchy, CLI/config/diagnostic references, bounded compatibility material, and runnable example sources. Package README links must resolve either inside their own tarball or to an exact-version hosted Pulse documentation URL.

package/docs/packages/assets.md

@@ -0,0 +1,85 @@
+# `@pulse-compute/assets`
+
+`@pulse-compute/assets` is the supported application entry point for both direct JavaScript execution and supported Native lowering.
+
+The package root exposes the complete JavaScript asset implementation—local files, hosted origins, S3-compatible buckets, and SigV4 support—plus the narrow request-bound surface that Native compilation can recognize.
+
+## Install
+
+```bash
+npm install @pulse-compute/assets@1.0.0-beta.1
+```
+
+## Portable lookup surface
+
+```ts
+import { assets } from '@pulse-compute/assets'
+
+const found = await assets.lookup(ctx, 'public', '/app.js', {
+  method: 'GET',
+  cacheControl: 'public, max-age=60',
+})
+
+return assets.respond(found)
+```
+
+The portable surface is:
+
+- `assets.lookup(ctx, store, key, options?)` — a request-bound package effect that may be directly awaited or used inside `ctx.parallel({ ... })`;
+- `assets.respond(response, options?)` — a pure response-adoption and decoration helper;
+- equivalent named exports `lookup` and `respond`.
+
+JavaScript executes the real package implementation through the request-owned package-effect bridge. Native compilation recognizes the same package-root call and emits the canonical `assets.lookup` package effect. Supported Native argument restrictions are enforced by package lowering eligibility and diagnostics rather than by changing the JavaScript API.
+
+## JavaScript middleware
+
+The package root also exports:
+
+```ts
+import {
+  AssetManager,
+  AssetBucket,
+  createAssets,
+  signSigV4,
+} from '@pulse-compute/assets'
+```
+
+`createAssets()` supports local, hosted, and bucket-backed middleware. Hosted and bucket responses adopt upstream Web streams directly, preserving status, headers, and host-owned response-body ownership. Local assets currently follow the restored implementation and materialize the selected file. Broader request/response resource limits belong at a shared core ownership boundary rather than in an Assets-only policy.
+
+## Response ownership
+
+A direct asset response preserves:
+
+- status, including range responses such as `206`;
+- repeated and ordinary headers;
+- `GET` and `HEAD` behavior;
+- upstream Web stream identity for hosted and bucket modes;
+- cancellation of discarded upstream bodies during pass-through or bodyless responses.
+
+The portable response is opaque to Native application code. Structured request-body and fetched-response projection bounds remain separate core contracts.
+
+## Compatibility subpath
+
+`@pulse-compute/assets/pulsewasm` remains a compatibility subpath. New
+applications should import from `@pulse-compute/assets`. The manifest and
+compiler subpaths are trusted toolchain integration, not application APIs. See
+[Compatibility imports and migration](../guides/compatibility-imports.md).
+
+## Package-owned files
+
+The release tarball includes:
+
+- the built JavaScript implementation and type declarations;
+- `pulse.package.json` product and target metadata;
+- `pulsewasm.manifest.cjs` trusted package-lowering identity;
+- `pulsewasm.compiler.cjs` package-specific static validation and lowering;
+- `as/index.as.ts` sidecar declarations used by compiled-Wasm integration.
+
+See [Package-owned lowering](../concepts/package-owned-lowering.md) and [Add a first-party package-owned lowerer](../contributing/adding-first-party-lowerer.md).
+
+## Related documentation
+
+- [Compilation and lowering](../concepts/compilation-and-lowering.md)
+- [Structured and opaque bodies](../concepts/bodies.md)
+- [Package support policy](./README.md)
+- [Implementation packages](./implementation-packages.md)

package/docs/packages/cli.md

@@ -0,0 +1,190 @@
+# `@pulse-compute/cli`
+
+`@pulse-compute/cli` owns the supported `pulse` command, project configuration types, project discovery, compilation workflow, local execution, and target builds.
+
+## Install and initialize
+
+The current repository CLI is a source candidate. Its conventional initializer
+depends on the public `@pulse-compute/pulse` package and is validated from both
+the checkout and the exact packed acceptance set:
+
+```bash
+pnpm pulse -- init ./my-app
+cd ./my-app
+npm install
+pulse doctor
+```
+
+`pulse init` writes a conventional `.pulse/config.ts` workspace, an async
+`Pulse` application root, a dedicated `tests/pulse.harness.ts`, strict
+TypeScript configuration, and exact source-candidate package versions. It does
+not run a package manager or perform hidden network work. Public npm
+availability is defined by the synchronized 18-package release manifest.
+
+## Daily workflow
+
+```bash
+pulse doctor
+pulse inspect
+pulse test
+pulse dev
+pulse compile
+pulse build
+```
+
+- `doctor` validates project, provider, dependencies, and external toolchain readiness.
+- `inspect` compiles and reports effects, continuations, schemas, event registrations/callsites, capabilities, target eligibility, and provider lowering without executing cases.
+- `test` executes configured request and explicit `kind: 'event'` cases through the provider-owned local conformance runtime.
+- `dev` runs a foreground local server and watches the project by default.
+- `compile` writes deterministic provider-neutral Pulse Wasm plus its native plan, generated AssemblyScript, WAT, and manifests.
+- `build` writes the configured target realization: Native profiles emit provider Wasm, while JavaScript profiles emit deterministic source packages. Eligible event projects also emit `event-catalog.json` and `event-inspection.json` beside the target output. Fastly JavaScript packages carry exact downstream compiler pins and deployment-candidate metadata.
+
+See the generated [CLI reference](../reference/cli.md) for every option, positional form, output, side effect, and exit behavior.
+
+## Project configuration
+
+```ts
+import { defineConfig } from '@pulse-compute/pulse'
+
+export default defineConfig((_scope) => ({
+  pulse: {
+    entry: 'src/index.ts',
+    tests: 'tests/pulse.harness.ts',
+    defaultProfile: 'local',
+    strict: true,
+  },
+  local: {
+    host: 'node',
+    target: 'native',
+    outDir: 'dist',
+    dev: { host: '127.0.0.1', port: 8787 },
+  },
+}))
+```
+
+The generated application imports `Pulse` from `@pulse-compute/pulse`, declares
+managed handlers `async`, and keeps deterministic request cases in the separate
+harness module. Workspace discovery starts from `.pulse/config.ts`.
+
+Harness event cases require the explicit `kind: 'event'` discriminant, one
+canonical input frame, and an ordered exact `expect.emitted` array. HTTP cases
+retain their existing shape and default behavior. There is no public `pulse
+event` command and `pulse dev` remains HTTP-only.
+
+The complete event workflow, queue, artifact, target, and diagnostic boundary
+is in [Static events and outbound emission](../guides/events.md).
+
+## Machine-readable contracts and shell completion
+
+The installed package exposes release-owned machine interfaces for editors, automation, validation, and documentation tooling:
+
+| Export or command | Contract |
+|---|---|
+| `pulse completion bash` | Bash completion generated from the public command specification. |
+| `pulse completion zsh` | Zsh completion generated from the same specification. |
+| `pulse completion fish` | Fish completion generated from the same specification. |
+| `@pulse-compute/cli/cli-spec.json` | Seven commands, public options, aliases, positional forms, provider restrictions, output modes, and completion metadata. |
+| `@pulse-compute/cli/project-config.schema.json` | JSON Schema bundle plus discovery, precedence, defaults, runtime rules, and provider configuration schemas. |
+| `@pulse-compute/cli/release-manifest.json` | Exact release, hosted-documentation routes, package tiers, supported entry points, and publication policy. |
+| `@pulse-compute/cli/documentation-versions.json` | Available documentation versions and the current `latest` target. |
+| `@pulse-compute/cli/project-config-schema` | Programmatic schema, defaults, structural validation, and reference metadata. |
+
+These files are generated from the same modules used by the parser, runtime configuration loader, package packer, and documentation release gate. See [Shell completion](../reference/shell-completion.md), the [CLI specification](../reference/cli-spec.json), the [project configuration schema](../reference/project-config.schema.json), and the [release manifest reference](../maintainers/release-manifest.md).
+
+## Public entry points
+
+The supported package surface is:
+
+| Entry point | Intended use |
+|---|---|
+| `pulse` binary | Application and CI workflow. |
+| `@pulse-compute/cli` | `defineConfig`, project-config types, diagnostics helper, and programmatic workflow entry. |
+| `@pulse-compute/cli/workflow` | CLI parsing and execution integration. |
+| `@pulse-compute/cli/project-config` | Project discovery and normalization integration. |
+| `@pulse-compute/cli/project-execution` | Canonical doctor/inspect/test/dev/compile/build orchestration. |
+| `@pulse-compute/cli/diagnostics` | Stable public diagnostic descriptors and mappings. |
+
+Other files present in the tarball are not automatically public APIs.
+
+## JSON output
+
+Completed commands emit one JSON object with a trailing newline when `--json` is used. `pulse dev --json` emits newline-delimited event objects instead of one enclosing document. Supported events include `compiled`, `ready`, `reloaded`, `request`, `compile-error`, and `request-error`.
+
+Stable failures include a public diagnostic code, remediation, exit class, and exact-version documentation URL. See [Diagnostics and remediation](../reference/diagnostics.md).
+
+## Provider behavior
+
+The CLI supports `node`, `fastly`, and compile-only `none`. Node and Fastly each
+accept an explicit `native` or `javascript` execution target:
+
+- Node Native lowers to Pulse-owned Wasm and executes through the Node host.
+- Node JavaScript loads the reachable application graph and runs the live runtime and package implementations.
+- Fastly Native emits compact direct-host-ABI `bin/main.wasm`.
+- Fastly JavaScript emits a deterministic source/deployment package and a structurally deployable downstream runtime candidate.
+- `none` can inspect or compile canonical output but cannot serve or run tests.
+
+For projects with reachable event registrations or `ctx.emit` callsites, Node
+Native and Node JavaScript are eligible for the bounded reference workflow.
+`inspect`, `doctor`, compile/build manifests, and event inspection artifacts
+report the catalog, schema IDs, callsites, host requirements, and per-command
+target support. `none` remains useful for compile-only catalog inspection.
+Fastly Native and JavaScript fail closed with exact event-ingress or event-emit
+diagnostics; Pulse does not translate that plane through HTTP or GRIP and never
+changes targets automatically.
+
+`pulse compile` is provider-neutral regardless of the configured provider. It produces the portable Pulse-owned Wasm boundary directly; `pulse build` continues to own provider realization.
+
+Those provider IDs are configuration data, not command-layer implementation
+branches. The CLI consumes a neutral facade over the compiler-owned fixed
+registry; concrete provider imports, configuration policy, and target adapters
+remain outside the CLI package. Node retains a deliberate reference/smoke role
+for canonical Native behavior.
+
+Both JavaScript declarations satisfy full-target-support and report general
+availability. Project eligibility remains separate, and target selection never
+falls back automatically. Fastly JavaScript `test` and `dev` identify their
+execution mode as provider emulation; the offline candidate gate compiles a real
+Fastly JavaScript runtime artifact but performs no deployment or publication.
+
+Provider and target selection change realization, not handler APIs. See
+[Contracts and providers](../concepts/contracts-and-providers.md).
+
+## Installed documentation payload
+
+The CLI npm package ships:
+
+- this public documentation hierarchy;
+- the canonical API reference;
+- CLI, configuration, diagnostics, environment, release, and version references;
+- generated command/config/release machine interfaces and shell completions;
+- package and contributor guides;
+- ten complete lifecycle example projects plus the focused Entities candidate,
+  including static Router lowering and mixed HTTP/event authoring.
+
+This makes diagnostic links and package README links usable from an installed exact-version release rather than depending on monorepo paths.
+
+## Safety boundaries
+
+- Build output must remain a real descendant of the project root.
+- `--no-clean` does not disable traversal or symbolic-link safety checks.
+- Raw configured secrets are redacted from public JSON and diagnostics.
+- `dev` is a foreground process, not a hidden daemon.
+- Repository-only fixture/profile/task flags are excluded from installed help and the public reference.
+- Fastly external execution is delegated to the Fastly CLI; the reality gate may pass an inspected Viceroy path, but Pulse does not launch Viceroy directly.
+
+## Related documentation
+
+- [Getting started](../getting-started.md)
+- [Project lifecycle](../guides/project-lifecycle.md)
+- [Static events and outbound emission](../guides/events.md)
+- [Provider and target compatibility](../reference/compatibility-matrix.md)
+- [Managed handler TypeScript and JavaScript](../reference/handler-authoring.md)
+- [Node build and execution](../guides/deploying-node.md)
+- [Fastly deployment candidates](../guides/deploying-fastly.md)
+- [CLI reference](../reference/cli.md)
+- [Shell completion](../reference/shell-completion.md)
+- [Project configuration](../reference/project-config.md)
+- [Release manifest and package policy](../maintainers/release-manifest.md)
+- [Documentation versioning](../maintainers/documentation-versioning.md)
+- [Environment-variable reference](../reference/environment.md)
+- [Release acceptance](../maintainers/release-acceptance.md)