docs: document writing values in the method reference

displaying-fields told readers to see the Method Reference for writes and
the Method Reference had nothing on them. Adds a Writing Values section
covering assignment, arrays becoming nested collections, Smart values
unwrapping into the target's mode, and unset(), plus the note that row
positions are stamped at build time. Leaves out $rows[] = [...], which is
deprecated in favour of an explicit key. The cross-reference now deep-links
to the section.

Author: daveedis

docs/displaying-fields.md

@@ -167,8 +167,8 @@ echo $row->{0};             // zero (numeric keys)
 ```
 
 SmartArrays are writable too, with the same syntax in reverse:
-`$user->status = 'Active'`. Template code rarely needs it; see the
-[Method Reference](method-reference.md) when you do.
+`$user->status = 'Active'`. Template code rarely needs it; see
+[Writing Values](method-reference.md#writing-values) when you do.
 
 ---
 

docs/method-reference.md

@@ -50,6 +50,24 @@ and objects are always truthy in PHP, so test for missing values with
 | `->last()`     | Returns the last element                                                                   |
 | `->at($index)` | Returns the element at a position, ignoring keys: 0 is first, negatives count from the end |
 
+### Writing Values
+
+Collections are writable with the same syntax in reverse. A plain value is
+stored as-is, an array becomes a nested collection, and a Smart value from
+another collection unwraps and re-wraps for this one's mode. Reading a field
+back gives you a field, so output still encodes.
+
+```php
+$user->status = 'Active';            // sets a field
+$user->tags   = ['staff', 'admin'];  // stored as a nested collection
+unset($user->nickname);              // removes the key
+
+echo $user->status;                  // Active
+```
+
+Row positions are set when a collection is built, so `isFirst()`, `isLast()`,
+and `position()` don't change when you add or remove rows afterward.
+
 ### [Collection Checks](displaying-fields.md#showing-a-no-results-message)
 
 *These return plain values, typically used in if statements.*

tests/Integration/DocsExamplesTest.php

@@ -1019,6 +1019,21 @@ public function testMethodReferenceGetRawValueUnwrapsAnythingYouHandIt(): void
         $this->assertSame('plain', SmartArray::getRawValue('plain'));
     }
 
+    /** The Writing Values block: assignment, nested arrays, unset. */
+    public function testMethodReferenceWritingValuesStoresFieldsRowsAndRemovesKeys(): void
+    {
+        $user = SmartArrayHtml::new(['status' => 'Pending', 'nickname' => 'Jay']);
+
+        $user->status = 'Active';
+        $user->tags   = ['staff', 'admin'];
+        unset($user->nickname);
+
+        $this->assertSame('Active', (string)$user->status);
+        $this->assertInstanceOf(SmartArrayHtml::class, $user->tags);
+        $this->assertSame(['staff', 'admin'], $user->tags->toArray());
+        $this->assertSame(['status' => 'Active', 'tags' => ['staff', 'admin']], $user->toArray());
+    }
+
     //endregion
     //region Troubleshooting: empty() and if() checks