Skip to content

docs: complete Clay's task coverage and add a Gifts section - #277

Open
sigilante wants to merge 1 commit into
urbit:masterfrom
sigilante:docs/pr6b-clay-cards
Open

docs: complete Clay's task coverage and add a Gifts section#277
sigilante wants to merge 1 commit into
urbit:masterfrom
sigilante:docs/pr6b-clay-cards

Conversation

@sigilante

Copy link
Copy Markdown
Contributor

Twelfth PR from the audit against urbit/urbit@08026c84b2. +$ task:clay (lull.hoon:2442-2481) has 30 cards; clay/tasks.md documented 16. Coverage is now 30/30, verified by script.

Companion PRs: #266, #267, #269, #270, #271, #272, #273, #274, #275, #276.

Ten tasks added, in the existing topic sections

Section Card Shape
Write and Modify %into [%into des=desk all=? fis=mode] — external edit, for Unix sync
%park [%park des=desk yok=yoki ran=rang] — synchronous commit
%pork [%pork ~] — resume interrupted commit
%prep [%prep lat=(map lobe page)] — prime the object store
Apps and updates %esse [%esse des=desk ese=?] — mark desk essential
%zeal [%zeal lit=(list [=desk =zest])] — batch form of %zest
%stir [%stir arg=*] — debug; not stable interface
Merge Desks %fuse [%fuse des=desk bas=beak con=(list [beak germ])]
%drop [%drop des=desk] — cancel pending merge
Foreign Ships %werp [%werp who=ship wer=ship rif=riff-any]

%fuse is the one most likely to be reached from userspace — it backs the |fuse generator — so its entry carries the real usage examples and the %track semantics from the generator's own help text (gen/hood/clay/fuse/help.txt) rather than a reconstruction.

I also called out the %warp / %werp distinction explicitly in the Foreign Ships intro. They differ by one letter: %warp is how we request a file from a named ship; %werp is the inbound form carrying the requesting ship, passed to Clay by Ames. Easy to reach for the wrong one.

Vane lifecycle tasks

Added a short section for the four $vane-task cards (%init, %trim, %vega, %plea). These are shared boilerplate rather than Clay-specific — but they are part of Clay's union, and omitting them is why the file previously looked complete while missing a third of its cards.

There's no shared vane-task page to link to instead; Gall's API page documents its own inline, so this follows that precedent.

Gifts section

All 13 cards of $gift:clay. Previously the gifts appeared only incidentally under whichever task produced them, and %croz, %cruz and %wris were never named at all. The quoted union was checked line-by-line against lull.hoon:2427-2441 by script.

Verification

  • Task coverage checked programmatically: 30 in source, 30 covered, none missing.
  • Gift union block diffed against lull.hoon — exact match.
  • All anchors resolve.
  • Test-merged against the eleven open companion PRs — all clean. Confirmed this coexists with docs: remove Clay's deleted Ford cache and correct the Arvo state #270, which removes the Ford cache from clay/data-types.md: the merged tree has zero fad=flow and three %fuse references.

🤖 Generated with Claude Code

Against urbit/docs.urbit.org@08026c84b2. `+$ task:clay` (lull.hoon:2442-2481) has 30 cards;
clay/tasks.md documented 16. Coverage is now 30/30, verified by script.

Ten tasks added, placed in the existing topic sections:

  Write and Modify
    %into  [%into des=desk all=? fis=mode]      external edit, for Unix sync
    %park  [%park des=desk yok=yoki ran=rang]   synchronous commit
    %pork  [%pork ~]                            resume interrupted commit
    %prep  [%prep lat=(map lobe page)]          prime the object store
  Apps and updates
    %esse  [%esse des=desk ese=?]               mark desk essential
    %zeal  [%zeal lit=(list [=desk =zest])]     batch form of %zest
    %stir  [%stir arg=*]                        debug; not stable interface
  Merge Desks
    %fuse  [%fuse des=desk bas=beak con=...]    merge many sources
    %drop  [%drop des=desk]                     cancel pending merge
  Foreign Ships
    %werp  [%werp who=ship wer=ship rif=...]    inbound remote request

%fuse is the one most likely to be reached from userspace -- it backs the
|fuse generator -- so its entry carries the real usage examples and the
%track semantics from the generator's own help text
(gen/hood/clay/fuse/help.txt), rather than a reconstruction.

Called out the %warp / %werp distinction explicitly in the Foreign Ships
intro: %warp is how we request a file from a named ship; %werp is the inbound
form carrying the requesting ship, passed to Clay by Ames. The two differ by
one letter and it would be easy to reach for the wrong one.

Added a "Vane lifecycle tasks" section for the four $vane-task cards
(%init, %trim, %vega, %plea). These are shared boilerplate rather than
Clay-specific, but they ARE part of Clay's union, and leaving them out is why
the file previously looked complete while missing a third of its cards. There
is no shared vane-task page in the docs to link to instead; Gall's API page
documents its own inline, and this follows that precedent.

Added a Gifts section covering all 13 cards of `$gift:clay`. Previously the
gifts appeared only incidentally under whichever task produced them, and
%croz, %cruz and %wris were never named at all. The quoted union was checked
line-by-line against lull.hoon:2427-2441 by script.

All anchors verified to resolve.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant