Following these comments I was pretty surprised to learn that we do not consider lus and terminating runes to actually be runes. I'm pretty sure everywhere in our documentation suggests that they are. This needs to be cleaned up.

What should these be called?

All the glob related links seem to be broken (404). Not sure where they should even be pointing to.

Besides this one issue, is there any way to check for all link/image validity in a linting step? Don't know what tooling exists, but it would certainly be helpful.

The Spider example for parent/child threading does not work in the current Arvo (%base hash tbef4).

> -parent
clay: read-at-aeon fail [desk=%base care=%b case=[%da p=~2021.11.18..16.40.51..216e] path=/thread-done]
clay: no files match /mar/thread-done/hoon
[%error-building-mark %thread-done]
[%error-building-dais %thread-done]
/sys/vane/clay/hoon:<[4.253 13].[4.253 34]>
/sys/vane/clay/hoon:<[4.241 7].[4.267 9]>
~sidret_samzod:dojo> 
bail: 4

bail: 2
spider crashed, killing all strands: %fact
! closing subscription
! 
  / cb
    ~sidret-banseg-finlud-tasmug--podmep-dibned-bossyn-samzod
    base
    ~2021.11.18..16.40.51..216e
    thread-done
spider got agent for non-existent ~.~.dojo_0v6.sorgb.opd4k.at2ft.b652a.kp5o1
eyre: replacing existing binding at /spider
spider got agent for non-existent ~.~.dojo_0v6.sorgb.opd4k.at2ft.b652a.kp5o1
thread failed: %cancelled

This refers to the following files:

parent.hoon:

/-  spider
/+  *strandio
=,  strand=strand:spider
^-  thread:spider
|=  arg=vase
=/  m  (strand ,vase)
^-  form:m
;<  =bowl:spider  bind:m  get-bowl
=/  tid  `@ta`(cat 3 'strand_' (scot %uv (sham %child eny.bowl)))
;<  ~             bind:m  (watch-our /awaiting/[tid] %spider /thread-result/[tid])
;<  ~             bind:m  %-  poke-our
                          :*  %spider
                              %spider-start
                              !>([`tid.bowl `tid byk.bowl %child !>(~)])
                          ==
;<  =cage         bind:m  (take-fact /awaiting/[tid])
;<  ~             bind:m  (take-kick /awaiting/[tid])
?+  p.cage  ~|([%strange-thread-result p.cage %child tid] !!)
  %thread-done  (pure:m q.cage)
  %thread-fail  (strand-fail !<([term tang] q.cage))
==

child.hoon:

/-  spider
/+  *strandio
=,  strand=strand:spider
=>
|%
++  url  "https://www.whatsthelatestbasehash.com/"
--
^-  thread:spider
|=  arg=vase
=/  m  (strand ,vase)
^-  form:m
;<  =cord  bind:m  (fetch-cord url)
=/  hash-as-cord  `@t`(end [3 (sub (met 3 cord) 1)] cord)
=/  hash  `@uv`(slav %uv hash-as-cord)
(pure:m !>(hash))

Hoon has four runes used for defining multi-arm cores: |%, |_, |@, and |^. We have at least a couple different ways in which we refer to the current subject in Hoon. For example:

Gall apps typically have:

|_  =bowl:gall
  +*  this  .

Cores made with |% often use ++:

|%
  ++  foo  .

A quick look for |@ and |^ runes with an arm whose content is just . didn't yield any results, but I didn't look for very long and am not clever enough with regular expressions to search the whole repo.

Can the appropriate lus rune to use always be directly inferred from the runes used to define the core? To be more precise, can we say something like "when you have a multi-arm core made with X bar rune and wish to name it, use Y lus rune".

Does this change at all when the core is iron/gold/zinc/lead/wet/dry?

What is it called when you name a core this way? Is it the face of the core, or some other name?

I suggest including this information in /docs/tutorials/hoon/style.md.

𐐝𐐮𐐾𐐮𐑊𐐰𐑌𐐻𐐨 Maybe instead of a 404, you could have a landing page that says the docs are in the docs app? I wouldn't have known either.

It links to /reference so it doesn't belong in the overview section anymore

The 'development roadmap' link here (https://github.com/urbit/urbit.org/blob/master/main/posts/overview.md) should be updated to link to the 2017 roadmap.

• ames
• aqua
• arm
• arvo
• atom
• azimuth
• battery
• behn
• bridge
• censures
• chat
• claims
• clay
• comet
• core
• delegated-sending
• desk
• dill
• docvote
• dojo
• door
• ecliptic
• eventlog
• eyre
• galaxy
• gall
• gate
• hdwallet
• hoon
• invite-tree
• iris
• jael
• keyfile
• khan
• landscape
• mark
• moon
• nock
• noun
• ota-updates
• payload
• ph
• pier
• pill
• planet
• proxies
• replay
• reset
• rollups
• sailudon
• senate
• ship
• shiparvonetwork
• star
• sync
• trap
• upgrade
• vane
• vere
• voting
• wallet-generator

This was suggested in the Infrastructure channel and is a good idea. Since I've been making diagrams sporadically, I'll probably do this, but I don't have an estimate on when I will get to that yet.

For each of the primary sections in Urbit's documentation, we've imagined that beautiful illustrations of the contained contents would be a fun bit of expressive "flavor" to add. We already have an artist primed to work on this, we simply need the go-ahead and a deadline.

Example intent below:

Following this comment here - separating out the arguments from the name isn't really necessary and just creates clutter.

urbit/docs#1089 (comment)

https://developers.urbit.org/overview/arvo

I removed them right before merging urbit/urbit.org#1084 since they were out of date. Making an issue so I remember to add them back in.

urbit/urbit.org#1084 (comment)

See event card designs – similar to blog post cards

Arguably this should go into urbit/urbit's CONTRIBUTING.md, arguably that should be mirrored onto the site. In any case:

Recent OTA introduced -work for creating a separate desk to do work off. There's also some changes to the way you load in structures/libraries in dojo, so you can no longer do /+ mylib etc, but you can do =mylib -build-file %/lib/mylib/hoon. The latter works for arbitrary files, so you could load in an app core and play around with it in dojo, which seems really powerful.

(I didn't test these, but @belisarius222 told me about them, and we agreed this should be documented. Just filing this to make sure it gets followed up on.)

There's probably other useful-for-developers things like that, that we can document.

I've seen the a=tape -> a-tape pattern come up a bit but as a beginner it's hard to understand it until you try it yourself since there's no documentation. I think it would be nice to see it on the irregular syntax page.

Here's an example of where it's used:
https://github.com/urbit/urbit/blob/98c6c77ebb1a5e39cf21fa532f088a64c8b4f56b/pkg/arvo/sys/vane/ames.hoon#L497

https://cs.github.com/?scope=org%3Aurbit&scopeName=urbit&q=%2F%3D%5Cw%2B%3D%5Cw%2B%2F+path%3A*.hoon

As of now there are no examples of its use in the Hoon codebase.

 [%bcls p=stud q=spec]                     ::  $+, standard   
 
         [%bcls *]  [%note [%know p.mod] $(mod q.mod)]                                                   

        [%bcls *]  (decorate [%note [%know p.mod] example(mod q.mod)])

on https://developers.urbit.org/guides there's no additional guides button/card/whatever so you have to open another guide & then click additional guides in the sidebar. There should be a list of the additional guides at the bottom of the landing page

It's unclear to me what is up-to-date in the docs. One way this could be remedied is by adding a last-updated date to each page in the docs.

It would also be fantastic to provide a link to the source code for each page – I think this was suggested by someone else too, maybe Mark.

^

https://urbit.org/docs/glossary/wallet-generator/

This was raised by someone in UC, but since I didn't immediately file an issue I don't remember who.

The page says "The Wallet Generator is a planned open-source app developed for generating an Urbit HD Wallet to secure your Azimuth identities. "

To the best of my knowledge, nobody is working on this right now. But there is an Urbit wallet generator https://github.com/urbit/urbit-wallet-generator that is marked as deprecated, but definitely still works.

The timeline of this is confusing. The wallet generator is ~2 years old, the glossary is ~18 months old, and the wallet generator was only marked deprecated 6 months ago. Since the glossary was started before I came to Tlon, I don't know if this entry was written before the wallet generator app was finished, and the "planned wallet generator app" was referring to the one that actually already exists, or if it is referring to whatever will be replacing the deprecated one.

So the entry needs to be changed somehow, but I'm not sure to what. Can you shed any light on this @jtobin ? (I'm guessing you're the person to ask based on commits on the wallet generator repo)

https://developers.urbit.org/guides/core/hoon-school/M-typecheck#nock-checks-(-dot-runes)

• merge in dev.tlon.io (?)
• copy over https://urbit.org/using/os/shell somewhere sensible
• move Graph Store docs to %docs app
• glossary words selected & cleaned up
• move image files out of Hoon School
• fix internal references/links
• alias old links in docs?
• update jetting guide at least for repos etc.

Much like how we generate a search cache on build, we are totally able to construct the glossary.js file from metadata if we want — we'd just need to put the information currently in the JSON file into the TOML (this itself could be scripted, probably).

@tinnus-napbus @sigilante I'm assuming this is desirable?

https://docs.google.com/document/d/1Y_Oz0Tc1R0CHof4jBcPcvhEMsb4tvXVA1ZBqusotUK8/edit

Found in the wild: https://github.com/Fang-/djay/blob/261766af0383eaa6f1e168b6c4c06da69a64175e/app/djay.hoon

[anonymous]> yeah, it gets treated as equivalent to => |% ... -- |_ ... --

Not mentioned in the bar rune reference or the irregular form reference.

If bit 31 is set in a u3_noun, bit 30 is always set - this bit is reserved. Bit 29 is 1 if the noun is a cell, 0 if it's an atom. Bits 28 through 0 are a word pointer into the loom - see below. The structures are:

This should be explicit about 0-indexing: "bit 31" is the most-significant bit of a uint32_t. And bit 30 is not always set -- it distinguishes atoms and cells. The two tag bits are adjacent.

More generally, this text was sourced from u3.md, but with an unknown amount of changes. u3.md is stale in some areas (especially wrt the jet dashboard), but is the most complete documentation we have for vere (outside of comments in the code itself). With these edited copies on urbit.org, improvements made to either side or very unlikely to be forward/back-ported to the other.

For low-level documentation, of implementation details subject to change, I think it would be better to keep docs close to the code. (As another example, the Cryptography page has apparently been wrong since those jets were rewritten on top of the urcrypt library over a year ago.)

https://developers.urbit.org/reference/hoon/stdlib links appear to be broken (compare to https://developers.urbit.org/reference/hoon/stdlib/table-of-contents)

See attached:

The docs for %^, %+, %-, and %: say that they take in N hoons https://urbit.org/docs/hoon/reference/rune/cen, but this is not the case if they're part of a structure definition, e.g +$ foo %- list @. In this case, the % runes parser takes in a hoon and N specs. The rune docs ought to reflect this.

The above 4 runes are the ones with explicit cases in +structure:norm but I think it also applies to e.g. %.

|pass isn't documented on its own in the Hood docs. It is used incidentally in the Jael, Clay, and Eyre examples.

Currently, the Urbit Docs are host to a variety of useful diagrams + visualizations provided by contributors.

These visual assets are generally technical in nature, and could use with a "standardization pass".

Some examples of existing divergent approaches:

At the very least, assets could be translated into vector filetypes. At the most, a producer could ingest all known visual attachments to Urbit docs and instill a singular visual language across all imagery.

• L2 rollup
• agent
• api
• aura
• aural ASCII
• battery
• bowl
• bunt
• card
• case
• cell
• commit
• cons
• context
• cord
• double boot
• duct
• entropy
• face
• fact
• foo bar baz
• garden
• generator
• gift
• glob
• helm
• hood
• jet
• kelvin
• kernel
• keywords
• kiln
• leg
• list
• loobean
• lull
• mold
• monad
• move
• path
• patp
• payload
• peek
• poke
• roller
• rune
• runtime
• sail
• sample
• scry
• slam
• spider
• string
• subject
• subject-oriented programming
• subscription
• tape
• thread
• userspace
• wing
• wire
• wrapper
• zuse
• ~
• ~zod
• cask
• dry
• wet
• metals
• warm atom
• cold atom

See this web page:
https://developers.urbit.org/reference/glossary/moon

the bottom two links in the page go to developers.urbit.org/relative_link instead of urbit.org/relative_link
so clicking the link results in a 404.

• Change font-weight of buttons to 600, add following html/css to buttons

-webkit-font-smoothing: antialiased;
    -moz-osx-font-smoothing: grayscale;
    text-rendering: optimizeLegibility;

• Change font-weight of h2s to 700, include above anti-aliasing css
• Change font-size on guide cards from 14px to 16px
• Change font-weight on .button-sm to 600, include above anti-aliasing css, increasing button height to 3rem - match design

There's an oldish guide (2 years I think?) for %aqua at https://urbit.org/docs/hoon/guides/aqua

I tried following the directions:

|start %aqua
:aqua +solid
-ph-add

but it doesn't get all the way through.

gall: installing %aqua
> |start %aqua
>=
%solid-start
%solid-loaded
%solid-parsed
%solid-arvo
[%solid-kernel 0x7168.4d12]
lull: ~hidrun-loclun
zuse: ~tipnut-hacpyl
vane %ames: ~rigsud-bolmes
vane %behn: ~sartes-masnyl
vane %clay: ~dachut-hapdur
vane %dill: ~milwer-fogmeb
vane %eyre: ~bonler-ranteb
vane %gall: ~dildus-landef
vane %iris: ~macryl-midnyl
vane %jael: ~rabbyl-famdeg
[%user-files 397]
> :aqua +solid
/sys/vane/gall/hoon:<[1.372 9].[1.372 37]>
/app/aqua/hoon:<[81 5].[89 17]>
/app/aqua/hoon:<[82 5].[89 17]>
/app/aqua/hoon:<[83 7].[88 9]>
/app/aqua/hoon:<[83 17].[83 45]>
[%aqua-bad-mark %boot-pill]
/app/aqua/hoon:<[83 42].[83 44]>
dojo: app poke failed

Not sure if this is actually a bug with %aqua or something else, or its just outdated. Given the release of software distribution, it might be the right time to rewrite this guide anyways.

See attached images

The child thread example (https://urbit.org/docs/userspace/threads/examples/child-thread) uses the website whatsthelatestbasehash.com which appears to be defunct.

From UC ~rivmud-fabwen

Q about galaxy-routing. If a planet is on a home network with no port-forwarding, are both incoming and outgoing packets routed through a galaxy, or only incoming?
05:56
Also how does a galaxy talk to the planet it's routing for?

I should do this sometime this quarter when I do another round of edits on the Ames doc, along with #139 urbit/urbit.org#1043

• parser-combinators as theoretical concept, à la (basics of this in already)
• implementing a custom aura
• how building code works

i can change them all to work by replacing ./ with /guides/core/hoon-school/, but it might be easier to change it in the parser? idk how possible that is tho? lmk if pref just swap to /guides/core/hoon-school/ and i shall continue doing that

here is an example: https://developers.urbit.org/guides/core/hoon-school/J-stdlib-text
link in first para is ./P-stdlib-io.md in markdown, but it links to https://developers.urbit.org/guides/P-stdlib-io.md while correct link is https://developers.urbit.org/guides/core/hoon-school/P-stdlib-io.md

also this particular relative link for an image seems to not have a file at all it's pointing to: https://developers.urbit.org/guides/core/hoon-school/binary-tree-tape.png
(on this page https://developers.urbit.org/guides/core/hoon-school/J-stdlib-text#(list-t)-tape )
(and interestingly it's relative link actually gives the correct relative path (/guides/core/hoon-school/), so perhaps just need to copy url parsing from <img> parsing to <a> parsing? )

From pending new vere release notes:

• ames.c packet filtering and stateless forwarding

Previously, every incoming packet would get passed into ames.hoon (and,
subsequently, the event log) for processing. The changes here add a
pre-processing stop to ames.c's packet handling, reducing the amount of
work that goes into ames.hoon proper. Specifically, we do two things:

First, if we detect we won't be able to do anything useful with the packet
(for example, it has an Ames protocol version we are not aware of, the hash
is invalid, or it's generally unreadable), we simply drop it.

Secondly, if we detect the packet isn't for us, but meant to be forwarded,
and we can forward it correctly, we do so synchronously. This lets the
packet avoid the event loop, which improves performance and reduces event
log growth for ships doing forwarding.