docs: finish the audit, and stop --out from silently working

[adiazpar]

Follow-up to #2, prompted by the question "did you update ALL documentation?" — the honest
answer was no.

What was stale

docs/ and README.md were rewritten in #2. The surfaces outside them were not, and two
actively contradicted the change:

File	Said	Reality
PULL_REQUEST_TEMPLATE.md	the palette is an input "the user supplies… never something this repo ships"	it ships — that checklist item would fail a PR for doing the right thing
PULL_REQUEST_TEMPLATE.md	"neither gate moved"	there are three byte gates
SECURITY.md	reads "a MIDI file you give it, plus two data files you point it at"	there are no files to point at
CODEOWNERS	guards CI + pyproject.toml as supply-chain-critical	the shipped palette is now exactly that, and wasn't guarded

SECURITY.md also gained the threat that replaced the two it lost: the shipped palette holds
identifiers rather than code, so nothing can execute, but a tampered entry silently changes
which sound every note plays and no test can tell that from an intentional edit. tools/
joins CODEOWNERS for the same reason — it is what regenerates that data.

Two behaviours were undocumented anywhere

architecture.md now explains why reading a pitch out of a name is ambiguous — b is both a
note and a flat marker, so play_fluteb4 parses two ways and only the instrument stem settles
it — and why the blank stage carries sixteen persistent integers.

The audit found a live bug

Checking that every documented flag actually exists turned up --out still working. argparse
abbreviates unambiguous prefixes, so --out song.json bound to --out-dir and wrote
song.json/rawmap.json — creating a directory named after the file the user meant to
write. Silent, exit 0. Anyone working from muscle memory or an old note got that.

--out now refuses with the migration it needs, and allow_abbrev=False stops any other flag
binding that way (--but was reaching --button).

README install instructions

It assumed pip install into a system Python — which fails outright on any PEP 668
distribution and pollutes the interpreter everywhere else. There is now a short path and an
isolated path: which folder to cd into, the activation line for each shell, the PowerShell
execution-policy fix, and the thing people actually trip on — activation does not survive
closing the terminal.

Every step was run verbatim from an empty directory before being written down.

How this was checked, not asserted

• every Python snippet in the docs executed against the installed package
• every documented CLI flag checked against --help
• every internal link and anchor resolved
• stale-claim grep across all 15 tracked text surfaces

130 passed, 4 skipped.