docs: correct behavioural contracts the code stopped matching

An audit compared every prose claim against the implementation. These are
the ones a scripting user would have been burned by. In every case the
code is right and the documentation was describing an older version.

EXIT CODES — eleven places across five files

sync.md, search.md x3, inspect.md x4, auth.md and config.md all said an
unhandled HTTPError escapes as a Python traceback and exits 1, "not the
2 that the rest of the CLI uses". main() has caught it since the
error-advice refactor:

    except urllib.error.HTTPError as e:
        specific = e.code in (401, 403, 404, 429) or 500 <= e.code < 600
        _fail_with_context(_advice_for_http(e), offer_traceback=not specific)

and _fail_with_context ends in sys.exit(2), with the traceback written at
debug level so -v shows it and a default run does not. Measured, not
assumed — stubbing a 400 into `da daily`:

    [error] DeviantArt refused the request (HTTP 400 Bad Request).
    ACTUAL exit code: 2

The docs told anyone writing `case $? in` to branch on a code the CLI
never returns. PermissionError was documented the same way and is
likewise caught, as an OSError.

Note what was NOT changed: `config get` exiting 1 for an unset key,
`auth status` exiting 1 on warn, `sync watched` exiting 1 on partial
failure, and exit-codes.md's statement that a genuinely unrecognised
exception is left alone with its traceback. Those are all still true —
main()'s except chain does not catch, say, a ValueError.

`da whoami` was described as calling the API directly "rather than
through the retry-on-401 wrapper", so a server-side revocation supposedly
produced a traceback. cmd_whoami goes through authed_http_json and
recovers by itself. The confusion is understandable: cmd_auth_status DOES
call http_json directly a few hundred lines earlier, deliberately,
because its job is to test the token as-is.

RESUME — sync.md, four passages

"There is no per-artist 'how far did I get' marker in state.json …
Resuming is manual." There is: _record_gallery_progress writes
state["galleries"][<artist>], _gallery_progress reads it back, and a
truncated walk logs `resuming alice at offset 96 (previous walk did not
finish)`. The early all-known exit is gated on the artist being recorded
complete, precisely so it cannot strand the rest of the gallery.

`sync watched` was documented as walking every artist at "--offset 0,
always". It passes offset=None deliberately, with a comment saying why —
pinning to 0 would defeat per-artist resume across a backfill, which is
the case that needs it most. docs/reference/files-on-disk.md already
documented the marker, so sync.md contradicted both the code and a
sibling page.

`da auth status` — documented as offline

"no network, no locks, one small object on stdout" and "Nothing else is
consulted — not the config file, not the network, not DeviantArt". It
resolves an access token and calls /placebo, which means it takes the
token lock and, on an hourly polling cadence, rotates the refresh token
on almost every call. The page now says so, and documents the two states
it can return that were missing from the three-key table — `revoked` and
`unreachable`, plus the `error` key that accompanies them. The
distinction matters: `unreachable` is why a dropped wifi link does not
send someone to re-authenticate.

SMALLER, ALL VERIFIED AGAINST THE CODE

  - "Eleven commands accept --json" — thirteen do, walking build_parser().
    The list also omitted `daily` and `search user`.
  - "in particular DA_JITTER is read by install_schedule.sh … never by
    `da` itself" — config.py's env_map has DA_JITTER. It was documented
    under a heading that says the opposite; now listed as the config
    override it is, in the table with the other four.
  - "NO_COLOR … Honoured regardless of --color" — it is consulted only in
    the `auto` branch; `--color always` sets colour unconditionally, which
    is what makes forcing colour into a pipe possible.
  - config.md said values are "not validated or converted" and that `set`
    has no exit 2. Measured: `da config set jitter 40%` prints
    `[error] jitter must be a number — got '40%'` and exits 2. A
    non-object config.json warns and is replaced at exit 0, rather than
    raising the documented TypeError.

Verified: lychee 194 OK / 0 errors with fragments checked, doc references
and doc flag tables both clean. One of my own edits introduced a broken
`#configuration` anchor and then a pointer to a table DA_JITTER was not
actually in; lychee caught the first and the second is fixed by adding
the row.

Author: FZ2000

docs/commands/auth.md

@@ -333,29 +333,46 @@ usage: da auth status [-h]
 
 Prints one line of JSON describing how much life the refresh-token chain
 has left, and encodes the same answer in its exit code. It is built for
-cron, launchd and monitoring wrappers: no network, no locks, one small
-object on stdout. Reach for it when you want a machine to
-notice the 90-day ceiling coming; reach for `da diagnose` when you want
-a person to read the whole health picture.
+cron, launchd and monitoring wrappers: one small object on stdout, no
+prose. Reach for it when you want a machine to notice the 90-day ceiling
+coming; reach for `da diagnose` when you want a person to read the whole
+health picture.
+
+It **does** talk to DeviantArt — see below. Poll it on a schedule, not in
+a tight loop.
 
 This command defines no flags of its own beyond `-h`, `--help`.
 
 ### Behaviour
 
 It reads `refresh_token_issued_at` from `state.json` and subtracts the
-elapsed time from 90 days (`REFRESH_TOKEN_TTL_DAYS`). Nothing else is
-consulted — not the config file, not the network, not DeviantArt. A
-green result therefore means "the chain has not aged out", not "the
-token works": for the second question use `da whoami` or `da diagnose`,
-both of which actually exercise the credentials.
-
-The output object always has the same three keys:
+elapsed time from 90 days (`REFRESH_TOKEN_TTL_DAYS`) — and then it
+confirms the answer with DeviantArt, by resolving an access token and
+calling `/placebo`. So a green result means both "the chain has not aged
+out" *and* "DeviantArt still accepts it", which is the answer a
+monitoring wrapper actually wants; the alternative was reporting healthy
+for a grant that had been revoked server-side.
+
+Two consequences worth planning around:
+
+- **It takes the token lock and can rotate your refresh token.** An
+  access token lives an hour and is refreshed 60 s early, so anything
+  polling on roughly an hourly cadence will refresh — and therefore
+  rotate — on almost every call. That is safe (rotation is serialised),
+  but it is not a read-only probe.
+- **It needs the network.** No connectivity is reported as
+  `unreachable`, distinct from `revoked`, so a dropped wifi link does not
+  send you to re-authenticate.
+
+The output object always carries these three keys, plus `error` on the
+two failure states:
 
 | Field | Type | Meaning |
 | --- | --- | --- |
-| `state` | string | `ok`, `warn`, `crit` or `unknown` |
-| `days_remaining` | float or null | Days left in the chain, rounded to one decimal; `null` when `state` is `unknown` |
+| `state` | string | `ok`, `warn`, `crit`, `unknown`, `revoked` or `unreachable` |
+| `days_remaining` | float or null | Days left in the chain, rounded to one decimal; `null` when `state` is `unknown`, `0.0` when `revoked` |
 | `issued_at_iso` | string or null | When the chain was issued, ISO 8601 in UTC; `null` when `state` is `unknown` |
+| `error` | string | Only on `revoked` / `unreachable`: what DeviantArt or the network said |
 
 The thresholds are `REFRESH_TOKEN_WARN_DAYS` (14) and
 `REFRESH_TOKEN_CRIT_DAYS` (3), and the comparisons are strict: more than
@@ -442,22 +459,19 @@ prints the first three lines, warns, and exits 0:
 [warn]  (re-run `da auth --scope "user browse"` to broaden)
 ```
 
-Two rough edges are worth knowing, because both look alarming and
-neither means your installation is broken. `da whoami` calls the API
-directly rather than through the retry-on-401 wrapper the sync commands
-use, so an access token that is locally fresh but has been revoked
-server-side produces an unhandled `urllib.error.HTTPError: HTTP Error
-401: Unauthorized` traceback and exit 1, not a tidy exit 2. Any non-403
-error from `/user/whoami` behaves the same way, as does a network
-failure while refreshing. If you see that traceback, run `da refresh` or
-`da auth`; the corresponding path in `da sync` recovers by itself.
+`da whoami` goes through `authed_http_json`, the same retry-on-401
+wrapper the sync commands use, so an access token that is locally fresh
+but has been revoked server-side is recovered automatically: the wrapper
+forces a refresh and retries once. You see the refresh happen, not an
+error. If the refresh itself fails — a dead refresh token, or no network
+— the command reports it in one line and exits 2.
 
 ### Exit codes
 
 0 when the token is valid, including the `browse`-only degraded case; 2
-when there is no refresh token or `/placebo` does not report success. An
-unhandled HTTP or network error exits 1 with a traceback, as described
-above.
+when there is no refresh token, when `/placebo` does not report success,
+or when an HTTP or network error prevents asking. Every failure path here
+ends in 2 — there is no case that exits 1.
 
 ## `da refresh`
 

docs/commands/config.md

@@ -25,11 +25,9 @@ first:
 
 1. **A command-line flag** on the command being run — `da sync feed
    --concurrency 8`, `da auth --redirect-uri ...`.
-2. **An environment variable.** Only four exist: `DA_CLIENT_ID`,
-   `DA_CLIENT_SECRET`, `DA_DESTINATION`, `DA_REDIRECT_URI`. No other key
-   can be set from the environment — in particular `DA_JITTER` is read
-   by `install_schedule.sh` when it writes the launchd job, never by
-   `da` itself. See
+2. **An environment variable.** Five exist: `DA_CLIENT_ID`,
+   `DA_CLIENT_SECRET`, `DA_DESTINATION`, `DA_REDIRECT_URI` and
+   `DA_JITTER`. No other config key can be set from the environment. See
    [environment variables](../reference/environment-variables.md).
 3. **The macOS Keychain**, for secrets only. The only secret is
    `client_secret`; it is stored under service `da-cli`, account
@@ -85,8 +83,9 @@ A `config.json` that is not valid JSON, or that parses to something
 other than an object (`[]`, `"x"`, `42`), produces a warning on stderr
 and is then ignored — `show` continues with an empty file and still
 prints the environment and Keychain values. A `config.json` that exists
-but cannot be read at all, for example mode `000`, is not handled: the
-`PermissionError` propagates and you get a traceback and exit 1.
+but cannot be read at all, for example mode `000`, raises
+`PermissionError`, which `main()` catches as an `OSError`: one line
+naming the path, and exit 2.
 
 `show` writes nothing and creates nothing, including the directories it
 prints.
@@ -219,14 +218,14 @@ Three things about `set` are worth knowing before you trust it:
   it; the sync and diagnose commands expand it when they use it. This is
   why `config show` prints `~/Pictures/DA` rather than an absolute path.
 
-Two failure modes are less friendly than they should be. If
-`config.json` contains unparsable JSON, `set` treats it as empty and
-overwrites the file with just the key you passed — everything else in it
-is lost. If it contains valid JSON that is not an object, `set` raises
-`TypeError: list indices must be integers or slices, not str` and exits
-1 with a traceback. In both cases the file is worth inspecting by hand
-before you write to it; `config show` will tell you which case you are
-in.
+One failure mode is less friendly than it should be. If `config.json`
+contains unparsable JSON, `set` treats it as empty and overwrites the
+file with just the key you passed — everything else in it is lost, with
+no warning. A file containing valid JSON that is *not* an object is
+handled better: `set` warns
+`expected a JSON object; replacing it` and continues, exit 0. Either way
+the file is worth inspecting by hand first; `config show` will tell you
+which case you are in.
 
 Finally, the value is a command-line argument. It appears in your shell
 history and, for the moment the process runs, in `ps`. For a secret you
@@ -266,10 +265,22 @@ $ da config set client_secret <your-client-secret>
 
 ### Exit codes
 
-0 on success. There is no 2: the ways `set` fails are unhandled
-exceptions, which exit 1 with a traceback — an unwritable config
-directory (`PermissionError`) and the non-object `config.json` case
-described above.
+0 on success, 2 on a rejected value. `set` validates the numeric keys
+before writing, so a bad value is caught rather than written and left to
+break the next sync:
+
+```console
+$ da config set jitter 40%
+[error] jitter must be a number — got '40%'
+$ echo $?
+2
+```
+
+`delay_api`, `delay_image` and `jitter` must parse as numbers;
+`concurrency` and `time_budget` must be whole numbers. Values are stored
+as given and coerced on read, so `3` and `3.0` both work. An unwritable
+config directory raises `PermissionError`, which `main()` catches as an
+`OSError` — also 2.
 
 ## config get
 

docs/commands/inspect.md

@@ -37,11 +37,12 @@ Beyond that:
   or write the destination folder or the SQLite index.
 - They take no lock, so they are safe to run while a `da sync` is in
   progress — the sync lock is held by sync commands only.
-- The only failures they handle are the ones documented in each section
-  below. Any other non-2xx response from DeviantArt propagates as an
-  unhandled `urllib.error.HTTPError`: a Python traceback and exit
-  status `1`, not the usual `2`. A 5xx or a network error is retried
-  twice before that happens (`HTTP_RETRY_DEFAULT = 2` in
+- The only failures they handle *themselves* are the ones documented in
+  each section below. Any other non-2xx response from DeviantArt reaches
+  `main()`'s backstop handler, which prints one line naming the status and
+  exits `2` — the usual code, not a traceback. `-v` shows the traceback,
+  which is written at debug level. A 5xx or a network error is retried
+  twice before any of that (`HTTP_RETRY_DEFAULT = 2` in
   `dacli/constants.py`); 4xx responses are never retried.
 
 ## `da user profile`
@@ -86,9 +87,9 @@ on this command, so those six fields are the whole interface to it.
 Nothing is cached: each run is a fresh API call.
 
 There is no "not found" handling either. A username DeviantArt rejects
-fails the request and surfaces as a traceback with exit `1`; a response
-carrying no `user` object prints the labels with `None` values rather
-than erroring.
+fails the request and surfaces as a one-line error with exit `2`; a
+response carrying no `user` object prints the labels with `None` values
+rather than erroring.
 
 ### Example
 
@@ -169,8 +170,8 @@ is only worth it if you want to reshape it.
 Exits `2`, with `[error] no metadata for deviationid <id>` on stderr,
 when the response contains no metadata entry for the id you asked
 about. That is the empty-result path, not the bad-id path: an id
-DeviantArt rejects outright fails the request instead, with a traceback
-and exit `1`.
+DeviantArt rejects outright fails the request instead — also exit `2`,
+but with the HTTP status in the message rather than the id.
 
 ## `da deviation morelikethis`
 
@@ -250,7 +251,7 @@ that needs more than the default token scope.
 
 Neither number is validated or clamped by the CLI, so whatever limits
 DeviantArt enforces on the endpoint are the ones that apply, and a
-rejected value comes back as a traceback with exit `1`.
+rejected value comes back as a one-line error with exit `2`.
 
 ### Behaviour
 

docs/commands/search.md

@@ -107,13 +107,19 @@ string), `is_mature`, `is_downloadable`, an `author` object
 object (`comments`, `favourites`), and `preview` / `content` / `thumbs`
 image entries whose `src` values are signed CDN URLs.
 
-**Errors.** These commands do not catch HTTP failures. A rejected
-`--limit`, a malformed date or an unauthorised endpoint surfaces as a
-Python traceback ending in a line like
-`urllib.error.HTTPError: HTTP Error 400: Bad Request`, and the process
-exits `1` — not the `2` that the rest of the CLI uses for "could not do
-the job" (see [exit codes](../reference/exit-codes.md)). An empty result
-set is not an error: nothing is printed and the exit code is `0`.
+**Errors.** These commands do not handle HTTP failures themselves; the
+failure reaches `main()`'s backstop handler. A rejected `--limit`, a
+malformed date or an unauthorised endpoint prints one line —
+
+```text
+[error] DeviantArt refused the request (HTTP 400 Bad Request).
+```
+
+— and exits `2`, the same code the rest of the CLI uses for "could not do
+the job" (see [exit codes](../reference/exit-codes.md)). The traceback is
+written at debug level, so `-v` shows it and the default run does not. An
+empty result set is not an error: nothing is printed and the exit code is
+`0`.
 
 **Rate limiting.** Each invocation makes exactly one API request and
 sleeps for nothing, so none of the `--delay-api` / `--jitter` throttling
@@ -403,9 +409,10 @@ not hit a `/browse/` endpoint — it POSTs to `/user/whois`, because that
 endpoint rejects GET with HTTP 400 — and the only one with no `--limit`
 and no `--mature`. The request hardcodes `mature_content=true`, so a
 `--mature` flag would have nothing to do.
-Being a `/user/` endpoint, it needs a token authorised for it; a token
-that is not gets HTTP 401 back, which surfaces as a traceback and exit
-`1` rather than a message.
+Being a `/user/` endpoint, it needs a token authorised for it. A token
+that is not gets HTTP 401 back, which surfaces as
+`[error] DeviantArt rejected the credentials (HTTP 401 Unauthorized)` and
+exit `2`.
 
 Each record DA returns prints as one line: `@` and the username as DA
 spells it, the user's UUID in parentheses, and `type=` followed by the
@@ -444,8 +451,8 @@ however many picks DA made that day — seventeen on
 the day this page was written — and only the human-readable form.
 
 A malformed date is not validated locally. A day-first date such as
-`15-01-2026` is sent to DA as-is, comes back 400, and ends in a
-traceback with exit `1`.
+`15-01-2026` is sent to DA as-is, comes back 400, and ends in a one-line
+error with exit `2`.
 
 ```console
 $ da daily 2026-01-15 | head -5

docs/commands/sync.md

@@ -198,10 +198,13 @@ corrupt index, or a 401 that survives a forced token refresh. `0` — with
 a `skipping:` message — when another sync already holds the lock.
 
 One deviation from the norm: an unexpected HTTP status from the feed
-endpoint (anything that is not 429 or a retried 5xx) is **not** caught.
-It escapes as a Python traceback and the process exits `1`, not `2`.
-`sync artist` handles the same situation differently, which is worth
-knowing before you write a wrapper script around either.
+endpoint (anything that is not 429 or a retried 5xx) is not handled
+inside the walk. It reaches `main()`'s backstop handler, which prints a
+one-line explanation and exits `2` — the same code the rest of the CLI
+uses for "could not do the job". No traceback, unless you pass `-v`.
+`sync artist` handles the same situation inside the walk instead,
+recording a stop reason; the difference matters if you parse the summary
+line, not if you branch on the exit code.
 
 ## da sync artist
 
@@ -255,21 +258,25 @@ Two details make the early stop safe rather than merely fast:
 - Known ids are filtered out before the metadata batch, so a page that
   is 23/24 duplicates costs one metadata call for one deviation.
 
-What the early stop does **not** do is compensate for a walk that
-stopped part-way down. There is no per-artist "how far did I get" marker
-in `state.json`; the index is the only memory, and it says nothing about
-order. So if a run is truncated by its time budget at offset 96, the
-newest four pages are indexed and everything older is not — and the next
-plain run reads page 0, finds it entirely known, reports `caught up` and
-stops without ever requesting offset 96 again. Resuming is manual, which
-is why the summary is followed by a
-`resume: da sync artist <name> --offset <n>` line whenever the walk
-stopped for a non-terminal reason.
-
-The same offset is recorded in `state.json` as `last_sync.last_offset`
-(only for non-terminal stops, so `gallery complete` and `caught up` do
-not record one). Re-run with that `--offset`, or with `--full`, or the
-rest of the gallery stays unsynced.
+A walk that stops part-way down **is** resumed automatically. The
+per-artist position is recorded in `state.json` under
+`galleries.<artist>`, so if a run is truncated by its time budget at
+offset 96, the next plain run starts there rather than at page 0:
+
+```text
+resuming alice at offset 96 (previous walk did not finish)
+```
+
+That marker is also what stops the early "everything on this page is
+known" exit from stranding the rest of the gallery — the early stop is
+gated on the artist being recorded as complete, so a truncated walk
+keeps going instead of reporting `caught up` at page 0.
+
+`--offset` still overrides it when you pass one explicitly, and `--full`
+still ignores it and walks from the top. The summary's
+`resume: da sync artist <name> --offset <n>` line is a convenience for
+running the rest immediately; you do not need it for the next scheduled
+run to make progress.
 
 **`--full`** disables the early stop only. It walks every page to the
 end of the gallery but still skips anything the index already knows, so
@@ -408,8 +415,12 @@ daily job; `sync feed` is.
 | `--concurrency CONCURRENCY` | int | config `concurrency`, else `4` | Passed to each artist walk, clamped to 1–16. |
 | `--dry-run` | flag | off | Passed to each artist walk. Nothing is written and the index is untouched, but every gallery is still paged and metadata is still fetched. |
 
-There is no `--limit` and no `--offset`. Each artist is walked with
-`--limit 24` and `--offset 0`, always.
+There is no `--limit` and no `--offset`. Each artist is walked at the
+gallery page cap, and — deliberately — with no offset supplied, so each
+one resumes its own unfinished walk from the position recorded in
+`state.json`. Passing `0` here would pin every artist to page 0 and
+defeat that, which is precisely the case a backfill across many artists
+needs most.
 
 ### Behaviour
 
@@ -448,10 +459,10 @@ for even one page, so the rest are skipped with a warning reading
 
 Skipped artists are not failures. Re-running picks up where it stopped in
 the useful sense: the artists already walked are all-known, so each costs
-one API call before the walk moves on — but a *truncated* artist, one cut
-off mid-gallery, is not resumed, for exactly the reason described under
-[`sync artist`](#behaviour-1). Its remaining pages need
-`da sync artist <name> --offset N` or `--full`.
+one API call before the walk moves on, and a *truncated* artist — one cut
+off mid-gallery — picks up where it left off, for the reason described
+under [`sync artist`](#behaviour-1). Nothing needs doing by hand; a
+backfill across many artists converges over successive scheduled runs.
 
 **Failure handling.** Each artist runs inside a `try`. An artist that
 exits or crashes is logged, counted as failed, and the run moves on to