docs: bring concepts.rst up to date with 2.1–2.4 behavior

[derek73]

concepts.rst was last edited on 2026-09-08. I read it against the tree and ran every checkable claim. Most still hold: the 8 tokens, spans, hashability, parsing never raising, the ambiguity examples, and STABLE_TAGS. Six things had drifted:

1. script_orders covered only "a name written wholly in one East Asian script". It also applies to kanji mixed with kana (高橋 みなみ, Japanese name segmentation via optional dependency (nameparser[ja]) #272).

2. "…nothing else does" (change what "first" and "last" mean) was false:

   • a never-given particle opening the name opens the surname under every order;
   • the opt-in patronymic_rules reorder a name.

   Both are now named. I measured the particle claim under all three orders. de Mesnil Jean under FAMILY_FIRST gives family de Mesnil, given Jean: the particle opens the surname, it doesn't take the whole name.

3. The two-layer model had no place for readings based on how a word is written. A word ending in a period at the front of the given part is a title with no list entry. Since 2.4, an unlisted dotted acronym is read as a credential, and so is an all-caps word after a comma by default. A new paragraph names each, says what position it needs, and links to the sections in usage.rst and customize.rst.

4. replace() / revise(): replace() tokens do carry a tag (vocab:unclassified), and revise() doesn't preserve tags; it parses the new value and produces fresh ones.

5. "A name of one name word… is reported" was broader than rules.md's "one name word nothing else decided". "Dr. Smith" reports nothing, and rules.md lists it as a boundary case.

6. The token-tags paragraph sat at the end of "Honest ambiguity", which it isn't about. It moves next to the spans paragraph, and "the four stable tags" drops its count.

Following docs/AGENTS.md: every new claim was measured, including the variations that showed my first wording of item 2 was wrong. A diff of inline literals and cross-references shows none dropped. sphinx-build -b doctest and -b html both print nothing.

Review rounds. One reviewer checked the PR for claim accuracy and for whether the model still reads coherently. A second reviewer then checked the fix commit. All findings were verified against the parser before fixing (83795a4f, e00ea412):

• Scripts: the family-first order covers any Japanese mix of kanji and kana, or of the two kanas, except katakana alone. That includes やまだ たろう, 山田 エミ and やまだ エミ. The list now has its own sentence instead of a nested parenthetical.
• All-caps credential: the reading needs a name with a mixed-case word of its own, like Smith. JOHN SMITH, XYZ and john smith, XYZ both keep XYZ as the given name.
• patronymic_rules reorder only under the default order (measured for both rules under all three orders).
• The one-name-word silencers are now introduced with "such as" and include the ones rules.md lists. Only a script that settles its own order silences; マイケル and Иван still report.
• The heading "Two layers decide the roles" became "How roles are decided" (nothing linked to it). The advice on which container to use now puts the unlisted-credential settings in the Policy, but not the period-title rule, which has no setting.
• Precision: the period-title rule is for a word of two or more letters with a single period at its end, and revise() classifies a value "the way a parse of that value on its own would".

No behavior change.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.98%. Comparing base (495b2b3) to head (e00ea41).
⚠️ Report is 4 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #592   +/-   ##
=======================================
  Coverage   98.98%   98.98%           
=======================================
  Files          45       45           
  Lines        4220     4220           
=======================================
  Hits         4177     4177           
  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.