@@ -8,191 +8,445 @@ title: Glossary
88# Glossary
99
1010Urbit is renowned for its exotic terminology. Here's a simple overview
11−from the strange words in.
11+from the strange words within.
1212
1313As Dijkstra put it: "The purpose of abstraction is not to be vague, but
1414to create a new semantic level in which one can be absolutely precise."
1515
16−## Ships
16+### application
1717
18−An Urbit *ship* is a cryptographic title on a *will* signed by private
19−key, a human-memorable name, and a packet routing address. Ships are
20−classed by the number of bits in their address:
18+Also known as an “app,” an *application* is a Hoon program that can hold state.
2119
22− Size Name Parent Object Example
23− ----- ------ ------ ------ -------
24− 2^8 galaxy ~ supernode ~zod
25− 2^16 star galaxy supernode ~dozbud
26− 2^32 planet star user ~tasfyn-partyv
27− 2^64 moon planet device ~sigsam-nimbot-tasfyn-partyv
28− 2^128 comet ~ bot ~racmus-mollen-fallyt-linpex--watres-sibbur-modlux-rinmex
20+### arm
2921
30−Any ship can be called an "urbit."
22+An *arm* is a named, functionally-computed attribute of a [core](#-core).
3123
32−> You can find a longer-form summary here:
33−> [`urbit.org/posts/address-space/`](https://urbit.org/posts/address-space/).
24+The [hoon](#-a-hoon) of each arm is compiled to a Nock formula, with the
25+enclosing [core](#-core) itself as the subject.
3426
35−An Urbit identity is a string like `~firbyr-napbes`. It means nothing,
36−but it's easy to remember and say out loud. `~firbyr-napbes` is actually
37−just a 32-bit number (`3.237.967.392`, to be exact), like an IP address,
38−that we turn into a human-memorable string. The full name of this string
39−can be viewed by typing `our` in the Dojo, Urbit's shell. This is useful
40−when running a ship with a longer name, such as a *moon* or a *comet*.
27+There are two kinds of arms: *dry* and *wet*. Most arms are
28+dry.
4129
42−Technically, an urbit is a secure digital identity that you own and
43−control with a cryptographic key, like a Bitcoin wallet. As in Bitcoin,
44−the supply of urbits is mathematically limited. This keeps the network
45−friendly, by making spam and abuse expensive.
30+- ##### dry:
4631
47−An urbit name is just a number; smaller numbers make shorter names.
48−Shorter names are easier to remember, so they're more valuable. So
49−urbits are classified by the number of bits in their name. (A ship name
50−is just a scrambled base-256 representation of the number.)
32+ normal, `++`, polymorphic by means of *variance*
5133
52−A 32-bit urbit (like `~firbyr-napbes`) is called a *planet.* A 16-bit
53−urbit (like `~pollev)` is a *star.* An 8-bit ship (like `~mun`) is a
54−*galaxy.* A planet is an identity for an independent, adult human. Stars
55−and galaxies are network infrastructure.
34+ For a dry arm, we ask: is the new payload compatible with the old
35+ payload (against which the core was compiled)?
5636
57−Each planet or star is launched by its *parent,* the star or galaxy
58−whose number is its bottom half. So the planet `~firbyr-napbes`,
59−`0xdead.beef` or `3.735.928.559`, is the child of `~pollev`, `0xbeef` or
60−`48.879`, whose parent is `~mun`, `0xef`, `239`. The parent of `~mun`
61−and all galaxies is `~zod`, `0`.
37+- ##### wet:
6238
63−#### pier
39+ unusual, `+-`, polymorphic by means of *genericity*
6440
65−A ship's *pier* is its Unix directory. For planets the name of the pier is usually the planet name.
41+ A wet arm uses the hoon as a macro. We create a new type analysis
42+ path, which works as if we expanded the callee with the caller's
43+ context.
6644
67−### Nock
45+*See [advanced types](../../hoon/advanced/)*.
6846
69−> Nock is a Turing-complete, non-lambda combinator interpreter.
7047
71−- <h6 id="-nock-noun">noun:</h6> an _atom_ or a _cell_
72−- <h6 id="-nock-atom">atom:</h6> any natural number
73−- <h6 id="-nock-cell">cell:</h6> any ordered pair of nouns
74−- <h6 id="-nock-subject">subject:</h6> a noun - the data against which a _formula_ is
75− evaluated
76−- <h6 id="-nock-formula">formula:</h6> a noun - a function at the Nock level
77−- <h6 id="-nock-product">product:</h6> a noun - the result of evaluating a formula against a
78− subject
48+### Arvo
7949
80−*See [Nock definition](../../nock/definition/).*
50+The Urbit operating system and kernel. Arvo's state is a pure function of its
51+event log, and it serves as the Urbit event manager. It contains vanes, which are
52+kernel modules that perform essential system operations. Arvo itself can only
53+deal with one file at a time. For more, it relies on Ford, the build-system
54+vane.
8155
82−## Hoon
56+Arvo being purely functional means that the it is a function that is:
8357
84−> Hoon is a strict, higher-order typed functional language that compiles
85−> itself to Nock.
58+> (state, event) → (state, effects).
8659
87−#### arm
60+Arvo coordinates and reloads vanes. It can be thought of as a traffic-director.
61+Any vane needs to go through Arvo before reaching another vane. Events and
62+their effects happen like so:
8863
89−An _arm_ is a named, functionally-computed attribute of a [core](#-core).
64+> Unix event → vere (the virtual machine that runs Urbit) → Arvo → vane → Arvo
9065
91−The [hoon](#-a-hoon) of each arm is compiled to a Nock formula, with the
92−enclosing [core](#-core) itself as the subject.
66+Arvo is located in `/home/sys/arvo.hoon` within your urbit.
9367
94−There are two kinds of arms: *dry* and *wet*. Most arms are dry.
68+More in-depth information on Arvo can be found
69+[`here`](https://urbit.org/docs/arvo/internals/).
9570
96−- <h6 id="-arm-dry">dry:</h6> normal, `++`, polymorphic by means of *variance*
71+Below are Arvo modules, which are called "vanes".
9772
98−For a dry arm, we ask, is the new payload compatible with the old
99−payload (against which the core was compiled)?
73+- #### Ames
10074
101−- <h6 id="-arm-wet">wet:</h6> unusual, `+-`, polymorphic by means of *genericity*
75+The networking vane. Ames handles all things UDP. Here live the protocols for
76+discovering and interacting with other urbits. It’s also the name for the Urbit
77+network itself. All communication is signed and encrypted.
10278
103−A wet arm uses the hoon as a macro. We create a new type analysis
104−path, which works as if we expanded the callee with the caller's
105−context.
79+Ames is located in `/home/sys/vane/ames.hoon` within your urbit.
10680
107−*See [advanced types](../../hoon/advanced/)*.
81+More in-depth information on Ames can be found
82+[`here`](https://urbit.org/docs/arvo/internals/ames/commentary/).
83+
84+- #### Behn
85+
86+The timing vane. Behn allows for applications to schedule events, which are
87+managed in a simple priority queue. For example, Clay, the Urbit filesystem,
88+uses Behn to keep track of time-specific file requests. Eyre, the Urbit web
89+vane, uses Behn for timing-out HTTP sessions.
90+
91+Behn is located in `/home/sys/vane/behn.hoon` within your urbit.
92+
93+- #### Clay
94+
95+The filesystem and typed revision-control vane. Think of Clay as a
96+continuously synced git. It handles file-change events and maps them from Urbit
97+to Unix and vice versa.
98+
99+A common way to use it is to create a pier, a directory that exists in and is
100+visible in Unix. Changes are automatically recorded from Urbit to the Unix
101+directory, and vice versa. Just set it and forget it!
102+
103+Clay is located at `/home/sys/vane/clay.hoon` within your urbit.
104+
105+Basic information on using Clay can be found
106+[`here`](https://urbit.org/docs/using/filesystem/). An in-depth explanation
107+of the architecture can be found
108+[`here`](https://urbit.org/docs/arvo/internals/clay/architecture/).
109+
110+- #### Dill
111+
112+The terminal-driver vane. You run your urbit in your Unix terminal, and
113+Unix sends every event -- such as a keystroke or a change in the dimensions of
114+the terminal window -- to be handled by Dill. Dill acts as an intermediary for
115+anything that uses keyboard events. This is why there’s some input lag in
116+Urbit’s command-line interface. (Optimization will come later!)
117+
118+A keyboard event's journey from Unix to Dojo, the Urbit shell, can be imagined
119+ as diagrammed below:
120+
121+> Keystroke in Unix terminal -> Vere (virtual machine) -> Arvo -> Dill ->
122+> the Dojo
123+
124+Dill is located at `/home/sys/vane/clay.hoon` within your urbit.
125+
126+More in-depth information on Eyre can be found
127+[`here`](https://urbit.org/docs/arvo/internals/dill/).
128+
129+- #### Eyre
130+
131+The web-server vane. Anything HTTP-related lives here. Unix sends HTTP messages
132+though to Eyre, and Eyre produces HTTP messages in response.
133+
134+In general, apps and vanes do not call Eyre; rather, Eyre calls apps and vanes.
135+Eyre uses Ford and Gall to functionally publish pages and facilitate
136+communication with apps.
137+
138+Eyre is located at `/home/sys/vane/eyre.hoon` within your urbit.
139+
140+More in-depth information on Eyre can be found
141+[`here`](https://urbit.org/docs/using/web/).
108142
109−#### atom
143+- #### Ford
110144
111−A Hoon _atom_ type describes a Nock atom, with two additional pieces
112−of metadata: an *aura*, and an optional constant.
145+The build-system vane. Ford is capable of sequencing generic asynchronous
146+computations. Its uses include linking source files into programs, assembling
147+live-updating websites, and performing file-type conversions.
148+
149+Ford neither accepts Unix events nor produces Unix effects. It exists
150+entirely for the benefit of Urbit applications and other vanes, in particular
151+Gall.
152+
153+Ford is located at `/home/sys/vane/ford.hoon` within your urbit.
154+
155+More in-depth information on Ford can be found
156+[`here`](https://urbit.org/docs/arvo/internals/ford/).
157+
158+- #### Gall
159+
160+The application-management vane. Userspace apps -- daemons, really -- are
161+started, stopped, and sandboxed by Gall. Gall provides developers with a
162+consistent interface for hooking their app up to the operating system. It allows
163+applications and other vanes to send messages to applications and subscribe to
164+data streams. Messages coming into Gall are routed to the intended application,
165+and the response comes back along the same route. If the intended target is on
166+another ship, Gall will route it, behind the scenes, through Ames to the other
167+ship.
168+
169+Gall is located at `/home/sys/vane/gall.hoon` within your urbit.
170+
171+More in-depth information on Ford can be found
172+[`here`](https://urbit.org/docs/arvo/internals/gall/).
173+
174+### atom
175+
176+An atom is any natural number, including zero. The atom is the most basic data
177+type in [Nock](#-nock) and [Hoon](#-hoon). A Hoon atom type describes a Nock
178+atom with two additional pieces of metadata: an [*aura*](#-aura), and an
179+optional constant.
113180
114181An atom type is *warm* or *cold* based on whether the constant exists.
115182
116−- <h6 id="-atom-warm">warm:</h6> if the constant is `~` (null), any
117− atom is in the type
118−- <h6 id="-atom-cold">cold:</h6> if the constant is `[~ atom]`, its
119− only legal value is `atom`.
183+- ##### warm:
184+ if the constant is `~` (null), any atom is in the type.
185+- ##### cold:
186+ if the constant is `[~ atom]`, its only legal value is `atom`.
120187
121188*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*
122189
123−#### aura
190+### Aura
191+
192+An aura a soft atom type. They appear as strings beginning with `@`. Auras
193+represent the structure of an atom, print format, or other semantics. Its
194+constraints on the value of an atom aren't enforced in any way.
195+
196+You can cast something to an aura, like a decimal, and get back its hexademical.
197+For example:
198+
199+ > =a `@`29
200+ > ^- @ux a
201+ 0x1d
202+
203+Auras are an advisory type system. You can go up or down, but not sideways in
204+the hierarchy. `@t` and `@` can each be cast to the other, but @t can’t be cast
205+to `@u`, for example, without first being cast to the empty aura `@`.
206+
207+For example
124208
125−An *aura* is a soft atom type. It represents the structure of an
126−atom in a string beginning with `@`. An aura may represent print
127−format or other semantics. Its constraints on the value of an
128−atom aren't enforced in any way.
209+ > ^- @ 'c' :: 'c' is of the aura @t
210+ 99
129211
130−Two auras are compatible if one is a prefix of the other. You can
131−change any aura into any other aura by casting through the empty
132−aura, `@`. The standard library has molds which alias many common
133−auras.
212+ > ^- @u 'c'
213+ ! exit
134214
135−Some common auras and their aliases:
215+Here is a non-exhaustive list of auras:
136216
137−- <h6 id="-aura-term">term:</h6> (`@tas`): a symbol - an atomic ASCII string which obeys
138− symbol rules: lowercase and digit only, infix hyphen ("kebab-case"),
139− first character must be lowercase alphabetic.
140−- <h6 id="-aura-cord">cord:</h6> (`@t`): UTF-8 text, least-significant-byte first
141−- <h6 id="-aura-char">char:</h6> (`@tD`): a character, a single unicode byte (for multi-byte
142− characters and codepoints, see `@c`)
217+```
218+Aura Meaning Example Literal Syntax
219+-------------------------------------------------------------------------
220+@d date
221+ @da absolute date ~2018.5.14..22.31.46..1435
222+@n nil ~
223+@p phonemic string (ship name) ~sorreg-namtyv
224+@r IEEE floating-point
225+ @rd double precision (64 bits) .~6.02214085774e23
226+ @rh half precision (16 bits) .~~3.14
227+@s signed integer, sign-bit low
228+ @sb signed binary --0b11.1000
229+ @sd signed decimal --1.000.056
230+ @sx signed hexadecimal -0x5f5.e138
231+@t UTF-8 text (cord) 'howdy'
232+ @ta ASCII text (knot) ~.howdy
233+ @tas ASCII text symbol (term) %howdy
234+@u unsigned integer
235+ @ub unsigned binary 0b11.1000
236+ @ud unsigned decimal 1.000.056
237+ @ux unsigned hexadecimal 0x5f5.e138
238+```
143239
144240You can find the list of all auras [here](../../hoon/atom/sand/).
145241
146−*See [basic types](../../hoon/basic/#-atom-p-term-q-unit-atom)*.
242+### blocksize
243+
244+Blocksize is the power-of-two bitwidth of an atom. So, an atom with a blocksize
245+of `3` has a bitwidth of `2^3`, which is 8. A bitwidth of 8, in turn, can
246+represent `2^8` values, or 256.
247+
248+### cast
249+
250+To cast is to put a Hoon expression through the compiler’s type-checker to test
251+whether the expression is guaranteed to evaluate to a product that falls within
252+the desired type. If the expression is not guaranteed to behave in this way,
253+then the compiler will halt with a nest-fail crash. Proper Hoon code will
254+include a cast for the product type of each gate.
255+
256+The cast rune is `^-` (pronounced "ket-hep"). So, to cast to a list of atoms,
257+we write `^- (list @)`. The irregular form of that expression is ``(list @)``.
258+
259+### cell
260+
261+In Nock and Hoon, a *cell* is an ordered pair of [nouns](#-noun).
262+
263+Syntax: `[a b]`.
264+
265+Cells orient to the right; for example, the noun [2 6 14 15] is short for
266+[2 [6 [14 15]]].
267+
268+
269+### clam
270+
271+A clam is the use of a structure as a gate. Usually used to verify marks from
272+other urbits.
273+
274+ > ((list @t) [97 98 ~])
275+ <|a b|>
276+
277+### cord
278+
279+In Hoon, `cord` is an aura for representing atoms as strings. UTF-8,
280+least-significant bit first. Represented as the aura `@t`.
281+
282+ > `@t`478.560.413.032
283+ 'hello'
147284
148285#### core
149286
150−A _core_ is a [cell](#-nock-cell) of `[code data]`, where we call the
151−code head the _battery_ and the data tail the _payload_. All code-data
287+A *core* is a [cell](#-nock-cell) of `[code data]`, where we call the
288+code head the *battery* and the data tail the *payload*. All code-data
152289structures in normal languages (functions, objects, modules, etc.)
153−become _core_s in Hoon.
290+translate to cores in Hoon.
291+
292+- ##### battery
293+ The code-containing head of a core.
154294
155−- <h6 id="-core-battery">battery:</h6> the code of a core, a tree of *arms*
156−- <h6 id="-core-payload">payload:</h6> the data in a core
295+- ##### payload
296+ The data-containing tail of a core.
157297
158298*See [basic types](../../hoon/basic)*.
159299
160−#### face
300+### Dojo
301+
302+The Dojo is the Urbit shell; the command line where you run programs,
303+expressions, and system commands. It’s a CLI that is encountered right when
304+an urbit is started for the first time. It is somewhat analogous to Bash, the
305+Unix terminal, and more analogous to a Hoon REPL.
306+
307+You’ll notice that many things can’t be written here; this is normal. The Dojo
308+enforces syntactical correctness right at the command line. Strings that can’t
309+be continued into a valid expression are automatically trimmed back to something
310+ that can be. Some syntactically invalid expressions can be completed, but the
311+Dojo will prevent them from being entered as a command. You can play around
312+with this functionality learn what syntax is kosher.
313+
161314
162−A Hoon _face_ is a labeled subtree.
315+### duct
163316
164−Hoon has no scope or symbol-table; there is only the subject. To
165−"declare" a "variable" is to construct a new subject:
166−`[name=value old-subject]`.
317+A duct is an Arvo-level call stack. At the beginning of every duct is a Unix
318+event, such as a keystroke, network packet, timer event, or file change.
167319
168−A face is a type that wraps a named symbol (of [aura](#-aura)
169−`@tas`) around another type.
320+A duct is a `list` of `wire`s. A wire is itself a `list` of `knot`s. A `knot`
321+is, in turn, a knot.
322+
323+### face
324+
325+A *face* is the Hoon analog to what is a variable name in most other
326+programming languages. Faces are metadata labels for legs, allowing us to
327+address parts. Because there is no metadata in Nock, faces cannot exist in Nock.
328+
329+ > a=2
330+ a=2
331+
332+In the above example, `a` is the face and `2` is the value.
333+
334+Hoon has no scope or symbol-table; there is only the subject. To "declare" a
335+"variable" is to construct a new subject: `[name=value old-subject]`.
170336
171337*See [advanced types](../../hoon/advanced/#-face-aliases-and-bridges)*.
172338
173−#### gate
174339
175−A _gate_ is a [core](#-core) with one [arm](#-arm) -- Hoon's closest
176−analog to a function/lambda/closure. To call a gate on an argument,
177−replace the sample (at [tree address](../../hoon/limb/limb/) `+6`
340+### flag
341+
342+A `flag` is Hoon's version of a boolean. `0` (`%.y`) is *yes*, `1` (`%.n`) is
343+*no*.
344+
345+> Why? It's fresh, it's different, it's new. And it's annoying. And it
346+> keeps you on your toes. And it's also just intuitively right.
347+
348+### gate
349+
350+A *gate* is a [core](#-core) with one [arm](#-arm) -- Hoon's closest
351+analog to a function. To call a gate on an argument, replace the sample
352+(at [tree address](../../hoon/limb/limb/) `+6`
178353in the core) with the argument, and then compute the arm.
179354
180355The payload of a gate has a shape of `[sample context]`.
181356
182−- <h6 id="-gate-sample">sample:</h6> the argument tuple
183−- <h6 id="-gate-context">context:</h6> the subject in which the gate was defined
357+- ##### sample
358+ The argument tuple.
359+- ##### context
360+ The subject in which the gate was defined.
184361
185362*See [basic types](../../hoon/basic/#-core-p-type-q-map-term-type),
186363[`%-` ("cenhep")](../../hoon/rune/cen/hep/) (the
187364[rune](#-rune) for calling a `gate`).*
188365
189−#### <h4 id="-a-hoon">hoon</h4>
366+### generator
367+
368+A *generator* is like a limited Hoon script: it’s a shell command that produces
369+a value before disappearing. Generators take an input [noun](#-noun) (a value)
370+and produce an output `noun` by performing calculations on its arguments,
371+prompting for input, or making HTTP requests.
372+
373+You need a `bar` rune like `|=` in your generator, because a generator is
374+essentially a function that you’re calling.
375+
376+Generators, unlike [apps](#-application), hold no state. They are pure,
377+stateless functions, and they cannot send [moves](#-move). Because of this,
378+generators are have a more narrow use than apps. Among the non-trivial uses of
379+a a generator is moving data into apps -- they’re the backbone of Urbit’s
380+information pipeline.
381+
382+Generators are run from the `/gen` directory of your current desk. For example,
383+to run a generator named whatever.hoon, you would type `> +whatever` in the
384+[Dojo](../dojo).
385+
386+### glyph
387+
388+A *glyph* is a single, non-alphanumeric ASCII character. Each glyph has its own
389+monosyllabic name, which allows the efficient communication of Hoon-related
390+information in speech. [`Runes`](#-rune) are composed of two glyphs.
391+Below is a complete list of glyphs with their associated pronunciations.
392+
393+```
394+ace space gal < per )
395+bar | gar > sel [
396+bas \ hax # mic ;
397+buc $ hep - ser ]
398+cab _ kel { sig ~
399+cen % ker } soq '
400+col : ket ^ tar *
401+com , lus + tec `
402+doq " pam & tis =
403+dot . pat @ wut ?
404+fas / pel ( zap !
405+```
406+
407+### Hall
190408
191−A [`hoon`](../../hoon/reference/) is the result of parsing a Hoon source
192−expression into an AST node. These AST nodes are nouns, like all
193−other Hoon data. Because every Hoon program is, in its entirety, a
194−single expression of Hoon, the result of parsing the whole thing
195−into an AST is a single `hoon`.
409+*Hall* is the Urbit communication back-end. It’s a messaging bus that can work
410+with clients of all sorts. [`:talk`](#-talk), the built-in chat client, is one
411+such app that uses Hall.
412+
413+*More information on Hall can be found [here](../hall).*
414+
415+- #### circle
416+
417+ A circle is the “audience” of your messages -- who can receive them. It can be
418+ thought of as a chat channel, but this is a little too narrow. More
419+ specifically, it’s a named collection of messages created by and hosted on a
420+ ship’s Hall, usually represented as `~ship-name/circle-name`. On Talk,
421+ Urbit’s built-in chat front-end, the first circle that you will likely
422+ encounter is `/urbit-meta`.
423+
424+### Hood
425+
426+*Hood* orchestrates many of the Urbit initialization systems necessary
427+for boot.
428+
429+### Hoon
430+
431+Hoon is a strict, higher-order typed functional language that compiles itself
432+to Nock.
433+
434+The Hoon source file is located in `/home/sys/hoon.hoon` within your urbit.
435+
436+*More information can be found in the [hoon](../../hoon) section.*
437+
438+- #### Mint
439+
440+ *Mint* is the Hoon compiler function. Mint takes the subject type and the
441+ expression source (a [hoon](#-a-hoon), for example) and produces the product
442+ type and nock formula. So [type hoon] is mapped to [type nock].
443+
444+### <a id="-a-hoon">hoon</a>
445+
446+A *hoon* (lowercase) is the result of parsing a Hoon source expression into an
447+AST node. These AST nodes are nouns, like all other Hoon data. Because every
448+Hoon program is, in its entirety, a single expression of Hoon, the result of
449+parsing the whole thing into an AST is a single `hoon`.
196450
197451A hoon is a tagged union of the form `[%tag data]`, where the tag
198452is a constant such as `%brts` (from the source [rune](#-rune) `|=`,
@@ -222,31 +476,107 @@ The result should be:
222476[%clls p=[%sand p=%ud q=12] q=[%sand p=%ud q=7] r=[%rock p=%tas q=97]]
223477```
224478
225−#### limb
479+See [expression reference](../../hoon/reference/) for the
480+full of hoons.
481+
482+### irregular form
483+
484+Irregular forms are alternative ways of writing Hoon expressions, alternatives
485+to the digraphic runes such as `:~`. Irregular forms are usually more compact
486+than regular forms.=
487+
488+*See [irregular forms](../../hoon/irregular).*
489+
490+### jet
491+
492+A *jet* is a piece of C code that have equivalent products to a piece of Hoon or
493+ Nock code. They are used for performance reasons; jets are meant to be faster
494+than the code that they are substituting for.
495+
496+Jets are necessary for mathematics, performance-wise, because Nock handles it
497+so inefficiently. Nock, for example, can’t decrement (reduce a number by one)
498+except by starting building a loop that starts from zero and increments to a
499+number just below.
500+
501+*See [API overview](../../vere/api).*
502+
503+### lark
504+
505+A lark is an expression that returns a [limb](#-limb) at the specified
506+address in a cell. Using `-` by itself returns the head of the subject, and
507+using `+` by itself returns the tail:
508+
509+```
510+> -:[[4 5] [6 [14 15]]]
511+[4 5]
512+
513+> +:[[4 5] [6 [14 15]]]
514+[6 14 15]
515+```
516+
517+You can combine `+` or `-` with either of `>` or `<` to get a more specific limb
518+of the subject. `-<` returns the head of the head; `->` returns the tail of the
519+head; `+<` returns the head of the tail; and `+>` returns the tail of the tail.
520+By alternating the `+`/`-` symbols with `<`/`>` symbols, you can go as deep as
521+you desire.
522+
523+```
524+> +>-:[[4 5] [6 [14 15]]]
525+14
526+
527+> +>+:[[4 5] [6 [14 15]]]
528+15
529+```
530+
531+### limb
226532
227−A _limb_ is an attribute or variable reference.
533+A *limb* is an attribute or variable reference. A limb is an [arm](#-arm) or a
534+[leg](#-leg).
228535
229536To resolve a *limb* named "foo", the subject is searched depth-first,
230537head-first for either a face named "foo" or a core with an arm of
231538"foo". If a face is found, the result is a leg, if a core is
232539found, the result is the product of the arm.
233540
234−- <h6 id="-limb-leg">leg:</h6> a subexpression, or subtree of the subject.
235−- <h6 id="-limb-wing">wing:</h6> a list of limbs, searched from right to left (`a.b` means
236− `b` within `a`).
541+- ##### leg
542+ a subexpression, or subtree of the
543+ [subject](#nock-subject).
544+-
545+- ##### wing
546+ a search path into the subject, composed of
547+ limbs. Search occurs from right to left (`a.b` means `b` within `a`).
237548
238549*See [Limbs and wings](../../hoon/limb/)*
239550
240−#### loobean
551+### move
241552
242−A _loobean_ is a Hoon boolean. `0` (`%.y`) is *yes*, `1` (`%.n`) is *no*.
553+A move is the [Arvo](#-arvo) equivalent of a syscall.
554+
555+### noun
556+
557+In [Nock](#-nock) and [Hoon](#-hoon), a *noun* is an atom or a cell.
558+
559+
560+### Nock
561+
562+Nock is Nock is a Turing-complete, non-lambda combinator interpreter. It's
563+Urbit's low-level programming language. Nock is functional and typeless.
564+
565+- <h5 id="-nock-noun">noun:</h5> an *atom* or a *cell*.
566+- <h5 id="-nock-atom">atom:</h5> any natural number, including zero.
567+- <h5 id="-nock-cell">cell:</h5> any ordered pair of nouns.
568+- <h5 id="-nock-subject">subject:</h5> a noun - the data against which a
569+ *formula* is evaluated.
570+- <h5 id="-nock-formula">formula:</h5> a noun - a function at the Nock level.
571+- <h5 id="-nock-product">product:</h5> a noun - the result of evaluating a
572+ formula against a subject.
573+
574+*See the [Nock definition](../../nock/definition/).*
243575
244−> Why? It's fresh, it's different, it's new. And it's annoying. And it
245−> keeps you on your toes. And it's also just intuitively right.
246576
247577#### mark
248578
249−A _mark_ is Urbit's version of a MIME type, if a MIME type was an
579+A *mark* is Urbit's version of a MIME type, if a MIME type was an
250580executable specification. The mark is just a label that's used as a path
251581to a local source file in the Arvo filesystem. This source file defines
252582a core that can mold untrusted data, diff and patch, convert to other
@@ -259,7 +589,7 @@ that we at least handle the situation in a predictable way.
259589
260590#### metal
261591
262−Every core has a _metal_ which defines its variance model (ie, the
592+Every core has a *metal* which defines its variance model (ie, the
263593properties of the type of a compatible core). The default is `gold`
264594(invariant).
265595
@@ -270,33 +600,89 @@ properties of the type of a compatible core). The default is `gold`
270600
271601*See [advanced types](../../hoon/advanced)*.
272602
273−#### mold
603+### ship
604+
605+An Urbit *ship* is: a cryptographic title on a *will* signed by private key; a
606+human-memorable name; and a packet-routing address. Ships are classed by the
607+number of bits in their address:
608+
609+ Size Name Parent Object Example
610+ ----- ------ ------ ------ -------
611+ 2^8 galaxy ~ supernode ~zod
612+ 2^16 star galaxy supernode ~dozbud
613+ 2^32 planet star user ~tasfyn-partyv
614+ 2^64 moon planet device ~sigsam-nimbot-tasfyn-partyv
615+ 2^128 comet ~ bot ~racmus-mollen-fallyt-linpex--watres-sibbur-modlux-rinmex
616+
617+Any ship can be called an *urbit*. The lowercase "u" distinguishes it from Urbit
618+ the software stack and Urbit the network.
619+
620+> You can find a longer-form summary here:
621+> [`urbit.org/posts/address-space/`](https://urbit.org/posts/address-space/).
622+
623+An Urbit identity is a string like `~firbyr-napbes`. It means nothing,
624+but it's easy to remember and say out loud. `~firbyr-napbes` is actually
625+just a 32-bit number (`3.237.967.392`, to be exact), like an IP address,
626+that we turn into a human-memorable string. The full name of this string
627+can be viewed by typing `our` in the Dojo, Urbit's shell. This is useful
628+when running a ship with a longer name, such as a *moon* or a *comet*.
629+
630+Technically, an urbit is a secure digital identity that you own and
631+control with a cryptographic key, like a Bitcoin wallet. As in Bitcoin,
632+the supply of urbits is mathematically limited. This keeps the network
633+friendly, by making spam and abuse expensive.
634+
635+An urbit name is just a number; smaller numbers make shorter names.
636+Shorter names are easier to remember, so they're more valuable. So
637+urbits are classified by the number of bits in their name. (A ship name
638+is just a scrambled base-256 representation of the number.)
639+
640+A 32-bit urbit (like `~firbyr-napbes`) is called a *planet.* A 16-bit
641+urbit (like `~pollev)` is a *star.* An 8-bit ship (like `~mun`) is a
642+*galaxy.* A planet is an identity for an independent, adult human. Stars
643+and galaxies are network infrastructure.
644+
645+Each planet or star is launched by its *parent,* the star or galaxy
646+whose number is its bottom half. So the planet `~firbyr-napbes`,
647+`0xdead.beef` or `3.735.928.559`, is the child of `~pollev`, `0xbeef` or
648+`48.879`, whose parent is `~mun`, `0xef`, `239`. The galaxy at the address of
649+`0` is `~zod`.
650+
651+
652+ - #### pier
653+
654+ A ship's *pier* is its Unix directory. For planets, the name of the pier is
655+ usually the planet name.
274656
275−A _mold_ is an idempotent [gate](#-gate) (function), accepting any noun,
276−and producing a range with a type, a set of nouns.
277657
278−Molds act as type constructor/validators in Hoon. An example: Arvo
279−[marks](#-marks) use Hoon's type system under the hood via molds to
658+
659+### structure
660+
661+A *structure* is an idempotent [gate](#-gate) (function) that constructs and
662+validates types in Hoon.
663+
664+An example: Arvo [marks](#-marks) use Hoon's type system via structures to
280665validate untrusted network data.
281666
282−Here's some common mold terminology:
667+Here's some common structure terminology:
283668
284−- <h6 id="-mold-bunt">bunt:</h6> the value a mold produces when normalizing its default
285− sample
286−- <h6 id="-mold-icon">icon:</h6> the type of the mold's range
669+- #### bunt:
287670
288−*See [mold hoons](../../hoon/rune/buc/).*
671+ A bunt is the default value of a [structure](#-structure). It's also a verb;
672+ to *bunt* a structure is to produce the bunt of that structure. For example,
673+ bunting `@` results in `0`, and bunting `@t` results in `''`. Bunting is
674+ performed with `*` followed by the structure in question:
675+ ~~~
676+ > *@
677+ 0
678+ > *@t
679+ ''
680+ ~~~
289681
290−#### nest
682+- #### icon: The type of the mold's range.
291683
292−`nest` is an internal Hoon function on two types which performs a type
293−compatibility test. `nest` produces yes if the
294−set of nouns in the second type is provably a subset of the first.
295−If `nest` produces no, the Hoon programmer will receive a `nest-fail`
296−error. This is one of the most commons errors in Hoon programming.
684+*See [mold hoons](../../hoon/rune/buc/).*
297685
298−*See [advanced types](../../hoon/advanced/)*.
299−*See [troubleshooting](../../hoon/troubleshooting/#-nest-fail)*.
300686
301687#### rune
302688
@@ -312,10 +698,10 @@ The result of parsing a Hoon source expression—the rune, followed
312698by its respective children—into an AST node is simply called
313699a [`hoon`](#-a-hoon).
314700
315−Runes have two syntactic forms, _tall_ and _flat_:
701+Runes have two syntactic forms, *tall* and *flat*:
316702
317−- <h6 id="-rune-tall">tall:</h6> multiple lines, no parentheses, two or more spaces between
318− tokens
703+- ##### tall:
704+ multiple lines, no parentheses, two or more spaces between tokens
319705
320706 Example:
321707
@@ -323,7 +709,8 @@ Runes have two syntactic forms, _tall_ and _flat_:
323709 ~zod:dojo> %+ add 2 2
324710 4
325711 ```
326−- <h6 id="-rune-flat">flat:</h6> one line, parentheses, one space between tokens
712+- ##### flat:
713+ one line, parentheses, one space between tokens
327714
328715 Example:
329716
@@ -341,18 +728,39 @@ forms are flat.
341728*See [hoon concept](../../hoon/concepts/#-hoon),
342729[expressions](../../hoon/rune/), and [syntax](../../hoon/syntax/)*.
343730
344−#### slot
731+### Sail
732+
733+*Sail* is the Hoon markup language for XML.
345734
346−`slot` is the name for Hoon's tree addressing scheme.
735+### scry
736+
737+To *scry* means to request data from the Arvo namespace and bring it
738+to userspace.
739+
740+*See [.^ (dot-ket)](../../hoon/rune/dot/ket/).*
741+
742+### slot
743+
744+`slot` is the name for Hoon's tree-addressing scheme.
347745
348746Every cell has a head and a tail, each of which may be either an atom or
349747a cell. Therefore every noun is a binary tree. `+1` or `.` resolves to
350748the whole cell (technically this would work against an atom as well).
351749The head of `+n` is `+2n`, the tail is `+(2n+1)`.
352750
353−#### type
751+`+7` is a special address for gates, because the position is defined
752+(by convention) as the context of a gate and of all cores.
753+
754+### Talk
755+
756+*Talk* is Urbit's built-in chat app. It’s one example of an app that can be
757+built on top of Hall, the Urbit back-end messaging system.
758+
759+*See [Messaging](../using/messaging). for more information.*
354760
355−A Hoon _type_ defines a set (finite or infinite) of nouns and ascribes
761+### type
762+
763+A Hoon *type* defines a set (finite or infinite) of nouns and ascribes
356764some semantics to it. There is no direct syntax for defining
357765types; they are always defined by inference (i.e., by
358766[`mint`](#-mint)), usually using a constructor ([`mold`](#-mold)).
@@ -362,4 +770,44 @@ All types are assembled out of base types defined in `++type`.
362770does type-inference on a program, it assembles complex types out
363771of the simpler built-in types.
364772
365−*See [basic types](../../hoon/basic/).*
773+- #### nest
774+
775+ `nest` is an internal Hoon function on two types which performs a type
776+ compatibility test. `nest` produces yes if the
777+ set of nouns in the second type is provably a subset of the first.
778+ If `nest` produces no, the Hoon programmer will receive a `nest-fail`
779+ error. This is one of the most commons errors in Hoon programming.
780+
781+ *See [advanced types](../../hoon/advanced/)*.
782+ *See [troubleshooting](../../hoon/troubleshooting/#-nest-fail)*.
783+
784+
785+### Unit
786+
787+Hoon's equivalent of a nullable pointer or a Haskell Maybe. If `q` is `~`,
788+null, the type is *warm*; any atom is in the type. If `q` is `[~ x]`, where
789+`x` is any atom, the type is *cold*; its only legal value is the constant `x`.
790+
791+### Vane
792+
793+A *vane* is an [Arvo](#-arvo) module. Each Vane is a single file because Arvo
794+cannot, on its own, deal with programs that are split between multiple files.
795+Some vanes can do this, however.
796+
797+### Vere (pronounced “vair”)
798+
799+The runtime system, written in C, that implements [Nock](#-nock). All
800+It’s written in C. Vere-level errors are prepended with as `bail:`.
801+
802+Vere is a virtual machine: it pretends to be hardware, and is the single point
803+of contact between your Urbit and the rest of your system. But more than that,
804+Vere handles the Urbit event log and handles jets. It’s also contains the i/o
805+drivers for Urbit’s vanes, responsible for generating events from Unix and
806+applying effects to Unix.
807+
808+### Zuse
809+
810+*Zuse* is a defined interface for vanes. It contains the part of the Hoon
811+standard library that is specific to Arvo functionality.
812+
813+Arvo is located in `/home/sys/zuse.hoon` within your urbit.