[docs] docs: add AWF_ONE_SHOT_TOKEN_DEBUG documentation

docs/environment.md

@@ -68,6 +68,33 @@ The following environment variables are set internally by the firewall and used
 
 **Note:** These are set automatically based on CLI options and should not be overridden manually.
 
+## Debugging Environment Variables
+
+The following environment variables control debugging behavior:
+
+| Variable | Description | Default | Example |
+|----------|-------------|---------|---------|
+| `AWF_ONE_SHOT_TOKEN_DEBUG` | Enable debug logging for one-shot-token library | `off` | `1` or `true` |
+
+### One-Shot Token Debug Logging
+
+The one-shot-token library protects sensitive tokens (GITHUB_TOKEN, OPENAI_API_KEY, etc.) from environment variable inspection. By default, it operates silently. To troubleshoot token caching issues, enable debug logging:
+
+```bash
+# Enable debug logging
+export AWF_ONE_SHOT_TOKEN_DEBUG=1
+
+# Run AWF with sudo -E to preserve the variable
+sudo -E awf --allow-domains github.com 'your-command'
+```
+
+When enabled, the library logs:
+- Token initialization messages
+- Token access and caching events
+- Environment cleanup confirmations
+
+**Note:** Debug output goes to stderr and does not interfere with command stdout. See `containers/agent/one-shot-token/README.md` for complete documentation.
+
 **Historical note:** Prior to v0.13.5, `HTTP_PROXY` and `HTTPS_PROXY` were set to point to Squid. These have been removed in favor of transparent iptables-based redirection, which is more reliable and avoids conflicts with tools that don't honor proxy environment variables.
 
 ## Troubleshooting

docs/troubleshooting.md

@@ -87,6 +87,32 @@
   echo $GITHUB_TOKEN  # Should print the token
   ```
 
+### Token Caching Issues
+
+**Problem:** Sensitive tokens (GITHUB_TOKEN, OPENAI_API_KEY, etc.) not being properly cached or cleared
+
+**Solution:**
+1. Enable debug logging for the one-shot-token library:
+   ```bash
+   export AWF_ONE_SHOT_TOKEN_DEBUG=1
+   sudo -E awf --allow-domains ... 'your-command'
+   ```
+2. Check the debug output for:
+   - `Initialized with N default token(s)` - Library loaded successfully
+   - `Token <NAME> accessed and cached` - Token was read and cached
+   - `INFO: Token <NAME> cleared from process environment` - Token removed from /proc/environ
+   - `WARNING: Token <NAME> still exposed` - Token cleanup failed (security concern)
+3. If tokens are still exposed, check:
+   - The token name is in the default protected list (see `containers/agent/one-shot-token/README.md`)
+   - Or set `AWF_ONE_SHOT_TOKENS` to explicitly protect custom tokens:
+     ```bash
+     export AWF_ONE_SHOT_TOKENS="MY_CUSTOM_TOKEN,ANOTHER_TOKEN"
+     export AWF_ONE_SHOT_TOKEN_DEBUG=1
+     sudo -E awf --allow-domains ... 'your-command'
+     ```
+
+**Note:** Debug output goes to stderr. Use `2>&1 | tee debug.log` to capture it.
+
 ## MCP Server Issues
 
 ### MCP Server Can't Connect