Correct the stale prose left by the #293 vocabulary rename

[derek73]

The documentation half of #356. Every claim was measured against this tree before rewriting — several had drifted further than the issue recorded, and two needed a different fix than it prescribed.

Then reviewed, which turned up six defects in this branch's own corrections; those are fixed in the last three commits and described below.

Deliberately not closing #356: the bridge/API and test-hygiene half is untouched (see the end).

Round 1 — the sweep

Site	Was	Measured
AGENTS.md particle note	"leading token → first-name join, mid-name → last-name join"	abu bakr ahmed → first='abu bakr'; mohammed abu bakr → last='abu bakr'
AGENTS.md internal-usage guard	an internal read "would consume the once-per-process warning"	internal_reader.py:1 then real_caller.py:1 → 2 warnings
AGENTS.md esq paragraph	SUFFIX_ACRONYMS − {esq} "changes many"	only multi-dot spellings move: E.S.Q./E.S.Q 5/7 frames, Esq/Esq./ESQ/esq 0/7
AGENTS.md delimiter gotcha	live 2.x guidance	half the mechanism is deleted — see below
docs/customize.rst	"TITLES, PARTICLES and the rest of nameparser.config are frozen"	REGEXES and CAPITALIZATION_EXCEPTIONS are still dict
nameparser/config/__init__.py	cites migration spec §3	the removal list is §4; §3 is the shim

Two places this diverges from the issue.

The delimiter gotcha isn't just v1 history. #356 reads it as a stale paragraph in a section not marked as such. Half is stale — CONSTANTS.regexes.parenthesis = ... raises TypeError, a custom delimiter key is refused rather than accepted as a compiled pattern, and HumanName.parse_nicknames is gone. But the pop() + assign routing advice is still correct and still the only way to move a built-in on the v1 API:

maiden_delimiters['parenthesis'] = nickname_delimiters.pop('parenthesis')
Jane (Jones) Smith    default -> nickname='Jones'
                      routed  -> maiden='Jones'

Retiring the whole bullet would have deleted working guidance, so it's split instead.

The spec-citation problem is repo-wide. Eight shipped modules cite migration spec §N / locales spec §N into gitignored docs/superpowers/. This PR fixes the wrong section number and makes that one note self-contained; the convention is left alone elsewhere, as changing it is a separate call.

Round 2 — review of the above

Six defects, five confirmed by measurement. Three are the same class of error the branch exists to fix.

Finding	Fix
customize.rst said TITLES "and the rest kept the names they already had" — false for NON_FIRST_NAME_PREFIXES, BOUND_FIRST_NAMES, SUFFIX_NOT_ACRONYMS	all five renames named, so the negative claim is now true
AGENTS.md "the CJK packs took it to eleven" — the eight keys came from one commit (7ee6e3a, #273), and five of eight are Western pairs	attributed to #273, counts split 5 Western / 3 CJK
AGENTS.md "the bridge warns per read location" — credits the bridge with __warningregistry__'s behavior	control: two files issuing a plain warnings.warn emit the same two warnings under -W once/default/module. Now credits the warnings module, and names the bridge's real contribution (no write-back caching) with a don't-optimize-it warning
customize.rst "still plain dicts" read as an exemption from the freeze	see below — the measurement changed the finding
AGENTS.md "there is no parse_nicknames() left" — the name is live in _facade.py's _V1_HOOKS, where overriding it warns (#280)	marked gone-as-a-method, live-as-a-hook
AGENTS.md esq single-token claim was a universal quantified over sampled frames	reframed as the proof it is; the 26-frame sweep demoted to corroboration

The dict finding got worse on re-measurement. The review comment said mutating CAPITALIZATION_EXCEPTIONS was a silent no-op. Through the correct API:

v1 shared CONSTANTS    unchanged
v1 fresh Constants()   CHANGED
v2 Lexicon.default()   unchanged

Not a no-op — the inconsistent reach the freeze was introduced to remove for the word lists. The committed text says that.

Also fixed, outside #356's list

nameparser/config/suffixes.py had two comments calling SUFFIX_ACRONYMS_AMBIGUOUS "consulted only by parse_nicknames()". Same staleness class, in a shipped module. Repointed at the three real 2.x readers: _extract.py:60 (delimited-content escape), _vocab.py:127 (period gate), _classify.py:47 (vocab:suffix-ambiguous tag).

Still open on #356 (the API/test half)

• no __all__ on particles.py / bound_given_names.py; particles.py re-exports BOUND_GIVEN_NAMES
• __dir__ raises KeyError rather than AttributeError off the read path
• inspect.getmembers()/help() on titles/suffixes resolves retired names and emits their warnings (confirmed incidentally — dir() on those modules warns)
• _RETIRED_NAMES duplicates what's derivable from ALIASES; ALIASES is a positionally-indexed bare 4-tuple
• star-import test asserts names but not values; from X import Y attribution tested for one alias of five

The natural bundle for whatever next touches nameparser/config/ — plausibly #342, which edits suffixes.py.

Verification

pytest              3197 passed, 41 skipped, 11 xfailed
ruff check          All checks passed!
mypy                Success: no issues found in 103 source files
sphinx -W           build succeeded
sphinx -b doctest   225 tests, 0 failures

Part of #356.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.51%. Comparing base (54c1894) to head (3038cd4).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #377   +/-   ##
=======================================
  Coverage   98.51%   98.51%           
=======================================
  Files          44       44           
  Lines        2895     2895           
=======================================
  Hits         2852     2852           
  Misses         43       43           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.