diff --git a/docs/container-lifecycle.md b/docs/container-lifecycle.md
index 2e04b7cc..f3b6c3b9 100644
--- a/docs/container-lifecycle.md
+++ b/docs/container-lifecycle.md
@@ -87,18 +87,18 @@ from under the operator by the catalog.
 
 ## Inspecting lifecycle state
 
-Run as the archipelago service user:
-
 ```bash
-# what podman actually has
+# what podman actually has — run as the archipelago service user (rootless)
 podman ps -a --format '{{.Names}}\t{{.Status}}'
 
 # the durable desired-state signals
 cat /var/lib/archipelago/user-stopped.json
 cat /var/lib/archipelago/user-uninstalled.json
 
-# the reconciler's decisions
-journalctl --user -u archipelago | grep -iE 'reconcile|adopt|install|user.stopped'
+# the reconciler's decisions. archipelago.service is a SYSTEM unit that runs
+# as User=archipelago (WantedBy=multi-user.target), so this is not --user —
+# unlike the companion Quadlet units, which are per-user.
+sudo journalctl -u archipelago | grep -iE 'reconcile|adopt|install|user.stopped'
 ```
 
 ## Related
diff --git a/docs/quadlet-compilation.md b/docs/quadlet-compilation.md
index 1d79872a..a98aa486 100644
--- a/docs/quadlet-compilation.md
+++ b/docs/quadlet-compilation.md
@@ -65,6 +65,11 @@ Two things to note in that mapping:
 - **`Pull=never` is deliberate.** The provisioner does not pull images from here;
   the image must already be local (pre-pulled or built). A missing image surfaces
   immediately instead of retrying silently behind systemd's restart loop.
+- **`PublishPort` is dropped entirely under `Network=host`.** Podman rejects the
+  combination and the container crash-loops on exit 125, so declared ports are
+  omitted rather than rendered. With host networking the container is already on
+  the host's ports; a manifest that declares both is not an error, the mapping is
+  just silently unnecessary.
 
 ## Where units land