[Vulcan] Document given-name loss in surname-particle chains

[iliaal]

Summary

• Document a current first-name-loss limitation in default Western-order parsing: Della van Berg incorrectly produces an empty first name when Della is the intended given name.
• Show the verified explicit-comma workaround van Berg, Della, including credential tails.
• Scope the historical credential-tail changelog claim to cases it actually fixed (Della Smith, MD / Van Smith, MD).
• Correct source/test comments that previously said adjacent particles resolve ambiguity. They select a surname interpretation; that interpretation can be wrong.

This is documentation only, not a runtime fix. Changed parser outputs: none. Both modified PHP files have identical executable tokens to the base (comments/whitespace excluded). No new regression test is added to enshrine the known wrong interpretation.

Path sweep and remaining limitation

• Default Western pipeline: the first-name loss remains for Della van Berg, Della van der Berg, and Van de Berg.
• Nickname placement: Della (Bob) van Berg, (Bob) Della van Berg, Della van (Bob) Berg, and Della van Berg (Bob) retain the nickname but still lose the given-name field.
• Empty/credential comma tails reuse the Western first-segment pipeline; they do not fix this collision. Della van Berg, MD remains wrong.
• Explicit surname/given segments: van Berg, Della, van der Berg, Della, and credential/nickname variants preserve the intended fields.
• Surname-first mode selects its documented first-token surname interpretation; it is not covered by the default-Western limitation claim. The explicit comma workaround works in that mode too.
• Promoted stock/direct LastnameMapper paths share the same adjacent-particle heuristic. Custom mapper pipelines can choose different behavior for ordinary non-comma input; comma paths still use built-in segment pipelines.
• Neighbours Della Smith, Van Smith, van der Berg, and the established credential-tail cases remain unchanged.
• Reviewed README, CHANGELOG, source comments, and related surname/nickname/credential tests. This patch is disjoint from open [Vulcan] Clarify parsed-part mutation and fixed dictionary rendering #20's Editing parsed parts documentation and AbstractPart comment edits.

Verification

• BASE and HEAD documentation probes confirm every added example and close neighbours.
• Full PHPUnit on PHP 8.4.26: 1,242 tests, 3,271 assertions; no skips.
• PHPStan level 9 and PHP 8.5 compatibility configuration pass (512 MiB memory limit).
• PHP CS Fixer dry run, empty-baseline guard, PHP 8.5 deprecation grep, README punctuation check, and git diff --check pass.
• Independent read-only review passed; executable-token equality independently verified.
• All 86 remote blob contents, paths, and modes match the tested local index, tree 1b072166211c9f0287af61f3e471a547ebaeef56.
• Exact-head CI run 38353569859 passed all five jobs: PHP 8.3/8.4/8.5 tests (including Composer audit), Static Analysis, and Code Style. All reported steps succeeded; no skipped/build-only lane. Workflow security scan did not trigger because no workflow paths changed. Complete run/job/check listings inspected (1 run, 5 jobs/checks, no legacy statuses).
• Local runtime is PHP 8.4.26. No performance claim.

Base: e93f6afa3d25baa7b0a8de74c7488aacfb03408e
Head: 0318172f6c1e8478aebc11981b8f4c678a9e1d80