docs: refresh PyPI install guidance

Make PyPI the default public install path, document the active Trusted Publishing release flow, and update the distribution policy guard test.

Tests: ruff check src/ tests/; python3 -m pytest tests/test_distribution_policy.py tests/test_versioning.py -q -p no:cacheprovider; python3 -m pytest -q -p no:cacheprovider

Author: saagpatel

CHANGELOG.md

@@ -8,6 +8,8 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ## [Unreleased]
 
 ### Changed
+- Updated public install documentation now that `github-repo-auditor` is live on
+  PyPI.
 - Added a manual PyPI Trusted Publishing workflow that builds a release tag and
   publishes from a protected `pypi` environment after PyPI is configured.
 - Made PyPI publishing explicitly opt-in while keeping GitHub Releases as the supported public distribution path.

README.md

@@ -138,7 +138,16 @@ Treat campaign/writeback, GitHub Projects, Notion sync, catalog overrides, score
 
 ### Installation
 
-The package is published as GitHub release artifacts today. PyPI/package-index publishing is not active yet, so registry commands like `pip install github-repo-auditor` are not the recommended public path. See [docs/distribution.md](docs/distribution.md) for the current distribution policy.
+The package is published on PyPI and through GitHub Releases. For normal CLI use,
+install it as an isolated tool:
+
+```bash
+# uv (recommended)
+uv tool install github-repo-auditor
+
+# pipx
+pipx install github-repo-auditor
+```
 
 Fastest no-clone path:
 
@@ -148,13 +157,10 @@ chmod +x audit.pyz
 ./audit.pyz --help
 ```
 
-Install from the public GitHub source:
+Install from the public GitHub source when you want the latest unreleased code:
 
 ```bash
-# uv (recommended)
 uv tool install 'git+https://github.com/saagpatel/GithubRepoAuditor.git'
-
-# pipx
 pipx install 'git+https://github.com/saagpatel/GithubRepoAuditor.git'
 
 # local editable clone
@@ -165,11 +171,12 @@ pip install -e ".[config]"
 
 The self-contained `.pyz` binary is also available from the
 [GitHub Releases](https://github.com/saagpatel/GithubRepoAuditor/releases) page.
+See [docs/distribution.md](docs/distribution.md) for the release and publishing policy.
 
 For the local web UI, install the `[serve]` extra from source:
 
 ```bash
-uv tool install 'git+https://github.com/saagpatel/GithubRepoAuditor.git#egg=github-repo-auditor[serve]'
+pip install "github-repo-auditor[serve]"
 # or from a clone: pip install -e ".[serve]"
 ```
 

docs/distribution.md

@@ -1,9 +1,16 @@
 # Distribution
 
-GitHub Repo Auditor is public and currently distributed through GitHub Releases.
+GitHub Repo Auditor is public and distributed through PyPI and GitHub Releases.
 
 ## Current Public Path
 
+Use PyPI for the normal CLI install:
+
+```bash
+uv tool install github-repo-auditor
+pipx install github-repo-auditor
+```
+
 Use the latest release binary when you want the fastest no-clone install:
 
 ```bash
@@ -12,7 +19,7 @@ chmod +x audit.pyz
 ./audit.pyz --help
 ```
 
-Use the public GitHub source when you want an isolated tool install:
+Use the public GitHub source when you want the latest unreleased code:
 
 ```bash
 uv tool install 'git+https://github.com/saagpatel/GithubRepoAuditor.git'
@@ -21,33 +28,30 @@ pipx install 'git+https://github.com/saagpatel/GithubRepoAuditor.git'
 
 ## PyPI Status
 
-PyPI publishing is not active yet. The package name `github-repo-auditor` was
-available when checked during the public-readiness pass on 2026-05-18, but that
-can change and should be rechecked immediately before first publication.
+PyPI publishing is active for `github-repo-auditor`.
 
-The repository is prepared for a future PyPI release:
+The repository uses GitHub Actions Trusted Publishing:
 
 - package metadata lives in `pyproject.toml`
 - `make build` creates the wheel and source distribution
 - `make dist-check` runs `twine check`
 - `scripts/release.sh` builds and checks artifacts by default
-- `scripts/release.sh --publish-pypi` is the only script path that uploads to PyPI
+- `scripts/release.sh --publish-pypi` remains an explicit local fallback only
 - `.github/workflows/pypi.yml` is a manual Trusted Publishing workflow for a
   release tag, using the `pypi` environment and short-lived OIDC credentials
 
-## Activation Checklist
+## Release Checklist
 
-Before the first PyPI release:
+For a normal public release:
 
-1. Recheck that the `github-repo-auditor` PyPI name is still available.
-2. Configure PyPI Trusted Publishing for owner `saagpatel`, repository
-   `GithubRepoAuditor`, workflow `pypi.yml`, and environment `pypi`.
-3. Protect the GitHub `pypi` environment so publishing requires intentional
-   approval.
-4. Run the standard and distribution gates from [release-gates.md](release-gates.md).
-5. Open **Actions -> Publish to PyPI -> Run workflow** and enter the release tag,
-   for example `v0.1.1`.
-6. Smoke-test `pipx install github-repo-auditor` or `uv tool install github-repo-auditor`.
+1. Run the standard and distribution gates from [release-gates.md](release-gates.md).
+2. Create a PEP 440-compatible `v*` tag from the verified `main` commit.
+3. Wait for the GitHub Release workflow to publish the wheel, source distribution,
+   and `audit.pyz` assets.
+4. Smoke-test the GitHub Release `audit.pyz`.
+5. Open **Actions -> Publish to PyPI -> Run workflow** and enter the same release
+   tag, for example `v0.1.3`.
+6. Approve the protected `pypi` environment.
+7. Smoke-test `pipx install github-repo-auditor` or `uv tool install github-repo-auditor`.
 
-Until that checklist is complete, GitHub Releases remain the supported public
-distribution channel.
+GitHub Releases and PyPI should always publish the same tag.

tests/test_distribution_policy.py

@@ -35,8 +35,10 @@ def test_distribution_docs_name_supported_public_channel() -> None:
     release_gates = (ROOT / "docs" / "release-gates.md").read_text()
     workflows_readme = (ROOT / ".github" / "workflows" / "README.md").read_text()
 
-    assert "GitHub Releases remain the supported public" in distribution_doc
-    assert "PyPI publishing is not active yet" in distribution_doc
+    assert "distributed through PyPI and GitHub Releases" in distribution_doc
+    assert "PyPI publishing is active" in distribution_doc
+    assert "uv tool install github-repo-auditor" in readme
+    assert "pipx install github-repo-auditor" in readme
     assert "docs/distribution.md" in readme
     assert "scripts/release.sh --publish-pypi" in release_gates
     assert "pypi.yml" in workflows_readme