docs: add 10 Mermaid diagrams across site and project docs

Site docs (6):
- ACL resolution chain flowchart (access-control.md)
- Password login sequence diagram (authentication.md)
- Auth middleware priority flowchart (authentication.md)
- Cross-graph proxy node diagram (cross-graph-links.md)
- Task status state diagram (tasks.md)
- Sequential indexing phases (embeddings.md)

Project docs (4):
- Architecture overview — replaced ASCII with Mermaid (architecture.md)
- Hybrid search pipeline flowchart (search.md)
- Three-queue indexer diagram (indexer.md)
- Bidirectional watcher sync diagram (watcher.md)

Author: prih

docs/architecture.md

@@ -2,63 +2,60 @@
 
 ## High-level diagram
 
-```
-┌──────────────────────────────────────────────────────────────────────┐
-│                              CLI                                     │
-│                   src/cli/index.ts (Commander)                       │
-│                                                                      │
-│   index ──── scan + embed + save + exit                              │
-│   serve ──── HTTP server + MCP + REST API + UI + WebSocket           │
-│   users ──── user management (add users to config)                   │
-└──────────────────────────┬───────────────────────────────────────────┘
-                           │
-            ┌──────────────┴──────────────┐
-            ▼                              ▼
-     ┌─────────────┐            ┌──────────────────┐
-     │ YAML Config │            │ ProjectManager   │
-     │ (Zod valid) │            │ (multi-project)  │
-     └──────┬──────┘            └────────┬─────────┘
-            │                            │
-            ▼                            ▼
-     ┌──────────────────────────────────────────┐
-     │           ProjectIndexer                 │
-     │   3 serial queues: docs / code / files   │
-     │   chokidar watcher for live updates      │
-     └──────────────────┬───────────────────────┘
-                        │
-                        ▼
-     ┌──────────────────────────────────────────┐
-     │         Embedding (transformers.js)      │
-     │   embed() / embedBatch() / loadModel()   │
-     │   named registry + model deduplication   │
-     └──────────────────┬───────────────────────┘
-                        │
-                        ▼
-     ┌──────────────────────────────────────────┐
-     │           Graphs (Graphology)            │
-     │                                          │
-     │   DocGraph ────── markdown chunks        │
-     │   CodeGraph ───── AST symbols            │
-     │   KnowledgeGraph  user notes + facts     │
-     │   FileIndexGraph  all project files      │
-     │   TaskGraph ───── tasks + kanban          │
-     │   SkillGraph ──── reusable recipes       │
-     └──────────────────┬───────────────────────┘
-                        │
-     ┌──────────────────┴───────────────────────┐
-     │        Graph Managers (unified API)       │
-     │                                          │
-     │   embed + CRUD + dirty + events          │
-     │   + cross-graph cleanup                  │
-     └──────────────────┬───────────────────────┘
-                        │
-         ┌──────────────┼──────────────┐
-         ▼              ▼              ▼
-     ┌────────┐   ┌──────────┐   ┌──────────┐
-     │  MCP   │   │ REST API │   │    UI    │
-     │ Tools  │   │ Express  │   │  React   │
-     │ (70)   │   │ + WS     │   │  + Vite  │
-     └────────┘   └──────────┘   └──────────┘
+```mermaid
+graph TD
+    CLI["CLI (commander)"]
+    Config["YAML Config"]
+    PM["ProjectManager"]
+
+    CLI --> Config
+    CLI --> PM
+
+    subgraph Indexer["ProjectIndexer"]
+        DQ["docs queue"]
+        CQ["code queue"]
+        FQ["files queue"]
+    end
+
+    PM --> Indexer
+
+    subgraph Embed["Embedding Layer"]
+        ONNX["ONNX Runtime"]
+        Models["bge-m3 / jina-code"]
+    end
+
+    Indexer --> Embed
+
+    subgraph Graphs
+        DocG["DocGraph"]
+        CodeG["CodeGraph"]
+        KG["KnowledgeGraph"]
+        TG["TaskGraph"]
+        SG["SkillGraph"]
+        FIG["FileIndexGraph"]
+    end
+
+    Embed --> Graphs
+
+    subgraph Managers["Graph Managers"]
+        DM["DocGraphManager"]
+        CM["CodeGraphManager"]
+        KM["KnowledgeGraphManager"]
+        TM["TaskGraphManager"]
+        SM["SkillGraphManager"]
+        FM["FileIndexGraphManager"]
+    end
+
+    Graphs --> Managers
+
+    subgraph API["API Layer"]
+        MCP["MCP Tools (70)"]
+        REST["REST Routes"]
+        WS["WebSocket"]
+        UI["Web UI"]
+    end
+
+    Managers --> API
 ```
 
 ## Layers

docs/indexer.md

@@ -4,17 +4,20 @@ The indexer (`src/cli/indexer.ts`) walks the project directory and dispatches fi
 
 ## Architecture
 
-```
-File detected (scan or watch event)
-  ↓ micromatch pattern matching
-  ↓
-┌────────────────┬────────────────┬────────────────┐
-│   docsQueue    │   codeQueue    │   fileQueue    │
-│                │                │                │
-│ parseFile()    │ parseCodeFile()│ fs.stat()      │
-│ embedBatch()   │ embedBatch()   │ embed()        │
-│ updateFile()   │ updateCodeFile │ updateFileEntry │
-└────────────────┴────────────────┴────────────────┘
+```mermaid
+flowchart TD
+    FILE[File detected] --> MATCH{Pattern matching}
+    MATCH -->|docs patterns| DQ[Docs Queue]
+    MATCH -->|code patterns| CQ[Code Queue]
+    MATCH -->|all files| FQ[File Index Queue]
+
+    DQ --> DP[parseFile + embedBatch]
+    CQ --> CP[parseCodeFile + embedBatch]
+    FQ --> FP[fs.stat + embed]
+
+    DP --> DG[Update DocGraph]
+    CP --> CG[Update CodeGraph]
+    FP --> FG[Update FileIndexGraph]
 ```
 
 ## Three-phase sequential indexing

docs/search.md

@@ -6,6 +6,21 @@ All graph searches use the same hybrid algorithm combining BM25 keyword search a
 
 ## Hybrid search algorithm
 
+```mermaid
+flowchart TD
+    Q[Search query] --> E[Compute query embedding]
+    E --> P{Score all nodes}
+    P --> BM25[BM25 keyword score]
+    P --> VEC[Vector cosine similarity]
+    BM25 --> RRF[Reciprocal Rank Fusion]
+    VEC --> RRF
+    RRF --> SEED[Select top seeds]
+    SEED --> BFS[BFS graph expansion]
+    BFS --> MERGE[Merge & deduplicate]
+    MERGE --> FILTER[Filter by minScore]
+    FILTER --> RESULT[Return top maxResults]
+```
+
 ### Step 1: Score all nodes
 
 Two scoring methods run in parallel:

docs/watcher.md

@@ -89,6 +89,26 @@ Updated description from IDE...
 
 The watcher detects the change, parses the file, updates the TaskGraph, and the change appears in the web UI via WebSocket push.
 
+## Bidirectional sync overview
+
+```mermaid
+flowchart LR
+    subgraph ProjectWatcher["Project Watcher"]
+        PW[chokidar watches projectDir]
+        PW --> PD[Dispatch to docs/code/file queues]
+    end
+
+    subgraph MirrorWatcher["Mirror Watcher"]
+        MW[chokidar watches .notes/.tasks/.skills]
+        MW --> MC{Our write?}
+        MC -->|Yes, skip| SKIP[MirrorWriteTracker match]
+        MC -->|No, external| IMP[Import to graph]
+    end
+
+    Graph <-->|mirror write| ProjectWatcher
+    Graph <-->|import| MirrorWatcher
+```
+
 ## Real-time flow
 
 ```

site/docs/concepts/cross-graph-links.md

@@ -27,6 +27,19 @@ notes_create_link({
 
 This creates a proxy node `@code::src/lib/auth.ts::loginUser` in the Knowledge graph, with an edge from your note to that proxy.
 
+```mermaid
+graph LR
+    subgraph KnowledgeGraph
+        Note["note: auth-notes"]
+        Proxy["proxy: @code::loginUser"]
+    end
+    subgraph CodeGraph
+        Symbol["symbol: loginUser()"]
+    end
+    Note -->|references| Proxy
+    Proxy -.->|resolves to| Symbol
+```
+
 ## Proxy node format
 
 Proxy IDs follow the pattern `@{graph}::{nodeId}`:

site/docs/concepts/embeddings.md

@@ -127,6 +127,23 @@ Additionally, ONNX Runtime session options are tuned to reduce memory overhead d
 
 During initial indexing, Graph Memory processes graphs in a fixed order: **docs → files → code**. Each phase completes before the next begins. Because models are loaded lazily, this means only one embedding model is resident in memory at a time during indexing.
 
+```mermaid
+graph LR
+    subgraph Phase1["Phase 1: Docs"]
+        D1[Scan docs] --> D2[Embed with bge-m3]
+        D2 --> D3[Drain queue]
+    end
+    subgraph Phase2["Phase 2: Files"]
+        F1[Scan files] --> F2[Embed with bge-m3]
+        F2 --> F3[Drain queue]
+    end
+    subgraph Phase3["Phase 3: Code"]
+        C1[Scan code] --> C2[Embed with jina-code]
+        C2 --> C3[Drain queue]
+    end
+    Phase1 --> Phase2 --> Phase3
+```
+
 For multi-project setups where each project has its own model configuration, this reduces peak memory by up to **~3 GB** compared to loading all models simultaneously. Projects are indexed sequentially as well, so the memory footprint stays flat regardless of how many projects are configured.
 
 :::tip

site/docs/concepts/tasks.md

@@ -45,6 +45,21 @@ backlog → todo → in_progress → review → done
                                        → cancelled
 ```
 
+```mermaid
+stateDiagram-v2
+    [*] --> backlog: create (default)
+    backlog --> todo: prioritize
+    todo --> in_progress: start work
+    in_progress --> review: submit
+    review --> done: approve
+    review --> in_progress: request changes
+    backlog --> cancelled: won't do
+    todo --> cancelled: skip
+    in_progress --> cancelled: abandon
+    done --> [*]
+    cancelled --> [*]
+```
+
 | Status | Meaning |
 |--------|---------|
 | `backlog` | Identified but not prioritized yet |

site/docs/security/access-control.md

@@ -32,6 +32,19 @@ When a user accesses a graph, their effective permission is resolved through a 5
 5. server.defaultAccess       ← fallback
 ```
 
+```mermaid
+flowchart TD
+    A[Request access to graph] --> B{graph.access[userId]?}
+    B -->|found| R1[Return permission]
+    B -->|not found| C{project.access[userId]?}
+    C -->|found| R2[Return permission]
+    C -->|not found| D{workspace.access[userId]?}
+    D -->|found| R3[Return permission]
+    D -->|not found| E{server.access[userId]?}
+    E -->|found| R4[Return permission]
+    E -->|not found| F[Return server.defaultAccess]
+```
+
 This means you can set a broad default and override it at any level.
 
 ## Default behavior

site/docs/security/authentication.md

@@ -58,6 +58,19 @@ When you open the UI with authentication enabled, you see a login page.
 3. On success, the server sets two **httpOnly cookies** containing JWT tokens
 4. The UI loads and you have full access according to your permissions
 
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant UI as Web UI
+    participant S as Server
+    U->>UI: Enter email + password
+    UI->>S: POST /api/auth/login
+    S->>S: Resolve user, verify scrypt hash
+    S->>S: Sign JWT (access 15m + refresh 7d)
+    S-->>UI: Set httpOnly cookies
+    UI-->>U: App loads (AuthGate passes)
+```
+
 ### JWT tokens
 
 Two tokens are issued as secure cookies:
@@ -239,6 +252,16 @@ When a request arrives, the server checks credentials in this order:
 2. **Bearer token** -- check the `Authorization: Bearer` header; accepts both API keys (`mgm-...`) and OAuth access tokens (JWT type `oauth_access`)
 3. **Anonymous** -- if neither is present, the request uses `server.defaultAccess` permissions
 
+```mermaid
+flowchart TD
+    R[Incoming request] --> J{JWT cookie present?}
+    J -->|valid| ID1[Use JWT identity]
+    J -->|missing/invalid| B{Bearer token?}
+    B -->|API key| ID2[Use API key identity]
+    B -->|OAuth token| ID3[Use OAuth identity]
+    B -->|none| ANON[Anonymous — use defaultAccess]
+```
+
 The first successful match determines the user identity for the request.
 
 Note: OAuth refresh tokens (type `oauth_refresh`) are only accepted at `POST /api/oauth/token`. They cannot be used as Bearer tokens for API or MCP requests.