e8fd1a37d1959a9e73943e946088d1b86d2b1bb4
braney
  Fri Sep 4 11:17:35 2026 -0700
docent: correct the claim that expect: is the only verb that can fail a run

An audit of tests/README.txt against the code found the claim wrong in both
READMEs. docent.js turns any step's throw into "step N (verb) failed" and exit
1, so mouseover:, loadSession:, drag:, convert: and go: all fail a run when they
cannot do what they were told. Verified by running a script with no expect: step
in it at all: it exited 1 from loadSession:.

The conclusion drawn from the claim still holds and is kept: expect: is the only
verb that CHECKS anything, and track: does not even check its own input, since a
name no assembly has is sent as name=mode and the run exits 0 (also verified).

Also documents why make derive strips one line of trackDb provenance: the
listing is cached for a day, a cold fetch prints a line a warm run does not, and
the first run of any day otherwise fails against a baseline captured warm.

refs #37892

diff --git src/hg/utils/docent/README.md src/hg/utils/docent/README.md
index 1da70cf1c46..87195454082 100644
--- src/hg/utils/docent/README.md
+++ src/hg/utils/docent/README.md
@@ -238,50 +238,57 @@
 - **A session taken on a lifted view is short-lived.** quickLift builds its hub under
   `trash/`, and the file records it by that path (`assumesHub 192070=../trash/quickLift/...`).
   It reloads correctly while the hub is there; it stops working when trash is cleaned. The
   GenArk hub beside it is a stable `/gbdb` path and does not expire. So a lifted session is
   good for showing a colleague what you are looking at this week, not for a paper.
 - **`make hires` writes to `sessions.hires/`.** A print run's cart carries `pix=2550` and
   `textSize=24`, which is not a state anyone wants handed to them, so it is kept out of the
   way of the screen run's files rather than overwriting them.
 
 ## Expectations
 
 Every other verb renders happily whatever it is handed. A superTrack that came up whole
 makes an image 7,581 px tall, a subtrack that never hid stays in the figure, a pinned
 tooltip grabs the neighbouring item, an Apache 414 arrives as a perfectly valid page saying
 *Request-URI Too Long*. All of those have shipped at least once, all were caught by eye, and
-all of them are mechanically checkable. `expect:` is the only verb that stops a run:
+all of them are mechanically checkable. `expect:` is the only verb that looks at any of it:
 
 ```yaml
   - track: {varsInPubs: hideKids, pubtator: pack}
   - expect: {rows: [ruler, mane, pubtator], exact: true, height: 2000, noText: "Too Long"}
   - mouseover: {track: quickLiftChain, item: "4.3.157828209.157828210", pin: true}
   - expect: {tip: "mismatch A->C"}
 ```
 
 A failure prints every check that failed **and the rows that were actually drawn**, then
 exits non-zero at that step, so `make` fails instead of writing a wrong figure over a right
 one and the stills that would have followed are never taken:
 
 ```
 step 5 (expect) failed: rows not drawn: clinvarMain; image is 69px, wanted <50
   drawn: ruler, mane
 ```
 
 Notes:
 
+- **Other verbs can still fail a run, they just do not check anything.** A verb throws
+  when it cannot do what it was told: `mouseover:` cannot find the item, `loadSession:`
+  cannot find the file, `drag:` gets endpoints it cannot read, `convert:` cannot find the
+  assembly in the dropdown. Any step's throw becomes `step N (verb) failed` and exit 1.
+  What none of them does is judge the result, and `track:` does not even judge its own
+  input -- a name no assembly has is sent as `name=mode` and the run exits 0. That is why
+  a script with no `expect:` in it is a tour and not a test.
 - **Row names are matched by suffix**, the way `mouseover:` resolves a track, so `mane`
   is satisfied by a lifted view's `hub_192070_mane` and a script does not have to know the
   per-run hub number.
 - **`rows:` is a set test unless you say `ordered: true`.** `exact: true` only adds "and
   nothing else", so neither of them can fail because the rows came out in the wrong order.
   When the order is the thing under test — a quickLift target that should read in source
   order, a superTrack whose members should follow their priorities — add `ordered: true`
   and the named rows have to appear top to bottom in the order given. Rows that were not
   drawn at all are reported once, by `rows:`, and skipped by the order check rather than
   failing twice. A failure names the first pair that is inverted:
 
       step 12 (expect) failed: rows out of order: mane should be drawn above gtexGeneV8
         drawn: ruler, hub_274823_quickLiftChain, hub_274823_gtexGeneV8, hub_274823_mane
 - **`height:` is in still pixels**, which is the CSS height times the device pixel ratio —
   the number someone means by "7,581 px tall". A print run makes it k times bigger, so a