README.md rewritten sentence by sentence (closes #219)

The old text served as the list of what a reader needs covered. The new
text leads with what quak is, what it is for and how to use it. Every
command, option, exit code and file layout follows in reference sections,
then the library reference, then design, entrypoints and development.
Every statement was checked against the code on next; the places where
the old text disagreed with it are listed in the pull request. No sentence
runs past about 30 words, every table is now a list, and no issue links or
project history remain in text meant for users. Two code comments that
named README sections now name the new ones.

Model: fable-5-1

README.md

@@ -158,11 +158,11 @@ output to `~/quak-backup.log`. Sunday's run adds `--verify`:
 
 A run with `--verify` does all a plain run does. It also hashes each original
 already in the backup and compares the result with the content hash. The content
-hash is the hash of the file's bytes that Ente recorded at upload. The run
+hash is the hash of the file's bytes that Ente recorded at upload. It fetches a
-fetches a new copy of each original that does not match, and replaces the
+new copy of each original that does not match, and replaces the original once
-original once the copy matches. Sunday's run is the `--verify` run, rather than
+the copy matches. Sunday's run is the `--verify` run, rather than a second job
-a second job that night, because two backups of one directory cannot run at
+that night, because two backups of one directory cannot run at once. The second
-once. The second one exits 2 without doing anything.
+one exits 2 without doing anything.
 
 Cron runs the job with a short `PATH`, usually `/usr/bin:/bin`, so the crontab
 names quak by its full path. quak finds the saved session through `HOME`, which
@@ -320,10 +320,10 @@ grid. It writes one file, also for a live photo. Without `--out`, the name is
 #### `quak backup <dir> [--json] [--verify]`
 
 Backs up every file in the account to `<dir>`. The layout is described under
-"The backup directory". The command downloads only the originals that are not
+"The backup directory". It downloads only the originals that are not yet in the
-yet in the backup, and it goes on past a file that fails. A file is downloaded
+backup, and it goes on past a file that fails. A file is downloaded once,
-once, however many collections hold it. An original the cache already holds is
+however many collections hold it. An original the cache already holds is copied
-copied from there instead.
+from there instead.
 
 Progress goes to stderr: one line per original fetched, and a `FAILED` line for
 each original or album that failed. The run ends with a summary of counts and,
@@ -689,10 +689,10 @@ The JSON file beside an original holds:
 
 Update times are in microseconds, as Ente records them.
 
-The JSON also holds the machine-learning data Ente computed for the photo, as
+The file also holds the machine-learning data Ente computed for the file, as
 `mlData`. Ente's apps detect faces in each photo and compute a CLIP embedding
 for it, a list of 512 numbers that describes what the photo shows. `mlData`
-holds everything but that embedding. In its place the JSON holds `keywords`,
+holds everything but that embedding. In its place the file holds `keywords`,
 derived from the embedding as described under "Keywords". A file with no
 machine-learning data has neither field. A file whose data holds no usable
 embedding has no `keywords`.
@@ -857,8 +857,8 @@ ends, whether it succeeded or failed.
 
 The lock is a directory that
 [proper-lockfile](https://github.com/moxystudio/node-proper-lockfile) creates.
-While the backup runs, it updates the modification time of `backup.lock` every 5
+While the backup runs, the backup updates the directory's modification time
-seconds. A second backup of `<dir>` fails at once: it prints
+every 5 seconds. A second backup of the directory fails at once: it prints
 `quak: another backup of <dir> is running` and exits 2. A run that is killed, or
 cut off by a crash, can leave the lock behind. Once the lock has gone 10 seconds
 without an update, the next run takes it over, so nobody has to remove it by
@@ -1055,14 +1055,14 @@ still in flight.
 `"refresh"`, `"fetchMLData"` for a machine-learning fetch, and
 `"precacheThumbnails"` or `"precacheOriginals"` for the two background
 downloads. Its `status` is `"started"` as the work starts and `"done"` as it
-ends. A refresh or a machine-learning fetch that fails ends with `"failed"`
+ends. A refresh or a machine-learning fetch that fails ends with `"failed"` and
-instead, with the message in `error`. In between, a refresh sends `"progress"`
+the error message instead. In between, a refresh sends `"progress"` after each
-after each collection whose files it fetched: `fetched` is the number of
+collection whose files it fetched: `fetched` is the number of collections
-collections fetched so far, and `total` the number it will fetch. A refresh
+fetched so far, and `total` the number it will fetch. A refresh fetches the
-fetches the files of each collection that is new or changed since the cache's
+files of each collection that is new or changed since the cache's copy, so on an
-copy, so on an empty cache it fetches those of every collection. The `"done"`
+empty cache it fetches those of every collection. The `"done"` event of a
-event of a machine-learning fetch, and of each background download, also carries
+machine-learning fetch, and of each background download, also carries `fetched`:
-`fetched`: how many items it newly stored.
+how many items it newly stored.
 
 `lib.status()` returns a `LibraryStatus`. It holds the collection and file
 counts. `lastRefreshAt` is the time of the last refresh that succeeded, and
@@ -1381,9 +1381,9 @@ They differ because a download's length depends on the file and the link. A
 whole-transfer deadline short enough to catch a hung connection would cancel a
 large video on a slow link that is still making progress. The download deadline
 restarts each time bytes arrive, so a slow download runs as long as it keeps
-moving, and one that stalls is aborted after 60 seconds of silence. The download
+moving, and one that stalls is aborted after 60 seconds of silence. It covers
-deadline covers the wait for the headers as well as the body. There is no limit
+the wait for the headers as well as the body. There is no limit on the total
-on the total length of a download.
+length of a download.
 
 A request that changes state is not blindly replayed. Every `POST` and `PUT` in
 the endpoint list under "HTTP API" goes through this rule. Verifying a second
@@ -1456,8 +1456,8 @@ exported `beginLogin`, `unwrapAuth`, `decryptCollection`, `decryptFile`,
 `downloadFile` and `downloadThumbnail` need the same.
 
 `client.logout()` clears the token and zeroes the key buffers in place. After
-it, every other method on that client throws. `logout()` does not contact the
+it, every other method on that client throws. It does not contact the server, so
-server, so the token stays valid there and in any saved snapshot. Call
+the token stays valid there and in any saved snapshot. Call
 `await client.logoutOnServer()` before `logout()` to end the session on the
 server.
 

test/cli/log.test.ts

@@ -328,7 +328,7 @@ describe("what the library reports", () => {
         ]);
     });
 
-    // Each operation is named in plain words.
+    // Each operation is named in plain words, as the README names it.
     it("logs a refresh's progress at info, and its start and end at debug", () => {
         const { log, lines } = collect();
         const onProgress = logRefresh(log);