docs: fix user-manual commands that fail or mislead as documented

[sigilante]

Third of three PRs from an audit against urbit/urbit@08026c84b2. This batch is dojo commands a reader would actually run. Every command below was run on a fake ship booted from urbit-408k-rc1.pill ([%zuse 408]), and every sample output is a real capture rather than a reconstruction.

Companion PRs: mechanical corrections, and Hoon stdlib signatures.

+vats — the documented argument surface did not exist

Source is (list desk) positional with =filt and =verb named (gen/vats.hoon:6-20). The dojo reports its own interface while rejecting the documented one:

> +vats, =show-blocking |
dojo: keywords allowed
[filt=@tas verb=?(%.y %.n)]
-find.show-blocking
dojo: generator failure

> +vats %suspended
desk does not yet exist: %suspended

That second one matters: the filter is a named argument, so a bare +vats %suspended is parsed as a desk of that name. Removed the four phantom =show-* arguments, corrected %nonexistent → %exists-not, and added the missing %exists.

The field list was also wrong in both directions. Default output is terse, not verbose, and prints three fields that were undocumented (%cz hash ends in, essential desk, /desk/bill) while omitting four that were documented (updates, base hash, force on/off, publishing ship). Split into terse and =verb & sections. app status has three values, not two — running, suspended, and suspended until next update (sur/hood.hoon:203). All examples replaced with real captures.

|bump, =force & fails

gen/hood/bump.hoon takes no arguments at all; the dojo reports an empty keyword set (%~) then -find.force. Both occurrences in updates.md corrected to plain |bump, which already does the suspend-and-upgrade. dojo-tools.md was already right, so the two pages had been contradicting each other.

updates: tracking is never emitted

The field is ?~(sink 'local' 'remote') (sur/hood.hoon:243), so the surrounding prose told readers to act on a string they can never see. Both sample outputs replaced with real captures — one local, one remote — and the commands changed to =verb &, since the terse default omits updates entirely.

Comet |ota

A bare |ota matches neither branch of the arg mold ?([%disable ~] [her=@p sud=?(~ [@tas ~])]) and fails with bad-argument. Corrected to |ota (sein:title our now our), matching what updates.md already said.

|reload / |breload are gone

Both fail with %generator-build-fail; no /gen/hood/reload exists. The |breload entry is deleted, and the |reload example — which existed only to demonstrate the | hood-command syntax — now uses |mass, verified working.

|new-desk, =from does not clone a desk

It only selects where a fixed five-file template is read from (gen/hood/clay/new-desk.hoon:30-60). Verified on a fresh ship:

%base                              ->  {app sur gen lib mar ted desk sys}
|new-desk %testdesk, =from %base   ->  {mar sys}

with mar holding exactly {hoon txt kelvin noun}. Dropped the desk.bill warning, which was advice about a copy that never happens — the created desk has no desk.bill at all.

Smaller

• |nuke — added the undocumented =hard flag, which skips the confirmation prompt on an irreversible state wipe.
• |suspend — takes (list desk), not a single desk; multiple desks suspend together.
• |essential-desk — new entry. Documented nowhere in the user manual despite essential desk appearing in every +vats print-out. Verified end to end: |essential-desk %testdesk & flips the field from no to yes.

🤖 Generated with Claude Code