docs(release): sync v0.0.22 and correct what the recent fixes made untrue

content/docs/(reference)/changelog.mdx

@@ -7,6 +7,15 @@ Each release of Marfa ships the server and its container image, the CLI for macO
 
 **Marfa doesn't upgrade a database in place.** A build refuses a database whose schema differs from its own, or that holds retired tables or settings, and leaves the file unchanged; a version change alone doesn't cause a refusal. [Upgrade](/guides/upgrade) shows how to test an export and restore on fresh storage before switching builds.
 
+## v0.0.22
+
+Released October 21, 2026. [v0.0.22 on GitHub](https://github.com/withmarfa/marfa/releases/tag/v0.0.22)
+
+For folders and app builders:
+
+- **A first sync of many files finishes in one run.** A working copy sends waiting new items and their placements in pages of up to 1,000, and reads them back in bulk, instead of using four requests for each file. Pushing 5,000 new notes took 11 pushes because of the request limit and now takes one. Fewer than 50 waiting items are sent one at a time, as before.
+- **A write a page cannot settle is sent on its own.** An entry the server skips or refuses goes alone under its key, and a page the server rate-limits is sent again on the next pass.
+
 ## v0.0.21
 
 Released October 21, 2026. [v0.0.21 on GitHub](https://github.com/withmarfa/marfa/releases/tag/v0.0.21)

content/docs/guides/back-up-and-restore.mdx

@@ -35,7 +35,7 @@ Stop the server, put the copied files where `SQLITE_PATH` and `BLOB_PATH` name,
 
 ## With a bucket
 
-When `S3_BUCKET` is set, **the container copies for you**. It streams each committed database write to the bucket within a second, keeps a day of hourly snapshots, and the `blob-replicate` housekeeping job copies each blob. A new volume started with the same bucket, prefix and secrets restores the database as it starts and brings the blobs back as replication runs.
+When `S3_BUCKET` is set, **the container copies for you**. It streams each committed database write to the bucket within a second, keeps a day of hourly snapshots, and the `blob-replicate` housekeeping job copies each blob; a blob whose store hasn't answered is skipped and copied on a later run. A new volume started with the same bucket, prefix and secrets restores the database as it starts and brings the blobs back as replication runs.
 
 Everything the instance keeps in the bucket is under its `S3_PREFIX`, so **give each instance on a shared bucket its own prefix**. [Settings](/guides/settings#every-environment-setting) says what a prefix may hold.
 

content/docs/guides/deploy.mdx

@@ -11,7 +11,7 @@ An instance is one server process and one SQLite database, so there's no databas
 | --- | --- | --- |
 | A computer you own | A Mac or a home server that stays on. | [Run it without a container](#run-it-without-a-container), under a supervisor. |
 | A container | A server you already run. | [Run it in a container](#run-it-in-a-container), with one volume. |
-| Railway | The quickest way to an instance on the internet, billed to you by Railway. | The [Marfa template](https://railway.com/new/template/5z9-Ja) creates the server, a volume and a backup bucket, and sets the secrets and the address, as [the Railway steps](https://github.com/withmarfa/marfa/blob/main/deploy/railway.md) say. |
+| Railway | The quickest way to an instance on the internet, billed to you by Railway. | The [Marfa template](https://railway.com/new/template/5z9-Ja) creates a server that runs the published release image, a volume and a backup bucket, and sets the secrets and the address, as [the Railway steps](https://github.com/withmarfa/marfa/blob/main/deploy/railway.md) say. |
 
 The server runs [housekeeping jobs](/guides/housekeeping) and backups in the background, so turn off any host feature that stops an idle service, such as Railway's Serverless mode.
 
@@ -153,7 +153,7 @@ The database and the blobs are the whole of your data, so put them on storage th
 
 `control/marfa.sock` lets a command run on the same machine, as the server's account, reach the instance with the owner's authority. You use it to claim the instance, make the first key and [recover the owner's password](/guides/sign-in-as-the-owner#recover-the-owners-password).
 
-- The socket carries no key, so the server refuses item properties, edges, tags, search, counts, events and exports through it with `401 unauthorized`. Run those with a key. Item summaries, the trash and removing an unused type you registered work through the socket.
+- The socket carries no key, so the server refuses item properties, edges, tags, search, counts, events and exports through it with `401 unauthorized`. Run those with a key. Item summaries, the trash, attachments, the status of bulk jobs and removing an unused type you registered work through the socket.
 - The CLI refuses `--socket` while `MARFA_API_URL` or `MARFA_API_KEY` is set, so unset them in that shell first.
 - The socket's folder must belong to the server's account and be readable by no one else. On Linux, install the `acl` package, which the server uses to check this.
 - A start replaces a socket that a crash left behind, and refuses one that another process listens on. Find that process before you remove the socket.

content/docs/guides/folder-safeguards.mdx

@@ -27,7 +27,7 @@ marfa folders push Notes
 ```text
 0 created, 0 updated, 0 renamed, 4 unchanged, 12 missing, 0 deleted, 0 skipped
 a large removal waits: 12 delete(s) not sent; `folders confirm` sends them, `folders restore` writes the files back
-answered 0, held 0
+the server answered 0 write(s)
 0 file(s) written
 ```
 
@@ -51,7 +51,7 @@ if status.paused.isPaused {
 
 `restore` lists each file it couldn't write back, such as one whose bytes it couldn't fetch, with the reason, and every later pull tries again.
 
-`marfa folders status Notes` shows where every file stands, and whether a removal waits, without asking the instance. `marfa folders health` takes the folder's ID and shows the server's latest report from each sign-in and local copy. A report's age says when it arrived, not whether that copy is reachable now.
+`marfa folders status Notes` shows where every file stands, and whether a removal waits, without asking the instance. A document the scan refuses, such as one with an unknown type, shows as `held` with the reason. `marfa folders health` takes the folder's ID and shows the server's latest report from each sign-in and local copy. A report's age says when it arrived, not whether that copy is reachable now.
 
 ## A missing or unreadable directory
 
@@ -80,7 +80,7 @@ marfa folders push Notes
 ```text
 0 created, 0 updated, 0 renamed, 3 unchanged, 0 missing, 0 deleted, 0 skipped
 server.pem: not taken, because its name is one a secret goes by
-answered 0, held 0
+the server answered 0 write(s)
 0 file(s) written
 ```
 
@@ -123,6 +123,6 @@ Exit `0` doesn't mean the server took every edit. A refused edit stays in the fi
 
 ### Writes still waiting
 
-A file whose write is sent but not yet answered counts as **waiting**, not unchanged: the report's first line adds `; 2 queued earlier and not delivered yet`, and `--json` has a `waiting` count.
+A file whose write is sent but not yet answered counts as **waiting**, not unchanged: the report's first line adds `; 2 already queued by an earlier scan, so not counted as created or updated here`, and `--json` has a `waiting` count.
 
 The rules behind this page are in the [folders](https://github.com/withmarfa/marfa/blob/main/conformance/spec/folders.md) chapter of the contract.

content/docs/guides/handle-files.mdx

@@ -52,7 +52,7 @@ Marfa answers with the blob's `hash`, the media type it will serve the bytes und
 
 The same bytes always give the same hash, so uploading them again **stores nothing new** and answers the same hash.
 
-An upload has **no size cap and no total time limit**. Marfa ends one with `408 request_timeout`, storing no blob, only when no bytes arrive for `MARFA_UPLOAD_IDLE_TIMEOUT_MS`, 60 seconds unless the instance sets it.
+An upload has **no size cap and no total time limit**. Marfa ends one with `408 request_timeout`, storing no blob, only when no bytes arrive for `MARFA_UPLOAD_IDLE_TIMEOUT_MS`, 60 seconds unless the instance sets it. While a store hasn't finished an earlier write or delete of the same bytes, an upload answers `503 blob_store_unavailable` and stores nothing: try again later.
 
 ## Point an item at the bytes
 

content/docs/guides/keep-folders-running.mdx

@@ -21,7 +21,7 @@ marfa folders watch
 watching every folder /Users/sam/Library/Application Support/Marfa/folders.json lists (interrupt to stop)
 /Users/sam/Notes: watching
 /Users/sam/Recipes: watching
-/Users/sam/Notes: 0 created, 1 updated, 0 renamed, 0 deleted; answered 1; 1 file(s) written
+/Users/sam/Notes: 0 created, 1 updated, 0 renamed, 0 deleted; the server answered 1 write(s); 1 file(s) written
 ```
 
 </Terminal>
@@ -100,7 +100,7 @@ marfa folders push Notes --send-only
 
 ```text
 1 created, 0 updated, 0 renamed, 2 unchanged, 0 missing, 0 deleted, 0 skipped
-answered 2, held 0
+the server answered 2 write(s), creating 1 item(s)
 send-only run: nothing was pulled, so no item's file was written or removed; the next `folders push` pulls what the server holds
 ```
 

content/docs/guides/receive-webhooks.mdx

@@ -54,7 +54,7 @@ Marfa answers with the webhook, its `secret` included:
 }
 ```
 
-Marfa shows the secret **only this once**. Every later read shows `****` and its last four characters. Keep it where your receiver can read it and nothing else can, as you would a password.
+Marfa shows the secret **only this once**. Every later read shows `****` and its last four characters. Keep it where your receiver can read it and nothing else can, as you would a password. The CLI prints the secret alone on the first line, as `marfa keys create` does with a key, and doesn't print back a secret you gave.
 
 To use a secret of your own instead, send `secret` with at least 32 characters.
 

content/docs/guides/sync-a-folder.mdx

@@ -148,7 +148,7 @@ marfa folders push Notes
 
 ```text
 0 created, 1 updated, 0 renamed, 2 unchanged, 0 missing, 0 deleted, 0 skipped
-answered 1, held 0
+the server answered 1 write(s)
 1 file(s) written
 ```
 

src/generated/cli-download.md

@@ -1,5 +1,5 @@
 ```bash
-curl -fsSL https://github.com/withmarfa/marfa/releases/download/v0.0.21/marfa-0.0.21-darwin-arm64.tar.gz | tar -xz
+curl -fsSL https://github.com/withmarfa/marfa/releases/download/v0.0.22/marfa-0.0.22-darwin-arm64.tar.gz | tar -xz
 sudo mkdir -p /usr/local/bin
 sudo mv marfa /usr/local/bin/
 marfa --version

src/generated/marfa-release.json

@@ -1 +1 @@
-{"version":"v0.0.21"}
+{"version":"v0.0.22"}

src/generated/server-image.md

@@ -1,5 +1,5 @@
 ```bash
-docker pull ghcr.io/withmarfa/marfa-server:0.0.21
+docker pull ghcr.io/withmarfa/marfa-server:0.0.22
 docker run --name marfa -d --restart unless-stopped -p 127.0.0.1:8600:8600 \
-  -v marfa-data:/data --env-file marfa.env ghcr.io/withmarfa/marfa-server:0.0.21
+  -v marfa-data:/data --env-file marfa.env ghcr.io/withmarfa/marfa-server:0.0.22
 ```