docs: restructure customize.rst into sections and add a user-docs style guide

[derek73]

The unlisted_dotted_suffixes and unlisted_caps_suffixes rows of the Policy table in customize.rst had grown to ~35 and ~25 lines each, which made the table hard to read as an index of fields.

Changes

• Both rows now say what the field does, give its default, and link to the new section.

• New subsection Credentials the vocabulary doesn't list (.. _unlisted-credentials:), after "Suffixes not separated by commas". It explains the shared positional reading and the two-letter initials exception once, then has one part per field. Every other row whose field has a section now links to it too (see the review round below).

• The examples that sat in table cells as untested prose are now .. doctest:: blocks. Every claim was re-run against the tree first; none had gone stale.

• One claim is narrowed, not just moved: "the fork is reported either way" holds only for the dotted field, and only where the dotted word ends a name, given part or clause. The caps field reports nothing for Smith, XYZ or García Márquez, MJ, and the dotted field reports nothing for John Smith, X.Y.Z..

• usage.rst's pointer now targets the new section instead of the whole page.

• The "Turning title detection off" example built its parser on Lexicon.empty(), which also drops the Korean surname list while hangul segmentation stays on, so the doctest build printed a segmenterless UserWarning. It now reuses lean, the title-only lexicon from the block above, with the same outputs, and the doctest build runs with no output.

• maiden_delimiters: the row now says what the field does and links to "Nicknames, maiden names, and brackets", which gets a .. _brackets: label and names the field it used to call "this knob". The section also picks up the two pieces it lacked, both as doctests: the two kinds of clause the pair decides (markerless content and a lone marker word), and the marker-dropping rule with its token nuance ((Nee) and 山田花子（旧姓佐藤） keep the marker). "Whatever pair encloses it" is narrowed to any configured pair: Jane Smith [née Jones] is not a maiden name, because square brackets are not a default pair.

• lenient_comma_suffixes: the CJK aside repeated usage.rst's paragraph on commas around CJK names, which already shows 田中さん, V. but didn't mention the switch. It moves there as one sentence, under that paragraph's caveat that the reading can change. The row is short enough now to need no section.

• "Words that are also ordinary names": the section opened on a 45-line paragraph. It now has a short intro and one ^ subsection per field: Credentials that are also surnames (the reading rules as a bullet list in precedence order), Mark a word, or leave it out (the choice between unambiguous, marked and removed, as a list), Particles that are also given names (which now holds the stray Mc Donald and Ste Marie read the particle as the given name #360 sentence), and One-letter connectives that are also initials. Every example was re-run first. The section title is unchanged, so its one inbound link still resolves.

• "Fixing the case of a particular word": the recipe and the replace-not-extend note stay at the top. The 28-line paragraph after them splits into How a key matches a word, Words that need no entry and Acronyms the vocabulary doesn't list (plain vs. dotted, as a list). Five claims that were prose are now doctests (ph.d., p.h.d., md iv, psyd, edd). The matching example now uses PHD instead of Phd: a mixed-case Phd does match the key, but it is left as written unless force=True, and the text now says so.

• "East Asian defaults, and turning them off": split into Switching off order and splitting, Teaching the splitter a surname, Japanese names and Behaviors no policy field controls. The long closing paragraph had covered four topics; it is now spread across the last two subsections, with the two behaviors no field controls (the ・ separator and the glued honorific) as a list. New doctests pin that script_orders=() clears the kana-licensed order (山田 エミ), that ・ and さん still split with both fields cleared, and that honorific_tails is the peel's off-switch. The note about () / frozenset() spellings moves up beside the first example that uses them. I checked the peel-cost claim against the if not tails guard in _script_segment.

• "Nicknames, maiden names, and brackets": split into How a bracketed clause is read, Routing a pair to maiden names and Adding a delimiter pair. The section said a clause "is settled in steps" but then described them in running prose. The steps are now a numbered list, and one doctest walks through all three. It includes the (née Jr.) example, which was prose before, and a quoted "née Jones" showing that step 2 holds inside any configured pair.

• Maiden markers: customize.rst never said where marker words come from or how to add one. A new Maiden markers subsection opens the brackets section. It shows the bare née Jones form in one line and links to usage.rst for the full treatment. It links the shipped marker list (in the module docs) instead of copying it. And it gives an add() recipe showing an added marker (formerly) working both bare and in brackets. usage.rst gains a nicknames-and-maiden-names label, and its maiden_delimiters pointer now goes to the brackets section, not the top of customize.

• All-caps words: each CapsSuffixes setting now has its own heading: AFTER_COMMA (the default), EVERYWHERE and OFF. They use a fifth heading level on the page (", rendered as <h5>). The contrast rule stays above them because it applies to all three.

• docs/AGENTS.md (new): a style guide for the .rst user docs, written up from this PR. Its rules are: tables are indexes, use subheadings per reader task, match list shape to content shape, put background before behavior, place notes next to what they explain, follow the heading-level sequence, write recipe doctests that are non-vacuous and warning-free, measure every claim before moving it, check it end to end, and link instead of restating. Each rule names the failure from this PR that it prevents. It loads automatically when an agent edits files under docs/, the same way docs/design/AGENTS.md does, and the root AGENTS.md now points to it. Sphinx reads only .rst files, so it doesn't appear in the built site.

Review round (three parallel reviewers: claim accuracy, content preservation, the guide), fixed in 4bde4b1 and 127aa83:

• The two-letter initials exception's give-way rule had landed under "Dotted acronyms" alone, but it covers capitals too (John Smith, PhD MJ). It moved into the shared intro.
• The dotted field reads a fourth position silently (John Smith, X.Y.Z.). It's now listed, and the reporting claim is narrowed.
• Restored what the move had dropped: the "since 2.4" and "since 2.2" notes and two EVERYWHERE examples.
• The marker-dropping rule was described as a token count, which (z domu) contradicts. It's restated, with a doctest.
• Five table rows (name_order, nickname_delimiters, extra_suffix_delimiters and both strip flags) had sections they didn't link to. They link now.
• docs/AGENTS.md: fixed its own cited evidence (row counts, the chancellor incident predating this PR, the dotted reporting claim), settled the recipe-vs-pin rule, and added three lessons from the round.
• Out of scope, filed as a separate task: a stale code comment in _script_segment.py claims jr is title vocabulary.

Second review round (on the fix commits, per AGENTS.md), fixed in the last commit:

• The initials exception gives way to an unlisted word of either kind (MJ X.Y.Z.), not just the same kind.
• "Since 2.4" is now said once for both fields; it had tagged only two positions, implying the others were older.
• The dotted reading reports a fork only when bare; behind a title (Ms G.J.) nothing is reported.
• Set-field examples (extra_suffix_delimiters, and two in migrate.rst) used bare set literals that fail mypy. They're now frozenset(...), checked with mypy --strict against the old spelling as a control.
• The table omitted script_orders and segment_scripts; they now have short rows linking to the East Asian section.
• docs/AGENTS.md: only the eight STAGES modules carry Reads: lines.

No behavior change.

Verified: sphinx-build -b doctest docs: 0 failures (126 tests in customize). sphinx-build -b html docs: exit 0.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.98%. Comparing base (ca28f04) to head (8cb9358).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #588   +/-   ##
=======================================
  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.