Release: tag-triggered PyPI publish via Trusted Publishing

Publication plan phase 4.  Pushing a v* tag builds with uv and
publishes to PyPI through OIDC (no stored tokens); the workflow
refuses if the tag doesn't match the pyproject version.  The
release ritual — notes, version bump, lock refresh, gates, tag —
is documented in docs/releasing.md.

Test Suite Status: Unknown
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: physicsrob

.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    # Trusted Publishing (OIDC): PyPI is configured to accept publishes
+    # from this repo + workflow + environment; no token is stored anywhere.
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Check tag matches project version
+        run: |
+          V=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "v$V" != "$GITHUB_REF_NAME" ]; then
+            echo "pyproject.toml version $V does not match tag $GITHUB_REF_NAME" >&2
+            exit 1
+          fi
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

docs/releasing.md

@@ -0,0 +1,43 @@
+# Releasing torchwright
+
+Versioning is SemVer, currently 0.x: breaking changes are allowed and land
+on minor bumps (`0.1.0` → `0.2.0`); fixes land on patch bumps.  The version
+in `pyproject.toml` is the single source of truth.
+
+A release is a commit on `main` plus a matching tag.  Pushing the tag
+triggers `.github/workflows/release.yml`, which rebuilds the package and
+publishes it to PyPI via Trusted Publishing (OIDC — no stored tokens; the
+`v*` tag must match the pyproject version or the workflow refuses).
+
+## The ritual
+
+1. **Finalize the notes.**  In `RELEASE_NOTES.md`, retitle the
+   `# Unreleased` section to the version and date
+   (`# 0.2.0 — 2026-08-01`), and start a fresh empty `# Unreleased`
+   above it.
+2. **Bump the version** in `pyproject.toml`.
+3. **Refresh the locks.**  `make modal-lock` (the standalone lock records
+   torchwright's own version), and `uv lock` at the umbrella root.
+4. **Gate.**  `make lint` and `make test` must pass.
+5. **Commit and push** (`Release 0.2.0`), wait for CI to go green on
+   `main`.
+6. **Tag and push the tag:**
+
+       git tag v0.2.0
+       git push origin v0.2.0
+
+7. **Verify:** the Release workflow run succeeds and
+   https://pypi.org/project/torchwright/ shows the new version.
+
+Optionally create a GitHub Release from the tag afterwards
+(`gh release create v0.2.0 --notes "..."`), pasting the version's
+section from `RELEASE_NOTES.md`.
+
+## One-time setup (already done / do once)
+
+- PyPI → account → Publishing → add a (pending) publisher:
+  project `torchwright`, owner `physicsrob`, repository `torchwright`,
+  workflow `release.yml`, environment `pypi`.
+- The `pypi` environment exists in the GitHub repo (Settings →
+  Environments); the workflow's `environment: pypi` line binds publishes
+  to it.