@@ -4,10 +4,69 @@ template = "page_indiced.html"
44slug = "/operations/"
55+++
66
7−## Admin and Operations {#urbit-administration}
7+## Using Bridge {#using-bridge}
88
9−Your urbit (also called your _ship_) is a persistent Unix process that you
10−mainly control from the console. For some things, a browser will also work.
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.
10+
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.
12+
13+### Online Bridge
14+
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.
16+
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).
18+
19+### Offline Bridge
20+
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.
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+
30+You can then use the Bridge app by navigating to `http://localhost:5000` in your internet browser.
31+
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.
33+
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.
35+
36+### Accept Your Transfer
37+
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.
39+
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.
41+
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.
43+
44+If you already own a point, click on the `Details ->` under your sigil in the `Your Points` section.
45+
46+### Set Your Networking Keys
47+
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!
49+
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
51+
52+```sh
53+hexdump -n 32 -e '4/4 "%08X"' /dev/random
54+```
55+
56+and use the result.
57+
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.
59+
60+### Generate Your Keyfile
61+
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.
64+
65+With that keyfile in hand, you can now exit Bridge and continue to the guide to [install the Urbit binary](@/install.md).
66+
67+## Using Your Ship {#urbit-administration}
68+
69+Your urbit (also called your _ship_) is a persistent Unix process that you mainly control from the console.
1170
1271### Shutdown
1372
@@ -19,63 +78,56 @@ You can force-quit your urbit with `Ctrl-z` from anywhere.
1978
2079To restart your urbit simply pass the name of your pier:
2180
22−```
23−$ urbit some-planet
81+```sh
82+$ ./urbit some-planet
2483```
2584
2685or
2786
28−```
29−$ urbit comet
87+```sh
88+$ ./urbit comet
3089```
3190
3291### Logging
3392
3493To log an urbit's command line output to a file, use `script`:
3594
36−```
37−$ script urbit.log urbit your-urbit
95+```sh
96+$ script urbit.log ./urbit your-urbit
3897```
3998
4099### Moving your pier
41100
42101Piers 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
44103of the same urbit in two places.
45104
46105To move a pier, simply move the contents of the directory it lives in.
47106To keep these files as small as possible we usually use the `--sparse`
48107option in `tar`. With a pier `your-urbit/`, something like this should work:
49108
50−```
109+```sh
51110tar -Scvzf ~/your-urbit.tar.gz ~/your-urbit/
52111scp your-old-server:~/your-urbit.tar.gz your-new-server:~
53112```
54113
55114Then to unzip it, on your other Unix server, run:
56115
57−```
116+```sh
58117tar xfvz your-urbit.tar.gz
59118```
60119
61−Delete the tar file, and, after installing Urbit on your new server,
62−start your urbit back up with:
120+Delete the tar file, and, after installing Urbit on your new server, start your urbit back up with:
63121
64−```
65−urbit your-urbit
122+```sh
123+./urbit your-urbit
66124```
67125
68126### Console
69127
70−Your Urbit terminal is separated into two parts: the prompt (the bottom
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.
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.
74129
75−In the CLI, Urbit apps can process your input before you hit return. To
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.
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.
79131
80132`Ctrl-x` - Switches the prompt between running console apps
81133
@@ -94,10 +146,10 @@ The following emacs-style key bindings are available:
94146Ctrl-a Cursor to beginning of the line (Home)
95147Ctrl-b Cursor one character backward (left-arrow)
96148Ctrl-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)
98150Ctrl-g Beep; cancel reverse-search
99151Ctrl-k Kill to end of line
100−Ctrl-l Clear the screen
152+Ctrl-l Clear the screen
101153Ctrl-n Next line in history (down-arrow)
102154Ctrl-p Previous line in history (up-arrow)
103155Ctrl-r Reverse-search
@@ -106,26 +158,15 @@ Ctrl-u Kill to beginning of line
106158Ctrl-y Yank from kill buffer
107159```
108160
109−### Web
161+### Landscape
110162
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
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).
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).
116164
117−Your urbit serves a simple homepage from `http://localhost` or
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`.
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`.
122166
123167### Moons {#moons}
124168
125−Planets can spawn moons, which are meant for connected devices: phones, smart
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.
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.
129170
130171To generate a random moon from your planet, run:
131172
@@ -138,8 +179,7 @@ moon: ~faswep-navred-sampel-palnet
138179\/ \/
139180```
140181
141−You must manually edit the output of `+moon` to get
142−the correct format for the `<key>`:
182+You must manually edit the output of `+moon` to get the correct format for the `<key>`:
143183
144184- strip out the `\/`
145185
@@ -159,20 +199,18 @@ Another way of generating `<keyfile>` is:
159199moon: ~faswep-navred-sampel-palnet
160200```
161201
162−`<keyfile>` will be at `path/to/sampel-palnet/.urb/put/moon.key`
163−and does not need editing to be used with the `-k` option.
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.
164203
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:
167205
168−```
169−$ urbit -w <moonname> -G <key> -c <piername>
206+```sh
207+$ ./urbit -w <moonname> -G <key> -c <piername>
170208```
171209
172210or
173211
174−```
175−$ urbit -w <moonname> -k <keyfile> -c <piername>
212+```sh
213+$ ./urbit -w <moonname> -k <keyfile> -c <piername>
176214```
177215
178216The `-c <piername>` argument is not required, but it is recommended; otherwise,
@@ -180,37 +218,28 @@ the resulting directory is a rather unwieldy moon name.
180218
181219Here's how an example moon might be booted:
182220
183−```
184−$ urbit -w faswep-navred-sampel-palnet -G <key> -c mymoon
221+```sh
222+$ ./urbit -w faswep-navred-sampel-palnet -G <key> -c mymoon
185223```
186224
187225or
188226
189−```
190−$ urbit -w faswep-navred-sampel-palnet -k <keyfile> -c mymoon
227+```sh
228+$ ./urbit -w faswep-navred-sampel-palnet -k <keyfile> -c mymoon
191229```
192230
193−Moons are automatically synced to their parent `%kids` desk, and can control
194−applications on their parent planet using `|link`.
231+Moons are automatically synced to their parent `%kids` desk, and can control applications on their parent planet using `|link`.
195232
196233### Continuity breaches
197234
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
200−to be shipped or we hit a bug that can't be fixed over the air.
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.
201236
202−Because Urbit networking is stateful we call this a _continuity breach_.
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
205−Urbit network.
206−
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).
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.
209238
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).
210240
211241## Creating a Comet {#creating-a-comet}
212242
213−
214243**Comets** are urbits whose names are 128-bits or 16 syllables, such as:
215244
216245`~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
221250
222251To boot your comet, go into the command line and run the following command from the directory that was created during Urbit installation:
223252
224−```
225−$ urbit -c mycomet
253+```sh
254+$ ./urbit -c mycomet
226255```
227256
228257This 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
235264~dasres_marzod:dojo>
236265```
237266
238−
239267## DNS Proxying {#dns-proxying}
240268
241269We 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
246274
247275For 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.
248276
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.
278+
250279To do so, simply run this command in your ship's Dojo:
251280
252281```
@@ -261,9 +290,9 @@ You'll then be prompted to enter the public IP address of your ship. You can als
261290
262291`: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`.
263292
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`.
265294
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.
267296
268297### Galaxies
269298
@@ -283,44 +312,23 @@ Otherwise, `:dns|auto` works the same as `:dns|ip` does with stars and planets:
283312
284313Configuring 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.
285314
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).
287−
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).
288316
289317## Messaging {#messaging}
290318
291−Talk is the built-in frontend for the Urbit messaging and notifications
292−protocol, Hall. Today we use Hall to chat and coordinate, but it's really
293−a general purpose piece of infrastructure.
294−
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.
298−
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.
302−
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.
308−
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).
319+Let’s get started using the :talk application from the command line.
312320
313321### Quickstart
314322
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.
316324
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.
318326
319327If 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.
320328
321329### Joining a channel
322330
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.
324332
325333Let's join the `~dopzod/urbit-help` channel. Use `ctrl-x` to switch from Dojo to Talk.
326334
@@ -330,8 +338,7 @@ Then:
330338~your-urbit:talk> ;join ~dopzod/urbit-help
331339```
332340
333−Scrolling down your terminal window, you'll probably see the playback of
334−previous `~dopzod/urbit-help` messages that you missed.
341+Scrolling down your terminal window, you'll probably see a playback of previous `~dopzod/urbit-help` messages that you missed.
335342
336343Post a line to `~dopzod/urbit-help:`
337344
@@ -345,18 +352,6 @@ You'll see your message printed below messages from others that came before it:
345352~your-urbit= Hello, world!
346353```
347354
348−### Subscribing to a channel in Landscape
349−
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.
351−
352−Again, that's:
353−
354−```
355−;join ~dopzod/urbit-help
356−```
357−
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".
359−
360355### Direct Messaging
361356
362357To send a direct message to someone, first set your audience:
@@ -404,9 +399,6 @@ Use `;leave` to unsubscribe from a channel:
404399~your-urbit:talk= ;leave ~dopzod/urbit-help
405400```
406401
407−The web UI ships as compiled JavaScript on your urbit, but has its own
408−source repo [here](https://github.com/urbit/talk).
409−
410402Last, let's create a channel we can invite some friends to:
411403
412404```
@@ -417,30 +409,21 @@ Now you can tell your friends to `;join ~your-urbit/my-channel`.
417409
418410---
419411
420−### Manual
412+### Messaging manual {#messaging-manual}
421413
422−Hall's design is similar in spirit to
423−[NNTP](https://en.wikipedia.org/wiki/Network_News_Transfer_Protocol),
424−the underlying protocol for Usenet.
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.
425415
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.
428417
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
431−`%journal` for curated content, and a public-access `%channel` for
432−general use.
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.
433419
434420#### Posts
435421
436−A post can be a variety of different data structures. Let's look at the
437−ones you can use from within Talk: lines, URLs, Hoon and replies.
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.
438423
439424#### Lines
440425
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
443−characters (see [filter](#filter)).
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)).
444427
445428If the line starts with `@`, it's an action (like `/me` in IRC).
446429
@@ -464,8 +447,7 @@ A URL is any valid URL.
464447
465448#### Hoon
466449
467−You can use Talk to evaluate Hoon code and share the result with everyone in a
468−Hall circle. To do so, preface your Hoon with `#`.
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 `#`.
469451
470452```
471453~your-urbit:talk= #(add 2 2)
@@ -495,8 +477,7 @@ will print as
495477
496478#### Activating Lines
497479
498−A line number identifying the **subsequent** line is displayed every 5
499−lines.
480+A line number identifying the **subsequent** line is displayed every 5 lines.
500481
501482```
502483---------[0]
@@ -528,19 +509,14 @@ in reply to: ~your-urbit:
528509That's my message!
529510```
530511
531−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
534−you all the details.
512+If information got truncated – like what happens for long URLs or expressions,
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.
535514
536−You can also activate the most recent line with `;`, the second-most recent
537−with `;;`, and so on.
515+You can also activate the most recent line with `;`, the second-most recent with `;;`, and so on.
538516
539517### Creating and managing circles
540518
541−As mentioned before, any urbit can host any number of circles. Existing circles
542−can be deleted or modified with various commands. All commands in this section
543−shoild be sent from the `talk>` prompt.
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.
544520
545521#### Create
546522
@@ -625,9 +601,7 @@ And we get the output:
625601
626602Syntax: `;invite %name ~someone`
627603
628−Invites someone into your circle `%name`. If they were previously banished,
629−removes them from the blacklist.
630−Can also invite multiple ships at once, `~comma, ~separated`.
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`.
631605
632606For example:
633607
@@ -639,16 +613,13 @@ For example:
639613
640614Syntax: `;banish %name ~someone`
641615
642−Removes someone from your circle `%name`. If they were previously invited,
643−removes them from the whitelist.
644−Can also banish multiple ships at once, `~comma, ~separated`.
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`.
645617
646618#### Source
647619
648620Syntax: `;source %name ~other/circle`
649621
650−Adds `~other/circle` as a source for circle `%name`. This causes all
651−messages sent to `~other/circle` to also appear in `%name`.
622+Adds `~other/circle` as a source for circle `%name`. This causes all messages sent to `~other/circle` to also appear in `%name`.
652623
653624For example:
654625
@@ -670,27 +641,23 @@ For example:
670641
671642#### Circle Membership
672643
673−If you have joined a circle, you can make this information publicly
674−available to help others find that circle as well.
644+If you have joined a circle, you can make this information publicly available to help others find that circle as well.
675645
676646#### Show Membership
677647
678648Syntax: `;show ~some/circle`
679649
680−Adds a circle to your public membership list on your Hall profile. Hall profiles
681−are not used yet.
650+Adds a circle to your public membership list on your Hall profile. Hall profiles are not used yet.
682651
683652#### Hide Membership
684653
685654Syntax: `;hide ~some/circle`
686655
687−Removes a circle from your public membership list on your Hall profile. Hall
688−profiles are not used yet.
656+Removes a circle from your public membership list on your Hall profile. Hall profiles are not used yet.
689657
690658### Status
691659
692−You'll see status notifications when people enter or leave circles you're
693−subscribed to.
660+You'll see status notifications when people enter or leave circles you're subscribed to.
694661
695662#### Notifications Off
696663
@@ -859,7 +826,7 @@ Set audience to another ship.
859826
860827Syntax: `;%circle`
861828
862−Set audience to a circle on your own ship
829+Set audience to a circle on your own ship.
863830
864831#### Set Audience + Send Message
865832
@@ -919,8 +886,8 @@ Syntax: `;unset nicks`
919886
920887Show ship-names instead of nicknames.
921888
922−Nicknames and handles longer than 14 character will be truncated in
923−output. Nicknames are strictly local - like the names on entries in a
889+Nicknames and handles longer than 14 characters will be truncated in
890+output. Nicknames are strictly local – like the names on entries in a
924891phonebook.
925892
926893### Miscellaneous configuration
@@ -941,7 +908,7 @@ Stop showing the timestamp for each message.
941908
942909Syntax: `;set timezone [+/-][hours]`
943910
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.
945912
946913#### Sound Notification On
947914
@@ -971,7 +938,6 @@ good place to quickly experiment with Urbit. On the surface the Dojo is just a
971938Hoon REPL. On the inside, the Dojo is a system for operating on and transforming
972939data in Urbit.
973940
974−
975941### Quickstart
976942
977943You 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:
995961```
996962
997963Hoon 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,
999965called faces, are stored.
1000966
1001967Use `=var` to save faces to the Dojo subject.
@@ -1016,7 +982,7 @@ Use `=dir` to set the current working directory:
1016982```
1017983
1018984(`%` 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).)
1020986
1021987Generators (files in `/gen`) are run with `+`:
1022988
@@ -1061,7 +1027,7 @@ arguments.
10611027
10621028#### `+curl`
10631029
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`.
10651031
10661032```
10671033~your-urbit:dojo> +curl "http://nyt.com"
@@ -1173,14 +1139,14 @@ number of vane names.
11731139
11741140---
11751141
1176−### Manual
1142+### Dojo manual
11771143
11781144#### Sources and sinks
11791145
11801146A Dojo command is either a **source** or a **sink**. A source is just something
11811147that can be printed to your console or the result of some computation. A
11821148sink 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.
11841150
11851151Sources can be chained together, but we can only produce one effect per
11861152command.
@@ -1250,7 +1216,7 @@ Which outputs a new `urbit.pill` to `pier/.urb/put/urbit.pill`
12501216
12511217#### `&` - Mark conversion
12521218
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:
12541220
12551221```
12561222~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,
14091375referentially transparent namespace. An easy way to think about it is like typed
14101376`git`.
14111377
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
1413−pier directory.
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.
14141379
14151380### Quickstart
14161381
@@ -1426,7 +1391,7 @@ desk based on the `%home` desk:
14261391```
14271392
14281393Running `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
14301395very long names.
14311396
14321397```
@@ -1507,7 +1472,7 @@ both connected as peers:
15071472
15081473---
15091474
1510−### Manual
1475+### Clay manual
15111476
15121477#### Paths
15131478
@@ -1613,7 +1578,7 @@ access a file called
16131578```
16141579
16151580Because 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
16171582works!
16181583
16191584We can do the same thing between desks. If `%sandbox` has been merged with
@@ -1738,8 +1703,8 @@ Merge the `%examples` desk from `~waxbex-ribmex`
17381703```
17391704
17401705Subscribe to continuous updates from remote `plot` on local `desk`.
1741−`plot-desk` can specify the remote `desk` name. When omitted it is
1742−defaulted to being the same as `desk`. Non-comet urbits have
1706+`plot-desk` can specify the remote `desk` name. When omitted it defaults
1707+to being the same as `desk`. Non-comet urbits have
17431708`|sync %home ~parent %kids` automatically set up (where `~parent` is the
17441709planet that issued a moon, the star that issued a planet, or the galaxy
17451710that issued a star).
@@ -1783,12 +1748,12 @@ Example:
17831748
17841749### Merge strategies
17851750
1786−`%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
1751+`%init` - used if it's the first commit to a desk. Also can be used to
1752+"reinitialize" a desk – revision numbers keep going up, but the new
17881753revision isn't necessarily a descendent of the previously numbered
17891754version, allowing merges to be rerun.
17901755
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.
17921757
17931758`%that` - take what's in Alice's desk, but join the ancestry. This is
17941759the reverse of `%this`. This is different from `%init` because the new
@@ -1808,8 +1773,8 @@ Bob's changed files.
18081773
18091774A `%mate` merge attempts to merge changes to the same file when both
18101775Alice 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,
1812−deleting a file vs changing it -- is always a conflict. If we succeed,
1776+fail. A merge between different types of changes – for example,
1777+deleting a file vs changing it – is always a conflict. If we succeed,
18131778the parents are both Alice's and Bob's heads, and the data is the merge
18141779base plus Alice's changed files plus Bob's changed files plus the merged
18151780files.
@@ -1854,8 +1819,8 @@ Produces a list of names at the `path`.
18541819
18551820Syntax: `|rm path`
18561821
1857−Remove the data at `path`. `path` must be a path to actual node, not a
1858−'directory'
1822+Remove the data at `path`. `Path` must be a path to the actual node, not a
1823+'directory'.
18591824
18601825#### `|cp`
18611826
@@ -1870,4 +1835,4 @@ Syntax: `|mv to from`
18701835Move the file at `from` into the path `to`.
18711836
18721837In 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.