Add OpenCode sidecar architecture diagram

Author: chenbo

README.en.md

@@ -71,6 +71,31 @@ opencode-plusplus --pure   # plain OpenCode without OpenCode++
 
 `opencode-plusplus` runs preflight, ensures `.agent-context`, writes `.opencode/plugins/opencode-plusplus.ts`, prepares OpenCode commands/agent files, prints a compact 3-line readiness summary, then opens the OpenCode TUI for the current repository. The sidecar listens for `tool.execute.before`, `tool.execute.after`, `file.edited`, and `session.idle`: it blocks dangerous or hallucinated commands before execution, records command result evidence after tool execution, and runs dirty/debounced incremental verification when OpenCode becomes idle.
 
+```mermaid
+flowchart TD
+  User["User"] --> CLI["opencode-plusplus"]
+  CLI --> TUI["OpenCode TUI"]
+  TUI --> Plugin[".opencode/plugins/opencode-plusplus.ts"]
+
+  Plugin --> Before["tool.execute.before"]
+  Plugin --> After["tool.execute.after"]
+  Plugin --> Idle["session.idle"]
+
+  Before --> CommandGuard["Command Guard"]
+  Before --> BoundaryGuard["Boundary Guard"]
+  After --> EvidenceRecorder["Evidence Recorder"]
+  Idle --> IncrementalVerify["Incremental Verify"]
+
+  CommandGuard --> Latest[".agent-context/sidecar/latest.md"]
+  BoundaryGuard --> Latest
+  EvidenceRecorder --> Latest
+  IncrementalVerify --> Latest
+
+  Latest --> Report["opencode-plusplus report"]
+  Latest --> Status["opencode-plusplus status"]
+  Latest --> Doctor["opencode-plusplus doctor"]
+```
+
 ## Advanced Usage
 
 The README main path intentionally recommends only `opencode-plusplus`. Batch Harness Mode, CI-like executors, manual `verify / policy / impact`, MCP, and retrieval commands are still available for advanced users:

docs/concepts/architecture.md

@@ -12,6 +12,35 @@ The generated context remains important, but it is one part of the enhancement l
 
 Current boundary: this is not a fully autonomous coding agent. It is a context, policy, trace, and runtime-state control plane with a bounded harness-led loop. The controller consumes repository state and trace evidence, persists `.agent-context/runs/<task-id>/state.json`, and reports the next allowed action, while an external coding agent or user still executes edits and commands. Harness-led mode can invoke an executor, but the real code changes still happen inside that external executor.
 
+## OpenCode Sidecar Flow
+
+```mermaid
+flowchart TD
+  User["User"] --> CLI["opencode-plusplus"]
+  CLI --> TUI["OpenCode TUI"]
+  TUI --> Plugin[".opencode/plugins/opencode-plusplus.ts"]
+
+  Plugin --> Before["tool.execute.before"]
+  Plugin --> After["tool.execute.after"]
+  Plugin --> Idle["session.idle"]
+
+  Before --> CommandGuard["Command Guard"]
+  Before --> BoundaryGuard["Boundary Guard"]
+  After --> EvidenceRecorder["Evidence Recorder"]
+  Idle --> IncrementalVerify["Incremental Verify"]
+
+  CommandGuard --> Latest[".agent-context/sidecar/latest.md"]
+  BoundaryGuard --> Latest
+  EvidenceRecorder --> Latest
+  IncrementalVerify --> Latest
+
+  Latest --> Report["opencode-plusplus report"]
+  Latest --> Status["opencode-plusplus status"]
+  Latest --> Doctor["opencode-plusplus doctor"]
+```
+
+This is the default product path: OpenCode owns chat, code reading, edits, and tool execution; OpenCode++ owns the surrounding sidecar, evidence, guards, verification reports, and diagnostics.
+
 ## Reliability Layer Model
 
 OpenCode++ is organized as a set of Guard modules around existing coding agents:

docs/integrations/opencode-sidecar.md

@@ -49,6 +49,31 @@ The sidecar stays quiet by default. It only surfaces a TUI message when a blocke
 
 ## Workflow
 
+```mermaid
+flowchart TD
+  User["User"] --> CLI["opencode-plusplus"]
+  CLI --> TUI["OpenCode TUI"]
+  TUI --> Plugin[".opencode/plugins/opencode-plusplus.ts"]
+
+  Plugin --> Before["tool.execute.before"]
+  Plugin --> After["tool.execute.after"]
+  Plugin --> Idle["session.idle"]
+
+  Before --> CommandGuard["Command Guard"]
+  Before --> BoundaryGuard["Boundary Guard"]
+  After --> EvidenceRecorder["Evidence Recorder"]
+  Idle --> IncrementalVerify["Incremental Verify"]
+
+  CommandGuard --> Latest[".agent-context/sidecar/latest.md"]
+  BoundaryGuard --> Latest
+  EvidenceRecorder --> Latest
+  IncrementalVerify --> Latest
+
+  Latest --> Report["opencode-plusplus report"]
+  Latest --> Status["opencode-plusplus status"]
+  Latest --> Doctor["opencode-plusplus doctor"]
+```
+
 ```txt
 opencode-plusplus
   -> preflight