diff --git a/README.md b/README.md
index 297033e..8a43264 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,22 @@
 # nono-opencode-tinfoil
-
+ 
 A [`nono`](https://github.com/guybedford/nono) sandbox profile for running
 [OpenCode](https://opencode.ai) with access to [Tinfoil](https://tinfoil.sh)
 enclaves and other LLM providers.
-
+ 
+## Quick Start
+ 
+```bash
+git clone https://github.com/autonomic/nono-opencode-tinfoil.git
+cd nono-opencode-tinfoil
+make install
+# Ensure ~/.local/bin is in your PATH
+opencode
+```
+ 
 ## Install
 
+
 ### macOS / Linux
 
 ```bash
@@ -198,15 +209,23 @@ The profile allows network access to:
 and grants read/write access to `~/.tinfoil` for Tinfoil credentials.
 
 ## Security model
-
+ 
 - Current working directory: read/write
 - OpenCode config: read/write
 - Tinfoil config: read/write
 - SSH private keys, AWS/GCP/Azure credentials, kubeconfig: denied
 - `sudo`, `su`, `doas`, `passwd`, disk tools: denied
-
+ 
+### Environment Variables
+ 
+| Status | Variables / Patterns |
+|--------|----------------------|
+| Allowed | `PATH`, `HOME`, `USER`, `SHELL`, `TERM` |
+| Denied  | `AWS_*`, `GOOGLE_*`, `AZURE_*`, `KUBECONFIG`, `SSH_AUTH_SOCK` |
+ 
 ## Uninstall
 
+
 ```bash
 make uninstall
 ```
@@ -218,5 +237,14 @@ rm -f ~/.local/bin/nono-tui
 ```
 
 ## License
-
+ 
 GPL-3.0
+
+## Troubleshooting
+ 
+**"command not found: opencode"**
+Ensure `~/.local/bin` is in your `PATH`. Add `export PATH="$HOME/.local/bin:$PATH"` to your `.bashrc` or `.zshrc` and restart your terminal.
+ 
+**Sandbox is being bypassed**
+If you have another version of `opencode` installed (e.g. via Homebrew) that appears earlier in your `PATH` than the wrapper, the sandbox will be bypassed. Check this using `which -a opencode`. The wrapper at `~/.local/bin/opencode` must come first.
+