diff --git a/Neon Vision Editor.xcodeproj/project.pbxproj b/Neon Vision Editor.xcodeproj/project.pbxproj
index 42c90ac..5080b31 100644
--- a/Neon Vision Editor.xcodeproj/project.pbxproj	
+++ b/Neon Vision Editor.xcodeproj/project.pbxproj	
@@ -361,7 +361,7 @@
 				CODE_SIGNING_ALLOWED = YES;
 				CODE_SIGN_IDENTITY = "Apple Development";
 				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 469;
+				CURRENT_PROJECT_VERSION = 470;
 				DEAD_CODE_STRIPPING = YES;
 				DEVELOPMENT_TEAM = CS727NF72U;
 				ENABLE_APP_SANDBOX = YES;
@@ -444,7 +444,7 @@
 				CODE_SIGNING_ALLOWED = YES;
 				CODE_SIGN_IDENTITY = "Apple Development";
 				CODE_SIGN_STYLE = Automatic;
-				CURRENT_PROJECT_VERSION = 469;
+				CURRENT_PROJECT_VERSION = 470;
 				DEAD_CODE_STRIPPING = YES;
 				DEVELOPMENT_TEAM = CS727NF72U;
 				ENABLE_APP_SANDBOX = YES;
diff --git a/README.md b/README.md
index e748211..23c6cbe 100644
--- a/README.md
+++ b/README.md
@@ -263,15 +263,55 @@ Feature checklist (explicit):
 
 ```mermaid
 flowchart LR
-  UI["SwiftUI/AppKit UI"] --> VM["EditorViewModel"]
-  VM --> CMD["Tab Commands / Flux-style mutations"]
-  VM --> IO["File I/O + Load/Sanitize Pipeline"]
-  VM --> HL["Syntax Highlight + Editor Runtime Limits"]
-  VM --> UPD["Update Manager (GitHub Releases)"]
-  IO --> STORE["Tabs + Session State"]
+  subgraph Shell["Platform Shells"]
+    Mac["macOS (SwiftUI + AppKit bridges)"]
+    IOS["iOS/iPadOS (SwiftUI + UIKit bridges)"]
+  end
+
+  subgraph App["Application Layer"]
+    VM["EditorViewModel (@MainActor state owner)"]
+    CMD["Command reducers (Flux-style mutations)"]
+    ACT["User actions (toolbar/menu/shortcuts)"]
+  end
+
+  subgraph Core["Core Services"]
+    IO["File I/O + load/sanitize pipeline"]
+    HL["Syntax highlighting + runtime limits"]
+    FIND["Find/replace + selection engine"]
+    PREV["Markdown preview renderer"]
+    SAFE["Unsupported-file safety guards"]
+  end
+
+  subgraph Infra["Infrastructure"]
+    STORE["Tabs + session restore store"]
+    PREFS["Settings + persistence"]
+    SEC["SecureTokenStore (Keychain)"]
+    UPD["Release update manager"]
+  end
+
+  Mac --> ACT
+  IOS --> ACT
+  ACT --> VM
+  VM --> CMD
   CMD --> STORE
+  VM --> IO
+  VM --> HL
+  VM --> FIND
+  VM --> PREV
+  VM --> SAFE
+  VM --> PREFS
+  VM --> UPD
+  PREFS --> STORE
+  IO --> STORE
+  VM --> SEC
 ```
 
+- `EditorViewModel` is the single UI-facing orchestration point per window/scene.
+- Commands mutate editor state predictably; session/tabs persist through store services.
+- File access and parsing stay off the main thread; UI state changes stay on the main thread.
+- Platform shells stay thin and route interactions into shared app/core services.
+- Security-sensitive credentials remain in Keychain (`SecureTokenStore`), not plain prefs.
+
 ## Platform Matrix
 
 Availability legend: `Full` = complete support, `Partial` = available with platform constraints, `No` = currently unavailable.