docs: polish public project surface

.github/workflows/README.md

@@ -35,7 +35,9 @@ environment `pypi`.
 
 ## `audit.yml` — Manual Automated Audit
 
-Runs manually via `workflow_dispatch`. The automatic weekly schedule is disabled while the repository remains private to avoid recurring GitHub Actions billing.
+Runs manually via `workflow_dispatch`. No automatic weekly schedule is enabled; this
+keeps public CI usage intentional and avoids opening or updating scheduled handoff
+issues unless an operator starts the workflow.
 
 Steps:
 1. Install the package with config support.

CHANGELOG.md

@@ -8,6 +8,10 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 ## [Unreleased]
 
 ### Changed
+- Replaced placeholder README badges with live CI, PyPI, release, Python, and
+  license badges for the public repository.
+- Refreshed public contributor, security, release-gate, and workflow docs now
+  that PyPI publishing is active.
 - 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

CONTRIBUTING.md

@@ -5,7 +5,7 @@ Thank you for your interest in contributing. This guide covers how to set up a l
 ## Prerequisites
 
 - **Python 3.11 or later** — the codebase uses `match` statements, `X | Y` union syntax, and other 3.11+ features.
-- **A GitHub Personal Access Token** — required to audit private repos and avoid rate limits. Create one at <https://github.com/settings/tokens> with `repo` and `read:org` scopes.
+- **A GitHub Personal Access Token** — optional for public-only audits, but useful for private repos, organization metadata, and higher rate limits. Create one at <https://github.com/settings/tokens> with the narrowest scopes needed for the audit you plan to run.
 - **Git** — standard installation, used for shallow cloning during audits.
 
 ## Local Setup
@@ -18,15 +18,15 @@ cd GithubRepoAuditor
 # Install all runtime + dev dependencies
 make install-dev
 
-# Copy the environment template and fill in your token
+# Copy the environment template if you need authenticated audit runs
 cp .env.example .env
-# Edit .env — at minimum set GITHUB_TOKEN=<your token>
+# Edit .env and set GITHUB_TOKEN=<your token>
 ```
 
 If you do not use `make`, the equivalent pip command is:
 
 ```bash
-python3 -m pip install -r requirements.txt pytest ruff mypy
+python3 -m pip install -e ".[dev,config]"
 ```
 
 ## Running Tests
@@ -171,4 +171,4 @@ Before opening a PR, verify:
 
 ## Questions
 
-Open an issue or start a discussion on GitHub. Please include the output of `python3 -m src.cli --help` and your Python version (`python3 --version`) when reporting bugs.
+Open an issue on GitHub. Please include the output of `audit --help` and your Python version (`python3 --version`) when reporting bugs.

README.md

@@ -1,6 +1,10 @@
 # GitHub Repo Auditor
 
-[![Python](https://img.shields.io/badge/Python-%233776ab?style=flat-square&logo=python)](#) [![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](#) [![Tests](https://img.shields.io/badge/tests-covered-brightgreen?style=flat-square)](#)
+[![CI](https://github.com/saagpatel/GithubRepoAuditor/actions/workflows/ci.yml/badge.svg)](https://github.com/saagpatel/GithubRepoAuditor/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/github-repo-auditor.svg)](https://pypi.org/project/github-repo-auditor/)
+[![Python](https://img.shields.io/pypi/pyversions/github-repo-auditor.svg)](https://pypi.org/project/github-repo-auditor/)
+[![Release](https://img.shields.io/github/v/release/saagpatel/GithubRepoAuditor?display_name=tag)](https://github.com/saagpatel/GithubRepoAuditor/releases/latest)
+[![License](https://img.shields.io/github/license/saagpatel/GithubRepoAuditor.svg)](LICENSE)
 
 > Know the truth about every project you've ever started — because `git log` across 100 repos doesn't tell you which ones are worth finishing.
 
@@ -112,6 +116,8 @@ Treat campaign/writeback, GitHub Projects, Notion sync, catalog overrides, score
 - Release gates: [docs/release-gates.md](docs/release-gates.md)
 - Distribution status: [docs/distribution.md](docs/distribution.md)
 - Project history: [docs/project-history.md](docs/project-history.md)
+- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
+- Security policy: [SECURITY.md](SECURITY.md)
 
 ## Features
 

SECURITY.md

@@ -22,4 +22,4 @@ We aim to acknowledge reports within 48 hours and resolve confirmed vulnerabilit
 - **GitHub token handling**: tokens are passed via env var, never logged or stored on disk
 - **Notion API token**: same handling as above
 - **Subprocess git clone**: uses authenticated URLs that are cleaned from env after use
-- **Output files**: reports written to local  directory only
+- **Output files**: reports are written to the local `output/` directory only

docs/audit-serve.md

@@ -14,10 +14,16 @@ The web UI dependencies are in the `[serve]` extra and are not installed by defa
 # editable / dev install
 pip install -e '.[serve]'
 
-# or via uv tool from the public GitHub source
+# from PyPI
+pip install 'github-repo-auditor[serve]'
+
+# or via pipx from PyPI
+pipx install 'github-repo-auditor[serve]'
+
+# or via uv tool from the public GitHub source for unreleased code
 uv tool install 'git+https://github.com/saagpatel/GithubRepoAuditor.git#egg=github-repo-auditor[serve]'
 
-# or via pipx from the public GitHub source
+# or via pipx from the public GitHub source for unreleased code
 pipx install 'git+https://github.com/saagpatel/GithubRepoAuditor.git#egg=github-repo-auditor[serve]'
 ```
 

docs/release-gates.md

@@ -153,19 +153,20 @@ All three must pass before tagging:
   and non-PEP 440 tag suffixes can break the release build.
 - Public hardening releases should use patch versions (`v0.1.x`). Feature releases
   should move the minor version (`v0.2.0`, `v0.3.0`, and so on).
-- PyPI upload is explicit opt-in and not part of the current public install story.
-  `scripts/release.sh` builds and checks artifacts by default; it uploads only when
-  run as `scripts/release.sh --publish-pypi` with valid credentials. CI only checks
-  and uploads to GitHub Releases.
-- After PyPI Trusted Publishing is configured, prefer the manual `Publish to PyPI`
-  workflow over local token-based uploads. It builds the release tag in one job and
-  publishes from a separate `pypi` environment job with `id-token: write`.
+- PyPI publishing is active through the manual `Publish to PyPI` workflow. Keep
+  GitHub Releases and PyPI on the same tag for each public release.
+- `scripts/release.sh` builds and checks artifacts by default.
+  `scripts/release.sh --publish-pypi` remains an explicit local fallback only;
+  prefer Trusted Publishing over token-based local uploads.
+- The manual `Publish to PyPI` workflow builds the release tag in one job and
+  publishes from a separate protected `pypi` environment job with
+  `id-token: write`.
 - The `[serve]` extra is not bundled in the shiv binary by default. Users who need the
-  web UI should install from the GitHub source with the `[serve]` extra or use a local
-  editable clone.
+  web UI should install `github-repo-auditor[serve]` from PyPI or use a local editable
+  clone.
 
-See [distribution.md](distribution.md) for the public distribution policy and the
-remaining PyPI activation checklist.
+See [distribution.md](distribution.md) for the public distribution policy and release
+checklist.
 
 ## Web UI Gate (scope: audit serve)
 

tests/test_distribution_policy.py

@@ -39,7 +39,12 @@ def test_distribution_docs_name_supported_public_channel() -> None:
     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 "github.com/saagpatel/GithubRepoAuditor/actions/workflows/ci.yml/badge.svg" in readme
+    assert "img.shields.io/pypi/v/github-repo-auditor.svg" in readme
     assert "docs/distribution.md" in readme
+    assert "PyPI publishing is active through the manual" in release_gates
+    assert "not part of the current public install story" not in release_gates
+    assert "remaining PyPI activation checklist" not in release_gates
     assert "scripts/release.sh --publish-pypi" in release_gates
     assert "pypi.yml" in workflows_readme
     assert "id-token: write" in workflows_readme