docs: anchor portfolio truth docs to canonical snapshot (#66)

Author: saagpatel

README.md

@@ -7,9 +7,9 @@
 [![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.
+> Know the truth about every project you've ever started — because `git log` across a crowded repo portfolio doesn't tell you which ones are worth finishing.
 
-📐 **Case study — [Operator OS: a multi-agent control plane over a 129-repo portfolio](CASE-STUDY.md).** How this auditor's truth layer anchors six local services and two coordinated coding agents (Claude Code + Codex), with real portfolio metrics and a [90-second demo plan](DEMO-PLAN.md).
+📐 **Case study — [Operator OS: a multi-agent control plane over a repo portfolio](CASE-STUDY.md).** How this auditor's truth layer anchors six local services and two coordinated coding agents (Claude Code + Codex), with real portfolio metrics and a [90-second demo plan](DEMO-PLAN.md).
 
 GitHub Repo Auditor is a portfolio audit and operator tool for developers with a lot of repositories. It clones every repo on your GitHub account, runs 12 analyzers across completeness and interest dimensions, assigns letter grades and achievement badges, preserves historical state, and generates actionable dashboards you can actually use to decide what to work on next. Built for developers who ship fast, start often, and need a system to manage the sprawl.
 
@@ -347,6 +347,12 @@ For day-to-day operations, `--control-center` is now the clean read-only entrypo
 
 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.
 
+For current live portfolio counts, query the canonical snapshot instead of copying numbers into handoff or demo docs:
+
+```bash
+jq '{generated_at,total:(.projects|length),counts:.source_summary.attention_state_counts}' output/portfolio-truth-latest.json
+```
+
 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.
 
 Watch mode now uses that same baseline contract in live execution. Each cycle records the requested watch strategy, the chosen mode, and the reason a full refresh was required or an incremental rerun remained safe.

docs/codex-restart-packet.md

@@ -17,6 +17,12 @@ Use JSON when another tool should consume the result:
 python -m src.codex_restart_packet --workspace-root /Users/d/Projects --json
 ```
 
+For the current generated portfolio truth counts, query the canonical snapshot directly:
+
+```sh
+jq '{generated_at,total:(.projects|length),counts:.source_summary.attention_state_counts}' output/portfolio-truth-latest.json
+```
+
 ## What It Decides
 
 - which repos are dirty, off-main, missing upstream, or ahead/behind upstream

docs/demo-proof/2026-06-07/README.md

@@ -19,6 +19,14 @@ the window title `Portfolio Command Center Demo`.
 - Projects: `129`
 - Weekly digest: `output/weekly-command-center-saagpatel-2026-06-03.json`
 
+These values are historical evidence for the screenshot package captured on
+2026-06-07. For current live private portfolio counts, query the canonical
+snapshot instead of reusing these numbers:
+
+```sh
+jq '{generated_at,total:(.projects|length),counts:.source_summary.attention_state_counts}' output/portfolio-truth-latest.json
+```
+
 ## Proof Points
 
 - Portfolio: `129` projects visible in the header and table count.

docs/demo-proof/2026-06-07/RECORDING-CHECKLIST.md

@@ -4,6 +4,14 @@ Use this as the operator checklist for recording the 2026-06-07
 PortfolioCommandCenter demo. It assumes the proof package in this directory and
 the script in `../../../DEMO-SCRIPT.md`.
 
+The numbers below are historical proof values for this captured local package.
+For a new live recording, regenerate the proof package and query the current
+canonical snapshot before writing spoken lines:
+
+```sh
+jq '{generated_at,total:(.projects|length),counts:.source_summary.attention_state_counts}' output/portfolio-truth-latest.json
+```
+
 ## Preflight
 
 - [ ] Run from `/Users/d/Projects/PortfolioCommandCenter`:

docs/demo-proof/2026-06-07/SUMMARY.md

@@ -7,13 +7,20 @@ demonstrated.
 
 Status: passed.
 
-Key proof points:
+Historical proof points from the captured 2026-06-07 run:
 
 - Portfolio tab: 129 projects.
 - Risk + Security tab: 117 scanned repos and 63 with open high/critical alerts.
 - Burndown tab: advisory-grouped fix guidance.
 - Trends tab: risk and high/critical history charts.
 - Weekly Digest tab: current decision ends with `Start with codexkit.`
 
+For current live private portfolio counts, query the canonical generated
+snapshot instead of reusing this historical proof summary:
+
+```sh
+jq '{generated_at,total:(.projects|length),counts:.source_summary.attention_state_counts}' output/portfolio-truth-latest.json
+```
+
 Use `proof-package.json` for the machine-readable claim-to-evidence map and
 `README.md` for the narrative proof summary.

docs/machine-wide-consolidation.md

@@ -21,6 +21,13 @@ The packet combines:
 - archive/dependency/temp exclusions so old cleanup waves do not reappear as
   live work
 
+For current portfolio truth counts, query the canonical generated snapshot
+instead of copying counts into continuation notes:
+
+```sh
+jq '{generated_at,total:(.projects|length),counts:.source_summary.attention_state_counts}' output/portfolio-truth-latest.json
+```
+
 ## Consolidation Policy
 
 1. Start from the packet, not from a raw filesystem scan.
@@ -47,7 +54,7 @@ The packet combines:
 5. Keep restart prompts short. Tell the next session to rerun the packet and
    inspect the live repo state, not to inherit stale chat counts.
 
-## 2026-06-07 Baseline
+## 2026-06-07 Historical Baseline
 
 The first verified packet run after adding the restart surface reported:
 
@@ -76,7 +83,8 @@ The top active working set was:
 12. `PortfolioCommandCenter`
 
 These counts are evidence from one run, not a permanent registry. Rerun the
-packet before making a new decision.
+packet and re-query `output/portfolio-truth-latest.json` before making a new
+decision.
 
 ## Next Strong Lane