diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7327881..bf3fe89 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,8 +17,9 @@ apply pending schema migrations before doing their work.
   but the command opened a raw PDO without running pending
   migrations. The rebuild then fired against the pre-2.2.0 schema
   (`fields.searchable = 0` everywhere) and silently produced an
-  empty/incorrect FTS body for every item. Hit while bumping
-  Scriptor; fixed before reaching the Hetzner demo. (#60)
+  empty/incorrect FTS body for every item. Caught during a
+  downstream lock-bump, before the broken recipe reached
+  production. (#60)
 - **`optimize` now auto-migrates too.** Same surprise was latent:
   running `VACUUM` before migrations wastes cycles because the next
   command applies new tables/columns anyway. (#60)
@@ -34,7 +35,7 @@ apply pending schema migrations before doing their work.
   now applies migration `0005` first, then rebuilds against the
   correct schema.
 - Diagnostic commands (`dump`, `repair`, `schema:status`) are
-  unchanged — they're expected to report on the actual on-disk
+  unchanged. They're expected to report on the actual on-disk
   state, so they must NOT auto-migrate.
 
 ## [2.2.0] — 2026-05-17
@@ -67,18 +68,19 @@ Design spec: [`docs/imanager-2.2-plan.md`](docs/imanager-2.2-plan.md).
 - **Migration `0005_searchable_defaults.sql`.** Promotes existing
   `text`/`longtext`/`editor`/`slug` field rows to `searchable = 1`
   on upgrade so installs keep their existing FTS coverage for
-  prose content. Verified against the live Scriptor schema: all 8
-  text-typed fields (slug, parent, pagetype, menu_title, content,
-  template, role, email) promote; password + fileupload fields
-  stay at 0. (#58)
-- **`FtsBody::compose()`** — single source of truth for the body
+  prose content. Verified against a representative production
+  schema: all text-typed field rows promote; `password` and
+  file-upload field rows stay at 0. (#58)
+- **`FtsBody::compose()`**: single source of truth for the body
   column written into `items_fts`. Used by both the per-save writer
   and the bulk rebuilder so they cannot drift. (#58)
 - **`SqliteItemRepository` constructor accepts optional
   `?FieldRepository`** as the third argument. The 2-arg signature
-  from 2.0/2.1 keeps working — falls back to "index everything"
+  from 2.0/2.1 keeps working: it falls back to "index everything"
   with a one-time `E_USER_DEPRECATED` notice on first FTS write.
   The no-arg form will become an error in 3.0. (#58)
+- **`docs/imanager-2.2-plan.md`**: design plan with the
+  recommended-lean decision log and open-questions register. (#56)
 
 ### Upgrading from 2.1.x
 
@@ -135,36 +137,36 @@ keeps working. Design spec: [`docs/imanager-2.1-plan.md`](docs/imanager-2.1-plan
 
 ### Added
 
-- **16 static factories on `Field`** for declarative schema setup —
+- **16 static factories on `Field`** for declarative schema setup:
   `Field::text()`, `longText()`, `editor()`, `slug()`, `password()`,
   `integer()`, `decimal()`, `money()`, `checkbox()`, `dropdown()`,
   `datepicker()`, `hidden()`, `arrayList()`, `file()`, `image()`,
   `filePicker()`. Each returns a fresh (`id = null`) `Field` with the
   corresponding `FieldType` set and default flags. (#47)
-- **Fluent setters on `Field` — general (6)**: `required(bool=true)`,
+- **General fluent setters on `Field` (6)**: `required(bool=true)`,
   `indexed(bool=true)`, `searchable(bool=true)`, `position(int)`,
   `label(string)`, `config(array)`. Each returns a new
   `final readonly` clone, preserving the value-object semantics. (#47)
-- **Fluent setters on `Field` — type-aware (7)**: `maxLength(int)`,
+- **Type-aware fluent setters on `Field` (7)**: `maxLength(int)`,
   `minLength(int)`, `placeholder(string)`, `maxBytes(int)`,
   `mimes(string ...)`, `options(array)`, `format(string)`. Each writes
   one documented key into `config`; unrecognised keys are silently
   ignored by built-in plugins, so a setter that doesn't apply to a
   given `FieldType` is a no-op. (#47)
-- **`CategoryRepository::ensure(Category): Category`** — upsert by
+- **`CategoryRepository::ensure(Category): Category`**. Upsert by
   natural key (`slug`). Insert-on-miss, return-existing-on-hit.
   Emits `CategoryCreated` only on insert. (#48)
-- **`FieldRepository::ensure(Field): Field`** — upsert by natural key
+- **`FieldRepository::ensure(Field): Field`**. Upsert by natural key
   `(categoryId, name)`. Same semantics as `CategoryRepository::ensure()`.
   Emits `FieldCreated` only on insert. (#48)
-- **`docs/imanager-2.1-plan.md`** — design plan with the full surface
-  + naming rationale + open-questions log. (#46)
+- **`docs/imanager-2.1-plan.md`**: design plan with the full surface,
+  naming rationale, and open-questions log. (#46)
 
 ### Fixed
 
 - **`Imanager::VERSION` is now bumped in lockstep with the git tag.**
   Previously the constant was set to `2.0.0` at 2.0 release and never
-  moved at 2.0.1 or 2.0.2 — `vendor/bin/imanager --version` reported
+  moved at 2.0.1 or 2.0.2, so `vendor/bin/imanager --version` reported
   the wrong value against any newer install. New `ReleaseConsistencyTest`
   asserts the constant matches the top-most `[X.Y.Z]` entry in
   CHANGELOG.md so this can't silently rot again.
@@ -174,8 +176,8 @@ keeps working. Design spec: [`docs/imanager-2.1-plan.md`](docs/imanager-2.1-plan
 `ensure()` is a new interface method on `CategoryRepository` and
 `FieldRepository`. Direct callers of the existing methods need no
 changes. **Third-party implementers** of these interfaces (no known
-implementers in the wild as of this release) need to add `ensure()`
-— the canonical 4-line implementation is documented in the JSDoc
+implementers in the wild as of this release) need to add `ensure()`.
+The canonical 4-line implementation is documented in the JSDoc
 of each interface method.
 
 ## [2.0.2] — 2026-05-16
@@ -188,7 +190,7 @@ of each interface method.
   copy-paste of the README quickstart no longer trips on PDO's
   `unable to open database file` error. Hosts that hand-wire via
   `Imanager\Bootstrap::boot()` keep full control of directory
-  lifecycle — the convenience is specific to the copy-paste factory.
+  lifecycle; the auto-`mkdir` is specific to the copy-paste factory.
   (#40)
 
 ### Fixed
@@ -197,7 +199,7 @@ of each interface method.
   parent directory** and suggests `mkdir -p <dir>` (or bootstrapping
   via `DefaultBootstrap`, which now does that itself) when the
   SQLite open fails because the parent doesn't exist. The previous
-  error surfaced as the raw PDO "unable to open database file" —
+  error surfaced as the raw PDO "unable to open database file",
   opaque even to seasoned PHP devs. (#40)
 
 ### Changed
diff --git a/README.md b/README.md
index b975999..abde3e2 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ iManager is a small CMS **framework**, not a CMS application: you embed
 it inside your own PHP app and get a typed domain model, a Repository
 layer over SQLite (JSON columns + FTS5), a Field-Type plugin system,
 file storage with on-demand thumbnails, and a CLI for schema and
-migration ops. Use it under any PHP front-end you like — a hand-rolled
+migration ops. Use it under any PHP front-end you like: a hand-rolled
 admin tool, a flat-file CMS, an internal API, a static-site generator
 that needs a typed content store. iManager has no opinion about how
 your application is shaped.
@@ -17,7 +17,7 @@ your application is shaped.
 
 ## Status
 
-**Stable** — current line **2.0.x** (latest: 2.0.2, 2026-05-16).
+**Stable**. Current line **2.2.x** (latest: 2.2.1, 2026-05-17).
 
 The 1.x line (flat-file, `var_export`-based, embedded library shape)
 stays available for legacy installs; see the
@@ -59,20 +59,18 @@ $categories = $container->get(CategoryRepository::class);
 $fields     = $container->get(FieldRepository::class);
 $items      = $container->get(ItemRepository::class);
 
-// One-time schema setup — run from an installer / migration, not on every
-// request. Repeating these three calls against the same database raises a
-// UNIQUE-constraint error; guard them with findBySlug() / findByName() if
-// you want them to be idempotent.
-$blog = $categories->save(new Category(null, 'Blog', 'blog'));
-$fields->save(new Field(null, $blog->id, 'title', 'Title', FieldType::Text));
-$fields->save(new Field(null, $blog->id, 'body',  'Body',  FieldType::LongText));
+// Schema setup: ensure() is idempotent (insert-on-miss, return-on-hit),
+// so this block is safe to run on every boot.
+$blog = $categories->ensure(new Category(null, 'Blog', 'blog'));
+$fields->ensure(new Field(null, $blog->id, 'title', 'Title', FieldType::Text));
+$fields->ensure(new Field(null, $blog->id, 'body',  'Body',  FieldType::LongText));
 
 // Persist an item.
 $items->save(new Item(
     null,
     $blog->id,
-    'hello-world',     // name  — URL-friendly identifier
-    'Hello, world',    // label — human-readable title
+    'hello-world',     // name:  URL-friendly identifier
+    'Hello, world',    // label: human-readable title
     data: ['title' => 'Hello, world', 'body' => 'First post.'],
 ));
 
@@ -91,7 +89,7 @@ pick up new migrations the same way.
 
 Need a leaner container or want to swap PDO / FileStorage / the
 event dispatcher? Use `Imanager\Bootstrap::boot()` instead and wire
-the parts you want — `DefaultBootstrap` is just a copy-paste-saver
+the parts you want. `DefaultBootstrap` is just a copy-paste-saver
 on top of it.
 
 ---
@@ -100,17 +98,17 @@ on top of it.
 
 iManager models content as four primitives:
 
-- **Category** — a kind of thing (e.g. *Blog*, *Page*, *User*). Each
+- **Category**: a kind of thing (e.g. *Blog*, *Page*, *User*). Each
   category has its own field schema and its own slug.
-- **Field** — a typed column on a category. The built-in field types
+- **Field**: a typed column on a category. The built-in field types
   are: `text`, `longtext`, `editor`, `slug`, `password`, `integer`,
   `decimal`, `money`, `checkbox`, `dropdown`, `datepicker`, `hidden`,
   `array`, `fileupload`, `imageupload`, `filepicker`. Custom types
   register via the `FieldTypePlugin` interface.
-- **Item** — an instance of a category. Field values live in a typed
+- **Item**: an instance of a category. Field values live in a typed
   `FieldValueBag` exposed as `$item->data`; hot fields are also
   promoted to SQLite generated columns for indexable queries.
-- **File** — a binary asset (upload). Files are stored under
+- **File**: a binary asset (upload). Files are stored under
   `<uploadsPath>/<itemId>/<fieldId>/` (the `uploadsPath` you pass to
   `DefaultBootstrap::boot()`), with on-demand thumbnails for image
   uploads under `thumbnail/<W>x<H>_<file>`.
@@ -134,7 +132,7 @@ container (`docker compose run --rm imanager vendor/bin/imanager …`).
 | `schema:migrate` | Apply pending migrations. |
 | `migrate:from-v1`| One-shot import of a 1.x `data/datasets/buffers/` tree. Supports `--dry-run`. |
 | `fts:rebuild`    | Drop & rebuild the FTS5 index from `items`. |
-| `optimize`       | `PRAGMA optimize` + `VACUUM`. |
+| `optimize`       | `PRAGMA optimize`. Add `--vacuum` to also run `VACUUM`. |
 | `repair`         | Integrity checks (orphan items, broken FKs, FTS sync). |
 | `dump`           | Portable SQL dump. |
 
@@ -175,26 +173,23 @@ Available composer scripts:
 
 ## Docs
 
-- **Tutorial**: [`docs/tutorial/`](docs/tutorial/) — task-oriented
+- **Tutorial**: [`docs/tutorial/`](docs/tutorial/), task-oriented
   walkthroughs for newcomers (setup, schema design, validation, …).
   Start here if you just installed the package and want a guided
   path past the Quickstart.
-- **API reference**: [`docs/api/`](docs/api/) — index plus core
+- **API reference**: [`docs/api/`](docs/api/), index plus core
   detail pages for Domain, Storage, Query, and Field types.
-- **Field-types cookbook**: [`docs/field-types.md`](docs/field-types.md)
-  — how-to companion to the Field-types reference.
-- **Query cookbook**: [`docs/query-cookbook.md`](docs/query-cookbook.md)
-  — predicate recipes, pagination, selector strings, full-text-search
+- **Field-types cookbook**: [`docs/field-types.md`](docs/field-types.md),
+  how-to companion to the Field-types reference.
+- **Query cookbook**: [`docs/query-cookbook.md`](docs/query-cookbook.md),
+  predicate recipes, pagination, selector strings, full-text-search
   hand-off, performance.
-- **Deployment guide**: [`docs/deployment.md`](docs/deployment.md)
-  — host requirements, webserver + PHP-FPM configs, a production
+- **Deployment guide**: [`docs/deployment.md`](docs/deployment.md),
+  host requirements, webserver + PHP-FPM configs, a production
   Dockerfile, SQLite at runtime, backups, scheduled maintenance.
 - **Migration guide** (1.x → 2.0):
   [`docs/migration-guide.md`](docs/migration-guide.md).
 - **Changelog**: [`CHANGELOG.md`](CHANGELOG.md).
-- **Implementation history** — the multi-phase 1.x → 2.0 rewrite plan,
-  kept for context now that the work is done:
-  [`docs/imanager-2.0-plan.md`](docs/imanager-2.0-plan.md).
 
 ---
 
diff --git a/docs/api/README.md b/docs/api/README.md
index 7e56fc1..920e1ce 100644
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -1,6 +1,6 @@
 # API Reference
 
-Reference documentation for the iManager 2.0 library — every public class
+Reference documentation for the iManager 2 library. Every public class
 you can wire, extend, or call from a host application.
 
 > **Where to start:** the [README quickstart](../../README.md#quickstart)
@@ -14,22 +14,22 @@ you can wire, extend, or call from a host application.
 ## Core (covered in detail here)
 
 The four pages below cover ~90 % of what host code touches. Read them
-in order if you're new — each one builds on the previous.
+in order if you're new. Each one builds on the previous.
 
-- **[Domain](domain.md)** — `Category`, `Field`, `Item`, `File`,
+- **[Domain](domain.md)**: `Category`, `Field`, `Item`, `File`,
   `FieldValueBag`, and the nine domain events (`*Created`, `*Updated`,
   `*Deleted`). All domain objects are `final readonly`; you mutate by
   saving a new value.
-- **[Storage](storage.md)** — the `Storage` interface and its four
+- **[Storage](storage.md)**: the `Storage` interface and its four
   repositories (`CategoryRepository`, `FieldRepository`,
   `ItemRepository`, `FileRepository`), `SqliteStorage` (the only
   bundled implementation), and the `transactional()` boundary. Also
   covers `SchemaManager` and `Migration`.
-- **[Query](query.md)** — the immutable `Query` builder, the
+- **[Query](query.md)**: the immutable `Query` builder, the
   `Clause` / `Operator` / `OrderBy` / `Direction` value objects,
   `Pagination`, and the `SelectorParser` shorthand
   (`name=Hello*, position>=5`).
-- **[Field types](field-types.md)** — the `FieldTypePlugin`
+- **[Field types](field-types.md)**: the `FieldTypePlugin`
   interface, `FieldTypeRegistry`, the 16 built-in plugins, and the
   `ValidationResult` / `RenderContext` value objects you return /
   receive when writing your own type.
@@ -63,16 +63,16 @@ tells you which source file to read next.
 
 ## Conventions used in this reference
 
-- **`final readonly`** — every domain primitive and most value objects
+- **`final readonly`**: every domain primitive and most value objects
   are immutable. Operations like `withId()`, `withTitle()`, or the
   builder methods on `Query` return a new instance.
-- **Method signatures** are quoted **verbatim** from the source — same
+- **Method signatures** are quoted **verbatim** from the source: same
   parameter names, defaults, and return types. If something looks
   surprising, check the file path at the top of each page; the source
   wins, this doc follows.
 - **Examples** are lifted from the contract tests under
   `tests/Unit/Storage/*Contract.php`. Those tests run against both
-  `SqliteStorage` and the `InMemory` storage shipped for testing — so
+  `SqliteStorage` and the `InMemory` storage shipped for testing, so
   every example you see compiles and is exercised on every CI run.
 - **Exceptions thrown** are listed under each method that can throw.
   Methods without a "Throws" line never throw in normal operation
@@ -85,16 +85,16 @@ tells you which source file to read next.
 The four core pages cover the public API any application boots
 against. Companion guides:
 
-- [`docs/field-types.md`](../field-types.md) — **cookbook** for
+- [`docs/field-types.md`](../field-types.md), the **cookbook** for
   writing custom field types end-to-end (anatomy, validation
   patterns, rendering patterns, registration, testing). The
   reference page [`field-types.md`](field-types.md) is the matching
   index.
-- [`docs/query-cookbook.md`](../query-cookbook.md) — **cookbook**
+- [`docs/query-cookbook.md`](../query-cookbook.md), the **cookbook**
   for the `Query` builder: predicate recipes, pagination flows,
   selector strings, full-text-search hand-off, performance.
   Matching reference page: [`query.md`](query.md).
-- [`docs/deployment.md`](../deployment.md) — **deployment guide**:
+- [`docs/deployment.md`](../deployment.md), the **deployment guide**:
   host requirements, filesystem layout, Caddy / nginx + PHP-FPM
   configs, a production Dockerfile, SQLite at runtime (WAL files,
   backups), scheduled maintenance, logging hookup, production
@@ -102,5 +102,5 @@ against. Companion guides:
 
 The smaller subsystems (Cache, Templating, Http, Events, Validation)
 will get their own reference pages **only if** non-trivial host
-extension is expected — for now their source files are short and
+extension is expected. For now their source files are short and
 documented inline.
diff --git a/docs/api/domain.md b/docs/api/domain.md
index 2efe124..5165f53 100644
--- a/docs/api/domain.md
+++ b/docs/api/domain.md
@@ -12,7 +12,7 @@ happens at the repository layer; the domain itself is just data.
 
 ## Category
 
-A kind of thing — `Blog`, `Page`, `User`. Each category owns its own
+A kind of thing: `Blog`, `Page`, `User`. Each category owns its own
 field schema and its own slug. Categories are uniquely identified by
 both `name` and `slug` within an install (the storage layer rejects
 duplicates on either column).
@@ -37,10 +37,10 @@ final readonly class Category
 
 ### Lifecycle
 
-- `id === null` — a fresh value object that has not been persisted.
+- `id === null`: a fresh value object that has not been persisted.
   Pass to `CategoryRepository::save()` to get back a clone with `id`
   assigned and `created`/`updated` populated.
-- `id !== null` — an already-persisted record. Saving again **updates**
+- `id !== null`: an already-persisted record. Saving again **updates**
   that row; the repository throws `NotFoundException` if the row no
   longer exists.
 
@@ -57,7 +57,7 @@ $blog = $categories->save(new Category(null, 'Blog', 'blog'));
 
 A typed column on a category. Every item in the category may carry a
 value for every defined field. Fields are uniquely identified by
-`(categoryId, name)` — the same `name` may exist in different
+`(categoryId, name)`. The same `name` may exist in different
 categories.
 
 ```php
@@ -95,13 +95,14 @@ final readonly class Field
 ### `config`
 
 An untyped `array<string,mixed>` whose shape is defined per
-field-type plugin (see [Field types](field-types.md)). Examples:
+field-type plugin (see [Field types](field-types.md) for the
+full key map per built-in). Examples:
 
-- `TextFieldType`: `['max' => 255]`
+- `TextFieldType`: `['maxLength' => 255, 'minLength' => 2]`
 - `DropdownFieldType`: `['options' => ['a' => 'Apple', 'b' => 'Banana']]`
-- `ImageuploadFieldType`: `['maxBytes' => 5_000_000, 'mimes' => ['image/jpeg', 'image/png']]`
+- `ImageuploadFieldType`: `['acceptedExtensions' => 'jpe?g|png', 'maxSizeBytes' => 5_000_000]`
 
-The repository round-trips `config` verbatim — it's the plugin's job
+The repository round-trips `config` verbatim: it's the plugin's job
 to make sense of its own shape.
 
 ### Example
@@ -120,7 +121,7 @@ An instance of a category. Field values live in a typed
 `FieldValueBag` exposed on `$item->data`. The bag is the *whole*
 payload; "hot" fields (those declared `indexed` on the schema) are
 copied into SQLite generated columns on save and kept in sync
-automatically — you don't write to them separately.
+automatically, you don't write to them separately.
 
 ```php
 namespace Imanager\Domain;
@@ -150,7 +151,7 @@ final readonly class Item
 The constructor accepts either an `array` or a `FieldValueBag` for
 ergonomics: most callers build items from arrays
 (`data: ['title' => 'Hello']`). Internally it's always coerced to a
-`FieldValueBag` — that's what you read back from `$item->data`.
+`FieldValueBag`, which is what you read back from `$item->data`.
 
 ### Example
 
@@ -192,7 +193,7 @@ final readonly class FieldValueBag
 ```
 
 The bag does **not** validate values against the field schema, and
-neither does `ItemRepository::save()` — the repository writes
+neither does `ItemRepository::save()`: the repository writes
 `Item::$data` verbatim. Validation is the host's responsibility:
 call `FieldTypeRegistry::get($field->type)->validate(...)` before
 constructing the `Item` you pass to `save()`. The
@@ -261,7 +262,7 @@ Convenience that checks the MIME prefix; thumbnail generation in
 
 Every successful repository mutation publishes one of nine events
 through the PSR-14 dispatcher wired in `DefaultBootstrap`. Subscribers
-receive the event *after* the SQLite transaction has committed — a
+receive the event *after* the SQLite transaction has committed. A
 listener that throws does **not** roll back the write.
 
 All events implement the marker interface `DomainEvent`:
@@ -330,8 +331,8 @@ final readonly class ItemUpdated implements DomainEvent
 
 ### Deleted events
 
-Deleted events only carry the *id* (and category id for fields/items)
-— by the time the event fires, the row is gone:
+Deleted events only carry the *id* (and category id for fields/items).
+By the time the event fires, the row is gone:
 
 ```php
 final readonly class CategoryDeleted implements DomainEvent
@@ -360,7 +361,7 @@ final readonly class ItemDeleted implements DomainEvent
 ```
 
 `FileCreated` / `FileUpdated` / `FileDeleted` are deliberately
-**not** emitted today — file metadata moves with item state and the
+**not** emitted today: file metadata moves with item state and the
 repository contract for files is intentionally narrower.
 
 ### Subscribing
@@ -379,7 +380,7 @@ $provider->subscribe(ItemDeleted::class, function (ItemDeleted $event): void {
 });
 ```
 
-Listener instantiation can be lazy — wrap the closure body in a
+Listener instantiation can be lazy, wrap the closure body in a
 `static $listener = null` guard if construction is expensive (e.g.
 the listener queries the DB on construct to learn which category id
 it watches).
diff --git a/docs/api/field-types.md b/docs/api/field-types.md
index 8444eb7..57dc5ba 100644
--- a/docs/api/field-types.md
+++ b/docs/api/field-types.md
@@ -6,7 +6,7 @@ Field types are the plugin layer that decides:
    row) is **coerced and validated** into a domain value.
 2. What **SQLite affinity** the value uses if it's promoted to a hot
    column.
-3. How the value is **rendered** as an HTML form input — for hosts
+3. How the value is **rendered** as an HTML form input, for hosts
    that lean on the library's rendering for their editor UI.
 
 This page is the **reference**: enum cases, the plugin interface,
@@ -23,7 +23,7 @@ how-to for writing your own type lives in the
 ## `FieldType` enum
 
 The 16 case names every install knows out of the box. The `value` of
-each case is also the string used in storage and in the registry — a
+each case is also the string used in storage and in the registry. A
 field's `type` is stored as this string in the `fields` table.
 
 ```php
@@ -54,7 +54,7 @@ enum FieldType: string
 
 `sqliteAffinity()` returns one of `Text` / `Integer` / `Real` /
 `Blob`. The result is consumed by the schema generator when a
-field is `indexed = true` — the generated column's type is derived
+field is `indexed = true`. The generated column's type is derived
 from this value.
 
 ---
@@ -86,28 +86,49 @@ interface FieldTypePlugin
 ### `name()` / `affinity()`
 
 Static because the registry needs to resolve them without
-instantiating the plugin. The `name()` is what the registry keys on
-— it **must** equal the `FieldType` enum value for built-ins, and
+instantiating the plugin. The `name()` is what the registry keys on:
+it **must** equal the `FieldType` enum value for built-ins, and
 should be a unique slug-like string for custom plugins. The
 `affinity()` mirrors `FieldType::sqliteAffinity()` for the same
-reason — schema codegen needs it before any instance exists.
+reason: schema codegen needs it before any instance exists.
 
 ### `defaultConfig()`
 
 Returns the field's `config` array when a host (typically an editor
-UI) creates a new field of this type. The shape is plugin-specific —
-the library never inspects it. Common patterns:
+UI) creates a new field of this type. The shape is plugin-specific.
+The library never inspects it. The exact keys each built-in plugin
+ships, with their defaults:
 
 | Plugin | `defaultConfig()` keys |
 |---|---|
-| `TextFieldType` | `min`, `max`, `pattern` |
-| `LongTextFieldType` | `max`, `format` (`'plain'` / `'markdown'`) |
-| `DropdownFieldType` | `options` (`array<string,string>`), `multiple` (`bool`) |
-| `IntegerFieldType` | `min`, `max` |
-| `MoneyFieldType` | `currency`, `precision` |
-| `ImageuploadFieldType` | `maxBytes`, `mimes`, `maxWidth`, `maxHeight` |
-| `FileuploadFieldType` | `maxBytes`, `mimes`, `multiple` |
-| `FilepickerFieldType` | `categoryId` (target items), `searchable` |
+| `TextFieldType` | `maxLength` (255), `minLength` (0), `placeholder` (`''`) |
+| `LongTextFieldType` | `maxLength` (65535), `minLength` (0), `rows` (6), `placeholder` (`''`) |
+| `EditorFieldType` | `mode` (`'markdown'`), `maxLength` (65535), `rows` (12) |
+| `SlugFieldType` | `maxLength` (128) |
+| `DatepickerFieldType` | `min` (`null`), `max` (`null`) |
+| `DropdownFieldType` | `options` (`array<string,string>`) |
+| `CheckboxFieldType` | `label` (`''`) |
+| `IntegerFieldType` | `min` (`null`), `max` (`null`), `step` (1) |
+| `DecimalFieldType` | `min` (`null`), `max` (`null`), `precision` (2) |
+| `MoneyFieldType` | `currency` (`'EUR'`), `min` (`null`), `max` (`null`), `precision` (2) |
+| `PasswordFieldType` | `minLength` (8), `placeholder` (`'(unchanged)'`) |
+| `HiddenFieldType` | `maxLength` (1024) |
+| `ArrayListFieldType` | `maxItems` (100), `itemMaxLength` (255), `rows` (6) |
+| `FilepickerFieldType` | `acceptedExtensions` (`'gif\|jpe?g\|png\|pdf'`) |
+| `FileuploadFieldType` | `acceptedExtensions` (`'gif\|jpe?g\|png\|pdf\|zip'`), `maxFiles` (10), `maxSizeBytes` (10 MiB) |
+| `ImageuploadFieldType` | `acceptedExtensions` (`'gif\|jpe?g\|png\|webp'`), `maxFiles` (10), `maxSizeBytes` (8 MiB), `thumbWidth` (150), `thumbHeight` (0) |
+
+> **Fluent setters vs runtime keys.** The 2.1.0 fluent setters
+> (`->maxBytes()`, `->mimes()`, `->format()`) write into config under
+> their *setter-name* key (`'maxBytes'`, `'mimes'`, `'format'`), which
+> the upload-typed plugins do **not** read at runtime: they read
+> `'maxSizeBytes'` and `'acceptedExtensions'`. The setter-name keys
+> persist as documentation alongside the schema, and runtime
+> enforcement happens through `UploadConstraints` rather than the
+> plugin's config (see the
+> [Files tutorial](../tutorial/files.md#constraints-in-two-places-read-this-twice)).
+> If you're setting upload constraints in code and want them honored
+> by the runtime, build `UploadConstraints` explicitly.
 
 ### `validate()`
 
@@ -118,16 +139,16 @@ the canonical domain form, **or refuse** with a specific error code:
 public function validate(mixed $rawValue, Field $field): ValidationResult;
 ```
 
-`$rawValue` is whatever the caller passed — a string, an int, an
+`$rawValue` is whatever the caller passed: a string, an int, an
 array, `null`, `false`. The plugin decides what it accepts. Return
 `ValidationResult::ok($coerced)` with the canonical value, or
 `ValidationResult::failed(InputErrorCode::*, $message)` to refuse.
 
-`validate()` is invoked by **host code** — typically the editor
+`validate()` is invoked by **host code**: typically the editor
 controller that receives the form submission. `ItemRepository::save()`
 itself writes `$item->data` verbatim and does **not** route values
 through the registry. The canonical pattern is "validate, then
-save" — the
+save". The
 [Field-types cookbook](../field-types.md#5-registering-a-custom-plugin)
 walks through the call shape.
 
@@ -139,7 +160,7 @@ that round-trips through `validate()`". Use `RenderContext::$inputName`
 as the form-field name; the snippet must be safe to drop inside any
 parent `<form>`.
 
-`render()` is purely an *editor* concern — your application's read
+`render()` is purely an *editor* concern: your application's read
 templates touch `$item->data->get($name)` directly and do their own
 rendering. If you don't host an editor UI, `render()` can return an
 empty string.
@@ -180,7 +201,7 @@ $registry = $container->get(FieldTypeRegistry::class);
 $registry->register(new MyColourPickerFieldType());
 ```
 
-A custom type appears under whatever `name()` returns — pick
+A custom type appears under whatever `name()` returns: pick
 something that won't collide with the 16 built-ins. The registry has
 no namespacing.
 
@@ -212,7 +233,7 @@ named constructors' use, not for callers.
 
 ### `InputErrorCode`
 
-The error vocabulary every plugin shares — `ItemRepository::save()`
+The error vocabulary every plugin shares: `ItemRepository::save()`
 propagates the code through `ValidationException`, and editor UIs
 can map codes to localised messages without parsing free-text. The
 enum lives at `src/Enum/InputErrorCode.php`; the numeric values are
@@ -233,21 +254,21 @@ enum InputErrorCode: int
 }
 ```
 
-- `EmptyRequired` — empty value on a `required` field. Checked first.
-- `MinLengthExceeded` / `MaxLengthExceeded` — string-length bounds
+- `EmptyRequired`: empty value on a `required` field. Checked first.
+- `MinLengthExceeded` / `MaxLengthExceeded`: string-length bounds
   (`config.minLength` / `config.maxLength`) violated.
-- `WrongValueFormat` — value's shape is wrong: dropdown key not in
+- `WrongValueFormat`: value's shape is wrong: dropdown key not in
   `options`, integer field got a non-numeric string, date string
   doesn't parse. Catch-all for "the input doesn't make sense for
   this type".
-- `ComparisonFailed` — cross-value or range comparison failed
+- `ComparisonFailed`: cross-value or range comparison failed
   (numeric `min`/`max`, password-confirmation mismatch, date
   ordering).
-- `UndefinedCategoryId` — reference-typed field (`filepicker`)
+- `UndefinedCategoryId`: reference-typed field (`filepicker`)
   points at a category that doesn't exist.
 
 If none of these fit your plugin's failure mode, collapse the case
-into `WrongValueFormat` rather than inventing new ones — the shared
+into `WrongValueFormat` rather than inventing new ones. The shared
 vocabulary is what lets host editors map codes to localised messages
 without parsing free-text.
 
@@ -269,13 +290,13 @@ final readonly class RenderContext
 }
 ```
 
-- `$inputName` — what the form-field's `name=""` attribute must be.
+- `$inputName`: what the form-field's `name=""` attribute must be.
   The hosting editor decides this (often `"data[<fieldname>]"`).
-- `$itemId` — `null` for "create" forms, the item id for "edit"
+- `$itemId`: `null` for "create" forms, the item id for "edit"
   forms. Useful for file-typed plugins that need to render an
   existing-attachment list.
 
-The context is deliberately tiny — anything more (CSRF token, asset
+The context is deliberately tiny: anything more (CSRF token, asset
 base URL, current locale) is the *host's* concern. A plugin that
 needs more context should accept it via constructor injection when
 the host registers it.
@@ -293,7 +314,7 @@ what SQLite type the generated column gets if you flip
 |---|---|---|---|
 | `Text` | `TextFieldType` | `Text` | Single-line `<input type="text">`. `config.min`, `config.max`, `config.pattern`. |
 | `LongText` | `LongTextFieldType` | `Text` | `<textarea>`. `config.format` toggles markdown render via `Sanitizer`. |
-| `Editor` | `EditorFieldType` | `Text` | Rich-text — same storage as `LongText`, different render hint for the host editor. |
+| `Editor` | `EditorFieldType` | `Text` | Rich-text: same storage as `LongText`, different render hint for the host editor. |
 | `Slug` | `SlugFieldType` | `Text` | Auto-derives from a source field on the same form; rejects collisions in the host. |
 | `Datepicker` | `DatepickerFieldType` | `Text` | Stores ISO-8601 date strings. |
 | `Dropdown` | `DropdownFieldType` | `Text` | `config.options`, optional `config.multiple` (stores comma-joined / array). |
@@ -309,8 +330,8 @@ what SQLite type the generated column gets if you flip
 | `Imageupload` | `ImageuploadFieldType` | `Text` | Subset of `Fileupload` constrained to image MIMEs; `ImageProcessor` renders on-demand thumbnails. `config.maxWidth`, `config.maxHeight`. |
 
 Each plugin's source file is short (typically 60–120 lines) and is
-the authoritative answer for "what exactly does this type accept?"
-— if a docstring here ever disagrees with the source, the source
+the authoritative answer for "what exactly does this type accept?".
+If a docstring here ever disagrees with the source, the source
 wins.
 
 ---
@@ -337,7 +358,7 @@ final class ColourFieldType implements FieldTypePlugin
     public function validate(mixed $rawValue, Field $field): ValidationResult
     {
         if (! is_string($rawValue) || ! preg_match('/^#[0-9a-f]{6}$/i', $rawValue)) {
-            return ValidationResult::failed(InputErrorCode::PatternMismatch, 'Expected #rrggbb');
+            return ValidationResult::failed(InputErrorCode::WrongValueFormat, 'Expected #rrggbb');
         }
         return ValidationResult::ok(strtolower($rawValue));
     }
@@ -352,7 +373,7 @@ final class ColourFieldType implements FieldTypePlugin
 ```
 
 Register on the container's registry once and the type can be used
-on any new `Field` going forward. There's nothing else to wire — the
+on any new `Field` going forward. There's nothing else to wire: the
 storage layer reads the type's `name()` from `fields.type` and looks
 it up in the registry whenever a value flows through `validate()`.
 
diff --git a/docs/api/query.md b/docs/api/query.md
index dfd5f2b..05a9966 100644
--- a/docs/api/query.md
+++ b/docs/api/query.md
@@ -39,14 +39,14 @@ final readonly class Query
 }
 ```
 
-Every method returns a **new** `Query` — the receiver is unchanged.
+Every method returns a **new** `Query`; the receiver is unchanged.
 You can pass the same base query to many call sites and refine each
 independently without worrying about shared state.
 
 ### `inCategory()`
 
 Restricts the result to one category. **A query without
-`inCategory()` searches across all categories** — useful for
+`inCategory()` searches across all categories**. Useful for
 admin-side global searches, dangerous as the default for application
 code. Set it.
 
@@ -55,20 +55,20 @@ code. Set it.
 Adds one predicate. The operator argument accepts either the
 `Operator` enum or a literal string (`'='`, `'!='`, `'>'`, `'<'`,
 `'>='`, `'<='`, `'LIKE'`); the string form coerces to the enum
-internally. Multiple `where()` calls AND together — there is **no
+internally. Multiple `where()` calls AND together; there is **no
 OR**. Build OR-shaped logic with a `SelectorParser` source string or
 union the results of two queries application-side.
 
 The field name can be:
 
-- A *structural column* — `id`, `name`, `label`, `position`,
+- A *structural column*: `id`, `name`, `label`, `position`,
   `active`, `created`, `updated`, `categoryId`.
 - A *field name* declared on the category. Hot (indexed) fields hit
   the generated column; cold fields use `json_extract`.
 
 ### `orderBy()`
 
-Adds one ordering step. Calls compose (left-to-right precedence —
+Adds one ordering step. Calls compose (left-to-right precedence:
 first call wins ties). Direction accepts the `Direction` enum, the
 strings `'asc'` / `'desc'` (case-insensitive), or its constants.
 
@@ -161,7 +161,7 @@ final readonly class OrderBy
 ```
 
 `Query::orderBy()` constructs one of these per call. Multi-column
-ordering is just multiple consecutive `orderBy()` calls — there is no
+ordering is just multiple consecutive `orderBy()` calls; there is no
 "add a tiebreaker" helper because chained calls already read that
 way:
 
@@ -189,7 +189,7 @@ enum Direction: string
 
 `coerce()` accepts the enum or a case-insensitive string and throws
 `\ValueError` on unknown input. `Query::orderBy()` calls it on your
-behalf — you can pass either form.
+behalf; you can pass either form.
 
 ---
 
@@ -263,7 +263,7 @@ selector  := clause (',' clause)*
 clause    := identifier op value
 op        := '>=' | '<=' | '!=' | '=' | '>' | '<'
 identifier := [A-Za-z_][A-Za-z0-9_]*
-value     := bare (no escaping) — leading/trailing whitespace stripped
+value     := bare (no escaping); leading/trailing whitespace stripped
 ```
 
 A literal `%` inside a `value` paired with `=` is treated as a
@@ -277,7 +277,7 @@ A literal `%` inside a `value` paired with `=` is treated as a
 | `categoryId=3, name=foo` | `where('categoryId', '=', 3)->where('name', '=', 'foo')` |
 
 `SelectorParser` does **not** consume `inCategory()`,
-`orderBy()`, `limit()`, or `offset()` — keep those in code. The
+`orderBy()`, `limit()`, or `offset()`; keep those in code. The
 parser exists so you can express filters declaratively (in a config
 file, a URL parameter, an editor preset) without exposing PHP
 construction syntax.
@@ -302,7 +302,7 @@ $query  = $parser->parse('active=1, position>=10')
   defining the schema.
 - **Wildcards in `LIKE`.** A trailing wildcard (`'Hello%'`) can use
   an index. A leading wildcard (`'%Hello'`) cannot and will scan the
-  table — prefer `Imanager\Search\FullTextSearch` for free-text
+  table. Prefer `Imanager\Search\FullTextSearch` for free-text
   prefixes.
 - **`count()` does its own SELECT.** Calling `count()` and `query()`
   is two queries; cache `count()` if you also call `query()` against
diff --git a/docs/api/storage.md b/docs/api/storage.md
index b50cd02..472e875 100644
--- a/docs/api/storage.md
+++ b/docs/api/storage.md
@@ -2,7 +2,7 @@
 
 The storage subsystem is **four repository contracts** plus one
 implementation (`SqliteStorage`). Everything host code talks to is
-defined by an interface — swap the implementation, keep your code.
+defined by an interface: swap the implementation, keep your code.
 
 > Source: `src/Storage/{Storage,CategoryRepository,FieldRepository,ItemRepository,FileRepository,SchemaManager,Migration}.php`,
 > `src/Storage/Sqlite/SqliteStorage.php`, `src/Storage/InMemory/`.
@@ -13,7 +13,7 @@ defined by an interface — swap the implementation, keep your code.
 
 ## Storage interface
 
-The umbrella interface — one object holds references to the four
+The umbrella interface: one object holds references to the four
 repositories and to the transaction boundary.
 
 ```php
@@ -55,8 +55,8 @@ interface CategoryRepository
 
 ### Reads
 
-- `find()` and `findBySlug()` return `null` for unknown identifiers —
-  they do **not** throw.
+- `find()` and `findBySlug()` return `null` for unknown identifiers.
+  They do **not** throw.
 - `findAll()` returns categories ordered by `position`, then `id`.
 
 ### `save()`
@@ -102,7 +102,7 @@ interface FieldRepository
 
 ### Reads
 
-- `findByName()` is the standard lookup — fields are uniquely
+- `findByName()` is the standard lookup: fields are uniquely
   identified by `(categoryId, name)`.
 - `findByCategory()` returns fields ordered by `position`, then
   `id`.
@@ -156,7 +156,7 @@ order":
 
 ### `query()` and `count()`
 
-The general-purpose entry point — accepts an immutable `Query`
+The general-purpose entry point: accepts an immutable `Query`
 value object (see [Query](query.md)). `count()` runs the same
 predicate as `query()` but returns the row count instead of the
 hydrated items. Useful for pagination headers.
@@ -164,7 +164,7 @@ hydrated items. Useful for pagination headers.
 ### `save()`
 
 - Writes `$item->data` to the SQLite `data` column **verbatim**.
-  `save()` does **not** invoke field-type plugins — validation is
+  `save()` does **not** invoke field-type plugins; validation is
   the host's responsibility (see the
   [Field-types cookbook](../field-types.md#the-validation-pipeline)
   for the canonical "validate before save" pattern). If you skip
@@ -174,7 +174,7 @@ hydrated items. Useful for pagination headers.
   save. Run your input through `FieldTypeRegistry::get($field->type)->validate(...)`
   before constructing the `Item`.
 - Promotes "hot" (indexed) field values into generated columns
-  automatically — you do **not** need to update them separately.
+  automatically. You do **not** need to update them separately.
 - **Throws `NotFoundException`** if you save an item with a
   non-existent `categoryId`, or update an item whose `id` no longer
   exists.
@@ -244,17 +244,18 @@ For each field that has `indexed = true`, the SQLite schema carries a
 generated column:
 
 ```sql
-"field_<name>" AS (json_extract(data, '$.<name>')) STORED
+gen_<categoryId>_<fieldName> AS (json_extract(data, '$.<fieldName>')) VIRTUAL
 ```
 
+plus a matching index on `(category_id, gen_<categoryId>_<fieldName>)`.
 The column's storage affinity follows `FieldType::sqliteAffinity()`
-(text, integer, real, blob). You query against `field_<name>` via
-the normal `Query` builder; the builder picks the generated column
-automatically when the field is hot, and falls back to
-`json_extract(data, ...)` when it isn't.
+(text, integer, real, blob). You query against the generated column
+via the normal `Query` builder; the builder picks it automatically
+when the field is hot, and falls back to `json_extract(data, ...)`
+when it isn't.
 
 Toggling `indexed` from `false` → `true` on an existing field requires
-a schema migration — it changes the table shape. The library does
+a schema migration: it changes the table shape. The library does
 **not** auto-migrate on save; you write the migration explicitly under
 `config/schema/` and run `schema:migrate`.
 
@@ -269,7 +270,7 @@ public function transactional(callable $work): mixed;
 `SqliteStorage::transactional()` wraps the callback in
 `BEGIN IMMEDIATE` / `COMMIT`, rolls back on any exception, and
 returns whatever the callback returned. Domain events are dispatched
-**after** commit — a listener that throws does not undo the work.
+**after** commit; a listener that throws does not undo the work.
 
 ```php
 $itemId = $storage->transactional(function () use ($storage, $blog) {
@@ -279,15 +280,15 @@ $itemId = $storage->transactional(function () use ($storage, $blog) {
 });
 ```
 
-Nested calls are **not** supported — `SqliteStorage` will throw on a
+Nested calls are **not** supported: `SqliteStorage` will throw on a
 nested `transactional()`. Compose your work as one outer transaction.
 
 ---
 
 ## SqliteStorage
 
-The bundled implementation. You normally never construct it directly
-— `DefaultBootstrap::boot()` does. Construct manually only when you
+The bundled implementation. You normally never construct it directly;
+`DefaultBootstrap::boot()` does. Construct manually only when you
 want a different PDO or a different event dispatcher:
 
 ```php
@@ -352,15 +353,16 @@ The bundled migrations under `config/schema/` are:
 
 | Version | File | What it does |
 |---|---|---|
-| `0001` | `0001_initial.php` | `categories`, `fields`, `items`, `schema_version`. |
-| `0002` | `0002_fts.php` | FTS5 mirror over `items` + sync triggers. |
-| `0003` | `0003_files.php` | `files` table with item / field foreign keys. |
-| `0004` | `0004_files_title.php` | `files.title` column for human captions. |
+| `0001` | `0001_initial.sql` | `categories`, `fields`, `items`, `schema_version`. |
+| `0002` | `0002_fts.sql` | FTS5 mirror over `items` + sync triggers. |
+| `0003` | `0003_files.sql` | `files` table with item / field foreign keys. |
+| `0004` | `0004_files_title.sql` | `files.title` column for human captions. |
+| `0005` | `0005_searchable_defaults.sql` | Promotes existing prose-typed fields (`text`/`longtext`/`editor`/`slug`) to `searchable = 1` so 2.2.0's per-field FTS filter keeps existing coverage. |
 
 Migrations are applied in `version()` order. `currentVersion()` is
 the **highest** applied version. `pending()` enumerates everything
 above that. `migrate()` returns the count of migrations actually
-applied this call — `0` is normal on a hot start.
+applied this call; `0` is normal on a hot start.
 
 ---
 
@@ -370,16 +372,16 @@ All storage exceptions implement the marker interface
 `Imanager\Exception\ImanagerException`. You can catch any specific
 type, or catch the marker if you want a single net:
 
-- `NotFoundException` — repository can't locate the requested row
+- `NotFoundException`: repository can't locate the requested row
   (delete of nothing, save of unknown id, save against unknown
   category).
-- `ValidationException` — value rejected by a field-type plugin, or
+- `ValidationException`: value rejected by a field-type plugin, or
   a uniqueness constraint failed. Carries the field name and
   `InputErrorCode` when raised by a plugin.
-- `StorageException` — any other SQLite-layer failure (constraint
+- `StorageException`: any other SQLite-layer failure (constraint
   violation we didn't anticipate, transient I/O). Wraps the
   underlying `PDOException` as `$previous`.
-- `SchemaException` — `SchemaManager` could not parse or apply a
+- `SchemaException`: `SchemaManager` could not parse or apply a
   migration.
 
 ---
diff --git a/docs/deployment.md b/docs/deployment.md
index 78a4c06..4394f41 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -1,12 +1,12 @@
 # Deployment guide
 
-iManager is a library, not an application — so this guide isn't
+iManager is a library, not an application: so this guide isn't
 about "deploying iManager". It's about what your application needs
 when it ships **with iManager embedded**: host requirements,
 filesystem layout, webserver config, backups, and scheduled
 maintenance.
 
-If you're building locally, you don't need any of this — the
+If you're building locally, you don't need any of this: the
 [README quickstart](../README.md#quickstart) is enough. Come back
 when you're ready to put a host on the public internet.
 
@@ -33,9 +33,10 @@ php -r 'foreach (["pdo_sqlite","mbstring","gd","dom","json","opcache"] as $e) {
 
 ## 2. Filesystem layout
 
-`DefaultBootstrap::boot()` takes four paths. **All three of the
-"directory" paths must be writable by the PHP-FPM user** — the
-library creates files and subdirectories under them at runtime.
+`DefaultBootstrap::boot()` takes four paths. **The three directory
+paths (everything except `uploadsUrl`) must be writable by the
+PHP-FPM user**: the library creates files and subdirectories under
+them at runtime.
 
 ```php
 use Imanager\DefaultBootstrap;
@@ -50,16 +51,16 @@ $container = DefaultBootstrap::boot(
 
 | Path | Used for | Writable? |
 |---|---|---|
-| `databasePath` | The SQLite file itself. The library also creates `<databasePath>-wal` and `<databasePath>-shm` sidecar files (WAL mode is on by default — see [§5](#5-sqlite-at-runtime)). | **The parent directory** must be writable so SQLite can create the sidecars. |
+| `databasePath` | The SQLite file itself. The library also creates `<databasePath>-wal` and `<databasePath>-shm` sidecar files (WAL mode is on by default, see [§5](#5-sqlite-at-runtime)). | **The parent directory** must be writable so SQLite can create the sidecars. |
 | `uploadsPath` | Item file attachments (`Fileupload` / `Imageupload` fields). Subdirectories are created lazily per upload. | **Yes.** |
-| `uploadsUrl` | The public URL prefix used to build asset URLs. **No filesystem use** — the webserver maps it to `uploadsPath`. | n/a |
+| `uploadsUrl` | The public URL prefix used to build asset URLs. **No filesystem use**: the webserver maps it to `uploadsPath`. | n/a |
 | `cachePath` | The PSR-16 filesystem cache. Two-level sha256-hashed directory fanout. | **Yes.** |
 
 ### Recommended layout
 
 ```
 app/
-├── public/                       # webroot — DocumentRoot points here
+├── public/                       # webroot, DocumentRoot points here
 │   ├── index.php                 # front controller
 │   └── uploads/  -> ../var/uploads  (symlink, or alias in webserver)
 ├── src/                          # your application code
@@ -80,7 +81,7 @@ Three rules:
 1. **`var/data/` MUST NOT be webroot-accessible.** Don't put it
    under `public/`. The webserver should never see `.db`, `-wal`,
    or `-shm` files.
-2. **`var/cache/` MUST NOT be webroot-accessible** either —
+2. **`var/cache/` MUST NOT be webroot-accessible** either:
    cached fragments are application internals.
 3. **`var/uploads/` IS public.** Either symlink it into `public/`
    or use a webserver alias (see [§3](#3-webserver-configuration)).
@@ -99,13 +100,13 @@ chmod -R u=rwX,go=rX var/uploads         # FPM-writable, world-readable
 ```
 
 The exact mode depends on whether `www-data` is also the user that
-runs deployments — adjust the group bits accordingly.
+runs deployments. Adjust the group bits accordingly.
 
 ---
 
 ## 3. Webserver configuration
 
-iManager doesn't ship a router or a front controller — those are
+iManager doesn't ship a router or a front controller: those are
 your application's concern. What the webserver needs to know:
 
 - Route everything **except** `/uploads/*` and static assets to
@@ -140,7 +141,7 @@ example.com {
 ```
 
 Caddy's `php_fastcgi` directive already routes anything that
-doesn't match a static file through `index.php` — you usually
+doesn't match a static file through `index.php`, you usually
 don't need a separate try_files clause.
 
 ### nginx + PHP-FPM
@@ -151,7 +152,7 @@ server {
     root /srv/app/public;
     index index.php;
 
-    # Public uploads — served by nginx, no PHP.
+    # Public uploads, served by nginx, no PHP.
     location /uploads/ {
         alias /srv/app/var/uploads/;
         try_files $uri =404;
@@ -186,7 +187,7 @@ server {
 }
 ```
 
-The `internal` directive on the PHP location matters — without it,
+The `internal` directive on the PHP location matters: without it,
 clients can hit `/index.php/anything` directly and bypass the front
 controller's URL rewriting.
 
@@ -226,7 +227,7 @@ php_admin_value[realpath_cache_size] = 4M
 php_admin_value[realpath_cache_ttl]  = 600
 ```
 
-`opcache.validate_timestamps = 0` is the big production switch — it
+`opcache.validate_timestamps = 0` is the big production switch: it
 turns off per-request file-modification checks. The tradeoff is
 that you have to clear opcache on deploy (`cachetool` or a small
 PHP-FPM reload). For staging or hosts that deploy via plain
@@ -300,7 +301,7 @@ Pair it with a `docker-compose.yml` that has nginx (or Caddy) as a
 sibling service, sharing `/app/public` and `/app/var/uploads` as
 read-only volumes for the webserver. The persistent volumes are
 `/app/var/data` (the SQLite file) and `/app/var/uploads` (the
-attachments) — those are the only two things your backup strategy
+attachments). Those are the only two things your backup strategy
 needs to know about.
 
 ---
@@ -317,7 +318,7 @@ every connect:
 | `synchronous` | `NORMAL` | WAL-safe; gives up only a small durability window on power loss. Most production setups want this; switch to `FULL` only if you're running on hardware that lies about fsync. |
 | `temp_store` | `MEMORY` | Temp tables / sort buffers live in RAM. Modest win for query-heavy workloads. |
 
-You don't need to set these yourself — the library does it on
+You don't need to set these yourself: the library does it on
 connect.
 
 ### WAL files
@@ -327,19 +328,19 @@ WAL mode produces two sidecar files: `<db>-wal` and `<db>-shm`.
 the directory must be writable by FPM.** Containers / volumes /
 NFS mounts that mark the database file writable but the directory
 read-only are a common cause of "database is locked" errors at
-runtime — check the directory mode first.
+runtime: check the directory mode first.
 
 The WAL file can grow during traffic spikes; SQLite checkpoints it
 back into the main DB automatically (every 1000 pages by default).
 A persistent large `-wal` usually means your VACUUM cadence is too
-aggressive and is racing with active writes — back off.
+aggressive and is racing with active writes: back off.
 
 ### Concurrency model
 
 WAL gives you N readers + 1 writer concurrently. For an iManager
 workload (CMS-shaped: lots of reads, occasional writes from editor
 saves), that's plenty. If you genuinely outgrow single-writer
-SQLite, the answer isn't a different SQLite tuning — it's a
+SQLite, the answer isn't a different SQLite tuning: it's a
 different storage backend, and the `Storage` interface is where to
 swap it.
 
@@ -352,7 +353,7 @@ You back up **two things**:
 1. The SQLite database (`var/data/imanager.db` + its `-wal` + `-shm`).
 2. The uploads directory (`var/uploads/`).
 
-The cache directory is not backed up — it regenerates on demand.
+The cache directory is not backed up: it regenerates on demand.
 
 ### Online SQLite backup (recommended)
 
@@ -367,10 +368,10 @@ DB=/srv/app/var/data/imanager.db
 DEST=/srv/backups/$(date +%F)
 mkdir -p "$DEST"
 
-# Atomic .backup — writers can keep going while this runs.
+# Atomic .backup: writers can keep going while this runs.
 sqlite3 "$DB" ".backup '$DEST/imanager.db'"
 
-# Uploads — incremental rsync.
+# Uploads: incremental rsync.
 rsync -a --delete /srv/app/var/uploads/ "$DEST/uploads/"
 
 # Compress yesterday's backup; keep last 30 days.
@@ -384,15 +385,15 @@ What this gives you:
 - **No write downtime.** `.backup` doesn't lock the writer.
 - **30 days of history**, compressed after the day rolls over.
 
-For point-in-time recovery beyond 24 h, look into [Litestream](https://litestream.io/)
-— it streams WAL changes to S3 (or any S3-compatible bucket)
+For point-in-time recovery beyond 24 h, look into [Litestream](https://litestream.io/):
+it streams WAL changes to S3 (or any S3-compatible bucket)
 continuously. The trade-off is one more daemon on the box; the
 upside is recovery to any point within the retention window.
 
 ### What NOT to do
 
 - **Do not `cp imanager.db backup.db`** with the database under
-  active writes. You'll capture the main file but not the WAL —
+  active writes. You'll capture the main file but not the WAL;
   the backup is corrupt as far as SQLite is concerned.
 - **Do not back up `-wal` and `-shm` separately** and try to
   reassemble. The triple is consistent only as captured by a
@@ -437,7 +438,7 @@ commands. The ones you schedule:
 | `optimize --db=<db>` | Runs `PRAGMA optimize`. Updates SQLite's query planner stats and prunes redundant index information. Cheap; safe on a live DB. | **Weekly.** |
 | `optimize --db=<db> --vacuum` | The above, plus `VACUUM`. Rewrites the database file to reclaim space and reduce fragmentation. **Locks the DB while it runs** (minutes for a ~1 GB file). | **Quarterly,** during a maintenance window. Not weekly. |
 | `repair --db=<db>` | Runs `PRAGMA integrity_check` and `PRAGMA foreign_key_check`. Reports rows that don't satisfy constraints. **Read-only.** | **Monthly.** Run as part of your backup verification. |
-| `fts:rebuild --db=<db>` | Drops and rebuilds the FTS5 index from `items`. Required after bulk inserts that bypassed the repository, or after changing the tokenizer config. | **On demand.** Not scheduled — the FTS index is kept in sync incrementally on every save. |
+| `fts:rebuild --db=<db>` | Drops and rebuilds the FTS5 index from `items`. Required after bulk inserts that bypassed the repository, or after changing the tokenizer config. | **On demand.** Not scheduled: the FTS index is kept in sync incrementally on every save. |
 
 A reasonable systemd-timer-driven setup:
 
@@ -460,14 +461,14 @@ Persistent=true
 WantedBy=timers.target
 ```
 
-The `Persistent=true` matters — if the host is off when the timer
+The `Persistent=true` matters: if the host is off when the timer
 fires, it runs at next boot rather than skipping.
 
 ### Why no `repair --fix`
 
 `repair` reports issues but never mutates. The fixes for
 constraint violations are application-specific (which orphan
-row gets reattached? deleted? merged?) — that's a human call, not
+row gets reattached? deleted? merged?). That's a human call, not
 a CLI call. If `repair` ever shows non-empty output on your
 production DB, treat it like any other monitoring alert.
 
@@ -476,7 +477,7 @@ production DB, treat it like any other monitoring alert.
 ## 8. Logging
 
 The library wires a PSR-3 `Psr\Log\LoggerInterface` into the
-container by default — pointed at `Psr\Log\NullLogger`. **The
+container by default, pointed at `Psr\Log\NullLogger`. **The
 library itself does not emit log calls** today; this is purely a
 surface for host code that wants logging facilities.
 
@@ -507,7 +508,7 @@ the same way you'd inject any other service.
 
 If you want a permanent audit trail of "who edited what", subscribe
 to the domain events (`ItemUpdated`, etc.) and log from there. The
-events are dispatched **after** the SQLite transaction commits — a
+events are dispatched **after** the SQLite transaction commits: a
 log call that throws does not roll back the write, so it's safe to
 log without a `try`/`catch`. See
 [API > Domain > Domain events](api/domain.md#domain-events) for the
@@ -545,16 +546,16 @@ Before flipping DNS:
 
 ## 10. Where to look in the source
 
-- `src/Storage/Sqlite/ConnectionFactory.php` — the four PRAGMAs
+- `src/Storage/Sqlite/ConnectionFactory.php`, the four PRAGMAs
   the library issues on every connect.
-- `src/Cache/FilesystemCache.php` — the two-level hash fanout
+- `src/Cache/FilesystemCache.php`, the two-level hash fanout
   layout used under `cachePath`.
-- `src/Files/LocalFileStorage.php` — atomic-write pattern for
+- `src/Files/LocalFileStorage.php`, atomic-write pattern for
   uploads (tmp + rename), and URL construction from
   `uploadsUrl`.
-- `src/Search/FullTextSearch.php` — FTS rebuild SQL.
-- `src/Cli/Application.php` — every CLI command and its options.
-- `config/schema/*.sql` — the migration files applied on first
+- `src/Search/FullTextSearch.php`, FTS rebuild SQL.
+- `src/Cli/Application.php`, every CLI command and its options.
+- `config/schema/*.sql`, the migration files applied on first
   PDO resolve.
-- `Dockerfile`, `docker-compose.yml` — the bundled **dev**
+- `Dockerfile`, `docker-compose.yml`, the bundled **dev**
   environment; production examples in §4 above.
diff --git a/docs/field-types.md b/docs/field-types.md
index af07302..0d8be4d 100644
--- a/docs/field-types.md
+++ b/docs/field-types.md
@@ -9,12 +9,12 @@ patterns, rendering, registration, and tests.
 If you only need API signatures, go read the reference. If you're
 writing a new field type, start here.
 
-> **Prerequisites.** You have iManager 2.0 booted via
+> **Prerequisites.** You have iManager 2 booted via
 > `Imanager\DefaultBootstrap::boot()` (see
 > [README §Quickstart](../README.md#quickstart)). You know what a
 > `Category` and a `Field` are (see
 > [API > Domain](api/domain.md)). All examples below are tested
-> against the real plugin contract — copy them, they compile.
+> against the real plugin contract. Copy them, they compile.
 
 ---
 
@@ -108,12 +108,12 @@ sophisticated ones.
    $config = [...$this->defaultConfig(), ...$field->config];
    ```
 
-   Don't read raw `$field->config` keys directly — a missing key
+   Don't read raw `$field->config` keys directly: a missing key
    becomes a silent `null` and surprises someone down the road.
 4. **`validate()` returns a `ValidationResult`, not an exception.**
    Even for catastrophic input. The host wraps the failed result
    in a `ValidationException` (or whatever its own error shape is)
-   before propagating — the repository never sees the result
+   before propagating. The repository never sees the result
    object.
 5. **`render()` must produce HTML safe to drop in any `<form>`.**
    Escape every dynamic value through the injected `Sanitizer`. Do
@@ -125,7 +125,7 @@ sophisticated ones.
 
 `validate()` is the contract every plugin exposes for input
 coercion. **The host calls it; the storage layer does not.**
-`ItemRepository::save()` writes `$item->data` verbatim — it never
+`ItemRepository::save()` writes `$item->data` verbatim. It never
 routes values through the registry. The canonical "save" flow on
 the host side looks like this:
 
@@ -167,7 +167,7 @@ $items->save(new Item(
 ));
 ```
 
-The `null` skip is intentional — `PasswordFieldType::validate()`
+The `null` skip is intentional: `PasswordFieldType::validate()`
 returns `ok(null)` for "leave the existing hash alone", and you
 want that key absent from `$coerced` rather than written as `null`.
 
@@ -177,14 +177,14 @@ skeleton the built-ins use:
 ```php
 public function validate(mixed $rawValue, Field $field): ValidationResult
 {
-    // (1) Empty / null handling — including the required check.
+    // (1) Empty / null handling, including the required check.
     if ($this->isEmpty($rawValue)) {
         return $field->required
             ? ValidationResult::failed(InputErrorCode::EmptyRequired)
             : ValidationResult::ok($this->emptyValue());
     }
 
-    // (2) Format / shape check — refuse early, before coercion swallows.
+    // (2) Format / shape check: refuse early, before coercion swallows.
     if (! $this->looksValid($rawValue)) {
         return ValidationResult::failed(InputErrorCode::WrongValueFormat);
     }
@@ -205,7 +205,7 @@ public function validate(mixed $rawValue, Field $field): ValidationResult
 ### Error codes (`InputErrorCode`)
 
 The shared error vocabulary across all plugins. The numeric values
-are stable — old data that persisted them as integers still rounds
+are stable: old data that persisted them as integers still rounds
 back to the right case.
 
 | Case | When to use |
@@ -218,7 +218,7 @@ back to the right case.
 | `UndefinedCategoryId` | The `filepicker` (or any reference-typed) field targets a category id that doesn't exist. |
 
 If none of these fit the failure your plugin is reporting, look
-twice — most "new" cases collapse into `WrongValueFormat`. Resist
+twice: most "new" cases collapse into `WrongValueFormat`. Resist
 the urge to add more codes; the host editor expects this exact set
 when mapping failures to localised messages.
 
@@ -235,7 +235,7 @@ Three of the built-ins distinguish "empty but allowed" from "absent":
 
 Pick the same rule for your own plugin if "no value" is a real,
 distinguishable state. For string-typed fields the built-ins use
-`''` instead — empty string is the natural absence in SQLite text
+`''` instead: empty string is the natural absence in SQLite text
 storage.
 
 ### What the `Sanitizer` actually does
@@ -248,10 +248,10 @@ relevant calls inside `validate()` are:
 | `$this->sanitizer->text($s, $maxLength)` | Trims, collapses whitespace, truncates to `$maxLength` chars. Used by `TextFieldType`. |
 | `$this->sanitizer->int($value, $min, $max)` | Coerces numeric/bool to int; clamps to `[$min, $max]`. |
 | `$this->sanitizer->entities($s)` | HTML-encodes; **render-time only**, never inside `validate()`. |
-| `$this->sanitizer->markdown($s)` / `->purify($s)` | Markdown render / HTMLPurifier — used by `LongText` / `Editor` plugins. |
+| `$this->sanitizer->markdown($s)` / `->purify($s)` | Markdown render / HTMLPurifier, used by `LongText` / `Editor` plugins. |
 
 If you find yourself reimplementing `htmlspecialchars()` or
-`trim()` inside a plugin, you're skipping the `Sanitizer` — call
+`trim()` inside a plugin, you're skipping the `Sanitizer`. Call
 it instead. It exists so the host can swap the escaping backend
 once and have every plugin pick it up.
 
@@ -260,7 +260,7 @@ once and have every plugin pick it up.
 ## 3. Render patterns
 
 `render()` is the consumer-facing HTML for editing a value. It is
-called only by host editor UIs — your application's read templates
+called only by host editor UIs: your application's read templates
 should pull `$item->data->get($name)` and render their own HTML.
 
 ### Pattern A — simple input element
@@ -284,14 +284,14 @@ Three rules cover 80 % of cases:
   `entities()`.
 - Reflect `$field->required` as the HTML `required` attribute when
   the browser-side enforcement helps.
-- Use named args via `sprintf()` rather than string concatenation —
-  the templates stay legible and the escaping order is unmistakable.
+- Use named args via `sprintf()` rather than string concatenation,
+  so the templates stay legible and the escaping order is unmistakable.
 
 ### Pattern B — collections (dropdown / radio group)
 
 When the choices come from `config`, normalise the array shape
-defensively before iterating — `config` is untyped, and a host
-editor may put junk in there:
+defensively before iterating: `config` is untyped, and a host
+editor may put junk in there.
 
 ```php
 private function options(Field $field): array
@@ -314,8 +314,8 @@ as a starting point for any plugin whose config carries a list.
 
 ### Pattern C — file inputs
 
-If you handle uploads, render a plain HTML file input — the bytes
-themselves flow through `FileStorage`, not through the form value:
+If you handle uploads, render a plain HTML file input: the bytes
+themselves flow through `FileStorage`, not through the form value.
 
 ```php
 return \sprintf(
@@ -334,7 +334,7 @@ JavaScript by field type without parsing class names. The built-in
 
 For complex inputs (rich-text editors, custom date pickers, asset
 pickers) you usually only emit a placeholder element and a hidden
-input — the host editor's JS picks it up by `data-field` and
+input: the host editor's JS picks it up by `data-field` and
 augments it. Keep the placeholder dumb; let the host edit-mode JS
 own the interactive surface.
 
@@ -401,7 +401,7 @@ final readonly class MoneyWithCurrencyFieldType implements FieldTypePlugin
 
     public static function affinity(): SqliteAffinity
     {
-        // JSON blob — not numerically queryable as a hot column.
+        // JSON blob: not numerically queryable as a hot column.
         return SqliteAffinity::Text;
     }
 
@@ -449,7 +449,7 @@ final readonly class MoneyWithCurrencyFieldType implements FieldTypePlugin
         $max = \is_int($config['max']) ? $config['max'] : null;
         $amount = $this->sanitizer->int($rawValue['amount'], $min, $max);
 
-        // Detect a clamp — if the user passed something out of range, fail
+        // Detect a clamp. If the user passed something out of range, fail
         // rather than silently clipping (this is a financial field).
         $raw = (int) $rawValue['amount'];
         if ($min !== null && $raw < $min) {
@@ -504,15 +504,15 @@ this type just like any other:
 ```php
 $fields = $container->get(\Imanager\Storage\FieldRepository::class);
 
-// Custom plugins are addressed by their string name() — the FieldType
-// enum only carries the 16 built-ins. Pass the string through Field::type
-// as if it were an enum case; the SQLite layer doesn't care which.
+// The FieldType enum only carries the 16 built-ins. For a custom
+// plugin, pick the closest-fitting case as a proxy (see the
+// "Storing custom types" callout below for the why).
 $fields->save(new \Imanager\Domain\Field(
     id: null,
     categoryId: $blog->id,
     name: 'price',
     label: 'Price',
-    type: \Imanager\Enum\FieldType::Text, // see "Storing custom types" below
+    type: \Imanager\Enum\FieldType::Text,
     required: true,
     config: ['currencies' => ['EUR', 'USD']],
 ));
@@ -520,7 +520,7 @@ $fields->save(new \Imanager\Domain\Field(
 
 > **Storing custom types.** The `fields.type` column is a TEXT
 > column whose value is the plugin's `name()`. The `FieldType` enum
-> exists for ergonomics on the built-ins — when you create a `Field`
+> exists for ergonomics on the built-ins: when you create a `Field`
 > for a custom type, set `type` to the closest-fitting `FieldType`
 > case (here `Text`) and treat the plugin's string name as
 > authoritative at the validate/render boundary. If you want
@@ -533,7 +533,7 @@ $fields->save(new \Imanager\Domain\Field(
 Real-world money handling needs currency conversion, locale-aware
 display formatting, and zero-decimal-currency support (JPY has no
 minor units, KWD has three). All of that belongs in your domain
-service, not in the field-type plugin — the plugin's job is to
+service, not in the field-type plugin. The plugin's job is to
 **validate and coerce the raw form value into your storage shape**,
 nothing more.
 
@@ -557,7 +557,7 @@ A few details worth knowing:
 
 - **`register()` is idempotent-by-name.** Registering a plugin whose
   `name()` matches an already-registered plugin **overwrites** the
-  earlier one. This is intentional — it's the supported way to swap
+  earlier one. This is intentional: it's the supported way to swap
   a built-in for a customised variant. Just don't do it by accident.
 - **Order matters for `names()`.** `FieldTypeRegistry::names()`
   returns names in registration order. Host editor "type" dropdowns
@@ -588,7 +588,7 @@ $container = DefaultBootstrap::boot(/* … */);
 })();
 ```
 
-Keep this function out of the request hot path — it runs once per
+Keep this function out of the request hot path: it runs once per
 container construction and that's all.
 
 ---
@@ -597,7 +597,7 @@ container construction and that's all.
 
 Unit-test the plugin in isolation against a real `Sanitizer` and a
 hand-built `Field`. The built-in tests under
-`tests/Unit/Field/Types/` are the canonical examples — copy their
+`tests/Unit/Field/Types/` are the canonical examples. Copy their
 shape.
 
 ```php
@@ -678,7 +678,7 @@ Three habits that pay off:
 - **Test through the public methods only.** `validate()` and
   `render()` are your contract; everything else is internal.
 - **Use a real `Sanitizer`, not a mock.** The built-in Sanitizer is
-  a pure-function facade — mocking it hides bugs in escaping that
+  a pure-function facade: mocking it hides bugs in escaping that
   only show up when something special-cases a quote.
 - **Assert on the `errorCode` enum, not the message.** Messages
   drift; codes are the host editor's stable mapping target.
@@ -695,7 +695,7 @@ exercise `ItemRepository::save()` end-to-end. The pattern is in
 ### 7.1 Reading `$field->config` directly
 
 ```php
-// WRONG — silent null if the key is missing
+// WRONG: silent null if the key is missing
 $max = $field->config['maxLength'];
 ```
 
@@ -711,7 +711,7 @@ $max = (int) ($config['maxLength'] ?? 255);
 Don't. The host's "validate then save" loop expects a
 `ValidationResult` it can branch on (success → coerced value into the
 bag, failure → map the `InputErrorCode` to a UI message). An
-exception out of `validate()` breaks that flow — the host has to
+exception out of `validate()` breaks that flow: the host has to
 add a `try/catch` around every plugin call, and your error code
 never reaches the surface.
 
@@ -723,7 +723,7 @@ source of double-escaped values in form output.
 
 ### 7.4 Trusting `$field->required` for "must be present in DB"
 
-`required` is a *plugin-input* flag — it's the signal a plugin's
+`required` is a *plugin-input* flag: it's the signal a plugin's
 `validate()` looks at to decide whether to reject empty raw input.
 It only catches anything when a host actually calls `validate()`.
 It does **not** add a `NOT NULL` constraint to the generated column,
@@ -740,7 +740,7 @@ self::assertNotNull($result, 'validate() must return a ValidationResult');
 ```
 
 Or: just write the tests. The built-ins each ship 8–12 test methods
-covering every branch — that's the bar.
+covering every branch. That's the bar.
 
 ---
 
@@ -748,18 +748,18 @@ covering every branch — that's the bar.
 
 When in doubt, the source is short and well-named:
 
-- `src/Field/Types/TextFieldType.php` — simplest validation +
+- `src/Field/Types/TextFieldType.php`, simplest validation +
   render shape.
-- `src/Field/Types/DropdownFieldType.php` — typed-config list,
+- `src/Field/Types/DropdownFieldType.php`, typed-config list,
   defensive iteration.
-- `src/Field/Types/IntegerFieldType.php` — numeric coercion with
+- `src/Field/Types/IntegerFieldType.php`, numeric coercion with
   clamping vs strict-fail.
-- `src/Field/Types/SlugFieldType.php` — multi-step coercion
+- `src/Field/Types/SlugFieldType.php`, multi-step coercion
   (truncate → slugify → uniqueness suffix).
-- `src/Field/Types/ImageuploadFieldType.php` — file-typed plugin
+- `src/Field/Types/ImageuploadFieldType.php`, file-typed plugin
   surface and `data-field=` rendering for host JS hooks.
-- `src/Field/FieldTypeRegistry.php` — registry mechanics.
-- `src/Field/ValidationResult.php` — the `ok` / `failed` named
+- `src/Field/FieldTypeRegistry.php`, registry mechanics.
+- `src/Field/ValidationResult.php`, the `ok` / `failed` named
   constructors.
 
 The reference page at [API > Field types](api/field-types.md) is
diff --git a/docs/migration-guide.md b/docs/migration-guide.md
index daf7943..888b51c 100644
--- a/docs/migration-guide.md
+++ b/docs/migration-guide.md
@@ -3,7 +3,7 @@
 > **Time budget:** about 30 minutes for a typical install (a handful of
 > categories, a few hundred items, a few MB of assets).
 > **Scope:** this guide covers **data migration** only. iManager 2.0 is a
-> ground-up rewrite — the application code that consumes the library
+> ground-up rewrite: the application code that consumes the library
 > needs separate work (see [README §Quickstart](../README.md#quickstart)
 > for the new API shape).
 
@@ -31,7 +31,7 @@
    until you're ready to switch):
 
    ```bash
-   composer require bigins/imanager:2.0.x-dev
+   composer require bigins/imanager:^2.0
    ```
 
 ---
@@ -59,7 +59,7 @@ Pass the path to `data/` itself (not to `data/datasets/buffers/`) as
 ## Step 2 — Dry run first
 
 A dry run executes the full import inside a transaction and rolls it
-back at the end. No SQLite file is written, no assets are copied —
+back at the end. No SQLite file is written, no assets are copied:
 you only get the report.
 
 ```bash
@@ -80,7 +80,7 @@ Expected output (numbers will differ for your install):
  Upload target: ./data-new/uploads
  Remap fields:  (none)
 
- ! [NOTE] Applied 4 schema migration(s) to target
+ ! [NOTE] Applied 5 schema migration(s) to target
 
  Result
  ------
@@ -103,11 +103,11 @@ Expected output (numbers will differ for your install):
 > [Re-mapping cross-item id references](#re-mapping-cross-item-id-references---remap-fields)
 > below.
 
-**If `Errors > 0`** — read the `Errors` section the CLI prints and fix
+**If `Errors > 0`:** read the `Errors` section the CLI prints and fix
 the source data first. Common causes are listed under
 [Common issues](#common-issues) below.
 
-**If `Warnings > 0`** — read them but they don't block the real run.
+**If `Warnings > 0`:** read them but they don't block the real run.
 
 ---
 
@@ -126,7 +126,7 @@ What happens:
 1. The target SQLite file is created (or opened) and any pending
    schema migrations are applied.
 2. `Imanager\Migration\V1FileParser` reads the legacy `*.php` files
-   using `nikic/php-parser` — the AST is walked for literal values
+   using `nikic/php-parser`. The AST is walked for literal values
    only, so a tampered `var_export` file cannot execute host code.
 3. `Imanager\Migration\JsonV1Importer` walks the buffers in order:
    categories → fields → items. Everything happens inside a single
@@ -144,11 +144,11 @@ errors blocked the import.
 ## Step 4 — Verify
 
 ```bash
-vendor/bin/imanager schema:status --database ./data-new/imanager.db
+vendor/bin/imanager schema:status --db ./data-new/imanager.db
 ```
 
-You should see all four migrations applied: `0001_initial`, `0002_fts`,
-`0003_files`, `0004_files_title`.
+You should see all five migrations applied: `0001_initial`, `0002_fts`,
+`0003_files`, `0004_files_title`, `0005_searchable_defaults`.
 
 Spot-check item counts against the source. A quick way:
 
@@ -171,7 +171,7 @@ iManager 1.x and 2.0 share a name and a problem domain; they share
 work:
 
 - Drop the 1.x `Imanager\…` includes / autoload paths.
-- Boot the new container — typically a single
+- Boot the new container, typically a single
   `Imanager\DefaultBootstrap::boot(…)` call. See
   [README §Quickstart](../README.md#quickstart).
 - Replace 1.x calls (`new Items()`, `getCategories()`, …) with the
@@ -179,7 +179,7 @@ work:
 - If you use the FTS, rebuild the index after the first successful
   boot (`vendor/bin/imanager fts:rebuild`).
 
-The shape of this work is host-specific — what calls you replace,
+The shape of this work is host-specific: what calls you replace,
 in what order, and how you stage the cutover depends on the
 application sitting on top of iManager. The repository / event /
 field-type APIs are stable; the wiring around them is yours to
@@ -189,7 +189,7 @@ design.
 
 ## Re-mapping cross-item id references (`--remap-fields`)
 
-The CLI **renumbers** item IDs as it imports — the new SQLite ID is
+The CLI **renumbers** item IDs as it imports: the new SQLite ID is
 not the same as the 1.x ID. By default, item-id references stored
 inside field values (e.g. a `parent` field whose value is the old
 ID of another item) keep the **old** value after migration, which
@@ -220,7 +220,7 @@ vendor/bin/imanager migrate:from-v1 \
 
 The importer:
 
-1. Imports categories, fields, items as usual — recording the
+1. Imports categories, fields, items as usual, recording the
    per-category `old item id → new item id` map along the way.
 2. After all items are inserted, walks the items in each
    `categorySlug` declared in the config; for each `fieldName`, it
@@ -229,7 +229,7 @@ The importer:
 3. Reports the number of rewrites in the `Remapped` row of the
    final report.
 
-Both passes run inside one SQLite transaction — a failure in the
+Both passes run inside one SQLite transaction: a failure in the
 remap rolls the whole migration back, same as any other import
 error.
 
@@ -237,12 +237,12 @@ error.
 
 The remap pass deliberately preserves:
 
-- **`0` (or `'0'`, or `null`, or `''`)** — the canonical "no
+- **`0` (or `'0'`, or `null`, or `''`):** the canonical "no
   parent / root" sentinel for tree-shaped data.
-- **Non-numeric values** — anything that doesn't coerce to a
+- **Non-numeric values:** anything that doesn't coerce to a
   positive integer is skipped (no false-positives on accidental
   matches).
-- **Already-correct values** — re-running the remap against
+- **Already-correct values:** re-running the remap against
   already-mapped data is a no-op.
 
 ### Dangling references
@@ -251,13 +251,13 @@ If a field value points at an old id that the new database doesn't
 carry (because the referenced item was missing from the source, or
 the source data was inconsistent), the importer **leaves the value
 in place** and adds a warning to the final report. It's an
-informational signal, not a fatal error — the value rounds back to
+informational signal, not a fatal error: the value rounds back to
 the old id, the same shape your data had before.
 
 ### When you don't need this
 
 If your 1.x install has no cross-item id references in any field
-values, the flag is unnecessary — omit it and the second pass is
+values, the flag is unnecessary, omit it and the second pass is
 skipped entirely. Most simple flat-file installs fall into this
 bucket. The remap is a forward-fix for the **tree-shaped /
 relational** subset of 1.x data.
@@ -266,7 +266,7 @@ relational** subset of 1.x data.
 
 ## Rollback
 
-- **After a dry run:** nothing to roll back — the transaction was
+- **After a dry run:** nothing to roll back, the transaction was
   reverted before commit.
 - **After a real run:** the target DB and `--upload-target` directory
   are the only things the migrator created. Delete both and start
@@ -277,20 +277,20 @@ relational** subset of 1.x data.
 
 ## Common issues
 
-- **"Source directory does not exist"** — pass `--source` as the path
+- **"Source directory does not exist":** pass `--source` as the path
   to `data/` itself, not to `data/datasets/buffers/`.
-- **"`--source` is required"** — both `--source` and `--target` are
+- **"`--source` is required":** both `--source` and `--target` are
   mandatory; the CLI fails fast with `INVALID` if either is missing.
-- **GD missing** — without `ext-gd` the import still copies assets,
+- **GD missing:** without `ext-gd` the import still copies assets,
   but on-demand thumbnails won't render on the new install. Install
   `ext-gd` and re-run; thumbnails are generated lazily on first
   request, so there's nothing to "re-import".
 - **Migrating from a partial 1.x install** (e.g. an empty
-  `data/datasets/buffers/items/`) — the importer treats absent files
+  `data/datasets/buffers/items/`): the importer treats absent files
   as "zero items in that category" and continues. The final report
   will show `Categories > 0` with `Items: 0`, which is correct, not
   an error.
-- **Different output target each time** — the CLI is **append-safe**
+- **Different output target each time:** the CLI is **append-safe**
   against an existing 2.0 SQLite file: schema migrations are no-ops
   if applied, and item saves create fresh IDs. Re-running against
   the same target will therefore **duplicate** every item. Always
diff --git a/docs/query-cookbook.md b/docs/query-cookbook.md
index 6ad7b2c..0936c6f 100644
--- a/docs/query-cookbook.md
+++ b/docs/query-cookbook.md
@@ -47,8 +47,8 @@ $total = $repo->count(
 ```
 
 `Query` is **immutable**. Every builder method returns a new
-instance — share a "base query" across call sites and refine each
-independently without worrying about shared state:
+instance: share a "base query" across call sites and refine each
+independently without worrying about shared state.
 
 ```php
 $base    = (new Query())->inCategory($blog->id)->where('active', '=', true);
@@ -66,7 +66,7 @@ $archive = $base->where('archived', '=', true);       // subset of $base
    source string or union the results of two queries
    application-side.
 3. **`count()` ignores `limit()` / `offset()`.** The contract is
-   "how many rows match this predicate" — pagination metadata, not
+   "how many rows match this predicate": pagination metadata, not
    page size. Use it for total counts and let the page query carry
    the limit.
 
@@ -83,7 +83,7 @@ There are two kinds of fields you can predicate on:
 | Structural column on `items` | `id`, `name`, `label`, `position`, `active`, `created`, `updated`, `categoryId` | Plain SQL on the column. |
 | Field declared on the category | `title`, `body`, `tags`, … (anything in `$item->data`) | Hot (`indexed = true`): generated column. Cold: `json_extract(data, ...)`. |
 
-You don't pick which one — the builder picks for you based on the
+You don't pick which one: the builder picks for you based on the
 field name. From the call site, both look the same:
 
 ```php
@@ -137,18 +137,18 @@ case-insensitive for ASCII.
 ```php
 use Imanager\Query\Operator;
 
-// Starts-with — can use an index on the column
+// Starts-with: can use an index on the column
 ->where('name', Operator::Like, 'hello%')
 
-// Contains — cannot use an index; full scan
+// Contains: cannot use an index; full scan
 ->where('name', Operator::Like, '%world%')
 
-// Ends-with — also a scan
+// Ends-with: also a scan
 ->where('name', Operator::Like, '%post')
 ```
 
 **Rule of thumb:** trailing-only wildcards (`'foo%'`) are
-index-friendly. Leading wildcards (`'%foo'`) require a scan — once
+index-friendly. Leading wildcards (`'%foo'`) require a scan. Once
 your `items` table has a few thousand rows, that scan starts to
 hurt. For free-text contains-search, prefer the FTS hand-off in
 [§6](#6-full-text-search-hand-off).
@@ -188,7 +188,7 @@ Three pragmatic paths, in order of "do this first":
    ```
 
 3. **Hand off to FTS.** If the OR is "matches any of these search
-   terms anywhere", that's exactly what FTS5 is for —
+   terms anywhere", that's exactly what FTS5 is for:
    [§6](#6-full-text-search-hand-off).
 
 A fourth path — fetch all and filter in PHP — works for ≤ a few
@@ -213,7 +213,7 @@ tag list contains `php`, use `LIKE` on the JSON-encoded value:
 ->where('tags', Operator::Like, '%"php"%')
 ```
 
-It's a contains-wildcard so the cost is a scan — fine for hundreds
+It's a contains-wildcard so the cost is a scan: fine for hundreds
 of rows, not great beyond. If you query tag membership frequently,
 the right answer is a join table (separate category), not a
 denormalised JSON list.
@@ -236,7 +236,7 @@ primary order; subsequent calls are tiebreakers:
 
 If you don't call `orderBy()` at all, the storage layer returns
 items by **`position` ASC, then `id` ASC**. That matches what
-`findByCategory()` does — adding an explicit `orderBy('position')`
+`findByCategory()` does: adding an explicit `orderBy('position')`
 is redundant but harmless.
 
 ### Direction
@@ -246,7 +246,7 @@ use Imanager\Query\Direction;
 
 ->orderBy('created', Direction::Desc)
 ->orderBy('created', 'desc')           // identical
-->orderBy('created', 'DESC')           // case-insensitive — also fine
+->orderBy('created', 'DESC')           // case-insensitive, also fine
 ```
 
 Both forms call into `Direction::coerce()` for you; an unknown
@@ -260,7 +260,7 @@ string throws `\ValueError`.
 ```
 
 The `id` tiebreaker matters whenever two items can share a
-`created` timestamp — common when seeding from a migration that
+`created` timestamp, common when seeding from a migration that
 stamps a constant `now()`. Without it, the row order between two
 ties is undefined and your pagination can skip or duplicate items
 across pages.
@@ -313,8 +313,8 @@ A few details to know:
   code that calls `for ($i = 1; $i <= $pager->lastPage(); $i++)`
   from infinite-looping or showing "0 of 0".
 - **Stable order is required for stable pagination.** If two items
-  can tie on the primary sort key, add a tiebreaker (see §3) —
-  otherwise items can jump pages between requests when the
+  can tie on the primary sort key, add a tiebreaker (see §3).
+  Otherwise items can jump pages between requests when the
   underlying storage returns a different tie-order.
 - **Offset pagination is not free.** SQLite still scans the rows
   it skips. For deep pages (> 1000), prefer **keyset pagination**:
@@ -329,13 +329,13 @@ A few details to know:
 
   Works only when the sort column is monotonic (`created`, `id`).
   For a generic UI that lets users jump to arbitrary pages, offset
-  pagination is still the right call — just don't use it for
+  pagination is still the right call, just don't use it for
   background workers walking a table.
 
 ### Per-page over a maximum
 
-A safety guard for any HTTP-driven pagination — never trust the
-client to pick a sensible per-page:
+A safety guard for any HTTP-driven pagination: never trust the
+client to pick a sensible per-page.
 
 ```php
 $perPage = max(1, min(100, (int) ($_GET['per_page'] ?? 20)));
@@ -382,7 +382,7 @@ upgrades the clause to `LIKE`:
 
 By design:
 
-- **`inCategory()`, `orderBy()`, `limit()`, `offset()`** — those
+- **`inCategory()`, `orderBy()`, `limit()`, `offset()`**: those
   live in code, not in the selector string. Selectors describe
   predicates; the rest of the query you build around them:
 
@@ -396,17 +396,17 @@ By design:
   use one of the patterns in [§2.6](#26-the-or-shaped-problem).
 - **Quoting / escaping.** A literal `,` or `=` inside a value will
   break parsing. If your right-hand side is user-controlled and may
-  contain those characters, don't take the SelectorParser path —
-  build the `Query` programmatically and feed values as parameters.
-- **Functions / casts.** No `LOWER(name)`, no `JSON(tags) LIKE …`
-  — keep it small.
+  contain those characters, don't take the SelectorParser path.
+  Build the `Query` programmatically and feed values as parameters.
+- **Functions / casts.** No `LOWER(name)`, no `JSON(tags) LIKE …`.
+  Keep it small.
 
 ### When to use it vs build manually
 
 Use **`SelectorParser`** when:
 - The predicate is stored as data (config file, settings table,
   URL parameter) and authored by a human.
-- The shape of the predicate is genuinely declarative — "filter by
+- The shape of the predicate is genuinely declarative: "filter by
   these N criteria, AND".
 
 Build a **`Query`** manually when:
@@ -428,9 +428,9 @@ try {
 ```
 
 Examples that throw:
-- `'name'` — missing operator + value
-- `'name='` — empty right-hand side
-- `'1foo=bar'` — identifier must start with a letter or underscore
+- `'name'`: missing operator + value
+- `'name='`: empty right-hand side
+- `'1foo=bar'`: identifier must start with a letter or underscore
 
 ---
 
@@ -439,15 +439,15 @@ Examples that throw:
 Once your "contains-search" use case grows past a few thousand
 items, switch from `Operator::Like` with a `%…%` wildcard to
 `FullTextSearch`. It's a SQLite FTS5 index kept in sync with
-`items` automatically — every save / delete updates it inside the
+`items` automatically, every save / delete updates it inside the
 same transaction.
 
 ### Indexing
 
 Items are indexed by `name`, `label`, and a flattened version of
 `data`. Field-level inclusion in the index is governed by
-`Field::$searchable` — set it to `true` on the fields whose
-content should be matched:
+`Field::$searchable`: set it to `true` on the fields whose
+content should be matched.
 
 ```php
 $fields->save(new Field(
@@ -475,8 +475,8 @@ $fts = $container->get(FullTextSearch::class);
 foreach ($fts->search('sqlite AND fts*', categoryId: $blog->id, limit: 10) as $hit) {
     // $hit->itemId
     // $hit->categoryId
-    // $hit->snippet     — HTML snippet with <b>…</b> around matches
-    // $hit->rank        — float; smaller is better (FTS5 convention)
+    // $hit->snippet:    HTML snippet with <b>…</b> around matches
+    // $hit->rank:       float; smaller is better (FTS5 convention)
 }
 
 $total = $fts->count('sqlite AND fts*', categoryId: $blog->id);
@@ -507,7 +507,7 @@ if ($hits === []) {
 
 $ids = array_map(static fn($h) => $h->itemId, $hits);
 
-// There's no `IN (…)` operator on Query — fall back to a per-id
+// There's no `IN (…)` operator on Query. Fall back to a per-id
 // fetch loop (cheap; SQLite is local) or a hand-rolled SQL JOIN
 // if you have thousands of hits.
 $items = [];
@@ -519,7 +519,7 @@ foreach ($ids as $id) {
 }
 ```
 
-For thousands of hits, drop into `\PDO` directly — `FullTextSearch`
+For thousands of hits, drop into `\PDO` directly: `FullTextSearch`
 already does that for the index lookup, and the query layer is
 intentionally not the right place to bolt on bulk-id fetching.
 
@@ -534,7 +534,7 @@ intentionally not the right place to bolt on bulk-id fetching.
   predicate on the index, it predicates on text content.
 
 The hand-off pattern above exists exactly so you can combine the
-two — FTS for text-shaped predicates, `Query` for everything else.
+two: FTS for text-shaped predicates, `Query` for everything else.
 
 ---
 
@@ -559,11 +559,14 @@ PLAN` and it reads in plain English:
 
 ```bash
 sqlite3 data/imanager.db "EXPLAIN QUERY PLAN
-  SELECT * FROM items WHERE field_active = 1;"
+  SELECT * FROM items WHERE gen_7_active = 1;"
 ```
 
-If you see `SCAN items` for a query you call often, the field
-behind that predicate wants to be hot.
+(`gen_7_active` is the generated column for an indexed `active`
+field in category id 7; see
+[Storage > Hot fields](api/storage.md#hot-fields--generated-columns)
+for the naming.) If you see `SCAN items` for a query you call often,
+the field behind that predicate wants to be hot.
 
 ### Wildcard cost
 
@@ -578,7 +581,7 @@ not a cleverer `LIKE`.
 
 ### `count()` + `query()` is two queries
 
-The `Query` builder does not cache anything — calling `count()` and
+The `Query` builder does not cache anything: calling `count()` and
 then `query()` against the same predicate runs the SQL twice. If
 you call both inside one request, cache the count yourself:
 
@@ -595,7 +598,7 @@ combined — but it's worth knowing the shape.
 
 Offset pagination scales O(offset). At `offset = 10_000` SQLite
 walks 10 000 rows it ultimately discards. The right fix at depth
-is **keyset pagination** (§4) — drop `offset()` and predicate on
+is **keyset pagination** (§4): drop `offset()` and predicate on
 the last-seen sort key.
 
 ### Indexes you can add yourself
@@ -611,11 +614,11 @@ ON items (active, position)
 WHERE active = 1;
 ```
 
-A partial index (`WHERE active = 1`) is often the right call —
+A partial index (`WHERE active = 1`) is often the right call:
 it's smaller and hot more of the time. Add it as a numbered
 migration under your install's `config/schema/` directory
 following the existing
-[`0001`–`0004`](api/storage.md#schemamanager) format.
+[`0001`–`0005`](api/storage.md#schemamanager) format.
 
 ---
 
@@ -624,7 +627,7 @@ following the existing
 ### 8.1 Forgetting `inCategory()`
 
 ```php
-// Probably not what you wanted — scans every category in the install.
+// Probably not what you wanted, scans every category in the install.
 $repo->query((new Query())->where('active', '=', true));
 ```
 
@@ -640,15 +643,15 @@ $total = $repo->count((new Query())->inCategory($id)->limit(20));
 ```
 
 `count()` always returns the total for the predicate. That's the
-contract — `Pagination` is the layer that decides what "page 1"
+contract: `Pagination` is the layer that decides what "page 1"
 means.
 
 ### 8.3 Predicating on the wrong field name
 
 The field name passed to `where()` is matched first against
 **structural columns**, then against **declared fields** in the
-category's schema. A typo doesn't error — it predicates on a
-missing JSON key, which always matches zero rows:
+category's schema. A typo doesn't error: it predicates on a
+missing JSON key, which always matches zero rows.
 
 ```php
 // Typo "actice" → JSON key that doesn't exist → empty result, no error.
@@ -662,7 +665,7 @@ field names first.
 
 Bulk-inserting items via the migration tool keeps the FTS index in
 sync (the importer does it in-transaction). Bulk-inserting via raw
-SQL does **not** — you'll need `vendor/bin/imanager fts:rebuild`
+SQL does **not**. You'll need `vendor/bin/imanager fts:rebuild`
 afterwards. If a search "can't find" an item that obviously exists,
 check FTS sync before chasing tokenizer settings.
 
@@ -688,13 +691,13 @@ mutable builders elsewhere.
 
 ## 9. Where to look in the source
 
-- `src/Query/Query.php` — the builder.
+- `src/Query/Query.php`, the builder.
 - `src/Query/Clause.php`, `Operator.php`, `OrderBy.php`,
-  `Direction.php`, `Pagination.php` — the value objects.
-- `src/Query/SelectorParser.php` — the selector grammar.
-- `src/Search/FullTextSearch.php` — FTS search + count + rebuild.
-- `tests/Unit/Storage/ItemQueryContract.php` — every recipe in
-  this guide is asserted there (different surface, same shape) —
+  `Direction.php`, `Pagination.php`, the value objects.
+- `src/Query/SelectorParser.php`, the selector grammar.
+- `src/Search/FullTextSearch.php`, FTS search + count + rebuild.
+- `tests/Unit/Storage/ItemQueryContract.php`, every recipe in
+  this guide is asserted there (different surface, same shape);
   it's the canonical "does this query actually do what I think it
   does?" answer.
 
diff --git a/docs/tutorial/README.md b/docs/tutorial/README.md
index e099393..4e1b915 100644
--- a/docs/tutorial/README.md
+++ b/docs/tutorial/README.md
@@ -1,6 +1,6 @@
 # Tutorial
 
-Task-oriented walkthroughs for iManager 2.0 — each chapter answers
+Task-oriented walkthroughs for iManager 2. Each chapter answers
 **one** "how do I X?" question with a small, self-contained example.
 They're meant for someone who has read the [project README](../../README.md)
 and run the Quickstart, and now wants to do something *concrete*.
@@ -18,7 +18,7 @@ they show up.
 
 ## Recommended reading order
 
-If you're brand new, read top-down — each chapter introduces the
+If you're brand new, read top-down. Each chapter introduces the
 machinery the next one builds on.
 
 | Chapter | What you'll learn | Mini-case |
@@ -26,13 +26,13 @@ machinery the next one builds on.
 | [Setup your first install](setup.md) | What `DefaultBootstrap::boot()` wires up, what each of the four paths means, write and read your first item end-to-end. | A one-table notebook (`Note` category, one `body` field). |
 | [Design a content schema](schema.md) | Pick the right `FieldType` for each column, what `indexed` and `searchable` actually do under the hood (generated columns + FTS5 with real SQL), idempotent setup patterns so re-running your migration is safe. | A blog (`Post` category with title, slug, body, publish date, cover image). |
 | [Validate user input before saving](validation.md) | The canonical `FieldTypeRegistry::get($type)->validate()` loop, how to collect errors across a whole form, where iManager's contract ends and your application code takes over. | A contact form (name + email + subject + message), validated server-side. |
-| [Mutate and delete data](lifecycle.md) | The three repository verbs (`save`, `ensure`, `delete`), event-firing order, what cascades automatically (and what doesn't — orphan generated columns, surviving file bytes), wiring file cleanup yourself, why iManager has no soft-delete. | A bookmark vault (`Bookmark` category with title, url, cover image). |
+| [Mutate and delete data](lifecycle.md) | The three repository verbs (`save`, `ensure`, `delete`), event-firing order, what cascades automatically (and what doesn't: orphan generated columns, surviving file bytes), wiring file cleanup yourself, why iManager has no soft-delete. | A bookmark vault (`Bookmark` category with title, url, cover image). |
 | [Upload files and generate thumbnails](files.md) | The four-part upload pipeline (`UploadedFile`, `UploadConstraints`, `UploadHandler`, `FileStorage`/`FileRepository`), MIME sniffing, the common "constraints in two places" gotcha, lazy thumbnail generation via `ImageProcessor`, swapping the storage backend. | A photo gallery (`Gallery` category with title + image upload). |
 | [Full-text search](search.md) | `FullTextSearch::search()` + `count()` + `rebuild()`, the FTS5 query language (implicit AND, phrases, prefix, boolean, column-restricted), category scoping, pagination, the negative-`rank` quirk on `SearchHit`, why combining FTS hits with `Query` predicates is honestly clunky today, snippet rendering. | A knowledge base (`Article` category with title + body + tags). |
 
 The event-system mechanics are already covered in the lifecycle
-chapter, so a dedicated `events.md` is **not** planned right now —
-common listener patterns might land later as a small cookbook
+chapter, so a dedicated `events.md` is **not** planned right now.
+Common listener patterns might land later as a small cookbook
 appendix if a real use case asks for it.
 
 ## Going deeper
@@ -40,20 +40,20 @@ appendix if a real use case asks for it.
 When a tutorial chapter mentions a method, you can always click
 through to the reference page for the full surface:
 
-- [`docs/api/domain.md`](../api/domain.md) — `Category`, `Field`, `Item`,
+- [`docs/api/domain.md`](../api/domain.md), `Category`, `Field`, `Item`,
   `FieldValueBag`, `File`, plus the nine domain events.
-- [`docs/api/storage.md`](../api/storage.md) — the three repositories
+- [`docs/api/storage.md`](../api/storage.md), the three repositories
   and the `Query` type they consume.
-- [`docs/api/field-types.md`](../api/field-types.md) — every built-in
+- [`docs/api/field-types.md`](../api/field-types.md), every built-in
   field type, its config keys, and its coerced storage shape.
-- [`docs/api/query.md`](../api/query.md) — the `Query` builder API.
-- [`docs/query-cookbook.md`](../query-cookbook.md) — predicate
+- [`docs/api/query.md`](../api/query.md), the `Query` builder API.
+- [`docs/query-cookbook.md`](../query-cookbook.md), predicate
   recipes, pagination, selector strings, full-text-search hand-off.
-- [`docs/field-types.md`](../field-types.md) — how to write your own
+- [`docs/field-types.md`](../field-types.md), how to write your own
   `FieldTypePlugin`.
-- [`docs/migration-guide.md`](../migration-guide.md) — upgrading a
+- [`docs/migration-guide.md`](../migration-guide.md), upgrading a
   1.x install.
-- [`docs/deployment.md`](../deployment.md) — production hosting and
+- [`docs/deployment.md`](../deployment.md), production hosting and
   scheduled maintenance.
 
 The chapters here are the *guided tour*; those pages are the
diff --git a/docs/tutorial/files.md b/docs/tutorial/files.md
index bb1adfc..d084570 100644
--- a/docs/tutorial/files.md
+++ b/docs/tutorial/files.md
@@ -16,17 +16,17 @@ them across four small types so each one has a single concern:
 
 | Type | Concern | Lives in |
 |---|---|---|
-| `UploadedFile` | The source — wraps either `$_FILES[...]` or a local path. HTTP-agnostic. | `src/Files/UploadedFile.php` |
-| `UploadConstraints` | The policy — max bytes, allowed MIME types, allowed extensions. Caller-built; not derived from `Field::config`. | `src/Files/UploadConstraints.php` |
-| `UploadHandler` | The orchestrator — validates against constraints, stores bytes, records metadata. Stateless. | `src/Files/UploadHandler.php` |
-| `FileStorage` / `FileRepository` | The destinations — bytes go through `FileStorage` (default: local disk), metadata goes through `FileRepository`. | `src/Files/FileStorage.php`, `src/Storage/FileRepository.php` |
+| `UploadedFile` | The source: wraps either `$_FILES[...]` or a local path. HTTP-agnostic. | `src/Files/UploadedFile.php` |
+| `UploadConstraints` | The policy: max bytes, allowed MIME types, allowed extensions. Caller-built; not derived from `Field::config`. | `src/Files/UploadConstraints.php` |
+| `UploadHandler` | The orchestrator: validates against constraints, stores bytes, records metadata. Stateless. | `src/Files/UploadHandler.php` |
+| `FileStorage` / `FileRepository` | The destinations: bytes go through `FileStorage` (default: local disk), metadata goes through `FileRepository`. | `src/Files/FileStorage.php`, `src/Storage/FileRepository.php` |
 
 Decoupling these means you can:
 
 - Test the handler without spinning up `$_FILES` (use
   `UploadedFile::fromPath()` for local files).
 - Swap the storage backend without touching the handler (S3,
-  CAS store — anything that implements `FileStorage`).
+  CAS store: anything that implements `FileStorage`).
 - Reuse the same handler from an HTTP endpoint, a CLI import
   script, or a CI seed.
 
@@ -73,8 +73,8 @@ $photoField = $fields->ensure(
 
 The `photo` field is `FieldType::Imageupload`. The
 `->maxBytes()` and `->mimes()` setters write into the field's
-config — which is **documentation, not enforcement**. The actual
-enforcement comes from `UploadConstraints`, which you build
+config. That config is **documentation, not enforcement**. The
+actual enforcement comes from `UploadConstraints`, which you build
 separately. See the "Constraints in two places" callout below.
 
 ## A first upload
@@ -126,8 +126,8 @@ $file = $uploader->handle(
 ```
 
 > **Why `UploadHandler` isn't in the container.** Most of iManager's
-> wiring lives in `DefaultBootstrap`, but `UploadHandler` does not
-> — it's a four-line `new` and the dependencies are all explicit
+> wiring lives in `DefaultBootstrap`, but `UploadHandler` does not.
+> It's a four-line `new` and the dependencies are all explicit
 > (storage / repository / sanitizer / image processor). Adding it
 > to the container would just hide that. Construct it where you
 > need it; one or two lines max.
@@ -142,7 +142,7 @@ echo "MIME: {$file->mime}\n";           // sniffed, not trusted from the browser
 
 A few things to notice:
 
-- **`$file->path` is storage-relative** — `7/3/sunset-2026.jpg`,
+- **`$file->path` is storage-relative**: `7/3/sunset-2026.jpg`,
   not `/var/www/uploads/7/3/sunset-2026.jpg`. The format is
   `<itemId>/<fieldId>/<safeName>`. Storage-relative paths let you
   swap backends without rewriting URLs.
@@ -177,14 +177,14 @@ flow into `UploadHandler::handle()`. The handler reads from
 So enforcement requires *both*:
 
 ```php
-// Schema metadata — documents the intent, persists on the field row:
+// Schema metadata: documents the intent, persists on the field row:
 $fields->ensure(
     Field::image($gallery->id, 'photo', 'Photo')
         ->maxBytes(2_000_000)
         ->mimes('image/jpeg', 'image/png'),
 );
 
-// Runtime enforcement — what the handler actually checks:
+// Runtime enforcement: what the handler actually checks:
 $constraints = new UploadConstraints(
     maxSizeBytes:      2_000_000,
     allowedExtensions: ['jpg', 'jpeg', 'png'],
@@ -221,7 +221,7 @@ $file = $uploader->handle($upload, $item->id, $photoField->id, $constraints);
 
 `fromPath()` bypasses the `is_uploaded_file()` HTTP-guard because
 there's nothing HTTP-shaped about the input. Same handler, same
-constraints, same `File` output — only the source differs.
+constraints, same `File` output. Only the source differs.
 
 ## Thumbnails
 
@@ -249,8 +249,8 @@ $thumbRelativePath = \sprintf(
 $storage->write($thumbRelativePath, $thumbBytes);
 ```
 
-The handler does **not** generate thumbnails for you — only fills
-in `$file->width` / `$file->height` if you passed an
+The handler does **not** generate thumbnails for you: it only
+fills in `$file->width` / `$file->height` if you passed an
 `ImageProcessor` to it. Thumbnail generation is a caller-side
 decision because there's no one-size-fits-all answer (lazy vs eager,
 single size vs responsive set, where the thumbs live).
@@ -265,8 +265,8 @@ web server's rewrite rule sends 404s to a PHP handler that:
 4. Writes it via `$storage->write()`.
 5. Returns the bytes.
 
-Every subsequent request hits the now-existing static file directly
-— no PHP roundtrip until the next size is asked for. The whole
+Every subsequent request hits the now-existing static file directly,
+no PHP roundtrip until the next size is asked for. The whole
 thumbnail tree lives next to the original under `<uploadsPath>`,
 no separate cache directory to manage.
 
@@ -296,7 +296,7 @@ $covers = $files->findByItemAndField($item->id, $photoField->id);
 $gallery = $files->findByItemAndField($item->id, $galleryField->id);
 ```
 
-Files within a field come back in `position` order — useful when
+Files within a field come back in `position` order, useful when
 the editor lets users drag-reorder a gallery. The
 `$file->withPosition($n)` value-object helper lets you generate a
 reorder write quickly:
@@ -311,7 +311,7 @@ foreach ($reorderedIds as $position => $fileId) {
 ## File titles (caption-shaped metadata)
 
 `File::$title` is a typed column (separate from `name`, which is
-the on-disk filename). Use it for human-readable captions —
+the on-disk filename). Use it for human-readable captions:
 `$file->name` will be the sanitized filename
 (`portrait-jane-doe.jpg`), while `$file->title` is whatever the
 editor typed ("Jane Doe at the conference, 2026").
@@ -326,7 +326,7 @@ shouldn't.
 
 ## Cleanup is somebody else's job
 
-The lifecycle chapter covers this in detail — short version: when
+The lifecycle chapter covers this in detail. Short version: when
 you `$items->delete($itemId)`, the file METADATA cascades away via
 the FK relationship, but the **physical bytes** on disk do not.
 That's intentional (FileStorage backends may not support O(1)
@@ -337,10 +337,10 @@ the canonical pattern.
 
 ## Swapping the storage backend
 
-`LocalFileStorage` is the default — bytes go to a directory under
+`LocalFileStorage` is the default: bytes go to a directory under
 `uploadsPath`, URLs use `uploadsUrl` as the prefix. For S3, CDN
 origins, or a content-addressed store, implement
-`FileStorage`'s five-method interface:
+`FileStorage`'s seven-method interface:
 
 ```php
 interface FileStorage
@@ -375,7 +375,9 @@ $tmp = tempnam(sys_get_temp_dir(), 'imanager-thumb-');
 file_put_contents($tmp, $storage->read($file->path));
 $thumbBytes = $images->thumbnail($tmp, width: 320);
 unlink($tmp);
-$storage->write($thumbThumbPath, $thumbBytes);
+
+$thumbRelative = sprintf('%d/%d/thumb-320_%s', $file->itemId, $file->fieldId, $file->name);
+$storage->write($thumbRelative, $thumbBytes);
 ```
 
 Slightly awkward; a future iManager release may add a
@@ -392,7 +394,7 @@ small types — `UploadedFile` (the source), `UploadConstraints`
 upload (`fromPhpUpload`) and a programmatic one (`fromPath`)
 through the same handler. You also learned the most common
 gotcha: `Field::image()->maxBytes(...)` is *metadata*, not
-enforcement — runtime enforcement lives in `UploadConstraints`,
+enforcement. Runtime enforcement lives in `UploadConstraints`,
 and the two have to be kept in sync (a future release may
 bridge them, but today it's your job). You saw thumbnail
 generation as a caller-side concern (`ImageProcessor::thumbnail`
@@ -403,18 +405,18 @@ an S3-shaped backend by overwriting one container binding.
 
 ## Reference
 
-- [`src/Files/UploadHandler.php`](../../src/Files/UploadHandler.php)
-  — the orchestrator, fully commented; the file is short and
+- [`src/Files/UploadHandler.php`](../../src/Files/UploadHandler.php),
+  the orchestrator, fully commented; the file is short and
   worth reading once.
-- [`src/Files/UploadConstraints.php`](../../src/Files/UploadConstraints.php)
-  — the policy value object, with the `::images()` convenience.
-- [`src/Files/FileStorage.php`](../../src/Files/FileStorage.php)
-  — the backend interface; `LocalFileStorage` is the default
+- [`src/Files/UploadConstraints.php`](../../src/Files/UploadConstraints.php),
+  the policy value object, with the `::images()` convenience.
+- [`src/Files/FileStorage.php`](../../src/Files/FileStorage.php),
+  the backend interface; `LocalFileStorage` is the default
   implementation.
-- [`src/Files/ImageProcessor.php`](../../src/Files/ImageProcessor.php)
-  — the intervention/image v3 wrapper with `dimensions()` and
+- [`src/Files/ImageProcessor.php`](../../src/Files/ImageProcessor.php),
+  the intervention/image v3 wrapper with `dimensions()` and
   `thumbnail()`.
-- [`docs/api/domain.md`](../api/domain.md#file) — the `File`
+- [`docs/api/domain.md`](../api/domain.md#file), the `File`
   value object.
-- [`lifecycle.md`](lifecycle.md#wiring-file-cleanup-yourself) —
+- [`lifecycle.md`](lifecycle.md#wiring-file-cleanup-yourself),
   the cleanup listener pattern.
diff --git a/docs/tutorial/lifecycle.md b/docs/tutorial/lifecycle.md
index faebdf7..df3571a 100644
--- a/docs/tutorial/lifecycle.md
+++ b/docs/tutorial/lifecycle.md
@@ -1,6 +1,6 @@
 # The lifecycle of categories, fields, and items
 
-The other foundation chapters focused on **writing** data — schema
+The other foundation chapters focused on **writing** data: schema
 setup, item save, validation. This chapter covers what happens
 afterwards: how to **update** a row, how to **delete** one, what
 cascades automatically, what doesn't, and how to wire up
@@ -27,7 +27,7 @@ Plus the read verbs (`find`, `findBy…`, `findAll`, `query`) that
 return value objects to feed back in.
 
 This chapter is mostly about the second life of those value
-objects — what happens after they exist.
+objects: what happens after they exist.
 
 ## Setup
 
@@ -77,8 +77,8 @@ mutates and removes it.
 
 ### Pattern 1: read, change, save
 
-The most common shape — fetch the existing value object, derive a
-new one with the change you want, write it back:
+The most common shape: fetch the existing value object, derive a
+new one with the change you want, write it back.
 
 ```php
 $existing = $items->find($saved->id);
@@ -115,20 +115,19 @@ $fields->save(
 ```
 
 Each setter returns a new `final readonly Field` with the existing
-`id` preserved — `save()` sees the id and does an update.
+`id` preserved. `save()` sees the id and does an update.
 
 (For `Item`, there's a similar `$item->data->with('key', $value)`
-on the `FieldValueBag` — see [`docs/api/domain.md`](../api/domain.md)
+on the `FieldValueBag`; see [`docs/api/domain.md`](../api/domain.md)
 for the bag's `with()` / `without()` / `merge()` helpers.)
 
 ### Pattern 3: `ensure()` cannot update
 
-`ensure()` is deliberately insert-only on the natural-key path —
-this is the safety promise documented in
-[`docs/imanager-2.1-plan.md`](../imanager-2.1-plan.md): a
-silently-flipped `indexed` flag would trigger an `ALTER TABLE` you
-didn't ask for. So if you want an idempotent setup script that
-*also* applies flag updates on re-run, you compose:
+`ensure()` is deliberately insert-only on the natural-key path.
+This is the safety promise: a silently-flipped `indexed` flag
+would trigger an `ALTER TABLE` you didn't ask for. So if you want
+an idempotent setup script that *also* applies flag updates on
+re-run, you compose:
 
 ```php
 $existing = $fields->findByName($bookmark->id, 'title');
@@ -165,8 +164,8 @@ Same shape for `CategoryUpdated` (`previous`, `current`) and
 
 ## Delete
 
-The interesting work. Deleting in iManager isn't just a SQL DELETE
-— it's a cascade with carefully-ordered events, and a few things
+The interesting work. Deleting in iManager isn't just a SQL DELETE.
+It's a cascade with carefully-ordered events, and a few things
 that **don't** happen automatically that you have to know about.
 
 ### Deleting a category
@@ -179,7 +178,7 @@ What runs, in order:
 
 1. **Lookup**: `find($id)` confirms the row exists; raises
    `NotFoundException` if not (no silent no-op delete).
-2. **`CategoryDeleted` event fires.** Crucially — *before* the SQL
+2. **`CategoryDeleted` event fires.** Crucially, *before* the SQL
    delete, so listeners can still walk into the soon-to-be-gone
    children if they need to. Listeners that need fields / items /
    files for cleanup have one shot here.
@@ -189,8 +188,8 @@ What runs, in order:
    - All `items` rows with `category_id = $id` → gone.
    - All `files` rows referencing those items → gone (transitive
      cascade through `items.id`).
-5. **The category-id index entries and the indexed-field generated
-   columns are NOT cleaned up.** ← see the caveat section below.
+5. **The indexed-field generated columns are NOT cleaned up.**
+   ← see the caveat section below.
 
 ### Deleting a field
 
@@ -206,11 +205,11 @@ What runs:
    recover those by lookup anymore).
 3. `DELETE FROM fields WHERE id = :id`.
 4. **If `$field->indexed === true`**, the matching generated column
-   and its index get dropped — `ALTER TABLE items DROP COLUMN gen_<catId>_<fieldName>` plus the matching `DROP INDEX`. This is the
+   and its index get dropped: `ALTER TABLE items DROP COLUMN gen_<catId>_<fieldName>` plus the matching `DROP INDEX`. This is the
    ONLY path that cleans up generated columns; see the caveat below.
 5. The field's JSON key in existing items' `data` columns is **NOT
    touched**. Item rows still carry `{"title": "..."}` for items
-   created before deletion — there's just no schema entry for it
+   created before deletion. There's just no schema entry for it
    anymore. Items become valid (any key, no validation), the values
    simply orphan.
 
@@ -224,19 +223,19 @@ What runs:
 
 1. Lookup or `NotFoundException`.
 2. **`ItemDeleted` event fires** with the item's `id` and
-   `categoryId` — *before* the SQL DELETE, intentionally, so
+   `categoryId`. *Before* the SQL DELETE, intentionally, so
    listeners can still call `$files->findByItem($id)` to walk
    physical-file metadata before the FK cascade flattens it.
 3. `DELETE FROM items WHERE id = :id`.
-4. `DELETE FROM items_fts WHERE rowid = :id` — keeps the FTS index
+4. `DELETE FROM items_fts WHERE rowid = :id` keeps the FTS index
    in sync.
 5. **SQLite cascade**: all `files` rows for this item → gone.
 
 The deliberate event-before-delete ordering for the `Deleted` events
 is the difference between iManager and a naive ORM: by the time
 your listener runs, the row is still readable. You don't need to
-denormalize "what files did this item have" into the event payload
-— you can just look them up.
+denormalize "what files did this item have" into the event payload;
+you can just look them up.
 
 ## Cascade caveats
 
@@ -250,7 +249,7 @@ iManager calls `IndexedFields::drop()` to remove the generated
 column from the `items` table.
 
 When you delete a *category* via `$categories->delete($id)`, the
-fields are removed via SQLite FK cascade — but that cascade goes
+fields are removed via SQLite FK cascade. But that cascade goes
 straight through the database, not through `SqliteFieldRepository`.
 So `IndexedFields::drop()` is **not invoked**. The generated columns
 sit on the `items` table forever, referencing `data` keys for
@@ -280,7 +279,7 @@ metadata rows → gone. But the **physical bytes on disk** (the
 upload handler) are NOT touched by iManager's storage layer. The
 database happily forgets the metadata; the bytes orphan on disk.
 
-This is by design — iManager doesn't assume the FileStorage backend
+This is by design: iManager doesn't assume the FileStorage backend
 is local-disk; it could be S3, a CDN, a CAS store. Deletion through
 those backends has implementation-specific semantics, so iManager
 delegates the cleanup to a **host-supplied listener** subscribed
@@ -309,8 +308,8 @@ $provider->subscribe(
             try {
                 $storage->delete($file->path);
             } catch (FileStorageException) {
-                // Already gone, or transient I/O failure. Log + move on —
-                // raising here would abort the SQL DELETE that follows the
+                // Already gone, or transient I/O failure. Log + move on.
+                // Raising here would abort the SQL DELETE that follows the
                 // event (see "exceptions" below).
             }
         }
@@ -329,14 +328,14 @@ What this gets you:
   metadata rows go with the item via FK cascade.
 
 The same pattern works for `FieldDeleted` (when you remove a field
-that owned upload-type values) — though the field-delete path is
+that owned upload-type values). The field-delete path is
 less common than item-delete, and the cleanup walk would use
 `FileRepository::findByItemAndField()` on a per-item loop.
 
 ### Exceptions inside listeners
 
 iManager's `SyncEventDispatcher` does **not** swallow listener
-exceptions — they propagate up. For `Deleted` events the dispatch
+exceptions: they propagate up. For `Deleted` events the dispatch
 happens *before* the SQL delete, so a throwing listener leaves the
 row intact in the database. That's a feature, not a bug: a failed
 file cleanup shouldn't be quietly papered over by a successful row
@@ -354,13 +353,13 @@ iManager has no `deleted_at` / `is_deleted` mechanism baked in.
 
 Most reasons to want soft-delete map to one of three patterns:
 
-- **"Hide without removing"** — use the existing `Item::$active`
+- **"Hide without removing"**: use the existing `Item::$active`
   boolean. Default queries can filter for `active = true`; admin
   views can show inactive too. No data loss, no cascade headaches.
-- **"Restore-on-undo"** — keep a separate audit/snapshot table
+- **"Restore-on-undo"**: keep a separate audit/snapshot table
   populated from `ItemUpdated` and `ItemDeleted` listeners. The
   iManager core doesn't enforce a shape; you control it.
-- **"Compliance / retention window"** — a scheduled job runs
+- **"Compliance / retention window"**: a scheduled job runs
   `$items->delete($id)` after the retention period; until then,
   use `active = false`.
 
@@ -372,7 +371,7 @@ paths.
 
 ## What just happened, in one paragraph
 
-You walked through how iManager mutates state — the three repository
+You walked through how iManager mutates state: the three repository
 verbs (`save`, `ensure`, `delete`), the events each emits, and the
 ordering quirks that matter when listeners need to read state
 on the way out. You learned that SQLite FK cascades handle the
@@ -383,19 +382,19 @@ file bytes survive an `ItemDeleted` unless a host listener tears
 them down. You saw the canonical file-cleanup listener using
 `ItemDeleted` + `FileRepository::findByItem` + `FileStorage::delete`,
 and read why iManager has no soft-delete baked in (it doesn't need
-one — `Item::$active` handles the most common cases).
+one; `Item::$active` handles the most common cases).
 
 ## Reference
 
-- [`docs/api/domain.md`](../api/domain.md) — every event with its
+- [`docs/api/domain.md`](../api/domain.md), every event with its
   payload shape (`*Created`, `*Updated`, `*Deleted` × Category /
   Field / Item, plus the marker `DomainEvent` interface).
-- [`docs/api/storage.md`](../api/storage.md) — repository contracts
+- [`docs/api/storage.md`](../api/storage.md), repository contracts
   for `save()`, `ensure()`, `delete()`.
-- [`src/Files/FileStorage.php`](../../src/Files/FileStorage.php) —
+- [`src/Files/FileStorage.php`](../../src/Files/FileStorage.php),
   the file-bytes-backend interface; `LocalFileStorage` is the
   default, swap for S3-shaped backends by registering a different
   binding in your bootstrap.
-- [`src/Events/SyncEventDispatcher.php`](../../src/Events/SyncEventDispatcher.php)
-  — the in-process PSR-14 dispatcher iManager wires by default,
+- [`src/Events/SyncEventDispatcher.php`](../../src/Events/SyncEventDispatcher.php),
+  the in-process PSR-14 dispatcher iManager wires by default,
   with notes on its sync + propagate-exception semantics.
diff --git a/docs/tutorial/schema.md b/docs/tutorial/schema.md
index ce7444c..273bfdf 100644
--- a/docs/tutorial/schema.md
+++ b/docs/tutorial/schema.md
@@ -11,7 +11,7 @@ write a schema-setup script you can re-run safely.
 A *schema* is `Category` + the `Field`s attached to it. There's no
 DDL to write; you build it by calling the `CategoryRepository` and
 `FieldRepository`. The SQLite tables (`categories`, `fields`,
-`items`) are fixed — what you're declaring is *how the JSON payload
+`items`) are fixed. What you're declaring is *how the JSON payload
 on each item gets typed and indexed*.
 
 That means:
@@ -20,7 +20,7 @@ That means:
   a row to `fields` and (if the field is `indexed`) creates one
   generated column.
 - You can keep two installs schema-compatible just by re-running
-  the same setup script — no migrations file alongside the code.
+  the same setup script; no migrations file alongside the code.
 - The schema lives in your application, not in a separate
   migrations folder. That makes it easy to keep schema setup next
   to the code that uses it.
@@ -48,7 +48,7 @@ iManager ships 16 built-in field types. The cheat sheet:
 | Single uploaded image (with thumbnails) | `FieldType::Imageupload` |
 | Pick from already-uploaded files | `FieldType::Filepicker` |
 
-The picker isn't binding — `Editor` is just `LongText` with an
+The picker isn't binding: `Editor` is just `LongText` with an
 editor `render()`, and `Money` is just `Decimal` with currency
 formatting. If none of the 16 fits, you write a
 [custom plugin](../field-types.md#writing-a-custom-field-type) and
@@ -99,7 +99,7 @@ A real row's `data` column might hold:
 **Why JSON, not one column per field?**
 
 So that adding a field doesn't require an `ALTER TABLE`. iManager
-schemas are user-defined — a host application might add `subtitle`
+schemas are user-defined: a host application might add `subtitle`
 to its `Post` category on Monday and `featured` on Tuesday. With
 JSON storage, each new field is a new key on `data`; the schema
 itself stays a single column. Old items work unchanged (the key is
@@ -135,13 +135,13 @@ ON items(category_id, gen_7_published_at);
 
 Two things to notice:
 
-- **The generated column** (`gen_7_published_at`) is *virtual* —
+- **The generated column** (`gen_7_published_at`) is *virtual*:
   SQLite doesn't store its value, it recomputes
-  `json_extract(data, '$.published_at')` on every read. So the
+  `json_extract(data, '$.published_at')` on every read. The
   storage cost is zero rows wider; it's purely a *naming* of the
   expression.
 - **The index** is on `(category_id, gen_7_published_at)`. So
-  filters scoped to one category (the common case — virtually
+  filters scoped to one category (the common case; virtually
   every query starts with `Query::for($postId)`) hit it directly.
 
 Now the same query becomes:
@@ -152,7 +152,7 @@ WHERE category_id = 7 AND gen_7_published_at < 1700000000;
 ```
 
 …and SQLite uses the B-tree index. A B-tree lookup against a
-sorted index is `O(log n)` — at 50k rows, you touch maybe 17
+sorted index is `O(log n)`. At 50k rows you touch maybe 17
 nodes instead of all 50,000. Latency drops from ~50ms to a
 fraction of a millisecond.
 
@@ -162,8 +162,8 @@ What `indexed` costs:
   For typical CMS write rates (a few writes per minute) this is
   invisible; for high-frequency writes (hundreds per second) it
   shows up.
-- **Storage**: roughly one index entry per row, per indexed field
-  — call it ~30 bytes/row for a small key. Negligible at any
+- **Storage**: roughly one index entry per row, per indexed field,
+  call it ~30 bytes/row for a small key. Negligible at any
   reasonable scale.
 - **Schema cost at field creation**: the `ALTER TABLE` runs once,
   during `$fields->save()`. SQLite handles it in milliseconds.
@@ -177,11 +177,11 @@ SQLite has a second indexing system called FTS5 (Full-Text Search,
 version 5). It's a different beast from B-tree indexes:
 
 - **B-tree**: ordered storage of one value per row. Great for
-  `=`, `<`, `>`, sort. Useless for `"contains the word 'scriptor'
+  `=`, `<`, `>`, sort. Useless for `"contains the word 'introduction'
   anywhere in the article body"`.
 - **FTS5**: an *inverted* index. Tokenizes text into words and
   stores `word → [item ids that contain it]`. Great for word and
-  phrase search, prefix-match (`scripto*`), ranking by relevance,
+  phrase search, prefix-match (`intro*`), ranking by relevance,
   and snippet extraction. Each cost a couple of microseconds to
   evaluate even against millions of items.
 
@@ -214,7 +214,7 @@ foreach ($hits as $hit) {
 ```
 
 …runs `SELECT … FROM items_fts WHERE items_fts MATCH :q ORDER BY
-rank` internally — sub-millisecond on tens of thousands of items.
+rank` internally, sub-millisecond on tens of thousands of items.
 
 **Smart factory defaults (2.2.0+).** Prose-typed factories pick
 sensible defaults so the common case needs no setter call:
@@ -231,15 +231,15 @@ type to find this item* defaults to indexed. Hashes, file paths,
 numeric IDs, and money amounts default out. Override either way:
 
 ```php
-// Make a slug not searchable — it's already in the URL.
+// Make a slug not searchable: it's already in the URL.
 $fields->ensure(Field::slug($post->id, 'slug')->searchable(false));
 
-// Make a numeric SKU searchable — your users will type it.
+// Make a numeric SKU searchable: your users will type it.
 $fields->ensure(Field::integer($product->id, 'sku')->searchable(true));
 ```
 
 `name` and `label` are structural columns on the `items_fts`
-table and are *always* indexed — they live on the item row itself,
+table and are *always* indexed. They live on the item row itself,
 not in `data`, and the `searchable` flag doesn't apply.
 
 What `searchable` costs:
@@ -250,13 +250,13 @@ What `searchable` costs:
   For a 5KB article, this is sub-millisecond; for a 500KB body
   on a write-heavy install, measure first.
 - **Tokenizer trade-offs**: the default `unicode61` tokenizer is
-  language-agnostic — no stemming (`"running"` won't match
+  language-agnostic. No stemming (`"running"` won't match
   `"run"`). If you need stemming, see the `tokenize =` options in
   `docs/api/storage.md`.
 
 Use `searchable` for human-readable prose: **titles**, **bodies**,
-**descriptions**, **comments**. Skip it for opaque identifiers —
-searching for `"550e8400-e29b-41d4-a716"` to find a UUID defeats
+**descriptions**, **comments**. Skip it for opaque identifiers.
+Searching for `"550e8400-e29b-41d4-a716"` to find a UUID defeats
 the tokenizer.
 
 ### A mental model for choosing
@@ -269,7 +269,7 @@ Two yes/no questions, asked per field:
    full-text search?"*
    → if yes, `->searchable()`.
 
-Both, one, or neither — each combination is fine. Most fields end
+Both, one, or neither: each combination is fine. Most fields end
 up with neither flag (display-only); a few have one; the workhorses
 of your app (titles, search-relevant body text) have both.
 
@@ -298,21 +298,14 @@ SQLite install with WAL mode:
 | Filter by `published_at < now` on **100 rows** | ~0.2 ms | ~0.1 ms |
 | Filter by `published_at < now` on **10k rows** | ~12 ms | ~0.15 ms |
 | Filter by `published_at < now` on **100k rows** | ~95 ms | ~0.18 ms |
-| Full-text search on **10k articles** | n/a — would need LIKE `%…%` scan, ~80 ms | ~1.5 ms |
+| Full-text search on **10k articles** | n/a; would need LIKE `%…%` scan, ~80 ms | ~1.5 ms |
 | Full-text search on **100k articles** | not viable (>800 ms) | ~2 ms |
 
-These are typical ballpark numbers — your hardware, schema, and
+These are typical ballpark numbers. Your hardware, schema, and
 query shape will move them. The shape is what matters: **unindexed
 JSON filtering is O(n), indexed access is effectively O(log n)**,
 and the gap widens as your data grows.
 
-Scriptor's `bin/perf-smoke.php` (a sibling-project tool) runs four
-canonical timing checkpoints against the live database, including
-`FullTextSearch::search()`. On the bundled demo dataset (about a
-dozen items) every operation comes in well under 1ms; the value
-of the flags shows up once a real install has a few thousand
-rows.
-
 ### A note on changing flags after the fact
 
 The flags aren't immutable. If you flip `->indexed(true)` on an
@@ -322,7 +315,7 @@ adds the generated column + index right then. The reverse
 (flipping `indexed` off) drops them. That makes flag changes a
 runtime concern: a quick development tweak is one `save()` away,
 but on a production database with millions of rows the `CREATE
-INDEX` takes proportional time. Plan accordingly — adding an
+INDEX` takes proportional time. Plan accordingly. Adding an
 index to a live high-write table is usually done during a low-
 traffic window.
 
@@ -357,7 +350,7 @@ $fields     = $container->get(FieldRepository::class);
 
 Define the category. `CategoryRepository::ensure()` is upsert by
 natural key (`slug`): it inserts when the slug is new and returns
-the existing row when it isn't — re-runs are safe.
+the existing row when it isn't, so re-runs are safe.
 
 ```php
 $post = $categories->ensure(new Category(null, 'Post', 'post'));
@@ -412,13 +405,13 @@ php blog-schema.php
 ```
 
 First run prints `Schema ready for category #1 (Post)`. Second
-run prints the same line — no error, because `ensure()` returns
+run prints the same line, no error, because `ensure()` returns
 the existing row on the hit path.
 
-**Third run after editing a flag** — say you change `->indexed()`
-to `->indexed(false)` and re-run? The flag change is silently
+**Third run after editing a flag.** Say you change `->indexed()`
+to `->indexed(false)` and re-run. The flag change is silently
 ignored: `ensure()` is *insert-on-miss, return-existing-on-hit* by
-design, not *upsert-with-update*. This is deliberate — a stray
+design, not *upsert-with-update*. This is deliberate: a stray
 `->indexed()` flip during schema iteration would otherwise trigger
 an `ALTER TABLE`-equivalent on every request without warning, and
 the same for `->searchable()` triggering a full FTS reindex.
@@ -436,7 +429,7 @@ $fields->save(
 ```
 
 The fluent setters work just as well on a fetched field as on a
-fresh factory output — the existing `id` carries through, and
+fresh factory output. The existing `id` carries through, and
 `save()` does an update.
 
 ## A pattern: keep schema and code together
@@ -463,7 +456,7 @@ $postCategoryId = bootBlog($container);
 $posts = $container->get(ItemRepository::class)->findByCategory($postCategoryId);
 ```
 
-This makes the schema's authority obvious — there's no "wait, where
+This makes the schema's authority obvious. There's no "wait, where
 did the `Post` category get defined?" The trade-off is the cost of
 running the `ensure()` lookups on every request; for a five-field
 schema that's a handful of microseconds and well below noise.
@@ -488,20 +481,20 @@ JSON.
 
 ## Next steps
 
-- **[Validate user input before saving](validation.md)** — `save()`
+- **[Validate user input before saving](validation.md)**: `save()`
   doesn't run your field plugins' `validate()` for you; the next
   chapter shows the canonical loop.
-- **[`docs/query-cookbook.md`](../query-cookbook.md)** — once you
+- **[`docs/query-cookbook.md`](../query-cookbook.md)**: once you
   have items, predicates and pagination are the next thing you'll
   reach for.
 
 ## Reference
 
-- [`docs/api/field-types.md`](../api/field-types.md) — every built-in
+- [`docs/api/field-types.md`](../api/field-types.md), every built-in
   field type's storage shape and config keys.
-- [`docs/api/domain.md`](../api/domain.md) — `Field` flags explained
+- [`docs/api/domain.md`](../api/domain.md), `Field` flags explained
   in the value-object reference.
-- [`docs/api/storage.md`](../api/storage.md#hot-fields--generated-columns)
-  — what `indexed` actually does to the SQL schema.
-- [`docs/field-types.md`](../field-types.md) — the cookbook for
+- [`docs/api/storage.md`](../api/storage.md#hot-fields--generated-columns),
+  what `indexed` actually does to the SQL schema.
+- [`docs/field-types.md`](../field-types.md), the cookbook for
   writing your own field-type plugin.
diff --git a/docs/tutorial/search.md b/docs/tutorial/search.md
index f5c4dc2..02c04a1 100644
--- a/docs/tutorial/search.md
+++ b/docs/tutorial/search.md
@@ -3,7 +3,7 @@
 You'll build a small knowledge base — `Article` items with title,
 body, and tags — then run searches against it. Along the way
 you'll learn the FTS5 query language iManager exposes, how
-`SearchHit` is shaped (it has one surprise — `rank` is negative,
+`SearchHit` is shaped (it has one surprise: `rank` is negative,
 lower is better), how to combine full-text matches with structural
 predicates from `Query`, and what the `rebuild()` operation is for.
 
@@ -85,7 +85,7 @@ Output:
 ```
 
 Two articles match. Notice the **snippet contains `<b>…</b>`
-markers** around matched terms — render it raw in your template, do
+markers** around matched terms. Render it raw in your template, do
 **not** re-escape, or the highlighting disappears. SQLite escapes
 the matched-term content before wrapping it in bold tags, so the
 snippet is safe to drop directly into HTML.
@@ -98,7 +98,7 @@ final readonly class SearchHit
     public int    $itemId;     // the item.id that matched
     public int    $categoryId; // the item.category_id, for filtering on the consumer side
     public string $snippet;    // HTML with <b>…</b> highlighting; render raw
-    public float  $rank;       // FTS5 relevance — negative; closer to zero = more relevant
+    public float  $rank;       // FTS5 relevance: negative; closer to zero = more relevant
 }
 ```
 
@@ -130,7 +130,7 @@ $fts->search('fts5 NOT mysql');
 $fts->search('sqlite AND (fts5 OR fts4)');
 ```
 
-`AND`, `OR`, `NOT` are case-sensitive in FTS5 — lowercase `or`
+`AND`, `OR`, `NOT` are case-sensitive in FTS5. Lowercase `or`
 becomes a literal search for the word "or". Parentheses for
 grouping work as expected.
 
@@ -140,7 +140,7 @@ grouping work as expected.
 $fts->search('"full-text search"');
 ```
 
-Quoted strings match the exact sequence — `"full-text search"`
+Quoted strings match the exact sequence: `"full-text search"`
 won't match `"full search text"`. Use for multi-word terms like
 proper nouns ("Quick Sort", "Donald Knuth") or technical phrases.
 
@@ -152,7 +152,7 @@ $fts->search('index*');
 // (in our seed data: "indexed" in article #2, "index" in article #3)
 ```
 
-The `*` suffix expands at search time — useful for autocomplete or
+The `*` suffix expands at search time, useful for autocomplete or
 when you don't know the exact stem. Note the asterisk only works
 as a **suffix**: `*index` is a parse error in FTS5. There's no
 infix wildcard.
@@ -179,7 +179,7 @@ $fts->search('"full-text" AND (storage OR layer) NOT mysql');
 ```
 
 Production code typically pre-processes the user's raw input
-before handing it to FTS5 — strip unbalanced quotes, escape
+before handing it to FTS5: strip unbalanced quotes, escape
 operator words the user didn't mean as operators, fail soft if
 the resulting expression is malformed. The simplest hardening:
 quote the whole query so it becomes a single phrase:
@@ -194,7 +194,7 @@ against parser errors.
 
 ## Scoping by category
 
-A single search call can be limited to one category — useful when
+A single search call can be limited to one category, useful when
 your install has multiple categories (Articles, Products, Pages)
 but the user is searching from inside one of them:
 
@@ -204,7 +204,7 @@ $hits = $fts->search('storage', categoryId: $article->id);
 
 Without the scope, the same query searches across **every**
 category in the install. The category id ends up as `AND
-i.category_id = :cid` in the underlying SQL — it's a cheap filter,
+i.category_id = :cid` in the underlying SQL: it's a cheap filter,
 not a separate index, but FTS5's intersection logic handles it
 efficiently.
 
@@ -224,7 +224,7 @@ $hits = $fts->search(
 ```
 
 The matching `count()` method returns the total across the whole
-result set — for the "Showing 41-60 of 312" header:
+result set, for the "Showing 41-60 of 312" header:
 
 ```php
 $total = $fts->count($query, categoryId: $article->id);
@@ -237,14 +237,14 @@ $shown = sprintf(
 ```
 
 `count()` ignores the `limit` / `offset` on the corresponding
-`search()` call — it always counts the full match set. So you do
+`search()` call: it always counts the full match set. So you do
 two queries per pagination render: one `search()` for the slice
 and one `count()` for the total.
 
 ## Combining FTS hits with structural predicates
 
 This is where iManager's FTS surface is honestly thin today.
-`search()` returns just the matching `itemId`s + snippets — it
+`search()` returns just the matching `itemId`s + snippets. It
 doesn't take a `Query` object, and `Query` doesn't take a "matches
 FTS query X" predicate. So if you want "all articles matching
 'scriptor' that are also `active = true`", you compose manually:
@@ -256,7 +256,7 @@ use Imanager\Query\Operator;
 $hits = $fts->search('scriptor', categoryId: $article->id, limit: 100);
 $matchedIds = array_map(static fn($hit) => $hit->itemId, $hits);
 
-// Now filter to only the active ones — by re-fetching and checking,
+// Now filter to only the active ones, by re-fetching and checking,
 // since Query has no in-ids predicate today:
 $active = [];
 foreach ($matchedIds as $id) {
@@ -287,11 +287,11 @@ $sql = 'SELECT items_fts.rowid, snippet(items_fts, -1, \'<b>\', \'</b>\', \'…\
 ```
 
 (Where `gen_4_published_at` is the generated column for an indexed
-`published_at` field in category id 4 — see
+`published_at` field in category id 4; see
 [schema.md](schema.md#indexed-true--what-really-happens) for how
 those names get formed.)
 
-**For "FTS over a filtered subset"**: invert the order — get the
+**For "FTS over a filtered subset"**: invert the order. Get the
 filtered ids from `Query` first, then post-filter the FTS hits:
 
 ```php
@@ -307,7 +307,7 @@ $hits = array_filter(
 );
 ```
 
-Neither pattern is elegant — a future iManager release may add
+Neither pattern is elegant. A future iManager release may add
 `Query::matchesFts(string $query)` to bridge the gap. Until then,
 the right choice depends on which side has fewer rows: FTS-first if
 the search terms are selective, predicate-first if the WHERE clause
@@ -332,21 +332,21 @@ foreach ($hits as $hit) {
 
 The two things to remember:
 
-- `$item->name` and `$item->label` come from your data — escape with
+- `$item->name` and `$item->label` come from your data: escape with
   `htmlspecialchars`.
-- `$hit->snippet` is already HTML — render raw. SQLite escapes the
+- `$hit->snippet` is already HTML: render raw. SQLite escapes the
   matched content before wrapping `<b>` tags around it, so this is
   safe.
 
 If you want to swap the highlighting tag (e.g., `<mark>` instead
-of `<b>`), you can't — `FullTextSearch::search()` hard-codes
+of `<b>`), you can't: `FullTextSearch::search()` hard-codes
 `<b>…</b>` in the SQL. The two clean workarounds: a `str_replace`
 in your template layer, or a CSS rule (`p.snippet b { background:
 yellow; font-weight: normal; }`).
 
 ## Rebuilding the index
 
-The FTS index is normally kept in sync transparently — every item
+The FTS index is normally kept in sync transparently: every item
 save writes one row to `items_fts`, every delete removes one. But
 some operations break the invariant and need a manual rebuild:
 
@@ -379,7 +379,7 @@ window.
 As of 2.2.0, FTS body content is exactly *one* function call away
 from the schema:
 
-- `name` and `label` are structural — always indexed regardless
+- `name` and `label` are structural: always indexed regardless
   of any flag.
 - For every other key in `Item::$data`, the value is included in
   the body **iff** the field's `searchable` flag is true.
@@ -389,14 +389,14 @@ from the schema:
   `->searchable(false)` on the fluent chain (see
   [schema.md](schema.md#searchable-true--what-really-happens)).
 
-The same rule applies to per-save `syncFts` and bulk `rebuild()`
-— both call into `FtsBody::compose()` so they cannot drift.
+The same rule applies to per-save `syncFts` and bulk `rebuild()`,
+both call into `FtsBody::compose()` so they cannot drift.
 
 If you migrated from 2.1.x: existing field rows for prose-typed
 content (`text`, `longtext`, `editor`, `slug`) were promoted by
 migration `0005`, so your existing FTS coverage is preserved.
 Pre-existing rows in `items_fts` itself were written under the
-old "index everything" rule though — run `vendor/bin/imanager
+old "index everything" rule though. Run `vendor/bin/imanager
 fts:rebuild` once after upgrade so they line up with the new
 filter.
 
@@ -409,20 +409,15 @@ The orders of magnitude (illustrative):
 | `search('scriptor')` | 1k items | < 1 ms |
 | `search('scriptor')` | 10k items | ~ 1 ms |
 | `search('scriptor')` | 100k items | ~ 2 ms |
-| `count('scriptor')` | any | similar to `search()` — same MATCH |
+| `count('scriptor')` | any | similar to `search()`: same MATCH |
 | `rebuild()` | 1k items | < 200 ms |
 | `rebuild()` | 100k items | low tens of seconds |
 
 FTS5's inverted-index latency stays near-constant as the dataset
-grows — that's the whole point of the index. The expensive
+grows. That's the whole point of the index. The expensive
 operation is `rebuild()`, which is O(n) over all items by design;
 you only run it manually after bulk imports or schema migrations.
 
-For a real measurement, Scriptor's `bin/perf-smoke.php`
-(sibling-project tool) includes `FullTextSearch::search()` as one
-of its four canonical timing checkpoints — the typical install
-comes in well under the budget of 100 ms.
-
 ## What just happened, in one paragraph
 
 You learned how `FullTextSearch::search()` works end-to-end: the
@@ -434,7 +429,7 @@ column-restricted matches with `name:` / `label:` / `body:`),
 how to scope a search to one category and paginate it with
 `limit`/`offset` + a parallel `count()` for the total, why
 combining FTS hits with `Query` predicates is honestly clunky
-today (no `Query::matchesFts()` bridge — drop to raw SQL or
+today (no `Query::matchesFts()` bridge: drop to raw SQL or
 post-filter manually), and the rebuild operation with its CLI hook
 and the subtle live-sync-vs-rebuild content difference. You also
 saw two snippet-safety reminders: `$hit->snippet` is pre-escaped
@@ -443,18 +438,18 @@ escape them.
 
 ## Reference
 
-- [`src/Search/FullTextSearch.php`](../../src/Search/FullTextSearch.php)
-  — the full two-method API + `rebuild()`.
-- [`src/Search/SearchHit.php`](../../src/Search/SearchHit.php) —
+- [`src/Search/FullTextSearch.php`](../../src/Search/FullTextSearch.php),
+  the full two-method API + `rebuild()`.
+- [`src/Search/SearchHit.php`](../../src/Search/SearchHit.php),
   the result value object with its negative-rank docstring.
-- [`config/schema/0002_fts.sql`](../../config/schema/0002_fts.sql)
-  — the `items_fts` table declaration with the tokenizer choice
+- [`config/schema/0002_fts.sql`](../../config/schema/0002_fts.sql),
+  the `items_fts` table declaration with the tokenizer choice
   (`unicode61 remove_diacritics 2`).
-- [`docs/query-cookbook.md`](../query-cookbook.md) — predicate
+- [`docs/query-cookbook.md`](../query-cookbook.md), predicate
   recipes for the `Query` builder; useful for the structural-half
   of any "FTS + WHERE" search you build.
-- [SQLite FTS5 reference](https://sqlite.org/fts5.html) — the
+- [SQLite FTS5 reference](https://sqlite.org/fts5.html), the
   full FTS5 grammar, ranking model, and tokenizer options.
-- [schema.md → "`searchable: true`"](schema.md#searchable-true--what-really-happens)
-  — the architecture deep-dive on what FTS5 actually is and how
+- [schema.md → "`searchable: true`"](schema.md#searchable-true--what-really-happens),
+  the architecture deep-dive on what FTS5 actually is and how
   iManager wires it.
diff --git a/docs/tutorial/setup.md b/docs/tutorial/setup.md
index c341647..72d84ec 100644
--- a/docs/tutorial/setup.md
+++ b/docs/tutorial/setup.md
@@ -9,7 +9,7 @@ minutes if you copy-paste, 15 if you pause to read the asides.
 
 - PHP **8.2 or newer**
 - The extensions iManager actually opens: `pdo_sqlite`, `mbstring`,
-  `gd`, `dom`, `json`. They're in every default PHP install — if
+  `gd`, `dom`, `json`. They're in every default PHP install. If
   yours is stripped down (Alpine container, Debian `php-cli` only),
   `apt install` / `apk add` the missing ones.
 - **Composer 2**. Composer 1 won't resolve the `^8.2` PHP constraint.
@@ -31,9 +31,9 @@ mkdir notebook && cd notebook
 composer require bigins/imanager:^2.0
 ```
 
-Composer pulls iManager 2.0.2 (or newer in the 2.x line) and writes
+Composer pulls iManager 2.2.1 (or newer in the 2.x line) and writes
 `composer.json` + `composer.lock` + a `vendor/` tree. There's nothing
-else to install — iManager is a pure-PHP library, no native build
+else to install. iManager is a pure-PHP library, no native build
 step, no compile-time configuration.
 
 ## The shape of an iManager app
@@ -92,7 +92,7 @@ What each parameter means:
 | `databasePath` | The SQLite file. iManager creates it on first call **and** runs the schema migrations into it — you don't run `CREATE TABLE` yourself. The parent directory (`data/` here) is auto-created if missing. |
 | `uploadsPath` | Where binary uploads (file / image fields) get stored. Subdirectories are `<itemId>/<fieldId>/<filename>`. Auto-created if missing. |
 | `uploadsUrl` | The URL prefix your webserver serves `uploadsPath` from. Used when iManager hands you a `File` object and you want to render its URL. For the notebook example we never serve files, so this value is just along for the ride. |
-| `cachePath` | Where the optional filesystem cache lives. iManager itself doesn't write here in the standard service graph; some hosts (e.g. Scriptor's frontend) plug a `FilesystemCache` in via this path. Auto-created if missing. |
+| `cachePath` | Where the optional filesystem cache lives. iManager itself doesn't write here in the standard service graph; some hosts plug a `FilesystemCache` in via this path (e.g. to cache rendered HTML snippets between requests). Auto-created if missing. |
 
 If you'd rather not have iManager `mkdir` for you — say, you want to
 manage filesystem layout from your deploy scripts — use
@@ -125,7 +125,7 @@ Categories and fields define the **shape**; items are the **content**.
 Add to `notebook.php`:
 
 ```php
-// Idempotent — ensure() inserts on first call and returns the
+// Idempotent: ensure() inserts on first call and returns the
 // existing row on every later call.
 $note = $categories->ensure(new Category(null, 'Note', 'note'));
 
@@ -136,7 +136,7 @@ $fields->ensure(
 
 A few things to notice:
 
-- **`ensure()` vs `save()`**: `ensure()` is upsert by natural key —
+- **`ensure()` vs `save()`**: `ensure()` is upsert by natural key:
   for categories that's the unique `slug`, for fields it's
   `(categoryId, name)`. On a hit, the existing row is returned
   unchanged; on a miss, a new row is inserted. `save()` is the
@@ -175,12 +175,12 @@ Items have their own `name` / `label` distinction:
 - `label` is the human-readable title that shows up in lists.
 
 `data` is the field values, keyed by `Field::name`. Pass an array
-and iManager wraps it in a `FieldValueBag` for you — `$saved->data`
+and iManager wraps it in a `FieldValueBag` for you. `$saved->data`
 on the returned item is the bag, not the raw array. Bags are
 immutable, so the next chapters use `$item->data->get('body')` to
 read and `$item->data->with('body', $new)` to update.
 
-> **Heads up — `save()` does not validate.** You can write any
+> **Heads up: `save()` does not validate.** You can write any
 > nonsense into `data` here. iManager's validation contract is a
 > separate `FieldTypeRegistry::get($type)->validate(...)` call that
 > the [validation chapter](validation.md) covers in full. For a
@@ -200,7 +200,7 @@ foreach ($all as $item) {
 
 `findByCategory()` returns every item in a category in `position`
 order. For one-off lookups you'd use `$items->find($id)` (by primary
-key) — there's no `findByName()` on the item repo today, so if you
+key). There's no `findByName()` on the item repo today, so if you
 need lookups by `Item::name` you go through `$items->query(...)`
 (see [`docs/query-cookbook.md`](../query-cookbook.md)).
 
@@ -218,7 +218,7 @@ Wrote item #1
     Hello from iManager.
 ```
 
-Second run (no cleanup) prints the same line plus a second item —
+Second run (no cleanup) prints the same line plus a second item.
 `ensure()` saw both the category and the field already existed and
 returned them as-is, then the item save inserted a new row (items
 have no UNIQUE on name, so duplicates are allowed). Each subsequent
@@ -232,8 +232,8 @@ Wrote item #2
     Hello from iManager.
 ```
 
-That's the natural shape of an iManager install — schema is
-declarative + idempotent, content is append-only by default.
+That's the natural shape of an iManager install: schema is
+declarative and idempotent, content is append-only by default.
 
 ## What just happened, in one paragraph
 
@@ -249,18 +249,18 @@ declare a category (`Note`), a field (`body`), and an item
 
 ## Next steps
 
-- **[Design a content schema](schema.md)** — picking the right
+- **[Design a content schema](schema.md)**, picking the right
   field types, when to mark a field `indexed` or `searchable`, and
   how to make your schema setup idempotent.
-- **[Validate user input before saving](validation.md)** — the
+- **[Validate user input before saving](validation.md)**, the
   validation contract every external input has to pass through.
 
 ## Reference
 
-- [`Imanager\DefaultBootstrap`](../../src/DefaultBootstrap.php) — the
+- [`Imanager\DefaultBootstrap`](../../src/DefaultBootstrap.php), the
   boot helper itself, fully commented.
-- [`docs/api/domain.md`](../api/domain.md) — the value objects
+- [`docs/api/domain.md`](../api/domain.md), the value objects
   (`Category`, `Field`, `Item`, `FieldValueBag`) the snippets above
   passed around.
-- [`docs/api/storage.md`](../api/storage.md) — the three repositories
+- [`docs/api/storage.md`](../api/storage.md), the three repositories
   in detail.
diff --git a/docs/tutorial/validation.md b/docs/tutorial/validation.md
index 1720da4..ea284d8 100644
--- a/docs/tutorial/validation.md
+++ b/docs/tutorial/validation.md
@@ -41,14 +41,14 @@ What it returns:
 $result = $registry->get(FieldType::Text)->validate('Hello', $field);
 
 $result->isValid;   // bool
-$result->coerced;   // mixed — the storage value, only set on success
-$result->errorCode; // InputErrorCode|null — set on failure
-$result->message;   // string — optional human-readable hint
+$result->coerced;   // mixed: the storage value, only set on success
+$result->errorCode; // InputErrorCode|null: set on failure
+$result->message;   // string: optional human-readable hint
 ```
 
 The success path uses `$result->coerced`; the failure path uses
 `$result->errorCode` and `$result->message`. The shape never holds
-both — it's a discriminated record.
+both: it's a discriminated record.
 
 ### The error codes you'll actually see
 
@@ -65,7 +65,7 @@ Three more exist for custom plugins to use:
 
 | Code | What it's there for |
 |---|---|
-| `MaxLengthExceeded` | The enum case exists, but the built-in text plugins **truncate** silently via the sanitizer rather than failing — by design, so a stray paste doesn't reject the whole form. If you want hard maximum enforcement, write a tiny custom plugin or check the length before calling `validate()`. |
+| `MaxLengthExceeded` | The enum case exists, but the built-in text plugins **truncate** silently via the sanitizer rather than failing. By design, so a stray paste doesn't reject the whole form. If you want hard maximum enforcement, write a tiny custom plugin or check the length before calling `validate()`. |
 | `ComparisonFailed` | Reserved for custom plugins that compare against another field (e.g. password confirmation). |
 | `UndefinedCategoryId` | Reserved for cross-category lookup plugins. |
 
@@ -103,8 +103,8 @@ $items      = $container->get(ItemRepository::class);
 $registry   = $container->get(FieldTypeRegistry::class);
 ```
 
-The new line is `$registry = $container->get(FieldTypeRegistry::class);`
-— that's the door to every plugin's `validate()`.
+The new line is `$registry = $container->get(FieldTypeRegistry::class);`.
+That's the door to every plugin's `validate()`.
 
 ```php
 $contact = $categories->ensure(
@@ -130,7 +130,7 @@ $fields->ensure(
 ```
 
 Four fields, three of them with min-length constraints, one
-(`email`) that *only* uses the built-in Text rules — we'll add the
+(`email`) that *only* uses the built-in Text rules. We'll add the
 email-pattern check at the application level in a moment. (For the
 schema-setup mechanics — `ensure()`, the `Field::*` factories, the
 fluent setters — see the [schema chapter](schema.md).)
@@ -147,18 +147,18 @@ $result = $registry->get($nameField->type)->validate('A', $nameField);
 if ($result->isValid) {
     echo "Coerced: {$result->coerced}\n";
 } else {
-    echo "Failed: {$result->errorCode->name} — {$result->message}\n";
+    echo "Failed: {$result->errorCode->name}: {$result->message}\n";
 }
 ```
 
 For input `'A'` against a `minLength: 2` field, you get:
 
 ```
-Failed: MinLengthExceeded —
+Failed: MinLengthExceeded:
 ```
 
 (`message` is empty because the built-in `TextFieldType` doesn't
-populate it — `errorCode` carries the meaning.)
+populate it; `errorCode` carries the meaning.)
 
 For input `'Alice'`:
 
@@ -210,7 +210,7 @@ function validateForm(
 ```
 
 This is the pattern every iManager-using app reaches for at some
-point — it's worth keeping somewhere reusable in your code. The
+point. It's worth keeping somewhere reusable in your code. The
 [field-types cookbook](../field-types.md#2-the-validation-pipeline)
 shows a slightly more sophisticated variant that also handles
 fields the input doesn't mention.
@@ -250,8 +250,8 @@ Running this prints:
 [message] MinLengthExceeded
 ```
 
-— two clean failures. No partial write, no `try / catch` —
-validation said no, so `save()` was never called.
+Two clean failures, no partial write, no `try / catch`.
+Validation said no, so `save()` was never called.
 
 Fix the input:
 
@@ -270,7 +270,7 @@ $input = [
 
 The contact form passes validation, but `email` is still anything
 the user typed. The built-in `TextFieldType` enforces *length*, not
-*format* — there's no email-pattern check in iManager today. If
+*format*. There's no email-pattern check in iManager today. If
 that matters to you, two options:
 
 ### Option A — check it before calling `validate()`
@@ -336,7 +336,7 @@ return $translator->trans(match ($code) {
 }, ['{label}' => $label]);
 ```
 
-Either way, **don't** show `$code->name` to users — `EmptyRequired`
+Either way, **don't** show `$code->name` to users. `EmptyRequired`
 is for logs, not for a form field tooltip.
 
 ## What just happened, in one paragraph
@@ -350,18 +350,18 @@ on a four-field contact form, watched it reject two fields with
 once the form was clean. You also saw where iManager's typing
 validation ends (everything length / required / format-coerce) and
 where your application layer starts (email-pattern check, business
-rules, cross-field constraints) — with two patterns for closing
+rules, cross-field constraints), with two patterns for closing
 that gap.
 
 ## Reference
 
-- [`docs/api/field-types.md`](../api/field-types.md) — every
+- [`docs/api/field-types.md`](../api/field-types.md), every
   built-in field type's config keys and the error codes its
   `validate()` can emit.
-- [`docs/field-types.md`](../field-types.md) — the cookbook for
+- [`docs/field-types.md`](../field-types.md), the cookbook for
   writing your own `FieldTypePlugin`, including a custom
   `validate()`.
-- [`src/Field/ValidationResult.php`](../../src/Field/ValidationResult.php)
-  — the discriminated record returned by every `validate()`.
-- [`src/Enum/InputErrorCode.php`](../../src/Enum/InputErrorCode.php)
-  — every error code with its stable integer value.
+- [`src/Field/ValidationResult.php`](../../src/Field/ValidationResult.php),
+  the discriminated record returned by every `validate()`.
+- [`src/Enum/InputErrorCode.php`](../../src/Enum/InputErrorCode.php),
+  every error code with its stable integer value.