@@ -63,7 +63,7 @@ A file-backed TinyDB holds an open file handle. Call [close()][tinydb.database.T
 
 > [!TIP]
 >
-> `TinyDB` supports the context-manager protocol: `with TinyDB('db.json') as db:` closes the file on exit. TinyDB flushes on every write, so an unclosed handle will not lose data — but closing it releases the OS file handle promptly, which matters for long-running processes and on Windows, where an open handle blocks other openers.
+> `TinyDB` supports the context-manager protocol: `with TinyDB('db.json') as db:` closes the file on exit. TinyDB flushes on every write, so an unclosed handle will not lose data — but closing it releases the OS file handle promptly, which matters for long-running processes and on Windows, where an open handle blocks deleting or renaming the file.
 
 ## YAML files
 
@@ -125,7 +125,7 @@ Log(id=1, msg='cached')
 
 ### Keeping document ids in numeric order
 
-TinyDB stores document ids as strings, so a table with ten documents serializes `"1"`, `"10"`, `"2"` — lexicographic order, which undoes much of the reason to choose a human-readable format in the first place. [SortIntDocIDsMiddleware][tinydantic.tinydb.middlewares.SortIntDocIDsMiddleware] converts the ids back to integers on write and inserts them in ascending numeric order:
+TinyDB stringifies document ids before handing a table to the storage layer, so whether ten documents serialize in numeric or lexicographic order is up to the serializer. `JSONStorage` preserves insertion order and writes `"1"` … `"10"`; a serializer that sorts its keys — notably `yaml.safe_dump`, which sorts by default — writes `"1"`, `"10"`, `"2"`, which undoes much of the reason to choose a human-readable format in the first place. [SortIntDocIDsMiddleware][tinydantic.tinydb.middlewares.SortIntDocIDsMiddleware] converts the ids back to integers on write and inserts them in ascending numeric order, so both kinds of serializer agree:
 
 ```pycon
 >>> from tinydantic.tinydb.middlewares import SortIntDocIDsMiddleware
@@ -147,7 +147,7 @@ tickets:
 
 ```
 
-Without it, that file would open with `1`, `10`, `2`. The trade-off is in the name: the middleware hands integer keys to the storage below it, which is fine for JSON and YAML but may break a storage that can only serialize string keys.
+Without it, that YAML file would open with `'1'`, `'10'`, `'2'`. The trade-off is in the name: the middleware hands integer keys to the storage below it, which is fine for JSON and YAML but may break a storage that can only serialize string keys.
 
 ### Counting storage operations
 
@@ -173,15 +173,17 @@ Event(id=1, name='boot')
 
 ```
 
-The counters are exact where timings are noisy, which makes them the right evidence for a performance bug report — an issue's measurement harness can state "3 storage reads" and be reproducible on any machine. Middlewares stack, and the position in the stack is what gets measured: `ProfilingMiddleware(CachingMiddleware(JSONStorage))` counts only what the cache lets through to disk, while `CachingMiddleware(ProfilingMiddleware(JSONStorage))` counts what the database asks for before caching.
+The counters are exact where timings are noisy, which makes them the right evidence for a performance bug report — an issue's measurement harness can state "3 storage reads" and be reproducible on any machine.
+
+Middlewares stack, and the position in the stack is what gets measured. TinyDB talks to the **outermost** wrapper, so `ProfilingMiddleware(CachingMiddleware(JSONStorage))` counts what the database asks for _before_ caching, while `CachingMiddleware(ProfilingMiddleware(JSONStorage))` counts only what the cache lets through to disk. Wrap outermost to answer "how many operations did this call make?", innermost to answer "how much disk traffic did it cause?" — for one insert followed by five `all()` calls, the outer profiler reports 7 reads and 1 write, the inner one 2 reads and 0 writes.
 
 ## Beyond the built-ins
 
 TinyDB's [storage documentation](https://tinydb.readthedocs.io/en/latest/usage.html#storage-types) lists more options, and third-party packages add backends such as SQLite. Any storage that presents the TinyDB `Storage` interface works with `tinydantic` unchanged, because `tinydantic` only ever hands the storage layer JSON-safe primitives.
 
 > [!NOTE]
 >
-> `YAMLStorage` and the other helpers under `tinydantic.tinydb` are kept free of any dependency on `tinydantic`'s core, so they can later be extracted into a standalone TinyDB-extensions package. Import them from `tinydantic.tinydb.storages` today; if that extraction happens, the import path is the only thing that would change.
+> `YAMLStorage` and the other helpers under `tinydantic.tinydb` are meant to be extractable into a standalone TinyDB-extensions package, so they depend on `tinydantic`'s core as little as possible. The one dependency today is `ProcessLockMiddleware`, which raises [DatabaseLockedError][tinydantic.DatabaseLockedError] and [TinydanticUserError][tinydantic.TinydanticUserError] from `tinydantic._errors`; an extraction would have to give those errors a home. Everything else — `YAMLStorage`, `SortIntDocIDsMiddleware`, `ProfilingMiddleware`, and the operations — imports nothing from `tinydantic` at all. Import them from `tinydantic.tinydb.storages` and `tinydantic.tinydb.middlewares` today.
 
 ## Where next
 
 
@@ -4,7 +4,7 @@
 
 """Generate API documentation pages and navigation.
 
-This script is an adaption of the recipe described in
+This script is an adaptation of the recipe described in
 <https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages>
 for use with the [mkdocs-awesome-pages-plugin][1].
 
 
@@ -115,7 +115,7 @@ def __init__(
 
 
 class UniqueConstraintError(TinydanticError):
-    """A write would duplicate a unique value (tuple).
+    """A write would duplicate a unique value, or value tuple.
 
     Raised by create-style and instance-level writes when a field
     marked [Unique][tinydantic.Unique] — or the field tuple of a
@@ -223,24 +223,31 @@ def __init__(self, *, model_name: str, keys: list[str]) -> None:
 
 
 class SelectorError(TinydanticUserError, ValueError):
-    """A method got no selector, or conflicting selectors.
-
-    Selector-taking methods (``get()``, ``contains()``,
-    ``update()``, ``remove()``, ``get_or_raise()``, ``upsert()``)
-    need exactly one way to pick documents. This covers *how many*
-    were given — none, or several — not what they are: a selector
-    of the wrong kind is a
-    [QueryTypeError][tinydantic.QueryTypeError].
+    """A method needed a way to pick documents and got none.
+
+    Raised by ``update()`` and ``remove()`` when their optional
+    ``cond`` is omitted, and by ``upsert()`` when ``cond`` is
+    omitted and the document's ``id`` is ``None`` too. Each of the
+    three has a whole-table or by-id spelling that the message
+    names, so a dropped condition can never quietly become "every
+    document".
+
+    This covers *whether* a selector was given, not what it is: a
+    selector of the wrong kind is a
+    [QueryTypeError][tinydantic.QueryTypeError]. Methods whose
+    ``cond`` is a required positional — ``search()``, ``get()``,
+    ``get_or_none()``, ``contains()`` — never raise this; omitting
+    the argument is an ordinary ``TypeError``.
 
     It stays separate from
     [QueryValueError][tinydantic.QueryValueError], despite sharing
-    a base, because a selector is not always a query:
-    ``get(doc_id=1, doc_ids=[1])`` names no query at all.
+    a base, because a selector is not always a query: ``upsert()``
+    can be selected by the document's own ``id``.
 
-    ``ValueError`` is the base for the same reason
-    ``subprocess.run(capture_output=True, stdout=...)`` raises one
-    — the arguments are individually well-typed and wrong in
-    combination. tinydantic raises it instead of letting TinyDB's
+    ``ValueError`` is the base because the arguments are
+    individually well-typed and wrong in combination, the same
+    reason ``subprocess.run(capture_output=True, stdout=...)``
+    raises one. tinydantic raises it instead of letting TinyDB's
     ``RuntimeError`` (which nothing catches deliberately) or its
     hints about TinyDB internals leak through.
     """
@@ -425,8 +432,8 @@ class DocumentIDRequiredError(TinydanticError):
     """Required document ID is missing.
 
     Raised by instance operations that address a stored document by
-    its id (``replace()``, ``delete()``) when the instance was never
-    inserted, so its ``id`` is still ``None``.
+    its id (``replace()``, ``delete()``, ``patch()``) when the
+    instance was never inserted, so its ``id`` is still ``None``.
     """
 
     def __init__(self, *, model_name: str, operation: str) -> None:
 
@@ -46,15 +46,16 @@ class Follow(
 class Unique:
     """Mark a field's values as unique within the model's table.
 
-    Enforced with a check-then-write scan on create-style and
-    instance-level writes (``insert``, ``insert_many``,
-    ``save``, ``replace``, ``upsert``, ``patch``); violations
-    raise
+    Enforced with a check-then-write scan by the six writes that
+    carry a model instance (``insert``, ``insert_many``, ``save``,
+    ``replace``, ``patch``, ``upsert``); violations raise
     [UniqueConstraintError][tinydantic.UniqueConstraintError].
-    ``None`` values are exempt (SQL ``NULL`` semantics), the
-    table-level bulk ``update()``/``update_many()`` path is a
-    documented bypass, and the check is in-process only — see the
-    models guide for the full contract.
+    ``None`` values are exempt (SQL ``NULL`` semantics), the five
+    update verbs (``update()``, ``update_by_ids()``,
+    ``update_all()``, ``update_many()``, and
+    ``FindQuery.update()``) are a documented bypass, and the check
+    is in-process only — see the models guide for the full
+    contract.
 
     Attributes:
         key: Optional comparison-key callable. When set,
@@ -87,9 +88,10 @@ class UniqueConstraint:
     [UniqueConstraintError][tinydantic.UniqueConstraintError].
     A row participates in the check only when **all** of the
     constraint's fields are non-``None`` (SQL composite
-    ``UNIQUE``/``NULL`` semantics); the table-level bulk
-    ``update()``/``update_many()`` path is a documented
-    bypass, and the check is in-process only.
+    ``UNIQUE``/``NULL`` semantics); the five update verbs
+    (``update()``, ``update_by_ids()``, ``update_all()``,
+    ``update_many()``, and ``FindQuery.update()``) are a
+    documented bypass, and the check is in-process only.
 
     Attributes:
         fields: The constrained field names, in declared order.
@@ -103,13 +105,15 @@ class UniqueConstraint:
             must be pure and deterministic and return a hashable
             result. It is never called when any field value is
             ``None``. Example — slug unique per author, ignoring
-            case::
-
-                UniqueConstraint(
-                    "author_id",
-                    "slug",
-                    key=lambda a, s: (a, s.casefold()),
-                )
+            case:
+
+            ```python
+            UniqueConstraint(
+                "author_id",
+                "slug",
+                key=lambda a, s: (a, s.casefold()),
+            )
+            ```
     """
 
     fields: tuple[str, ...]
 
@@ -15,7 +15,7 @@
 -   The pipeline is fixed — match, sort, skip, limit — regardless
     of modifier call order, following the unanimous SQL/MongoDB/
     ODM convention.
--   Each clause is stated once; repeating a modifier raises
+-   Ordering and window are stated once; repeating either raises
     [QueryUsageError][tinydantic.QueryUsageError] because the wider
     ecosystem disagrees on what repetition means (Beanie appends a
     tiebreaker, Python's stable-sort idiom and pandas make the
@@ -71,7 +71,7 @@
 def _validated_window(name: str, n: object) -> int:
     """Check that a skip/limit operand is a non-negative int.
 
-    Bools are rejected like the id-condition operand rule.
+    Bools are rejected, matching the id-condition operand rule.
 
     Raises:
         QueryTypeError: If ``n`` is not an int (bools included).
@@ -114,11 +114,14 @@ class FindQuery(Generic[ModelT]):
     """An immutable, lazy fluent query over a model's table.
 
     Built by [find][tinydantic.TinydanticModel.find]; not meant to
-    be constructed directly. Modifiers (``sort``/``skip``/
-    ``limit``) return new chains and validate eagerly; terminals
+    be constructed directly. Chain-returning methods (``filter``,
+    and the ``sort``/``skip``/``limit`` modifiers) return new
+    chains and validate eagerly; terminals
     (``all``/``first``/``first_or_raise``/``count``/``exists``/
     iteration/``delete``/``update``) execute a fresh read against
     the current binding — results are never cached on the chain.
+    ``filter()`` is repeatable and ANDs into the condition; the
+    three modifiers each state their clause once.
 
     The pipeline is fixed: match, then sort, then skip, then
     limit, regardless of the order modifiers are called in. Every
@@ -433,7 +436,7 @@ def _in_window_order(written: list[int], window: list[int]) -> list[int]:
 
         Condition writes report ids in table order, but a chain
         promises the order its own read pipeline produced — the
-        whole point of honouring ``sort``/``skip``/``limit``.
+        whole point of honoring ``sort``/``skip``/``limit``.
         """
         touched = set(written)
         return [doc_id for doc_id in window if doc_id in touched]
@@ -456,11 +459,17 @@ def delete(self) -> list[int]:
         concrete ids first and removes those — unlike Beanie,
         which silently ignores sort/skip/limit on delete. Under
         the documented single-process, single-threaded contract
-        the two paths are observably identical.
+        the two paths remove the same documents and return the
+        same ids.
 
-        An empty window is a no-op returning ``[]`` with zero
-        storage writes. Deleting the whole table via ``find()``
-        with no condition is legal (the spelling is explicit);
+        They differ in storage cost on an empty window: the
+        resolved-ids path returns ``[]`` without writing, while
+        the condition-only path reaches TinyDB's
+        ``Table.remove(cond=…)``, which writes the table back
+        whether or not anything matched. Tracked in issue #145.
+
+        Deleting the whole table via ``find()`` with no condition
+        is legal (the spelling is explicit);
         [truncate][tinydantic.TinydanticModel.truncate] remains
         the idiomatic one-pass spelling.
 
@@ -511,6 +520,8 @@ def update(
         Raises:
             DocumentIDUpdateError: If a mapping contains
                 ``id``.
+            RevisionUpdateError: If a mapping contains
+                ``revision_id`` on a ``use_revision=True`` model.
             UnknownUpdateFieldError: If a mapping has non-field
                 keys and ``extra_keys`` is ``"reject"``.
             pydantic.ValidationError: If a value or a merged
 
@@ -126,10 +126,13 @@ class ProfilingMiddleware(Middleware):
     to zero them between measurements.
 
     Middlewares stack, and the position in the stack is what gets
-    measured: ``ProfilingMiddleware(CachingMiddleware(JSONStorage))``
-    counts only the operations the cache lets through, while
+    measured. TinyDB talks to the **outermost** wrapper, so
+    ``ProfilingMiddleware(CachingMiddleware(JSONStorage))`` counts
+    what the database asks for *before* caching, while
     ``CachingMiddleware(ProfilingMiddleware(JSONStorage))`` counts
-    what the database asks for before caching.
+    only the operations the cache lets through to the file. Wrap
+    outermost to measure the database's demand; wrap innermost to
+    measure real disk traffic.
 
     Attributes:
         read_count: Number of ``read()`` calls seen so far.
 
@@ -51,7 +51,11 @@ def __init__(
         access mode is appropriate for writing.
 
         Note: Using an access mode other than `r` or `r+` will probably
-        lead to data loss or data corruption!
+        lead to data loss or data corruption! The binary modes `rb`
+        and `rb+` are accepted without a warning — inherited from
+        TinyDB's `JSONStorage`, whose check this mirrors — but they
+        do not work here: `write` writes a `str`, which raises
+        `TypeError` on a binary handle.
 
         Args:
             path: Where to store the YAML data.
@@ -60,7 +64,7 @@ def __init__(
             encoding: The encoding used to open the storage file.
             access_mode: Mode in which the file is opened (`r`, `r+`).
             **kwargs: Additional keyword arguments passed to
-                `yaml.dump()` when writing data.
+                `yaml.safe_dump()` when writing data.
 
         Raises:
             ImportError: If PyYAML is not installed — it ships in