Skip to content

docs: add missing vane Gifts sections and undocumented tasks - #278

Open
sigilante wants to merge 1 commit into
urbit:masterfrom
sigilante:docs/pr6d-vane-gifts
Open

docs: add missing vane Gifts sections and undocumented tasks#278
sigilante wants to merge 1 commit into
urbit:masterfrom
sigilante:docs/pr6d-vane-gifts

Conversation

@sigilante

Copy link
Copy Markdown
Contributor

Thirteenth PR from the audit against urbit/urbit@08026c84b2. Four vanes documented their tasks but never their gifts — the cards existed only as passing mentions under whichever task produced them, if at all.

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

Gifts sections added

Vane Cards Source
behn 4 — %doze %wake %meta %heck lull.hoon:2404
dill 8 — %blit %logo %meld %pack %trim %logs %meme %quac :2861
eyre 6 — %boon/%done %set-config %sessions %response %bound %grow :2978
iris 3 — %request %cancel-request %http-response :4131

Coverage verified by script: every gift in each source union now appears in its doc.

Two naming collisions are called out explicitly, since both are easy to misread:

  • Iris has %request and %cancel-request as both a task and a gift. The task is how a vane asks Iris to fetch something; the gift is how Iris asks Unix to do it.
  • Dill has %meld, %pack, %trim and %quac in both unions, pointing in opposite directions.

Tasks added

Vane Task Note
dill %mass run a memory report — the mechanism behind |mass
dill %quac the runtime's reply carrying that report
dill %knob documented as deprecated
eyre %eauth-host set the EAuth base URL
eyre %spew set verbosity toggle
khan %done external control socket closed

%knob is marked :: deprecated removeme in lull.hoon. The entry exists to stop anyone adopting it, not to encourage use — an undocumented deprecated card is worse than a documented one, since nothing signals that it's on its way out.

%eauth-host is a nice illustration of the gap: the EAuth guide already described this task in detail, while tasks.md — the page that purports to enumerate Eyre's interface — never listed it. Now cross-referenced.

Checked and deliberately not changed

  • khan already had a complete Gifts section (%arow, %avow).
  • eyre's %reject-origin and %set-response did not appear in a first partial extraction of the task union, which briefly looked like the docs had phantom cards. They exist at lull.hoon:3063 and :3069 — the docs were right and my extraction range was too narrow. No phantom cards in any of these files.

All anchors verified to resolve. Test-merged against the twelve open companion PRs — all clean, including confirmation that dill/tasks.md takes #269's %meld payload change and this PR's Gifts section together.

🤖 Generated with Claude Code

Against urbit/docs.urbit.org@08026c84b2. Four vanes documented their tasks but never their
gifts; the cards existed only as passing mentions under whichever task produced
them, if at all. Coverage verified by script against lull.hoon.

Gifts sections added:
  behn  4 cards   %doze %wake %meta %heck                       lull.hoon:2404
  dill  8 cards   %blit %logo %meld %pack %trim %logs %meme %quac   :2861
  eyre  6 cards   %boon/%done %set-config %sessions %response
                  %bound %grow                                     :2978
  iris  3 cards   %request %cancel-request %http-response          :4131

Two naming collisions are called out explicitly, since both would be easy to
misread:
  - Iris has %request and %cancel-request as BOTH a task and a gift. The task
    is how a vane asks Iris to fetch something; the gift is how Iris asks Unix
    to do it.
  - Dill has %meld, %pack, %trim and %quac in both unions, in opposite
    directions.

Tasks added:
  dill  %mass   run a memory report; the mechanism behind |mass
  dill  %quac   the runtime's reply carrying that report
  dill  %knob   documented AS DEPRECATED -- it is marked
                `:: deprecated removeme` in lull.hoon, so the entry exists to
                stop anyone adopting it, not to encourage use
  eyre  %eauth-host  set the EAuth base URL; eyre appends /~/eauth internally.
                     Cross-referenced to the existing EAuth guide, which
                     already described this task while tasks.md did not list it
  eyre  %spew   set verbosity toggle
  khan  %done   external control socket closed

Checked and NOT changed: khan already had a complete Gifts section (%arow,
%avow), and eyre's %reject-origin and %set-response -- which I could not find
in a first partial extraction -- do exist at lull.hoon:3063 and :3069. Neither
file has a phantom card.

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