packages/docs/docs/forms.md

@@ -5,18 +5,33 @@ title: Forms
 
 # Forms
 
-The `Form` module is the low-level field model used by Effect-FC forms. A form
-field is built on the same state model as the rest of Effect-FC:
+The form modules provide an Effect-first model for editable, schema-validated
+state. They are not a visual component library. Instead, they give you
+Lenses/Subscribables for form values, validation issues, and commit state, so
+you can build the UI with whatever components your app already uses.
 
-- `encodedValue`: a `Lens` containing the raw value used by the input.
+The base `Form` type represents a field. A field tracks both the raw encoded
+value used by inputs and the decoded value produced by an Effect `Schema`:
+
+- `encodedValue`: a `Lens` containing the raw input value.
 - `value`: a `Subscribable` containing the decoded value as an `Option`.
 - `issues`: a `Subscribable` containing schema validation issues for that field.
 - `canCommit`, `isValidating`, and `isCommitting`: `Subscribable` flags for UI
   state.
 
-Most apps create a root form with `SubmittableForm` or `SynchronizedForm`, then
-focus it into fields with `Form.focusObjectOn`, `Form.focusArrayAt`, or the
-other focusing helpers.
+There are two root form flavors:
+
+- `SubmittableForm`: owns local encoded form state, validates it, and submits a
+  decoded value through a mutation.
+- `SynchronizedForm`: wraps an existing target `Lens` and writes valid changes
+  back to that target.
+
+Most apps create one of those root forms, then focus it into fields with
+`Form.focusObjectOn`, `Form.focusArrayAt`, or the other focusing helpers.
+
+The core form model is Effect code and can technically be used outside
+Effect-FC. Effect-FC adds the React-facing hooks, such as `Form.useInput`, that
+make those forms convenient to bind to components.
 
 ## Field Inputs