subharness 0.0.2 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "subharness",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "type": "module",
   "engines": {
     "node": ">=22.18.0"

package/sdk/distribution.md

@@ -16,7 +16,7 @@ Source development uses pnpm 11.20.0, pinned in the root `packageManager` field.
 
 Repository scripts use pnpm, including workspace command forwarding and content-generation lifecycle hooks. Dependency build scripts are explicitly allowed only for the native build helpers required by the installed SDK and website dependencies. Package consumers can use any compatible npm package manager; the clean-consumer check deliberately installs with npm to verify that the published artifact does not require pnpm.
 
-A tarball built from a source checkout can differ from the registry release with the same version. The current package version is `0.0.2`, producing `subharness-0.0.2.tgz`. Install a local tarball with `npm install --save-dev /absolute/path/to/subharness-0.0.2.tgz`. Run the project's local executable with `npx subharness`.
+A tarball built from a source checkout can differ from the registry release with the same version. The current package version is `0.0.3`, producing `subharness-0.0.3.tgz`. Install a local tarball with `npm install --save-dev /absolute/path/to/subharness-0.0.3.tgz`. Run the project's local executable with `npx subharness`.
 
 ## Package contents and release checks
 
@@ -28,6 +28,18 @@ The committed lockfile pins dependency content with integrity hashes and does no
 
 Releases use the public npm registry, public access, and the `latest` distribution tag. A release publishes the verified tarball for its package version. The matching source commit is tagged `v<version>` in the source repository. Publishing the package does not change the repository's internal visibility.
 
+## GitHub release publishing
+
+Publishing a stable GitHub release runs `.github/workflows/release.yml`. The release tag must have the form `vX.Y.Z`, with three nonnegative integers and no leading zeroes. Drafts and GitHub pre-releases do not publish to npm. Release-candidate tags and other tag formats are rejected. Pushing a tag alone does not publish a package.
+
+The workflow checks out the commit associated with the release event. The tag supplies the npm version: for example, `v0.0.3` publishes `subharness@0.0.3`. The workflow sets that version in its temporary checkout before building and testing. It does not commit a version bump or change the tag. The version in a development checkout therefore need not match the latest registry release.
+
+One GitHub-hosted job installs the frozen pnpm dependencies, builds the SDK, checks TypeScript, runs the behavioral tests with bounded concurrency, and verifies the package in a clean consumer. Setting `SUBHARNESS_PACK_DESTINATION` to an absolute directory when running `pnpm run check:package` retains the verified tarball there; temporary consumer files are still removed. The workflow publishes that exact tarball to npm with public access and the `latest` tag. Failed checks prevent publication. An existing npm version cannot be overwritten; rerunning an already successful publication fails rather than replacing it. Maintainers publish releases in increasing version order and wait for each release job to finish before publishing another.
+
+Authentication uses npm trusted publishing through GitHub Actions OIDC, without an `NPM_TOKEN` secret. In the npm settings for `subharness`, the GitHub Actions trusted publisher must use organization `vercel-labs`, repository `subharness`, and workflow filename `release.yml`, with no environment name. Direct `npm publish` must be enabled in its allowed actions. The workflow requires `contents: read` and `id-token: write` permissions. Provenance is disabled while the source repository is internal, because npm provenance requires a public source repository.
+
+To release, choose a new stable tag on `main` that includes this workflow, enter the release notes, leave the GitHub pre-release option unchecked, and publish the GitHub release. The corresponding Actions run reports whether npm publication succeeded. No separate version-bump commit or release-candidate channel is required.
+
 ## License
 
 The current source checkout and packages built from it are distributed under the Apache License, Version 2.0. The already-published `subharness@0.0.1` registry release remains under the MIT license. The root [LICENSE](../LICENSE) contains the complete Apache License text and is included in packages built from this source.