Refactor and improve documentation, add examples

ARCHITECTURE.md

@@ -302,93 +302,4 @@ With `-m` on Linux, you only see proxy-level denials:
 
 ## Security Model
 
-### How Each Layer Works
-
-#### Network Isolation
-
-All outbound connections are routed through local HTTP/SOCKS5 proxies that filter by domain:
-
-- Direct socket connections are blocked at the OS level (syscall filtering on macOS, network namespace on Linux)
-- Only localhost connections to the proxy ports are allowed
-- The proxy inspects the target domain and allows/denies based on config
-- Environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`) route application traffic
-
-#### Filesystem Restrictions
-
-Access control follows a deny-by-default model for writes:
-
-| Operation | Default | Config |
-|-----------|---------|--------|
-| Read | Allow all | `denyRead` blocks specific paths |
-| Write | Deny all | `allowWrite` permits specific paths |
-| Write exceptions | - | `denyWrite` overrides `allowWrite` |
-
-#### Dangerous File Protection
-
-Certain paths are always protected from writes regardless of config to prevent common attack vectors:
-
-**Protected files:**
-
-- Shell configs: `.bashrc`, `.bash_profile`, `.zshrc`, `.zprofile`, `.profile`
-- Git config: `.gitconfig`, `.gitmodules`, `.git/config` (can define aliases that run code)
-- Git hooks: `.git/hooks/*` (can execute arbitrary code on git operations)
-- Tool configs: `.ripgreprc`, `.mcp.json`
-
-**Protected directories:**
-
-- IDE/editor settings: `.vscode`, `.idea`
-- Claude agent configs: `.claude/commands`, `.claude/agents`
-
-#### Process Isolation
-
-- Commands run in isolated namespaces (Linux) or with syscall restrictions (macOS)
-- PID namespace isolation prevents seeing/signaling host processes (Linux)
-- New session prevents terminal control attacks
-
-### What Fence Blocks
-
-| Attack Vector | How It's Blocked |
-|---------------|------------------|
-| Arbitrary network access | Proxy filtering + OS-level enforcement |
-| Data exfiltration to unknown hosts | Only allowlisted domains reachable |
-| Writing malicious git hooks | `.git/hooks` always protected |
-| Modifying shell startup files | `.bashrc`, `.zshrc`, etc. always protected |
-| Reading sensitive paths | Configurable via `denyRead` |
-| Arbitrary filesystem writes | Only `allowWrite` paths permitted |
-
-### What Fence Allows
-
-- Network access to explicitly allowed domains
-- Filesystem reads (except `denyRead` paths)
-- Filesystem writes to `allowWrite` paths
-- Process spawning within the sandbox
-- Inbound connections on exposed ports (`-p` flag)
-
-### Limitations
-
-#### Domain-based filtering only
-
-Fence doesn't inspect request content. A sandboxed process can:
-
-- Download arbitrary code from allowed domains
-- Exfiltrate data by encoding it in requests to allowed domains
-- Use allowed domains as tunnels if they support it
-
-You're trusting your allowlist - if you allow `*.github.com`, the sandbox can reach any GitHub-hosted content.
-
-#### Root processes may escape restrictions
-
-- *Linux*: The sandboxed process has root inside its namespace and could potentially manipulate mounts, cgroups, or exploit kernel vulnerabilities. Network namespace isolation (`--unshare-net`) is solid, but filesystem isolation via bind mounts is more permeable.
-- *macOS*: `sandbox-exec` is robust at the kernel level, but root can modify system state before the sandbox starts or (on older macOS) load kernel extensions.
-
-#### macOS sandbox-exec is deprecated
-
-Apple deprecated `sandbox-exec` but it still works on current macOS (including Sequoia). There's no good alternative for CLI sandboxing:
-
-- App Sandbox requires signed `.app` bundles
-- Virtualization.framework is heavyweight
-- We use `sandbox-exec` pragmatically until Apple removes it
-
-#### Not for hostile code containment
-
-Fence is defense-in-depth for running semi-trusted code (npm install, build scripts, CI jobs), not a security boundary against actively malicious software designed to escape sandboxes.
+See [`docs/security-model.md`](docs/security-model.md) for Fence's threat model, guarantees, and limitations.