docs: make landing pages more informative

docs/explanation/index.md

@@ -1,11 +1,40 @@
 # Explanation
 
+These guides explain how Pebble works.
+
+
+## Fundamentals
+
+Pebble works as a daemon and a client, with state and configuration stored in the `$PEBBLE` directory.
+
 ```{toctree}
 :titlesonly:
 :maxdepth: 1
 
-API and clients <api-and-clients>
 General model <general-model>
+```
+
+
+## Access to the API
+
+The daemon exposes an API that clients can connect to. By default, Pebble restricts access to some API endpoints based on the user that is connecting. You can set up named "identities" to grant specific access levels to users.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+
+API and clients <api-and-clients>
+```
+
+
+## Service orchestration
+
+Pebble automatically starts and stops services if you specify dependencies between services.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+
 Service dependencies <service-dependencies>
 Service start order <service-start-order>
 ```

docs/how-to/index.md

@@ -1,11 +1,11 @@
 # How-to guides
 
-These guides will walk you through every step of using Pebble through its complete operations lifecycle.
+These guides walk you through key operations you can perform with Pebble.
 
 
 ## Installation
 
-Installation follows a broadly similar pattern on all architectures, and you can choose to install the pre-built binary or build it from the source by yourself.
+Installation follows a similar pattern on all architectures. You can choose to install the pre-built binary or build it from the source by yourself.
 
 ```{toctree}
 :titlesonly:
@@ -29,7 +29,7 @@ Manage service dependencies <service-dependencies>
 
 ## Identities
 
-Use named identities to allow additional users to access the API.
+Use named "identities" to allow additional users to access the API.
 
 ```{toctree}
 :titlesonly:

docs/reference/index.md

@@ -1,17 +1,101 @@
 # Reference
 
+These guides provide technical information about Pebble.
+
+
+## Layers
+
+Pebble configuration is defined as a stack of "layers".
+
 ```{toctree}
 :titlesonly:
 :maxdepth: 1
 
-Changes and tasks <changes-and-tasks>
-CLI Commands <cli-commands/cli-commands>
-Health checks <health-checks>
-Identities <identities>
 Layers <layers>
 Layer specification <layer-specification>
-Log forwarding <log-forwarding>
-Notices <notices>
-Service auto-restart <service-auto-restart>
+```
+
+
+## Pebble commands
+
+The `pebble` command has several subcommands.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+
+CLI Commands <cli-commands/cli-commands>
+```
+
+
+## Pebble in containers
+
+When the Pebble daemon is running inside a remote system (for example, a separate container), you can manage the remote system using subcommands on the Pebble client.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+
 Use Pebble in containers <pebble-in-containers>
 ```
+
+
+## Access to the API
+
+You can set up named "identities" to control access to the API.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+
+Identities <identities>
+```
+
+
+## Service failures
+
+Pebble provides two ways to automatically restart services when they fail. Auto-restart is based on exit codes from services. Health checks are a more sophisticated way to test and report the availability of services.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+
+Service auto-restart <service-auto-restart>
+Health checks <health-checks>
+```
+
+
+## Changes and tasks
+
+Pebble tracks system changes as "tasks" grouped into "change" objects.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+
+Changes and tasks <changes-and-tasks>
+```
+
+
+## Notices
+
+Pebble records events as "notices". In addition to the built-in notices, clients can report custom notices.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+
+Notices <notices>
+```
+
+
+## Log forwarding
+
+Pebble can send service logs to a Loki server.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 1
+
+Log forwarding <log-forwarding>
+```