@@ -45,19 +45,21 @@ Urbit: a personal server operating function
4545### macOS
4646
4747```sh
48+mkdir urbit
49+cd urbit
4850curl -O https://bootstrap.urbit.org/urbit-v0.10.8-darwin.tgz
4951tar xzf urbit-v0.10.8-darwin.tgz
50−cd urbit-v0.10.8-darwin
51−./urbit
52+./urbit-v0.10.8-darwin/urbit
5253```
5354
5455### Linux (64-bit)
5556
5657```sh
58+mkdir urbit
59+cd urbit
5760curl -O https://bootstrap.urbit.org/urbit-v0.10.8-linux64.tgz
5861tar xzf urbit-v0.10.8-linux64.tgz
59−cd urbit-v0.10.8-linux64
60−./urbit
62+./urbit-v0.10.8-linux64/urbit
6163```
6264
6365To access your Urbit via HTTP on port 80 on Ubuntu, you may need to run the following:
@@ -80,6 +82,8 @@ Once WSL 2 is installed, open a Linux terminal in Windows and then follow the Li
8082
8183Now that you have Urbit installed you can start it up with an ID.
8284
85+You should have an `urbit` directory with two files in it: the `urbit-v0.XX.X-<OS>` directory, and the .tgz of that directory. The .tgz file can now be safely deleted.
86+
8387If this is your first time using Urbit, it'll be easiest to start with a comet in order to get on the network.
8488
8589### Comet: Install and Setup {#comet}
@@ -94,13 +98,13 @@ Comets are disposable, free identities that can be used to quickly join the netw
9498
9599### Booting a comet
96100
97−To boot a comet, go into the command line and run the following command from the directory that was created during Urbit installation:
101+To boot a comet, go into the command line and run the following command from the urbit directory you created during Urbit installation:
98102
99103```sh
100−$ ./urbit -c mycomet
104+$ ./urbit-v0.10.8-darwin/urbit -c mycomet
101105```
102106
103−This will take a few minutes 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.
107+This 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).
104108
105109Toward the end of the boot process, you'll see something like:
106110
@@ -114,7 +118,9 @@ http: live (insecure, loopback) on 12321
114118
115119When 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.
116120
117−To exit Urbit, use `Ctrl-d`. To start your ship up again, run `./urbit mycomet` from the directory that you first booted from.
121+To exit Urbit, use `Ctrl-d`.
122+
123+To start your ship up again, run `./urbit-v0.10.8-darwin/urbit mycomet` from your `urbit` directory.
118124
119125### The Dojo
120126
@@ -246,7 +252,36 @@ Never boot multiple instances of your ship at the same time. You can prevent thi
246252
247253### Updating to the latest binary
248254
249−Most updates to Urbit are downloaded and applied automatically as OTA (Over the Air) updates. Occasionally it would be infeasible to distribute an update this way, and a new `urbit` binary is released. This is announced in the [urbit-dev](https://groups.google.com/a/urbit.org/forum/#!forum/dev) Google Group when it occurs (as are all OTA updates). To update to the latest binary, follow the same process outlined above to download and extract it into a new folder. (the binary linked on this page will always be the latest). Then run it as before with `./urbit path/to/sampel-palnet/`.
255+Most updates to Urbit are downloaded and applied automatically as OTA (Over the Air) updates. Occasionally it would be infeasible to distribute an update this way, and a new `urbit` binary is released. This is announced in the [urbit-dev](https://groups.google.com/a/urbit.org/forum/#!forum/dev) Google Group when it occurs (as are all OTA updates).
256+
257+To update to the latest binary, download and extract it to replace your existing one. Then run it as before.
258+
259+**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.
260+
261+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):
262+
263+First shut down your ship, by running the following in dojo (or control-d).
264+```
265+|exit
266+```
267+
268+Next download and extract the most recent binary from inside your `urbit` directory:
269+```
270+curl -O https://bootstrap.urbit.org/urbit-v0.10.8-darwin.tgz
271+tar xzf urbit-v0.10.8-darwin.tgz
272+```
273+
274+Delete the old binary directory from your `urbit` directory:
275+```
276+rm -rf urbit-v0.10.7-darwin
277+```
278+
279+Start up your ship with the new binary from your `urbit` directory:
280+```
281+./urbit-v0.10.8-darwin/urbit mycomet
282+```
283+
284+Then you're good to go, in the future you'll just modify the version numbers in the example above to the most recent version.
250285
251286### Breaches
252287