docs: fix what the second review round found in the first round's fixes

- The initials exception gives way to an unlisted word of EITHER kind
  beside the letters ("MJ X.Y.Z.", "G.J. XYZ"), not only the same kind,
  where that word's own field reads it.
- "Since 2.4" marked two of the dotted field's positions when the whole
  field is new in 2.4, implying the others were older; the section
  intro now says both fields are new in 2.4, once.
- The dotted spelling reports the BARE initials reading; behind a title
  ("Ms G.J.") nothing is reported.
- The extra_suffix_delimiters example, and two migrate.rst mappings,
  spelled set fields as bare set literals, which fail mypy against the
  frozenset annotations; now frozenset(...), checked with mypy --strict
  against the old spelling as a control.
- The Policy table claimed to list every field but omitted
  script_orders and segment_scripts; both get short rows linking to the
  East Asian section, which gains a label. The script order winning
  over every name_order was measured.
- docs/AGENTS.md: only the eight STAGES modules carry Reads: lines;
  _vocab.py and _pieces.py read the lexicon without one. And the first
  pass LEFT the five unlinked rows; the review found them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: derek73

docs/AGENTS.md

@@ -6,7 +6,7 @@ The rules below were distilled from PR #588, which restructured `customize.rst`
 
 ## Structure
 
-**A table is an index.** A row states what the field does and its default, in a sentence or two, and links to a section with `:ref:`. Detail, boundary cases and examples go in the section. A description cell past about five lines is the signal that the row has stopped being an index. Rows grow by accretion — each fix adds its boundary case where the field is already described — so when you have a new case to document, add it to the section, never to the row. `customize.rst`'s Policy table is the model: every row whose field has a section links to it, and a field that needs no more than its row (`middle_as_family`) has no section at all. A row that has a section and does not link to it is a dead end — #588's first pass found five.
+**A table is an index.** A row states what the field does and its default, in a sentence or two, and links to a section with `:ref:`. Detail, boundary cases and examples go in the section. A description cell past about five lines is the signal that the row has stopped being an index. Rows grow by accretion — each fix adds its boundary case where the field is already described — so when you have a new case to document, add it to the section, never to the row. `customize.rst`'s Policy table is the model: every row whose field has a section links to it, and a field that needs no more than its row (`middle_as_family`) has no section at all. A row that has a section and does not link to it is a dead end — #588's first pass left five.
 
 **One topic per paragraph; subheadings for a section with several.** A paragraph that answers more than one question gets split, and a section holding more than one task gets subheadings named for what the reader came to do ("Routing a pair to maiden names", "Teaching the splitter a surname"), not for the mechanism. Keep an existing section title when you add subheadings under it: other pages link to titles (`` `Words that are also ordinary names`_ ``), and renaming breaks them.
 
@@ -40,7 +40,7 @@ The rules below were distilled from PR #588, which restructured `customize.rst`
 
 **Check a claim end to end, through the call the reader makes.** "One `phd` key covers `Phd`" was true of the key match and false of `capitalized()`'s output, which leaves mixed case alone unless `force=True`. Verify against what the reader would observe, not an intermediate step.
 
-**A claim about code needs the code.** "An empty `honorific_tails` stops the peel at its first guard" is checked by reading the guard, not by parsing a name. Find it through the stage headers: each `nameparser/_pipeline/*.py` module declares the `Policy`/`Lexicon` fields it reads on a `Reads:` line, so grepping those for the field names the stage to read.
+**A claim about code needs the code.** "An empty `honorific_tails` stops the peel at its first guard" is checked by reading the guard, not by parsing a name. Find it through the stage headers: each stage module (the eight in `nameparser/_pipeline/__init__.py`'s `STAGES`) declares the `Policy`/`Lexicon` fields it reads on a `Reads:` line. The shared helpers `_vocab.py` and `_pieces.py` have no such line and read the lexicon too, so grep them as well.
 
 ## Linking
 

docs/customize.rst

@@ -486,6 +486,16 @@ listed below.
        John" puts the family name first); a comma that only sets off
        suffixes ("John Smith, Jr.") leaves it governing the name part.
        See :ref:`name-order`.
+   * - ``script_orders``
+     - pairs of ``Script`` and an order
+     - Assigns a name in one of these scripts in the paired order,
+       whatever ``name_order`` says. Defaults to family-first for a
+       name wholly in Han or Hangul, or mixing kanji with kana. See
+       :ref:`east-asian-defaults`.
+   * - ``segment_scripts``
+     - ``frozenset[Script]``
+     - Scripts whose unspaced names are split into surname and given
+       name. Defaults to Hangul. See :ref:`east-asian-defaults`.
    * - ``patronymic_rules``
      - ``frozenset[PatronymicRule]``
      - Reorders patronymic-shaped names via opt-in detectors — East
@@ -718,6 +728,8 @@ so leaves a real question to answer.
 `Words that are also ordinary names`_ covers dropping a word from a
 vocabulary, or moving one between those two sets.
 
+.. _east-asian-defaults:
+
 East Asian defaults, and turning them off
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -984,7 +996,7 @@ is bad enough to be the reason you'd go looking:
     >>> name = parse("Jane Smith, RN - CRNA")
     >>> name.given, name.family, name.suffix
     ('RN', 'Jane Smith', 'CRNA')
-    >>> policy = Policy(extra_suffix_delimiters={" - "})
+    >>> policy = Policy(extra_suffix_delimiters=frozenset({" - "}))
     >>> name = Parser(policy=policy).parse("Jane Smith, RN - CRNA")
     >>> name.given, name.family, name.suffix
     ('Jane', 'Smith', 'RN, CRNA')
@@ -994,7 +1006,8 @@ is bad enough to be the reason you'd go looking:
 Credentials the vocabulary doesn't list
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-No suffix list holds every post-nominal, so two ``Policy`` fields read
+No suffix list holds every post-nominal, so two ``Policy`` fields, both
+new in 2.4, read
 an unlisted word as a credential from how it is written: in periods
 (``X.Y.Z.``), or in capitals (``XYZ``). The writing cannot settle it
 alone, because a surname can be written either way, so both fields
@@ -1005,12 +1018,13 @@ Both fields share one exception. Two letters alone right after a comma
 are how a person's initials are written, and the words before the comma
 may be one surname of two words, so ``"García Márquez, G.J."`` and
 ``"García Márquez, MJ"`` keep given ``G.J.`` and ``MJ``. The dotted
-spelling reports that reading as a fork; the capitals do not.
+spelling reports the bare reading as a fork; the capitals do not.
 
 The exception gives way to evidence that the letters are a credential:
 an unambiguous post-nominal in front of them that is not also a title,
-or another unlisted word of the same kind beside them. A title in front
-of them says the opposite:
+or another unlisted dotted or all-caps word beside them that its own
+field reads as a credential. A title in front of them says the
+opposite:
 
 .. doctest::
 
@@ -1029,9 +1043,9 @@ Dotted acronyms
 
 ``unlisted_dotted_suffixes`` is on by default. It reads a token of two
 or more period-separated chunks as a credential at the end of a name,
-right after a comma behind two or more name words, and — since 2.4 —
-at the end of the given part after a family comma and at the end of a
-maiden marker's clause. Case is irrelevant; the periods are the signal.
+right after a comma behind two or more name words, at the end of the
+given part after a family comma, and at the end of a maiden marker's
+clause. Case is irrelevant; the periods are the signal.
 With nothing to spare in front of it, the word stays a name. At the end
 of a name, given part or clause, either reading reports the fork as a
 ``suffix-or-name`` ambiguity, so a record that reads wrong can still be

docs/migrate.rst

@@ -148,7 +148,7 @@ Attribute map
      - Same three knobs, now call-site arguments to
        :meth:`~nameparser.ParsedName.initials`
    * - ``suffix_delimiter``
-     - ``Policy(extra_suffix_delimiters={...})``
+     - ``Policy(extra_suffix_delimiters=frozenset({...}))``
      - Moves from a ``HumanName``/``Constants`` scalar to a ``Policy``
        set field, so more than one custom delimiter can be active at
        once. It is the *set* that moved, not just the name: passing the
@@ -366,8 +366,8 @@ rendering argument, where the 2.0 equivalent isn't config at all):
      - 2.0 equivalent
      - Note
    * - ``patronymic_name_order``
-     - ``Policy(patronymic_rules={PatronymicRule.EAST_SLAVIC,
-       PatronymicRule.TURKIC})``
+     - ``Policy(patronymic_rules=frozenset({PatronymicRule.EAST_SLAVIC,
+       PatronymicRule.TURKIC}))``
      - v1's single flag enabled both detectors at once; pick one rule
        (or a locale pack, see :doc:`locales`) if you only want one
        tradition