usage: Describe filesystem semantics

I was a bit confused into thinking our `-dev` images had
`root.transient` on, but they don't quite right now because
we don't regenerate the initramfs after installing the updated
ostree in that image.

However, because bootc-image-builder today is throwing away
the immutable bit on `/` (a different bug, see
ostreedev/ostree#3094 ) we actually...
amazingly get a very similar effect in practice!

Anyways, let's go ahead and describe filesystem state here.

docs/usage.md

@@ -35,3 +35,44 @@ Then add it into your container:
 RUN mkdir -p /usr/lib/systemd/system/bootc-fetch-apply-updates.timer.d
 COPY 50-weekly.conf /usr/lib/systemd/system/bootc-fetch-apply-updates.timer.d
 ```
+
+## Filesystem interaction and layout
+
+At "build" time, this image runs the same as any other OCI image where
+the default filesystem setup is an `overlayfs` for `/` that captures all
+changes written - to anywhere.
+
+However, the default runtime (when booted on a virtual or physical host system,
+with systemd as pid 1) there are some rules around persistence and writability.
+
+The reason for this is that the primary goal is that base operating system
+changes (updating kernels, binaries, configuration) are managed in your container
+image and updated via `bootc upgrade`.
+
+In general, aim for most content in your container image to be underneath
+the `/usr` filesystem.  This is mounted read-only by default, and this
+matches many other "immutable infrastructure" operating systems.
+
+The `/etc` filesystem defaults to persistent and writable - and is the expected
+place to put machine-local state (static IP addressing, hostnames, etc).
+
+All other machine-local persistent data should live underneath `/var` by default;
+for example, the default is for systemd to persist the journal to `/var/log/journal`.
+
+### Understanding `root.transient``
+
+At a technical level today, the base image uses the
+[bootc](https://github.com/containers/bootc) project, which uses
+[ostree](https://github.com/ostreedev/ostree) as a backend. However, unlike many
+other ostree projects, this base image enables the `root.transient` feature from
+[ostree-prepare-root](https://github.com/ostreedev/ostree/blob/main/man/ostree-prepare-root.xml#L121).
+
+This has two primary effects:
+
+- Content placed underneath `/var` at container build time is moved to `/usr/share/factory/var`,
+  and on firstboot, updated files are handled via a systemd `tmpfiles.d` rule that copies
+  new files (see `/usr/lib/tmpfiles.d/ostree-tmpfiles.conf`)
+- The default `/` filesystem is writable, but not persistent.  All content added in the container
+  image in other toplevel directories (e.g. `/opt`) will be refreshed from the new container
+  image on updates, and any modifications will be lost.
+