saagpatel · saagpatel · May 18, 2026 · May 18, 2026 · May 18, 2026
diff --git a/.github/workflows/README.md b/.github/workflows/README.md
@@ -2,9 +2,11 @@
 
 ## `ci.yml` — Continuous Integration
 
-Runs on code-bearing pushes and pull requests to `main`. Documentation-only changes are ignored to avoid spending private Actions minutes on non-code updates. Superseded runs are canceled automatically.
+Runs on all pushes and pull requests to `main`. Superseded runs are canceled
+automatically.
 
-While this repository remains private during the GitHub Actions billing mitigation period, CI runs the canonical Python 3.11 lane only. Restore the broader Python version matrix after either making the repository public or explicitly accepting the private-runner cost.
+CI runs the canonical Python 3.11 lane. This includes documentation-only pull requests
+because branch protection requires the `test (3.11)` check before merge.
 
 Steps:
 1. Install dependencies via `pip install -e ".[dev]"`

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -2,16 +2,8 @@ name: CI
 on:
   push:
     branches: [main]
-    paths-ignore:
-      - "*.md"
-      - "docs/**"
-      - ".github/workflows/README.md"
   pull_request:
     branches: [main]
-    paths-ignore:
-      - "*.md"
-      - "docs/**"
-      - ".github/workflows/README.md"
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}

diff --git a/README.md b/README.md
@@ -23,7 +23,7 @@ Today it:
 - scores repos on dual axes, classifies them into useful tiers, and surfaces quick wins
 - generates aligned JSON, Markdown, HTML, workbook, review-pack, and control-center outputs from the same audit facts
 - writes a report-only weekly command-center digest beside the control-center artifact so paused automation can consume one bounded summary instead of stale notes
-- generates a canonical workspace-level portfolio truth snapshot for `/Users/d/Projects` and derives the shared registry/report compatibility artifacts from it
+- generates a canonical workspace-level portfolio truth snapshot for a local projects folder and derives the shared registry/report compatibility artifacts from it
 - preserves historical state in SQLite so the operator loop can show change, regression, recovery, and follow-through
 - keeps the workbook and `--control-center` as the main day-to-day operating surfaces
 
@@ -100,6 +100,7 @@ Treat campaign/writeback, GitHub Projects, Notion sync, catalog overrides, score
 
 ## Demo and Guides
 
+- Safe demo path: run `make demo` after a local clone to generate sample artifacts from the committed fixture without a GitHub token.
 - Demo fixture: [fixtures/demo/sample-report.json](fixtures/demo/sample-report.json)
 - Product modes: [docs/modes.md](docs/modes.md)
 - Web UI operator guide: [docs/audit-serve.md](docs/audit-serve.md)
@@ -109,6 +110,7 @@ Treat campaign/writeback, GitHub Projects, Notion sync, catalog overrides, score
 - Workbook tour: [docs/workbook-tour.md](docs/workbook-tour.md)
 - Extending analyzers: [docs/extending-analyzers.md](docs/extending-analyzers.md)
 - Release gates: [docs/release-gates.md](docs/release-gates.md)
+- Historical implementation notes: [docs/plans/](docs/plans/) records prior roadmap and closeout context. Treat current product docs and code as authoritative.
 
 ## Features
 
@@ -135,35 +137,57 @@ Treat campaign/writeback, GitHub Projects, Notion sync, catalog overrides, score
 
 ### Installation
 
-The fastest paths — no git clone needed:
+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.
+
+Fastest no-clone path:
+
+```bash
+curl -LO https://github.com/saagpatel/GithubRepoAuditor/releases/latest/download/audit.pyz
+chmod +x audit.pyz
+./audit.pyz --help
+```
+
+Install from the public GitHub source:
 
 ```bash
 # uv (recommended)
-uv tool install githubrepoauditor
+uv tool install 'git+https://github.com/saagpatel/GithubRepoAuditor.git'
 
 # pipx
-pipx install githubrepoauditor
+pipx install 'git+https://github.com/saagpatel/GithubRepoAuditor.git'
 
-# pip
-pip install githubrepoauditor
+# local editable clone
+git clone https://github.com/saagpatel/GithubRepoAuditor.git
+cd GithubRepoAuditor
+pip install -e ".[config]"
 ```
 
-**No-Python path** — download the self-contained `.pyz` binary from the
-[GitHub Releases](https://github.com/saagpatel/GithubRepoAuditor/releases) page:
+The self-contained `.pyz` binary is also available from the
+[GitHub Releases](https://github.com/saagpatel/GithubRepoAuditor/releases) page.
+
+For the local web UI, install the `[serve]` extra from source:
 
 ```bash
-curl -LO https://github.com/saagpatel/GithubRepoAuditor/releases/latest/download/audit.pyz
-chmod +x audit.pyz
-./audit.pyz --help
+uv tool install 'git+https://github.com/saagpatel/GithubRepoAuditor.git#egg=github-repo-auditor[serve]'
+# or from a clone: pip install -e ".[serve]"
 ```
 
-For the local web UI add the `[serve]` extra:
+### Try the safe demo
+
+The demo uses committed fixture data and writes only to `output/demo/`.
 
 ```bash
-uv tool install 'githubrepoauditor[serve]'
-# or: pip install 'githubrepoauditor[serve]'
+git clone https://github.com/saagpatel/GithubRepoAuditor.git
+cd GithubRepoAuditor
+pip install -e ".[config]"
+make demo
 ```
 
+Expected outputs include `output/demo/demo-report.json`,
+`output/demo/demo-workbook.xlsx`, `output/demo/dashboard-*.html`,
+`output/demo/operator-control-center-demo.json`, and
+`output/demo/operator-control-center-demo.md`.
+
 ### Quick start (subcommand form)
 
 ```bash
@@ -284,7 +308,7 @@ Before normal runs start, the CLI now performs a shared preflight that checks co
 
 For day-to-day operations, `--control-center` is now the clean read-only entrypoint. It reuses the latest report, review state, campaign history, governance drift, and setup health to build one shared operator queue without running a new audit or mutating any external system.
 
-The portfolio truth layer now has its own dedicated generation path. `--portfolio-truth` scans the broader workspace, produces `output/portfolio-truth-latest.json` plus dated historical truth snapshots, and regenerates `/Users/d/Projects/project-registry.md` and `/Users/d/Projects/PORTFOLIO-AUDIT-REPORT.md` as compatibility outputs from that same truth contract instead of treating either markdown file as canonical.
+The portfolio truth layer now has its own dedicated generation path. `--portfolio-truth` scans the configured local projects workspace, produces `output/portfolio-truth-latest.json` plus dated historical truth snapshots, and regenerates the configured project-registry and portfolio-audit Markdown compatibility outputs from that same truth contract instead of treating either markdown file as canonical.
 
 Phase 104 added a second standalone workspace mode: `--portfolio-context-recovery`. That mode freezes the active/recent weak-context cohort from the live truth snapshot, writes dry-run recovery plan artifacts into `output/`, skips dirty or temporary repos automatically, and can apply bounded minimum-context upgrades plus repo-level catalog seeds before regenerating the truth snapshot and compatibility outputs.
 

diff --git a/docs/architecture.md b/docs/architecture.md
@@ -14,7 +14,7 @@ The weekly packaging seam now has an explicit structured contract, `weekly_story
 
 Phase 107 adds one more bounded read model on top of that same weekly seam: `weekly_command_center_digest_v1` in `src/weekly_command_center.py`. The digest is derived from `weekly_story_v1`, the latest operator summary, and the current portfolio-truth snapshot. It is explicitly report-only and workbook-first. Its job is to give a future weekly loop one canonical digest artifact without creating a second weekly authority or widening automation power.
 
-The portfolio layer now has its own explicit truth contract too. `--portfolio-truth` builds a versioned machine-readable snapshot for the broader `/Users/d/Projects` workspace and treats the legacy markdown registry/report files as derived compatibility surfaces rather than as canonical inputs.
+The portfolio layer now has its own explicit truth contract too. `--portfolio-truth` builds a versioned machine-readable snapshot for the configured local projects workspace and treats the legacy markdown registry/report files as derived compatibility surfaces rather than as canonical inputs.
 
 Phase 104 extends that contract with a minimum-context recovery layer. The truth snapshot now distinguishes `none`, `boilerplate`, `minimum-viable`, `standard`, and `full`, and the workspace recovery workflow writes context only into one primary repo-local file (`CLAUDE.md` first, otherwise `AGENTS.md`) instead of inventing a second mutable database for portfolio context.
 

diff --git a/docs/audit-serve.md b/docs/audit-serve.md
@@ -14,11 +14,11 @@ 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
-uv tool install 'githubrepoauditor[serve]'
+# or via uv tool from the public GitHub source
+uv tool install 'git+https://github.com/saagpatel/GithubRepoAuditor.git#egg=github-repo-auditor[serve]'
 
-# or via pipx
-pipx install 'githubrepoauditor[serve]'
+# or via pipx from the public GitHub source
+pipx install 'git+https://github.com/saagpatel/GithubRepoAuditor.git#egg=github-repo-auditor[serve]'
 ```
 
 If you try to run `audit serve` without the extra installed, the CLI will exit with a

diff --git a/docs/extending-analyzers.md b/docs/extending-analyzers.md
@@ -17,7 +17,7 @@ An analyzer should inspect one aspect of a repo and return:
 
 ## Practical workflow
 
-1. Add the analyzer under [/Users/d/Projects/GithubRepoAuditor/src/analyzers](/Users/d/Projects/GithubRepoAuditor/src/analyzers).
+1. Add the analyzer under `src/analyzers/`.
 2. Make sure it fits the existing result shape used by scoring and report writers.
 3. Add tests for both the analyzer output and any score/report behavior it changes.
 4. Re-run `pytest` and `make workbook-gate` if workbook-facing summaries change.

diff --git a/docs/modes.md b/docs/modes.md
@@ -13,6 +13,16 @@ for the full mapping.
 
 Use this mode when you are setting the system up or coming back after a long gap.
 
+If you only want to see the product surfaces before auditing a real account, run the
+safe fixture demo first:
+
+```bash
+make demo
+```
+
+That writes sample JSON, workbook, HTML, and control-center artifacts to
+`output/demo/` without a GitHub token.
+
 Recommended path:
 
 ```bash
@@ -204,6 +214,7 @@ Each section should answer the same three questions quickly:
 ## Default guidance
 
 - `audit run <user> --doctor` is the recommended first step.
+- A GitHub token is optional for public-only audits, but recommended for private repos, higher rate limits, and any mutation/writeback path.
 - `--excel-mode standard` is the default and recommended workbook path.
 - `audit triage <user> --control-center` is the read-only daily operator entrypoint.
 - `template` workbook mode, scorecards config, catalog config, campaigns, writeback, GitHub Projects, and Notion sync are advanced workflows.

diff --git a/docs/operator-troubleshooting.md b/docs/operator-troubleshooting.md
@@ -1,6 +1,6 @@
 # Operator Troubleshooting
 
-Use this guide when the workflow is failing or a required artifact is missing. For the normal weekly loop, use [weekly-review.md](/Users/d/Projects/GithubRepoAuditor/docs/weekly-review.md). For the high-level product map, use [modes.md](/Users/d/Projects/GithubRepoAuditor/docs/modes.md).
+Use this guide when the workflow is failing or a required artifact is missing. For the normal weekly loop, use [weekly-review.md](weekly-review.md). For the high-level product map, use [modes.md](modes.md).
 
 Start here first:
 

diff --git a/docs/plans/README.md b/docs/plans/README.md
@@ -0,0 +1,14 @@
+# Historical Planning Notes
+
+This folder keeps older roadmap, sprint, handoff, and closeout notes for project history.
+They may reference local operator paths, archived branches, or past workflow decisions.
+
+For current public usage, start with:
+
+- [README.md](../../README.md)
+- [docs/modes.md](../modes.md)
+- [docs/weekly-review.md](../weekly-review.md)
+- [docs/release-gates.md](../release-gates.md)
+
+Treat code, tests, and current product docs as authoritative when they disagree with an
+older plan.
diff --git a/docs/portfolio-context-contract.md b/docs/portfolio-context-contract.md
@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Phase 104 introduced one explicit minimum-context contract for repos in `/Users/d/Projects`.
+Phase 104 introduced one explicit minimum-context contract for repos in the configured local projects workspace.
 
 The goal is not to turn every repo into a full documentation portal. The goal is to make the
 important repos resumable without rediscovery while keeping the truth snapshot derived from

diff --git a/docs/release-gates.md b/docs/release-gates.md
@@ -111,7 +111,7 @@ The following survivors are confirmed equivalent mutants — behavioral tests ca
 
 (1 timeout excluded from denominator; 1 suspicious counted as killed)
 
-## Distribution Gate (scope: PyPI + shiv binary)
+## Distribution Gate (scope: GitHub Release assets)
 
 Run before any public release tag. Requires the `[build]` extra:
 
@@ -146,12 +146,18 @@ All three must pass before tagging:
 
 ### Notes
 
-- The GitHub Actions `release.yml` workflow runs these same steps on every `v*` tag
+- The GitHub Actions `release.yml` workflow runs these same steps on every PEP 440-compatible `v*` tag
   and uploads all three artifacts to the GitHub Release.
-- TWINE upload to PyPI is manual-only (run `scripts/release.sh`); CI only checks and
-  uploads to GitHub Releases.
+- Use tags like `v0.1.0` or `v0.1.1`. Avoid suffix tags such as
+  `v0.1.0-public-baseline`; package version derivation comes from `setuptools-scm`
+  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).
+- TWINE upload to PyPI is manual-only and not part of the current public install
+  story; CI only checks and uploads to GitHub Releases.
 - The `[serve]` extra is not bundled in the shiv binary by default. Users who need the
-  web UI should install via `uv tool install 'githubrepoauditor[serve]'`.
+  web UI should install from the GitHub source with the `[serve]` extra or use a local
+  editable clone.
 
 ## Web UI Gate (scope: audit serve)
 

diff --git a/docs/weekly-review.md b/docs/weekly-review.md
@@ -1,6 +1,6 @@
 # Weekly Review
 
-Use this guide for the normal ongoing operator loop. If you need the broader product map first, start with [modes.md](/Users/d/Projects/GithubRepoAuditor/docs/modes.md). If something is broken, jump to [operator-troubleshooting.md](/Users/d/Projects/GithubRepoAuditor/docs/operator-troubleshooting.md).
+Use this guide for the normal ongoing operator loop. If you need the broader product map first, start with [modes.md](modes.md). If something is broken, jump to [operator-troubleshooting.md](operator-troubleshooting.md).
 
 ## Weekly cadence