@@ -4,10 +4,69 @@ template = "page_indiced.html"
4slug = "/operations/"
4slug = "/operations/"
7−## Admin and Operations {#urbit-administration}
7+## Using Bridge {#using-bridge}
9+[Bridge](https://github.com/urbit/bridge) is the application we built for interacting with [Azimuth](https://azimuth.network), the Urbit PKI, and managing your Urbit ID. 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.
11+This guide assumes that you have an Urbit ID, or that you have found someone to send an Urbit ID to your Ethereum address and are looking to claim it.
15+To connect to Bridge, go to [https://bridge.urbit.org](https://bridge.urbit.org) into your browser, and enter your identity's credentials in the appropriate fields. If you were invited to claim an Urbit ID, 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.
17+Once you arrive proceed through the steps presented. 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 and proceed to [install the Urbit binary](@/install.md).
21+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 on GitHub](https://github.com/urbit/bridge/releases/). Download the `.zip` file of the latest version. After you download it, follow the instructions below.
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.`
30+You can then use the Bridge app by navigating to `http://localhost:5000` in your internet browser.
32+Note: Bridge allows you to 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.
34+Once the program is running in your browser, go through the steps presented according to the type of wallet you have. You’ll be presented with a few login options. 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 require you to set your own networking keys.
36+### Accept Your Transfer
38+If you were given points by Tlon you likely already fully own them. But if someone else sent you a point, then you will first need to use Bridge to accept that transfer.
40+After you access your Ethereum address, if a point was sent to that address, you'll come to a page that has an `Incoming Transfers` header, under which is a graphic. Click the `Details ->` link under that graphic.
42+Now you'll be on the management page of your point. The transfer isn't completed yet, so click `Accept incoming transfer`. Then check both boxes and and click their associated `Sign Transaction` and `Send Transaction` buttons.
44+If you already own a point, click on the `Details ->` under your sigil in the `Your Points` section.
46+### Set Your Networking Keys
48+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!
50+Click the link that says `Set network keys`. The field presented in the resulting page expects a 32-byte hexadecimal string. If it's filled already, no action is required. If it 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
53+hexdump -n 32 -e '4/4 "%08X"' /dev/random
58+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.
60+### Generate Your Keyfile
62+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 it's not filled in or does not match, fill it in with the correct string.
63+Click `Generate ->`, which will download a keyfile onto your machine.
65+With that keyfile in hand, you can now exit Bridge and continue to the guide to [install the Urbit binary](@/install.md).
67+## Using Your Ship {#urbit-administration}
9−Your urbit (also called your _ship_) is a persistent Unix process that you
69+Your urbit (also called your _ship_) is a persistent Unix process that you mainly control from the console.
10−mainly control from the console. For some things, a browser will also work.
12### Shutdown
71### Shutdown
@@ -19,63 +78,56 @@ You can force-quit your urbit with `Ctrl-z` from anywhere.
20To restart your urbit simply pass the name of your pier:
79To restart your urbit simply pass the name of your pier:
23−$ urbit some-planet
82+$ ./urbit some-planet
29−$ urbit comet
88+$ ./urbit comet
32### Logging
91### Logging
34To log an urbit's command line output to a file, use `script`:
93To log an urbit's command line output to a file, use `script`:
37−$ script urbit.log urbit your-urbit
96+$ script urbit.log ./urbit your-urbit
40### Moving your pier
99### Moving your pier
42Piers are designed to be portable, but it _must_ be done while the urbit
101Piers are designed to be portable, but it _must_ be done while the urbit
43−is turned off. Urbit networking is stateful, so you can't run two copies
102+is not running. Urbit networking is stateful, so you can't run two copies
44of the same urbit in two places.
103of the same urbit in two places.
46To move a pier, simply move the contents of the directory it lives in.
105To move a pier, simply move the contents of the directory it lives in.
47To keep these files as small as possible we usually use the `--sparse`
106To keep these files as small as possible we usually use the `--sparse`
48option in `tar`. With a pier `your-urbit/`, something like this should work:
107option in `tar`. With a pier `your-urbit/`, something like this should work:
51tar -Scvzf ~/your-urbit.tar.gz ~/your-urbit/
110tar -Scvzf ~/your-urbit.tar.gz ~/your-urbit/
52scp your-old-server:~/your-urbit.tar.gz your-new-server:~
111scp your-old-server:~/your-urbit.tar.gz your-new-server:~
55Then to unzip it, on your other Unix server, run:
114Then to unzip it, on your other Unix server, run:
58tar xfvz your-urbit.tar.gz
117tar xfvz your-urbit.tar.gz
61−Delete the tar file, and, after installing Urbit on your new server,
120+Delete the tar file, and, after installing Urbit on your new server, start your urbit back up with:
62−start your urbit back up with:
65−urbit your-urbit
123+./urbit your-urbit
68### Console
126### Console
70−Your Urbit terminal is separated into two parts: the prompt (the bottom
128+Your Urbit terminal is separated into two parts: the prompt (the bottom line) and the record (everything above that). The record is shared; all the output from all the apps in your command set appears in it. The prompt is multiplexed.
71−line) and the record (everything above that). The record is shared; all
72−the output from all the apps in your command set appears in it. The
73−prompt is multiplexed.
75−In the CLI, Urbit apps can process your input before you hit return. To
130+In the CLI, Urbit apps can process your input before you hit return. To see this in action try entering `)` as the first character at the Dojo prompt. Since there is no Dojo command or Hoon expression that starts with ')', the Dojo rejects it.
76−see this in action try entering `)` as the first character at the Dojo
77−prompt. Since there is no Dojo command or Hoon expression that starts
78−with ')', the Dojo rejects it.
80`Ctrl-x` - Switches the prompt between running console apps
132`Ctrl-x` - Switches the prompt between running console apps
@@ -94,10 +146,10 @@ The following emacs-style key bindings are available:
94Ctrl-a Cursor to beginning of the line (Home)
146Ctrl-a Cursor to beginning of the line (Home)
95Ctrl-b Cursor one character backward (left-arrow)
147Ctrl-b Cursor one character backward (left-arrow)
96Ctrl-e Cursor to the end of the line (End)
148Ctrl-e Cursor to the end of the line (End)
97−Ctrl-f Cursor one character forward (right-arrow)
149+Ctrl-f Cursor one character forward (right-arrow)
98Ctrl-g Beep; cancel reverse-search
150Ctrl-g Beep; cancel reverse-search
99Ctrl-k Kill to end of line
151Ctrl-k Kill to end of line
100−Ctrl-l Clear the screen
152+Ctrl-l Clear the screen
101Ctrl-n Next line in history (down-arrow)
153Ctrl-n Next line in history (down-arrow)
102Ctrl-p Previous line in history (up-arrow)
154Ctrl-p Previous line in history (up-arrow)
103Ctrl-r Reverse-search
155Ctrl-r Reverse-search
@@ -106,26 +158,15 @@ Ctrl-u Kill to beginning of line
106Ctrl-y Yank from kill buffer
158Ctrl-y Yank from kill buffer
109−### Web
161+### Landscape
111−On startup Urbit tries to bind to `localhost:80`. If you're already
112−running something on port `80` -- such as any other HTTP server, or another urbit -- you'll find the urbit
163+On startup Urbit tries to bind to `localhost:80`. If you're already running something on port `80` -- such as any other HTTP server, or another urbit -- you'll find the urbit that you just started on `8080`, `8081`, and so on. For planets only, we also proxy web domains through Urbit's own servers. Any planet `~your-urbit` is also at `your-urbit.arvo.network`, but only after you [set up DNS](#dns-proxying).
113−that you just started on `8080`, `8081`, and so on. For planets only, we also proxy web
114−domains through Urbit's own servers. Any planet `~your-urbit` is also at
115−`your-urbit.arvo.network`, but only after you [set up DNS](../dns-proxying).
117−Your urbit serves a simple homepage from `http://localhost` or
165+Once running, you can sign into Landscape, your ship’s web interface, from `http://localhost` or `https://your-urbit.arvo.network`. Since our HTTPS isn't audited / battle tested, we just call it "secure" HTTPS. You can find that on `8443`. Or `8444` (and so on) if you're already running something on `8443`.
118−`https://your-urbit.arvo.network` that should be self-explanatory. Since
119−our HTTPS isn't audited / battle tested, we just call it "secure" HTTPS.
120−You can find that on `8443`. Or `8444` (and so on) if you're already
121−running something on `8443`.
123### Moons {#moons}
167### Moons {#moons}
125−Planets can spawn moons, which are meant for connected devices: phones, smart
169+Planets can spawn moons, which are meant for connected devices: phones, smart TVs, digital thermostats. The basic idea is that your planet runs permanently in a data center somewhere, while moons run on all your devices. Each planet can issue ~4 billion (`2^32`) moons.
126−TVs, digital thermostats. The basic idea is: your planet runs permanently in a
127−data center somewhere and moons run on all your devices. Each planet can issue
128−~4 billion (`2^32`) moons.
130To generate a random moon from your planet, run:
171To generate a random moon from your planet, run:
@@ -138,8 +179,7 @@ moon: ~faswep-navred-sampel-palnet
141−You must manually edit the output of `+moon` to get
182+You must manually edit the output of `+moon` to get the correct format for the `<key>`:
142−the correct format for the `<key>`:
144- strip out the `\/`
184- strip out the `\/`
@@ -159,20 +199,18 @@ Another way of generating `<keyfile>` is:
159moon: ~faswep-navred-sampel-palnet
199moon: ~faswep-navred-sampel-palnet
162−`<keyfile>` will be at `path/to/sampel-palnet/.urb/put/moon.key`
202+`<keyfile>` will be at `path/to/sampel-palnet/.urb/put/moon.key` and does not need editing to be used with the `-k` option.
163−and does not need editing to be used with the `-k` option.
165−You can use the resulting output in the same installation flow from the
166−[Booting a Ship](@/install.md) guide, following the same scheme as for booting a planet. That scheme is:
204+You can use the resulting output in the same installation flow from the [Installing Urbit](@/install.md) guide, following the same scheme as for booting a planet. That scheme is:
169−$ urbit -w <moonname> -G <key> -c <piername>
207+$ ./urbit -w <moonname> -G <key> -c <piername>
175−$ urbit -w <moonname> -k <keyfile> -c <piername>
213+$ ./urbit -w <moonname> -k <keyfile> -c <piername>
178The `-c <piername>` argument is not required, but it is recommended; otherwise,
216The `-c <piername>` argument is not required, but it is recommended; otherwise,
@@ -180,37 +218,28 @@ the resulting directory is a rather unwieldy moon name.
181Here's how an example moon might be booted:
219Here's how an example moon might be booted:
184−$ urbit -w faswep-navred-sampel-palnet -G <key> -c mymoon
222+$ ./urbit -w faswep-navred-sampel-palnet -G <key> -c mymoon
190−$ urbit -w faswep-navred-sampel-palnet -k <keyfile> -c mymoon
228+$ ./urbit -w faswep-navred-sampel-palnet -k <keyfile> -c mymoon
193−Moons are automatically synced to their parent `%kids` desk, and can control
231+Moons are automatically synced to their parent `%kids` desk, and can control applications on their parent planet using `|link`.
194−applications on their parent planet using `|link`.
196### Continuity breaches
233### Continuity breaches
198−While the Urbit network is in this alpha state, we sometimes have to
199−reboot the whole network. This happens either when major changes need
235+While the Urbit network is in this alpha state, we sometimes have to reboot the whole network. This happens either when major changes need to be shipped or we hit a bug that can't be fixed over the air.
200−to be shipped or we hit a bug that can't be fixed over the air.
202−Because Urbit networking is stateful we call this a _continuity breach_.
237+Because Urbit networking is stateful we call this a _continuity breach_. Everything has to be restarted from scratch. Your pier will continue to function after we have breached, but it won’t connect to the rest of the Urbit network.
203−Everything has to be restarted from scratch. Your pier will continue to
204−function after we have breached, but it wont connect to the rest of the
207−When this happens, back up any files you'd like to save, shut down your
208−urbit and recreate it (as if you were starting for the first time).
239+When this happens, back up any files you'd like to save, shut down your urbit, and recreate it (as if you were starting for the first time).
211## Creating a Comet {#creating-a-comet}
241## Creating a Comet {#creating-a-comet}
214**Comets** are urbits whose names are 128-bits or 16 syllables, such as:
243**Comets** are urbits whose names are 128-bits or 16 syllables, such as:
216`~dasres-ragnep-lislyt-ribpyl--mosnyx-bisdem-nidful-marzod`
245`~dasres-ragnep-lislyt-ribpyl--mosnyx-bisdem-nidful-marzod`
@@ -221,8 +250,8 @@ Comet names aren't quite as memorable as others, but they're disposable identiti
222To boot your comet, go into the command line and run the following command from the directory that was created during Urbit installation:
251To boot your comet, go into the command line and run the following command from the directory that was created during Urbit installation:
225−$ urbit -c mycomet
254+$ ./urbit -c mycomet
228This will take a few minutes and will spin out a bunch of boot messages. Toward the end, you'll see something like:
257This will take a few minutes and will spin out a bunch of boot messages. Toward the end, you'll see something like:
@@ -235,7 +264,6 @@ http: live (insecure, loopback) on 12321
235~dasres_marzod:dojo>
264~dasres_marzod:dojo>
239## DNS Proxying {#dns-proxying}
267## DNS Proxying {#dns-proxying}
241We 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.
269We 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.
@@ -246,7 +274,8 @@ Stars and planets follow the same process DNS proxying process, and galaxies hav
247For 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.
275For 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.
249−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.
277+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.
250To do so, simply run this command in your ship's Dojo:
279To do so, simply run this command in your ship's Dojo:
@@ -261,9 +290,9 @@ You'll then be prompted to enter the public IP address of your ship. You can als
262`: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`.
291`: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`.
264−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`.
293+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 set up, `~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`.
266−Great! You're set up now. Try accessing your `ship.arvo.network` in your browser to use Landscape; we recommend using Chrome or Brave.
295+Great! You're set up now. Try accessing your `ship.arvo.network` in your browser to use Landscape; we recommend Chrome or Brave.
268### Galaxies
297### Galaxies
@@ -283,44 +312,23 @@ Otherwise, `:dns|auto` works the same as `:dns|ip` does with stars and planets:
284Configuring 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.
313Configuring 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.
286−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).
315+The built-in logic for listening on port 80 is 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).
289## Messaging {#messaging}
317## Messaging {#messaging}
291−Talk is the built-in frontend for the Urbit messaging and notifications
319+Let’s get started using the :talk application from the command line.
292−protocol, Hall. Today we use Hall to chat and coordinate, but it's really
293−a general purpose piece of infrastructure.
295−For the time being come join us in `~dopzod/urbit-help` by using the
296−'quickstart' section below. `~dopzod` is the host ship, and `/urbit-help` is the
297−channel on that ship.
299−Today, Hall is sort of like a distributed, encrypted Slack that can be
300−used from the CLI and the browser. There’s no central Hall server.
301−Any urbit can host one.
303−Hall is a general purpose tool for both aggregating and publishing
304−streams of messages. Applications can use Hall as their transport
305−protocol, API connectors can push disparate data sources into Hall,
306−and so on. There are lots of things a distributed message protocol can
307−be used for that we haven't even thought of.
309−Here we'll be discussing how to operate the default CLI frontend, Talk,
310−to send and receive messages. For a more in-depth look at Hall's internals,
311−take a look at its [documentation](@/docs/arvo/hall.md).
313### Quickstart
321### Quickstart
315−The most common uses of Talk right now are communicating over a public chat channel called `~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.
323+The most common uses of :talk 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.
317−There are two ways of using Talk: from the terminal running the Urbit process, or through the Landscape web UI available at `http://localhost/~~/landscape`.
325+There are two ways of using :talk: from the terminal running the Urbit process, or through the Landscape web UI available from your ship’s URL address.
319If you're using Landscape for the first time, you'll need to enter a code to gain access. You can obtain this code by running `+code` from the Dojo.
327If you're using Landscape for the first time, you'll need to enter a code to gain access. You can obtain this code by running `+code` from the Dojo.
321### Joining a channel
329### Joining a channel
323−In Hall, a medium for a message is called a _circle_. There are four types of circles, but we 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](#manual) section.
331+Hall is the Arvo vane on the back-end that manages :talk. In Hall, a medium for a message is called a _circle_. There are four types of circles, 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.
325Let's join the `~dopzod/urbit-help` channel. Use `ctrl-x` to switch from Dojo to Talk.
333Let's join the `~dopzod/urbit-help` channel. Use `ctrl-x` to switch from Dojo to Talk.
@@ -330,8 +338,7 @@ Then:
330~your-urbit:talk> ;join ~dopzod/urbit-help
338~your-urbit:talk> ;join ~dopzod/urbit-help
333−Scrolling down your terminal window, you'll probably see the playback of
341+Scrolling down your terminal window, you'll probably see a playback of previous `~dopzod/urbit-help` messages that you missed.
334−previous `~dopzod/urbit-help` messages that you missed.
336Post a line to `~dopzod/urbit-help:`
343Post a line to `~dopzod/urbit-help:`
@@ -345,18 +352,6 @@ You'll see your message printed below messages from others that came before it:
345~your-urbit= Hello, world!
352~your-urbit= Hello, world!
348−### Subscribing to a channel in Landscape
350−In Landscape, you can always navigate to a channel by opening the menu, or using the shortcut `cmd-k`, then typing `go ~host-urbit/channel-name`. However, if you want to see messages in your inbox, you'll need to join from the Talk terminal.
355−;join ~dopzod/urbit-help
358−Now, navigate to `localhost/~~/landscape`. You should see recent messages under the "Recent" tab, and if you navigate to the "All" tab, you should see your subscription to `~dopzod/urbit-help` under "Chats".
360### Direct Messaging
355### Direct Messaging
362To send a direct message to someone, first set your audience:
357To send a direct message to someone, first set your audience:
@@ -404,9 +399,6 @@ Use `;leave` to unsubscribe from a channel:
404~your-urbit:talk= ;leave ~dopzod/urbit-help
399~your-urbit:talk= ;leave ~dopzod/urbit-help
407−The web UI ships as compiled JavaScript on your urbit, but has its own
408−source repo [here](https://github.com/urbit/talk).
410Last, let's create a channel we can invite some friends to:
402Last, let's create a channel we can invite some friends to:
@@ -417,30 +409,21 @@ Now you can tell your friends to `;join ~your-urbit/my-channel`.
420−### Manual
412+### Messaging manual {#messaging-manual}
422−Hall's design is similar in spirit to
423−[NNTP](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
414+Hall, the back-end Arvo vane that provides the messaging for :talk, has a design that is similar in spirit to [NNTP](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol), the underlying protocol for Usenet.
424−the underlying protocol for Usenet.
426−Our design is pretty simple: Hall messages are called _posts_. Posts
427−go to _circles_. Any urbit can host or subscribe to any number of circles.
416+The design is pretty simple: Hall messages are called _posts_. Posts go to _circles_. Any urbit can host or subscribe to any number of circles.
429−There are four kinds of circles: a write-only `%mailbox` for direct
430−messages, an invite-only `%village` for private conversation, a read-only
418+There are four kinds of circles: a write-only `%mailbox` for direct messages, an invite-only %village` for private conversation, a read-only `%journal` for curated content, and a public-access `%channel` for general use.
431−`%journal` for curated content, and a public-access `%channel` for
434#### Posts
420#### Posts
436−A post can be a variety of different data structures. Let's look at the
422+A post can be a variety of different data structures. Let's look at the ones you can use from within Talk: lines, URLs, Hoon, and replies.
437−ones you can use from within Talk: lines, URLs, Hoon and replies.
439#### Lines
424#### Lines
441−A line is simply a string of text. Depending on the filtering rules set
442−by the circle's host, these may or may not include uppercase and Unicode
426+A line is simply a string of text. Depending on the filtering rules set by the circle's host, these may or may not include uppercase and Unicode characters (see [filter](#filter)).
443−characters (see [filter](#filter)).
445If the line starts with `@`, it's an action (like `/me` in IRC).
428If the line starts with `@`, it's an action (like `/me` in IRC).
@@ -464,8 +447,7 @@ A URL is any valid URL.
467−You can use Talk to evaluate Hoon code and share the result with everyone in a
450+You can use Talk to evaluate Hoon code and share the results with everyone in a Hall circle. To do so, preface your Hoon with `#`.
468−Hall circle. To do so, preface your Hoon with `#`.
471~your-urbit:talk= #(add 2 2)
453~your-urbit:talk= #(add 2 2)
@@ -495,8 +477,7 @@ will print as
496#### Activating Lines
478#### Activating Lines
498−A line number identifying the **subsequent** line is displayed every 5
480+A line number identifying the **subsequent** line is displayed every 5 lines.
502---------[0]
483---------[0]
@@ -528,19 +509,14 @@ in reply to: ~your-urbit:
528That's my message!
509That's my message!
531−If information got truncated — like what happens for long URLs or expressions,
512+If information got truncated – like what happens for long URLs or expressions,
532−or if there's additional information available — as is the case with
533−replies and attachments (e.g. stack traces) — activating the message will show
513+or if there's additional information available – as is the case with replies and attachments (e.g. stack traces) – activating the message will show you all the details.
536−You can also activate the most recent line with `;`, the second-most recent
515+You can also activate the most recent line with `;`, the second-most recent with `;;`, and so on.
537−with `;;`, and so on.
539### Creating and managing circles
517### Creating and managing circles
541−As mentioned before, any urbit can host any number of circles. Existing circles
519+As mentioned before, any urbit can host any number of circles. Existing circles can be deleted or modified with various commands. All commands in this section should be sent from the `talk>` prompt.
542−can be deleted or modified with various commands. All commands in this section
543−shoild be sent from the `talk>` prompt.
545#### Create
521#### Create
@@ -625,9 +601,7 @@ And we get the output:
626Syntax: `;invite %name ~someone`
602Syntax: `;invite %name ~someone`
628−Invites someone into your circle `%name`. If they were previously banished,
604+Invites someone into your circle `%name`. If they were previously banished, removes them from the blacklist. Can also invite multiple ships at once, `~comma, ~separated`.
629−removes them from the blacklist.
630−Can also invite multiple ships at once, `~comma, ~separated`.
632For example:
606For example:
@@ -639,16 +613,13 @@ For example:
640Syntax: `;banish %name ~someone`
614Syntax: `;banish %name ~someone`
642−Removes someone from your circle `%name`. If they were previously invited,
616+Removes someone from your circle `%name`. If they were previously invited, removes them from the whitelist. Can also banish multiple ships at once, `~comma, ~separated`.
643−removes them from the whitelist.
644−Can also banish multiple ships at once, `~comma, ~separated`.
646#### Source
618#### Source
648Syntax: `;source %name ~other/circle`
620Syntax: `;source %name ~other/circle`
650−Adds `~other/circle` as a source for circle `%name`. This causes all
622+Adds `~other/circle` as a source for circle `%name`. This causes all messages sent to `~other/circle` to also appear in `%name`.
651−messages sent to `~other/circle` to also appear in `%name`.
653For example:
624For example:
@@ -670,27 +641,23 @@ For example:
671#### Circle Membership
642#### Circle Membership
673−If you have joined a circle, you can make this information publicly
644+If you have joined a circle, you can make this information publicly available to help others find that circle as well.
674−available to help others find that circle as well.
676#### Show Membership
646#### Show Membership
678Syntax: `;show ~some/circle`
648Syntax: `;show ~some/circle`
680−Adds a circle to your public membership list on your Hall profile. Hall profiles
650+Adds a circle to your public membership list on your Hall profile. Hall profiles are not used yet.
683#### Hide Membership
652#### Hide Membership
685Syntax: `;hide ~some/circle`
654Syntax: `;hide ~some/circle`
687−Removes a circle from your public membership list on your Hall profile. Hall
656+Removes a circle from your public membership list on your Hall profile. Hall profiles are not used yet.
688−profiles are not used yet.
690### Status
658### Status
692−You'll see status notifications when people enter or leave circles you're
660+You'll see status notifications when people enter or leave circles you're subscribed to.
695#### Notifications Off
662#### Notifications Off
@@ -859,7 +826,7 @@ Set audience to another ship.
860Syntax: `;%circle`
827Syntax: `;%circle`
862−Set audience to a circle on your own ship
829+Set audience to a circle on your own ship.
864#### Set Audience + Send Message
831#### Set Audience + Send Message
@@ -919,8 +886,8 @@ Syntax: `;unset nicks`
920Show ship-names instead of nicknames.
887Show ship-names instead of nicknames.
922−Nicknames and handles longer than 14 character will be truncated in
889+Nicknames and handles longer than 14 characters will be truncated in
923−output. Nicknames are strictly local - like the names on entries in a
890+output. Nicknames are strictly local – like the names on entries in a
924phonebook.
891phonebook.
926### Miscellaneous configuration
893### Miscellaneous configuration
@@ -941,7 +908,7 @@ Stop showing the timestamp for each message.
942Syntax: `;set timezone [+/-][hours]`
909Syntax: `;set timezone [+/-][hours]`
944−Adjust the display of the timestamps to a specific timezone. Relative to UTC.
911+Adjust the display of timestamps to a specific timezone. Relative to UTC.
946#### Sound Notification On
913#### Sound Notification On
@@ -971,7 +938,6 @@ good place to quickly experiment with Urbit. On the surface the Dojo is just a
971Hoon REPL. On the inside, the Dojo is a system for operating on and transforming
938Hoon REPL. On the inside, the Dojo is a system for operating on and transforming
972data in Urbit.
939data in Urbit.
975### Quickstart
941### Quickstart
977You can use the Dojo to run arbitrary Hoon code, as well as non-Hoon system
943You can use the Dojo to run arbitrary Hoon code, as well as non-Hoon system
@@ -995,7 +961,7 @@ Tall-form Hoon may require multiple lines:
997Hoon uses something called [the subject](@/docs/hoon/hoon-tutorial/the-subject-and-its-legs.md).
963Hoon uses something called [the subject](@/docs/hoon/hoon-tutorial/the-subject-and-its-legs.md).
998−The Dojo has its own subject, and that's where Hoon's equivalent of variables,
964+The Dojo has its own subject and that's where Hoon's equivalent of variables,
999called faces, are stored.
965called faces, are stored.
1001Use `=var` to save faces to the Dojo subject.
967Use `=var` to save faces to the Dojo subject.
@@ -1016,7 +982,7 @@ Use `=dir` to set the current working directory:
1018(`%` represents your current directory. For a complete explanation on urbit
984(`%` represents your current directory. For a complete explanation on urbit
1019−paths, see the [filesystem section](@/operations.md))
985+paths, see the [filesystem section](#filesystem).)
1021Generators (files in `/gen`) are run with `+`:
987Generators (files in `/gen`) are run with `+`:
@@ -1061,7 +1027,7 @@ arguments.
1062#### `+curl`
1028#### `+curl`
1064−Retrives data from a URL. Accepts a `tape`. Similar to Unix `curl`.
1030+Retrieves data from a URL. Accepts a `tape`. Similar to Unix `curl`.
1067~your-urbit:dojo> +curl "http://nyt.com"
1033~your-urbit:dojo> +curl "http://nyt.com"
@@ -1173,14 +1139,14 @@ number of vane names.
1176−### Manual
1142+### Dojo manual
1178#### Sources and sinks
1144#### Sources and sinks
1180A Dojo command is either a **source** or a **sink**. A source is just something
1146A Dojo command is either a **source** or a **sink**. A source is just something
1181that can be printed to your console or the result of some computation. A
1147that can be printed to your console or the result of some computation. A
1182sink is an **effect**: a change to the filesystem, a network message, a
1148sink is an **effect**: a change to the filesystem, a network message, a
1183−change to your environment, or typed message to an app.
1149+change to your environment, or a typed message to an app.
1185Sources can be chained together, but we can only produce one effect per
1151Sources can be chained together, but we can only produce one effect per
@@ -1250,7 +1216,7 @@ Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`
1251#### `&` - Mark conversion
1217#### `&` - Mark conversion
1253−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/arvo/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:
1219+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/arvo/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:
1256~your-urbit:dojo>&html &hymn &udon ';h1#hello: hello'
1222~your-urbit:dojo>&html &hymn &udon ';h1#hello: hello'
@@ -1409,8 +1375,7 @@ Urbit has its own revision-controlled filesystem, Clay. Clay is a typed, global,
1409referentially transparent namespace. An easy way to think about it is like typed
1375referentially transparent namespace. An easy way to think about it is like typed
1412−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
1378+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 pier directory.
1415### Quickstart
1380### Quickstart
@@ -1426,7 +1391,7 @@ desk based on the `%home` desk:
1428Running `our` produces your ship-name, meaning that you can run the following
1393Running `our` produces your ship-name, meaning that you can run the following
1429−command instead of typing out the entire thing. Useful for comets, due to their
1394+command instead of typing out the entire thing. Useful for comets due to their
1430very long names.
1395very long names.
@@ -1507,7 +1472,7 @@ both connected as peers:
1510−### Manual
1475+### Clay manual
1512#### Paths
1477#### Paths
@@ -1613,7 +1578,7 @@ access a file called
1615Because both paths share a directory named `/gmail` at the same position in the
1580Because both paths share a directory named `/gmail` at the same position in the
1616−address hierarchy -- which, if you recall, is just a `list` -- the above command
1581+address hierarchy – which, if you recall, is just a `list` – the above command
1619We can do the same thing between desks. If `%sandbox` has been merged with
1584We can do the same thing between desks. If `%sandbox` has been merged with
@@ -1738,8 +1703,8 @@ Merge the `%examples` desk from `~waxbex-ribmex`
1740Subscribe to continuous updates from remote `plot` on local `desk`.
1705Subscribe to continuous updates from remote `plot` on local `desk`.
1741−`plot-desk` can specify the remote `desk` name. When omitted it is
1706+`plot-desk` can specify the remote `desk` name. When omitted it defaults
1742−defaulted to being the same as `desk`. Non-comet urbits have
1707+to being the same as `desk`. Non-comet urbits have
1743`|sync %home ~parent %kids` automatically set up (where `~parent` is the
1708`|sync %home ~parent %kids` automatically set up (where `~parent` is the
1744planet that issued a moon, the star that issued a planet, or the galaxy
1709planet that issued a moon, the star that issued a planet, or the galaxy
1745that issued a star).
1710that issued a star).
@@ -1783,12 +1748,12 @@ Example:
1784### Merge strategies
1749### Merge strategies
1786−`%init` - Used if it's the first commit to a desk. Also can be used to
1751+`%init` - used if it's the first commit to a desk. Also can be used to
1787−"reinitialize" a desk -- revision numbers keep going up, but the new
1752+"reinitialize" a desk – revision numbers keep going up, but the new
1788revision isn't necessarily a descendent of the previously numbered
1753revision isn't necessarily a descendent of the previously numbered
1789version, allowing merges to be rerun.
1754version, allowing merges to be rerun.
1791−`%this` - Keep what's in Bob's desk, but join the ancestry.
1756+`%this` - keep what's in Bob's desk, but join the ancestry.
1793`%that` - take what's in Alice's desk, but join the ancestry. This is
1758`%that` - take what's in Alice's desk, but join the ancestry. This is
1794the reverse of `%this`. This is different from `%init` because the new
1759the reverse of `%this`. This is different from `%init` because the new
@@ -1808,8 +1773,8 @@ Bob's changed files.
1809A `%mate` merge attempts to merge changes to the same file when both
1774A `%mate` merge attempts to merge changes to the same file when both
1810Alice and Bob change it. If the merge is clean, we use it; otherwise, we
1775Alice and Bob change it. If the merge is clean, we use it; otherwise, we
1811−fail. A merge between different types of changes -- for example,
1776+fail. A merge between different types of changes – for example,
1812−deleting a file vs changing it -- is always a conflict. If we succeed,
1777+deleting a file vs changing it – is always a conflict. If we succeed,
1813the parents are both Alice's and Bob's heads, and the data is the merge
1778the parents are both Alice's and Bob's heads, and the data is the merge
1814base plus Alice's changed files plus Bob's changed files plus the merged
1779base plus Alice's changed files plus Bob's changed files plus the merged
@@ -1854,8 +1819,8 @@ Produces a list of names at the `path`.
1855Syntax: `|rm path`
1820Syntax: `|rm path`
1857−Remove the data at `path`. `path` must be a path to actual node, not a
1822+Remove the data at `path`. `Path` must be a path to the actual node, not a
1858−'directory'
1823+'directory'.
1860#### `|cp`
1825#### `|cp`
@@ -1870,4 +1835,4 @@ Syntax: `|mv to from`
1870Move the file at `from` into the path `to`.
1835Move the file at `from` into the path `to`.
1872In Clay, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
1837In Clay, `|mv` is just a shorthand for `|cp` then `|rm`. The `|rm`
1873−doesn't happen unless the `|cp` succeeds.
1838+doesn't happen unless the `|cp` succeeds.