docs: document +dbug =depth, |eyre/clean, and missing test-library arms

content/build-on-urbit/app-school/3-imports-and-aliases.md

@@ -208,5 +208,5 @@ The key takeaways are:
 
 * Run through the [example](3-imports-and-aliases.md#example) yourself on a fake ship if you've not done so already.
 * Have a read through the [Ford rune documentation](../../hoon/rune/fas.md) for details about importing libraries, structures and other things.
-* Try the `+dbug` generator out on some other agents, like `:settings +dbug`, `:contacts +dbug`, etc, and try some of its options [described above](3-imports-and-aliases.md#dbug).
+* Try the `+dbug` generator out on some other agents, like `:azimuth +dbug`, `:spider +dbug`, `:hood +dbug`, etc, and try some of its options [described above](3-imports-and-aliases.md#dbug).
 * Have a quick look over the source of the `/lib/default-agent.hoon` library, located at `/lib/default-agent.hoon` in the `%base` desk. We've not yet covered what the different arms do but it's still useful to get a general idea, and you'll likely want to refer back to it later.

content/build-on-urbit/userspace/examples/dbug.md

@@ -89,9 +89,12 @@ There are four actions exposed by the wrapper via the `+dbug` generator:
         ::  inline arguments
         args=?(~ [what=?(%bowl %state) ~] [=poke ~])
         ::  named arguments
-        ~
+        depth=@ud
     ==
 :-  %dbug
+=;  =poke
+  ?:  =(0 depth)  poke
+  [%skip depth poke]
 ?-  args
   ~          [%state '']
   [@ ~]      ?-(what.args %bowl [%bowl ~], %state [%state ''])
@@ -111,7 +114,8 @@ There are four actions exposed by the wrapper via the `+dbug` generator:
 ::
 |%
 +$  poke
-  $%  [%bowl ~]
+  $%  [%skip depth=@ud =poke]
+      [%bowl ~]
       [%state grab=cord]
       [%incoming =about]
       [%outgoing =about]
@@ -141,6 +145,12 @@ There are four actions exposed by the wrapper via the `+dbug` generator:
       [cards this]
     =/  dbug
       !<(poke vase)
+    =?  dbug  ?=([%skip %0 *] dbug)  poke.dbug
+    ?:  ?=(%skip -.dbug)
+      =^  cards  agent
+        %+  on-poke:ag  %dbug
+        !>(`poke`dbug(depth (dec depth.dbug)))
+      [cards this]
     =;  =tang
       ((%*(. slog pri 1) tang) [~ this])
     ?-  -.dbug
@@ -289,6 +299,12 @@ By applying this door builder using `%-` censig, the `+on-poke` and `+on-peek` a
       [cards this]
     =/  dbug
       !<(poke vase)
+    =?  dbug  ?=([%skip %0 *] dbug)  poke.dbug
+    ?:  ?=(%skip -.dbug)
+      =^  cards  agent
+        %+  on-poke:ag  %dbug
+        !>(`poke`dbug(depth (dec depth.dbug)))
+      [cards this]
     =;  =tang
       ((%*(. slog pri 1) tang) [~ this])
     ?-  -.dbug

content/build-on-urbit/userspace/unit-tests.md

@@ -36,11 +36,14 @@ The `%base` desk includes a `-test` thread which can run unit tests you've writt
 
 Any arms that don't begin with `test-` will be ignored. Each `+test-*` arm must produce a `$tang` (a `(list tank)`). If the `$tang` is empty (`~`), it indicates success. If the `$tang` is non-empty, it indicates failure, and the contents of the `$tang` is the error message.
 
-To make test-writing easier, the `%base` desk includes the `/lib/test.hoon` library which you can import into your test file. The library contains four functions which all produce `$tang`s:
+To make test-writing easier, the `%base` desk includes the `/lib/test.hoon` library which you can import into your test file. The library contains the following functions, which all produce `$tang`s:
 
 - `+expect-eq` - test whether an expression produces the expected value. This function takes `[expected=vase actual=vase]`, comparing `.expected` to `.actual`.
 - `+expect` - test whether an expression produces `%.y`. This function takes a `$vase` containing the result to check.
 - `+expect-fail` - tests whether the given `$trap` crashes, failing if it succeeds.
+- `+expect-success` - the converse of `+expect-fail`: tests whether the given `$trap` succeeds, failing if it crashes.
+- `+expect-fail-message` - takes `[msg=@t a=(trap)]`. Like `+expect-fail`, but also requires that `.msg` appear in the resulting error message, so you can assert on *why* something failed rather than just that it did.
+- `+run-chain` - takes an `$a-test-chain` and runs a sequence of tests, stopping at the first failure. Note that arms in the chain should not begin with `test-`, so that `-test %/... ~` does not also run them individually.
 - `+category` - this is a utility that prepends an error message to a failed test (non-null `$tang`), passing through an empty `$tang` (successful test) unchanged.
 
 The most commonly used function is `+expect-eq`, which is used like:

content/user-manual/os/dojo-tools.md

@@ -1185,16 +1185,61 @@ Query the state or bowl of a running agent.
 
 #### Arguments
 
-See the [dbug section of App School lesson 3](../../build-on-urbit/app-school/3-imports-and-aliases.md#dbug) for details of usage.
+```
+?(~ [?(%bowl %state) ~] [poke ~]), =depth @ud
+```
+
+See the [dbug section of App School lesson 3](../../build-on-urbit/app-school/3-imports-and-aliases.md#dbug) for details of the positional argument.
+
+The named `=depth` argument addresses an agent running *underneath* a wrapper
+agent. With a non-zero depth the poke is wrapped as `[%skip depth poke]`, and
+each layer of `/lib/dbug` decrements it before passing the poke down. It is only
+meaningful for a nested agent; sending it to an ordinary agent produces
+`unexpected poke to %agent with mark %dbug`.
 
 #### Example
 
 This is only used with an `:agent`, not by itself.
 
 ```
-> :graph-store +dbug [%state '(~(got by graphs) ~zod %dm-inbox)']
+> :azimuth +dbug [%state 'whos']
 >=
->   [p={} q=[~ %graph-validator-dm]]
+>   {}
+```
+
+---
+
+### `|eyre/clean` {#eyreclean}
+
+Delete stale incoming HTTP subscriptions.
+
+Eyre channel subscriptions can be left behind when a channel goes away without
+its subscriptions being torn down. This generator finds those and can remove
+them.
+
+**It runs in dry mode by default**, only reporting how many stale subscriptions
+it found. Pass `=dry |` to actually delete them.
+
+#### Arguments
+
+```
+=dry ?, =veb ?(%1 %2 ~)
+```
+
+- `=dry` - defaults to `&` (dry run). Pass `|` to delete.
+- `=veb` - verbosity. `%1` prints each stale subscription; `%2` prints each
+  subscription that still exists.
+
+#### Examples
+
+```
+> |eyre/clean
+>=
+"#0 stale incoming subscriptions"
+```
+
+```
+> |eyre/clean, =dry |
 ```
 
 ---
@@ -1822,7 +1867,7 @@ These are more advanced desk and filesystem tools.
 
 Enable automatic commits for a mounted desk
 
-Auto-commits can be disabled with [`|clay/cancel-autocommit`](#claycancelautocommit).
+Auto-commits can be disabled with [`|clay/cancel-autocommit`](#claycancel-autocommit).
 
 #### Arguments
 
@@ -1886,7 +1931,7 @@ The `$desk` is mandatory, the `.auto` is optional.
 
 If `.auto` is `%.y`, auto-commits will be enabled, meaning changes to that desk on the host side will automatically be committed as soon as they happen.
 
-Auto-commits can be disabled with [`|clay/cancel-autocommit`](#claycancelautocommit).
+Auto-commits can be disabled with [`|clay/cancel-autocommit`](#claycancel-autocommit).
 
 #### Example