@@ -101,7 +101,11 @@ Comets are disposable, free identities that can be used to quickly join the netw
101101To boot a comet, go into the command line and run the following command from the urbit directory you created during Urbit installation:
102102
103103```sh
104+macOS:
104105$ ./urbit-v0.10.8-darwin/urbit -c mycomet
106+
107+Linux:
108+$ ./urbit-v0.10.8-linux64/urbit -c mycomet
105109```
106110
107111This will take up to an hour, and will spin out a bunch of boot messages. It will also create a directory called `mycomet` in the Unix directory that you ran the command from (which should be your urbit directory).
@@ -118,9 +122,16 @@ http: live (insecure, loopback) on 12321
118122
119123When your ship is finished booting, you will see either the `~sampel_commet:dojo>` or `~sampel_commet:chat-cli/` prompt. If you're seeing `:chat-cli` press `Ctrl-x` to switch into Dojo.
120124
121−To exit Urbit, use `Ctrl-d`.
125+To exit Urbit, use `control-d` or enter `|exit` into Dojo.
122126
123−To start your ship up again, run `./urbit-v0.10.8-darwin/urbit mycomet` from your `urbit` directory.
127+To start your ship up again, run the following from your `urbit` directory (note the lack of `-c` argument):
128+```sh
129+macOS:
130+$ ./urbit-v0.10.8-darwin/urbit mycomet
131+
132+Linux:
133+$ ./urbit-v0.10.8-linux64/urbit mycomet
134+```
124135
125136### The Dojo
126137
@@ -225,30 +236,58 @@ Find the absolute path to the keyfile that you downloaded from Bridge. Copy it.
225236
226237#### Step 3: Run the boot command
227238
228−If you are not already within the directory you installed above, enter it by running `cd urbit-v0.10.8-darwin` (for Mac) or `cd urbit-v0.10.8-linux64` (for Linux) from where you ran the install commands. It contains your Urbit binary, and your ship will be installed here as well.
239+Enter your `urbit` directory.
229240
230241Once you're inside, run the command below, except with `sampel-palnet` replaced by the name of your
231242Urbit identity, and `path/to/my-planet.key` replaced with the path to your keyfile:
232243
233244```sh
234−./urbit -w sampel-palnet -k path/to/my-planet.key
245+macOS:
246+./urbit-v0.10.8-darwin/urbit -w sampel-palnet -k path/to/my-planet.key
247+
248+Linux:
249+./urbit-v0.10.8-linux64/urbit -w sampel-palnet -k path/to/my-planet.key
235250```
236251
237252Or, if you'd prefer to copy your key in, you can run:
238253
239254```sh
240−./urbit -w sampel-palnet -G rAnDoMkEy
255+macOS:
256+./urbit-v0.10.8-darwin/urbit -w sampel-palnet -G rAnDoMkEy
257+
258+Linux:
259+./urbit-v0.10.8-linux64/urbit -w sampel-palnet -G rAnDoMkEy
241260```
242261
243262Either command will create a directory called `sampel-palnet/` and begin building your ship. It may take a few minutes.
244263
245−When your ship is finished booting, you will see either the `~sampel-palnet:dojo>` or `~sampel-palnet:chat-cli/` prompt. If you're seeing `:chat-cli` press `Ctrl-x` to switch into Dojo. At that point, you should permanently erase your keyfile from your machine.
264+When your ship is finished booting, you will see either the `~sampel-palnet:dojo>` or `~sampel-palnet:chat-cli/` prompt. If you're seeing `:chat-cli` press `Ctrl-x` to switch into Dojo.
265+
266+To shut down your ship, use `control-d`. To start your ship up again, run the following from your `urbit` directory:
246267
247−To shut down your ship, use `Ctrl-d`. To start your ship up again, run `./urbit sampel-palnet/` from the directory where your Urbit binary is saved. Note that in this usage, `sampel-palnet/` is the path of a folder, which by default is located in the same folder as the Urbit binary. This folder is called your ship's **pier**, and you can put it wherever you like.
268+```sh
269+macOS:
270+./urbit-v0.10.8-darwin/urbit sampel-palnet
271+
272+Linux:
273+./urbit-v0.10.8-linux64/urbit sampel-palnet
274+```
275+
276+Note that `sampel-palnet/` is the path of a folder, which we just created in your `urbit` directory. This folder is called your ship's **pier**.
248277
249278Never boot multiple instances of your ship at the same time. You can prevent this from happening on accident by only ever keeping a single copy of your pier.
250279
251−**Important:** once a key has been used to boot a ship onto the network, it cannot be used to boot that ship again later - doing so will cause communication problems with other ships. For this reason you should **delete the keyfile from your machine once your ship has booted successfully**. (If you do use the same key twice, you'll need to conduct a [personal breach](#breaches) to restore your ship to full functionality).
280+**Important:** once a key has been used to boot a ship onto the network, it cannot be used to boot that ship again later - doing so will cause communication problems with other ships.
281+
282+For this reason you should **delete the keyfile from your machine once your ship has booted successfully**.
283+
284+If you do use the same key twice, you'll need to conduct a [personal breach](#breaches) to restore your ship to full functionality).
285+
286+Delete the keyfile with the command below:
287+
288+```sh
289+rm path/to/my-planet.key
290+```
252291
253292### Updating to the latest binary
254293
@@ -256,34 +295,47 @@ Most updates to Urbit are downloaded and applied automatically as OTA (Over the
256295
257296To update to the latest binary, download and extract it to replace your existing one. Then run it as before.
258297
259−For example, if in your current `urbit` directory you have an `urbit-v0.10.7-darwin` directory along with a ship directory called `mycomet`, and a new `urbit-v0.10.8-darwin` binary was just released, then you'd run the following commands from your `urbit` directory (the example commands below use the darwin installer, but you should use the one for your OS):
298+For example, if in your current `urbit` directory you have an `urbit-v0.10.7-<OS>` directory along with a ship directory called `mycomet`, and a new `urbit-v0.10.8-<OS>` binary was just released, then you'd run the following commands from your `urbit` directory:
260299
261300First shut down your ship, by running the following in dojo (or control-d).
262301```
263302|exit
264303```
265304
266−Next download and extract the most recent binary from inside your `urbit` directory:
267−```
268−curl -O https://bootstrap.urbit.org/urbit-v0.10.8-darwin.tgz
269−tar xzf urbit-v0.10.8-darwin.tgz
270−```
271−
272305Delete the old binary directory from your `urbit` directory:
273306
274307**NOTE**: Your ship itself can be reused, only the binary needs to be changed. This is why we have the directory structure configured as an urbit directory that contains your ship and your binary. This structure makes it easy to swap in new binaries. If you have your ship *inside* the `urbit-vX.XX.X` directory, move it out before deleting that directory.
275−```
308+```sh
309+macOS:
276310rm -rf urbit-v0.10.7-darwin
311+
312+Linux:
313+rm -rf urbit-v0.10.7-linux64
277314```
278315
279−Start up your ship with the new binary from your `urbit` directory:
316+Next download and extract the most recent binary from inside your `urbit` directory:
317+```sh
318+macOS:
319+curl -O https://bootstrap.urbit.org/urbit-v0.10.8-darwin.tgz
320+tar xzf urbit-v0.10.8-darwin.tgz
321+
322+Linux:
323+curl -O https://bootstrap.urbit.org/urbit-v0.10.8-linux64.tgz
324+tar xzf urbit-v0.10.8-linux64.tgz
280325```
326+
327+Start up your ship with the new binary from your `urbit` directory:
328+```sh
329+macOS:
281330./urbit-v0.10.8-darwin/urbit mycomet
331+
332+Linux:
333+./urbit-v0.10.8-linux64/urbit mycomet
282334```
283335
284336Then you're good to go, in the future you'll just modify the version numbers in the example above to the most recent version.
285337
286−### Breaches
338+### Breaches {#breaches}
287339
288340An important concept on the Urbit network is that of continuity. Continuity refers to how ships remember the order of their own network messages and the network messages of others -- these messages are numbered, starting from zero. A breach is when ships on the network agree to forget about this sequence and treat one or more ships like they are brand new.
289341