Read a particle phrase as the second given name; leave Kaur and Singh to neither two-name switch (#704)

AGENTS.md

@@ -223,6 +223,7 @@ The compiled sets, read by `Lexicon` (mostly as the `_sets` field of the same na
 - particles — `PARTICLES` (family-name particles, e.g. "de", "van") and `NON_GIVEN_NAME_PARTICLES`, the curated subset that is *never* a standalone given name (the particles whose word has no `given` reading, each stating `may_be_given = false`; a `given` reading on the word is what makes a particle possibly given, the phase 1 flag `may_be_given = true` refused since 2026-10-25). What the subset licenses is rules/P1's fold in `post_rules` (the "rule 1b" of older issue comments — decisions/legacy-rule-numbers maps the old numbers), and the fold has ONE site: the piece that OPENS the name. A lone never-given particle there, with at least one more name word behind it, starts the family. Titles do not move the opening position (rules/P4), so `Sir de Mesnil` reads family `de Mesnil` under every `name_order`, as `de Mesnil` does. How far the fold reaches depends on the order the name was read under: by default it takes the rest of the name (`de Mesnil Jean` → family `de Mesnil Jean`); under either family-first order it takes the particle run plus ONE name unit and lays the rest out by the order (`de Mesnil Jean` → family `de Mesnil`, given `Jean`); after a family comma it takes the rest of that part whatever the order (`Smith, de Mesnil Jean` → family `Smith de Mesnil Jean`). The leading particle stays a lone piece for the fold to find — `group` does not chain it forward, and the fold walks the particles after it itself — so `de la Vega` reads family `de la Vega` under all three orders. The GIVEN position is not a site. It was a second one until #467, which removed it because under a family-first order that slot holds what the caller DECLARED to be the given name: `Mesnil de` under `FAMILY_FIRST` or `FAMILY_FIRST_GIVEN_LAST` reads given `de`, family `Mesnil`. Nor is a particle inside the name: `Juan de la Vega` under a family-first order reads family `Juan`, given `de la Vega`, with no ambiguity recorded — what the vocabulary forbids is the bare particle as a given name, not a name part that begins with one. A bare `de` has nothing to fold into and is placed by position like any one-word name: given `de` by default, family `de` under both family-first orders. A leading particle OUTSIDE the set is left to position — `van Gogh` is given `van`, family `Gogh` by default and family `van`, given `Gogh` under both family-first orders — and records a `PARTICLE_OR_GIVEN` ambiguity under all three; a never-given particle opening the name records none (`de Mesnil`), and neither does an ambiguous one inside it (`Vincent van Gogh`). The internal `Lexicon._sets.particles_ambiguous`, the particles holding a `given` reading, is its complement within `PARTICLES`, so the two mark OPPOSITE sets — see the flip warning in `docs/migrate.rst` before translating either
 - bound given names — `BOUND_GIVEN_NAMES` (`bound_given` readings, e.g. "abdul", "abu"; one that is also a particle needs a `given` reading, a build check); a group-stage rule joins the first non-title piece to its following piece before roles are assigned, reserving a family word unless a family comma has already fixed it or a given-name title stands ahead (#369, rules/P5) (ported from v1's `_join_bound_first_name`)
 - given names written short — `GIVEN_NAME_ABBREVIATIONS` (#789, a `given` reading carrying `same_as`, the full name: "chas", "wm", Filipino "ma"), the given names written short that rules/H2's shape yields to; nothing else reads it
+- names the two-name switches read — `PARTICLE_GIVEN_NAMES` (#704, a `given` reading written `after_particle`: "carmen", "ángeles", the Spanish words a compound given name writes behind a particle, `María del Carmen`) and `SHARED_NAMES` (#704, a name reading written `shared`: Sikh "kaur", "singh"), private; only rules/O7 and O6 read them, through classify's tags, so neither moves a parse with both switches off
 - conjunctions — `CONJUNCTIONS` (e.g. "and", "of") used to chain multi-word titles and to join name parts (rules/P3), plus `CONJUNCTIONS_AMBIGUOUS` (#383/#479, rules/P8, `may_be_initial`, refused by the build on anything but a cased single letter), the subset of single cased letters that read as an INITIAL in a name written wholly in one case — a marker set
 - maiden markers — `MAIDEN_MARKERS` (`birth_marker` readings, e.g. "née", "geb.") routing the following name to `maiden`; with an `addresses = "given"` title, the one kind a phrase may be (`z domu`)
 - `config/surnames.py`, a public module — `KOREAN_SURNAMES`, the census list the 2.0 API splits unspaced hangul on (#271), still written in Python with an import-time `assert_normalized`: a segmentation list, outside the per-word model, like the locale packs' lists.

docs/customize.rst

@@ -124,7 +124,8 @@ A kind belongs to a category, which decides what the reading does:
      - none
    * - name
      - ``given``, ``family``
-     - ``same_as="..."`` on ``given``
+     - ``same_as="..."`` and ``after_particle=True`` on ``given``;
+       ``shared=True`` on either
 
 ``nameparser/vocab/README.md`` in the repository says what each kind
 and property means. A property given its unwritten value (``None``,
@@ -1063,7 +1064,8 @@ hyphen or ``y`` joins them (``"Ana María García-López"``, ``"José
 Ortega y Gasset"``) or a particle chain took them both: a compound
 given name opening with a particle, such as ``"María del Carmen García
 López"``, reads family ``del Carmen García López`` with the switch on
-or off. A name of two words is unchanged, and a comma naming the family
+or off, until ``two_given_names`` below takes ``del Carmen`` into the
+given name. A name of two words is unchanged, and a comma naming the family
 decides by itself, so ``"García López, Ana"`` needs no switch at all. Under a family-first ``name_order`` the *first* two
 name words are the family.
 
@@ -1149,11 +1151,30 @@ two:
     >>> both.parse("Gabriel García Márquez").given
     'Gabriel'
 
-A given name a particle completes reads whole where a second particle
-starts the family (``"María del Carmen de la Vega"`` gives given
-``María del Carmen``); where the particle's words run to the end of
-the name, as in ``"Maria do Carmo Silva"``, they stay the family with
-the switch on or off, the same shape as ``"João da Silva Santos"``.
+A given name a particle completes reads whole too. Where the
+particle's words would otherwise run on into the family, the switch
+takes them only if the vocabulary marks the word behind the particle
+as a given name written there (``after_particle``). The Spanish ones
+are marked, those that ORCID's researchers from Spain and
+Spanish-speaking America write in the given box at least nine times
+for each ten they also open a family box with it (``del
+Carmen``, ``de los Ángeles``, ``del Mar``, ``del Pilar``: 23 words in
+all on 2026-11-03). A phrase too often a surname to mark, as Portuguese ``do Carmo``
+is, stays the family, the same shape as ``"João da Silva Santos"``:
+
+.. doctest::
+
+    >>> carmen = two_given.parse("María del Carmen García")
+    >>> carmen.given, carmen.family
+    ('María del Carmen', 'García')
+    >>> two_given.parse("Maria do Carmo Silva").family
+    'do Carmo Silva'
+
+To mark a word of your own, add it with ``Lexicon.default().add("carmo",
+kind="given", after_particle=True)``. The two switches also leave alone
+the Sikh names Kaur and Singh, given to every Sikh woman and man and
+written after the personal name: ``"Harpreet Kaur Dhillon"`` keeps
+middle ``Kaur`` under either switch, as it does by default.
 
 Turn it on only for data written this way: under it every name whose
 second given word is a middle name gains it in the given name