docs(diagrams): refresh ai-optimized mermaid flows after audit

docs/api/PROTOCOL.md

@@ -57,6 +57,11 @@ sequenceDiagram
     LQ-->>G: starts work immediately
   else lane busy
     Note over LQ: work queued (FIFO) for this lane
+    opt mode=interrupt and newer request arrives
+      LQ->>SB: request cancellation of active lane run
+      SB->>A: cancel() (best effort)
+      G-->>C: transient preempt notice (queue.preempt)
+    end
   end
 
   G->>A: process(message) in that session

docs/architecture/AGENT_DIAGRAM.md

@@ -14,6 +14,14 @@ flowchart LR
     MP[Model Providers\nAnthropic/OpenAI/Gemini/...\nvia ModelClient]
     CH[Chat Networks\nTelegram/Discord/Slack/WhatsApp/...]
     WEB[Web\nsearch/fetch targets]
+    GOOG[Google APIs\nGmail/Calendar/Docs/Drive/Tasks]
+  end
+
+  subgraph CFG[Config Sources]
+    CD[config/default.yaml]
+    CO[config/profiles/*.overlay.yaml]
+    CG[Generated config profile\nconfig/paas.yaml]
+    CE[ENV vars + expansion]
   end
 
   subgraph HOST[Host (Flynn Daemon)]
@@ -29,6 +37,9 @@ flowchart LR
     MEM[Memory Store\nfiles + vector/keyword]
     AU[Audit Logger\nredacted]
     HS[Hooks/Autonomy\nconfirm/log/silent]
+    GA[Google OAuth Runtime\nsrc/google/oauth.ts]
+    AS[Auth Store\n~/.config/flynn/auth.json]
+    TF[Legacy Token Files\n~/.config/flynn/*-token.json]
   end
 
   subgraph SBX[Sandbox (per-session Docker)]
@@ -37,6 +48,13 @@ flowchart LR
     NET[Sandbox Network\n(egress policy)]
   end
 
+  CD --> CG
+  CO --> CG
+  CE --> CG
+
+  CG --> RT
+  CE --> RT
+
   CH --> CA
   GW --> RT
   CA --> RT
@@ -57,6 +75,10 @@ flowchart LR
   ST --> NET
 
   TE -->|web tools| WEB
+  TE -->|google tools| GA
+  GA --> GOOG
+  GA <--> AS
+  GA --> TF
 ```
 
 ## Big Picture (Runtime Data Flow)
@@ -228,10 +250,15 @@ sequenceDiagram
   participant NA as NativeAgent
   participant MR as ModelRouter
   participant MC as ModelClient
+  participant FC as Fallback Client
   participant TP as ToolPolicy/Registry
   participant TE as ToolExecutor
   participant HE as HookEngine
   participant AL as AuditLogger
+  participant GA as Google OAuth Runtime
+  participant AS as Auth Store
+  participant TF as Token Files
+  participant GP as Google APIs
 
   U->>CA: message
   CA->>CR: onMessage(InboundMessage)
@@ -241,7 +268,13 @@ sequenceDiagram
   AR->>NA: process(userMessage)
   NA->>MR: chat(messages + tools)
   MR->>MC: provider request
-  MC-->>MR: response (content or tool_calls)
+  alt primary model success
+    MC-->>MR: response (content or tool_calls)
+  else primary model error
+    Note over MR: retry + tier/global fallback\n(skip duplicate clients)
+    MR->>FC: fallback provider request
+    FC-->>MR: fallback response
+  end
   MR-->>NA: ChatResponse
 
   alt model requests tool use
@@ -249,6 +282,16 @@ sequenceDiagram
     NA->>TE: execute(tool, args, context)
     TE->>HE: confirm/log/silent (autonomy)
     HE-->>TE: approved/denied
+    alt google.* tool execution
+      TE->>GA: createGoogleOAuth2Client(service)
+      GA->>AS: load stored token
+      alt auth store token missing
+        GA->>TF: read legacy token file
+        TF-->>GA: token
+        GA->>AS: migrate token record
+      end
+      GA->>GP: API request with refreshed OAuth creds
+    end
     TE->>AL: audit (redacted)
     TE-->>NA: ToolResult
     NA->>MR: chat(tool_result blocks)

docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md

@@ -15,11 +15,16 @@ If you only want the protocol surface, see `docs/api/PROTOCOL.md`.
 
 ```mermaid
 flowchart LR
+  subgraph CFG[Config + Runtime Policy]
+    QP[server.queue policy\nmode/cap/overflow/overrides]
+  end
+
   subgraph GW[Gateway Process]
     WS[WebSocket connection\n(connectionId)]
     GS[GatewayServer]
     LQ[LaneQueue\nper-session FIFO]
     SB[SessionBridge\nconnectionId -> sessionId -> AgentOrchestrator]
+    AQ[AuditLogger\nqueue.preempt events]
   end
 
   subgraph CORE[Flynn Core]
@@ -29,8 +34,10 @@ flowchart LR
   end
 
   WS --> GS
+  QP --> GS
   GS --> LQ
   GS --> SB
+  LQ --> AQ
 
   SB --> AO
   SB --> SM
@@ -97,4 +104,3 @@ Key files:
 
 - `src/gateway/handlers/agent.ts`
 - `src/backends/native/orchestrator.ts`
-

docs/plans/state.json

@@ -7,7 +7,7 @@
       "status": "completed",
       "date": "2026-02-24",
       "updated": "2026-02-24",
-      "summary": "Completed a repo-wide audit and implemented hardening/refactors for Google OAuth token handling, router fallback correctness, config-profile consolidation, and audit logging path behavior. Added Google service coverage to `flynn doctor`, introduced a unified `flynn google-auth` command, aligned fallback-chain defaults with runtime semantics, expanded provider capability type coverage, and produced operator/agent-facing documentation plus REPORT.md.",
+      "summary": "Completed a repo-wide audit and implemented hardening/refactors for Google OAuth token handling, router fallback correctness, config-profile consolidation, and audit logging path behavior. Added Google service coverage to `flynn doctor`, introduced a unified `flynn google-auth` command, aligned fallback-chain defaults with runtime semantics, expanded provider capability type coverage, produced operator/agent-facing documentation plus REPORT.md, and refreshed Mermaid architecture/protocol diagrams to match the new flows.",
       "files_modified": [
         "src/auth/google.ts",
         "src/google/oauth.ts",
@@ -28,6 +28,9 @@
         "README.md",
         "docs/operations/GOOGLE_AUTH.md",
         "docs/architecture/AGENT_REPO_MAP.md",
+        "docs/architecture/AGENT_DIAGRAM.md",
+        "docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md",
+        "docs/api/PROTOCOL.md",
         "REPORT.md",
         "docs/plans/state.json"
       ],