Publish and verify the first v0.1 release

[hellices]

Goal

Publish the first real v0.1 release and prove that users can install, verify, start, and remove korvid through the documented paths. Validate the real external supply-chain boundary rather than treating the existing workflow as proven.

Assessment

The package is already versioned 0.1.0, the full gate is green, Windows compatibility issue #173 was completed by #184, and the release workflow already builds once, verifies metadata, creates SBOMs and checksums, attests artifacts, stages a draft GitHub release, publishes with PyPI OIDC, and promotes the same bytes.

The remaining release blockers are concrete:

• no PyPI project or GitHub release exists;
• no protected release environment exists;
• no immutable v* tag ruleset exists;
• the workflow has no non-publishing dry-run entry point;
• online wheel smoke coverage is Ubuntu/base-only rather than the supported OS, Python, and optional-extra matrix;
• installation, state locations, recovery, and post-publication verification are not yet an operator runbook.

A demo mode will not be invented solely for packaging. Runtime startup is already covered by integration/UI tests; release-artifact smoke will verify import, --help, --version, optional-extra behavior, and clean uninstall. Because v0.1.0 has no prior PyPI version, a real cross-version upgrade cannot be demonstrated until the next release; v0.1.0 will instead verify package-manager reinstall/extra expansion and document that limitation honestly. Package uninstall must not silently delete user-owned config, keyring entries, audit logs, or exports; the runbook will document all locations and explicit cleanup.

Approved approach

1. Land a focused release-hardening PR:
   • add a main-only workflow_dispatch dry run that executes every reversible build, audit, smoke, offline-bundle, collection, and attestation job but cannot stage or publish a release;
   • expand clean-wheel smoke tests across Linux, macOS, Windows, Python 3.11-3.13, and base/agent/mcp/all variants without weakening the existing offline bundle matrix;
   • expose korvid --version;
   • add a concise release runbook covering external prerequisites, dry run, tag creation, approval, partial-failure recovery, verification, uninstall, retained user data, and rollback limitations.
2. Configure external trust before tagging:
   • immutable protected v* tags restricted to the release maintainer;
   • protected release environment limited to protected tags and requiring maintainer approval;
   • exact PyPI Trusted Publisher binding to hellices/korvid, .github/workflows/release.yml, environment release.
3. Run and inspect the non-publishing dry run.
4. Create and push annotated tag v0.1.0 at the verified main commit.
5. Approve publication only after the pre-publication jobs and staged draft assets are verified.
6. Verify PyPI, GitHub release assets, checksums, attestations, install variants, optional-extra behavior, package-manager reinstall/extra expansion, uninstall, and documented retained-state behavior.

Acceptance criteria

• korvid==0.1.0 is installable from PyPI.
• The matching non-draft GitHub release contains the exact promoted wheel, sdist, checksums, SBOM, provenance attestations, metadata, and documented offline bundles.
• gh attestation verify and checksum verification succeed on downloaded artifacts.
• The release dry run succeeds without creating a tag, GitHub release, or PyPI project/version.
• Clean built-wheel smoke tests pass on Linux, macOS, and Windows with Python 3.11, 3.12, and 3.13 for base, agent, mcp, and all.
• Optional extras fail or degrade exactly as documented when absent and are importable when installed.
• korvid --help and korvid --version work from the built and published wheel.
• Uninstall removes the package and console entry point; retained user-owned config, credentials, audit logs, saved logs, and payload exports are documented with explicit cleanup locations.
• README installation and release sections describe current reality after publication and state the tested platform matrix.
• The release runbook records external administrator prerequisites, irreversible steps, and recovery paths for partial publication.
• The first-release limitation on true cross-version upgrade testing is explicit; the real upgrade path becomes a required check for the next version.

Out of scope

• A native single-file executable.
• Homebrew, Krew, or additional package managers before PyPI/GitHub publication is proven.
• A new demo/canned-data runtime mode solely for release smoke testing.
• Automatic deletion of user-owned configuration, credentials, audit logs, or exports during package uninstall.
• Claiming a cross-version PyPI upgrade before a previous PyPI version exists.

[hellices]

Assessment complete. Proceeding with the focused release-hardening path above. This keeps the current v0.1 scope, removes stale #173 assumptions after #184, and rejects two low-value shortcuts: a tag-first publication with no dry run, and a release-only demo mode. External trust configuration and the irreversible tag remain gated until the dry run and review loop are green.