[iliaal]

Summary

• Correct setSurnameFirst() documentation: empty and credential-only comma tails also use first-token surname order, despite the old claim that only comma-less input was affected.
• Document the existing multi-token surname limitation and the explicit given-name comma workaround (van Gogh, Vincent), plus short-input fallback examples.
• Reconcile related source comments and add six executable boundary examples. No runtime behavior changes; PHP tokenization confirms executable tokens are identical to the base.

Scope and branch audit

Traced every caller of takeSurnameFirst(): parseInput() for space-separated input, parseSplitNameSegments() for empty comma tails, and parseSplitParts() when the tail has no given-name parts. Followed their early returns and the explicit-given-name path through the surname sub-parser. Existing tests cover the credential-only and single-token cases; new examples cover multi-token surnames, empty tails, explicit boundaries with credentials, and one token after a salutation. Grepped source/README for contradictory surname-first comments and corrected them.

This documents current behavior rather than changing parsing: setSurnameFirst(true)->parse('van Gogh Vincent') still returns lastname Van, firstname Gogh, middlename Vincent. The same limitation remains with an empty or credential-only comma tail; an explicit given-name segment preserves van Gogh. No parser path is represented as fixed.

Verification

• PHP 8.4.24 full PHPUnit suite: 1,226 tests / 3,186 assertions passed.
• SurnameFirstTest: 32 tests / 129 assertions passed, including six added examples.
• PHPStan level 9 and PHP 8.5 config passed with 512 MB memory limit.
• PHP-CS-Fixer dry run, empty-baseline guard, PHP 8.5 deprecation guard, README guard, and git diff --check passed.
• Independent review found no documentation defects and passed focused tests/style. Its separate full/performance runs hit timing-sensitive scaling assertions (combined initials during concurrent work; joint salutations on a later isolated run). The primary full run passed; no executable code changed. Initial local subprocess extension-configuration failures were resolved before the final checks.
• Remote head 41911190225887b21ecf84737c1cf434c6117d4a verified before publication: all 85 tracked file contents and modes match final tested tree e6793759fdaca7309b3a1491638410432eeac29d.
• Rechecked all open PRs/files before editing and publication. Sole sibling Keep surname particles together across nicknames #18 changes three different files; no overlap. Documentation-only change, so no Unreleased entry.

Local runtime is PHP 8.4 only. PHP 8.3/8.5 and dependency audit remain CI checks; no dependency or workflow changes.