[binlecode]

Docs only — no code, CLI, or test change. Lands under CHANGELOG.md [Unreleased]; per When to cut a release this is repo-internal churn and ships with the next user-visible release, not as a release of its own.

Why

The PyPI hygiene note said to delete the project-scoped token once OIDC Trusted Publishing was confirmed on a release. Two problems:

1. It contradicted the failure playbook two paragraphs above it, which names the token-driven Flow B as the recovery path when publish-pypi fails on an OIDC / trusted-publisher error. Obeying the hygiene rule removed the fallback exactly when a broken release would need it.
2. It failed silently. ~/.zshrc builds TWINE_PASSWORD with $(cat … 2>/dev/null), so deleting the file yields an empty password — a confusing PyPI auth error rather than an obvious missing-file one.

This is not hypothetical: immediately after the v1.9.11 release published cleanly over OIDC, an agent (me) read that note as an action item and proposed deleting the live break-glass token. The maintainer declined. The note is the root cause, so it is retired.

Changes

• Hygiene note reversed — retain the token, refresh on expiry, revoke only on leak/replacement. Also warns that ~/.zshrc names pypi-org-api-token-binlecode literally, not by glob, so adding a dated -exp-<month>-<year> suffix requires editing the .zshrc path in the same commit or the export breaks silently.
• Break-glass documented as env-sourced — TWINE_USERNAME / TWINE_PASSWORD are pre-exported, so twine upload needs no flags and nobody hunts for a token file. Presence is checked with env | grep -c TWINE_PASSWORD, never by printing the value.
• New hard rule under Security & Configuration Tips: never delete, revoke, or rotate a credential, or propose it as cleanup — credential lifecycle is the maintainer's call. Plus secret-handling rules (never print a value; assert on presence, not content; filenames and env-var names are not secrets, their values are).
• Drive-by dedupe of the two near-identical "avoid persistent privileged processes" bullets in that section.

Validation

.venv/bin/ruff check .          # All checks passed
.venv/bin/ruff format --check . # 60 files already formatted

Diff leak-checked for token material (pypi-Ag… / AgEIcHlwaS5vcmc): 0 matches. The doc references the credential's filename and env-var names only — never a value.

🤖 Generated with Claude Code