Various fixes and improvements.

pub/docs.mdy

@@ -7,15 +7,16 @@ anchor: none
 
 # Urbit documentation
 
-The Urbit doc is divided into three parts: user doc, developer
-doc, and general propaganda (whitepaper, essays, videos, etc).
+The Urbit doc is divided into three parts: [user doc](user),
+[developer doc](dev), and [theory](theory) (whitepaper, essays,
+videos, etc).
 
-If you want to try Urbit, start with the [user doc](docs/user).
-If you want to learn about Urbit, subject yourself to the
-[theory](docs/theory).  Or just start with the user doc, which
-doesn't assume any prior knowledge.
+If you want to try Urbit, start with the user doc.  If you want
+to learn about Urbit, try the theory.  Or just start with the
+user doc; it doesn't assume any prior knowledge.
 
-The developer doc is still under construction...
+The most fun thing to do with Urbit is code, but the developer
+doc remains under construction.  Sorry.  We'll have more soon.
 
 <list dataSort="true"></list>
 

pub/docs/dev.mdy

@@ -5,7 +5,7 @@ sort: 2
 ---
 <div class="short">
 
-# Developer doc
+# Developer documentation
 
 Urbit has three programming layers: Nock (combinator nano-VM),
 Hoon (strict functional language), and Arvo (functional OS).

pub/docs/theory.mdy

@@ -17,10 +17,10 @@ Everest, it's there.
 Some critics experience doubt that Urbit is actually a real
 thing.  This is forgivable.  Sometimes, visual evidence will
 correct these disturbed minds.  See our 2015 demo
-[(part1)](part-i), [(part 2)](part-ii), or our original
+[(part 1)](part-i), [(part 2)](part-ii), or our original
 [2013 demo](old).  But if the aliens could fake the moon
 landings, they could certainly fake Urbit.
 
 <list dataSort="true"></list>
 
-</div>
+</div>

pub/docs/user.mdy

@@ -5,7 +5,7 @@ sort: 1
 ---
 <div class="short">
 
-# User doc
+# User documentation
 
 Read the [introduction](intro) for a summary of Urbit.
 The [installation guide](install) gets you ready to run.
@@ -13,11 +13,11 @@ The [launch procedure](launch) holds your hand as you create
 your server image.  Once your urbit is live, the [quickstart
 page](start) is all you need if in a hurry.
 
-For power users, the [appliance handbook](admin) explains
+For power users, the [appliance handbook](appliance) explains
 your apps and how to control them.  The [filesystem handbook](clay) 
-describes the Urbit filesystem, `clay`, and how to sync it with Unix.
-Finally, the [`:dojo` manual](dojo) and [`:talk` manual](talk) 
-explain the fine points of our shell and messenger respectively.
+explains the Urbit filesystem and how to sync it with Unix.
+Finally, the [:dojo manual](dojo) and [:talk manual](talk) 
+reveal the fine points of our shell and messenger respectively.
 
 <list dataSort="true"></list>
 

pub/docs/user/appliance.mdy

@@ -1,15 +1,22 @@
 ---
-title: Basic administration
+title: Appliance handbook
 sort: 5
 next: true
 ---
 
-# Basic administration
+# Appliance handbook
 
-You've built and launched your urbit.  How do you control it?
+You've built and launched your urbit.  How do you control it
+securely?  Three ways: through the Unix console, over the Web,
+or via an Urbit moon.
 
-You have three ways to drive your brand-new urbit: through the
-Unix console, through the Web, or through an Urbit moon.
+What are you controlling, anyway?  A user-level application on
+Urbit is called an "appliance."  Think of an appliance as like a
+Unix process that's also a persistent database.
+
+By default, your urbit is running two appliances, the `:dojo`
+shell and the `:talk` messenger.  For more advanced information
+about your appliance state, see the end of this document.
 
 ## Console
 
@@ -265,5 +272,3 @@ specified, the desk is `%home`:
     |start %foo %away
 
 If the appliance is running, `|start` sets its desk instead.
-
-

pub/docs/user/clay.mdy

@@ -1,9 +1,9 @@
 ---
-title: Filesystem
-sort: 8
+title: Filesystem handbook
+sort: 6
 ---
 
-# The Urbit filesystem, `%clay`
+# Filesystem handbook
 
 Urbit has its own revision-controlled filesystem, the `%clay`
 vane.  `%clay` is like a simplified `git`, but more reactive,

pub/docs/user/dojo.mdy

@@ -1,10 +1,10 @@
 ---
 title: Dojo manual
-sort: 7
+sort: 8
 next: true
 ---
 
-# `:dojo`
+# `:dojo` manual
 
 The dojo is a typed functional shell.  Its prompt is:
 

pub/docs/user/talk.mdy

@@ -1,10 +1,10 @@
 ---
 title: Talk manual
-sort: 6
+sort: 7
 next: true
 ---
 
-# `:talk`
+# `:talk` manual
 
 `:talk` is the Urbit appliance for chatter and notifications.
 For less sophisticated users, Urbit *is* just `:talk`.  If you