Background

PR #178 merged after the latest public release v0.4.6 and added release-surface protection for the npm wrapper documentation. The current binary behavior does not require an urgent runtime release, but the merged CI/docs change is release-surface work and should be explicitly routed before any next tag or package-channel update.

Evidence

• Latest release: v0.4.6, published 2026-05-10.
• Merged after that release: Add npm README release surface checks #178 Add npm README release surface checks, merged 2026-05-10T14:00:00Z.
• Add npm README release surface checks #178 extended scripts/ci/check-release-surfaces.sh so npm/README.md stale release tags and unavailable active npm install wording are checked.
• Post-merge Product validation passed release surfaces, docs commands, output contract, deterministic output, report semantics, and Pages artifact checks.
• Decide npm package publication path before launch docs go live #174 remains open for the actual npm package-channel decision.

User value

Users and contributors get clearer install documentation and lower risk that unavailable npm install instructions reappear in release-facing surfaces.

Adoption rationale

Install-path trust is part of onboarding clarity. Keeping npm wrapper docs synchronized with the actual publication state reduces failed first-run attempts and keeps future package-channel work auditable.

Release type

docs-only / package-surface maintenance

Target version

Next maintainer-authorized version, if a docs-only or patch release is approved.

Release scope

• Include Add npm README release surface checks #178 only unless additional release-surface fixes merge before authorization.
• Keep Decide npm package publication path before launch docs go live #174 as the source of truth for npm publish / defer / do-not-publish decisions.

Suggested scope

• Decide whether Add npm README release surface checks #178 should be included in the next release train or simply remain on master until another user-facing runtime change lands.
• If a release proceeds, run the normal Quality Release Gate before any tag/release execution.
• Keep public npm install wording cautious unless npm publication is explicitly authorized and completed.

Non-goals

• Do not publish npm from this issue.
• Do not create a GitHub release, tag, Homebrew update, or external announcement from Product.
• Do not change package-channel policy; Decide npm package publication path before launch docs go live #174 owns that decision.
• Do not merge PR Add growth assets and npm launch docs #156 from this issue.

Blocker check

No new runtime P0/P1 blocker found in Product validation. Release execution remains blocked on explicit maintainer authorization and Quality Release Gate PASS.

Required authorization

RELEASE_ALLOWED, TAG_ALLOWED, PACKAGE_PUBLISH_ALLOWED, NPM_PUBLISH_ALLOWED, and HOMEBREW_PUBLISH_ALLOWED are not granted by this issue. A maintainer must record any needed authorization before execution.

Package plan

Keep active install paths limited to currently available channels. npm remains prepared but unpublished unless #174 records a maintainer decision and the package is actually published.

Post-release validation

If a release is authorized, verify:

• release tag and agenttrace --version agree
• scripts/ci/check-release-surfaces.sh passes
• scripts/ci/check-docs-commands.sh passes
• output contract, deterministic output, and report semantics checks pass
• Pages artifact check passes
• npm documentation reflects the actual package publication state

Acceptance criteria

• Maintainer records whether this waits for the next runtime release or proceeds as a docs-only/package-surface release train.
• Any release execution has explicit authorization and a Quality Release Gate PASS.
• Decide npm package publication path before launch docs go live #174 remains open until the npm package-channel decision is recorded.
• Public docs do not present unavailable npm installation as an active path.

Suggested lane

lane/growth

Risk

Low implementation risk; moderate onboarding risk if release-facing install copy drifts from actual package availability.

Source

Product post-merge回访 of #178 after v0.4.6.