git.iko.soy/urbit.org
on master help sign in
restructures
39bc0abRobert
azimuth/glossary.md+1−1
compare with master
unifiedsplit
@@ -1,6 +1,6 @@
1+++
1+++
2title = "Azimuth Glossary"
2title = "Azimuth Glossary"
3−weight = 3
3+weight = 4
4template = "doc.html"
4template = "doc.html"
5aliases = ["/docs/reference/azimuth-glossary/"]
5aliases = ["/docs/reference/azimuth-glossary/"]
6+++
6+++
concepts/_index.mdnew file+13
@@ -0,0 +1,13 @@
1++++
2+title = "Concepts"
3+weight = 3
4+sort_by = "weight"
5+template = "sections/docs/chapters.html"
6++++
7+The documents in this section are high-level introductions to the Urbit project and components thereof.
8+
9+
10+* [Technical Overview](technical-overview): An in-the-weeds explanation of the components of the Urbit stack.
11+* [Azimuth](azimuth): An overview of Azimuth, the Urbit identity layer.
12+* [Galaxies, Stars, and Planets](galaxies-stars-and-planets): A guide to the Urbit network hierarchy.
13+* [Community Tutorials](community-tutorials): A collection of community guides for various pieces of the project.
concepts/azimuth.mdnew file+93
@@ -0,0 +1,93 @@
1++++
2+title = "Azimuth"
3+weight = 4
4+template = "doc.html"
5+description = "An explanation of the Urbit identity layer."
6++++
7+Azimuth is a general-purpose public-key infrastructure (PKI) on the Ethereum blockchain, used as a platform for Urbit identities that we call _points_. You need a point to use the Arvo network.
8+
9+The primary way to interact with Azimuth is through our [Bridge](https://github.com/urbit/bridge) application and the node libraries that it depends on, [azimuth-js](https://github.com/urbit/azimuth-js) and [urbit-key-generation](https://github.com/urbit/urbit-key-generation). Take a look at the source and play around, or see [Getting Started](/docs/getting-started).
10+
11+## Arvo vs. Azimuth
12+
13+Urbit is a project, not a single computer system. It has multiple components: Arvo, the operating system; and Azimuth, the identity system. Let's compare them.
14+
15+**Arvo** is an operating system that provides the software for a personal server. These personal servers together constitute the peer-to-peer Arvo network. To make this network work on the social level, Arvo is built to work with a system of scarce and immutable identities.
16+
17+**Azimuth** is the public-key infrastructure built to be such a system. A suite of smart-contracts on the Ethereum blockchain, Azimuth determines which Ethereum addresses own which Azimuth identities, called _points_. All point-related operations, such as transfers, are governed at this layer. But Azimuth isn't built strictly for Arvo -- it could be used as a generalized identity system for other projects.
18+
19+These otherwise-parallel systems meet when you want to connect to the Arvo network. Your Arvo personal server, called your _ship_, needs to be able to prove cryptographically that it is who it says it is. This proof comes in the form of a keyfile, derived from your point, that you use to start your ship.
20+
21+A metaphor might help illustrate the relationship between these two systems: the Arvo network is the neighborhood that you live in; Azimuth is the bank vault that stores the deed to your house.
22+
23+## Why Urbit Uses a Blockchain
24+
25+The Arvo network is composed of personal servers: instances of the Arvo operating system, called ships, that communicate as peers.
26+
27+Every ship has an associated secure identity, called a point, that it needs to connect to the network. Your point is your name and your network address. Each point has associated authentication and encryption keys for networking. Think of a point as an IP address, a domain name, and a PGP key-pair.
28+
29+There are a limited number of points and, as you might expect, scarcity gives points value. This means that bad actors – spammers, scammers, and malware-spreaders – can be made economically unviable. Points being immutable allows for reputation systems to be built on top, keeping the network friendly and giving users information to help them decide who to treat as a trusted peer.
30+
31+At the user level, having one identity for your digital life means that all the services that you trust recognize you. You no longer need to worry about managing dozens of different logins. When you're using Arvo, everything you do is "verified" in the sense that it links back to your point.
32+
33+But wait! We need some way to secure these identities. To that end, we have built the Azimuth identity layer on the Ethereum blockchain to determine which PKI. As mentioned above, it's separate from and parallel to the Arvo network.
34+
35+In theory, our ecosystem doesn't need a blockchain, because Urbit identities are more like real estate than currency: they change hands slowly. A low-friction, zero-trust solution to the double-spend problem isn't an economic necessity for transactions such as ours. So we could have the Arvo network run its own key-signing system. But, since Azimuth identities are valuable, you don't want to put them in an self-hosted PKI that isn't generally recognized as secure. Arvo is still young, we'd prefer to use an existing system for people to secure their property.
36+
37+Moving the Urbit land registry to Ethereum is an easy and obvious solution to this problem. We chose Ethereum over Bitcoin because the former is built for computation and the latter is not. We need a computational blockchain to enforce the specific rules of the Urbit identity registry.
38+
39+For more background on the decision to use the Ethereum blockchain, check out [these](https://urbit.org/posts/essays/urbit-and-the-blockchain/) [two](https://urbit.org/posts/essays/bootstrapping-urbit-from-ethereum/) posts.
40+
41+## The Urbit HD Wallet
42+
43+Owners of Azimuth points need safeguards that allow for the use of Urbit without jeopardizing cryptographic ownership of their assets. Toward this end, we created the **Urbit Hierarchical Deterministic (HD) Wallet** for the storage of points. The Urbit HD Wallet is not one key-pair, but a system of related key-pairs that each have distinct powers, from setting networking keys for communicating in the Arvo network to transferring ownership of points.
44+
45+The Urbit HD Wallet's derivation paths have a hierarchical structure, so that keys with different powers can be physically separated. A \"master ticket" can re-derive the entire wallet in case of loss. The encryption and authentication keys that points ships use to sign messages within the network are also derived from the wallet.
46+
47+Urbit HD wallets are composed of the following items, which are each assigned to their own individual Ethereum key-pairs.
48+
49+### Master Ticket
50+
51+Think of your master ticket like a very high-value password. The master ticket is the secret code from which all of your other keys are derived. Technically, your master ticket is seed entropy. You should never share it with anyone, and store it very securely. This ticket can derive all of your other keys: your ownership key and all of the related proxies.
52+
53+### Ownership Address
54+
55+An ownership address has all rights over the assets deeded to it. These rights are on-chain actions described and implemented in the Ecliptic, Azimuth's suite of governing smart-contracts.
56+
57+### Proxies
58+
59+Proxy addresses allow you to execute non-ownership related actions like spawning child points, voting, and setting networking keys without jeopardizing the keys you've designated with ownership rights. Setting proxy rights is optional, but it is recommended for on-chain actions you will execute more frequently.
60+
61+- **Management Proxy**
62+
63+ Can configure or set Arvo networking keys and conduct sponsorship related
64+ operations.
65+
66+- **Voting Proxy**
67+
68+ Galaxies only. Galaxies are the part of the galactic senate, and this means
69+ they can cast votes on new proposals including changes to the Ecliptic.
70+
71+- **Spawn Proxy**
72+
73+ For stars and galaxies only. Can create new child points.
74+
75+![](https://media.urbit.org/fora/proposals/UP-8.jpg)
76+
77+
78+Most Ethereum tokens use the ERC-20 standard for smart contracts. Azimuth points
79+are, however, essentially different from most Ethereum tokens, due to points not
80+being fungible. Since any two stars will handle social-networking realities in a
81+different way, they will carry a different reputation. Points are to houses as
82+tokens are to gold.
83+
84+The ERC-721 standard, having been made specifically to provide a smart-contract
85+interface for non-fungible assets, serves our needs well. This is the standard
86+that we use for deeding Azimuth points.
87+
88+Points, and all of their blockchain operations, are governed by the Ecliptic.
89+The Ecliptic is an Ethereum smart-contract that governs point state and the
90+ownership, spawn, management, and voting rights affiliated with your points.
91+
92+For the technical implementation details, take a look at Azimuth's
93+[Github repository](https://github.com/urbit/azimuth).
concepts/community-tutorials.mdnew file+15
@@ -0,0 +1,15 @@
1++++
2+title = "Community Tutorials"
3+weight = 9
4+template = "doc.html"
5+description = "A collection of unofficial but useful Urbit learning resources."
6++++
7+Here are some tutorials written by members of the Urbit community. Some are a little outdated, but they may still prove useful.
8+
9+- [Generators](https://github.com/joemfb/mardev/tree/master/docs/gen) by `~master-morzod`
10+- [Urbit by Doing](https://github.com/Fang-/Urbit-By-Doing) by `~palfun-foslup`
11+- [Learning Hoon](https://github.com/knubie/learning-hoon) by `@knubie`
12+- [A Nock Interpreter](https://jtobin.io/nock) by `~nidsut-tomdun`
13+- [Basic Hoonery](https://jtobin.io/basic-hoonery) by `~nidsut-tomdun`
14+
15+If you want to add something to the list, [shoot us an email](mailto:support@urbit.org) or make a pull request in the [docs repository](https://github.com/urbit/docs).
concepts/galaxies-stars-and-planets.mdnew file+34
@@ -0,0 +1,34 @@
1++++
2+title = "Galaxies, Stars, and Planets"
3+weight = 7
4+template = "doc.html"
5+description = "An explanation of the Urbit address-space hierarchy. "
6++++
7+
8+The current internet has no consistent system of identity. There are only quasi-identities such as IP addresses, Google accounts and email addresses, each able to be assumed and abandoned without much trouble. The result is a hostile social experience, since bad actors -- spammers, scammers, malware-spreaders, and harassers -- have an inexhaustible supply of places to hide.
9+
10+That's why we built a system for persistent identity called [Azimuth](@/docs/concepts/azimuth.md). Azimuth identities are called _points_, and you need one to use the Arvo network. Points are secure, since they are owned and controlled with key-pair the Ethereum blockchain, which Azimuth is built on top of.
11+
12+An Azimuth point is a pronounceable string like `~firbyr-napbes`. It means nothing, but it's easy to remember and say out loud. `~firbyr-napbes` is actually just a 32-bit number (`3.237.967.392`, to be exact) that we turn into a human-memorable string.
13+
14+Points come in three classes: **galaxies**, **stars**, and **planets**. You can tell what class a point is in by how long its name is. The address space grows like a family tree. Galaxies are 8-bit and have names like `~mul`. Galaxies can issue 16-bit stars (`~dacpyl`), which can themselves issue 32-bit planets (`~laptel-holfur`).
15+
16+Planets are intended for everyday use by an adult human, and there is a maximum of about 4.3 billion of them (2 to the 32nd power). Stars and galaxies, on the other hand, are meant to act as network infrastructure: in the Arvo network they provide P2P routing and distribute software updates.
17+
18+```
19+ Size Name Parent Object Example
20+ ----- ------ ------ ------ -------
21+ 2^8 galaxy ~ supernode ~zod
22+ 2^16 star galaxy supernode ~dozbud
23+ 2^32 planet star user ~tasfyn-partyv
24+ 2^64 moon planet device ~sigsam-nimbot-tasfyn-partyv
25+ 2^128 comet ~ bot ~racmus-mollen-fallyt-linpex--watres-sibbur-modlux-rinmex
26+```
27+
28+## Moons and Comets
29+
30+In addition to these three classes of Azimuth points, there two other kinds of Urbit identities, but they do _not_ use Azimuth.
31+
32+**Moons** are 64 bits, are issued by planets, and have names like `~doznec-salfun-naptul-habrys`. Moons are meant for connected devices: phones, smart TVs, digital thermostats. Moons are not independent, but are subordinated to their parent planet. To create new moon under your planet, follow [this guide](/docs/using/admin#moons).
33+
34+**Comets** are 128-bit points with no parents that can be launched by anyone. They are meant for bots. Being disposable and essentially unlimited, they will likely not be trusted by the others on the Arvo network. They have enormous names, like `~racmus-mollen-fallyt-linpex--watres-sibbur-modlux-rinmex`.
concepts/technical-overview.mdnew file+170
@@ -0,0 +1,170 @@
1++++
2+title = "Technical overview"
3+weight = 1
4+template = "doc.html"
5+description = "A more in-depth description of the entire Urbit stack."
6++++
7+Urbit is a clean-slate software stack designed to implement an encrypted P2P
8+network of general-purpose personal servers. Each server on this network is a
9+deterministic computer called an 'urbit' that runs on a Unix-based virtual
10+machine.
11+
12+The current Urbit stack includes (among other things):
13+
14+- Arvo: the functional operating system of each urbit, written in Hoon.
15+- Azimuth: the Urbit identity layer, built on the Ethereum blockchain.
16+- Hoon: a strictly typed functional programming language whose standard library
17+ includes a Hoon-to-Nock compiler.
18+- Nock: a low-level combinator language whose formal specification fits readably on a t-shirt.
19+- Vere: a Nock interpreter and Unix-based virtual machine that mediates between
20+ each urbit and the Unix software layer.
21+
22+## Anatomy of a personal server
23+
24+Your urbit is a deterministic computer in the sense that its state is a pure
25+function of its event history. Every event in this history is a
26+[transaction](https://en.wikipedia.org/wiki/Transaction_processing); your
27+urbit's state is effectively an [ACID database](https://en.wikipedia.org/wiki/ACID).
28+
29+Because each urbit is deterministic we can describe its role appropriately in
30+purely functional terms: it maps an input event and the old urbit state to a
31+list of output actions and the subsequent state. This is the Urbit transition
32+function.
33+
34+```
35+<input event, old state> -> <output actions, new state>
36+```
37+
38+For example, one input event could be a keystroke from the terminal, say
39+`[enter]` after having already typed `(add 2 2)`; and an output action could be
40+to print in the terminal window the resulting value of a computation performed
41+when the user hit `[enter]`, in this case `4`. The input event is stored in the
42+urbit's event history.
43+
44+Events always start from outside of your urbit, whether they're local to the
45+computer running the urbit (e.g., a keystroke in the terminal) or they originate
46+elsewhere (e.g., a packet received from another urbit). When an event is
47+processed, various parts of the urbit state can be modified before the resulting
48+list of output actions is returned.
49+
50+Can output actions from your urbit cause side-effects in the outside world?
51+The answer had better be "yes," because a personal server without side effects
52+isn't useful for much. In another sense the answer had better be "no," or else
53+there is a risk of losing functional purity; your urbit cannot _guarantee_ that
54+the side effects in question actually occur. What's the solution?
55+
56+Each urbit is
57+[sandboxed](https://en.wikipedia.org/wiki/Sandbox_%28computer_security%29) in a
58+virtual machine, Vere, which runs on Unix. Code running in your urbit cannot
59+make Unix system calls or otherwise directly affect the underlying platform.
60+Strictly speaking, internal urbit code can only change internal urbit state; it
61+has no way of sending events outside of its runtime environment. Functional
62+purity is preserved.
63+
64+In practical terms, however, you don't want your urbit to be an impotent
65+[brain in a vat](https://en.wikipedia.org/wiki/Brain_in_a_vat). That's why
66+Vere also serves as the intermediary between your urbit and Unix. Vere observes
67+the list of output events, and when external action is called for makes the
68+appropriate system calls itself. When external events relevant to your urbit
69+occur in the Unix layer, Vere encodes and delivers them as input events.
70+
71+### Arvo
72+
73+Arvo is a purely functional, [non-preemptive](https://en.wikipedia.org/wiki/Cooperative_multitasking)
74+OS, written in Hoon, that serves as the event manager of your urbit.
75+It can upgrade itself from over the network without downtime. The Arvo kernel
76+proper is quite simple -- it's only about 600 lines of code, excluding its
77+various modules.
78+
79+The Urbit transition function is implemented in Arvo. Upon being 'poked' by
80+Vere with the pair of `<input event, state>`, Arvo directs the event to the
81+appropriate OS module. The result of each Vere 'poke' is a pair of
82+`<output events, new state>`. Events are typed, and each has an explicit
83+call-stack structure indicating the event's source module in Arvo.
84+
85+Arvo modules are also called 'vanes'. Arvo's vanes are:
86+
87+- Ames: defines and implements Urbit's encrypted P2P network protocol, as well
88+ as Urbit's identity protocol.
89+- Behn: manages timer events for other vanes.
90+- Clay: global, version-controlled, and referentially-transparent file system.
91+- Dill: terminal driver.
92+- Eyre: HTTP web client and server.
93+- Ford: typed functional build system.
94+- Gall: application sandbox and manager.
95+ - Dojo (app): Shell and Hoon REPL.
96+ - Talk (app): Chat client.
97+
98+### Hoon
99+
100+Hoon is a strictly typed functional programming language that compiles itself
101+to Nock and is designed to support higher-order functional programming without
102+requiring knowledge of category theory or other advanced mathematics. Haskell
103+is fun but it isn't for everybody.
104+
105+Hoon aspires to a concrete, imperative feel. To discourage the creation of
106+write-only code, Hoon forbids user-level macros and uses ASCII digraphs instead
107+of keywords. The type system infers only forward and does not use unification,
108+but is not much weaker than Haskell's. The compiler and inference engine is
109+about 3000 lines of Hoon.
110+
111+### Nock
112+
113+Nock is a low-level [homoiconic](https://en.wikipedia.org/wiki/Homoiconicity)
114+combinator language. It's so simple that its [specification](@/docs/learn/nock/definition.md)
115+fits on a t-shirt. In some ways Nock resembles a nano-Lisp but its ambitions
116+are more narrow. Most Lisps are one-layer: a practical language is to be
117+created by extending a theoretically simple interpreter. The abstraction is
118+simple and the implementation is practical. Unfortunately it's far more difficult
119+to enforce both simplicity and practicality in an actual Lisp codebase. Hoon
120+and Nock are two layers: Hoon, the practical layer, compiles itself to Nock, the
121+simple layer. Your urbit runs in Vere, which includes a Nock interpreter, so it
122+can upgrade Hoon over the network without downtime.
123+
124+The Nock data model is quite simple. Every piece of data is a 'noun'. A noun
125+is an atom or a cell. An atom is any unsigned integer. A cell is an ordered
126+pair of nouns. Nouns are acyclic and expose no pointer equality test.
127+
128+### Vere
129+
130+Vere is the Nock runtime environment and Urbit VM. It's written in C, runs on
131+Unix, and is the intermediate layer between your urbit and Unix. As noted
132+earlier, Unix system calls are made by Vere, not Arvo; Vere must also encode
133+and deliver relevant external events to Arvo. Vere is also responsible for
134+implementing jets and maintaining the persistent state of each urbit.
135+
136+In principle, Vere keeps a comprehensive log of every event from the time you
137+initially booted your urbit. What happens if the physical machine loses power
138+and your urbit's state is 'lost' from memory? When your urbit restarts it will
139+replay its entire event history and totally recover its latest state from
140+scratch.
141+
142+In practice, event logs become large and unwieldy over time. Periodically a
143+snapshot of the permanent state is taken and the logs are pruned. You're still
144+able to rebuild your state in case of power outage, down to the last keystroke.
145+
146+Vere is not essential to the Urbit stack; one can imagine using Urbit on a
147+hypervisor, or even bare metal. One member of the community is even working on
148+an independent implementation of Urbit using Graal/Truffle on the JVM.
149+
150+The Urbit stack (compiler, standard library, kernel, modules, and applications,
151+but excluding Vere) is about 30,000 lines of Hoon. Urbit is patent-free and MIT
152+licensed.
153+
154+### Azimuth
155+
156+Azimuth is a general-purpose public-key infrastructure (PKI) on the Ethereum
157+blockchain, used as a decentralized ledger for Urbit identities that we call
158+**points**. Having a point is necessary to use the Urbit network, which makes it
159+important to have a neutral ledger to determine who owns what.
160+
161+Azimuth is not, however, part of the Urbit stack. Azimuth is a parallel system
162+that can be used as a generalized identity system for other projects. Azimuth
163+"touches" the Urbit ecosystem when a point is used to boot a virtual computer
164+on the Urbit network for the first time. When that happens, the point considered
165+**linked** to Azimuth and the point’s full powers are available for use. Once a
166+point is linked, it cannot be unlinked.
167+
168+A metaphor might make the relationship between these two systems to understand:
169+Azimuth is the bank vault that stores the deed to your house. The Urbit network
170+is the neighborhood that you live in.
getting-started/_index.mdnew file+37
@@ -0,0 +1,37 @@
1++++
2+title = "Getting Started"
3+weight = 1
4+sort_by = "weight"
5+template = "sections/docs/chapters.html"
6++++
7+
8+Welcome to Urbit, a personal server. Urbit isn't ready for serious use yet, but it's available to try out. If you have an Azimuth point, you can follow this step-by-step guide to get your point's _keyfile_, which you need to boot your ship. Then you can install Urbit and join the community.
9+
10+If you don't have an Azimuth point, you can always [create a comet](@/docs/using/creating-a-comet.md) to join the network before committing to a point, or [create a development ship](@/docs/using/creating-a-development-ship.md) and start using Urbit offline first.
11+
12+### [Step 1: Using Bridge](@/docs/getting-started/using-bridge.md)
13+
14+In order to join the Urbit network, you need an Azimuth point, which acts like an identity and a password for your Urbit ship. Bridge is our client for managing Azimuth points, and lets you get your keyfile and claim the point.
15+
16+### [Step 2: Installing Urbit](@/docs/getting-started/installing-urbit.md)
17+
18+The Urbit software is a command-line application that runs the Arvo operating system. This guide walks you through the installation process.
19+
20+### [Step 3: Booting a Ship](@/docs/getting-started/booting-a-ship.md)
21+
22+This guide teaches you how to get your ship operational and onto the Arvo network.
23+
24+### [Optional: Contributing](contributing)
25+
26+This document will get your started with contributing code or contributing to the community.
27+
28+## Terminology
29+
30+You've already encountered some new terminology on this page, and you'll encounter more as you proceed with this guide. Let's go over the basics:
31+
32+- Arvo is the name of the Urbit operating system.
33+- An instance of the Arvo operating system is called a _ship_.
34+- Ships communicate with one another over "the Arvo network."
35+- Azimuth is an Ethereum-based PKI used to give each ship a unique identity on the Arvo network.
36+- An Azimuth identity is called a _point_. You'll need a point to use the Arvo network.
37+- Urbit refers to the project as a whole, including Arvo, Azimuth, and other system components.
getting-started/booting-a-ship.mdnew file+108
@@ -0,0 +1,108 @@
1++++
2+title = "Booting a Ship"
3+weight = 3
4+template = "doc.html"
5++++
6+Now the rubber meets the road. You'll be booting your ship with the keyfile that you [downloaded from Bridge](@/docs/concepts/azimuth.md).
7+
8+Note that this document is only for booting a ship that uses the live Arvo network. If you just want to create an unnetworked ship for development purposes, read [this guide](@/docs/using/creating-a-development-ship.md) instead.
9+
10+## Step 1: Find Your Point's Name
11+
12+This will look something like `~lodleb-ritrul`. You can see the name of your point(s) when you log into your wallet using the Bridge client.
13+
14+![](https://media.urbit.org/site/bridge-0.png)
15+
16+## Step 2: Find the path to your keyfile
17+
18+Find the absolute path to the keyfile that you downloaded from Bridge. Copy it.
19+
20+## Step 3: Run the boot command
21+
22+Type `cd` in your terminal to return to your home directory. If you want to
23+store your ship somewhere besides your home directory, change the terminal's
24+working directory to the desired directory.
25+
26+Run the command below, except with `sample-planet` replaced by the name of your
27+Urbit identity, and `path/to/my-planet.key` replaced with the path to your
28+keyfile:
29+
30+```
31+./urbit -w sample-planet -k path/to/my-planet.key
32+```
33+
34+Or, if you'd prefer to copy your key in, you can run:
35+
36+```
37+./urbit -w sample-planet -G rAnDoMkEy
38+```
39+
40+Either command will create a directory called `sample-planet/` and begin
41+building your ship. It may take a few minutes.
42+
43+When your ship is finished booting, you will see the `~sample-planet:dojo>`
44+prompt. At that point, you should permanently erase your keyfile from your
45+machine.
46+
47+## Basic Operations
48+
49+Welcome to your ship! There's a few things you should do to become oriented.
50+
51+### The Dojo
52+
53+Let's try out the Dojo, the Arvo command line and Hoon REPL:
54+
55+```
56+~sample-planet:dojo> (add 2 2)
57+```
58+
59+Should produce:
60+
61+```
62+> (add 2 2)
63+4
64+```
65+
66+Good.
67+
68+### Mounting
69+
70+Your ship's filesystem being "mounted" means that its filesystem can be interacted with through Unix. This makes things much easier for you.
71+
72+The Arvo filesystem isn't mounted to Unix by default. Switch to the Dojo prompt and run:
73+
74+```
75+~sample-planet:dojo> |mount %
76+```
77+
78+This should produce:
79+
80+```
81+> |mount %
82+>=
83+```
84+
85+which indicates that the command was processed.
86+
87+`|mount %` will cause a `home/` directory to appear inside your _pier_ folder in Unix (the "pier" is our shorthand for the directory whose name corresponds to your Azimuth point). Once you've changed a file, `|commit %home` to synchronize changes to your pier.
88+
89+**Note:** Do not delete your pier. Doing so will make your ship unusable, because deleted piers normally cannot be recovered. The exception is during a network breach (a reset) -- in such a rare event, you must delete your pier to update your ship to the new era, and ships with previously deleted piers can be recovered.
90+
91+### Shutting Down and Restarting
92+
93+You can toggle between the Dojo and Talk (chat) prompts with `ctrl-x`. You can turn your ship off with `ctrl-d` from the Talk or Dojo prompts.
94+
95+To restart your ship, simply pass the name of your pier:
96+
97+```
98+./urbit some-planet
99+```
100+
101+### Using Landscape
102+
103+Landscape is the Urbit web interface, and it's the best way to interact with your ship. Chrome and Brave are the recommended browsers for using Landscape. To get onto Landscape:
104+
105+1. Start your ship. In the boot messages, look for a line that says something like `http: live (insecure, public) on 80`. The number given is the port that your ship is using.
106+2. If the port given is 80, simply type `localhost` into your browser's address bar. If the given port is a different number, such as `8080`, you would type `localhost:8080`.
107+3. Type `+code` into your ship's Dojo. Copy-paste the returned code into the field asking for it.
108+4. You're in! Now you can explore apps such as Chat for messages, Publish for blogging, and Weather.
getting-started/contributing.mdnew file+21
@@ -0,0 +1,21 @@
1++++
2+title = "Contributing"
3+weight = 5
4+template = "doc.html"
5+description = "A guide to getting involved with the Urbit project."
6++++
7+
8+We welcome submissions for improving our [code](https://github.com/urbit/urbit/) and [documentation](https://github.com/urbit/docs/) alike. If you're looking to get involved, there are a few things you can do to get started right away:
9+
10+- Join the [urbit-dev](https://groups.google.com/a/urbit.org/forum/#!forum/dev) mailing list
11+- [Apply to Hoon School](https://urbit.org/hoonschool/). We run a beginner course and an advanced course to teach the Hoon programming language and Urbit application development. Both courses are free, online, and asynchronous.
12+- Check out the "good contributor issues" tag in the [urbit](https://github.com/urbit/urbit/labels/good%20contributor%20issue) and [arvo](https://github.com/urbit/arvo/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+contributor+issue%22) Github repositories.
13+- Reach out to [support@urbit.org](mailto:support@urbit.org) to say hi and ask any questions you might have. We're always happy to try to point you in the right direction.
14+
15+Many contributors start by contributing to the [documentation](https://github.com/urbit/docs), [urbit.org](https://github.com/urbit/urbit.org), or [bridge](https://github.com/urbit/bridge) repositories. If you're not yet comfortable with Hoon, we recommend starting there.
16+
17+If you're just getting set up to work on the Urbit or Arvo code base for the first time, see our [Getting Started](@/docs/getting-started/_index.md) guide, then have a look at [CONTRIBUTING.md](https://github.com/urbit/urbit/blob/master/CONTRIBUTING.md) in the Urbit repository.
18+
19+## Code style
20+
21+Before contributing Hoon code, you should familiarize yourself with the [Hoon style guide](@/docs/learn/hoon/style.md). For a good example of idiomatic Hoon, see [Ford](https://github.com/urbit/urbit/blob/master/pkg/arvo/sys/vane/ford.hoon).
getting-started/installing-urbit.mdnew file+74
@@ -0,0 +1,74 @@
1++++
2+title = "Installing Urbit"
3+weight = 2
4+template = "doc.html"
5++++
6+
7+Arvo runs nicely on a Unix-like operating system – Ubuntu, Fedora, macOS, and FreeBSD, for example. If you're using Windows, you'll need to get one of the aforementioned systems. Don't worry: most of them are free. Let's get it onto your machine.
8+
9+But first, some terminology:
10+
11+- `vere` or `urbit`: the interpreter that runs when you run a command like `urbit` or `/bin/urbit` in your command line
12+- `arvo`: the deterministic OS that lives in a directory whose name matches your Azimuth point, ie `~famreb-todmec` lives in `/famreb-todmec`
13+
14+We have different installation instructions for different platforms. To install and run Arvo, run the commands that are listed for your operating system.
15+
16+On any platform, you can check your Arvo installation by running the `urbit` command. Installation was successful if you get a block of output that begins with the line below:
17+
18+```
19+Urbit: a personal server operating function
20+```
21+
22+## Instructions
23+
24+### macOS (Darwin)
25+
26+We provide static binaries for macOS. You can grab the latest stable release as follows:
27+
28+```
29+curl -O https://bootstrap.urbit.org/urbit-darwin-v0.8.2.tgz
30+tar xzf urbit-darwin-v0.8.2.tgz
31+./urbit
32+```
33+
34+### Linux (64-bit)
35+
36+We also provide static binaries for 64-bit Linux distributions (Ubuntu, Debian, Fedora, Arch, etc.). You can get the latest stable release similarly:
37+
38+```
39+curl -O https://bootstrap.urbit.org/urbit-linux64-v0.8.2.tgz
40+tar xzf urbit-linux64-v0.8.2.tgz
41+./urbit
42+```
43+
44+To access your Urbit via HTTP on port 80 on Ubuntu, you may need to run the following:
45+
46+```
47+sudo apt-get install libcap2-bin
48+sudo setcap 'cap_net_bind_service=+ep' /path/to/urbit
49+```
50+
51+### Other
52+
53+We maintain a [Nix](https://nixos.org/nix) derivation for Urbit in [nixpkgs](https://github.com/NixOS/nixpkgs), however we're still in the process of updating it to `v0.8.2`. Once available, you will be able to install and launch it like so:
54+
55+```
56+nix-env -i urbit
57+urbit
58+```
59+
60+## Booting a Ship
61+
62+One you've completed your installation, you can continue on to the instructions for [booting your ship](@/docs/getting-started/booting-a-ship.md) to get on the Arvo network.
63+
64+Or, if you want to try testing and writing code, check out the guide to [getting an unnetworked development ship](/docs/using/creating-a-development-ship).
65+
66+## Set Up Swap
67+
68+If you're running Urbit in the cloud on a small instance, you may need to additionally configure swap space. If you're not, you can safely ignore this section.
69+
70+Urbit wants to map 2GB of memory when it boots up. We won’t necessarily use all this memory, we just want to see it. On a normal modern PC or Mac, or on a large cloud virtual machine, this is not an issue. On some small cloud virtual machines (Amazon or Digital Ocean), the default memory configuration is smaller than this, and you need to manually configure a swapfile.
71+
72+Digital Ocean has a post on adding swap [here](https://www.digitalocean.com/community/tutorials/how-to-add-swap-space-on-ubuntu-16-04). For Amazon there’s a StackOverflow thread [here](https://stackoverflow.com/questions/17173972/how-do-you-add-swap-to-an-ec2-instance).
73+
74+Don’t spend a lot of time tweaking these settings; the simplest thing is fine.
getting-started/using-bridge.mdnew file+70
@@ -0,0 +1,70 @@
1++++
2+title = "Using Bridge"
3+weight = 1
4+template = "doc.html"
5++++
6+
7+[Bridge](https://github.com/urbit/bridge) is the application we built for interacting with [Azimuth](@/docs/concepts/azimuth.md), the Urbit PKI, and managing your Azimuth identities, also known as _points_. Importantly, Bridge also allows you to generate a keyfile that you will need to boot your ship so that it can use the Arvo network.
8+
9+This guide assumes that you own an Azimuth identity, or that you have found someone to send an Azimuth identity to your Ethereum address and are looking to claim it.
10+
11+## Online Bridge
12+
13+To connect to Bridge, type `https://bridge.urbit.org` into your browser, and enter the your identity's credentials in the appropriate fields. If you were invited to claim an Azimuth identity, it's very likely that you received an email that would direct you to Bridge, and you can simply follow the hyperlink in that email.
14+
15+Once you arrive Proceed through the steps presented to you. You'll eventually arrive at a page with a few choices: `Invite`, `Admin`, and `Boot Arvo`. `Admin` is the only option that you're interested in right now; click on it. On the "Admin" page, click the `Download Arvo Keyfile` button. Once you have downloaded the keyfile, you can exit Bridge ands proceed to the guide to [installing Arvo](@/docs/getting-started/installing-urbit.md).
16+
17+## Offline Bridge
18+
19+Alternatively, Bridge can be run locally. It's more complicated, but we recommend this option for managing sufficiently valuable assets, such as several stars or more. To install local Bridge, navigate to the [release page](https://github.com/urbit/bridge/releases/) on GitHub. Download the `.zip` file of the latest version. After you download it, follow the instructions below.
20+
21+### Installation
22+
23+To use Bridge:
24+
25++ Unzip the `.zip` file that you downloaded (`bridge-$version.zip`).
26++ Open up your command line interface (Terminal on OSX, Command Prompt on Windows).
27++ Navigate to the `bridge-$version` directory, where `$version` is the appropriate version number.
28++ Run this command: `python3 -m http.server 5000 --bind 127.0.0.1`
29++ You can then use the Bridge app by navigating to `http://localhost:5000` in your internet browser.
30+
31+**Note:** Bridge allows you both make reads and writes to the Ethereum blockchain. Writing to the blockchain, such as changing your networking keys, will incur a transaction cost that will require you to have some ETH in your address.
32+
33+Once the program is running in your browser, go through each step presented according to what kind of wallet you have. There are a few login options you'll be presented with. A notable option is **Urbit Master Ticket**. This is for those who used our Wallet Generator software. If you bought points from an Urbit sale and then used the Wallet Generator, your networking keys will be set for you. All other login options will result in you needing to set your own networking keys.
34+
35+### Accept Your Transfer
36+
37+If you were given points by Tlon, you likely already fully own them. But if someone sent you a point, then you will first need to use Bridge to accept that transfer.
38+
39+After you access your Ethereum address, if a point was sent to that address,
40+you'll come to a page that has an `Incoming Transfers` header, under which is
41+a graphic. Click the `Details ->` link under that graphic.
42+
43+Now you'll be on the management page of your point. The transfer isn't completed
44+yet, so click `Accept incoming transfer`. Then check both boxes and and click
45+their associated `Sign Transaction` and `Send Transaction` buttons.
46+
47+If you already own a point, then click on the `Details ->` under your sigil in the
48+`Your Points` section.
49+
50+### Set Your Networking Keys
51+
52+If you just accepted a point, you'll be returned to your point screen. Notice that that links and buttons are now clickable. You now own this point!
53+
54+Click the link that says `Set network keys`. The field that is presented in the resulting page expects a 32-byte hexadecimal string. If it's filled already, no action is required. If this is empty, you will need to generate such a string. You can generate this data any way you please, but in the terminal on MacOS or Linux, you can write
55+
56+```
57+hexdump -n 32 -e '4/4 "%08X"' /dev/random
58+```
59+
60+and use the result.
61+
62+It should be noted that setting your network keys is an event on the Ethereum network, and will therefore cost a trivial, but non-zero, amount of [gas](https://github.com/ethereum/wiki/wiki/Design-Rationale#gas-and-fees) to complete.
63+
64+### Generate Your Keyfile
65+
66+From the detail page associated with your point, click the `Generate Arvo Keyfile` link and you'll be taken to a page with a field titled `Network seed`. This field should already be filled in, and should match the hexadecimal string that you entered in the previous step. If its not filled in or does not match, fill it in with the correct string.
67+
68+Click `Generate ->`, which will download a keyfile onto your machine.
69+
70+With that keyfile in hand, you can now exit Bridge, and continue to the guide to [installing Arvo](@/docs/getting-started/installing-urbit.md).
learn/_index.mdnew file+27
@@ -0,0 +1,27 @@
1++++
2+title = "Learn"
3+weight = 4
4+sort_by = "weight"
5+template = "sections/docs/chapters.html"
6++++
7+Tutorials and explanations for all the components of Urbit.
8+
9+## [Arvo](@/docs/learn/arvo/_index.md)
10+
11+Arvo is a clean-slate system software stack defined as a deterministic computer. An encrypted P2P network, %ames, runs on a functional operating system, Arvo, written in a strict, typed functional language, Hoon, which compiles itself to a combinator interpreter, Nock, whose spec gzips to 340 bytes.
12+
13+## [Hoon](@/docs/learn/hoon/_index.md)
14+
15+Hoon is a high-level, statically typed, functional programming language, custom-designed for use with Urbit. For a functional language it has a surprisingly imperative style, and mastering it doesn't require knowing any advanced mathematics.
16+
17+The [Hoon Tutorial](@/docs/learn/hoon/hoon-tutorial/_index.md) is the best place to start if you want to learn Urbit.
18+
19+## [Nock](@/docs/learn/nock/_index.md)
20+
21+Nock is the low-level functional programming language that is interpreted by Vere. You don't need to know Nock to write Hoon, or even to work on most parts of Vere. But if you want to understand the foundations of Urbit and are mathematically-inclined, dive right in.
22+
23+## [Vere](@/docs/learn/vere/_index.md)
24+
25+The Nock runtime system, written in C.
26+
27+Keep reading if you're planning to work on the Urbit interpreter, you're a language implementation geek, or you don't really understand anything until you've seen the actual structs.
arvo/_index.md → learn/arvo/_index.mdrenamed

The content is the same.

arvo/ames.md → learn/arvo/ames.mdrenamed

The content is the same.

arvo/behn.md → learn/arvo/behn.mdrenamed

The content is the same.

arvo/clay.md → learn/arvo/clay.mdrenamed

The content is the same.

arvo/dill.md → learn/arvo/dill.mdrenamed

The content is the same.

arvo/eyre.md → learn/arvo/eyre.mdrenamed

The content is the same.

arvo/ford.md → learn/arvo/ford.mdrenamed

The content is the same.

arvo/gall.md → learn/arvo/gall.mdrenamed

The content is the same.

arvo/glossary.md → learn/arvo/glossary.mdrenamed

The content is the same.

arvo/hall.md → learn/arvo/hall.mdrenamed

The content is the same.

azimuth/azimuth.md → learn/azimuth.mdrenamed

The content is the same.

hoon/_index.md → learn/hoon/_index.mdrenamed

The content is the same.

hoon/hoon-tutorial/_index.md → learn/hoon/hoon-tutorial/_index.mdrenamed

The content is the same.

hoon/hoon-tutorial/ackermann.md → learn/hoon/hoon-tutorial/ackermann.mdrenamed

The content is the same.

hoon/hoon-tutorial/arms-and-cores.md → learn/hoon/hoon-tutorial/arms-and-cores.mdrenamed

The content is the same.

hoon/hoon-tutorial/atoms-auras-and-simple-cell-types.md → learn/hoon/hoon-tutorial/atoms-auras-and-simple-cell-types.mdrenamed

The content is the same.

hoon/hoon-tutorial/bank-account.md → learn/hoon/hoon-tutorial/bank-account.mdrenamed

The content is the same.

hoon/hoon-tutorial/caesar.md → learn/hoon/hoon-tutorial/caesar.mdrenamed

The content is the same.

hoon/hoon-tutorial/conditionals.md → learn/hoon/hoon-tutorial/conditionals.mdrenamed

The content is the same.

hoon/hoon-tutorial/doors.md → learn/hoon/hoon-tutorial/doors.mdrenamed

The content is the same.

hoon/hoon-tutorial/egg-timer.md → learn/hoon/hoon-tutorial/egg-timer.mdrenamed

The content is the same.

hoon/hoon-tutorial/fibonacci.md → learn/hoon/hoon-tutorial/fibonacci.mdrenamed

The content is the same.

hoon/hoon-tutorial/gall.md → learn/hoon/hoon-tutorial/gall.mdrenamed

The content is the same.

hoon/hoon-tutorial/gates.md → learn/hoon/hoon-tutorial/gates.mdrenamed

The content is the same.

hoon/hoon-tutorial/generators.md → learn/hoon/hoon-tutorial/generators.mdrenamed

The content is the same.

hoon/hoon-tutorial/hoon-syntax.md → learn/hoon/hoon-tutorial/hoon-syntax.mdrenamed

The content is the same.

hoon/hoon-tutorial/iron-polymorphism.md → learn/hoon/hoon-tutorial/iron-polymorphism.mdrenamed

The content is the same.

hoon/hoon-tutorial/lead-polymorphism.md → learn/hoon/hoon-tutorial/lead-polymorphism.mdrenamed

The content is the same.

hoon/hoon-tutorial/libraries.md → learn/hoon/hoon-tutorial/libraries.mdrenamed

The content is the same.

hoon/hoon-tutorial/list-of-numbers.md → learn/hoon/hoon-tutorial/list-of-numbers.mdrenamed

The content is the same.

hoon/hoon-tutorial/lists.md → learn/hoon/hoon-tutorial/lists.mdrenamed

The content is the same.

hoon/hoon-tutorial/molds.md → learn/hoon/hoon-tutorial/molds.mdrenamed

The content is the same.

hoon/hoon-tutorial/nouns.md → learn/hoon/hoon-tutorial/nouns.mdrenamed

The content is the same.

hoon/hoon-tutorial/recursion.md → learn/hoon/hoon-tutorial/recursion.mdrenamed

The content is the same.

hoon/hoon-tutorial/setup.md → learn/hoon/hoon-tutorial/setup.mdrenamed

The content is the same.

hoon/hoon-tutorial/structures-and-complex-types.md → learn/hoon/hoon-tutorial/structures-and-complex-types.mdrenamed

The content is the same.

hoon/hoon-tutorial/the-subject-and-its-legs.md → learn/hoon/hoon-tutorial/the-subject-and-its-legs.mdrenamed

The content is the same.

hoon/hoon-tutorial/trees-sets-and-maps.md → learn/hoon/hoon-tutorial/trees-sets-and-maps.mdrenamed

The content is the same.

hoon/hoon-tutorial/type-checking-and-type-inference.md → learn/hoon/hoon-tutorial/type-checking-and-type-inference.mdrenamed

The content is the same.

hoon/hoon-tutorial/type-polymorphism.md → learn/hoon/hoon-tutorial/type-polymorphism.mdrenamed

The content is the same.

hoon/style.md → learn/hoon/style.mdrenamed

The content is the same.

hoon/workbook/_index.md → learn/hoon/workbook/_index.mdrenamed

The content is the same.

hoon/workbook/bomb.md → learn/hoon/workbook/bomb.mdrenamed

The content is the same.

hoon/workbook/digits.md → learn/hoon/workbook/digits.mdrenamed

The content is the same.

hoon/workbook/eightball.md → learn/hoon/workbook/eightball.mdrenamed

The content is the same.

hoon/workbook/traffic-light.md → learn/hoon/workbook/traffic-light.mdrenamed

The content is the same.

nock/_index.md → learn/nock/_index.mdrenamed

The content is the same.

nock/definition.md → learn/nock/definition.mdrenamed

The content is the same.

nock/example.md → learn/nock/example.mdrenamed

The content is the same.

nock/explanation.md → learn/nock/explanation.mdrenamed

The content is the same.

nock/implementations.md → learn/nock/implementations.mdrenamed

The content is the same.

vere/_index.md → learn/vere/_index.mdrenamed

The content is the same.

vere/api.md → learn/vere/api.mdrenamed

The content is the same.

vere/c.md → learn/vere/c.mdrenamed

The content is the same.

vere/jetting.md → learn/vere/jetting.mdrenamed

The content is the same.

vere/nouns.md → learn/vere/nouns.mdrenamed

The content is the same.

vere/runtime.md → learn/vere/runtime.mdrenamed

The content is the same.

reference/_index.mdnew file+29
@@ -0,0 +1,29 @@
1++++
2+title = "Reference"
3+weight = 5
4+sort_by = "weight"
5+template = "sections/docs/chapters.html"
6++++
7+Various reference documents are stored here, particularly for Hoon, but also for other parts of the system.
8+
9+## [The Arvo Glossary](@/docs/reference/arvo-glossary.md)
10+
11+Urbit is known for introducing a great deal of new terminology. The glossary will
12+help demystify our jargon.
13+
14+## [The Cheat Sheet](@/docs/reference/cheat-sheet.md)
15+
16+The cheat sheet is a compact document for looking up Hoon runes.
17+
18+## [Hoon Expressions](@/docs/reference/hoon-expressions/_index.md)
19+
20+This section contains more comprehensive reference materials for Hoon runes and other expressions, describing their exact
21+semantics and syntax.
22+
23+## [Standard Library](@/docs/reference/library/_index.md)
24+
25+This section documents the gates and mold-builders of the Hoon standard library.
26+
27+## [Troubleshooting](@/docs/reference/troubleshooting.md)
28+
29+When your Hoon produces an error, check what it means here.
reference/arvo-glossary.mdnew file+850
@@ -0,0 +1,850 @@
1++++
2+title = "Glossary"
3+weight = 3
4+template = "doc.html"
5+aliases = ["docs/reference/arvo-glossary/"]
6++++
7+
8+Urbit is renowned for its exotic terminology. Here's a simple overview
9+from the strange words within.
10+
11+As Dijkstra put it: "The purpose of abstraction is not to be vague, but
12+to create a new semantic level in which one can be absolutely precise."
13+
14+This glossary only covers terms the Arvo side of the project. You can find the
15+Azimuth glossary [here](../azimuth/glossary)
16+
17+### application
18+
19+Also known as an “app,” an _application_ is a Hoon program that can hold state.
20+
21+### arm
22+
23+An _arm_ is a named, functionally-computed attribute of a [core](#core).
24+
25+The [hoon](#a-hoon) of each arm is compiled to a Nock formula, with the
26+enclosing [core](#core) itself as the subject.
27+
28+There are two kinds of arms: _dry_ and _wet_. Most arms are
29+dry.
30+
31+#### dry
32+
33+ normal, `++`, polymorphic by means of _variance_
34+
35+ For a dry arm, we ask: is the new payload compatible with the old
36+ payload (against which the core was compiled)?
37+
38+#### wet
39+
40+ unusual, `+-`, polymorphic by means of _genericity_
41+
42+ A wet arm uses the hoon as a macro. We create a new type analysis
43+ path, which works as if we expanded the callee with the caller's
44+ context.
45+
46+_See [advanced types](/docs/hoon/hoon-expressions/advanced/)_.
47+
48+
49+
50+### Arvo
51+
52+The Urbit operating system and kernel. Arvo's state is a pure function of its
53+event log, and it serves as the Urbit event manager. It contains vanes, which are
54+kernel modules that perform essential system operations. Arvo itself can only
55+deal with one file at a time. For more, it relies on Ford, the build-system
56+vane.
57+
58+Arvo being purely functional means that the it is a function that is:
59+
60+`(state, event) → (state, effects)`
61+
62+Arvo coordinates and reloads vanes. It can be thought of as a traffic-director.
63+Any vane needs to go through Arvo before reaching another vane. Events and
64+their effects happen like so:
65+
66+`Unix event → vere (the virtual machine that runs Urbit) → Arvo → vane → Arvo`
67+
68+Arvo is located in `/home/sys/arvo.hoon` within your urbit.
69+
70+More in-depth information on Arvo can be found
71+[`here`](@/docs/arvo/_index.md).
72+
73+Below are Arvo modules, which are called "vanes".
74+
75+#### Ames
76+
77+ The networking vane. Ames handles all things UDP. Here live the protocols for
78+ discovering and interacting with other urbits. It’s also the name for the Urbit
79+ network itself. All communication is signed and encrypted.
80+
81+ Ames is located in `/home/sys/vane/ames.hoon` within your urbit.
82+
83+ More in-depth information on Ames can be found
84+ [`here`](@/docs/arvo/ames.md).
85+
86+#### Behn
87+
88+ The timing vane. Behn allows for applications to schedule events, which are
89+ managed in a simple priority queue. For example, Clay, the Urbit filesystem,
90+ uses Behn to keep track of time-specific file requests. Eyre, the Urbit web
91+ vane, uses Behn for timing-out HTTP sessions.
92+
93+ Behn is located in `/home/sys/vane/behn.hoon` within your urbit.
94+
95+#### Clay
96+
97+ The filesystem and typed revision-control vane. Think of Clay as a
98+ continuously synced git. It handles file-change events and maps them from Urbit
99+ to Unix and vice versa.
100+
101+ A common way to use it is to create a pier, a directory that exists in and is
102+ visible in Unix.
103+
104+ Clay is located at `/home/sys/vane/clay.hoon` within your urbit.
105+
106+ Basic information on using Clay can be found
107+ [`here`](@/operations.md). An in-depth explanation
108+ of the architecture can be found
109+ [`here`](@/docs/arvo/clay.md).
110+
111+#### Dill
112+
113+ The terminal-driver vane. You run your urbit in your Unix terminal, and
114+ Unix sends every event -- such as a keystroke or a change in the dimensions of
115+ the terminal window -- to be handled by Dill. Dill acts as an intermediary for
116+ anything that uses keyboard events. This is why there’s some input lag in
117+ Urbit’s command-line interface. (Optimization will come later!)
118+
119+ A keyboard event's journey from Unix to Dojo, the Urbit shell, can be imagined
120+ as diagrammed below:
121+ ```
122+ Keystroke in Unix -> Vere (virtual machine) -> Arvo -> Dill -> the Dojo
123+ ```
124+
125+ Dill is located at `/home/sys/vane/dill.hoon` within your urbit.
126+
127+ More in-depth information on Dill can be found
128+ [`here`](@/docs/arvo/dill.md).
129+
130+#### Eyre
131+
132+ The web-server vane. Anything HTTP-related lives here. Unix sends HTTP messages
133+ though to Eyre, and Eyre produces HTTP messages in response.
134+
135+ In general, apps and vanes do not call Eyre; rather, Eyre calls apps and vanes.
136+ Eyre uses Ford and Gall to functionally publish pages and facilitate
137+ communication with apps.
138+
139+ Eyre is located at `/home/sys/vane/eyre.hoon` within your urbit.
140+
141+ More in-depth information on Eyre can be found
142+ [`here`](@/docs/arvo/eyre.md).
143+
144+#### Ford
145+
146+ The build-system vane. Ford is capable of sequencing generic asynchronous
147+ computations. Its uses include linking source files into programs, assembling
148+ live-updating websites, and performing file-type conversions.
149+
150+ Ford neither accepts Unix events nor produces Unix effects. It exists
151+ entirely for the benefit of Urbit applications and other vanes, in particular
152+ Gall.
153+
154+ Ford is located at `/home/sys/vane/ford.hoon` within your urbit.
155+
156+ More in-depth information on Ford can be found
157+ [`here`](@/docs/arvo/ford.md).
158+
159+#### Gall
160+
161+ The application-management vane. Userspace apps -- daemons, really -- are
162+ started, stopped, and sandboxed by Gall. Gall provides developers with a
163+ consistent interface for hooking their app up to the operating system. It allows
164+ applications and other vanes to send messages to applications and subscribe to
165+ data streams. Messages coming into Gall are routed to the intended application,
166+ and the response comes back along the same route. If the intended target is on
167+ another ship, Gall will route it, behind the scenes, through Ames to the other
168+ ship.
169+
170+ Gall is located at `/home/sys/vane/gall.hoon` within your urbit.
171+
172+ More in-depth information on Gall can be found
173+ [`here`](@/docs/arvo/gall.md).
174+
175+### atom
176+
177+An atom is any natural number, including zero. The atom is the most basic data
178+type in [Nock](#nock) and [Hoon](#hoon). A Hoon atom type describes a Nock
179+atom with two additional pieces of metadata: an [_aura_](#aura), and an
180+optional constant.
181+
182+An atom type is _warm_ or _cold_ based on whether the constant exists.
183+
184+
185+#### warm
186+
187+ If the constant is `~` (null), any atom is in the type.
188+
189+#### cold
190+
191+ If the constant is `[~ atom]`, its only legal value is `atom`.
192+
193+_See [basic types](@/docs/hoon/hoon-expressions/basic.md)_
194+
195+### aura
196+
197+An aura is a soft atom type. They appear as strings beginning with `@`. Auras
198+represent the structure of an atom, print format, or other semantics. Its
199+constraints on the value of an atom aren't enforced in any way.
200+
201+You can cast something to an aura, like a decimal, and get back its hexademical.
202+For example:
203+
204+```
205+ > =a `@`29
206+ > ^- @ux a
207+ 0x1d
208+```
209+
210+Auras are an advisory type system. You can go up or down, but not sideways in
211+the hierarchy. `@t` and `@` can each be cast to the other, but @t can’t be cast
212+to `@u`, for example, without first being cast to the empty aura `@`.
213+
214+For example
215+
216+```
217+ > ^- @ 'c' :: 'c' is of the aura @t
218+ 99
219+
220+ > ^- @u 'c'
221+ ! exit
222+```
223+
224+Here is a non-exhaustive list of auras:
225+
226+```
227+Aura Meaning Example Literal Syntax
228+-------------------------------------------------------------------------
229+@d date
230+ @da absolute date ~2018.5.14..22.31.46..1435
231+@n nil ~
232+@p phonemic string (ship name) ~sorreg-namtyv
233+@r IEEE floating-point
234+ @rd double precision (64 bits) .~6.02214085774e23
235+ @rh half precision (16 bits) .~~3.14
236+@s signed integer, sign-bit low
237+ @sb signed binary --0b11.1000
238+ @sd signed decimal --1.000.056
239+ @sx signed hexadecimal -0x5f5.e138
240+@t UTF-8 text (cord) 'howdy'
241+ @ta ASCII text (knot) ~.howdy
242+ @tas ASCII text symbol (term) %howdy
243+@u unsigned integer
244+ @ub unsigned binary 0b11.1000
245+ @ud unsigned decimal 1.000.056
246+ @ux unsigned hexadecimal 0x5f5.e138
247+```
248+
249+You can find the list of all auras [here](@/docs/hoon/hoon-expressions/rune/constants.md).
250+
251+### blocksize
252+
253+Blocksize is the power-of-two bitwidth of an atom. So, an atom with a blocksize
254+of `3` has a bitwidth of `2^3`, which is 8. A bitwidth of 8, in turn, can
255+represent `2^8` values, or 256.
256+
257+### cast
258+
259+To cast is to put a Hoon expression through the compiler’s type-checker to test
260+whether the expression is guaranteed to evaluate to a product that falls within
261+the desired type. If the expression is not guaranteed to behave in this way,
262+then the compiler will halt with a nest-fail crash. Proper Hoon code will
263+include a cast for the product type of each gate.
264+
265+The cast rune is `^-` (pronounced "ket-hep"). So, to cast to a list of atoms,
266+we write `^- (list @)`. The irregular form of that expression is ``(list @)``.
267+
268+### cell
269+
270+In Nock and Hoon, a _cell_ is an ordered pair of [nouns](#noun).
271+
272+Syntax: `[a b]`.
273+
274+Cells orient to the right; for example, the noun [2 6 14 15] is short for
275+[2 [6 [14 15]]].
276+
277+
278+### clam
279+
280+A clam is the use of a structure as a gate. Usually used to verify marks from
281+other urbits.
282+
283+```
284+ > ((list @t) [97 98 ~])
285+ <|a b|>
286+```
287+
288+### cord
289+
290+In Hoon, `cord` is an aura for representing atoms as strings. UTF-8,
291+least-significant bit first. Represented as the aura `@t`.
292+
293+```
294+ > `@t`478.560.413.032
295+ 'hello'
296+```
297+
298+### core
299+
300+A _core_ is a [cell](#nock-cell) of `[code data]`, where we call the
301+code head the _battery_ and the data tail the _payload_. All code-data
302+structures in normal languages (functions, objects, modules, etc.)
303+translate to cores in Hoon.
304+
305+#### battery
306+
307+ The code-containing head of a core.
308+
309+#### payload
310+
311+ The data-containing tail of a core.
312+
313+_See [basic types](@/docs/hoon/hoon-expressions/basic.md)._
314+
315+### Dojo
316+
317+The Dojo is the Urbit shell; the command line where you run programs,
318+expressions, and system commands. It’s a CLI that is encountered right when
319+an urbit is started for the first time. It is somewhat analogous to Bash, the
320+Unix terminal, and more analogous to a Hoon REPL.
321+
322+You’ll notice that many things can’t be written here; this is normal. The Dojo
323+enforces syntactical correctness right at the command line. Strings that can’t
324+be continued into a valid expression are automatically trimmed back to something
325+that can be. Some syntactically invalid expressions can be completed, but the
326+Dojo will prevent them from being entered as a command. You can play around
327+with this functionality learn what syntax is kosher.
328+
329+### desk
330+
331+A desk is independently revision-controlled branch of urbit filesystem.
332+
333+_See [filesystem](@/operations.md#filesystem) and [Clay](@/docs/arvo/clay.md)._
334+
335+### duct
336+
337+A duct is an Arvo-level call stack. At the beginning of every duct is a Unix
338+event, such as a keystroke, network packet, timer event, or file change.
339+
340+A duct is a `list` of `wire`s. A wire is itself a `list` of `knot`s. A `knot`
341+is, in turn, a knot.
342+
343+### face
344+
345+A _face_ is the Hoon analog to what is a variable name in most other
346+programming languages. Faces are metadata labels for legs, allowing us to
347+address parts. Because there is no metadata in Nock, faces cannot exist in Nock.
348+
349+```
350+ > a=2
351+ a=2
352+```
353+
354+In the above example, `a` is the face and `2` is the value.
355+
356+Hoon has no scope or symbol-table; there is only the subject. To "declare" a
357+"variable" is to construct a new subject: `[name=value old-subject]`.
358+
359+_See [advanced types](@/docs/hoon/hoon-expressions/advanced.md)_.
360+
361+
362+### flag
363+
364+A `flag` is Hoon's version of a boolean. `0` (`%.y`) is _yes_, `1` (`%.n`) is
365+_no_.
366+
367+### gate
368+
369+A _gate_ is a [core](#core) with one [arm](#arm) -- Hoon's closest
370+analog to a function. To call a gate on an argument, replace the sample
371+(at [tree address](@/docs/hoon/hoon-expressions/limb/limb.md) `+6`
372+in the core) with the argument, and then compute the arm.
373+
374+The payload of a gate has a shape of `[sample context]`.
375+
376+#### sample
377+
378+ The argument tuple.
379+
380+#### context
381+
382+ The subject in which the gate was defined.
383+
384+_See [basic types](@/docs/hoon/hoon-expressions/basic.md),
385+[`%-` ("cenhep")](@/docs/hoon/hoon-expressions/rune/cen.md#cenhep) (the
386+[rune](#rune) for calling a `gate`)._
387+
388+### generator
389+
390+A _generator_ is like a limited Hoon script: it’s a shell command that produces
391+a value before disappearing. Generators take an input [noun](#noun) (a value)
392+and produce an output `noun` by performing calculations on its arguments,
393+prompting for input, or making HTTP requests.
394+
395+You need a `bar` rune like `|=` in your generator, because a generator is
396+essentially a function that you’re calling.
397+
398+Generators, unlike [apps](#application), hold no state. They are pure,
399+stateless functions, and they cannot send [moves](#move). Because of this,
400+generators are have a more narrow use than apps. Among the non-trivial uses of
401+a a generator is moving data into apps -- they’re the backbone of Urbit’s
402+information pipeline.
403+
404+Generators are run from the `/gen` directory of your current desk. For example,
405+to run a generator named `whatever.hoon`, you would type `> +whatever` in the
406+[Dojo](@/operations.md#using-the-shell).
407+
408+### glyph
409+
410+A _glyph_ is a single, non-alphanumeric ASCII character. Each glyph has its own
411+monosyllabic name, which allows the efficient communication of Hoon-related
412+information in speech. [`Runes`](#rune) are composed of two glyphs.
413+Below is a complete list of glyphs with their associated pronunciations.
414+
415+```
416+ace [1 space] gal < pal (
417+bar | gap [>1 space, nl] par )
418+bas \ gar > sel [
419+buc $ hax # mic ;
420+cab _ hep - ser ]
421+cen % kel { sig ~
422+col : ker } soq '
423+com , ket ^ tar *
424+doq " lus + tic `
425+dot . pam & tis =
426+fas / pat @ wut ?
427+zap !
428+```
429+
430+### Hall
431+
432+_Hall_ is the Urbit communication back-end. It’s a messaging bus that can work
433+with clients of all sorts. [`:talk`](#talk), the built-in chat client, is one
434+such app that uses Hall.
435+
436+_More information on Hall can be found [here](@/docs/arvo/hall.md)._
437+
438+#### circle
439+
440+ A circle is the “audience” of your messages -- who can receive them. It can be
441+ thought of as a chat channel, but this is a little too narrow. More
442+ specifically, it’s a named collection of messages created by and hosted on a
443+ ship’s Hall, usually represented as `~ship-name/circle-name`. On Talk,
444+ Urbit’s built-in chat front-end, the first circle that you will likely
445+ encounter is `~dopzod/urbit-help`.
446+
447+### Hood
448+
449+_Hood_ orchestrates many of the Urbit initialization systems necessary
450+for boot.
451+
452+### Hoon
453+
454+Hoon is a strict, higher-order typed functional language that compiles itself
455+to Nock.
456+
457+The Hoon source file is located in `/home/sys/hoon.hoon` within your urbit.
458+
459+_More information can be found in the [hoon](@/docs/hoon/_index.md) section._
460+
461+#### Mint
462+
463+ _Mint_ is the Hoon compiler function. Mint takes the subject type and the
464+ expression source (a [hoon](#a-hoon), for example) and produces the product
465+ type and nock formula. So [type hoon] is mapped to [type nock].
466+
467+### hoon
468+
469+A _hoon_ (lowercase) is the result of parsing a Hoon source expression into an
470+AST node. These AST nodes are nouns, like all other Hoon data. Because every
471+Hoon program is, in its entirety, a single expression of Hoon, the result of
472+parsing the whole thing into an AST is a single `hoon`.
473+
474+A hoon is a tagged union of the form `[%tag data]`, where the tag
475+is a constant such as `%brts` (from the source [rune](#rune) `|=`,
476+i.e. "bartis"), and is matched up with the appropriate type of data
477+(often more `hoon`s, from source subexpressions). For example, the
478+expression `:-(2 17)`, once parsed into an AST, becomes the following:
479+
480+```
481+[%clhp p=[%sand p=%ud q=2] q=[%sand p=%ud q=17]]
482+```
483+
484+The `%clhp` is produced from the rune `:-` (i.e. "colhep"). The 2 and
485+17 have each been parsed as `%sand`-tagged hoons, which represent
486+atoms (in this case each with an aura of `%ud`, i.e. unsigned
487+decimal).
488+
489+To parse Hoon source into a hoon AST, use `ream` on a `cord`
490+containing Hoon source. Try the following in [Dojo](@/operations.md#using-the-shell):
491+
492+```
493+(ream ':+(12 7 %a)')
494+```
495+
496+The result should be:
497+
498+```
499+[%clls p=[%sand p=%ud q=12] q=[%sand p=%ud q=7] r=[%rock p=%tas q=97]]
500+```
501+
502+See [expression reference](@/docs/hoon/hoon-expressions/rune/_index.md) for the full list of hoons.
503+
504+### irregular form
505+
506+Irregular forms are alternative ways of writing Hoon expressions, alternatives
507+to the digraphic runes such as `:~`. Irregular forms are usually more compact
508+than regular forms.=
509+
510+_See [irregular forms](@/docs/hoon/hoon-expressions/irregular.md)._
511+
512+### jet
513+
514+A _jet_ is a piece of C code that have equivalent products to a piece of Hoon or
515+Nock code. They are used for performance reasons; jets are meant to be faster
516+than the code that they are substituting for.
517+
518+Jets are necessary for mathematics, performance-wise, because Nock handles it
519+so inefficiently. Nock, for example, can’t decrement (reduce a number by one)
520+except by starting building a loop that starts from zero and increments to a
521+number just below.
522+
523+_See [API overview](@/docs/vere/api.md)._
524+
525+### lark
526+
527+A lark is an expression that returns a [limb](#limb) at the specified
528+address in a cell. Using `-` by itself returns the head of the subject, and
529+using `+` by itself returns the tail:
530+
531+```
532+> -:[[4 5] [6 [14 15]]]
533+[4 5]
534+
535+> +:[[4 5] [6 [14 15]]]
536+[6 14 15]
537+```
538+
539+You can combine `+` or `-` with either of `>` or `<` to get a more specific limb
540+of the subject. `-<` returns the head of the head; `->` returns the tail of the
541+head; `+<` returns the head of the tail; and `+>` returns the tail of the tail.
542+By alternating the `+`/`-` symbols with `<`/`>` symbols, you can go as deep as
543+you desire.
544+
545+```
546+> +>-:[[4 5] [6 [14 15]]]
547+14
548+
549+> +>+:[[4 5] [6 [14 15]]]
550+15
551+```
552+
553+### limb
554+
555+A _limb_ is an attribute or variable reference. A limb is an [arm](#arm) or a
556+[leg](#leg).
557+
558+To resolve a _limb_ named "foo", the subject is searched depth-first,
559+head-first for either a face named "foo" or a core with an arm of
560+"foo". If a face is found, the result is a leg, if a core is
561+found, the result is the product of the arm.
562+
563+#### leg
564+
565+ a subexpression, or subtree of the
566+ [subject](#nock-subject).
567+
568+#### wing
569+
570+ a search path into the subject, composed of
571+ limbs. Search occurs from right to left (`a.b` means `b` within `a`).
572+
573+_See [Limbs and wings](@/docs/hoon/hoon-expressions/limb/_index.md)_
574+
575+### move
576+
577+A move is the [Arvo](#arvo) equivalent of a syscall.
578+
579+### noun
580+
581+In [Nock](#nock) and [Hoon](#hoon), a _noun_ is an atom or a cell.
582+
583+### Nock
584+
585+Nock is a Turing-complete, non-lambda combinator interpreter. It's
586+Urbit's low-level programming language. Nock is functional and typeless.
587+
588+#### noun
589+
590+ an _atom_ or a _cell_.
591+
592+#### atom
593+
594+ any natural number, including zero.
595+
596+#### cell
597+
598+ any ordered pair of nouns.
599+
600+
601+#### subject
602+
603+ a noun - the data against which a _formula_ is evaluated.
604+
605+#### formula
606+
607+ a noun - a function at the nock level.
608+
609+#### product
610+
611+ a noun - the result of evaluating a formula against a subject.
612+
613+_See the [Nock definition](@/docs/nock/definition.md)._
614+
615+### mark
616+
617+A _mark_ is Urbit's version of a MIME type, if a MIME type was an
618+executable specification. The mark is just a label that's used as a path
619+to a local source file in the Arvo filesystem. This source file defines
620+a core that can mold untrusted data, diff and patch, convert to other
621+marks, etc.
622+
623+If this sounds like magic, it isn't quite magic. There's no way
624+for different urbits to make sure they mean the same thing by the
625+same mark. However, when incompatibility happens, marks ensure
626+that we at least handle the situation in a predictable way.
627+
628+#### metal
629+
630+Every core has a _metal_ which defines its variance model (ie, the
631+properties of the type of a compatible core). The default is `gold`
632+(invariant).
633+
634+- `gold`: _invariant_
635+- `lead`: _bivariant_
636+- `zinc`: _covariant_
637+- `iron`: _contravariant_
638+
639+_See [advanced types](@/docs/hoon/hoon-expressions/advanced.md)_.
640+
641+### ship
642+
643+An Urbit _ship_ is: a cryptographic title on a _will_ signed by private key; a
644+human-memorable name; and a packet-routing address. Ships are classed by the
645+number of bits in their address:
646+
647+```
648+ Size Name Parent Object Example
649+ ----- ------ ------ ------ -------
650+ 2^8 galaxy ~ supernode ~zod
651+ 2^16 star galaxy supernode ~dozbud
652+ 2^32 planet star user ~tasfyn-partyv
653+ 2^64 moon planet device ~sigsam-nimbot-tasfyn-partyv
654+ 2^128 comet ~ bot ~racmus-mollen-fallyt-linpex--watres-sibbur-modlux-rinmex
655+```
656+
657+Any ship can be called an _urbit_. The lowercase "u" distinguishes it from Urbit
658+the software stack and Urbit the network.
659+
660+_You can find a longer-form summary [here.](https://urbit.org/posts/essays/the-urbit-address-space/)._
661+
662+An Urbit identity is a string like `~firbyr-napbes`. It means nothing,
663+but it's easy to remember and say out loud. `~firbyr-napbes` is actually
664+just a 32-bit number (`3.237.967.392`, to be exact), like an IP address,
665+that we turn into a human-memorable string. The full name of this string
666+can be viewed by typing `our` in the Dojo, Urbit's shell. This is useful
667+when running a ship with a longer name, such as a _moon_ or a _comet_.
668+
669+Technically, an urbit is a secure digital identity that you own and
670+control with a cryptographic key, like a Bitcoin wallet. As in Bitcoin,
671+the supply of urbits is mathematically limited. This keeps the network
672+friendly, by making spam and abuse expensive.
673+
674+An urbit name is just a number; smaller numbers make shorter names.
675+Shorter names are easier to remember, so they're more valuable. So
676+urbits are classified by the number of bits in their name. (A ship name
677+is just a scrambled base-256 representation of the number.)
678+
679+A 32-bit urbit (like `~firbyr-napbes`) is called a _planet._ A 16-bit
680+urbit (like `~pollev)` is a _star._ An 8-bit ship (like `~mun`) is a
681+_galaxy._ A planet is an identity for an independent, adult human. Stars
682+and galaxies are network infrastructure.
683+
684+Each planet or star is launched by its _parent,_ the star or galaxy
685+whose number is its bottom half. So the planet `~firbyr-napbes`,
686+`0xdead.beef` or `3.735.928.559`, is the child of `~pollev`, `0xbeef` or
687+`48.879`, whose parent is `~mun`, `0xef`, `239`. The galaxy at the address of
688+`0` is `~zod`.
689+
690+#### pier
691+
692+ A ship's _pier_ is its Unix directory. For planets, the name of the pier is
693+ usually the planet name.
694+
695+### structure
696+
697+A _structure_ is an idempotent [gate](#gate) (function) that constructs and
698+validates types in Hoon.
699+
700+An example: Arvo [marks](#mark) use Hoon's type system via structures to
701+validate untrusted network data.
702+
703+Here's some common structure terminology:
704+
705+#### bunt
706+
707+ A bunt is the default value of a [structure](#structure). It's also a verb;
708+ to _bunt_ a structure is to produce the bunt of that structure. For example,
709+ bunting `@` results in `0`, and bunting `@t` results in `''`. Bunting is
710+ performed with `*` followed by the structure in question:
711+
712+ ```
713+ > *@
714+ 0
715+ > *@t
716+ ''
717+ ```
718+
719+#### icon: The type of the mold's range
720+
721+_See [mold hoons](/docs/hoon/hoon-expressions/rune/buc/)._
722+
723+### rune
724+
725+A Hoon _rune_ is a pair of ASCII symbols used to begin a
726+[Hoon expression](#a-hoon).
727+
728+For example, the rune [`?:`](@/docs/hoon/hoon-expressions/rune/wut.md#wutcol) is
729+Hoon's most common conditional, a branch on a boolean test. The first
730+symbol in a rune represents a family of related runes. For example, the
731+[`?` family](@/docs/hoon/hoon-expressions/rune/wut.md) are all conditionals.
732+
733+The result of parsing a Hoon source expression&mdash;the rune, followed
734+by its respective children&mdash;into an AST node is simply called
735+a [`hoon`](#a-hoon).
736+
737+Runes have two syntactic forms, _tall_ and _flat_:
738+
739+#### tall
740+
741+ multiple lines, no parentheses, two or more spaces between tokens
742+
743+ Example:
744+
745+ ```
746+ > %+ add 2 2
747+ 4
748+ ```
749+
750+#### flat
751+
752+ one line, parentheses, one space between tokens
753+
754+ Example:
755+ ```
756+ > %+(add 2 2) :: regular flat form
757+ 4
758+
759+ > (add 2 2) :: irregular flat form
760+ 4
761+ ```
762+
763+Tall hoons can contain flat hoons, but not vice versa. All irregular
764+forms are flat.
765+
766+_See [hoon concept](#a-hoon),
767+[expressions](@/docs/hoon/hoon-expressions/rune/_index.md).
768+
769+### Sail
770+
771+_Sail_ is the Hoon markup language for XML.
772+
773+### scry
774+
775+To _scry_ means to request data from the Arvo namespace and bring it
776+to userspace.
777+
778+_See [.^ (dot-ket)](@/docs/hoon/hoon-expressions/rune/dot.md#dotket)._
779+
780+### slot
781+
782+`slot` is the name for Hoon's tree-addressing scheme.
783+
784+Every cell has a head and a tail, each of which may be either an atom or
785+a cell. Therefore every noun is a binary tree. `+1` or `.` resolves to
786+the whole cell (technically this would work against an atom as well).
787+The head of `+n` is `+2n`, the tail is `+(2n+1)`.
788+
789+`+7` is a special address for gates, because the position is defined
790+(by convention) as the context of a gate and of all cores.
791+
792+### talk
793+
794+_Talk_ is Urbit's built-in chat app. It’s one example of an app that can be
795+built on top of Hall, the Urbit back-end messaging system.
796+
797+_See [Messaging](@/operations.md#messaging). for more information._
798+
799+### type
800+
801+A Hoon _type_ defines a set (finite or infinite) of nouns and ascribes
802+some semantics to it. There is no direct syntax for defining
803+types; they are always defined by inference (i.e., by
804+[`mint`](#mint)), usually using a constructor ([structure](#structure)).
805+
806+All types are assembled out of base types defined in `++type`.
807+(Look up `++ type` in hoon.hoon for examples.) When the compiler
808+does type-inference on a program, it assembles complex types out
809+of the simpler built-in types.
810+
811+#### nest
812+
813+ `nest` is an internal Hoon function on two types which performs a type
814+ compatibility test. `nest` produces yes if the
815+ set of nouns in the second type is provably a subset of the first.
816+ If `nest` produces no, the Hoon programmer will receive a `nest-fail`
817+ error. This is one of the most commons errors in Hoon programming.
818+
819+ _See [advanced types](@/docs/hoon/hoon-expressions/advanced.md)_ and [troubleshooting](@/docs/arvo/ship-troubleshooting.md).
820+
821+
822+### Unit
823+
824+Hoon's equivalent of a nullable pointer or a Haskell Maybe. If `q` is `~`,
825+null, the type is _warm_; any atom is in the type. If `q` is `[~ x]`, where
826+`x` is any atom, the type is _cold_; its only legal value is the constant `x`.
827+
828+### Vane
829+
830+A _vane_ is an [Arvo](#arvo) module. Each Vane is a single file because Arvo
831+cannot, on its own, deal with programs that are split between multiple files.
832+Some vanes can do this, however.
833+
834+### Vere (pronounced “vair”)
835+
836+The runtime system, written in C, that implements [Nock](#nock). All
837+It’s written in C. Vere-level errors are prepended with as `bail:`.
838+
839+Vere is a virtual machine: it pretends to be hardware, and is the single point
840+of contact between your Urbit and the rest of your system. But more than that,
841+Vere handles the Urbit event log and handles jets. It’s also contains the i/o
842+drivers for Urbit’s vanes, responsible for generating events from Unix and
843+applying effects to Unix.
844+
845+### Zuse
846+
847+_Zuse_ is a defined interface for vanes. It contains the part of the Hoon
848+standard library that is specific to Arvo functionality.
849+
850+Arvo is located in `/home/sys/zuse.hoon` within your urbit.
reference/azimuth-glossary.mdnew file+118
@@ -0,0 +1,118 @@
1++++
2+title = "Azimuth Glossary"
3+weight = 4
4+template = "doc.html"
5+aliases = ["/docs/reference/azimuth-glossary/"]
6++++
7+
8+
9+Azimuth is a general-purpose public-key infrastructure (PKI) on the Ethereum blockchain, used as a platform for Urbit identities. You need an Azimuth identity to use the Arvo network. All identity-related operations are governed at this layer For more information, see the [Azimuth documentation](azimuth).
10+
11+This glossary is intended to familiarize you with Azimuth-related terminology. To brush up on terminology related to Arvo, check out the [Arvo glossary](../arvo/glossary).
12+
13+### Azimuth identity
14+
15+An Azimuth identity, previously known as a _point_, is a non-fungible Ethereum token ([ERC-271](https://medium.com/@brenn.a.hill/noobs-guide-to-understanding-erc-20-vs-erc-721-tokens-d7f5657a4ee7)) that represents a digital identity. The ERC-721 standard, having been made specifically to provide a smart-contract interface for non-fungible assets, allows Azimuth identity ownership to be take advantage of existing third-party tools and systems.
16+
17+#### Planet
18+
19+An Azimuth identity to be used as a personal identity. Issued by stars.
20+
21+#### Star
22+
23+An Azimuth identity meant to be used as network infrastructure. Issued by galaxies, issues planets.
24+
25+#### Galaxy
26+
27+An Azimuth identity meant to be used as top-level network infrastructure, with governance powers. Issues stars.
28+
29+### Bridge
30+
31+A tool that's the primary way to interact with Azimuth and manage your identities. It can be accessed at bridge.azimuth.network.
32+
33+### Master Ticket
34+
35+Think of your master ticket as a very high-value password. The master ticket is the secret code from which all of your other secrets are derived. Technically, your master ticket is seed entropy. You should never share it with anyone, and store it very securely. This ticket can derive all of your other keys: your ownership key and all of the related proxies.
36+
37+### Multipass
38+
39+Multipass is a planned feature of an Azimuth point that can be used as a universal, real-world identity. It will be able to hold money and have packets routed to it. See this [blog post](https://urbit.org/posts/azimuth-as-multipass/) for more information.
40+
41+#### Network Explorer
42+
43+A Bridge-based interface for browsing Azimuth identities. You can do things such as see which ships are on which invite pools, and much more.
44+
45+### Ownership Address
46+
47+The Ethereum address that owns a point. As the owner, it can perform all possible operations for that point.
48+
49+### Invite Pool
50+
51+Also called an _invite tree_. A host starts a pool and all individuals invited to it have the ability to share remaining, unclaimed invites with others; when an invite is sent to someone, they become a full member of the invite pool and themselves have the ability to invite. So membership of the invite pool grows like a tree.
52+
53+#### Pool Host
54+
55+The ship that generates the invite pool. It's most often a star.
56+
57+#### Guest List
58+
59+The names of planets invited to the same invite pool, as viewed by the pool host.
60+
61+#### Invite Cohort
62+
63+The names of planets invited to the same invite pool, as viewed by the pool's member's.
64+
65+#### Sending Invites
66+
67+The action of giving someone a planet using Bridge.
68+
69+#### Code
70+
71+Activation code from an email that allows you to claim an invite
72+
73+#### Birth Time
74+
75+When a ship is claimed from an invite
76+
77+### Passport
78+
79+The Passport is a folder of files one downloads that contains the secrets of your point and should be stored securely. As long as you own the passport, you own the point. The master ticket is stored in the Passport.
80+
81+### Proxy Address
82+
83+An Ethereum address that's allowed to perform a specific subset of the operations the owner of the point can perform. Useful for allowing some control over a point while keeping its ownership address in cold storage. Below, the specific kinds of proxy addresses are listed.
84+
85+#### Management Proxy Address
86+
87+An Ethereum address used for managing a point. This means it can only configure public (aka networking) keys, and perform sponsorship-related operations (requesting sponsor changes & approving/rejecting those).
88+Use cases:
89+- Keeping this handy so you can put the ownership/master ticket in a super safe place
90+- Allowing someone to manage your ship (by setting/deriving networking keys, managing sponsorship)
91+- Allowing a smart contract to manage sponsorship ops (ie star service smart contract)
92+
93+#### Network Keys
94+
95+Your public key contains Authentication and Encryption addresses, and also have Revision, Continuity Era, and Crypto Suite versions. Resetting Network Keys increases the revision number on the key. A main use case would be if your Network Keys were compromised, so you can use your Management Address to re-derive your Network Keys to another revision.
96+
97+#### Spawn Proxy Address
98+
99+An Ethereum address used for spawning children of a point. It can only perform the spawn operation (creating child points) and can do nothing else.
100+
101+Use cases:
102+- Keeping this handy so you can put the ownership/master ticket in a super safe place
103+- Allowing a smart contract to spawn on your behalf (delegated sending/invites, planet sale)
104+
105+#### Voting Proxy Address
106+An Ethereum address used for voting as a point.
107+
108+Use cases:
109+- Keeping this handy so you can put the ownership/master ticket in a super safe place
110+- Delegating your voting rights to someone else
111+
112+#### Transfer Proxy Address
113+
114+An Ethereum address that's allowed to transfer ownership of a point. Generally not used outside of transfers-in-progress. Using a transfer proxy allows one to give the recipient the power to take ownership of a point, rather than being given it. This "control check" is a strong safety mechanism commonly used in many (Ethereum-based) cryptographic assets.
115+
116+### Sponsorship
117+
118+Azimuth registers hierarchical dependence of identities on other identities; planets depend on stars, and stars depend on galaxies. Applications that use Azimuth can use this to set up things like network topology. In Arvo's case, the sponsor promises to provide software updates and peer discovery.
hoon/cheat-sheet.md → reference/cheat-sheet.mdrenamed

The content is the same.

hoon/troubleshooting.md → reference/hoon-errors.mdrenamed+2−2
@@ -1,6 +1,6 @@
1+++
1+++
2−title = "Troubleshooting Hoon"
2+title = "Hoon Errors"
3−weight = 5
3+weight = 6
4template = "doc.html"
4template = "doc.html"
5+++
5+++
6Ideally your Hoon works perfectly the first time. But...
6Ideally your Hoon works perfectly the first time. But...
hoon/hoon-expressions/_index.md → reference/hoon-expressions/_index.mdrenamed

The content is the same.

hoon/hoon-expressions/advanced.md → reference/hoon-expressions/advanced.mdrenamed

The content is the same.

hoon/hoon-expressions/basic.md → reference/hoon-expressions/basic.mdrenamed

The content is the same.

hoon/hoon-expressions/irregular.md → reference/hoon-expressions/irregular.mdrenamed

The content is the same.

hoon/hoon-expressions/limb/_index.md → reference/hoon-expressions/limb/_index.mdrenamed

The content is the same.

hoon/hoon-expressions/limb/limb.md → reference/hoon-expressions/limb/limb.mdrenamed

The content is the same.

hoon/hoon-expressions/limb/wing.md → reference/hoon-expressions/limb/wing.mdrenamed

The content is the same.

hoon/hoon-expressions/rune/_index.md → reference/hoon-expressions/rune/_index.mdrenamed

The content is the same.

hoon/hoon-expressions/rune/bar.md → reference/hoon-expressions/rune/bar.mdrenamed

The content is the same.

hoon/hoon-expressions/rune/buc.md → reference/hoon-expressions/rune/buc.mdrenamed

The content is the same.

hoon/hoon-expressions/rune/cen.md → reference/hoon-expressions/rune/cen.mdrenamed

The content is the same.

hoon/hoon-expressions/rune/col.md → reference/hoon-expressions/rune/col.mdrenamed

The content is the same.

hoon/hoon-expressions/rune/constants.md → reference/hoon-expressions/rune/constants.mdrenamed

The content is the same.

hoon/hoon-expressions/rune/dot.md → reference/hoon-expressions/rune/dot.mdrenamed

The content is the same.

hoon/hoon-expressions/rune/ket.md → reference/hoon-expressions/rune/ket.mdrenamed

The content is the same.

hoon/hoon-expressions/rune/lus.md → reference/hoon-expressions/rune/lus.mdrenamed

The content is the same.

hoon/hoon-expressions/rune/mic.md → reference/hoon-expressions/rune/mic.mdrenamed

The content is the same.

hoon/hoon-expressions/rune/sig.md → reference/hoon-expressions/rune/sig.mdrenamed

The content is the same.

hoon/hoon-expressions/rune/terminators.md → reference/hoon-expressions/rune/terminators.mdrenamed

The content is the same.

hoon/hoon-expressions/rune/tis.md → reference/hoon-expressions/rune/tis.mdrenamed

The content is the same.

hoon/hoon-expressions/rune/wut.md → reference/hoon-expressions/rune/wut.mdrenamed

The content is the same.

hoon/hoon-expressions/rune/zap.md → reference/hoon-expressions/rune/zap.mdrenamed

The content is the same.

hoon/library/1a.md → reference/library/1a.mdrenamed

The content is the same.

hoon/library/1b.md → reference/library/1b.mdrenamed

The content is the same.

hoon/library/1c.md → reference/library/1c.mdrenamed

The content is the same.

hoon/library/2a.md → reference/library/2a.mdrenamed

The content is the same.

hoon/library/2b.md → reference/library/2b.mdrenamed

The content is the same.

hoon/library/2c.md → reference/library/2c.mdrenamed

The content is the same.

hoon/library/2d.md → reference/library/2d.mdrenamed

The content is the same.

hoon/library/2e.md → reference/library/2e.mdrenamed

The content is the same.

hoon/library/2f.md → reference/library/2f.mdrenamed

The content is the same.

hoon/library/2g.md → reference/library/2g.mdrenamed

The content is the same.

hoon/library/2h.md → reference/library/2h.mdrenamed

The content is the same.

hoon/library/2i.md → reference/library/2i.mdrenamed

The content is the same.

hoon/library/2j.md → reference/library/2j.mdrenamed

The content is the same.

hoon/library/2k.md → reference/library/2k.mdrenamed

The content is the same.

hoon/library/2l.md → reference/library/2l.mdrenamed

The content is the same.

hoon/library/2m.md → reference/library/2m.mdrenamed

The content is the same.

hoon/library/2n.md → reference/library/2n.mdrenamed

The content is the same.

hoon/library/2o.md → reference/library/2o.mdrenamed

The content is the same.

hoon/library/2p.md → reference/library/2p.mdrenamed

The content is the same.

hoon/library/2q.md → reference/library/2q.mdrenamed

The content is the same.

hoon/library/3a.md → reference/library/3a.mdrenamed

The content is the same.

hoon/library/3b.md → reference/library/3b.mdrenamed

The content is the same.

hoon/library/3c.md → reference/library/3c.mdrenamed

The content is the same.

hoon/library/3d.md → reference/library/3d.mdrenamed

The content is the same.

hoon/library/3e.md → reference/library/3e.mdrenamed

The content is the same.

hoon/library/3f.md → reference/library/3f.mdrenamed

The content is the same.

hoon/library/3g.md → reference/library/3g.mdrenamed

The content is the same.

hoon/library/4a.md → reference/library/4a.mdrenamed

The content is the same.

hoon/library/4b.md → reference/library/4b.mdrenamed

The content is the same.

hoon/library/4c.md → reference/library/4c.mdrenamed

The content is the same.

hoon/library/4d.md → reference/library/4d.mdrenamed

The content is the same.

hoon/library/4e.md → reference/library/4e.mdrenamed

The content is the same.

hoon/library/4f.md → reference/library/4f.mdrenamed

The content is the same.

hoon/library/4g.md → reference/library/4g.mdrenamed

The content is the same.

hoon/library/4h.md → reference/library/4h.mdrenamed

The content is the same.

hoon/library/4i.md → reference/library/4i.mdrenamed

The content is the same.

hoon/library/4j.md → reference/library/4j.mdrenamed

The content is the same.

hoon/library/4k.md → reference/library/4k.mdrenamed

The content is the same.

hoon/library/4l.md → reference/library/4l.mdrenamed

The content is the same.

hoon/library/4m.md → reference/library/4m.mdrenamed

The content is the same.

hoon/library/4n.md → reference/library/4n.mdrenamed

The content is the same.

hoon/library/4o.md → reference/library/4o.mdrenamed

The content is the same.

hoon/library/5a.md → reference/library/5a.mdrenamed

The content is the same.

hoon/library/5b.md → reference/library/5b.mdrenamed

The content is the same.

hoon/library/5c.md → reference/library/5c.mdrenamed

The content is the same.

hoon/library/5d.md → reference/library/5d.mdrenamed

The content is the same.

hoon/library/5e.md → reference/library/5e.mdrenamed

The content is the same.

hoon/library/5f.md → reference/library/5f.mdrenamed

The content is the same.

hoon/library/5g.md → reference/library/5g.mdrenamed

The content is the same.

hoon/library/_index.md → reference/library/_index.mdrenamed

The content is the same.

hoon/library/table-of-contents.md → reference/library/table-of-contents.mdrenamed

The content is the same.

hoon/library/zuse.md → reference/library/zuse.mdrenamed

The content is the same.

using/_index.mdnew file+18
@@ -0,0 +1,18 @@
1++++
2+title = "Using"
3+weight = 2
4+sort_by = "weight"
5+template = "sections/docs/chapters.html"
6++++
7+This section contains guides to using your urbit.
8+
9+- [Creating a Development Ship](creating-a-development-ship) will show you how to set up the environment for coding on Urbit.
10+- [Creating a Comet](creating-a-comet) will show you how to create a comet: quick, disposable 128-bit identities on the Urbit network.
11+- [Admin and Operation](admin) is a guide to the basic commands used to interact with your ship.
12+- [Messaging](messaging) tells you how to use Talk, our chat system.
13+- [Shell](shell) is a guide to using Dojo, our command-line interface.
14+- [Introduction to the Filesystem](filesystem) explains the basics of using use Clay, our revision-control filesystem.
15+- [Source Layout](layout) walks you through the various directories of the Arvo operating system.
16+- [Sail](sail) is a guide to Sail: Hoon markup that's used to build web pages with XML.
17+- [Udon](udon) is a guide to Udon, which is our take on Markdown.
18+- [Generators](generators) will explain how to use the "generator," a kind of file that's the easiest way to run Hoon programs.
using/admin.mdnew file+213
@@ -0,0 +1,213 @@
1++++
2+title = "Admin and Operations"
3+weight = 2
4+template = "doc.html"
5++++
6+Your urbit (also called your _ship_) is a persistent Unix process that you
7+mainly control from the console. For some things, a browser will also work.
8+
9+## Shutdown
10+
11+You can turn your urbit off with `Ctrl-d` from the Talk or Dojo prompts.
12+
13+You can force-quit your urbit with `Ctrl-z` from anywhere.
14+
15+## Restart
16+
17+To restart your urbit simply pass the name of your pier:
18+
19+```
20+$ urbit some-planet
21+```
22+
23+or
24+
25+```
26+$ urbit comet
27+```
28+
29+## Logging
30+
31+To log an urbit's command line output to a file, use `script`:
32+
33+```
34+$ script urbit.log urbit your-urbit
35+```
36+
37+## Moving your pier
38+
39+Piers are designed to be portable, but it _must_ be done while the urbit
40+is turned off. Urbit networking is stateful, so you can't run two copies
41+of the same urbit in two places.
42+
43+To move a pier, simply move the contents of the directory it lives in.
44+To keep these files as small as possible we usually use the `--sparse`
45+option in `tar`. With a pier `your-urbit/`, something like this should work:
46+
47+```
48+tar -Scvzf ~/your-urbit.tar.gz ~/your-urbit/
49+scp your-old-server:~/your-urbit.tar.gz your-new-server:~
50+```
51+
52+Then to unzip it, on your other Unix server, run:
53+
54+```
55+tar xfvz your-urbit.tar.gz
56+```
57+
58+Delete the tar file, and, after installing Urbit on your new server,
59+start your urbit back up with:
60+
61+```
62+urbit your-urbit
63+```
64+
65+## Console
66+
67+Your Urbit terminal is separated into two parts: the prompt (the bottom
68+line) and the record (everything above that). The record is shared; all
69+the output from all the apps in your command set appears in it. The
70+prompt is multiplexed.
71+
72+In the CLI, Urbit apps can process your input before you hit return. To
73+see this in action try entering `)` as the first character at the Dojo
74+prompt. Since there is no Dojo command or Hoon expression that starts
75+with ')', the Dojo rejects it.
76+
77+`Ctrl-x` - Switches the prompt between running console apps.
78+
79+`Ctrl-c` - Crash current event. Processed at the Unix layer and prints a stack.
80+trace.
81+
82+`Ctrl-d` - From Talk or Dojo, stops your Urbit process.
83+
84+`Ctrl-z` - Stops the Urbit process from _anywhere_.
85+
86+`↑` / `↓` - History navigation.
87+
88+`Backspace` - Interrupts running commands. For example, if you have begun a multiline Hoon expression and then press backspace, it will discard the already-written code, or if you press backspace while a request is still pending it will cancel it and print `! cancel /hand`.
89+
90+The following emacs-style key bindings are available:
91+
92+```
93+Ctrl-a Cursor to beginning of the line (Home)
94+Ctrl-b Cursor one character backward (left-arrow)
95+Ctrl-e Cursor to the end of the line (End)
96+Ctrl-f Cursor one character forward (right-arrow)
97+Ctrl-g Beep; cancel reverse-search
98+Ctrl-k Kill to end of line
99+Ctrl-l Clear the screen
100+Ctrl-n Next line in history (down-arrow)
101+Ctrl-p Previous line in history (up-arrow)
102+Ctrl-r Reverse-search
103+Ctrl-t Transpose characters
104+Ctrl-u Kill to beginning of line
105+Ctrl-y Yank from kill buffer
106+```
107+
108+Full coverage of the Urbit shell, the Dojo is covered in the
109+[Shell walkthrough](@/docs/using/shell.md).
110+
111+## Web
112+
113+On startup Urbit tries to bind to `localhost:80`. If you're already
114+running something on port `80` -- such as any other HTTP server, or another urbit -- you'll find the urbit
115+that you just started on `8080`, `8081`, and so on. For planets only, we also proxy web
116+domains through Urbit's own servers. Any planet `~your-urbit` is also at
117+`your-urbit.arvo.network`, but only after you [set up DNS](../dns-proxying).
118+
119+Your urbit serves a simple homepage from `http://localhost` or
120+`https://your-urbit.arvo.network` that should be self-explanatory. Since
121+our HTTPS isn't audited / battle tested, we just call it "secure" HTTPS.
122+You can find that on `8443`. Or `8444` (and so on) if you're already
123+running something on `8443`.
124+
125+## Moons {#moons}
126+
127+Planets can spawn moons, which are meant for connected devices: phones, smart
128+TVs, digital thermostats. The basic idea is: your planet runs permanently in a
129+data center somewhere and moons run on all your devices. Each planet can issue
130+~4 billion (`2^32`) moons.
131+
132+To generate a random moon from your planet, run:
133+
134+```
135+~sampel-palnet:dojo> +moon
136+moon: ~faswep-navred-sampel-palnet
137+\/~.0wd.rZU67.3jSny.z1vda.7sr-s.EL1Jt.-76Nj.ugXxY.g6-Bx.HvKZl.G53oV.hPnXe.7U3E3.J4CEe.MEVuq.~08Nt\/
138+ .zNT0K.k-Ab~.Nn90d.OZ2fT.-XlQQ.Cfrkf.y6~K0.2Do09.EaE3W.BSK--.5Q~9N.y3QIP.eokH-.T6lwz.gg8MX.7LU5
139+ x.DJROE.IzQsy.OXOLr.IOE3a.-QI40.H5ukK.Cw-u4.uxE-y.V-o1F.Q84g0.effP0.de01g.600g1
140+\/ \/
141+```
142+
143+You must manually edit the output of `+moon` to get
144+the correct format for the `<key>`:
145+
146+- strip out the `\/`
147+
148+- combine into one line, omitting spaces
149+
150+- trim the leading `~.`
151+
152+`<key>` would be `0wd.rZU67.3jSny.z1vda ... <snip> ... effP0.de01g.600g1`
153+in this example.
154+
155+Put `<key>` in a file and that file becomes `<keyfile>`.
156+
157+Another way of generating `<keyfile>` is:
158+
159+```
160+~sampel-palnet:dojo> @moon/key +moon
161+moon: ~faswep-navred-sampel-palnet
162+```
163+
164+`<keyfile>` will be at `path/to/sampel-palnet/.urb/put/moon.key`
165+and does not need editing to be used with the `-k` option.
166+
167+You can use the resulting output in the same installation flow from the
168+[Booting a Ship](@/docs/getting-started/booting-a-ship.md) guide, following the same scheme as for booting a planet. That scheme is:
169+
170+```
171+$ urbit -w <moonname> -G <key> -c <piername>
172+```
173+
174+or
175+
176+```
177+$ urbit -w <moonname> -k <keyfile> -c <piername>
178+```
179+
180+The `-c <piername>` argument is not required, but it is recommended; otherwise,
181+the resulting directory is a rather unwieldy moon name.
182+
183+Here's how an example moon might be booted:
184+
185+```
186+$ urbit -w faswep-navred-sampel-palnet -G <key> -c mymoon
187+```
188+
189+or
190+
191+```
192+$ urbit -w faswep-navred-sampel-palnet -k <keyfile> -c mymoon
193+```
194+
195+Moons are automatically synced to their parent `%kids` desk, and can control
196+applications on their parent planet using `|link`. You can read more about
197+those operations in the [filesystem](@/docs/using/filesystem.md) and [console](@/docs/using/shell.md)
198+walkthroughs, respectively.
199+
200+
201+## Continuity breaches
202+
203+While the Urbit network is in this alpha state, we sometimes have to
204+reboot the whole network. This happens either when major changes need
205+to be shipped or we hit a bug that can't be fixed over the air.
206+
207+Because Urbit networking is stateful we call this a _continuity breach_.
208+Everything has to be restarted from scratch. Your pier will continue to
209+function after we have breached, but it wont connect to the rest of the
210+Urbit network.
211+
212+When this happens, back up any files you'd like to save, shut down your
213+urbit and recreate it (as if you were starting for the first time).
using/arvo-network-dns.mdnew file+52
@@ -0,0 +1,52 @@
1++++
2+title = "Arvo.network DNS"
3+weight = 2
4+template = "doc.html"
5++++
6+
7+We have a system that lets you request a domain name for your ship in the form of `ship.arvo.network`, where `ship` is your ship's name minus the `~`. This allows users to access their ships remotely using Landscape, our graphical web interface.
8+
9+Stars and planets follow the same process DNS proxying process, and galaxies have their own requirements. Moons and comets are not supported.
10+
11+## Planets and Stars
12+
13+For a planet or star's DNS proxying request to be made and fulfilled, they must be hosting their ship someplace with a public IP address, and its HTTP server must be listening on port 80.
14+
15+To get `ship.arvo.network` on a planet or star, you must set up DNS routing with its parent ship by starting the `:dns` app.
16+To do so, simply run this command in your ship's Dojo:
17+
18+```
19+> :dns|request
20+```
21+
22+You'll then be prompted to enter the public IP address of your ship. You can also pass the IP address as an argument, using the .0.0.0.0 (`@if`) syntax. For example:
23+
24+```
25+> :dns|request .1.2.3.4
26+```
27+
28+`:dns`, running locally, will make an HTTP request to that IP address on port 80 to confirm that it is itself available at that IP and port. If that fails, you'll receive a `%bail-early` message in `:talk`; this request will retry a few times. If the self-check is successful, the request is relayed to `~zod`, and you'll receive a message saying, `request for DNS sent to ~zod`. Once `~zod` has acknowledged receipt of the request, your local `:dns` app will send a `:talk` message saying `awaiting response from ~zod`.
29+
30+The request will be picked up shortly, and the `ship.arvo.network` DNS record will be set to the given IP address. Once that's setup, `~zod` will be notified, and `~zod` will, in turn, notify your ship. That ship will now try to verify that it can reach itself on `ship.arvo.network` over port 80. If it can't, it'll send a message saying `unable to access via ship.arvo.network`. If it can, it will configure itself with that domain, and say `confirmed access via ship.arvo.network`.
31+
32+Great! You're set up now. Try accessing your `ship.arvo.network` in your browser to use Landscape; we recommend using Chrome or Brave.
33+
34+## Galaxies
35+
36+Galaxies are already required to have separate DNS entry at galaxy.urbit.org. There's no automated process for getting that binding, so if you're a galaxy-holder, get in touch with us at support@urbit.org.
37+
38+There is a command for galaxies that will try to re-use their already-necessary Ames DNS entry for HTTPS:
39+
40+```
41+> :dns|auto
42+```
43+
44+This will make HTTP-requests to self-check availability over `galaxy.$AMES-DOMAIN` (currently galaxy.urbit.org), where `galaxy` is the galaxy's name minus the `~`.
45+
46+Otherwise, `:dns|auto` works the same as `:dns|ip` does with stars and planets: if it's available or unavailable, talk messages, and so on.
47+
48+## More Information
49+
50+Configuring a ship's domain causes the `:acme` app to request an HTTPS certificate for that domain from LetsEncrypt. Note that LetsEncrypt also requires that the HTTP server be listening on port 80. If the certificate request fails, `:acme` will send a `:talk` message with an explanation. Once the certificate is successfully retrieved, `:acme` will install it, causing the HTTP servers to restart. A secure server will be started on port 443 (the HTTPS default) if it's available. Otherwise, it will try 8443, and then increment to the next port until it can successfully bind one.
51+
52+The built-in logic for listening on port 80 similar. Urbit tries to bind port 80; if it cannot, it tries 8080, then increments until it can bind a port. Port 80 is available to unprivileged process on recent version of macOS. Otherwise, the process needs to either be run as root, or be given special permission (CAP\_NET_BIND on Linux).
using/creating-a-comet.mdnew file+29
@@ -0,0 +1,29 @@
1++++
2+title = "Creating a Comet"
3+weight = 1
4+template = "doc.html"
5++++
6+
7+**Comets** are urbits whose names are 128-bits or 16 syllables, such as:
8+
9+`~dasres-ragnep-lislyt-ribpyl--mosnyx-bisdem-nidful-marzod`
10+
11+Comet names aren't quite as memorable as others, but they're disposable identities that anyone can make for free to join the live network.
12+
13+## Booting a Comet
14+
15+To boot your comet, go into the command line and run the following command from the directory that was created during Urbit installation:
16+
17+```
18+$ urbit -c mycomet
19+```
20+
21+This will take a few minutes and will spin out a bunch of boot messages. Toward the end, you'll see something like:
22+
23+```
24+ames: on localhost, UDP 31337.
25+http: live (insecure, public) on 8080
26+http: live ("secure", public) on 8443
27+http: live (insecure, loopback) on 12321
28+~dasres_marzod:dojo>
29+```
using/creating-a-development-ship.mdnew file+69
@@ -0,0 +1,69 @@
1++++
2+title = "Creating a Development Ship"
3+weight = 0
4+template = "doc.html"
5++++
6+
7+To do work with Hoon and with the system, we recommended using a "fake" ship -- one not connected to the network.
8+
9+Because such a ship has no presence on the network, you don't need an Azimuth identity for its purposes. You just need to have [installed our software](@/docs/getting-started/installing-urbit.md).
10+
11+To create a fake ship named `~zod`, run the command below. You can replace `zod` with any valid Urbit ship-name.
12+
13+```
14+urbit -F zod
15+```
16+
17+Now you should see a block of boot messages, starting with the Urbit version number. Welcome!
18+
19+## Basic Operations
20+
21+Welcome to your ship! There's a few things you should do to become oriented.
22+
23+### The Dojo
24+
25+Let's try out the Dojo, the Arvo command line and Hoon REPL:
26+
27+```
28+~sample-planet:dojo> (add 2 2)
29+```
30+
31+Should produce:
32+
33+```
34+> (add 2 2)
35+4
36+```
37+
38+Good.
39+
40+### Mounting
41+
42+Your ship's filesystem being "mounted" means that its filesystem can be interacted with through Unix. This makes things much easier for you.
43+
44+The Arvo filesystem isn't mounted to Unix by default. Switch to the Dojo prompt and run:
45+
46+```
47+~sample-planet:dojo> |mount %
48+```
49+
50+This should produce:
51+
52+```
53+> |mount %
54+>=
55+```
56+
57+which indicates that the command was processed.
58+
59+`|mount %` will cause a `home/` directory to appear inside your _pier_ folder in Unix (the "pier" is our shorthand for the directory whose name corresponds to your Azimuth point). Changes to these files can be committed to your pier by running `|commit %home` once you're done.
60+
61+### Shutting Down and Restarting
62+
63+You can turn your ship off with `ctrl-d` from the Talk or Dojo prompts.
64+
65+To restart your ship, simply pass the name of your pier:
66+
67+```
68+urbit some-planet
69+```
using/filesystem.mdnew file+471
@@ -0,0 +1,471 @@
1++++
2+title = "Filesystem"
3+weight = 5
4+template = "doc.html"
5++++
6+Urbit has its own revision-controlled filesystem, Clay. Clay is a typed, global,
7+referentially transparent namespace. An easy way to think about it is like typed
8+`git`.
9+
10+The most common way to use Clay is to mount a Clay node in a Unix directory. The mounted directory is always at the root of your
11+pier directory.
12+
13+## Quickstart
14+
15+This quick-start guide will walk you through some common commands. Follow along
16+using your Dojo. When you get a `>=` message after entering a command, this means
17+that the command was successful.
18+
19+When developing it's a good idea to use a separate desk. Create a `%sandbox`
20+desk based on the `%home` desk:
21+
22+```
23+~your-urbit:dojo> |merge %sandbox ~your-urbit %home
24+```
25+
26+Running `our` produces your ship-name, meaning that you can run the following
27+command instead of typing out the entire thing. Useful for comets, due to their
28+very long names.
29+
30+```
31+~your-urbit:dojo> |merge %sandbox our %home
32+```
33+
34+Most of the time we want to use Clay from Unix. Mount the entire contents of
35+your `sandbox` desk to Unix:
36+
37+```
38+~your-urbit:dojo> |mount /=sandbox=
39+```
40+
41+To explore the filesystem from inside Urbit `+ls` and `+cat` are useful. `+ls`
42+displays files in the current directory, and `+cat` displays the contents of
43+a file.
44+
45+We can use `%` to mean "current directory." The result of the command below
46+is just like using `ls` in a Unix terminal.
47+
48+```
49+~your-urbit:dojo> +ls %
50+```
51+
52+Notice how `+cat %` does the same thing. That's because everything in Clay,
53+including directories, is a file.
54+
55+Let's explore the `/web` directory of the `%sandbox` desk.
56+
57+```
58+~your-urbit:dojo> +ls /=sandbox=/web
59+```
60+
61+Let's see the contents of `/=sandbox=/web/404/hoon`:
62+
63+```
64+~your-urbit:dojo> +cat /=sandbox=/web/404/hoon
65+```
66+
67+Now let's navigate to `/web` on `%sandbox` using `=dir`, which is like `cd` in Unix.
68+
69+```
70+~your-urbit:dojo> =dir /=sandbox=/web
71+```
72+
73+You'll notice that your prompt is now
74+`~your-urbit:dojo/=/sandbox/~2018.10.2..00.35.44..d7e8/web>`.
75+
76+```
77+~your-urbit:dojo/=/sandbox/~2018.10.2..00.35.44..d7e8/web> +ls %
78+```
79+
80+To change back to our home directory, we use `=dir` without any path.
81+
82+```
83+~your-urbit:dojo/=/sandbox/~2018.10.2..00.35.44..d7e8/web> =dir
84+```
85+
86+Sync from your friend `~some-ship`'s `%experiment` desk to your
87+`%sandbox` desk:
88+
89+```
90+~your-urbit:dojo> |sync %sandbox ~some-ship %experiment
91+```
92+
93+If and when your sync is successful, you will receive a message:
94+
95+```
96+activated sync from %experiment on ~some-ship to %sandbox
97+```
98+
99+The ship that you sync from will get their own message indicating that you're
100+both connected as peers:
101+
102+```
103+; ~your-urbit is your neighbor.
104+```
105+
106+---
107+
108+## Manual
109+
110+### Paths
111+
112+A path in Clay is a list of URL-safe text, restricted to the characters
113+`[a z]`,`[0 9]`, `.`, `-`, `_`, and `~`. Formally this is a `(list knot)`,
114+meaning that each segment, delineated by `/`, is of the `knot` ASCII-text type.
115+In other words, paths are expressed as `/foo/bar/baz`. File extensions are
116+separated from file names with `/`, not `.`. Extensions are syntactically
117+identical to subdirectories, except that they must terminate the path.
118+
119+Paths begin with a piece of data called a `beak`. A beak is formally a
120+`(p=ship q=desk r=case)`; it has three components, and might look like
121+`/~dozbud-namsep/home/11`.
122+
123+The first `beak` component is `ship`, which is, as you might guess, the name of
124+an Urbit ship. The second component is `desk`, which is a workspace meant to
125+contain other directories; the default desk is `%home`. The third component is
126+`case`, which represents version information in various ways: date and time;
127+a version sequence, which is a value incremented by one whenever a file on the
128+given `desk` is modified; or an arbitrary plaintext label.
129+
130+You can find what your `beak` is at any given moment by
131+typing `%` in the Dojo and looking at the first three results.
132+
133+We use `beak`s because, unlike the current internet, the Urbit network uses a
134+global namespace. That means that a file named `example.hoon` in the `/gen`
135+directory on the `%home` desk of your ship `~lodleb-ritrul` would have a
136+universal address to anyone else on the network:
137+`/~lodleb-ritrul/home/186/gen/example/hoon`. That, of
138+course, doesn't mean that everyone on the network has privileges to access that
139+path.
140+
141+The structure that combines a `beak` with further path information is called a
142+`beam`.
143+
144+#### Relative paths
145+
146+The `%` command, which we gestured at in the above section, represents the
147+**relative path**, which is the path where you are currently working. If your
148+working directory is just your home desk, indicated by the
149+prompt `~your-planet:dojo>`, then running the command below will print your
150+working directory's `beam` information: your `beak`, and a `~` that represents
151+the empty list since no path is present.
152+
153+```
154+~your-urbit:dojo> %
155+```
156+
157+`%`s can be stacked to indicate one level further up in the hierarchy for each
158+additional `%`. Try the following command:
159+
160+```
161+~your-planet:dojo> %%%
162+```
163+
164+You'll probably notice that it only has your ship name and the empty list. The
165+two additional `%`s abandoned the `case` and the `desk` information by moving
166+up twice the hierarchy.
167+
168+There are no local relative paths. `/foo/bar` must be written as
169+`%/foo/bar`.
170+
171+#### Substitution
172+
173+You don't need to write out the explicit path every time you want to reference
174+somewhere outside of your working directory. You can substitute `=` for the
175+segments of a path.
176+
177+Recall that a full address in the the Urbit namespace is a `beam`: the
178+`/ship/desk/case/path`. If you've switched to another desk before, you're
179+already familiar with substitution syntax:
180+
181+```
182+~your-urbit:dojo> =dir /=sandbox=
183+```
184+
185+The above command substitutes uses substitution to use your current `ship` and
186+`case`; only the `desk` argument, which is located between the other two, is
187+given something new. Without substitution, you would need to write:
188+
189+```
190+~your-urbit:dojo> =dir /~your-urbit/home/85
191+```
192+
193+Substitutions work the same way in `beak`s (the `ship/desk/case` part) and
194+paths. For example, if you are in the `/gen` directory, you can reference a file
195+in the `/app` directory like below. (`+cat` displays the contents of a file).
196+
197+```
198+~your-urbit:dojo> =dir %/gen
199+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> +cat /===/app/curl/hoon
200+```
201+
202+Note what was substituted out, and note that we don't need to separate `=` with
203+`/`.
204+
205+If we changed our working directory to something called `/gen/gmail`, we could
206+access a file called
207+
208+```
209+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> =dir %/gmail
210+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/gmail> +cat /===/app/=/split/hoon
211+```
212+
213+Because both paths share a directory named `/gmail` at the same position in the
214+address hierarchy -- which, if you recall, is just a `list` -- the above command
215+works!
216+
217+We can do the same thing between desks. If `%sandbox` has been merged with
218+`%home`, the following command will produce the same results as the above
219+command.
220+
221+```
222+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/gmail> +cat /=sandbox=/app/=/split/hoon
223+```
224+
225+Most commonly this is used to avoid having to know the current revision
226+number in the `dojo`: `/~lodleb-ritrul/home/~2018.10.2..00.35.44..d7e8/gen/example/hoon`
227+
228+#### Changing directories
229+
230+Change the working directory with `=dir`. It's our equivalent of the Unix `cd`.
231+
232+For example, the syntax to navigate to `/home/gen/ask` is:
233+
234+```
235+~your-urbit:dojo> =dir /=home=/gen/ask
236+```
237+
238+This command will turn your prompt into something like this:
239+
240+```
241+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/ask>
242+```
243+
244+Using `=dir` without anything else uses the null path, which returns you to
245+your home desk.
246+
247+```
248+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen/ask> =dir
249+```
250+
251+Your dojo prompt will turn back into `~your-urbit:dojo>`.
252+
253+To go up levels in the path hierarchy, recall the relative path expression
254+`%`. Stacking them represents another level higher in the hierarchy than
255+the current working directory for each `%` beyond the initial. The command below
256+brings you one level up:
257+
258+```
259+~your-urbit:dojo> =dir %/gen
260+~your-urbit:dojo/=/=/~2018.10.2..00.35.44..d7e8/gen> =dir %%
261+```
262+
263+### Revision-control
264+
265+#### Mount
266+
267+Syntax: `|mount /clay/path [Unix-name]`
268+
269+Mount the `clay-path` at the Unix mount point `Unix-name`.
270+
271+**Examples:**
272+
273+```
274+|mount %/web
275+```
276+
277+Mounts `%/web` to `/web` inside your pier directory.
278+
279+```
280+|mount %/gen generators
281+```
282+
283+Mounts `%/gen` to `/generators` inside your pier directory.
284+
285+#### Unmount
286+
287+```
288+|unmount [clay-path || Unix-name]
289+```
290+
291+Unmount the path or name from Unix.
292+
293+**Examples:**
294+
295+```
296+|unmount %/web
297+```
298+
299+Unmounts the path `%/web` from whatever name it was mounted as.
300+
301+```
302+|unmount %generators
303+```
304+
305+Unmounts the Unix path `/generators`.
306+
307+#### Merge
308+
309+```
310+|merge desk beak[, =gem strategy]
311+```
312+
313+Merges a `beak` into a `desk` using an optional merge `strategy`.
314+
315+A `beak` is a ship-desk-case triple, encoded as a
316+path(`/~dozbud/home/2`)
317+
318+**Examples:**
319+
320+```
321+|merge %home-work /=home=, =gem %fine
322+```
323+
324+Merge `/=home=` into `%home-work` using merge strategy `%fine`.
325+
326+```
327+|merge %examples ~wacbex-ribmex %examples
328+```
329+
330+Merge the `%examples` desk from `~waxbex-ribmex`
331+
332+#### Sync
333+
334+```
335+|sync desk plot [plot-desk]
336+```
337+
338+Subscribe to continuous updates from remote `plot` on local `desk`.
339+`plot-desk` can specify the remote `desk` name. When omitted it is
340+defaulted to being the same as `desk`. Non-comet urbits have
341+`|sync %home ~parent %kids` automatically set up (where `~parent` is the
342+planet that issued a moon, the star that issued a planet, or the galaxy
343+that issued a star).
344+
345+**Examples:**
346+
347+```
348+|sync %home-local ~dozbud %home
349+
350+|sync %home ~doznec
351+```
352+
353+#### Unsync
354+
355+```
356+|unsync desk plot [plot-desk]
357+```
358+
359+Unsubscribe from updates from remote `plot` on local `desk` with
360+optional `plot-desk`. Arguments must match original `|sync` command.
361+
362+Example:
363+
364+```
365+|unsync %home-local ~dozbud %home
366+```
367+
368+#### Label
369+
370+```
371+|label desk name`
372+```
373+
374+Label the current version of `desk` `name`.
375+
376+Example:
377+
378+```
379+|label %home release
380+```
381+
382+### Merge strategies
383+
384+`%init` - Used if it's the first commit to a desk. Also can be used to
385+"reinitialize" a desk -- revision numbers keep going up, but the new
386+revision isn't necessarily a descendent of the previously numbered
387+version, allowing merges to be rerun.
388+
389+`%this` - Keep what's in Bob's desk, but join the ancestry.
390+
391+`%that` - take what's in Alice's desk, but join the ancestry. This is
392+the reverse of `%this`. This is different from `%init` because the new
393+commit has both sides in its ancestry.
394+
395+`%fine` - "fast-forward" merge. This succeeds if and only if one head is in the
396+ancestry of the other.
397+
398+`%meet`, `%mate`, and `%meld` - find the most recent common ancestor to
399+use as our merge base.
400+
401+A `%meet` merge only succeeds if the changes from the merge base to
402+Alice's head (hereafter, "Alice's changes") are in different files than
403+Bob's changes. In this case, the parents are both Alice's and Bob's
404+heads, and the data is the merge base plus Alice's changed files plus
405+Bob's changed files.
406+
407+A `%mate` merge attempts to merge changes to the same file when both
408+Alice and Bob change it. If the merge is clean, we use it; otherwise, we
409+fail. A merge between different types of changes -- for example,
410+deleting a file vs changing it -- is always a conflict. If we succeed,
411+the parents are both Alice's and Bob's heads, and the data is the merge
412+base plus Alice's changed files plus Bob's changed files plus the merged
413+files.
414+
415+A `%meld` merge will succeed even if there are conflicts. If there are
416+conflicts in a file, then we use the merge base's version of that file,
417+and we produce a set of files with conflicts. The parents are both
418+Alice's and Bob's heads, and the data is the merge base plus Alice's
419+changed files plus Bob's changed files plus the successfully merged
420+files plus the merge base's version of the conflicting files.
421+
422+`%auto` - meta-strategy. Check to see if Bob's desk exists, and if it
423+doesn't we use an `%init` merge. Otherwise, we progressively try
424+`%fine`, `%meet`, and `%mate` until one succeeds. If none succeed, we
425+merge Bob's desk into a scratch desk. Then, we merge Alice's desk into
426+the scratch desk with the `%meld` option to force the merge. Finally, we
427+annotate any conflicts, if we know how.
428+
429+### Manipulation
430+
431+#### +cat
432+
433+Syntax: `+cat path [path ...]`
434+
435+Similar to Unix `cat`. `+cat` takes one or more `path`s, and prints their
436+contents. If that `path` is a file, the contents of the file is printed. If the
437+`path` terminates in a directory, the list of names at that path is produced.
438+
439+#### +ls
440+
441+Syntax: `+ls path`
442+
443+Similar to Unix `ls`. `+ls` takes a single `path`.
444+
445+Produces a list of names at the `path`.
446+
447+```
448+~your-urbit:dojo> +cat %/our/home/gen/curl/hoon
449+```
450+
451+#### |rm
452+
453+Syntax: `|rm path`
454+
455+Remove the data at `path`. `path` must be a path to actual node, not a
456+'directory'
457+
458+#### |cp
459+
460+Syntax: `|cp to from`
461+
462+Copy the file at `from` into the path `to`.
463+
464+#### |mv
465+
466+Syntax: `|mv to from`
467+
468+Move the file at `from` into the path `to`.
469+
470+In Clay, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
471+doesn't happen unless the `|cp` succeeds.
using/messaging.mdnew file+315
@@ -0,0 +1,315 @@
1++++
2+title = "Messaging"
3+weight = 2
4+template = "doc.html"
5++++
6+
7+Chat (also called "chat-cli") is the built-in messaging app for Urbit.
8+
9+For the time being come join us in `~dopzod/urbit-help` by using the
10+'quickstart' section below. `~dopzod` is the host ship, and `/urbit-help` is the
11+channel on that ship.
12+
13+### Quickstart
14+
15+The most common uses of `:chat-cli` right now are communicating over a public chat channel on `~dopzod/urbit-help`, and sending direct messages. Everyone is more than welcome in `~dopzod/urbit-help`. It's the place to get help, ask questions and chat about Urbit in general.
16+
17+There are two ways of using `:chat-cli`: from the terminal running the Urbit process, or through the Landscape web UI available from your ship’s URL address, mentioned earlier in this guide.
18+
19+### Joining a chat
20+
21+In `:chat-cli`, any kind of medium for a message is called a _chat_. There are four types of chats: the _channel_ (public with blacklist), _village_ (private with whitelist), the _journal_ (publicly readable, privately writable), and the _mailbox_ (privately readable, publicly writable). But for now we'll be dealing with the _channel_, a publicly accessible chatroom for general use. We'll discuss the other three kinds in the [manual](#messaging-manual) section later on.
22+
23+Let's join the `~dopzod/urbit-help` channel. Use `ctrl-x` to switch from the Dojo prompt to the Chat prompt.
24+
25+Then:
26+
27+```
28+~your-urbit:chat-cli> ;join ~dopzod/urbit-help
29+```
30+
31+Scrolling down your terminal window, you'll probably see a playback of previous `~dopzod/urbit-help` messages that you missed. You c
32+
33+Post a line to `~dopzod/urbit-help:`
34+
35+```
36+~your-urbit:chat-cli= Hello, world!
37+```
38+
39+You'll see your message printed below messages from others that came before it. You can always type `;chats` in the `chat-cli` prompt to list all the chats you're in:
40+
41+
42+
43+Glyphs will be automatically assigned to channels, but have the option of binding a glyph (single non-alphanumeric character) to the channel you're joining; the syntax is in the form of `;join ~dopzod/books +`. The chosen glyph will be the symbol that ends your prompt, and it will be what you use as a shortcut to switch to this channel.
44+
45+```
46+~your-urbit:chat-cli= ;+
47+~your-urbit:chat-cli+
48+```
49+
50+Use `;leave` to unsubscribe from a channel:
51+
52+```
53+~your-urbit:chat-cli= ;leave ~dopzod/urbit-help
54+```
55+
56+Now, let's create a channel we can invite some friends to:
57+
58+```
59+~your-urbit:chat-cli= ;create channel /my-channel
60+```
61+
62+Now you can tell your friends to `;join ~your-urbit/my-channel`.
63+
64+### Direct messaging
65+
66+To send a direct message to someone, first set your audience:
67+
68+```
69+~your-urbit:chat-cli= ;~talsur-todres
70+```
71+
72+You'll see your prompt change:
73+
74+```
75+~your-urbit:chat-cli[~talsur-todres]
76+```
77+
78+Now you and `~talsur-todres` can exchange messages directly.
79+
80+```
81+~your-urbit:chat-cli[~talsur-todres] Hey buddy!
82+```
83+
84+To set your audience back to `~dopzod/urbit-help`:
85+
86+```
87+~your-urbit:chat-cli[~talsur-todres] ;~dopzod/urbit-help
88+```
89+
90+You'll see your prompt change back:
91+
92+```
93+~your-urbit:chat-cli=
94+```
95+
96+#### Hoon
97+
98+You can use Chat to evaluate Hoon code and share the results with everyone in a chat. To do so, preface your Hoon with `#`.
99+
100+```
101+~your-urbit:chat-cli= #(add 2 2)
102+```
103+
104+will print as
105+
106+```
107+~your-urbit# (add 2 2)
108+4
109+```
110+
111+### Creating and managing chats
112+
113+As mentioned before, any urbit can host any number of chats. Existing chats can be deleted or modified with various commands. All commands in this section should be sent from the `chat-cli>` prompt.
114+
115+#### Create
116+
117+Syntax: `;create [type] /name +`, where `+` represents an optional glyph.
118+
119+Creates and joins a chat, where `[type]` is any of the following:
120+- `channel`: public chat. Has a blacklist for write control.
121+- `village`: invite-only chat.
122+- `journal`: publicly readable, invite-only for writing.
123+- `mailbox`: publicly writeable, can only be read by its host.
124+
125+Let's create an example mailbox:
126+
127+```
128+sampel-palnet:chat-cli> ;create mailbox /coolbox ^
129+```
130+
131+#### Delete
132+
133+Syntax: `;delete /name`
134+
135+Deletes a chat.
136+
137+### Status
138+
139+You'll see status notifications when people enter or leave chats you're subscribed to.
140+
141+#### Notifications off
142+
143+Syntax: `;set quiet`
144+
145+Turn off status (and config) notifications.
146+
147+#### Notifications on
148+
149+Syntax: `;unset quiet`
150+
151+Turn on status (and config) notifications.
152+
153+#### Chat glyphs
154+
155+Glyphs are found at the end of your prompt to as a quick indicator of where
156+your messages will be sent.
157+
158+Glyphs are assigned by chat hash out of the following list:
159+
160+```
161+> = + - } ) , . " ' ^ $ % & @
162+```
163+
164+Alphanumeric characters and `|#;:*~_` are reserved; all others (the
165+above list, and `\/!?({<`) can be manually assigned.
166+
167+For example, `-` the glyph at the end of the prompt below might indicates that
168+messages sent from this prompt will go to some chat with that glyph:
169+
170+```
171+~sampel-palnet:chat-cli-
172+```
173+
174+To see what chat is bound to a glyph, use the `;what` command followed by the
175+glyph in question, or use `;what` without specifying a glyph to see all of your
176+subscriptions which are bound to glyphs. For example, to see `=`:
177+
178+```
179+~sampel-palnet:chat-cli> ;what =
180+~dopzod/urbit-help
181+```
182+
183+To see all of your glyph-bound subscriptions:
184+
185+```
186+~sampel-palnet:chat-cli> ;what
187+> ~paldev/numismatic-forum
188+. ~middev/ny-martians
189+= ~dopzod/urbit-help
190+```
191+
192+Not every audience has a glyph, however. When the audience doesn't have a glyph,
193+such as in the case of direct-messaging a ship, we see their name at the end of
194+the prompt instead. Here we're talking directly to `~dannum-mitryl`:
195+
196+```
197+~sampel-palnet:chat-cli[~dannum-mitryl]
198+```
199+
200+#### Bind
201+
202+Syntax: `;bind [glyph] /chat-name`
203+
204+Assigns the chosen glyph to a chat owned by your ship.
205+
206+For example:
207+
208+```
209+~sampel-palnet:chat-cli> ;bind + /my-chat
210+```
211+
212+#### Unbind
213+
214+Syntax: `;unbind [glyph] /chat-name`
215+
216+Unassigns the chosen glyph from a chat owned by your ship.
217+
218+For example:
219+
220+```
221+~sampel-palnet:chat-cli> ;unbind + /my-chat
222+```
223+
224+#### Prefixes
225+
226+Received posts are prefixed with a glyph to let you know what the
227+audience is. You can activate an individual post to see the full
228+audience.
229+
230+There are a few special-purpose glyphs:
231+
232+- `|` - Informational messages
233+- `:` - Posts directly to you
234+- `;` - Posts to you and others (a multiparty conversation)
235+- `*` - Posts to a complex audience that doesn't directly include you.
236+
237+
238+### Configuration
239+
240+#### Set audience
241+
242+`;~ship/chat`
243+
244+Set audience to `~ship/chat`.
245+
246+#### Set audience by glyph
247+
248+Syntax: `;[glyph]`
249+
250+Set audience to the chat previously bound to the chosen glyph.
251+
252+#### Set audience to ship
253+
254+syntax `;~ship`
255+
256+Set audience to another ship.
257+
258+#### Set audience to own chat
259+
260+Syntax: `;%chat`
261+
262+Set audience to a chat on your own ship.
263+
264+#### Set audience and send message
265+
266+Syntax: `;~dannum-mitryl this is a private message`
267+
268+Set the audience and send a post in the same line. This works for all of the
269+above audience commands.
270+
271+Your audience is configured with regard to the following rules (in order):
272+
273+- if you manually set the audience, that audience.
274+- if you activated a post, the post you activated.
275+- audience of the last post sent.
276+
277+### Miscellaneous configuration
278+
279+#### Show timestamps
280+
281+Syntax: `;set showtime`
282+
283+Show the timestamp for each message. This is set by default.
284+
285+#### Hide timestamps
286+
287+Syntax: `;unset showtime`
288+
289+Stop showing the timestamp for each message.
290+
291+#### Change timezone
292+
293+Syntax: `;set timezone [+/-][hours]`
294+
295+Adjust the display of timestamps to a specific timezone. Relative to UTC.
296+
297+#### Sound notification on
298+
299+Syntax: `;set notify`
300+
301+Emit a terminal bell sound if your six-syllable ship name is mentioned in
302+a message. This is set by default.
303+
304+#### Sound notification off
305+
306+Syntax `;unset notify`
307+
308+Do not notify when your ship name is mentioned.
309+
310+#### Set width
311+
312+Syntax: `;set width [number]`
313+
314+Set the rendering width of `:chat-cli` to a specific number of characters.
315+(Minimum of 30.)
using/operating-a-star.mdnew file+49
@@ -0,0 +1,49 @@
1++++
2+title = "Operating a Star"
3+weight = 6
4+template = "doc.html"
5++++
6+A _ship_ is an instance of the Arvo operating system that is used as a personal server on the Arvo network. Stars are a type of ship that act as infrastructure for the Arvo network. In the Arvo ship-hierarchy, stars are below galaxies and above planets.
7+
8+Parallel to the Arvo network is Azimuth, the Urbit identity system that uses the Ethereum blockchain. All ships must boot with a corresponding _point_ -- an Azimuth identity -- to use the Arvo network.
9+
10+Important star operations happen on both the Arvo side and the Azimuth side. On the Arvo side, these operations come in the form of Dojo commands. On the Azimuth side, operations happen by making changes to smart-contracts on the blockchain via a point.
11+
12+## Powers of a Star
13+
14+Stars are above planets in the network hierarchy in the sense that each star sponsors some number of planets: stars discover peers for planets, route packets for planets, provide DNS routing for planets, and push software updates to planets. A star that fulfills this is called the **sponsor** of planets that receive such services from the star; those planets, in turn, are called **dependents** of that star.
15+
16+Stars are also the "parents" of planets. A new planet comes into existence only when spawned by a parent star. A parent planet is the sponsor of its children planets by default. This can change if a planet chooses to find a new sponsor (see the "Escaping a Sponsor" section below).
17+
18+Planets must have a sponsor star to use most features of the Arvo network. A planet cannot boot without a sponsor, and cannot make new connections to peers as long as it is not connected to a sponsor. Planets without a sponsor will still be able to message discovered peers until any such peers change their IP addresses.
19+
20+## Responsibilities
21+
22+Like with real-life infrastructure, the operation of Arvo infrastructure comes with unique responsibilities. For reasons stated above, stars should be always be online on a reliable cloud service, such as Amazon Web Services or Google Cloud Platform. These systems have layers of redundancies that make them much more resilient than local machines, so stars hosted on the cloud are unlikely to leave their dependents in the dark.
23+
24+## Operations
25+
26+Below are some handy operations for the use and maintenance of your star.
27+
28+### arvo.network DNS Records
29+
30+We have a system that lets users request a domain name for their star under `arvo.network`, in the form of `shipname.arvo.network`, where `shipname` is their ship's name, so that it can be accessed remotely via our Landscape web interface. To find out how to do this, take a look at the [DNS Proxying](../dns-proxying) documentation.
31+
32+### Maintaining Connectivity
33+
34+Occasionally, your star might lose network connectivity due to a known timer issue or by falling out of sync with the Ethereum blockchain. When this happens, there are a few things to try:
35+
36+1. Enter the `|bonk` command in the Dojo to reset the timer and restore connectivity.
37+2. Run `|start %eth-manage`, then `:eth-manage %look-ethnode` to ensure that your star is synced up to the latest block.
38+
39+When in doubt, contact [support@urbit.org](mailto:support@urbit.org).
40+
41+### Escaping a Sponsor
42+
43+Planets are, of course, able to change sponsors. To do this, they must request that a different star takes them on as a dependent and that star must accept the request. Planets cannot emancipate themselves from a sponsor without having a new sponsor lined up.
44+
45+All of these actions happen on Azimuth. There will be Bridge functionality to handle these actions in the future, but for now users will need to interact directly with the contracts with MetaMask, through services such as [Etherscan.io](https://etherscan.io/address/ecliptic.eth#writeContract). A sketch of the process is listed below; for now, only the Ethereum-savvy should act on these steps.
46+
47++ The planet calls the `escape` function in the Ecliptic contract and writes the resulting data to the blockchain.
48++ If the chosen star wants to become the planet's sponsor, it calls the `adopt` function in the Ecliptic contract.
49++ The Arvo network notices the change, and the operation is complete.
arvo/sail-and-udon.md → using/sail-and-udon.mdrenamed

The content is the same.

using/shell.mdnew file+440
@@ -0,0 +1,440 @@
1++++
2+title = "Shell"
3+weight = 4
4+template = "doc.html"
5++++
6+The Dojo is our shell; it processes system commands and returns output. It's a
7+good place to quickly experiment with Urbit. On the surface the Dojo is just a
8+Hoon REPL. On the inside, the Dojo is a system for operating on and transforming
9+data in Urbit.
10+
11+
12+## Quickstart
13+
14+You can use the Dojo to run arbitrary Hoon code, as well as non-Hoon system
15+commands.
16+
17+### Math
18+
19+Evaluate a Hoon expression (whitespace matters):
20+
21+```
22+~your-urbit:dojo> (add 2 2)
23+~your-urbit:dojo> %+ add 2 2
24+```
25+
26+Tall-form Hoon may require multiple lines:
27+
28+```
29+~your-urbit:dojo> %+ add
30+~your-urbit:dojo< 2
31+~your-urbit:dojo< 2
32+```
33+
34+Hoon uses something called [the subject](@/docs/learn/hoon/hoon-tutorial/the-subject-and-its-legs.md).
35+The Dojo has its own subject, and that's where Hoon's equivalent of variables,
36+called faces, are stored.
37+
38+Use `=var` to save faces to the Dojo subject.
39+
40+```
41+~your-urbit:dojo> =foo (add 2 2)
42+```
43+
44+Note, however, that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a
45+face in a `.hoon` file in this way.
46+
47+### System Commands
48+
49+Use `=dir` to set the current working directory:
50+
51+```
52+~your-urbit:dojo> =dir %/web
53+```
54+
55+(`%` represents your current directory. For a complete explanation on urbit
56+paths, see the [filesystem section](@/docs/using/filesystem.md))
57+
58+Generators (files in `/gen`) are run with `+`:
59+
60+```
61+~your-urbit:dojo> +hello 'world'
62+```
63+
64+Save output to a file in `%clay` with `*`:
65+
66+```
67+~your-urbit:dojo> *some/file/path/hoon 'hello world'
68+```
69+
70+Run system commands from `:hood`, like `reload`, using `|`:
71+
72+```
73+~your-urbit:dojo> |reload %eyre
74+```
75+
76+## Generators
77+
78+Generators are short Hoon scripts, saved as `.hoon` files in the `/gen`
79+directory. Many Dojo commands exist in the form of generators. The syntax for
80+running a generator is `+genname` for a generator saved as `genname.hoon`.
81+
82+### +cat
83+
84+Accepts a path and displays the file. Similar to Unix `cat`.
85+
86+```
87+~your-urbit:dojo> +cat %/gen/curl/hoon
88+```
89+
90+### +code
91+
92+Generates a code that is used to remotely log into your ship. No
93+arguments.
94+
95+```
96+~your-urbit:dojo> +code
97+```
98+
99+### +curl
100+
101+Retrives data from a URL. Accepts a `tape`. Similar to Unix `curl`.
102+
103+```
104+~your-urbit:dojo> +curl "http://nyt.com"
105+```
106+
107+### +hello
108+
109+Just prints the argument. Accepts a `@ta`.
110+
111+```
112+~your-urbit:dojo> +hello 'mars'
113+```
114+
115+### +ls
116+
117+Similar to Unix `ls`. Accepts a path.
118+
119+```
120+~your-urbit:dojo> +ls %/web
121+~your-urbit:dojo> +ls /~talsur-todres/home/2/web/notes
122+```
123+
124+### +moon
125+
126+Generates a random moon from a planet. No arguments.
127+
128+```
129+~your-urbit:dojo> +moon
130+```
131+
132+### +solid
133+
134+Compile the current state of the kernel and output a
135+noun. Usually downloaded to a file in unix. No arguments.
136+
137+```
138+~your-urbit:dojo> .urbit/pill +solid
139+```
140+
141+### +test
142+
143+Testrunner. Can test multiple generators at once, conventionally ones
144+in the `/test` folder. Takes a path.
145+
146+```
147+~your-urbit:dojo> +test /lib
148+```
149+
150+### +ticket
151+
152+Generate a ticket for an urbit ship. Takes an urbit name (`@p`).
153+
154+
155+```
156+~your-urbit:dojo> +ticket ~talsur-todres-your-urbit
157+```
158+
159+### +tree
160+
161+Generate a recursive directory listing. Takes a path.
162+
163+```
164+~your-urbit:dojo> +tree %/web
165+```
166+
167+## Hood
168+
169+The hood is the system daemon. See `gen/hood` and `app/hood`.
170+
171+`|hi` - Sends a direct message. Sort of like Unix `write`. Accepts
172+an urbit name (`@p`) and a string (`tape`, which is text wrapped with double-quotes).
173+
174+```
175+~your-urbit:dojo> |hi ~binzod "you there?"
176+```
177+
178+`|link` / `|unlink` - Link / unlink a remote app. Accepts an
179+Urbit name and an app name.
180+
181+```
182+~your-urbit:dojo> |link ~talsur-todres %octo
183+```
184+
185+`|mass` - Prints the current memory usage of all the kernel modules.
186+No arguments.
187+
188+```
189+~your-urbit:dojo> |mass
190+```
191+
192+`|reload` - Reloads a kernel module (vane) from source. Accepts any
193+number of vane names.
194+
195+```
196+~your-urbit:dojo> |reload %clay %eyre
197+```
198+
199+`|reset` - Reloads `hoon.hoon` and all modules. No arguments.
200+
201+```
202+~your-urbit:dojo> |reset
203+```
204+
205+`|start` - Starts an app. Accepts an app name.
206+
207+```
208+~your-urbit:dojo> |start %curl
209+```
210+
211+---
212+
213+## Manual
214+
215+## Sources and sinks
216+
217+A Dojo command is either a **source** or a **sink**. A source is just something
218+that can be printed to your console or the result of some computation. A
219+sink is an **effect**: a change to the filesystem, a network message, a
220+change to your environment, or typed message to an app.
221+
222+Sources can be chained together, but we can only produce one effect per
223+command.
224+
225+### Sinks
226+
227+#### `=` - Set variable
228+
229+Set any environment variable:
230+
231+```
232+~your-urbit:dojo> =foo 42
233+~your-urbit:dojo> (add 2 foo)
234+
235+44
236+```
237+
238+Make sure to note that `=var` is Dojo syntax, not Hoon syntax. You cannot bind a
239+variable in a `.hoon` file in this way.
240+
241+#### Special Variables
242+
243+There are a few special variables that the Dojo maintains.
244+
245+#### `:` - Send to app
246+
247+`:app` goes to a local `app`, `:~ship/app` goes to the `app` on `~ship`.
248+
249+Send a `helm-hi` message to `hood`:
250+
251+```
252+~your-urbit:dojo> :hood &helm-hi 'hi'
253+```
254+
255+Apps usually expect marked data, so `&` is often used here.
256+
257+#### `*` - Save in `%clay`
258+
259+Save a new `.udon` ([Udon](@/docs/using/sail-and-udon.md)) file in `web`:
260+
261+```
262+~your-urbit:dojo> *%/web/foo/udon '# hello'
263+```
264+
265+The last component of the path is expected to be the mark (or mime
266+type).
267+
268+#### `.` - Export to Unix
269+
270+Export a noun to Unix with `.`:
271+
272+```
273+~your-urbit:dojo> .foo/bar/baz (add 2 2)
274+```
275+
276+Which creates a file at `pier/.urb/put/foo/bar.baz`.
277+
278+This is very often used with `+solid`:
279+
280+```
281+~your-urbit:dojo> .urbit/pill +solid
282+```
283+
284+Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`
285+
286+### Sources
287+
288+#### `&` - Mark conversion
289+
290+Convert between marks using `&`, with the destination mark first. You can stack multiple mark conversions together, and some marks can only be converted to specific other marks. In this example, [Udon](@/docs/using/sail-and-udon.md#udon) is converted to `&hymn` (a mark which supplies the `html`, `head`, `body` and closing tags) first, before being converted to HTML:
291+
292+```
293+~your-urbit:dojo>&html &hymn &udon ';h1#hello: hello'
294+'<html><head></head><body><h1 id="hello">hello</h1></body></html>'
295+```
296+
297+Performing a conversion straight from Udon to the `&hymn` mark reveals a bit more about its mark conversion:
298+
299+```
300+~your-urbit:dojo>&hymn &udon ';h1#hello: hello'
301+[[%html ~] [[%head ~] ~] [[%body ~] [g=[n=%h1 a=~[[n=%id v="hello"]]] c=~[[g=[n=%$ a=~[[n=%$ v="hello"]]] c=~]]] ~] ~]
302+```
303+
304+As does converting straight from Udon to HTML:
305+
306+```
307+~your-urbit:dojo>&html &udon ';h1#hello: hello'
308+';h1#hello: hello'
309+```
310+
311+#### `_` - Run a function
312+
313+Use `_` to run a gate (or function):
314+
315+Write an arbitrary function and pass data to it:
316+
317+```
318+~your-urbit:dojo> _|=([a=@] (mul a 3)) 3
319+9
320+```
321+
322+Use a function to get the status code from an http request:
323+
324+```
325+~your-urbit:dojo> _|=([p=@ud q=* r=*] p) +http://google.com
326+301
327+```
328+
329+#### `+` `-` - HTTP requests
330+
331+`+http[s]://example.com` - sends a GET request
332+
333+`+http[s]://example.com &json [%s 'hi']` - sends a POST request with the
334+JSON `"hi"` in the body.
335+
336+`-http[s]://example.com &json [%s 'hi']` - sends a PUT request with the
337+JSON `"hi"` in the body.
338+
339+Note that the first of these is a source while the last two are sinks.
340+
341+#### `+` - Generators
342+
343+Generators are simple Hoon scripts loaded from the filesystem. They live
344+in `gen/`.
345+
346+An example of a generator that is built into your urbit is `+code`. It produces
347+the code needed to log into your ship remotely.
348+
349+```
350+~your-urbit:dojo> +code
351+fintyr-haldet-fassev-solhex
352+```
353+
354+### Variables
355+
356+You can use `=` to set an environment variable in Dojo, but there are
357+a few reserved names that have special uses.
358+
359+#### dir
360+
361+Current working `%clay` desk and revision. Read / write.
362+
363+**Examples:**
364+
365+```
366+~your-urbit:dojo> =dir %/web
367+~your-urbit:dojo> +ls %
368+404/hoon docs/ dojo/hoon lib/ listen/hoon md static/udon talk/ testing/udon tree/main/ unmark/ womb/
369+```
370+
371+#### lib
372+
373+Current set of libraries (`/lib`) in your environment. Can be set
374+with `/+`. Read / write.
375+
376+**Examples:**
377+
378+```
379+~your-urbit:dojo> /+ number-to-words
380+```
381+Now we can use arms from lib/number-to-words.hoon
382+```
383+~your-urbit:dojo> (to-words:eng-us:number-to-words 123.456)
384+```
385+
386+#### sur
387+
388+Current set of structures (`/sur`) in your environment. Can be set
389+with `/-`. Read / write.
390+
391+**Examples:**
392+
393+```
394+~your-urbit:dojo> /- sole
395+```
396+Now we can use arms in sur/sole.hoon.
397+```
398+~your-urbit:dojo> `sole-effect:sole`[%bel ~]
399+```
400+
401+#### now
402+
403+The current (128-bit `@da`) time. Read-only.
404+
405+**Example:**
406+
407+```
408+~your-urbit:dojo> now
409+~2016.3.21..21.10.57..429a
410+```
411+
412+#### our
413+
414+The current urbit ship. Read-only.
415+
416+**Example:**
417+
418+```
419+~your-urbit:dojo> our
420+~your-urbit
421+```
422+
423+#### eny
424+
425+512 bits of entropy. Read-only.
426+
427+**Example:**
428+
429+```
430+~your-urbit:dojo> eny
431+\/0vnt.d474o.gpahj.jcf3o.448fh.2lamb.82ljm.8ol8u.b02vi.mrvvp.b7et2.knb7m.l8he\/
432+ 8.8qb9s.drm36.77n9b.a0qst.30g03.l5lb5.nvsbc.v39tn
433+\/
434+```
435+
436+## Troubleshooting
437+
438+If you encounter `%dy-edit-busy` while entering commands, it is
439+because your Dojo is blocked on a timer or an HTTP request. Type backspace
440+and your Dojo will end the blocked command.
arvo/ship-troubleshooting.md → using/ship-troubleshooting.mdrenamed

The content is the same.