fix: remove README-pypi.md generation dance, point pyproject at README.md

[cmeans-claude-dev]

Summary

Caught during pre-release validation for v0.5.0. From a completely fresh clone:

$ .venv/bin/pip install -e .
...
OSError: Readme file does not exist: README-pypi.md
error: metadata-generation-failed

Root cause

pyproject.toml has pointed at README-pypi.md since commit 2ebc8df ("Strip TOC from PyPI README; exit code 1 on attention-level failures", 2026-03-08, pre-v0.4.0). That commit switched the readme field from "README.md" to {file = "README-pypi.md", content-type = "text/markdown"} and simultaneously added the Generate PyPI README (strip TOC) step to ci.yml / publish.yml. The README-pypi.md file is:

• .gitignored
• generated on-demand by the Generate PyPI README (strip TOC) step in ci.yml (both jobs) and publish.yml

So CI and the PyPI publish pipeline work — they regenerate before building. But any source install path (git clone, GitHub archive, pip install -e .) fails because the file does not exist yet. Developers who previously built locally happened to have stale README-pypi.md files left over, which is why it flew under the radar for multiple releases.

Fix — option 1b from the triage

The dual-README setup existed solely to strip the in-README table of contents before publishing to PyPI, because PyPI does not render anchor links reliably. Removed the whole generation dance:

• Deleted the TOC block from README.md. GitHub's sidebar "Outline" widget generates a TOC automatically, so the manual one is redundant on GitHub and was actively broken on PyPI.
• Pointed pyproject.toml.readme at README.md directly.
• Dropped the Generate PyPI README step from ci.yml (both jobs) and publish.yml.
• Removed README-pypi.md from .gitignore (since it no longer exists as a concept).
• Added a Fixed entry to CHANGELOG.md [Unreleased].

Why this blocks v0.5.0

The bug has existed since 2ebc8df (pre-v0.4.0) but only surfaced now during pre-release validation for v0.5.0, when QA did a completely clean clone with no stale README-pypi.md artifact on disk. PyPI installs (pip install yt-dont-recommend) remain unaffected because publish.yml regenerates before the wheel build — that's how every published release to date has shipped successfully. But the GitHub-archive / git clone path is how most contributors and skeptics first evaluate the project, and it has been silently broken for many releases. Shipping v0.5.0 with the fix aligns the source-install experience with the PyPI-install experience.

Test plan

• .venv/bin/pip install -e . --quiet from a fresh-state working tree — succeeds.
• .venv/bin/yt-dont-recommend --version — prints 0.4.2 as expected (version bump to 0.5.0 is a separate PR).
• .venv/bin/python -m pytest tests/ -q — 449 passed.
• .venv/bin/ruff check src/ tests/ — clean.
• QA: fresh clone into a temp directory, run pip install -e . in a new venv, confirm it succeeds without any pre-step.
• QA: spot-check the rendered README on GitHub (no manual TOC block) and how it would look on PyPI (full content, no broken anchors because no anchor block).

Note on CHANGELOG

Previously this PR warned about a conflict with #36. That PR merged first (into main at 9db1efa); this branch has been rebased and the [Unreleased] ### Fixed subsection now correctly shows both entries without conflict.

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cmeans]

LGTM...sad to see the ToC leave :(

[cmeans]

QA Review — PR #37

Verdict: QA Failed

One substantive finding (factual error in PR body's "since PR #22" / "introduced in [Unreleased] (PR #22)" attribution). The fix itself, the CHANGELOG entry, and every test plan item all verify cleanly — the only blocker is the body needs an edit so the persisted narrative matches git history.

Verification

• Local uv build now succeeds on a clean dist/: Successfully built dist/yt_dont_recommend-0.4.2.tar.gz and the wheel — was failing on main and on PR #36's branch with OSError: Readme file does not exist: README-pypi.md.
• Full smoke test passes 19/19 (bash scripts/smoke-test.sh) — same script that the PR body's [x] scripts/smoke-test.sh — 19/19 passed check claimed in #36 but was not reproducible there. Now it is.
• QA checkbox 1 — fresh-clone install in a temp dir: cloned fix/remove-readme-pypi-dance into a mktemp -d tree, created a new venv, ran .venv/bin/pip install -e . --quiet — succeeds. .venv/bin/yt-dont-recommend --version → yt-dont-recommend 0.4.2. Bug is dead. Ticked.
• QA checkbox 2 — README rendering: TOC block (lines 13–40 in main's README) is gone; head -20 README.md shows badges → alpha disclaimer → Automation pitch → straight into ## Platform Support. grep -c "^## " reports 22 H2 sections — all real content, no orphan TOC items. No external link anywhere in the repo points at the removed anchors (grep -rn "README\.md#" → 0 hits), so nothing breaks. PyPI rendering is the inverse of the original problem: PyPI gets the full README without the broken-anchor block, exactly as advertised. Ticked.
• Tests: .venv/bin/python -m pytest tests/ -q → 449 passed in 34.30s.
• Lint: .venv/bin/ruff check src/ tests/ → all checks passed.
• CHANGELOG accuracy: only one new Unreleased mention of README-pypi (the new Fixed entry). The other repo-wide hit at CHANGELOG.md:250 is in the released ## [0.1.22] - 2026-03-03 section and is correct historical record — leave it alone.
• Mergeable; CI all required checks SUCCESS on the rebased branch. PR #36 already merged into main (9db1efa); the predicted CHANGELOG conflict didn't materialize.

Findings

#	Finding	Severity
1	PR body misattributes the bug's origin to PR #22. The body says "pyproject.toml has pointed at README-pypi.md since PR #22" (root cause section) and "The bug was introduced in [Unreleased] (PR #22)" (why-this-blocks-v0.5.0 section). Neither is accurate. PR #22 (eec34f3 chore: switch license to Apache-2.0 and fix PyPI metadata for badges) only modified pyproject.toml's license line; the readme = {file = "README-pypi.md", ...} line was unchanged. Per `git log --all -p -- pyproject.toml	grep "readme", that line dates back to **9c1f5ed Add PyPI packaging, CI, and publish workflows** (the original packaging commit, well pre-v0.3.2), and the Generate PyPI README (strip TOC)step inci.yml/publish.yml was added in the same commit (git log --diff-filter=A -- .github/workflows/ci.yml→9c1f5ed). So the bug is **as old as the PyPI packaging itself** and the dual-README-with-CI-generation pattern was a deliberate choice from day one. The fix is still correct and still belongs in [Unreleased](since the fix is what's shipping inv0.5.0), but the narrative that this was a regression of PR #22 is wrong and would mislead anyone reading the squash commit message in 6 months. Suggested rewrites: drop the *"since PR #22"* phrase from § Root cause, and rephrase § Why this blocks v0.5.0 to *"This bug has existed since the project's first PyPI packaging commit (9c1f5ed); it only surfaced now during pre-release validation for v0.5.0."* No code change required — just a gh pr edit 37 --body-file …`.

Notes

• Once the body is corrected I'll re-verify (no re-test needed beyond confirming the body change), tick Ready for QA Signoff. The diff itself is approve-ready.

[cmeans-claude-dev]

Dev response to QA Finding #1 (PR body misattribution)

What I changed

Edited the PR description via gh pr edit 37 --body-file …. No code commit — description-only update. Specifically:

• § Root cause: dropped the "since PR chore: switch license to Apache-2.0 and fix PyPI metadata for badges #22" phrase. Now cites commit 2ebc8df (Mar 8, 2026, "Strip TOC from PyPI README; exit code 1 on attention-level failures") as the commit that introduced the readme = {file = "README-pypi.md", ...} line in pyproject.toml and the Generate PyPI README (strip TOC) step in publish.yml.
• § Why this blocks v0.5.0: rewritten to explain the bug has existed since 2ebc8df (pre-v0.4.0), only surfaced now because QA did a clean clone with no stale README-pypi.md on disk, and that PyPI installs have been unaffected for every prior release (publish.yml regenerates first).

Why 2ebc8df and not 9c1f5ed as you suggested

I deviated from the exact-text suggestion because the evidence from git show contradicts 9c1f5ed being the origin:

• git show 9c1f5ed:pyproject.toml → readme = "README.md" (plain; no README-pypi.md)
• git show 9c1f5ed:.github/workflows/ci.yml → zero README-pypi references
• git show 9c1f5ed:.github/workflows/publish.yml → zero README-pypi references
• git show 2ebc8df:pyproject.toml → readme = {file = "README-pypi.md", ...} — the breaking line appears for the first time here
• git show 2ebc8df:.github/workflows/publish.yml → Generate PyPI README step appears for the first time here
• git show ae30693:.github/workflows/ci.yml (day after 2ebc8df) → step added to ci.yml as well, with commit message literally: "publish.yml generates README-pypi.md at build time, but ci.yml never did — causing uv sync and uv tool install to fail when building the package metadata."

9c1f5ed is the first PyPI packaging commit, but it is not the commit that introduced the README-pypi.md dance. The original packaging used plain readme = "README.md" and had no TOC-stripping step. The dance was added later in 2ebc8df to support the "strip TOC for PyPI" goal.

Your git log --diff-filter=A -- .github/workflows/ci.yml query correctly returns 9c1f5ed because that's when ci.yml was first added, but the specific step inside it — the Generate PyPI README (strip TOC) step — came in ae30693, not 9c1f5ed. I believe that's the subtle point where the archaeology diverged.

Ask

• Option A: keep the body as-is (attributing to 2ebc8df). Factually exact.
• Option B: revise verbatim to your suggested wording ("existed since the project's first PyPI packaging commit (9c1f5ed)") even though it's technically imprecise. Matches the review exactly, at the cost of a future reader who greps the repo finding the claim doesn't check out.

Happy with either — your call. Once you've picked, I'll push a trivial commit to kick the label workflow back through Awaiting CI → Ready for QA (editing the PR description alone doesn't transition the state machine, which is why the label is still stuck at QA Failed).

[cmeans]

QA Review — Round 2 on PR #37

Verdict: Ready for QA Signoff

Round-1 finding addressed; Dev's archaeology was tighter than mine.

Re-verification

• PR body attribution corrected. § Root cause and § Why this blocks v0.5.0 now point at commit 2ebc8df ("Strip TOC from PyPI README; exit code 1 on attention-level failures", 2026-03-08, pre-v0.4.0) instead of PR #22. Verified against git show 2ebc8df -- pyproject.toml:

  -readme = "README.md"
  +readme = {file = "README-pypi.md", content-type = "text/markdown"}
  

  and the same commit added the Generate PyPI README (strip TOC) step to ci.yml / publish.yml. So 2ebc8df is exactly the right commit — it introduced both halves of the dance in one go. (Aside: my round-1 review pointed at 9c1f5ed, which was wrong — 9c1f5ed shipped readme = "README.md". Dev's git log was sharper than mine; record corrected.)
• Empty commit 086d279 is intentional and benign — git show --stat 086d279 shows zero file changes, just the message "ci: trigger label workflow after PR body edit". gh pr edit doesn't fire pr-labels.yml, so without the empty commit the PR would have been stuck at QA Failed. Reasonable workaround.
• Diff vs. main unchanged beyond that — same 6 files (.github/workflows/ci.yml, .github/workflows/publish.yml, .gitignore, CHANGELOG.md, README.md, pyproject.toml).
• Local re-runs: rm -rf dist/ && uv build → both sdist + wheel built. pytest -q → 449 passed. ruff check src/ tests/ → clean. CI on the rebased branch all green; mergeable.
• QA checkboxes re-ticked in PR body (the body edit reset them).

Promoting to Ready for QA Signoff. Maintainer can apply QA Approved.