From 70dd0fa12048b978071cb51b0660418373d6256f Mon Sep 17 00:00:00 2001
From: August Cayzer <a@cyzr.me>
Date: Sun, 25 Oct 2026 00:56:49 +0100
Subject: [PATCH 1/2] docs(cli): add the item fields a working copy writes and
 queries

---
 content/docs/(reference)/cli.mdx | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/content/docs/(reference)/cli.mdx b/content/docs/(reference)/cli.mdx
index 60fc908b..e12510cd 100644
--- a/content/docs/(reference)/cli.mdx
+++ b/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. 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.
+
+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.
+
+`--updated-after` without `--sort` lists in change order, oldest first. Combined with any other sort, it 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>

From 1a31ac99f7ea4b849059d2a6fd34c51995a422f4 Mon Sep 17 00:00:00 2001
From: August Cayzer <a@cyzr.me>
Date: Sun, 25 Oct 2026 01:38:32 +0100
Subject: [PATCH 2/2] docs(cli): true the working copy's sort, edge and
 own-time notes

---
 content/docs/(reference)/cli.mdx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/content/docs/(reference)/cli.mdx b/content/docs/(reference)/cli.mdx
index e12510cd..ed851de0 100644
--- a/content/docs/(reference)/cli.mdx
+++ b/content/docs/(reference)/cli.mdx
@@ -251,15 +251,15 @@ A working copy takes every item field the API does, and answers a list or search
 | 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. The two can't be combined. |
+| `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.
+**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.
+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` without `--sort` lists in change order, oldest first. Combined with any other sort, it 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.
+`--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