docs: add github architecture diagrams

Author: BunsDev

COVEN-GITHUB.md

@@ -9,6 +9,8 @@
 
 A GitHub App that turns any Coven-configured familiar into a first-class GitHub coding agent. Assign an issue to `@cody` (or any familiar bot user), and the familiar plans, edits, commits, and opens a pull request — with live oversight in CovenCave and no black-box model lock-in.
 
+For the GitHub-rendered system diagrams that explain this repo at a glance, see [docs/architecture.md](docs/architecture.md).
+
 ---
 
 ## Problem
@@ -43,7 +45,29 @@ Mixing these creates a monolith that is hard to test, deploy, and reason about.
 
 ### Session Lifecycle
 
+```mermaid
+sequenceDiagram
+    participant GitHub
+    participant Webhook as coven-github webhook
+    participant Worker as coven-github worker
+    participant Runtime as coven-code headless
+    participant Cave as CovenCave
+
+    GitHub->>Webhook: Signed webhook for issue, label, mention, or review
+    Webhook->>Webhook: Validate HMAC and route familiar
+    Webhook->>GitHub: Create Check Run
+    Webhook->>Worker: Enqueue task
+    Worker->>Runtime: Start session with session-brief.json
+    Worker->>Cave: Publish live status link
+    Runtime-->>Worker: Structured progress and result.json
+    Worker->>GitHub: Update Check Run
+    Runtime->>GitHub: Push branch
+    Worker->>GitHub: Open draft PR and link issue
 ```
+
+The same lifecycle in operational prose:
+
+```text
 1. Webhook arrives
    → validate HMAC signature (reject invalid)
    → parse event: repo, ref, issue body/diff, assignee/label/mention

DESIGN.md

@@ -2,6 +2,8 @@
 
 `coven-github` is a thin GitHub ingress layer for trusted familiar work. It should not become a generic agent platform inside the GitHub App. The GitHub App accepts repository events, routes them to the right familiar, records task state, and keeps humans in control through Cave oversight.
 
+For a visual system map, webhook sequence, task lifecycle, and trust-boundary diagrams, see [Architecture Diagrams](docs/architecture.md).
+
 ## Design Goal
 
 Assign GitHub work to a known familiar and get a draft PR back with visible context, evidence, and an oversight path.
@@ -15,16 +17,19 @@ The core design constraint is trust continuity:
 
 ## Task Flow
 
-```text
-GitHub event
-  -> webhook HMAC validation
-  -> event parsing and familiar routing
-  -> task record and queue
-  -> worker starts isolated session
-  -> coven-code --headless receives session brief
-  -> familiar drafts changes and result envelope
-  -> GitHub Check Run and PR are updated
-  -> Cave Board and session link expose oversight
+```mermaid
+flowchart LR
+    event[GitHub event]
+    hmac[Webhook HMAC validation]
+    route[Event parsing and familiar routing]
+    task[Task record and queue]
+    worker[Worker starts isolated session]
+    brief[coven-code receives session brief]
+    result[Familiar drafts changes and result envelope]
+    github[GitHub Check Run and PR updated]
+    cave[Cave Board and session link expose oversight]
+
+    event --> hmac --> route --> task --> worker --> brief --> result --> github --> cave
 ```
 
 ## Routing Model

HOSTED.md

@@ -4,6 +4,23 @@ Hosted OpenCoven is the managed version of `coven-github`: install the GitHub Ap
 
 The hosted tier should monetize managed reliability and familiar continuity, while the open-source adapter remains self-hostable for trust and inspection.
 
+See [Architecture Diagrams](docs/architecture.md) for the hosted vs self-hosted deployment diagram and trust-boundary map.
+
+## Hosted Flow
+
+```mermaid
+flowchart LR
+    install[Install hosted GitHub App]
+    route[Configure familiar routing]
+    trigger[Assign issue or add trigger label]
+    queue[Managed queue and task history]
+    worker[Managed isolated worker]
+    pr[Draft PR with Check Run evidence]
+    cave[Cave oversight link]
+
+    install --> route --> trigger --> queue --> worker --> pr --> cave
+```
+
 ## What Hosted Adds
 
 | Capability | Self-hosted adapter | Hosted OpenCoven |

README.md

@@ -4,14 +4,25 @@
 
 `coven-github` is the GitHub App adapter for [OpenCoven](https://opencoven.ai). It bridges GitHub's issue and pull-request workflow with the Coven harness — turning any Coven-configured familiar into a first-class GitHub coding agent, without black-box model lock-in.
 
-```
-GitHub issue assigned to @cody
-  → coven-github webhook receiver
-  → spawns coven-code session with issue context
-  → Check Run shows live progress in GitHub UI
-  → familiar opens branch, commits, pushes
-  → PR opened and linked to original issue
-  → Cave session available for live oversight
+```mermaid
+flowchart LR
+    issue[GitHub issue, label, mention, or review comment]
+    app[coven-github GitHub App]
+    worker[coven-github worker]
+    familiar[coven-code familiar session]
+    check[GitHub Check Run]
+    pr[Draft pull request]
+    cave[CovenCave oversight]
+
+    issue --> app
+    app --> worker
+    worker --> familiar
+    worker --> check
+    familiar --> pr
+    worker --> cave
+    check --> reviewer[Maintainer]
+    pr --> reviewer
+    cave --> reviewer
 ```
 
 ---
@@ -24,31 +35,47 @@ Every existing GitHub coding agent is a black box: GitHub's model, GitHub's cont
 
 That is the product wedge: assign it like a teammate, get a PR back, and keep Cave oversight in the loop. A familiar should know the difference between "technically works" and "good enough for this repo, this team, and this moment."
 
-See [Design](DESIGN.md), [Hosted OpenCoven](HOSTED.md), [Familiar Contract](FAMILIAR-CONTRACT.md), [Roadmap](ROADMAP.md), and [Hosted vs self-hosted](docs/hosted-vs-self-hosted.md) for the operational plan.
+See [Architecture Diagrams](docs/architecture.md), [Design](DESIGN.md), [Hosted OpenCoven](HOSTED.md), [Familiar Contract](FAMILIAR-CONTRACT.md), [Roadmap](ROADMAP.md), and [Hosted vs self-hosted](docs/hosted-vs-self-hosted.md) for the operational plan.
 
 ---
 
 ## Architecture
 
+```mermaid
+flowchart TB
+    subgraph github[GitHub]
+        trigger[Issue assignment<br/>trigger label<br/>@mention<br/>review comment]
+        checks[Check Run]
+        pull[Draft PR]
+    end
+
+    subgraph adapter[coven-github]
+        webhook[Webhook receiver<br/>HMAC validation<br/>event parsing]
+        routing[Familiar routing<br/>bot username<br/>trigger labels]
+        tasks[Task queue/store<br/>status and audit]
+        runner[Worker<br/>session brief<br/>timeout enforcement]
+    end
+
+    subgraph runtime[OpenCoven runtime]
+        session[coven-code --headless]
+        result[Result envelope<br/>summary, branch, evidence]
+    end
+
+    cave[CovenCave oversight<br/>live session and intervention]
+
+    trigger --> webhook
+    webhook --> routing
+    routing --> tasks
+    tasks --> runner
+    runner --> session
+    session --> result
+    result --> runner
+    runner --> checks
+    runner --> pull
+    runner --> cave
 ```
-GitHub
-  │ webhook (issue assigned / @mention / label)
-  ▼
-coven-github (this repo)
-  │ validates HMAC · enqueues task · creates Check Run
-  ▼
-coven-code --headless --context session-brief.json
-  │ agent loop: reads code · edits · runs tests
-  │ emits structured progress events
-  ▼
-GitHub Check Run API     ← live status: "Cody: running tests…"
-  │
-  ▼
-git push → GitHub PR     ← opened by coven-code's git tool
-  │
-  ▼
-CovenCave oversight UI   ← watch session live, intervene, steer
-```
+
+For deeper system, sequence, state, security-boundary, and hosted deployment diagrams, read [docs/architecture.md](docs/architecture.md).
 
 ### Components