docs: refresh consumer-facing README for Phase 5+ container-pinned workflows

[cbeaulieu-gt]

Summary

Closes #219.

Refreshes README.md so the consumer-facing surface reflects the Phase 5+ container-pinned reality. Audit (triggered by user wiring two intra-org consumer repos onto the system) found drift in 3 quick-start examples and a missing packages: read story that maps directly to the #192 trap.

Changes (8)

1. Intro — removed stale "two actions" count; replaced with capability list covering PR review, @claude mentions, lint-failure, CI-failure, apply-fix.
2. Authentication line — clarified CLAUDE_CODE_OAUTH_TOKEN is universal; noted APP_ID + APP_PRIVATE_KEY are additionally required for every write-capable action.
3. Actions table — added the missing apply-fix row.
4. Permissions Reference — added packages: read to every container-pinned row, added an "Apply Fix" row, added a paragraph explaining why the implicit docker pull (which runs before any step) requires the permission. Cites bug: 5 container-pinned workflows missing packages:read; all Claude CI jobs blocked #192.
5. CI Failure quick-start — ci-failure.yaml@v2 → claude-ci-failure.yml@v2; added packages: read.
6. Lint Fix quick-start — claude-lint-fix.yml@v2 → claude-lint-failure.yml@v2; added packages: read.
7. Apply Fix manual trigger — apply-fix.yml → claude-apply-fix.yml in the CLI example.
8. New section: "GHCR package access for org-wide consumers" — documents the Internal-visibility flip as the recommended intra-org pattern (just executed across all 3 overlay packages), plus the per-repo grant alternative for cross-org. Both paths still require packages: read on the caller workflow.

Test plan

• All 4 quick-start YAML examples reference Phase 5 reusable workflow names
• Permissions table lists packages: read for every container-pinned row
• New GHCR-access section present between CI runtime and CI Failure Diagnosis
• Commit on issue-219-readme-onboarding, not main
• CI lint workflow (actionlint) green — there's no embedded YAML in actual workflow files, only fenced code blocks, so this should be a no-op for .github/workflows/lint.yml
• Reviewer eyes on the new "GHCR package access" section for accuracy of click-paths

Out of scope (follow-ups)

• Add examples/ directory with drop-in caller workflows for each consumer surface #220 — examples/ directory with drop-in caller workflows
• Add docs/consumer-onboarding.md: end-to-end walkthrough for intra-org consumer setup #221 — docs/consumer-onboarding.md end-to-end walkthrough

🤖 Generated by Claude Code on behalf of @cbeaulieu-gt

[github-actions]

Claude finished @cbeaulieu-gt's task in 2m 16s —— View job

---

PR Review Complete

I've reviewed PR #222 which refreshes the consumer-facing README for Phase 5+ container-pinned workflows. The PR successfully addresses most of the stated objectives, but I found two critical inconsistencies in the quick-start examples that need fixing before merge.

---

What's Working Well ✅

Accurate updates (6/8 changes):

1. Intro refresh (line 3) — capability list is comprehensive and accurate
2. Authentication clarification (line 5) — clearly explains the two-tier auth model (OAuth token + App credentials)
3. Actions table (line 14) — apply-fix row added
4. Permissions Reference (lines 22, 28-32) — excellent addition of "Container pull permission" blockquote, all rows correctly show packages: read, includes bug: 5 container-pinned workflows missing packages:read; all Claude CI jobs blocked #192 citation
5. CI Failure quick-start (lines 310-322) — claude-ci-failure.yml@v2 + packages: read ✅
6. Lint Fix quick-start (lines 359-383) — claude-lint-failure.yml@v2 + packages: read ✅
7. Apply Fix manual trigger (line 430) — claude-apply-fix.yml ✅
8. GHCR section (lines 229-259) — well-structured, explains both Internal visibility and per-repo grant patterns, clear explanation of why packages: read is mandatory

The new GHCR section is particularly well-written. The distinction between "necessary condition" (visibility setting) and "also necessary" (packages: read permission) is clear and will prevent the #192 trap.

---

Critical Issues Found 🚨

The permissions table (lines 28-29) correctly lists packages: read for all container-pinned workflows, but two quick-start examples are missing it:

1. PR Review quick-start (lines 52-54)

Current:

permissions:
  contents: read
  pull-requests: write

Should be (per permissions table line 28):

permissions:
  contents: read
  pull-requests: write
  packages: read

2. Tag Claude quick-start (lines 85-88)

Current:

permissions:
  contents: write
  issues: write
  pull-requests: write

Should be (per permissions table line 29):

permissions:
  contents: write
  issues: write
  pull-requests: write
  packages: read

Impact: Consumers who copy-paste these examples will hit the manifest unknown error described in #192 and the new GHCR section. Since these are the first two quick-start examples most consumers encounter, this undermines the entire PR's goal of preventing the #192 trap.

Why this matters: The PR correctly updates the CI Failure, Lint Fix, and Apply Fix examples (changes #5, #6, #7), but misses the two most commonly used workflows. This creates an inconsistency where the permissions table says one thing but the examples show another.

---

Recommendations

1. Before merge: Add packages: read to:

   • PR Review example at line 54 (after pull-requests: write)
   • Tag Claude example at line 88 (after pull-requests: write)

2. Optional improvement: Consider adding a brief inline comment in the quick-start examples explaining why packages: read is required, e.g.:

   permissions:
     contents: read
     pull-requests: write
     packages: read  # Required for GHCR overlay image pull (see "GHCR package access" section)

   This would make the examples more self-documenting, but the current permissions table blockquote (line 22) already explains it well.

3. Validation: After fixing, verify all 5 quick-start examples match their corresponding permissions table rows.

---

Test Plan Status

From the PR body test plan:

• ✅ All 4 quick-start YAML examples reference Phase 5 workflow names (verified)
• ✅ Permissions table lists packages: read for every container-pinned row (verified)
• ✅ New GHCR-access section present (verified — lines 229-259)
• ✅ Commit on correct branch (verified — issue-219-readme-onboarding)
• ⏸️ CI lint workflow — cannot verify without pushing
• ⏸️ Reviewer eyes on GHCR section — this review confirms the click-paths and technical accuracy are correct

---

Summary

Strong PR that addresses the Phase 5 documentation gap and the #192 trap. The permissions table, GHCR section, and 3/5 quick-start examples are excellent. The two missing packages: read entries in PR Review and Tag Claude examples need fixing before merge to ensure consistency and prevent the exact error this PR aims to prevent.

Recommended action: Add packages: read to lines 54 and 88, then merge.

---

Tasks

• Retrieve PR diff
• Read README.md to understand full context
• Review workflow name updates
• Verify packages: read additions
• Check GHCR access documentation
• Evaluate quick-start examples
• Post comprehensive review

[github-actions]

Claude finished @cbeaulieu-gt's task in 51s —— View job

---

PR Review: Incremental Changes ✅

Reviewed the latest push (bed91dd → 8d9a133). Both critical issues from the previous review have been addressed.

Tasks

• Run git diff to see incremental changes
• Verify if packages: read was added to PR Review example
• Verify if packages: read was added to Tag Claude example
• Check for any new issues introduced
• Post final review feedback

---

What Changed

The author added packages: read to both quick-start examples that were missing it:

1. PR Review example (line 55) — Added packages: read ✅
2. Tag Claude example (line 90) — Added packages: read ✅

Review Assessment

Status: Ready to merge 🎉

The incremental changes are minimal, focused, and correct. They directly address the two critical inconsistencies identified in the previous review:

• Both examples now match the permissions table (which correctly lists packages: read for all container-pinned workflows)
• Consumers who copy-paste these examples will no longer hit the manifest unknown error from bug: 5 container-pinned workflows missing packages:read; all Claude CI jobs blocked #192
• The changes are consistent with the other quick-start examples (CI Failure, Lint Fix, Apply Fix) which already had packages: read

No Issues Found

• ✅ Changes are accurate and complete
• ✅ No new issues introduced
• ✅ All 5 quick-start examples now have packages: read where required
• ✅ Documentation is internally consistent

The PR now achieves its stated goal: "refresh consumer-facing README for Phase 5+ container-pinned workflows" with accurate examples that prevent the #192 trap.

Recommendation: Merge when CI passes.