# Releasing `@curatogether/pi`

## One-time npm setup

1. Confirm that the `@curatogether` npm organization exists and that the
   publisher has permission to create public packages in it.
2. Decide on a source license. The package is deliberately marked
   `UNLICENSED` until the repository owner makes that legal choice.
3. For the first publish, add an npm automation token as the GitHub Actions
   secret `NPM_TOKEN`. After the package exists, configure npm trusted
   publishing for this repository and the `publish-pi.yml` workflow; the
   workflow already requests the required OIDC permission. npm Trusted
   Publishing works for a private GitHub repository, but public Sigstore
   provenance does not.

## Prepare a release

1. Update `version` in `packages/pi/package.json` using semantic versioning.
2. Pin and review any change to `pi-web-access`; it executes inside the
   controlled researcher process.
3. Run:

   ```bash
   pnpm install --frozen-lockfile
   pnpm --filter @curatogether/pi type-check
   pnpm --filter @curatogether/pi build
   npm pack --dry-run --workspace packages/pi
   ```

4. Inspect the file list. It must contain `dist/`, `skills/`, `README.md`, and
   `RELEASING.md`; it must not contain workspace source packages, credentials,
   environment files, or research data.
5. Commit the version and lockfile and push the commit to `main`. Changes under
   `packages/pi`, `packages/client`, or `packages/domain` trigger the release
   workflow. It rebuilds, inspects, and publishes the package when that exact
   version is not already on npm. If the version already exists, the workflow
   exits successfully without publishing, so every package-content change must
   include a new semantic version.
6. Optionally create the annotated tag `pi-v<version>` and publish a GitHub
   release from exactly that tag. The workflow verifies that the tag and package
   version agree; if the push workflow already published it, the release run
   safely skips the duplicate npm publish. The workflow currently sets
   `NPM_CONFIG_PROVENANCE: false` because the GitHub repository is private. If
   the repository becomes public, change that setting to `true` to publish npm
   provenance.

## Verify after publishing

Use a clean Pi profile or disposable machine:

```bash
pi install npm:@curatogether/pi
pi list
pi update npm:@curatogether/pi
```

Open Pi, confirm `/cura` is available, complete the device flow with a test
account, and run a non-public research cycle. Do not use `/cura publish` during
the smoke test unless the resulting project and full provenance are intended to
be public.