chore(release): operationalize PyPI publishing — bump harbor, smoke gates, docs

[szjanikowski]

Summary

What started as a routine harbor 0.4 → 0.6 bump uncovered a chain of issues in the just-merged PyPI publish pipeline (#36, #37) that were only visible when actually trying to install nasde-toolkit from a clean environment. This PR fixes them all and hardens the release flow so we don't repeat the experience.

What's in this PR

Commit	Why
chore(deps): bump harbor 0.4 → 0.6, refresh opik to 2.0.22	Latest harbor (0.6.4) and opik (2.0.22). Side benefit: pulls in supabase 2.29.0 instead of broken 2.28.3 (see below).
ci(publish): make TestPyPI uploads idempotent (skip-existing)	TestPyPI rejects re-uploads of the same filename. Two consecutive workflow_dispatch runs producing the same devN hit 400 File already exists. skip-existing: true makes re-runs harmless.
fix(runner): adapt to JobStats field rename in harbor 0.6	Harbor 0.6 renamed n_trials → n_completed_trials and n_errors → n_errored_trials on top-level JobStats. Our _print_job_summary crashed after a successful trial. Caught only by an end-to-end smoke test (claude-vanilla on python-gilded-rose with --with-opik).
fix(deps): pin supabase>=2.29.0,<3 to avoid broken transitive wheels	Two upstream releases (supabase 2.28.3 and 3.0.0a1) ship wheels missing the _async/ and _sync/ subpackages, which causes nasde --version to fail at import. Constraint pins us within healthy 2.x.
ci(publish): add fresh-install smoke tests + weekly canary	After every TestPyPI publish (and PyPI publish on tag push), spin up a clean venv, install the just-published version, and run nasde --version + --help. Weekly Monday cron catches transitive-dep breakage between releases.
ci(publish): linear release flow with TestPyPI gate before PyPI	Restructured the workflow so publish-pypi is gated by a successful smoke test on TestPyPI. Previously the PyPI smoke ran after publish — too late to prevent a broken release. Renamed dispatch input test_pypi → publish_to_prod (default false). Added "tag must be on main" guard on PyPI publish.
docs(releasing): rewrite for automated publish.yml flow	RELEASING.md and ci-setup.md still described a manual gh release create flow with "do not publish to PyPI" warnings. Rewritten for the automated flow with a recovery table for the failure modes hit during this PR's verification.

The release flow after this PR

git tag vX.Y.Z && git push origin vX.Y.Z
  └─ publish.yml automatically:
       quality-gate → build → publish-testpypi → smoke-test-testpypi
                                                       │ ← GATE
                                                       ▼
                                                  publish-pypi
                                                  (verify tag on main, create GH Release)
                                                       │
                                                       ▼
                                                  smoke-test-pypi

Manual TestPyPI dry-run from any branch (no tag needed):

gh workflow run publish.yml --ref <branch>

Disaster recovery (PyPI publish without a tag):

gh workflow run publish.yml --ref main --field publish_to_prod=true

Weekly canary on Monday 09:00 UTC re-runs the TestPyPI flow — catches transitive-dep breakage between releases.

Test plan

• uv run pytest — 147 passed (24 in test_update_check.py from feat: PyPI publishing + in-CLI update notifier #36)
• uv run ruff check / ruff format --check / mypy — all clean
• uv run nasde --version and CI smoke variants work locally
• uv build produces wheel + sdist with correct version (0.3.1.devN)
• End-to-end benchmark (nasde run --variant claude-vanilla --tasks python-gilded-rose-polymorphism --with-opik -C examples/refactoring-skill) completed successfully: trial ran, assessment eval scored 71/100, 7 feedback scores uploaded to Opik
• TestPyPI clean install — verified 0.3.1.dev5 resolves correctly with harbor 0.6.5, opik 2.0.23, supabase 2.30.0; both nasde --version and nasde --help work
• Linear flow verified — manual dispatch with publish_to_prod=false (default) correctly skips publish-pypi and smoke-test-pypi
• After merge: tag the next release (likely v0.3.1) to verify the full tag-push → PyPI flow end-to-end

Related

• Builds on feat: PyPI publishing + in-CLI update notifier #36 (initial PyPI publish workflow) and fix(build): drop local-version segment from hatch-vcs output #37 (hatch-vcs local_scheme fix).
• The README install-instruction migration (uv tool install nasde-toolkit instead of git-tag pinning) remains intentionally out of scope — it lands in PR2 after the first real PyPI release exists, to avoid pointing users at a name that 404s.