From 3305bdfa068c0a16ed17806672395aa6643ea6a1 Mon Sep 17 00:00:00 2001
From: Lakshman Patel <Lakshmanp230@gmail.com>
Date: Fri, 4 Sep 2026 09:42:43 +0530
Subject: [PATCH 1/2] docs: add three-repo architecture diagram and status

---
 docs/design/three-repo-architecture.md | 62 ++++++++++++++++++++++++++
 1 file changed, 62 insertions(+)
 create mode 100644 docs/design/three-repo-architecture.md

diff --git a/docs/design/three-repo-architecture.md b/docs/design/three-repo-architecture.md
new file mode 100644
index 00000000..5b859004
--- /dev/null
+++ b/docs/design/three-repo-architecture.md
@@ -0,0 +1,62 @@
+# Three-repo architecture: CLI · Router · Platform
+
+Status: current state verified against code (2026-09-04); target state is a
+proposal. See also `gateway-architecture.md` (human-readable version),
+`ECOSYSTEM-WIRING.md` (pre-migration wiring, partially stale).
+
+## Current state (verified)
+
+```mermaid
+flowchart LR
+    subgraph CLI["graycode-cli"]
+        TUI["chat · exec · review\nagent loop · sessions"]
+        ENG["eyrie engine\n(compiled in)"]
+    end
+
+    subgraph ROUTER["graycode-router"]
+        LIB["engine library\n(router, adapters)"]
+        SRV["HTTP server (skeleton)\ninternal/api + openapi.yaml"]
+    end
+
+    subgraph PLAT["graycode-platform"]
+        WEB["web / BFF"]
+        AUTH["login · billing"]
+    end
+
+    TUI --> ENG
+    ENG -. "go.mod (module only)" .-> LIB
+    TUI -. "opt-in HTTPS\n(device login, usage, sync)" .-> WEB
+```
+
+Wires, with evidence:
+
+| From → To | Mechanism | Evidence |
+|---|---|---|
+| CLI → Router | Go module dep, in-process construction | `go.mod` requires `github.com/GrayCodeAI/eyrie`; `internal/provider/gateway/gateway.go` is the sole importer |
+| CLI → Platform | Opt-in HTTPS (login, usage, graph sync) | `internal/platform/cloud/client.go`; `Enabled()` requires endpoint + token; no default URL |
+| Router → CLI | none | router `go.mod`/`go.sum` contain zero graycode-cli refs |
+| Router ↔ Platform | none | no imports, package deps, or API calls either direction |
+
+## Target state (proposal)
+
+```mermaid
+flowchart LR
+    CLI2["graycode-cli\n(default: in-process)"] -. "opt-in --model-gateway" .-> GW
+    WEB2["platform web/BFF"] -->|per-user keys| GW
+    subgraph GW["graycode-router: common service"]
+        API["OpenAI-compatible API\n/v1/chat/completions + SSE"]
+        POL["routing · retry · guardrails\nspend tracking"]
+    end
+    GW --> PROV[(providers)]
+    CLI2 -->|direct| PROV
+```
+
+Rules: CLI always works alone; streams pass through byte-transparent;
+auth fails fast with a login hint; CLI pins a gateway API version.
+
+## Open items
+
+- Gateway endpoints don't exist yet (`server.go` is a skeleton).
+- Plugin registry index has no live home (both old and new URLs 404).
+- `Y0_MARKETPLACE` default disagrees between code (on) and old docs (off).
+- Remaining architecture prose still describes the pre-migration ecosystem.

From 16891ace0bbf8424d01b666597f2c8f755df1ee2 Mon Sep 17 00:00:00 2001
From: Lakshman Patel <Lakshmanp230@gmail.com>
Date: Fri, 4 Sep 2026 13:16:13 +0530
Subject: [PATCH 2/2] docs: rename eyrie to graycode-router in three-repo
 architecture

---
 docs/design/three-repo-architecture.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/design/three-repo-architecture.md b/docs/design/three-repo-architecture.md
index 5b859004..48272776 100644
--- a/docs/design/three-repo-architecture.md
+++ b/docs/design/three-repo-architecture.md
@@ -10,7 +10,7 @@ proposal. See also `gateway-architecture.md` (human-readable version),
 flowchart LR
     subgraph CLI["graycode-cli"]
         TUI["chat · exec · review\nagent loop · sessions"]
-        ENG["eyrie engine\n(compiled in)"]
+        ENG["graycode-router engine\n(compiled in)"]
     end
 
     subgraph ROUTER["graycode-router"]
@@ -32,7 +32,7 @@ Wires, with evidence:
 
 | From → To | Mechanism | Evidence |
 |---|---|---|
-| CLI → Router | Go module dep, in-process construction | `go.mod` requires `github.com/GrayCodeAI/eyrie`; `internal/provider/gateway/gateway.go` is the sole importer |
+| CLI → Router | Go module dep, in-process construction | `go.mod` requires `github.com/GrayCodeAI/graycode-router`; `internal/provider/gateway/gateway.go` is the sole importer |
 | CLI → Platform | Opt-in HTTPS (login, usage, graph sync) | `internal/platform/cloud/client.go`; `Enabled()` requires endpoint + token; no default URL |
 | Router → CLI | none | router `go.mod`/`go.sum` contain zero graycode-cli refs |
 | Router ↔ Platform | none | no imports, package deps, or API calls either direction |