From b34e434917b0fe854739b14bd034bebfb3c1b6e3 Mon Sep 17 00:00:00 2001
From: Bruce Leidl <bruce@subgraph.com>
Date: Mon, 19 Mar 2018 18:09:11 -0400
Subject: [PATCH] some more info

---
 docs/realms.md | 41 ++++++++++++++++++++++++++++++++---------
 1 file changed, 32 insertions(+), 9 deletions(-)

diff --git a/docs/realms.md b/docs/realms.md
index b61777a..54062bc 100644
--- a/docs/realms.md
+++ b/docs/realms.md
@@ -1,7 +1,30 @@
+Citadel Realms
+==============
+
+In Citadel applications are installed into and run from spaces called Realms.  Realms
+are implemented internally as systemd-nspawn containers but you don't need to know
+this because the `realms` command-line tool manages creating and launching containers
+for you.
+
+
+### Application Images
+
+The root filesystem for realms are called Application Images, but we usually just call them
+appimgs. We have created a framework for constructing these images from Debian based distributions 
+which we use to build the default appimg that we provide, but we
+also encourage users to experiment with building their own images.
+
+#### Tree Application Images
+
+Tree images are the only type of application image which is currently implemented for realms.
+
+The rootfs is a tree of files on the filesystem, and also it is a btrfs subvolume.
+
+#### Block Application Images
 
 
 
-## `default` realm
+### `default` realm
 
 One realm is always selected to be the `default` realm.  The default realm
 starts automatically when the system boots.  The `realms` utility can be used
@@ -17,7 +40,7 @@ the symlink `/realm/default.realm` to point to a different realm instance direct
     citadel:~# realms default
     Default Realm: project
 
-## `current` realm
+### `current` realm
 
 If any realms are running, then one realm is always the `current` realm. The current
 realm is a realm that is being monitored by the `citadel-desktopd` daemon.  This
@@ -32,7 +55,7 @@ started by gnome-shell will run in the `current` realm.
     citadel:~# realms 
     Current Realm: main
     
-## Realms base directory layout
+### Realms base directory layout
 
 The realms base directory is stored on the storage partition at `/storage/realms` and is bind mounted to `/realms` on the root filesystem for convenience.
 
@@ -45,23 +68,23 @@ The realms base directory is stored on the storage partition at `/storage/realms
         /realm-project
         /realm-testing
 
-### `/realms/config` file
+#### `/realms/config` file
 
 This file is a template of the configuration file for individual realms.  When a new realm is created this file in copied into the new realm instance directory.  By modifying this file, the default configuration for new realm instances can be changed.
 
-### `/realms/Shared` directory
+#### `/realms/Shared` directory
 
 This directory is bind mounted to `/home/user/Shared` of each running realm that has the option `use-shared-dir` enabled.  It's a convenient way to move files between different realms and between citadel and realms.
 
-### `/realms/skel` directory
+#### `/realms/skel` directory
 
 Files which are added to this directory will be copied into the home directory of any newly created realm.  The directory is copied as a tree of files and may contain subdirectories.  
 
-### `/realms/default.realm`
+#### `/realms/default.realm`
 
 A symlink which points to a realm instance directory of the default realm.  The default realm is the realm which starts when the system is booted.
  
-### `/realms/realm-$name`
+#### `/realms/realm-$name`
 
 This is a realm instance directory, for a realm with $name as the realm name.
 
@@ -75,7 +98,7 @@ This is a realm instance directory, for a realm with $name as the realm name.
  * `/rootfs` : btrfs subvolume clone (snapshot) of an application image.
     
 
-### Realm instance directory layout
+#### Realm instance directory layout
 
     /realm-main
         config