Merge REVIEW.md: expanded comparison table, condensed troubleshooting with dedicated page, Quick Start cleanup

Author: bethropolis

.github/workflows/docs.yml

@@ -45,7 +45,7 @@ jobs:
 
       - name: Fix asset paths in subdirectory pages
         run: |
-          for dir in architecture config export guest dbus-proxy quadlet protocol; do
+          for dir in architecture config export guest dbus-proxy quadlet protocol troubleshooting; do
             [ -d "site/$dir" ] && find "site/$dir" -name '*.html' -exec \
               sed -i 's|"assets/|"../assets/|g' {} +
           done

README.md

@@ -20,7 +20,7 @@
 ## Quick Start
 
 ```bash
-# 1. Install via pre-built binary
+# Install via pre-built binary
 curl -fsSL https://bethropolis.github.io/podbox/install.sh | sh
 
 podbox create fedora    # pulls, builds, enables, starts
@@ -31,14 +31,25 @@ Also available from source: `git clone https://github.com/bethropolis/podbox &&
 
 ## Why podbox?
 
-Unlike other desktop sandboxing tools, `podbox` translates a single TOML config directly into native systemd Quadlet units — no daemon, no persistent orchestrator.
+Most desktop container tools make a trade-off: full integration means mounting your entire home directory into the container. podbox doesn't. You declare exactly what the container can see — directories, devices, and services — and nothing else is shared.
 
 | | podbox | Distrobox / Toolbox | Raw `podman run` |
 |---|---|---|---|
-| **Daemonless** | Yes (systemd units) | Yes (shell shims) | No |
-| **Sandbox** | Strict (declared dirs only) | Weak (full `$HOME` mount) | Custom per invocation |
+| **Home directory** | Isolated volume, opt-in sharing | Full `$HOME` mounted by default | Manual `-v` flags |
+| **Config** | Declarative TOML, version-controllable | Imperative CLI flags | Shell flags per run |
+| **Lifecycle** | systemd Quadlet units | Shell shims | Manual |
 | **D-Bus** | Filtered via `xdg-dbus-proxy` | Unfiltered session bus | Unfiltered |
-| **Config** | Declarative TOML | Imperative CLI params | Shell flags |
+| **Wayland / audio** | Opt-out (on by default) | Always on | Manual |
+| **GPU** | `auto` / `nvidia` / off | `--nvidia` flag | Manual device flags |
+| **Notifications** | Guest interceptor → host | Via shared D-Bus | Not supported |
+| **Clipboard** | Guest interceptor → host | Via shared home | Not supported |
+| **Host commands** | `host-exec` interceptor | `distrobox-host-exec` | Not supported |
+| **SSH agent** | Socket forward (opt-in) | Auto-mounted | Not supported |
+| **Baked images** | Yes — packages in image, not runtime | No — packages reinstalled on rebuild | N/A |
+| **Reproducibility** | Full — TOML → image → unit | Partial — image only | None |
+| **Runtime** | Podman only | Podman / Docker / lilipod | Any OCI runtime |
+
+> podbox is not a distrobox replacement. Distrobox optimises for maximum host integration and is excellent at that. podbox optimises for declared, reproducible environments where you control exactly what is shared.
 
 ## How It Works
 
@@ -148,17 +159,9 @@ Supports `linux/x86_64`. Uninstall with `scripts/uninstall.sh`.
 
 ## Troubleshooting
 
-### D-Bus proxy fails or container hangs
+Run `podbox doctor` first — it checks the most common issues automatically and explains what to fix.
 
-Missing `xdg-dbus-proxy` on the host. Install it or set `dbus = false` under `[integration]`.
-
-### UID mismatch inside mounts
-
-`UserNS=keep-id` + `User=root` maps host UID 1000 to container UID 999. Don't `chown` inside mounts — it will corrupt host ownership.
-
-### Desktop shims or interceptors not working
-
-The `podbox-guest` daemon relies on `/run/podbox/bin` being in the guest `$PATH`. Verify the systemd socket unit is active: `systemctl --user status <name>.socket`.
+For detailed guides on specific issues (container won't start, D-Bus proxy, Wayland socket errors, interceptors, UID mapping, SSH agent forwarding, build failures, shell hangs), see the [Troubleshooting Guide](docs/troubleshooting.md).
 
 ## Command Reference
 
@@ -205,6 +208,7 @@ All commands support `--dry-run` to preview without executing.
 | [D-Bus Proxy](docs/dbus-proxy.md) | Filtered D-Bus access via xdg-dbus-proxy |
 | [Quadlet Reference](docs/quadlet.md) | Generated systemd units |
 | [Host-Guest Protocol](docs/protocol.md) | Wire format and message types |
+| [Troubleshooting Guide](docs/troubleshooting.md) | Common issues and fixes |
 
 ## Contributing
 

docs/troubleshooting.md

@@ -0,0 +1,92 @@
+---
+description: Common podbox issues — container startup, D-Bus proxy, Wayland, interceptors, UID mapping, SSH agent forwarding, build failures, and shell hangs.
+---
+
+# Troubleshooting
+
+Running `podbox doctor` first is recommended — it checks the most common issues automatically and explains what to fix.
+
+---
+
+### Container won't start
+
+```bash
+systemctl --user status <name>.service   # check the unit status
+podbox logs                              # check container output
+```
+
+If the unit failed immediately after `podbox enable`, the Quadlet file may be malformed. Run `podbox enable --dry-run` to inspect the generated files without writing them.
+
+---
+
+### D-Bus proxy fails or container hangs on startup
+
+`xdg-dbus-proxy` is missing or not on `PATH`. Install it from your distro's package manager (`xdg-dbus-proxy` on most distros). Alternatively, set `dbus = false` under `[integration]` if you don't need D-Bus access.
+
+```bash
+which xdg-dbus-proxy   # should return a path
+```
+
+---
+
+### GUI apps don't appear / Wayland socket errors
+
+Verify `$WAYLAND_DISPLAY` is set on the host before starting the container. The socket is resolved at `podbox enable` time — if it changed after a reboot, re-run `podbox enable` to regenerate the Quadlet with the correct socket path.
+
+```bash
+echo $WAYLAND_DISPLAY                    # should be wayland-0 or similar
+podbox disable && podbox enable          # regenerate Quadlets
+podbox stop && podbox start
+```
+
+---
+
+### Interceptors not working (notify-send, xdg-open, clipboard, host-exec)
+
+The `podbox-guest` daemon connects to the host socket on container startup. If it can't connect, interceptors are silently skipped.
+
+```bash
+systemctl --user status <name>.socket           # check the socket unit
+podbox exec -- ps aux | grep podbox-guest       # check daemon running
+podbox exec -- echo $PATH                       # check /run/podbox/bin
+```
+
+If the socket unit is inactive, run `podbox enable` and `podbox start` again. If the daemon is running but `PATH` is wrong, the `/etc/environment.d/podbox.conf` file may not have been written — check with `podbox exec -- cat /etc/environment.d/podbox.conf`.
+
+---
+
+### UID mismatch or permission errors inside bind mounts
+
+`UserNS=keep-id` maps your host UID into the container with a shift of 1 (host UID 1000 → container UID 999). Do not run `chown` on bind-mounted directories from inside the container — it will change ownership on the host through the idmapped mount.
+
+If files appear owned by `nobody` inside the container, the mount was created before the UID mapping was set up. Stop the container, check the volume path exists on the host with the correct ownership, then start again.
+
+---
+
+### SSH agent not forwarding
+
+SSH agent forwarding requires Podman >= 5.6 and `ssh_agent = true` in `[integration]`. Verify both:
+
+```bash
+podman --version                         # must be >= 5.6
+grep ssh_agent ~/.config/podbox/<name>.toml
+```
+
+If you're on Podman 5.5, the socket path is baked at `podbox enable` time. If `$SSH_AUTH_SOCK` changed since then (e.g. new login session), re-run `podbox disable && podbox enable`.
+
+---
+
+### Build fails or produces a stale image
+
+Run `podbox build --rebuild` to force a full rebuild from scratch, bypassing the lock file. If the build context is corrupted:
+
+```bash
+rm -rf ~/.local/share/podbox/<name>/     # clear build context
+podbox build --rebuild
+```
+
+---
+
+### Container starts but `podbox shell` hangs
+
+The shell binary specified in `container.shell` may not be installed in the image. Check your `image.packages.install` list includes the shell package, then run `podbox build --rebuild`.

mkdocs.yml

@@ -36,6 +36,7 @@ nav:
   - D-Bus Proxy: dbus-proxy.md
   - Quadlet Reference: quadlet.md
   - Protocol: protocol.md
+  - Troubleshooting: troubleshooting.md
 
 extra_css:
   - stylesheets/catppuccin.css