diff --git a/web/paradise.prs b/web/paradise.prs
index 10358b6..035f12b 100644
--- a/web/paradise.prs
+++ b/web/paradise.prs
@@ -1,21 +1,51 @@
 version 1 .
 
-Name = string .
+# # Containment
+#
+# Each `Vessel` has zero or one `Parent` asserted in its main dataspace. The vessel's parent
+# dataspace has a corresponding `Link` pointing back to the contained vessel. Each `Vessel`
+# monitors `Link` records asserted to it: each one causes tracking of the linked vessel's name
+# and genus to start, with the results published locally to the containing vessel as a
+# `LocalName` record.
 
-# a dataspace
+Link = <link @vessel Vessel> .
+Parent = <parent @vessel Vessel> .
+LocalName = <name @name Name @genus Name @vessel Vessel> .
+
+# # Homing
+#
+# When a vessel's container vanishes unexpectedly (through disconnection or destruction,
+# perhaps), the vessel's location is automatically updated to its `Home` vessel.
+
+Home = <home @vessel Vessel> .
+
+# # Object appearance
+#
+# Objects present themselves as having a name and a genus, both simple strings, plus a
+# general-purpose "properties" dictionary, all bundled up in a `Here` record asserted to their
+# main dataspace (`Vessel`).
+
+Name = string .
+Here = <here @name Name @genus Name @properties { symbol: any ...:... }> .
 Vessel = #:any .
 
+# # Event broadcasting and logging
+#
+# Players are shown a record of things that have happened "nearby", a series of `Event`s. Each
+# has a unique ID, a Unix-epoch timestamp, and a sentence made up of a sequence of
+# `EventItem`s. Each `EventItem` is either a plain piece of text, displayed as itself, or a
+# reference to a `Vessel`, displayed as its name and kept up-to-date as the name changes. Each
+# `Event` is to be asserted at a vessel for a short while and then retracted.
+
 Event = <event @id any @unixTimeMs int @description [EventItem ...]> .
 EventItem = @string string / @name <name @article Article @capitalized bool @vessel Vessel> .
 Article = =none / =a / =the .
 
-Link = <link @vessel Vessel> .
-Parent = <parent @vessel Vessel> .
-
-Here = <here @name Name @genus Name @properties { symbol: any ...:... }> .
-Home = <home @vessel Vessel> .
-
-LocalName = <name @name Name @genus Name @vessel Vessel> .
+# # Sentence parsing
+#
+# A `CommandFormat` describes an imperative sentence structure that can be used at the
+# text-based UI. A matched sentence results in a `CommandInvocation` being asserted to
+# whichever vessel is the target of the command.
 
 CommandFormat = <command-format @prefix [any ...] @pattern [MatchPredicate ...]> .
 MatchPredicate =
@@ -35,6 +65,10 @@ MatchFilter =
 
 CommandInvocation = <command @id any @unixTimeMs int @agent Vessel @body [any ...]> .
 
+# # Command S-expressions
+#
+# These are a few common forms of command understood by vessels.
+
 VesselCommand =
 / @say ["say", @message string]
 / @destroy ["destroy"]
@@ -49,6 +83,3 @@ VesselCommand =
 .
 
 GotoAction = "initial" / "link" / "move" / "give" / "put" / "take" / "drop" / "enter" .
-
-# For upgrades from before there was the notion of genus.
-SavedHere = @new Here / @old <here @name Name @properties { symbol: any ...:... }> .