# Releasing `@sakiv/sagent`

## One-time npm/GitHub setup

1. Confirm the npm scope/package is `@sakiv/sagent` and the account has publish rights.
2. Prefer npm Trusted Publishing: configure npm to trust repository `sakiv-io/sagent` and workflow `.github/workflows/publish.yml`.
3. Create a protected GitHub Environment named `npm` with required reviewer approval. This is the explicit human gate immediately before publish.
4. If Trusted Publishing is unavailable, add an environment secret named `NPM_TOKEN` with publish-only scope. Never place it in repository files.
5. Require the CI workflow on `main` before releases.

## Release

1. Update `package.json` using semantic versioning and commit it through review.
2. Run:

   ```bash
   bun install --frozen-lockfile
   bun run verify
   bun run verify:package
   bun run smoke:package
   ```

3. Dispatch **Publish npm package** on the intended commit with confirmation `PUBLISH`. The tag input is optional. A GitHub Release also still works if `v<package-version>` already exists.
4. Approve the protected `npm` environment after reviewing the exact commit, version, CI results, and packed file list.
5. The workflow refuses an existing npm version, rebuilds and tests, then publishes. Provenance is enabled only when the GitHub repository is public; private repositories publish with `--provenance=false` because Sigstore rejects private Actions sources. After npm succeeds it creates annotated tag `v<package-version>` on that commit if it is missing. A pre-existing tag must already point at the same commit. It uploads the tarball plus SHA-256 checksum.
6. Verify:

   ```bash
   npm view @sakiv/sagent version
   pi install npm:@sakiv/sagent
   ```

## Rollback

Published npm versions are immutable. For a defective release:

1. `npm deprecate @sakiv/sagent@<version> "Reason and fixed version"`
2. Fix forward and publish a new patch version.
3. Update the GitHub Release with the advisory.
4. Unpublish only when npm policy permits and the security/legal impact requires it; prefer deprecation and a fixed release.

The first public publish requires separate explicit user confirmation after E3 approval. Preparing or merging this workflow is not authorization to publish.