[Vulcan] Clarify parsed-part mutation and fixed dictionary rendering

README.md

@@ -120,6 +120,20 @@ $parser->parse('Dr. Jane A. Doe DDS')->toArray();
 `lastname` already includes any particle prefix (`de la Torre`);
 `lastname_prefix` is a convenience extract, not a component to prepend.
 
+### Editing parsed parts
+
+`getParts()` returns the part objects used by the `Name`. Calling `setValue()`
+on an ordinary name part updates its normalized output, even after a getter has
+cached it: changing a `Lastname` from `smith` to `jones` changes `getLastname()`
+from `Smith` to `Jones`. Initials also normalize their current value.
+
+Salutations, suffixes, and surname/middle-name prefixes keep the rendered form
+supplied at construction. Their `setValue()` changes only `getValue()`, so a
+suffix constructed from `md` with rendered form `MD` still renders `MD` after
+changing its raw value. Replace these objects through `Name::setParts()` when
+changing their rendered form. Editing parts does not update `getSource()` or
+rerun parsing; parse a revised input string when you need a new interpretation.
+
 ### Joint names
 
 An honorific can cover two people. The parser still returns one `Name`, and the

src/Part/AbstractPart.php

@@ -21,12 +21,11 @@ public function __construct(string|AbstractPart $value)
      * set the value to wrap
      * (can take string or part instance)
      *
-     * Parts are frozen after mapping: the mapper fixes the rendered form at
-     * map time (pre-normalized parts keep their dictionary form, camelcased
-     * parts memoize off the mapped value), so mutating a mapped part leaves
-     * normalize() out of sync with getValue(). The method stays public only
-     * for the released 1.x API (external callers mutate unmapped parts);
-     * Name::getPartner() defensively clones instead of re-pointing values.
+     * Clears the camelcase cache so ordinary name parts normalize the new
+     * value, including parts already returned by a mapper. Initials likewise
+     * normalize their current value. PreNormalized parts are the exception:
+     * setValue() changes their raw value but keeps the rendered form supplied
+     * at construction (salutations, suffixes, and surname/middle-name prefixes).
      */
     public function setValue(string|AbstractPart $value): static
     {