docs: SCRIPTS.md covers 42 of 103 bin scripts and 4 of 31 modules — make the inventory mechanically complete

[adrianwedd]

docs/SCRIPTS.md claimed to document "every script in bin/ and every module in src/pxh/". Measured on this branch by counting ### bin/… and ### src/pxh/… headings against ls:

• bin/: 42 of 103 documented — 61 missing
• src/pxh/: 4 of 31 documented — 27 missing

That is 88 gaps, not the 58 first estimated. The module side is far worse than the script side: the only documented modules are state.py, logging.py, time.py, and voice_loop.py. Every entry that is present names a script that really exists, so the inventory has holes rather than rot.

The gaps are not peripheral. Absent entries include px-mind, px-brain, px-brain-status, px-claude-session, px-blog, px-api-server, px-evolve, and 36 of the 46 tool-* scripts — including tool-wander, tool-brain-reply, and tool-remember. (tool-voice is documented; an earlier revision of this issue said otherwise.)

#215 softened the completeness claim rather than filling the gap, because a document asserting completeness while known-incomplete is exactly the failure mode that PR exists to eliminate. This issue tracks actually closing it.

Proposed

1. A structural test in tests/test_docs.py that fails when a bin/ script or pxh module has no entry — with an explicit, shrinking allowlist of known-undocumented names, so the gap can only get smaller.
2. Backfill entries, prioritising the daemons and tool-* scripts, since tools are the ones an agent is most likely to reach for from a prompt.

Do not merge step 1 without the allowlist — a test that fails on 88 pre-existing gaps is a test nobody will keep.

Note the counts in docs/SCRIPTS.md are hand-maintained and were wrong on first writing (45/11 rather than 42/4). Step 1 makes them mechanical, which is the real fix: a hand-counted self-audit is the same class of defect as #214.

[adrianwedd]

Grooming 2026-08-26 — re-measured on master 5b9070de; the gap widened

$ ls bin | wc -l                       # 104
$ ls src/pxh/*.py | wc -l              #  38
$ grep -c '^### bin/'      docs/SCRIPTS.md   # 41
$ grep -c '^### src/pxh/'  docs/SCRIPTS.md   #  4

63 bin scripts and 34 modules undocumented — 97 gaps, up from the 88 measured
when this was filed. The bin count went down by one entry (42→41) while the
tree grew by one script; the module side has not moved at all. New arrivals since
filing that are absent: bin/px-motd, bin/px-person-seed, src/pxh/people.py,
src/pxh/quiet_mode.py.

That drift is the argument for step 1 as written: a hand-maintained inventory
does not merely stay incomplete, it decays, and nothing fails when it does.
tests/test_docs.py currently has no SCRIPTS.md check.

Proposal unchanged, and the ordering constraint in it still matters — the
structural test must ship with a shrinking allowlist, not as a test that fails
on 97 pre-existing gaps.