From 0215a7563d5c3ac37f8c8a61f2cc6120af14305f Mon Sep 17 00:00:00 2001
From: CREDO23 <bakerathierry@gmail.com>
Date: Fri, 24 Jul 2026 19:16:21 +0200
Subject: [PATCH] plans: add git-native KB flow diagrams

---
 plans/git-native-kb/00b-diagrams.md | 102 ++++++++++++++++++++++++++++
 1 file changed, 102 insertions(+)
 create mode 100644 plans/git-native-kb/00b-diagrams.md

diff --git a/plans/git-native-kb/00b-diagrams.md b/plans/git-native-kb/00b-diagrams.md
new file mode 100644
index 000000000..aac0e4b4e
--- /dev/null
+++ b/plans/git-native-kb/00b-diagrams.md
@@ -0,0 +1,102 @@
+# Git-native KB — flow diagrams (end-to-end)
+
+> Visual companion to [`00-umbrella-plan.md`](00-umbrella-plan.md).
+> Phase refs: `01` storage core · `02` working-tree backend · `03` commit write path · `04` derived index · `05` migration · `06` Zero projection.
+
+## 1. The shape — one source of truth, one derived index
+
+```mermaid
+flowchart LR
+  subgraph TRUTH["SOURCE OF TRUTH"]
+    GIT["Git repo per workspace\n(commit per turn/save)"]
+  end
+  subgraph DERIVED["DERIVED (rebuildable cache)"]
+    PG[("Postgres: chunks + embeddings")]
+  end
+  GIT -->|"one-way derivation (04)"| PG
+  PG -. "reindex(workspace) rebuilds from git (04)" .-> GIT
+  classDef t fill:#1f3a2e,stroke:#4f9d76,color:#e6f7ee;
+  classDef d fill:#22314f,stroke:#5b7fbf,color:#e6edf7;
+  class GIT t;
+  class PG d;
+```
+
+There is **no arrow from Postgres back into Git**. Postgres is disposable.
+
+## 2. Write path — everything indexed becomes a commit
+
+```mermaid
+flowchart TD
+  AG["Agent edits (turn)"] --> WT["Working tree (staged)"]
+  ED["Editor save"] --> WT
+  UP["Upload → extracted markdown"] --> WT
+  NOT["Indexable connector sync (Notion/Drive)"] --> WT
+  WT -->|"end of turn / save (03)"| C["git commit (per-workspace lock, 01)"]
+  C --> IDX["Indexer: diff tree → changed blobs (04)"]
+  IDX --> PG[("chunks + embeddings\n(embed keyed by blob SHA)")]
+  C --> ZP["Zero projection: upsert documents/folders rows (06)"]
+```
+
+## 3. Read path — file ops vs. search hit different stores
+
+```mermaid
+flowchart LR
+  A["Agent"] -->|"ls/read/write/edit/mv/rm"| B["Git working-tree backend (02)"]
+  B --> GIT["Git (truth)"]
+  A -->|"semantic search"| S["hybrid_search (unchanged)"]
+  S --> PG[("Postgres chunks + embeddings")]
+```
+
+## 4. Live connectors — never stored (out of scope)
+
+```mermaid
+flowchart LR
+  Q["Chat query"] --> LC["Slack / Gmail (live)"]
+  LC -->|"fetched at chat time"| ANS["used in the answer"]
+  LC -.->|"never"| GIT["Git"]
+  LC -.->|"never"| PG[("Postgres chunks")]
+```
+
+## 5. History / undo — git replaces the three hand-rolled systems
+
+```mermaid
+flowchart TD
+  subgraph OLD["BEFORE (deleted)"]
+    V1["DocumentVersion"]
+    V2["DocumentRevision / FolderRevision + revert_service"]
+    V3["AgentActionLog (audit)"]
+  end
+  subgraph NEW["AFTER"]
+    L["git log / diff (history)"]
+    R["git revert (undo)"]
+    BL["git blame (attribution)"]
+  end
+  OLD -->|"replaced by (04)"| NEW
+```
+
+## 6. Migration (05) — Postgres KB → seed git repo
+
+```mermaid
+sequenceDiagram
+  autonumber
+  participant M as Migrator (per workspace, flagged)
+  participant PG as Postgres (existing docs/folders)
+  participant GIT as New git repo
+  participant IDX as reindex(workspace)
+  M->>PG: read documents + folders (preserve unique_identifier_hash)
+  M->>GIT: write files + one seed commit
+  M->>IDX: rebuild chunks/embeddings from git HEAD
+  IDX-->>M: chunk set
+  M->>M: verify search parity vs pre-migration, then flip flag
+  Note over M,GIT: Postgres content kept until verified (rollback window).
+```
+
+## 7. Reindex (04) — the safety net (Fossil `rebuild`)
+
+```mermaid
+flowchart LR
+  GIT["Git HEAD (truth)"] --> RB["reindex(workspace)"]
+  RB --> WIPE["wipe chunks + embeddings"]
+  WIPE --> REBUILD["re-chunk + re-embed all files\n(reuse cache by blob SHA)"]
+  REBUILD --> PG[("Postgres index rebuilt")]
+```