From 5deca296ff9801eeeb78bdfb55718b93e00ce29f Mon Sep 17 00:00:00 2001
From: Pedram Amini <pedram.amini@gmail.com>
Date: Sun, 30 Nov 2025 02:54:38 -0600
Subject: [PATCH] docs: Simplify README and move architecture diagram to
 ARCHITECTURE.md

- Streamline Key Concepts table with clearer terminology
- Move Mermaid architecture diagram to ARCHITECTURE.md
- Rename "Project" to "Agent" in diagram labels for consistency
- Keep README focused on user-facing information

Claude ID: 900964ee-78bd-47d3-af6a-f8ef6112e80c
Maestro ID: 5a166b38-b7e9-47f0-a8ff-0113c65f2682
---
 ARCHITECTURE.md | 47 ++++++++++++++++++++++++++++++++++++++++
 README.md       | 57 +++++--------------------------------------------
 2 files changed, 52 insertions(+), 52 deletions(-)

diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 7a8a1bcd..48ffebd7 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -18,6 +18,53 @@ Deep technical documentation for Maestro's architecture and design patterns. For
 
 ---
 
+## Architecture
+
+Maestro organizes work into **Projects** (workspaces), each with a **CLI Terminal** and multiple **Agent Tabs**. Each tab can be connected to an **Agent Session** - either newly created or resumed from the session pool.
+
+```mermaid
+graph LR
+    subgraph Maestro["Maestro App"]
+        subgraph ProjectA["Agent A (workspace)"]
+            TermA[CLI Terminal]
+            subgraph TabsA["Agent Tabs"]
+                Tab1A[Tab 1]
+                Tab2A[Tab 2]
+            end
+        end
+        subgraph ProjectB["Agent B (workspace)"]
+            TermB[CLI Terminal]
+            subgraph TabsB["Agent Tabs"]
+                Tab1B[Tab 1]
+                Tab2B[Tab 2]
+            end
+        end
+    end
+
+    subgraph SessionPool["Agent Session Pool"]
+        direction TB
+        S1["Session α"]
+        S2["Session β"]
+        S3["Session γ"]
+        S4["Session δ"]
+        S5["..."]
+    end
+
+    Tab1A -.->|"resume"| S1
+    Tab2A -.->|"resume"| S2
+    Tab1B -.->|"resume"| S3
+    Tab2B -.->|"new"| S4
+
+    style Maestro fill:#9b8cd6,stroke:#6b5b95
+    style ProjectA fill:#87ceeb,stroke:#4682b4
+    style ProjectB fill:#87ceeb,stroke:#4682b4
+    style TermA fill:#90ee90,stroke:#228b22
+    style TermB fill:#90ee90,stroke:#228b22
+    style TabsA fill:#ffe4a0,stroke:#daa520
+    style TabsB fill:#ffe4a0,stroke:#daa520
+    style SessionPool fill:#ffb6c1,stroke:#dc143c
+```
+
 ## Dual-Process Architecture
 
 Maestro uses Electron's main/renderer split with strict context isolation.
diff --git a/README.md b/README.md
index 2cc3f351..204af5e7 100644
--- a/README.md
+++ b/README.md
@@ -41,62 +41,15 @@ Download the latest release for your platform from the [Releases](https://github
 
 > **Note**: Maestro currently supports Claude Code only. Support for other agentic coding tools may be added in future releases based on community demand.
 
-## Architecture
-
-Maestro organizes work into **Projects** (workspaces), each with a **CLI Terminal** and multiple **Agent Tabs**. Each tab can be connected to an **Agent Session** - either newly created or resumed from the session pool.
-
-```mermaid
-graph LR
-    subgraph Maestro["Maestro App"]
-        subgraph ProjectA["Project A (workspace)"]
-            TermA[CLI Terminal]
-            subgraph TabsA["Agent Tabs"]
-                Tab1A[Tab 1]
-                Tab2A[Tab 2]
-            end
-        end
-        subgraph ProjectB["Project B (workspace)"]
-            TermB[CLI Terminal]
-            subgraph TabsB["Agent Tabs"]
-                Tab1B[Tab 1]
-                Tab2B[Tab 2]
-            end
-        end
-    end
-
-    subgraph SessionPool["Agent Session Pool"]
-        direction TB
-        S1["Session α"]
-        S2["Session β"]
-        S3["Session γ"]
-        S4["Session δ"]
-        S5["..."]
-    end
-
-    Tab1A -.->|"resume"| S1
-    Tab2A -.->|"resume"| S2
-    Tab1B -.->|"resume"| S3
-    Tab2B -.->|"new"| S4
-
-    style Maestro fill:#9b8cd6,stroke:#6b5b95
-    style ProjectA fill:#87ceeb,stroke:#4682b4
-    style ProjectB fill:#87ceeb,stroke:#4682b4
-    style TermA fill:#90ee90,stroke:#228b22
-    style TermB fill:#90ee90,stroke:#228b22
-    style TabsA fill:#ffe4a0,stroke:#daa520
-    style TabsB fill:#ffe4a0,stroke:#daa520
-    style SessionPool fill:#ffb6c1,stroke:#dc143c
-```
-
 ### Key Concepts
 
 | Concept | Description |
 |---------|-------------|
-| **Project** | A workspace tied to a directory. Contains one CLI terminal and multiple agent tabs. |
-| **CLI Terminal** | A PTY shell session for running commands directly. One per project. |
-| **Agent Tab** | A conversation context within a project. Each tab has its own input, images, and message history. |
-| **Agent Session** | A persistent conversation with an AI coding agent. Can be resumed across tabs or app restarts. |
-| **Session Pool** | All agent sessions for a project, including those created by AutoRun, manually by user, or imported. Sessions can be starred, named, and mapped to tabs. |
+| **Agents** | An agent has a workspace tied to a directory. Contains one CLI terminal and multiple agent tabs. |
+| **CLI Terminal** | A PTY shell session for running commands directly. One per agent. |
+| **Agent Tabs** | A conversation context with an agent. Each tab has its own input, images, and message history. |
+| **Agent Sessions** | The complete list of conversations with this specific agent. |
+| **History** | Actions made by the user or autonomously. |
 
 ## UI Overview