docs: add static architecture diagrams to the site

.github/mkdocs/hooks.py

@@ -65,6 +65,10 @@ def _rewrite(target, page, config):
     site = _site_path(resolved)
     if site is not None:
         return posixpath.relpath(site, posixpath.dirname(page.file.src_uri) or ".") + fragment
+    # Files under docs/ are published with the site, not served from GitHub.
+    if resolved.startswith("docs/") and (ROOT / resolved).is_file():
+        asset = resolved[len("docs/"):]
+        return posixpath.relpath(asset, posixpath.dirname(page.file.src_uri) or ".") + fragment
     branch = "blob" if (ROOT / resolved).is_file() else "tree"
     return f"{config['repo_url'].rstrip('/')}/{branch}/main/{resolved}{fragment}"
 

README.md

@@ -64,6 +64,8 @@ OpenCode runs every tool call in its server, not in the TUI, so each agent
 gets two sandboxes: a **server sandbox** (OpenCode's private server and every
 tool it runs) and a **client sandbox** (the TUI).
 
+![Launch flow: Herdr starts an action that opens an agent pane; its bridge launches separate server and client sandboxes, verifies both from the host, and records the result.](docs/images/launch.svg)
+
 | | Server sandbox: server and tools | Client sandbox: TUI |
 | --- | --- | --- |
 | Project files | Read-write: the worktree or git repository of the focused pane | Same |

docs/design.md

@@ -1,5 +1,17 @@
 # Design
 
+## Launch and verification
+
+The action runs briefly under Herdr; the bridge stays in the agent pane for
+the lifetime of the session. The server and client run in separate nono
+sandboxes, while verification and the pane mapping stay outside both.
+
+![Launch flow: Herdr starts the action, which opens a pane and saves a mapping; the bridge starts a client and a private server in separate sandboxes, then verifies them from the host and records the outcome.](images/launch.svg)
+
+The client can reach only its private server port; the server runs tools and
+uses nono's proxy for allowed provider hosts. See [Security](security.md) for
+the network and trust boundaries.
+
 ## Two plugin processes
 
 Herdr runs plugin actions as short-lived processes without a terminal, so

docs/security.md

@@ -19,19 +19,7 @@ The plugin picks the port `P` and a fresh password (`OPENCODE_PASSWORD`) on
 every launch; the server rejects requests without it. `--server` is a required
 argument that configuration cannot replace.
 
-```mermaid
-flowchart LR
-    subgraph client["client sandbox: network blocked"]
-      CLIENT["opencode --server http://127.0.0.1:P<br/>(TUI)"]
-    end
-    subgraph server["server sandbox: provider hosts via nono proxy"]
-      SERVER["opencode serve --port P"] --> TOOLS["tools: bash, edits, ..."]
-    end
-    SVC["OpenCode host service<br/>127.0.0.1:4096 (unsandboxed)"]
-    CLIENT -->|"port P + password"| SERVER
-    SERVER --> PROXY["nono proxy"] --> NET(("GitHub Copilot"))
-    TOOLS -. "denied, directly and via the proxy" .-> SVC
-```
+![Security boundary: the network-blocked client reaches only its private server port; the sandboxed server runs tools and reaches allowed provider hosts through nono's proxy. Neither sandbox can reach the unsandboxed OpenCode host service.](images/security-boundary.svg)
 
 ## What each sandbox can reach