Skip to content

docs: mechanical corrections and kelvin refresh - #266

Open
sigilante wants to merge 2 commits into
urbit:masterfrom
sigilante:docs/pr1-mechanical
Open

docs: mechanical corrections and kelvin refresh#266
sigilante wants to merge 2 commits into
urbit:masterfrom
sigilante:docs/pr1-mechanical

Conversation

@sigilante

Copy link
Copy Markdown
Contributor

First of three PRs from an audit of the docs against urbit/urbit@08026c84b2 and urbit/vere@92847eb3fd. This one is deliberately the low-risk batch: mechanical corrections that need no domain review. The other two cover Hoon stdlib signatures and user-manual commands.

Claims were verified against upstream source, and where possible reproduced on a fake ship booted from urbit-408k-rc1.pill ([%zuse 408]).

math.md: 40 corrupted $$ inside code fences

A stray doubling made 34 $( recursion calls and 4 $: bunts invalid Hoon, so every affected listing fails to parse when copied. Confirmed in the dojo:

> =/  i  1  |-  ?:  (gth i 3)  i  $(i +(i))
4

while the $$( form as printed is rejected by the parser outright.

Scope was checked carefully, because a naive replace would do damage:

  • the 16 out-of-fence $$...$$ in math.md are LaTeX and are preserved
  • stdlib/3b.md, hoon-school/S-math.md and others contain only LaTeX $$ — untouched
  • stdlib/4o.md and core-academy/ca02.md contain :: $$, recursion, which is verbatim source ($$ is the %bcbc rune) — untouched

math.md: phantom +exp section

lib/math.hoon:148 is ::++ exp exp:^rs — commented out. The doc dropped the :: and presented it as a live pass-through arm, which also created a duplicate {#exp} anchor colliding with the real +exp. Removed. (The same line is commented out four times in source, once per float core; only the rs one had leaked in.)

Vane count

"nine vanes" → ten, in four files. Lick was missing from the list in arvo/README.md entirely.

Source-block typos

Each checked against sys/hoon.hoon:

File Arm Fix
4j.md +hif:ab bossbass
2l.md +molt }]
4b.md +rt:at `$tape``tape`
4m.md +stab `$path``path`
4i.md +mes {a/@ b/@}[a=@ b=@]
1c.md +bloq $bloq (it is +$ in source); anchor left intact

Note +til legitimately uses +boss, so the +hif fix is deliberately not a global replace. The $tape/$path cases look like a $-prefixing pass that leaked into code blocks.

Runtime and dojo

  • vere.md: --scry-info--scry-into. The long option never existed under the documented name (main.c:303).
  • dojo-tools.md: +vat does not exist — verified %generator-build-fail. Dead cross-reference replaced with +vats %base.

Kelvins → 408

Ten illustrative or instructional sites updated. Two of them are commands a reader actually runs (echo "[%zuse 417]" > sys.kelvin in flap.md, same in lick/guide.md); a desk declaring an unsupported kelvin is rejected, so those were not merely cosmetic. Verified |new-desk writes [%zuse 408].

Deliberately not changed — these state when a feature was introduced and remain true: remote scry at 413 and path-format version at 411 (remote-scry.md), %kroc no-op at 410 (hood.md), noun channels at 413 (noun-channels.md), and Core Academy's explicit "snapshot at Zuse 412k".

🤖 Generated with Claude Code

sigilante and others added 2 commits August 4, 2026 11:44
…/ vere@92847eb3fd

Purely mechanical fixes; no semantic rewrites. Each verified against
upstream source, and where possible reproduced on a fake ship (v4.6 pill).

math.md: repair 40 corrupted `$$` -> `$` inside hoon code fences.
  A stray doubling made 34 `$(` recursion calls and 4 `$:` bunts invalid
  Hoon, so every listing failed to parse when copied. Confirmed in dojo:
  `$(i +(i))` evaluates, `$$(i +(i))` is rejected by the parser.
  The 16 out-of-fence `$$...$$` are LaTeX and are deliberately preserved,
  as are the genuine `::  $$, recursion` comments in 4o.md and ca02.md
  (`$$` is the %bcbc rune).

math.md: drop phantom `+exp` pass-through section. lib/math.hoon:148
  has `::++  exp  exp:^rs` commented out; the doc dropped the `::` and
  presented it as a live arm. Also removes a duplicate `{#exp}` anchor.

Vane count: nine -> ten (Lick was missing), across 4 files including
  the vane list in arvo/README.md.

Source-block typos, each checked against sys/hoon.hoon:
  4j.md  +hif:ab  `boss` -> `bass`   (note +til legitimately uses +boss)
  2l.md  +molt    `}` -> `]`
  4b.md  +rt:at   `$tape` -> `tape`  (a $-prefix pass leaked into code)
  4m.md  +stab    `$path` -> `path`
  4i.md  +mes     `{a/@ b/@}` -> `[a=@ b=@]`
  1c.md  +bloq -> $bloq (it is `+$` in source); anchor left intact

vere.md: `--scry-info` -> `--scry-into` (the long option never existed
  under the documented name; main.c:303).

dojo-tools.md: `+vat` does not exist (verified: %generator-build-fail);
  replace the dead cross-reference with `+vats %base`.

Kelvin updates are deliberately NOT included: upstream/develop is
[%zuse 408] but the shipping v4.6 pill reports [%zuse 409], and which
one the docs should track is a maintainer decision.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Follows the mechanical-corrections commit on this branch, where these were
deliberately held back pending a decision on which kernel the docs track.
Resolved: they track the current kernel, which is [%zuse 408]. Kelvin counts
down, so 408 is newer than the 410-417 figures the docs carried.

Verified on a fake ship booted from urbit-408k-rc1.pill: %base reports
[%zuse 408], and a desk made by |new-desk gets sys.kelvin [%zuse 408]
(scried as [1.702.065.530 408]), which is what environment.md claims.

Updated, all illustrative or instructional:
  hoon/generators.md (x2)              sample desk listing
  hoon/zuse/README.md                  "410k" naming example
  build-on-urbit/environment.md        "the current kernel version like ..."
  app-school-full-stack/8-desk.md      sample sys.kelvin contents
  hoon-school/H-libraries.md (x2)      sample desk listing
  userspace/examples/flap.md           echo "[%zuse 417]" > sys.kelvin
  userspace/dist/README.md             "e.g. [%zuse 410] (mandatory)"
  urbit-os/kernel/clay/data-types.md   example $weft
  urbit-os/kernel/lick/guide.md        echo "[%zuse 410]" > sys.kelvin

The flap.md and lick/guide.md lines are commands a reader actually runs; a
desk declaring a kelvin the running kernel does not support is rejected, so
those were not merely stale.

Deliberately NOT changed -- these state when a feature was introduced and are
still true:
  userspace/remote-scry.md:18    remote scry landed in [%zuse 413]
  userspace/remote-scry.md:224   path format version added in [%zuse 411]
  urbit-os/base/hood.md:381      %kroc no-op since [%zuse 410]
  urbit-os/kernel/eyre/noun-channels.md:18   noun channels since [%zuse 413]
  core-academy/README.md:22      explicitly a snapshot at Zuse 412k

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