docs: correct the scope of the period-abbreviation title rule

The docs said "a leading word that ends in a period is read as a title"
and that the rule "only applies to the leading run". Neither was true of
any comma form. _peel_leading_titles runs at the head of the part that
carries the given name -- NO_COMMA segment 0, SUFFIX_COMMA segment 0,
and FAMILY_COMMA segment 1 -- so "Morse, Det. Insp. Jane" reads
Det. Insp. as a title. Long-standing, verified against 1.4.0; only the
description was wrong.

Also replace the examples. "Major." is a whole word carrying a stray
period, not an abbreviation, so it never showed why the rule exists;
"Foo. Xyz." showed nothing at all. "Det. Insp." is a real rank whose
parts are real abbreviations and are both absent from TITLES, so the
example demonstrates the structural inference rather than merely
surviving it.

The closing paragraph states that only the title direction is inferred,
in prose and without a doctest: whether an unrecognized trailing
abbreviation should reach `suffix` is an open question, and pinning
today's answer in an example would prejudge it.

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

Author: derek73

AGENTS.md

@@ -172,7 +172,7 @@ Add a dedicated `copy.deepcopy()` round-trip test for it too (see `test_regexes_
 
 **Titles permanently shadow first names — be conservative** — any word in `TITLES` is always consumed as a title and can never be parsed as a first name. `"Dean"` is the canonical example: it's a common academic title *and* a common given name, so it is intentionally absent from the default titles (see `docs/customize.rst` — users who need it add it via opt-in `Constants`). Before adding a word to `TITLES`, ask: "Could this plausibly be someone's given name in any culture?" If yes, don't add it globally; it belongs in caller-supplied `Constants` instead. This same caution applies to international honorifics — `Prince`, `Sheikh`, `Frau` are all first names in some contexts. It also applies to any prefix sub-set gated on "never a first name": obscure-looking foreign particles are surprisingly often real given names — `Von` (Von Miller), `Vander` (Brazilian, also the Arcane character). When unsure, exclude — a missing member just means that name isn't auto-handled, whereas a wrong member misparses a real person.
 
-**`is_leading_title()` infers titles beyond the `TITLES` set, but only in leading position** — an unrecognized multi-letter word ending in a single trailing period (matched via the `period_abbreviation` regex, `{2,}` letters) is treated as a title when it appears before the first name is set, e.g. `"Major. Dona Smith"` → `title='Major.'`. It's distinct from `is_title()` and does not mutate `C.titles`, so the periodless form (`"Major"`) is unaffected elsewhere. The `{2,}` length requirement — not a separate initials check — is what excludes single-letter initials like `"J."` from being swallowed as titles; the same word after the first name is left as a middle name. (#109; see `docs/usage.rst` "Leading Period-Abbreviation Titles")
+**The period-abbreviation title inference runs at the head of the GIVEN-NAME part, not the head of the name** — an unrecognized multi-letter word ending in a single trailing period (`_assign._PERIOD_ABBREV`, a hand copy of the `period_abbreviation` regex, `{2,}` letters) is treated as a title in the leading title run, e.g. `"Insp. Jane Morse"` → `title='Insp.'`. "Leading" is per SEGMENT: `_peel_leading_titles` is called for NO_COMMA segment 0, SUFFIX_COMMA segment 0, and FAMILY_COMMA **segment 1**, so `"Morse, Det. Insp. Jane"` → `title='Det. Insp.'` and a lone `"Smith, Xyz."` → `title='Xyz.'` — long-standing, verified against 1.4.0, and the mechanism behind #296 (`"Smith, Jr."` → title, which the shape rule claims even once `jr` leaves `TITLES`). The docs said "leading word" until 2026-08-01 and were wrong for every comma path. It does not mutate `C.titles`, so the periodless form (`"Major"`) is unaffected elsewhere. The `{2,}` length requirement — not a separate initials check — is what excludes single-letter initials like `"J."`; the same word after the given name is left as a middle name. **Only the title direction is inferred**: a trailing abbreviation has no structural fallback and is matched against the suffix vocabulary alone (`"John Smith Xyz."` → `family='Xyz.'`), while `period_joined_vocab` resolves INTERIOR-period tokens (`Lt.Gov.`, `Msc.Ed.`) to title-or-suffix by vocabulary, and `_extract._suffix_shaped` treats any period-final delimited content as not-a-nickname. Three period rules, three different resolutions — see the v2.2 issue on unifying them. (#109; see `docs/usage.rst` "Titles you didn't configure")
 
 **Cyrillic suffix regexes need `re.I` even when the pattern is suffix-only** — a Latin title-cased word (`Ivanovich`) keeps its suffix lowercase, so `re.I` seemed skippable; but an irregular Cyrillic suffix can be nearly the whole word (`ильич`), so title-casing capitalizes into the suffix itself (`Ильич`). `east_slavic_patronymic_cyrillic` shipped without `re.I` on the Latin reasoning and silently failed on capitalized irregular forms — don't assume Latin's title-case safety transfers to Cyrillic. (#185)
 

docs/customize.rst

@@ -70,9 +70,10 @@ go together:
     'Hon'
 
 Emptying the vocabulary does not switch titles off entirely, though. A
-leading word that ends in a period is read as a title structurally,
-without consulting ``titles`` at all — that is what lets unfamiliar
-ranks and abbreviations work (see :ref:`abbreviated-titles`):
+word ending in a period, standing at the front of the part that carries
+the given name, is read as a title structurally, without consulting
+``titles`` at all — that is what lets unfamiliar ranks and
+abbreviations work (see :ref:`abbreviated-titles`):
 
 .. doctest::
 

docs/release_log.rst

@@ -31,6 +31,10 @@ Release Log
     - Fix NFD-decomposed input missing the East Asian defaults entirely: script classification now normalizes to NFC before deciding, so a Korean or Japanese name typed on macOS — where decomposed text is routine — gets the same order rule as its composed twin, which it silently did not before. Segmentation MATCHING deliberately stays raw, so an unspaced NFD hangul name is ordered correctly but not split, rather than being split in the wrong place. One gotcha worth stating plainly: parse output preserves the encoding it was given, so for NFD input ``name.family == "김"`` is ``False`` even though it is the same name — compare NFC-normalized text when comparing across encodings (#272)
     - Fix the Ukrainian conjunction ``й`` not joining the pieces around it: it is the euphonic alternate of ``і``, the two chosen by the surrounding vowel and consonant rather than by meaning (``"Олесь і Олена"`` but ``"Марія й Петро"``), so real Ukrainian data carries both spellings and shipping only ``і`` recognized just one of them. ``"Олесь й Олена Коваленки"`` now gives given ``"Олесь й Олена"`` where the ``й`` previously landed in ``middle``. Same treatment as the ``и``/``і`` entries added in 2.0.0, single-letter carve-out included: the conjunction joins only once the name has enough pieces, and a punctuated initial still wins, so ``"Й. Сліпий"`` is unaffected. Raised in a comment on #267
 
+    **Documentation**
+
+    - Correct the documented scope of the period-abbreviation title rule. It was described as applying to "a leading word", which was never true of any comma form: the rule runs at the front of the part that carries the given name, which after a family comma is the part *after* the comma — so ``"Morse, Det. Insp. Jane"`` gives title ``Det. Insp.``. Behavior is unchanged and matches 1.4.0; only the description was wrong. The examples now use real abbreviations absent from the shipped vocabulary (``Det. Insp.``) rather than whole words carrying a stray period, so they demonstrate the structural inference instead of merely surviving it
+
 * 2.0.0 - July 27, 2026
 
     Two release candidates preceded this release (rc1 on 2026-07-23,

docs/usage.rst

@@ -530,34 +530,55 @@ what that field marks and how to add to it.
 Titles you didn't configure
 -----------------------------
 
-A leading word that ends in a period is read as a title even when it is
-in no vocabulary list, which is what lets unfamiliar ranks, honorifics
-and abbreviations work without configuring anything:
+A trailing period marks an abbreviation, and the parts of a name that
+get abbreviated are the ones standing outside it — titles and
+post-nominals. So a word ending in a period, in no vocabulary list at
+all, is read as a title when it stands where a title stands: at the
+front of the part that carries the given name. That is what lets
+unfamiliar ranks, honorifics and abbreviations work without configuring
+anything:
 
 .. doctest::
 
-    >>> parse("Major. Dona Smith").title
-    'Major.'
-    >>> parse("Foo. Xyz. John Smith").title      # chains
-    'Foo. Xyz.'
+    >>> parse("Insp. Jane Morse").title
+    'Insp.'
+    >>> parse("Det. Insp. Jane Morse").title     # chains
+    'Det. Insp.'
+
+Neither ``det`` nor ``insp`` is in the shipped vocabulary; the periods
+are doing all the work.
+
+The part that carries the given name is not always the front of the
+string. After a family comma it is the part *after* the comma, and the
+rule applies there in exactly the same way:
+
+.. doctest::
+
+    >>> parse("Morse, Det. Insp. Jane").title
+    'Det. Insp.'
 
 The rule is bounded in three ways, so it doesn't swallow ordinary
 names. Single initials are left alone, so are abbreviations with
-interior periods, and the rule only applies to the leading run — the
-same word after the given name is a middle name:
+interior periods, and it applies only to that leading run — the same
+word after the given name is a middle name:
 
 .. doctest::
 
     >>> parse("J. Smith").given
     'J.'
     >>> parse("E.T. Jones").given
     'E.T.'
-    >>> parse("John Major. Smith").middle
-    'Major.'
+    >>> parse("Jane Insp. Morse").middle
+    'Insp.'
 
 Because this is structural rather than vocabulary-driven, emptying
 ``titles`` does not switch it off; see :doc:`customize`.
 
+Only the title direction is inferred this way. A *trailing*
+abbreviation is matched against the suffix vocabulary and nothing more,
+so an abbreviated post-nominal is recognized only if it is a word the
+parser already knows.
+
 Comparing names
 ----------------