diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 73d38b2e1..1b6b0851c 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -43,6 +43,7 @@
 
 # Bootc usage in containers
 
+- [Read-only when in a default container](bootc-in-container.md)
 - [`man bootc-container-lint`](man/bootc-container-lint.md)
 
 # Architecture
diff --git a/docs/src/bootc-in-container.md b/docs/src/bootc-in-container.md
new file mode 100644
index 000000000..56783eaa8
--- /dev/null
+++ b/docs/src/bootc-in-container.md
@@ -0,0 +1,20 @@
+# bootc is read-only when run in a default container
+
+Currently, running e.g. `podman run <someimage> bootc upgrade` will not work.
+There are a variety of reasons for this, such as the basic fact that by
+default a `docker|podman run <image>` doesn't know where to update itself;
+the image reference is not exposed into the target image (for security/operational
+reasons).
+
+## Supported operations
+
+There are only two supported operations in a container environment today:
+
+- `bootc status`: This can reliably be used to detect whether the system is
+  actually booted via bootc or not.
+- `bootc container lint`: See [man/bootc-container-lint.md](man/bootc-container-lint.md).
+
+### Testing bootc in a container
+
+Eventually we would like to support having bootc run inside a container environment
+primarily for testing purposes. For this, please see the [tracking issue](https://github.com/bootc-dev/bootc/issues/400).