Complete Age lifecycle management (#8)

docs/AGES.md

@@ -0,0 +1,39 @@
+# Age administration
+
+Rivencraft owns each Age definition for the lifetime of a world. A definition
+contains the Age UUID, canonical name, seed, generation version, runtime
+dimension identifier, spawn, and deterministic traits. Definitions are stored
+in the Overworld saved data and are never rerolled during ordinary loading.
+
+## Lifecycle
+
+An Age definition is created before its runtime dimension. If dimension
+creation is interrupted, the saved definition remains authoritative and the
+same Age is reconstructed the next time its Descriptive Book is used.
+
+Registered Ages load when the server starts. A book also loads its destination
+on demand when an administrator previously unloaded it. Unloading retains the
+definition and world folder, so existing books continue to reference the same
+Age and later reload the same terrain.
+
+Rivencraft does not automatically delete Ages. Safe permanent deletion needs a
+complete reference index for books in inventories, containers, Book Stands,
+and unloaded chunks. Until that exists, retaining the definition prevents an
+administrator action from silently orphaning books.
+
+Destination-preview chunk loaders are temporary. Rivencraft releases them when
+the book closes, the player travels, the player disconnects, the destination
+Age is unloaded, or the server stops.
+
+## Commands
+
+The commands require permission level 2.
+
+- `/rivencraft age list` lists every registered Age and whether its runtime
+  dimension is currently loaded.
+- `/rivencraft age unload <dimension>` safely unloads one Age. Players in that
+  Age are handled by Dynamic Dimensions, and its definition and world data are
+  retained. Use the command suggestions to select a registered dimension.
+
+Opening a Descriptive Book for an unloaded Age loads it again from its saved
+definition.

docs/PORTING.md

@@ -46,6 +46,8 @@ acceptance issue and all required implementation issues are complete.
 Age references use UUIDs rather than dimension keys. The server-owned Age
 registry maps each stable identity to its immutable definition and runtime
 dimension, keeping saved books valid if an Age is migrated or regenerated.
+Operational lifecycle and unload behavior are documented in
+[AGES.md](AGES.md).
 
 The core mod must remain usable without Create, Ponder, or Immersive Portals.
 The built-in legacy animation is the dependency-free destination preview.