docs: overhaul docs, add architecture and traces, update README/GEMINI

- Add docs/architecture.md with 4 mermaid diagrams - Add docs/mitm.md with 3 mermaid diagrams (replaces mitm-interception-status) - Add docs/traces.md documenting per-call trace system - Rewrite README.md to be concise with mermaid and doc refs - Rewrite GEMINI.md for core philosophy and agent usage - Clean extension-server-analysis.md (remove stale debug sections) - Delete temp docs: standalone-ls-todo, panel-stream-investigation, endpoint-gap-analysis, request-comparison
2026-02-18 01:31:18 -06:00
parent 28d3296c87
commit 3d87c04d20
11 changed files with 679 additions and 1305 deletions
--- a/docs/traces.md
+++ b/docs/traces.md
@@ -0,0 +1,118 @@
+# Trace System
+
+Per-call debug traces for inspecting request/response flow. Every API call writes a structured trace directory.
+
+## Location
+
+```
+~/.config/antigravity-proxy/traces/{YYYY-MM-DD}/{HH-MM-SS.sss}_{cascade_short}/
+```
+
+Disable with `--no-trace`.
+
+## Files Per Trace
+
+| File            | Purpose                                                    |
+| --------------- | ---------------------------------------------------------- |
+| `meta.txt`      | One-line grep-friendly summary                             |
+| `summary.md`    | Human-readable trace overview with tables                  |
+| `request.json`  | Client request metadata (message count, preview, tools)    |
+| `response.json` | Token usage (input, output, thinking, cache)               |
+| `turns.json`    | Per-turn details (MITM match, gate wait, response preview) |
+
+## Data Flow
+
+```mermaid
+sequenceDiagram
+    participant H as API Handler
+    participant T as TraceHandle
+    participant D as Disk
+
+    H->>T: trace.start(cascade_id, endpoint, model)
+    H->>T: set_client_request(preview, tool_count, ...)
+    Note over H: Request processing...
+    H->>T: start_turn()
+    H->>T: record_mitm_match(gate_wait_ms)
+    Note over H: Response arrives...
+    H->>T: record_response(text_len, preview, finish_reason)
+    H->>T: set_usage(input, output, thinking, cache)
+    H->>T: finish("completed")
+    T->>D: Write meta.txt, summary.md, request.json, response.json, turns.json
+```
+
+## Example: meta.txt
+
+```
+cascade=e57e3ddf endpoint=POST gemini model=gemini-3-flash outcome=completed duration=1865ms stream=false
+```
+
+## Example: request.json
+
+```json
+{
+  "message_count": 2,
+  "tool_count": 3,
+  "tool_round_count": 0,
+  "user_text_len": 46,
+  "user_text_preview": "You are a pirate.\n\nSay ahoy in exactly 3 words",
+  "system_prompt": true,
+  "has_image": false
+}
+```
+
+## Example: turns.json
+
+```json
+[
+  {
+    "turn": 0,
+    "mitm_matched": true,
+    "gate_wait_ms": 90,
+    "response": {
+      "text_len": 18,
+      "thinking_len": 0,
+      "text_preview": "Ahoy there, matey!",
+      "finish_reason": "stop",
+      "grounding": false
+    }
+  }
+]
+```
+
+## Example: response.json
+
+```json
+{
+  "usage": {
+    "input_tokens": 284,
+    "output_tokens": 13,
+    "thinking_tokens": 37,
+    "cache_read": 0
+  }
+}
+```
+
+## Outcomes
+
+| Outcome          | When                              |
+| ---------------- | --------------------------------- |
+| `completed`      | Normal response received          |
+| `tool_call`      | Model returned function calls     |
+| `upstream_error` | Google API returned an error      |
+| `timeout`        | No response within timeout window |
+| `mitm_timeout`   | MITM gate match timed out         |
+
+## Agent Usage
+
+Traces are designed for LLM consumption. To inspect the last trace:
+
+```bash
+# Find latest trace
+ls -t ~/.config/antigravity-proxy/traces/$(date +%Y-%m-%d)/ | head -1
+
+# Read the summary
+cat ~/.config/antigravity-proxy/traces/$(date +%Y-%m-%d)/$(ls -t ~/.config/antigravity-proxy/traces/$(date +%Y-%m-%d)/ | head -1)/summary.md
+
+# Grep for failures
+grep 'outcome=.*error\|outcome=.*timeout' ~/.config/antigravity-proxy/traces/$(date +%Y-%m-%d)/*/meta.txt
+```