docs(cli): add the item fields a working copy writes and queries

content/docs/(reference)/cli.mdx

@@ -244,6 +244,23 @@ The `marfa device views` commands read saved views from the database named by `-
 
 Each command takes `--json`. A view whose whole query or grouping is not held is refused with a reason.
 
+## Write and read items in a working copy
+
+A working copy takes every item field the API does, and answers a list or search the way the server does. A create or an edit shows in the copy at once and waits in the queue until a drain sends it, as [Devices](/devices#a-write-made-offline) explains.
+
+| Command | Options |
+| --- | --- |
+| `marfa device items create` | `--state` (`active`, `archived` or `trashed`; `revoked` is refused), `--capture-latitude` with `--capture-longitude`, and `--edges <json>`, an object from an edge type to the IDs of the items it points at. |
+| `marfa device items update` | `--occurred-at <time>` sets the item's own time. `--clear-occurred-at` gives the item no time of its own, so it sits at its creation time. If the item's create hasn't been sent yet, the copy shows the time the create was queued until the instance answers. The two can't be combined. |
+| `marfa device items list` | `--source`, `--updated-after` (inclusive), `--updated-before` (exclusive) and `--sort properties.<field>` with `--direction`. |
+| `marfa device search <text>` | `--tier`, `--occurred-after` and `--occurred-before` (both exclusive). |
+
+**A create is one write.** The state, the capture location and the edges go in the body of the write that creates the item. If the instance refuses any edge, for example because a target doesn't exist, it creates neither the item nor its edges, and the write stays in the queue as `refused` with its body. While the write waits, the copy shows each edge. When the instance answers, the copy holds the edges the instance made in their place. An answer carries at most 50 edges of one type, so an edge it leaves out stays shown until the next catch-up brings the instance's own.
+
+A create the instance would refuse as malformed, such as a `revoked` state, a coordinate that isn't a finite number, or an edge type or target that isn't valid, is refused before it is queued, with the error code the instance would answer.
+
+`--updated-after` lists in change order, oldest first. `--sort updated-at` or `--direction asc` on its own keeps that order; any other sort or direction is refused with `validation_error`. A `properties.<field>` sort puts numbers and booleans first, then text, then items with the field missing, null, an object or an array, in either direction. Items that compare equal go by ID.
+
 ## Exit codes
 
 <include cwd>src/generated/cli/exit-codes.md</include>