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
@@ -314,16 +314,16 @@ refused, because both files would land on it.
 #### `quak get-thumb <fileID> [--out <path>]`
 
 Downloads and decrypts one file's thumbnail, the small JPEG Ente shows in a
-grid. It writes one file, also for a live photo. Without `--out`, the name is
+grid. It works as `get` does. Without `--out`, the name is `thumb_` followed by
-`thumb_` followed by the title. In all else it works as `get` does.
+the title.
 
 #### `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,
@@ -362,8 +362,7 @@ Writes the metadata quak keeps about the account, its collections and its files
 as JSON files under `<dir>`. The layout is described under "The metadata dump
 directory". Photo content is not written. With `--exif`, or its alias `--all`,
 the command also fetches each file's original and records the image's own
-metadata from it (see "The metadata dump directory"). Each original it fetches
+metadata from it (see "The metadata dump directory").
-stays in the cache.
 
 Ente's apps compute machine-learning data for each photo, such as the faces in
 it (see "The JSON beside each original"). The command fetches it in requests of
@@ -378,9 +377,9 @@ word, and does not change the exit status.
 
 #### `quak helper list-missing-thumbnails [--json]`
 
-Finds the files whose thumbnail is missing on the server. It downloads the
+Finds the files whose thumbnail is missing on the server. It downloads every
-thumbnail of every file you own, one collection at a time, newest updated first,
+thumbnail in the account, one collection at a time, newest collection first, so
-so on a large account it takes a while. A thumbnail counts as missing when the
+on a large account it takes a while. A thumbnail counts as missing when the
 server answers with an empty body or with HTTP 404. Any other failure is logged
 as `[<collection>] Could not check <title>: <reason> (not reported as missing)`,
 and the file is left out of the list. The command exits 0 even when some files
@@ -478,11 +477,20 @@ before any request is sent. The command logs `Invalid file ID: <arg>` or
 
 ### What quak prints
 
-stdout holds a command's output, such as the listing or the JSON, and the
+stdout holds only a command's output: the listing, the JSON, or nothing. The
-prompts of `login`. Every other line goes to stderr as a log line at one of six
+prompts of `login` go to stdout too. Every other line goes to stderr as a log
-levels. From the quietest, the levels are fatal, error, warning, info, debug and
+line at one of six levels. From the quietest, the levels are fatal, error,
-trace. A run prints the lines at its own level and at every quieter one. The
+warning, info, debug and trace. A run prints the lines at its own level and at
-level is info unless `-v`, `-vv` or `-q` says otherwise.
+every quieter one. The level is info unless `-v`, `-vv` or `-q` says otherwise.
+
+The one exception is a command line quak cannot parse, such as a missing
+argument, an unknown option or `-q` with `-v`. quak refuses it with one
+`error: …` line that is not a log line, and exits 1. `-q` does not hide that
+line. `quak` with no command prints the usage on stderr and exits 1.
+
+`yarn quak` prints yarn's own lines on stdout as well. To pipe a command's
+output, run `yarn --silent quak files --json` or
+`node dist/bin/quak.js files --json` instead.
 
 - Fatal: why a command exits non-zero. A command that runs and exits non-zero
   logs at least one fatal line. A command that exits 1 because files or albums
@@ -508,15 +516,6 @@ level is info unless `-v`, `-vv` or `-q` says otherwise.
 one that exits non-zero prints only its fatal lines. The prompts of `login` are
 not log lines, and `-q` leaves them alone.
 
-Two things on stderr are not log lines. A command line that quak cannot parse,
-such as a missing argument, an unknown option or `-q` with `-v`, is refused with
-an `error: …` message, and quak exits 1. `-q` does not hide the message. `quak`
-with no command prints the usage on stderr and exits 1.
-
-`yarn quak` prints yarn's own lines on stdout as well. To pipe a command's
-output, run `yarn --silent quak files --json` or
-`node dist/bin/quak.js files --json` instead.
-
 With `--json`, a command's JSON on stdout takes the place of its summary on
 stderr. For `backup`, that is the `--- Backup complete ---` line, the counts and
 the `Failed files:` list. For `list-missing-thumbnails`, it is
@@ -689,13 +688,13 @@ 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 the `clip` block, which holds that embedding. In its place
+holds everything but that embedding. In its place the file holds `keywords`,
-the JSON holds `keywords`, derived from the embedding as described under
+derived from the embedding as described under "Keywords". A file with no
-"Keywords". A file with no machine-learning data has neither field. A file whose
+machine-learning data has neither field. A file whose data holds no usable
-data holds no usable embedding has no `keywords`.
+embedding has no `keywords`.
 
 The backup waits for the library's fetch of machine-learning data to finish
 before it writes the JSON files. When a file's data cannot be fetched,
@@ -748,11 +747,11 @@ derives a file's keywords the way the app sorts it. The categories are:
 
 Each category has a query, and a text embedding of that query from Ente's CLIP
 text model. A file's score for a category is the cosine similarity of the file's
-embedding and the category's. That is a number from -1 to 1; the more alike the
+embedding and the category's: a number from -1 to 1, higher the more alike the
-two embeddings are, the higher it is. The file falls in the category when its
+two embeddings are. The file falls in the category when its score reaches the
-score reaches the category's minimum score. The keywords are the titles of the
+category's minimum score. The keywords are the titles of the categories the file
-categories the file falls in, highest score first. A video never falls in a
+falls in, highest score first. A video never falls in a category marked "no
-category marked "no videos", as in the app.
+videos", as in the app.
 
 #### Collection directories
 
@@ -775,21 +774,19 @@ ignoring case, each gets its ID added: two albums named `Trip` become
 `Trip (10)/` and `Trip (11)/`. Two files in one collection whose titles match,
 ignoring case, get their IDs added before the extension: `IMG_0001 (12345).JPG`
 and `IMG_0001 (12346).JPG`. A collection named like another collection's JSON
-file, such as `Trip.json` beside `Trip`, also gets its ID added. A file name
+file, such as `Trip.json` beside `Trip`, also gets its ID added. A name too long
-longer than 255 bytes, the limit on most file systems, gets its ID added too. So
+for a file name, which most file systems limit to 255 bytes, gets its ID added
-does a collection name longer than 250 bytes, which leaves room for `.json`.
+too. It is then cut short before the ID, just far enough to fit. IDs never
-Either name is then cut short before the ID, just far enough to fit. IDs never
 change, so a name stays the same from run to run until such a clash appears or
 goes away.
 
 Each run removes every symlink in a collection's directory that points into the
 date folders and is not one of its current links, yours included. A file or
 symlink of yours at the name of one of its links is replaced by the link. A
-directory of yours at that name stays, and the photo whose link it blocks goes
+directory at that name stays, and the file goes into `failures.json`. Anything
-into `failures.json`. Anything else you put under `collections/` stays. A run
+else you put under `collections/` stays. A run removes the directory and JSON of
-removes the directory and JSON of a collection that was deleted or renamed, once
+a collection that was deleted or renamed, once the directory holds nothing else.
-the directory holds nothing else. One that still holds something of yours stays,
+One that still holds something of yours stays, with its JSON.
-with its JSON.
 
 A collection whose directory or JSON cannot be written does not stop the run.
 For example, a file you put there may already have the directory's name. The run
@@ -834,9 +831,8 @@ Each entry holds:
 
 - `fileID` and `title`;
 - `classification`: the kind of failure;
-- `attempts`: how many runs in a row have failed the file;
+- `attempts`: how many runs have tried the file;
-- `lastTriedAt`: when the run that last tried it finished its refresh, as a Unix
+- `lastTriedAt`: when it was last tried, as a Unix time in milliseconds;
-  time in milliseconds;
 - `error`: the error, as quak printed it.
 
 The kinds are:
@@ -859,8 +855,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
@@ -964,9 +960,9 @@ of the same name apart.
 `files`. Each `<fileID>.json` holds the fields a backup's JSON beside an
 original holds, with these differences:
 
-- `imageMetadata` is written only with `--exif`. The original of every file,
+- `imageMetadata` is written only with `--exif`. The original of every file is
-  videos included, is then downloaded and read for its EXIF, XMP and JPEG
+  then downloaded, videos included, and read as a backup reads it (see "The JSON
-  dimensions.
+  beside each original").
 - A file whose original holds no image metadata gets no `imageMetadata` field.
 - An original that cannot be downloaded or read gives `imageMetadataError`
   instead.
@@ -1057,14 +1053,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
@@ -1079,10 +1075,10 @@ cached, so the next fetch asks for it again. The reasons are kept in memory
 only.
 
 `lib.close()` stops the background timer. It can be called more than once. A
-refresh in flight is left to finish, with its write to the cache. `close()`
+refresh in flight is left to finish, with its write to the cache. The promise
-returns a promise. It resolves once that refresh, the machine-learning fetch and
+`close()` returns resolves once that refresh, the machine-learning fetch and the
-the background downloads already running have all finished. The cache directory
+background downloads already running have all finished. The cache directory can
-can then be removed. After `close()`, `fresh()`, `freshCollections()`,
+then be removed. After `close()`, `fresh()`, `freshCollections()`,
 `freshFiles()` and `lib.backup()` reject with `the library is closed`.
 
 ### Default reads and fresh reads
@@ -1187,11 +1183,11 @@ progress of that one file.
   keyed by tag name, each as exifreader decodes it with its `id`, `value`,
   `description` and `computed` value. For example, `Make` is
   `{ id: 271, value: ["Example"], description: "Example", computed: "Example" }`.
-  A tag that exifreader has no name for is keyed `undefined-<tag number>`. The
+  A tag exifreader has no name for is keyed `undefined-<tag number>`. The tags
-  tags of the thumbnail embedded in the file are under `Thumbnail`, so they
+  of the thumbnail embedded in the file are under `Thumbnail`, so they cannot
-  cannot hide the main image's tags of the same name. The thumbnail image itself
+  hide the main image's tags of the same name. The thumbnail image itself is
-  is left out. Any file exifreader cannot read gives `{}`, and a video gives
+  left out. Any file exifreader cannot read gives `{}`, and a video gives `{}`
-  `{}` without being downloaded.
+  without being downloaded.
 - `await photo.make(opts?)` returns one common EXIF field, picked from the tags
   `exif()` returns and typed as in `PhotoExif`, or `undefined` when the file
   lacks it. These methods do the same for their fields:
@@ -1311,9 +1307,8 @@ Only the requests named above go through the pools. A refresh,
 with
 `new RequestPools({ metadataConcurrency, contentConcurrency, thumbnailConcurrency })`
 and pass it as `pools`. Each pool serves on-demand work ahead of background
-work. Two tasks given to `BoundedPool.run()` with the same `key` run once while
+work. A task submitted under a key that is still pending is not run a second
-the first is pending, and both get its result. An idle pool never lends its
+time. An idle pool never lends its slots to a busy one.
-slots to a busy one.
 
 `lib.backup()` works on as many originals at once as the content pool allows, 5
 by default. `quak backup` uses the default. The limit covers everything it does
@@ -1383,9 +1378,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
@@ -1407,13 +1402,13 @@ that rule although they look like connect-time failures. On Linux they are also
 delivered on an established socket, after the request may have been written.
 They stay retryable for requests that change nothing. Bun's `ConnectionRefused`
 and `FailedToOpenSocket` are treated the same way: a request that changes
-nothing is retried on them, and a `POST` or `PUT` is not replayed on them. Bun
+nothing is retried on them, and a `POST` or `PUT` is not replayed on them. When
-reuses a connection it kept open from an earlier request. When that connection
+a connection bun kept open from an earlier request closes before any answer, bun
-closes before any answer, bun sends the request again on a new one. If that one
+sends the request again on a new connection. If that one fails, bun gives one of
-fails, bun gives one of these codes although the server may already have the
+these codes although the server may already have the request. The upload of a
-request. The upload of a thumbnail to its presigned URL is exempt from the rule.
+thumbnail to its presigned URL is exempt from the rule. It stores one whole
-It stores one whole object at one key in one request, so replaying it has no
+object at one key in one request, so replaying it has no partial state to
-partial state to damage.
+damage.
 
 A download is retried as a whole: the request, the reading of the body and the
 decryption. A socket reset after the response headers have arrived surfaces in
@@ -1451,15 +1446,15 @@ working client from that snapshot without logging in again. It checks every
 field and each key's length first, and throws an error naming the bad field.
 
 `Client.fromJSON` works only once libsodium, the cryptography library quak uses,
-is loaded. `Client.login` loads it, and `Client.fromJSON` does not. A program
+is loaded. Only `Client.login` loads it. A program that restores a session in a
-that restores a session in a new process first runs `await sodium.ready`, with
+new process first runs `await sodium.ready`, with `sodium` imported from
-`sodium` imported from `libsodium-wrappers-sumo`, which quak depends on. The
+`libsodium-wrappers-sumo`, which quak depends on. The exported `beginLogin`,
-exported `beginLogin`, `unwrapAuth`, `decryptCollection`, `decryptFile`,
+`unwrapAuth`, `decryptCollection`, `decryptFile`, `downloadFile` and
-`downloadFile` and `downloadThumbnail` need the same.
+`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.
 
@@ -1912,9 +1907,7 @@ These apply to people and to coding agents alike.
 - Not pinned:
     - bun, which `make build-bin` takes from `nix-shell -p bun`;
     - `make` and `git`, which `script/bootstrap` installs from the system
-      package manager when they are missing, as every `Dockerfile` stage does;
+      package manager when they are missing, as every `Dockerfile` stage does.
-    - `bash` and `curl`, which `script/bootstrap` installs the same way when it
-      has to install Node.
 - Follow the workflow above: branches off `next`, tests first and committed
   failing, and `next` merged into `main` by sneak alone.
 - Before every commit, `make lint` and `make fmt-check` must pass. `make lint`

src/cli-log.ts

@@ -1,18 +1,15 @@
 // The CLI's log level, and the one function the commands write stderr lines
 // through.
 //
-// Every line quak logs goes to stderr, at one of six levels, from the
+// Every line quak prints on stderr is a log line at one of six levels, from
-// quietest: fatal, error, warning, info, debug, trace. A run prints the lines
+// the quietest: fatal, error, warning, info, debug, trace. A run prints the
-// at its own level and at every quieter one. Its level is info unless `-v` or
+// lines at its own level and at every quieter one. Its level is info unless
-// `-q` asks for another (see "What quak prints" in the README). A command that
+// `-v` or `-q` asks for another (see "What quak prints" in the README). Every
-// runs and exits non-zero logs a fatal line saying why, so even `-q`, which
+// command that exits non-zero logs a fatal line saying why, so even `-q`, which
-// prints only fatal lines, never leaves such an exit unexplained. An error
+// prints only fatal lines, never leaves a non-zero exit unexplained. An error
 // line reports something that failed, such as a file or an album, and a
 // warning something that did not fail but needs the user's attention. stdout
-// carries a command's output and the prompts of `login`, and is not a log.
+// carries only a command's output and is not a log.
-// Two things on stderr are not log lines: the `error:` message for a
-// command line that quak cannot parse, and the usage printed when no command
-// is given.
 //
 // The library itself writes no lines: its layers report through callbacks, and
 // the CLI logs what they report. `logRequests` gives the API client options

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);