diff --git a/packages/boost/resources/boost/docs/core/actions.md b/packages/boost/resources/boost/docs/core/actions.md
index 4fea0367..39614312 100644
--- a/packages/boost/resources/boost/docs/core/actions.md
+++ b/packages/boost/resources/boost/docs/core/actions.md
@@ -186,6 +186,8 @@ Action::make('edit')
 
 The closure may hand back an enum case straight off a cast attribute (`fn ($record) => ['role' => $record->role]`): the seeded bag collapses every enum to its backing value, because that is what Livewire state carries to the browser and what a `Select` matches its `<option>` values against. The choice still saves back through the cast.
 
+The `$data` the callback receives is what the form **would have persisted**, not the raw widget state: on submit the modal runs the same field-level dehydration as `Form::save()` (see [Custom fields](../forms/custom-fields.md#shaping-the-value-a-field-stores)). A cleared `Select` arrives as `null` rather than `''`, a cleared `numeric()` `TextInput` as `null`, a `DateTimePicker` in its storage format and zone, and a `FileUpload` as its stored path. A wizard dehydrates every step, not only the one on screen at submit. Footer actions are deliberately excluded — they read the form mid-edit, before it is submitted.
+
 A `HeaderAction` form modal has **no record**, so its `fillFormUsing` closure takes no arguments. Use it to seed initial state — and always seed array-typed fields (`CheckboxList`, `Tags`, multiple `Select`) with an empty array so they bind correctly from the first interaction:
 
 ```php
diff --git a/packages/boost/resources/boost/docs/forms/custom-fields.md b/packages/boost/resources/boost/docs/forms/custom-fields.md
index e9e2539b..9e00eb24 100644
--- a/packages/boost/resources/boost/docs/forms/custom-fields.md
+++ b/packages/boost/resources/boost/docs/forms/custom-fields.md
@@ -334,7 +334,7 @@ directions. They are independent — implement only the one you need:
 | Contract | Method | Runs |
 |---|---|---|
 | `HydratesState` | `hydrateState($value, ?Model $record)` | model value → state, after the `getStateType()` cast |
-| `DehydratesState` | `dehydrateState($state, ?Model $record)` | state → stored value, during save |
+| `DehydratesState` | `dehydrateState($state, ?Model $record)` | state → stored value, on every write path |
 
 Note that the [`MoneyInput`](#building-a-custom-field) above needs *neither*: its
 state is already the integer it stores, which `getStateType(): 'int'` is enough to
@@ -376,6 +376,17 @@ The same two contracts drive [editable table columns](../table/columns/editing.m
 `TextInputColumn` uses them for its trim/case/number pipeline — so a component
 that implements them behaves the same in a form and in an inline-edited cell.
 
+**Three hosts run the write path, and they must agree.** `Form::save()` runs it
+through `SaveHandler`; an editable cell runs it in `updateTableCell()`; an
+[action modal](../core/actions.md#form-modal) runs it on submit, so the `$data`
+an action callback receives is what the form would have persisted rather than
+raw Livewire state. A host that skipped it would make the same schema write
+`null` through one path and `''` through another. The one deliberate exception
+is a [footer action](../core/actions.md#footer-actions): it reads the form
+mid-edit and writes back into the same bag, so dehydrating there would hand the
+callback a value the form no longer holds — and would run a `FileUpload`'s store
+on a form the user has not submitted.
+
 > **Both directions, or neither.** If a transform moves the value (a timezone
 > conversion, a unit change), implementing only `hydrateState()` means the shifted
 > state gets written straight back on save, moving the value a little further on
diff --git a/packages/boost/resources/boost/docs/forms/fields/text-input.md b/packages/boost/resources/boost/docs/forms/fields/text-input.md
index e1bc7bc6..8307072e 100644
--- a/packages/boost/resources/boost/docs/forms/fields/text-input.md
+++ b/packages/boost/resources/boost/docs/forms/fields/text-input.md
@@ -31,6 +31,24 @@ TextInput::make('age')->integer()
 | `search()` | `search` | Search input |
 | `type(string)` | Custom | Set HTML input type directly |
 
+## Cleared Values
+
+A cleared number input submits `''`, and no numeric column can hold that: MySQL
+in strict mode refuses the write outright (`Incorrect decimal value: ''`) and a
+lenient driver silently stores `0`. So a field whose HTML type is `number` —
+`numeric()`, `integer()`, `type('number')` — **stores `null` when it is left
+empty**, on every write path: `Form::save()`, an
+[action modal](../../core/actions.md#form-modal) submit, an editable cell.
+
+Every other type is left alone. `''` is a legitimate string value, and a
+non-nullable text column holds one; turning it into `null` would break the write
+rather than save it.
+
+```php
+TextInput::make('discount')->numeric()  // cleared → null
+TextInput::make('note')                 // cleared → ''
+```
+
 ## Constraints
 
 ```php