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

[sigilante]

Eighth PR from the audit against urbit/urbit@08026c84b2. Developer tooling. Everything below was run on a fake ship (urbit-408k-rc1.pill).

Companion PRs: #266, #267, #268, #269, #270, #271, #272.

+dbug gained =depth

The generator has a named depth=@ud argument (gen/dbug.hoon) which wraps the poke as [%skip depth poke]. /lib/dbug's +$ poke gained a matching [%skip depth=@ud =poke] case, and its +on-poke unwraps one layer per hop, decrementing as it passes the poke down. This lets you address an agent running underneath a wrapper agent.

examples/dbug.md is a line-by-line walkthrough of both files, so its quoted source was stale in three places: the generator's named-argument slot, the +$ poke union, and +on-poke.

Worth flagging for review: that file quotes +on-poke twice — once in the full library listing and once in its own <details> section. My first patch attempt asserted a single occurrence and aborted before writing, which is how I caught it; both copies are now updated. Each refreshed block was then checked against upstream by script.

Documented the caveat that =depth only makes sense for a nested agent — verified that sending it to an ordinary one fails:

> :azimuth +dbug, =depth 1
"unexpected poke to %azimuth with mark %dbug"

|eyre/clean — new entry

Added 2025-06, undocumented. Deletes stale incoming HTTP channel subscriptions. dry=? bunts to %.y, so it runs as a dry run by default and only reports a count; =dry | actually deletes. =veb takes %1 (print each stale subscription) or %2 (print each surviving one).

> |eyre/clean
"#0 stale incoming subscriptions"

+dbug examples referenced agents that don't ship

:graph-store +dbug fails with gall: not running %graph-store yet — that agent lives only in frozen pkg/landscape. Same for the :settings / :contacts suggestions in App School 3. Replaced with agents present on a bare ship (checked against %base's desk.bill: azimuth, spider, hood), using real captured output:

> :azimuth +dbug [%state 'whos']
{}

/lib/test.hoon exports seven arms, not four

unit-tests.md described "four functions". Added the three missing ones:

• +expect-success — the converse of +expect-fail
• +expect-fail-message — asserts on the error text, not merely that a crash occurred
• +run-chain — runs a sequence, stopping at first failure; includes the source's note that chained arms must not begin with test-, or -test will also run them individually

Incidental

Fixed two pre-existing broken anchor links to #claycancelautocommit; the heading anchor is #claycancel-autocommit.

The remaining broken #vat link in this file is deliberately left alone — it is already fixed in #266, and fixing it twice would create a conflict. Verified in a combined test-merge that the result has zero broken #vat and zero broken autocommit links.

Test-merged against the seven open companion PRs — all clean, including the three that now touch dojo-tools.md.

🤖 Generated with Claude Code