@adaptic/maestro 1.0.0

package/docs/architecture/system-architecture.md

@@ -0,0 +1,1273 @@
+# System Architecture — Maestro (Autonomous AI Agent Operating System)
+
+> Classification: INTERNAL — System Architecture Specification
+> Version: 1.0
+> Last updated: 2026-04-02
+> Maintainer: Sophie Nguyen (Maestro)
+> Deployment: Dedicated Mac mini — perpetual operation
+
+---
+
+## Table of Contents
+
+1. [System Overview](#1-system-overview)
+2. [Architecture Layers](#2-architecture-layers)
+3. [Agent Architecture](#3-agent-architecture)
+4. [Desktop Control Architecture](#4-desktop-control-architecture)
+5. [Memory Architecture](#5-memory-architecture)
+6. [Communication Architecture](#6-communication-architecture)
+7. [Scheduling Architecture](#7-scheduling-architecture)
+8. [Integration Points](#8-integration-points)
+9. [Security Architecture](#9-security-architecture)
+10. [Resilience and Recovery](#10-resilience-and-recovery)
+11. [Directory Structure Reference](#11-directory-structure-reference)
+
+---
+
+## 1. System Overview
+
+### 1.1 Purpose
+
+CEO Brain is the autonomous executive operating system for Adaptic.ai. It runs perpetually on a dedicated Mac mini under the operating persona **Sophie Nguyen** (Chief of Staff), providing continuous strategic operations, communications management, execution tracking, and desktop automation for the CEO.
+
+The system is not an assistant that waits for instructions. It is a persistent, self-scheduling executive office that observes the operational environment, maintains strategic memory, coordinates specialist agent teams, executes approved actions, and escalates decisions requiring human authority.
+
+### 1.2 Deployment Model
+
+| Attribute           | Value                                                          |
+| ------------------- | -------------------------------------------------------------- |
+| Hardware            | Mac mini (Apple Silicon, 24GB+ RAM, 1TB+ SSD)                  |
+| Operating System    | macOS 14+ (Sonoma or later)                                    |
+| Runtime             | Claude Code CLI with MCP protocol extensions                   |
+| Process Supervision | launchd (macOS native) + custom watchdog                       |
+| Network             | Persistent internet — Slack, Gmail, APIs, remote bridge        |
+| Physical Location   | Secure, climate-controlled, UPS-backed                         |
+| Access Model        | Remote management via SSH + remote bridge; no physical console |
+| Uptime Target       | 99.5%+ (planned maintenance windows at 03:00-04:00 UTC Sunday) |
+
+### 1.3 Design Principles
+
+1. **Perpetual operation** — The system never stops. Scheduled tasks fire on cadence. Event-driven triggers respond in real time. If a process dies, it restarts.
+2. **Observe first, act with governance** — Reading, monitoring, and analysing are always permitted. Acting on the external world requires appropriate authorisation level.
+3. **Human-in-the-loop for high-risk actions** — The CEO retains authority over investor communications, regulatory submissions, strategic commitments, and financial decisions.
+4. **Audit everything** — Every observation, decision, delegation, and action is logged with timestamps, context, and provenance.
+5. **Agent decomposition** — Sophie orchestrates; specialist agents execute. Work is decomposed, routed, monitored, and synthesised.
+6. **Fail safe, recover fast** — State is persisted to disk. Processes are supervised. Recovery procedures are automated.
+
+### 1.4 Conceptual Architecture
+
+```
+                           ┌─────────────────────────────────┐
+                           │       GOVERNANCE LAYER           │
+                           │  Approval Gates / Audit Trail    │
+                           │  Kill Switches / Escalation      │
+                           └──────────┬──────────────────┬────┘
+                                      │                  │
+               ┌──────────────────────┴──────────────────┴───────────────────┐
+               │                     REASONING LAYER                         │
+               │          Strategic Memory / Knowledge Synthesis             │
+               │          Decision Support / Context Assembly                │
+               └──────┬────────────────┬───────────────────┬─────────────────┘
+                      │                │                   │
+       ┌──────────────┴───┐   ┌───────┴────────┐   ┌──────┴──────────────┐
+       │  PERCEPTION LAYER│   │ ORCHESTRATION  │   │   ACTUATION LAYER   │
+       │                  │   │    LAYER       │   │                     │
+       │ Slack, Gmail,    │   │ Agent Teams,   │   │ Desktop Control,    │
+       │ WhatsApp, Browser│   │ Task Routing,  │   │ App Automation,     │
+       │ Repos, Market    │   │ Decomposition  │   │ Communications,     │
+       │ Data, Filesystem │   │                │   │ File Operations     │
+       └──────────────────┘   └────────────────┘   └─────────────────────┘
+```
+
+---
+
+## 2. Architecture Layers
+
+### 2.1 Perception Layer
+
+The Perception Layer is responsible for observing the operational environment. All perception operations are read-only and require no approval gates.
+
+#### 2.1.1 Communication Channels
+
+| Source   | Method                                  | Cadence                       | Data Captured                                  |
+| -------- | --------------------------------------- | ----------------------------- | ---------------------------------------------- |
+| Slack    | MCP server + desktop control fallback   | Continuous + scheduled sweeps | Messages, threads, reactions, channel activity |
+| Gmail    | MCP server (Google API) + IMAP fallback | Scheduled sweeps (15 min)     | Inbox, sent, drafts, labels, attachments       |
+| WhatsApp | Desktop app control via Accessibility   | Scheduled sweeps (30 min)     | Messages, group activity, read receipts        |
+| Calendar | MCP server (Google Calendar API)        | Scheduled sync (5 min)        | Events, invitations, conflicts, availability   |
+
+#### 2.1.2 Information Sources
+
+| Source            | Method                              | Cadence                    | Data Captured                             |
+| ----------------- | ----------------------------------- | -------------------------- | ----------------------------------------- |
+| GitHub Repos      | CLI (`gh`, `git`) + MCP server      | Event-driven + hourly poll | PRs, issues, commits, CI status, reviews  |
+| Market Data       | REST APIs (Polygon.io, Alpaca)      | Morning sweep + continuous | Prices, volumes, news, earnings, signals  |
+| Competitive Intel | Web scraping + RSS + news APIs      | Daily sweep                | Competitor announcements, filings, hiring |
+| Filesystem        | Direct access + `fswatch`           | Event-driven               | File changes in watched directories       |
+| Browser / Web     | Desktop-controlled browser sessions | On-demand                  | Dashboard state, portal data, web content |
+
+#### 2.1.3 Perception Pipeline
+
+```
+Source → Ingest → Normalise → Classify → Route → Store
+                                │
+                                ├─ Urgent → Immediate alert to Reasoning Layer
+                                ├─ Standard → Queue for next scheduled processing
+                                └─ Background → Store in knowledge base for synthesis
+```
+
+Ingested data is written to `/Users/sophie/sophie-ai/ingest/` with structured metadata (source, timestamp, classification, confidence) before being routed to the appropriate processing pipeline.
+
+### 2.2 Reasoning Layer
+
+The Reasoning Layer is where the system thinks. It assembles context from memory and perception, applies strategic knowledge, and produces decisions, recommendations, and action plans.
+
+#### 2.2.1 Context Assembly
+
+For every reasoning task, the system assembles a context window comprising:
+
+1. **Task specification** — What needs to be decided or produced
+2. **Relevant memory** — Retrieved from working, episodic, semantic, and decision memory stores
+3. **Fresh perception data** — Recent observations relevant to the task
+4. **Policy constraints** — Governance rules, regulatory requirements, authority limits
+5. **Entity context** — Key people, organisations, and relationships involved
+6. **Historical precedent** — Past decisions on similar matters and their outcomes
+
+#### 2.2.2 Reasoning Modes
+
+| Mode                  | Trigger                                       | Output                                          |
+| --------------------- | --------------------------------------------- | ----------------------------------------------- |
+| Reactive Analysis     | Inbound message or event requiring response   | Draft communication, action recommendation      |
+| Scheduled Synthesis   | Cron-triggered workflow (briefs, reviews)     | Structured deliverable (memo, brief, report)    |
+| Strategic Planning    | Explicit request or quarterly cadence         | Scenario analysis, strategic recommendation     |
+| Decision Support      | Decision point surfaced by perception layer   | Options matrix, risk assessment, recommendation |
+| Anomaly Investigation | Alert or deviation detected by monitoring     | Root cause analysis, escalation recommendation  |
+| Knowledge Integration | New information conflicts with existing model | Updated synthesis, contradiction flag           |
+
+#### 2.2.3 Decision Support Framework
+
+Every substantive recommendation follows the structure:
+
+```
+CONTEXT:     What prompted this decision point
+OPTIONS:     Enumerated choices with trade-offs
+EVIDENCE:    Data supporting each option (with source citations)
+RISK:        Downside scenarios for each option
+RECOMMENDATION: Sophie's recommended course of action
+AUTHORITY:   Who decides (auto-execute, CEO approval, Board)
+URGENCY:     Time sensitivity classification
+```
+
+### 2.3 Orchestration Layer
+
+The Orchestration Layer coordinates work across the agent hierarchy. Sophie (Executive Cortex) decomposes strategic objectives into executable tasks and routes them to the appropriate Domain VP or Specialist Worker agent.
+
+#### 2.3.1 Task Decomposition
+
+```
+Strategic Objective
+  └─ Workstream (assigned to Domain VP Agent)
+       └─ Task (assigned to Specialist Worker Agent)
+            └─ Sub-task (atomic, executable unit)
+```
+
+#### 2.3.2 Work Routing
+
+Tasks are routed based on:
+
+- **Domain alignment** — Match task domain to agent specialisation
+- **Current load** — Distribute work across available agents
+- **Context proximity** — Prefer agents that already hold relevant context
+- **Authority level** — Ensure the agent has the required access permissions
+- **Dependency graph** — Sequence tasks that have order dependencies
+
+#### 2.3.3 Orchestration Protocol
+
+1. **Decompose** — Break the objective into discrete, assignable tasks with clear deliverables
+2. **Assign** — Route each task to the best-matched agent with full context handoff
+3. **Monitor** — Track execution status, check for blockers, verify progress
+4. **Synthesise** — Combine agent outputs into executive-ready deliverables
+5. **Escalate** — Surface blockers, failures, or decisions requiring human authority
+6. **Close** — Verify completion, archive results, update memory
+
+Task definitions, assignments, and status are tracked in `/Users/sophie/sophie-ai/teams/` with structured manifests.
+
+### 2.4 Actuation Layer
+
+The Actuation Layer is how the system acts on the world. All actuation is subject to governance controls defined in the Governance Layer.
+
+#### 2.4.1 Action Categories
+
+| Category                | Examples                                                  | Governance Level          |
+| ----------------------- | --------------------------------------------------------- | ------------------------- |
+| File Operations         | Write memos, update knowledge base, generate reports      | Auto-execute              |
+| Internal Communications | Slack messages to team, task assignments, status requests | Auto-execute (logged)     |
+| Desktop Automation      | Open apps, navigate UI, extract data from screens         | Auto-execute (logged)     |
+| Draft Communications    | Email drafts, investor memo drafts, board materials       | Draft-and-hold            |
+| External Communications | Send emails, post in external channels                    | Approval required         |
+| Code Operations         | Create PRs, commit changes, run scripts                   | Context-dependent         |
+| Financial Actions       | Trade execution, fund operations                          | Prohibited (out of scope) |
+
+#### 2.4.2 Output Generation
+
+All generated outputs are written to `/Users/sophie/sophie-ai/outputs/` in the appropriate subdirectory:
+
+```
+outputs/
+├── briefs/           # CEO morning/evening briefs
+├── memos/            # Strategic and operational memos
+├── communications/   # Draft communications awaiting review
+├── board/            # Board-related materials
+└── followups/        # Follow-up tracking documents
+```
+
+### 2.5 Governance Layer
+
+The Governance Layer enforces control over all system actions. It is the outermost layer and cannot be bypassed by any inner layer.
+
+#### 2.5.1 Approval Gates
+
+| Gate                   | Trigger                                         | Approver     | Method                         |
+| ---------------------- | ----------------------------------------------- | ------------ | ------------------------------ |
+| External Communication | Any message to parties outside the organisation | CEO (Mehran) | Slack approval prompt / review |
+| Investor Communication | Any message to investors, LPs, or board members | CEO (Mehran) | Explicit per-message approval  |
+| Regulatory Submission  | Any filing or correspondence with regulators    | CEO + SEO    | Dual approval required         |
+| Strategic Commitment   | Commitments that bind the company               | CEO (Mehran) | Explicit approval              |
+| Code Deployment        | Merges to main/production branches              | CTO / CEO    | PR review process              |
+| Budget / Expenditure   | Any financial commitment                        | CEO (Mehran) | Explicit approval              |
+
+#### 2.5.2 Audit Trail
+
+Every action is recorded in `/Users/sophie/sophie-ai/logs/` with:
+
+```json
+{
+  "timestamp": "2026-04-02T06:30:00Z",
+  "action_type": "communication.draft",
+  "agent": "sophie-chief-of-staff",
+  "target": "investor-update-q1-2026",
+  "governance_level": "draft-and-hold",
+  "approval_status": "pending",
+  "context_hash": "sha256:...",
+  "input_sources": [
+    "knowledge/syntheses/adaptic-overview.md",
+    "ingest/market-data/2026-04-01.json"
+  ],
+  "output_path": "outputs/communications/investor-update-q1-2026-draft.md",
+  "session_id": "session-2026-04-02-0630"
+}
+```
+
+#### 2.5.3 Escalation Protocol
+
+```
+Level 0: Auto-execute with logging (read operations, internal file writes)
+Level 1: Auto-execute with notification (internal Slack messages, routine follow-ups)
+Level 2: Draft-and-hold for review (external communications, substantive content)
+Level 3: Explicit approval required (investor/regulator communications, commitments)
+Level 4: Dual approval required (regulatory submissions, material agreements)
+Level 5: PROHIBITED (actions outside system authority — trading, fund operations)
+```
+
+#### 2.5.4 Kill Switches
+
+| Switch             | Activation                                   | Effect                                         |
+| ------------------ | -------------------------------------------- | ---------------------------------------------- |
+| Full Stop          | `kill-switch.lock` file in project root      | All actuation ceases; perception continues     |
+| Communication Hold | `comms-hold.lock` file in project root       | No outbound communications; all else continues |
+| Agent Suspend      | `agents/{name}/suspended.lock`               | Specific agent stops receiving work            |
+| Emergency Shutdown | `launchctl unload` of all CEO Brain services | Complete system halt                           |
+| Remote Kill        | Remote bridge command from CEO's device      | Full Stop equivalent via remote signal         |
+
+Kill switch activation is itself logged and triggers an immediate notification via all available channels.
+
+---
+
+## 3. Agent Architecture
+
+### 3.1 Three-Tier Model
+
+The agent architecture follows a three-tier hierarchy inspired by the AI-Born thesis — small human teams directing autonomous agent swarms at institutional scale.
+
+```
+                    ┌─────────────────────────────┐
+                    │     SOPHIE NGUYEN            │
+                    │     Executive Cortex         │
+                    │     Chief of Staff           │
+                    └──────┬──────────────┬────────┘
+                           │              │
+            ┌──────────────┴──┐     ┌─────┴──────────────┐
+            │                 │     │                     │    ... (8-10 Domain VPs)
+    ┌───────┴───────┐ ┌──────┴──────┴─┐ ┌───────────────┐
+    │ VP Strategic  │ │ VP Capital &  │ │ VP Platform & │
+    │ Planning      │ │ Rollup Ops    │ │ Engineering   │
+    └───┬───────────┘ └───┬───────────┘ └───┬───────────┘
+        │                 │                 │
+    ┌───┴───┐         ┌───┴───┐         ┌───┴───┐
+    │Workers│         │Workers│         │Workers│       ... (20+ Specialist Workers)
+    └───────┘         └───────┘         └───────┘
+```
+
+### 3.2 Tier 1: Executive Cortex — Sophie
+
+Sophie is the single top-level orchestrator. There is exactly one instance. She holds the master context, maintains strategic memory, and is the sole interface to the CEO.
+
+| Attribute      | Value                                                         |
+| -------------- | ------------------------------------------------------------- |
+| Agent ID       | `sophie-chief-of-staff`                                       |
+| Role           | Executive Cortex / Chief of Staff                             |
+| Instance Count | 1 (singleton)                                                 |
+| Context Window | Full strategic context — all memory layers accessible         |
+| Authority      | Orchestration over all agents; direct actuation for Level 0-1 |
+| Persistence    | Continuous — session state preserved across restarts          |
+| Location       | `/Users/sophie/sophie-ai/agents/sophie-chief-of-staff/`       |
+
+**Core responsibilities:**
+
+- Morning and evening CEO briefings
+- Communication triage and response coordination
+- Strategic initiative tracking and follow-through
+- Agent team orchestration and work routing
+- Decision log maintenance
+- Escalation management
+- Knowledge synthesis oversight
+
+### 3.3 Tier 2: Domain VP Agents
+
+Domain VPs are strategic-level agents responsible for an entire operational domain. They receive high-level objectives from Sophie and decompose them into tasks for Specialist Workers.
+
+| Agent                      | Domain                                                  | Key Outputs                                                |
+| -------------------------- | ------------------------------------------------------- | ---------------------------------------------------------- |
+| `strategic-planning`       | Long-term strategy, scenario analysis, thesis alignment | Strategic memos, scenario reports, milestone tracking      |
+| `capital-raising`          | LP relationships, fundraising, investor communications  | Investor materials, pipeline tracking, term sheet analysis |
+| `corporate-development`    | M&A, rollup execution, due diligence coordination       | Target briefs, DD checklists, deal structure analysis      |
+| `engineering-coordination` | Platform health, technical architecture, delivery       | Engineering reports, PR reviews, architecture decisions    |
+| `product-strategy`         | Product roadmap, feature prioritisation, UX direction   | Product briefs, feature specs, competitive comparison      |
+| `regulatory-dfsa`          | DFSA application, compliance infrastructure, legal      | Gap analysis, regulatory responses, compliance reports     |
+| `fund-ops`                 | Fund structuring, NAV, investor reporting               | Fund reports, NAV calculations, investor statements        |
+| `communications`           | External comms, brand voice, media, content             | Communication drafts, press materials, content calendar    |
+| `hiring-org-design`        | Talent acquisition, org structure, team planning        | JDs, candidate assessments, org chart updates              |
+| `risk-register`            | Enterprise risk, operational risk, regulatory risk      | Risk assessments, mitigation plans, risk dashboard         |
+
+Each Domain VP agent is defined in `/Users/sophie/sophie-ai/agents/{agent-name}/` with:
+
+- Agent system prompt (role, responsibilities, constraints)
+- Context assembly rules (which memory and knowledge sources to load)
+- Output templates (standard deliverable formats)
+- Escalation rules (when to push back to Sophie)
+
+### 3.4 Tier 3: Specialist Worker Agents
+
+Specialist Workers execute discrete, well-scoped tasks. They receive fully specified task assignments from Domain VPs and return structured deliverables.
+
+| Agent                      | Specialisation                                         |
+| -------------------------- | ------------------------------------------------------ |
+| `ceo-briefing`             | Compile and format CEO morning/evening briefs          |
+| `competitive-intelligence` | Monitor competitors, produce intelligence reports      |
+| `market-research`          | Analyse market data, trends, and signals               |
+| `rollup-target-sourcing`   | Identify and qualify rollup acquisition targets        |
+| `board-prep`               | Prepare board meeting materials and packs              |
+| `legal-structuring`        | Analyse legal structures, draft term sheets            |
+| `partnerships`             | Track and advance strategic partnership discussions    |
+| `decision-log`             | Maintain the structured decision log with rationale    |
+| `founder-voice`            | Draft communications in the CEO's voice and style      |
+| `pmo-execution`            | Track project milestones, deadlines, and deliverables  |
+| `platform-architecture`    | Analyse and recommend technical architecture decisions |
+| `workflow-automation`      | Design and implement automated workflows               |
+
+#### Desktop Operator Specialists
+
+| Agent               | Specialisation                                                   |
+| ------------------- | ---------------------------------------------------------------- |
+| `desktop-operator`  | General macOS desktop automation and control                     |
+| `slack-operator`    | Slack-specific navigation, reading, composing, thread management |
+| `gmail-operator`    | Gmail inbox management, drafting, labelling, search              |
+| `whatsapp-operator` | WhatsApp message monitoring and reply preparation                |
+| `browser-operator`  | Web browsing, dashboard checking, form filling                   |
+| `calendar-ops`      | Calendar management, scheduling, conflict resolution             |
+
+### 3.5 Agent Lifecycle
+
+```
+DEFINE → INITIALISE → ASSIGN → EXECUTE → REPORT → IDLE / TERMINATE
+  │          │            │         │         │          │
+  │          │            │         │         │          └─ Return to pool or end session
+  │          │            │         │         └─ Deliver output, update status
+  │          │            │         └─ Execute task with access to specified tools/memory
+  │          │            └─ Receive task specification with context package
+  │          └─ Load agent prompt, configure tool access, attach memory
+  └─ Define agent in agents/{name}/ with system prompt and config
+```
+
+### 3.6 Agent Communication Protocol
+
+Agents communicate through structured messages, not free-form text:
+
+```yaml
+message:
+  from: sophie-chief-of-staff
+  to: corporate-development
+  type: task_assignment
+  priority: high
+  task:
+    id: task-2026-04-02-001
+    objective: "Prepare updated briefing document for Graham Capital acquisition target"
+    deliverable: "Target briefing document in outputs/memos/"
+    deadline: "2026-04-02T14:00:00Z"
+    context_sources:
+      - knowledge/entities/graham-capital.md
+      - knowledge/sources/rollup-pipeline.md
+    constraints:
+      - "Use only verified data (G0+ confidence)"
+      - "Include regulatory implications for DFSA"
+    escalation: "If key data missing, escalate to Sophie before deadline"
+```
+
+---
+
+## 4. Desktop Control Architecture
+
+### 4.1 Overview
+
+The system operates as a full desktop user on macOS. It can see the screen, control the mouse and keyboard, switch between applications, and interact with native UI elements. This is not screen scraping — it is full computer use capability.
+
+### 4.2 Control Stack
+
+```
+┌─────────────────────────────────────────────────┐
+│            Agent Decision Layer                  │
+│  "I need to check the #general channel in Slack" │
+├─────────────────────────────────────────────────┤
+│            Action Planning Layer                 │
+│  1. Activate Slack  2. Navigate to #general     │
+│  3. Scroll to unread  4. Capture content        │
+├─────────────────────────────────────────────────┤
+│         State Awareness Layer                    │
+│  Screenshot analysis, UI element detection,     │
+│  current app identification, window state       │
+├──────────────┬──────────────────────────────────┤
+│  AppleScript │  Accessibility API  │  CGEvent   │
+│  (app-level) │  (UI elements)      │  (input)   │
+├──────────────┴──────────────────────────────────┤
+│              macOS Desktop                       │
+└─────────────────────────────────────────────────┘
+```
+
+### 4.3 Control Mechanisms
+
+#### 4.3.1 AppleScript / JXA (JavaScript for Automation)
+
+Primary mechanism for application-level control. Provides structured access to app state without relying on visual interpretation.
+
+```applescript
+-- Example: Get unread Slack channel list
+tell application "Slack"
+    activate
+end tell
+
+-- Example: Compose a new Gmail message
+tell application "Google Chrome"
+    set URL of active tab of front window to "https://mail.google.com/mail/#compose"
+end tell
+```
+
+**Used for:** Application activation, window management, menu bar interaction, basic state queries.
+
+#### 4.3.2 macOS Accessibility API (AXUIElement)
+
+Programmatic access to UI element trees. Enables reading and interacting with specific UI controls without screenshot analysis.
+
+**Used for:** Reading text from UI elements, clicking buttons by role/label, navigating form fields, checking control states (enabled, selected, value).
+
+**Prerequisite:** System Preferences > Privacy & Security > Accessibility must grant access to the controlling process.
+
+#### 4.3.3 CGEvent / IOHIDEvent (Input Simulation)
+
+Low-level input simulation for cases where neither AppleScript nor Accessibility API provides the needed interaction.
+
+**Used for:** Keyboard input, mouse clicks at coordinates, scroll events, drag operations, keyboard shortcuts.
+
+#### 4.3.4 Screenshot Analysis (Computer Use)
+
+Claude's computer use capability analyses screenshots to understand the current visual state of the desktop.
+
+**Used for:** Identifying current application state, locating UI elements visually when Accessibility API access is unavailable, verifying that actions produced the expected result, handling non-standard UI components.
+
+### 4.4 Application Control Patterns
+
+#### 4.4.1 Standard Application Interaction Sequence
+
+```
+1. VERIFY   — Screenshot: What app is active? What state is it in?
+2. ACTIVATE — AppleScript: Bring target app to front
+3. CONFIRM  — Screenshot: Is the app visible and in expected state?
+4. NAVIGATE — Accessibility/Keyboard: Navigate to target UI location
+5. CONFIRM  — Screenshot: Am I at the correct location?
+6. ACT      — Input simulation: Perform the action (click, type, select)
+7. VERIFY   — Screenshot: Did the action succeed?
+8. EXTRACT  — Accessibility/Screenshot: Capture result data
+```
+
+#### 4.4.2 Slack Control
+
+```
+Capabilities:
+  - Monitor all channels for new messages
+  - Read message content and thread context
+  - Compose and send messages (governance-gated)
+  - React to messages
+  - Search message history
+  - Navigate between workspaces
+
+Method hierarchy:
+  1. MCP Slack server (preferred — structured API access)
+  2. Slack desktop app via Accessibility API
+  3. Slack web app via browser control (fallback)
+```
+
+#### 4.4.3 Gmail Control
+
+```
+Capabilities:
+  - Inbox triage (read, classify, label)
+  - Draft composition
+  - Attachment handling
+  - Search and filter
+  - Label/folder management
+
+Method hierarchy:
+  1. MCP Gmail server (preferred — Google API access)
+  2. Gmail web app via browser control (fallback)
+```
+
+#### 4.4.4 WhatsApp Control
+
+```
+Capabilities:
+  - Read incoming messages across chats/groups
+  - Compose replies (governance-gated)
+  - Monitor group activity
+  - Export conversation content
+
+Method:
+  - WhatsApp Desktop app via Accessibility API + input simulation
+  - No API access available — desktop control is primary method
+```
+
+### 4.5 Window Management
+
+```
+Strategies:
+  - Single-app focus: Maximise target app, perform operations, restore
+  - Split-screen: Side-by-side for reference tasks (e.g., draft email while viewing document)
+  - Background monitoring: Minimised apps checked via AppleScript state queries
+
+Window state is tracked to enable restoration after operations:
+  - Record app positions and sizes before rearranging
+  - Restore layout after task completion
+  - Maintain a "home state" layout for idle periods
+```
+
+### 4.6 Recovery Patterns
+
+Desktop control is inherently fragile. The system implements defensive patterns:
+
+| Failure Mode                         | Detection                        | Recovery                                             |
+| ------------------------------------ | -------------------------------- | ---------------------------------------------------- |
+| App not responding                   | Screenshot shows hang/beach ball | Force-quit via `kill`, relaunch, retry               |
+| Unexpected dialog/modal              | Screenshot shows unexpected UI   | Dismiss dialog (Escape/click), retry original action |
+| App crashed                          | Process not found                | Relaunch application, navigate to last known state   |
+| Screen lock activated                | Screenshot shows login screen    | Unlock via input simulation (credential in keychain) |
+| Wrong app in foreground              | Screenshot mismatch              | Activate correct app, retry                          |
+| UI element not found                 | Accessibility query returns null | Retry with delay, fallback to coordinate-based click |
+| Network-dependent app loading slowly | Screenshot shows spinner/loading | Wait with exponential backoff, timeout after 30s     |
+| macOS system dialog (update, etc.)   | Screenshot shows system UI       | Dismiss/defer, log occurrence                        |
+
+**Maximum retry depth:** 3 attempts per action. After 3 failures, escalate to error log and move to next task.
+
+Desktop control scripts and configurations reside in `/Users/sophie/sophie-ai/desktop-control/`.
+
+---
+
+## 5. Memory Architecture
+
+### 5.1 Overview
+
+The memory system provides persistent knowledge across sessions. It is structured into four tiers that mirror cognitive architecture: working memory, episodic memory, semantic memory, and decision memory.
+
+All memory is file-based, stored in `/Users/sophie/sophie-ai/knowledge/`, and version-controlled via git.
+
+### 5.2 Working Memory
+
+**Location:** In-session context window
+**Persistence:** Session-scoped (lost on session restart unless explicitly persisted)
+**Capacity:** Bounded by Claude context window (up to 1M tokens)
+
+Working memory contains:
+
+- Current task specification and progress
+- Assembled context for the active reasoning task
+- Intermediate results from in-progress operations
+- Active conversation threads with agents
+
+**Management:** Working memory is explicitly managed. At session boundaries, important working memory contents are flushed to episodic or semantic memory.
+
+### 5.3 Episodic Memory
+
+**Location:** `/Users/sophie/sophie-ai/knowledge/memory/`
+**Persistence:** Permanent (file-based)
+**Structure:** Chronological entries with structured metadata
+
+Episodic memory records events, conversations, and observations:
+
+```markdown
+## 2026-04-02 — Mehran flagged concern about Quantedge timeline
+
+- Context: Morning Slack message in #strategy
+- Content: Mehran noted that Quantedge CIO is considering retirement earlier than expected.
+  This compresses the engagement timeline from 12 months to potentially 6 months.
+- Implication: Due diligence work on Quantedge must be front-loaded.
+- Action taken: Escalated to corporate-development agent for pipeline timeline revision.
+- Source: Slack #strategy, message ID msg-20260402-0823
+```
+
+**Retrieval:** Episodic memory is searched by date range, entity mention, topic tag, and full-text search when assembling context for reasoning tasks.
+
+### 5.4 Semantic Memory
+
+**Location:** `/Users/sophie/sophie-ai/knowledge/`
+**Persistence:** Permanent (file-based, periodically refreshed)
+**Structure:** Structured knowledge documents organised by domain
+
+Semantic memory contains long-term strategic knowledge:
+
+```
+knowledge/
+├── entities/       # Entity profiles (people, companies, funds, regulators)
+├── sources/        # Ingested and synthesised source documents
+├── syntheses/      # Cross-source synthesis documents (e.g., adaptic-overview.md)
+├── decisions/      # Decision log entries
+└── memory/         # Episodic memory entries
+```
+
+#### 5.4.1 Entity Maps
+
+Entity profiles in `knowledge/entities/` maintain structured records:
+
+```yaml
+entity: Graham Capital Management
+type: acquisition_target
+status: pipeline_active
+aum: "$3.2B"
+strategy: "Systematic CTA"
+founder: "Name, age 71"
+engagement_stage: "G0 — Identified, not yet contacted"
+key_contacts: []
+regulatory_jurisdiction: "SEC"
+last_updated: "2026-04-01"
+confidence: "verified"
+source_documents:
+  - knowledge/sources/rollup-pipeline.md
+  - knowledge/sources/graham-capital-research.md
+```
+
+#### 5.4.2 Knowledge Freshness
+
+Every knowledge document carries metadata:
+
+- `last_updated` — When the document was last refreshed
+- `confidence` — Verified, probable, speculative, stale
+- `source_authority` — Primary source, secondary synthesis, third-party report
+- `refresh_cadence` — How often the document should be refreshed (daily, weekly, monthly)
+- `contradictions` — Known conflicts with other knowledge sources
+
+The system runs a weekly knowledge freshness audit that flags stale documents for refresh.
+
+### 5.5 Decision Memory
+
+**Location:** `/Users/sophie/sophie-ai/knowledge/decisions/`
+**Persistence:** Permanent (append-only)
+**Structure:** Structured decision records
+
+Every significant decision is recorded:
+
+```markdown
+## DECISION-2026-0042: Prioritise Graham Capital as Deal #1 candidate
+
+- **Date:** 2026-03-28
+- **Decider:** Mehran Granfar (CEO)
+- **Context:** Pipeline review revealed Graham Capital has strongest succession-trigger signal
+- **Options considered:**
+  1. Graham Capital — strongest trigger, manageable AUM, systematic strategy aligns
+  2. Cadian Capital — distressed AUM, but reputational risk from -64% decline
+  3. Quantedge — excellent performance, but higher AUM means higher capital requirement
+- **Decision:** Pursue Graham Capital as primary Deal #1 candidate
+- **Rationale:** Founder age (71) creates natural succession pressure. Systematic CTA strategy aligns with Adaptic OS. $3.2B AUM is within achievable capital raise range.
+- **Risks accepted:** Limited geographic overlap (US-based, we are DIFC). SEC regulatory complexity.
+- **Review date:** 2026-05-01
+- **Outcome:** [Pending — to be updated]
+```
+
+---
+
+## 6. Communication Architecture
+
+### 6.1 Voice Modes
+
+| Mode                    | Use Case                                                      | Governance Level |
+| ----------------------- | ------------------------------------------------------------- | ---------------- |
+| Sophie's Voice          | Internal team communications, operational coordination        | Level 0-1        |
+| Mehran's Voice (Draft)  | External communications drafted for CEO review                | Level 2          |
+| Mehran's Voice (Direct) | Pre-approved routine messages sent as the CEO                 | Level 1          |
+| Internal Notes          | Analysis, recommendations, risk flags — never sent externally | Level 0          |
+| Neutral / Institutional | Official company communications, regulatory correspondence    | Level 3-4        |
+
+### 6.2 Channel Routing
+
+| Recipient Type      | Primary Channel | Fallback Channel | Governance    |
+| ------------------- | --------------- | ---------------- | ------------- |
+| Internal team       | Slack           | Email            | Auto-execute  |
+| CEO (Mehran)        | Slack DM        | WhatsApp         | Auto-execute  |
+| Investors / LPs     | Email (draft)   | —                | CEO approval  |
+| Board members       | Email (draft)   | —                | CEO approval  |
+| Regulators          | Email (draft)   | —                | Dual approval |
+| Acquisition targets | Email (draft)   | —                | CEO approval  |
+| External advisors   | Email (draft)   | Slack guest      | CEO approval  |
+| Engineering team    | Slack + GitHub  | Email            | Auto-execute  |
+
+### 6.3 Approval Flow
+
+```
+Sophie drafts communication
+  │
+  ├─ Level 0-1: Auto-send, log action
+  │
+  ├─ Level 2: Hold in outputs/communications/
+  │            Notify Mehran via Slack: "Draft ready for review: [title]"
+  │            Wait for: Approve / Revise / Reject
+  │            On Approve: Send, log approval
+  │            On Revise: Update draft, re-submit
+  │            On Reject: Archive, log rejection
+  │
+  └─ Level 3-4: Hold in outputs/communications/
+                Notify Mehran via Slack + WhatsApp
+                Require explicit "APPROVED" response
+                Level 4: Require second approver confirmation
+                On Approve: Send, log all approvals
+                On Timeout (24h): Re-escalate
+```
+
+### 6.4 Communication Logging
+
+Every communication (sent or drafted) is logged with:
+
+- Timestamp, channel, sender identity (voice mode), recipient(s)
+- Full message content
+- Governance level applied
+- Approval chain (who approved, when)
+- Thread context (what prompted this communication)
+
+---
+
+## 7. Scheduling Architecture
+
+### 7.1 Scheduling Infrastructure
+
+The system uses a dual scheduling approach:
+
+1. **launchd** (macOS native) — For system-level process supervision and core daemon scheduling
+2. **Cron-equivalent workflows** — For business-logic scheduling managed within the CEO Brain runtime
+
+### 7.2 launchd Configuration
+
+Core system processes are managed as launchd agents:
+
+```xml
+<!-- ~/Library/LaunchAgents/com.adaptic.sophie-ai.core.plist -->
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.adaptic.sophie-ai.core</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/usr/local/bin/claude</string>
+        <string>--session</string>
+        <string>sophie-main</string>
+    </array>
+    <key>KeepAlive</key>
+    <true/>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <string>/Users/sophie/sophie-ai/logs/core.stdout.log</string>
+    <key>StandardErrorPath</key>
+    <string>/Users/sophie/sophie-ai/logs/core.stderr.log</string>
+    <key>WorkingDirectory</key>
+    <string>/Users/sophie/sophie-ai</string>
+</dict>
+</plist>
+```
+
+### 7.3 Scheduled Workflows
+
+Workflow definitions reside in `/Users/sophie/sophie-ai/workflows/` organised by cadence:
+
+```
+workflows/
+├── daily/            # Runs every day
+├── weekly/           # Runs on specific days
+├── monthly/          # Runs on specific dates
+├── quarterly/        # Runs at quarter boundaries
+└── event-driven/     # Triggered by external events
+```
+
+#### 7.3.1 Daily Schedule
+
+| Time (UTC) | Workflow                             | Agent                              | Output                |
+| ---------- | ------------------------------------ | ---------------------------------- | --------------------- |
+| 02:00      | Market data overnight ingest         | `market-research`                  | `ingest/market-data/` |
+| 02:30      | Competitive intelligence sweep       | `competitive-intel`                | `ingest/competitive/` |
+| 03:00      | System maintenance window            | `system`                           | `logs/maintenance/`   |
+| 05:30      | Morning intelligence synthesis       | `sophie`                           | Working memory        |
+| 06:00      | CEO Morning Brief compilation        | `ceo-briefing`                     | `outputs/briefs/`     |
+| 07:30      | Inbox triage (Gmail + Slack)         | `gmail-operator`, `slack-operator` | Classified queue      |
+| 08:00      | Action item extraction               | `sophie`                           | Task assignments      |
+| 12:00      | Midday follow-up sweep               | `slack-operator`                   | Follow-up queue       |
+| 17:00      | End-of-day communications review     | `sophie`                           | Pending items report  |
+| 17:30      | CEO Evening Wrap compilation         | `ceo-briefing`                     | `outputs/briefs/`     |
+| 22:00      | Overnight monitoring mode activation | `sophie`                           | Alert-only mode       |
+
+#### 7.3.2 Weekly Schedule
+
+| Day       | Workflow                       | Agent                   |
+| --------- | ------------------------------ | ----------------------- |
+| Monday    | Weekly priorities review       | `sophie` + `pmo`        |
+| Tuesday   | Engineering health review      | `engineering-coord`     |
+| Wednesday | Rollup pipeline review         | `corporate-development` |
+| Thursday  | Regulatory and legal follow-up | `regulatory-dfsa`       |
+| Friday    | Weekly Strategic Memo          | `sophie` + `strategic`  |
+
+#### 7.3.3 Monthly Schedule
+
+| Workflow                       | Agent                          |
+| ------------------------------ | ------------------------------ |
+| Runway and capital review      | `fund-ops` + `capital-raising` |
+| Product maturity assessment    | `product-strategy`             |
+| Board readiness review         | `board-prep`                   |
+| Risk register refresh          | `risk-register`                |
+| Hiring and org review          | `hiring-org-design`            |
+| Knowledge base freshness audit | `sophie`                       |
+
+### 7.4 Event-Driven Triggers
+
+In addition to scheduled workflows, the system responds to real-time events:
+
+| Event                               | Trigger Source         | Response                                     |
+| ----------------------------------- | ---------------------- | -------------------------------------------- |
+| CEO Slack message to Sophie         | Slack monitoring       | Immediate context assembly and response      |
+| Critical email received             | Gmail monitoring       | Alert + triage + draft response              |
+| GitHub PR merged to main            | GitHub webhook / poll  | Engineering status update                    |
+| Market circuit breaker triggered    | Market data monitoring | Risk alert to CEO + risk-register agent      |
+| Competitor announcement detected    | News / RSS monitoring  | Competitive intelligence brief               |
+| Kill switch activated               | Filesystem watch       | Immediate halt per kill switch type          |
+| New file in ingest directory        | `fswatch` on ingest/   | Classify and route to appropriate processing |
+| Calendar event approaching (15 min) | Calendar sync          | Meeting brief preparation and delivery       |
+
+Event-driven workflow definitions reside in `/Users/sophie/sophie-ai/workflows/event-driven/`.
+
+---
+
+## 8. Integration Points
+
+### 8.1 MCP (Model Context Protocol) Servers
+
+MCP is the primary integration protocol. MCP servers expose external services as structured tools available to Claude Code.
+
+| MCP Server            | Service            | Capabilities                                              |
+| --------------------- | ------------------ | --------------------------------------------------------- |
+| `mcp-slack`           | Slack              | Read channels, post messages, manage threads, search      |
+| `mcp-gmail`           | Gmail (Google API) | Read inbox, send/draft emails, manage labels, search      |
+| `mcp-google-calendar` | Google Calendar    | Read/write events, check availability, manage invitations |
+| `mcp-github`          | GitHub             | Repos, PRs, issues, actions, code search                  |
+| `mcp-filesystem`      | Local filesystem   | Read/write files, directory operations, file watching     |
+| `mcp-linear`          | Linear             | Issue tracking, project management, sprint data           |
+| `mcp-browser`         | Browser automation | Navigate, extract, fill forms, download                   |
+
+MCP server configurations are stored in `/Users/sophie/sophie-ai/mcp/`.
+
+### 8.2 Claude Code CLI
+
+The system runs on Claude Code as the primary runtime. Key integration points:
+
+| Feature             | Usage                                                           |
+| ------------------- | --------------------------------------------------------------- |
+| Session persistence | Named sessions (`--session sophie-main`) for context continuity |
+| Tool use            | Bash, Read, Write, Edit, Glob, Grep for filesystem operations   |
+| MCP tool invocation | Access to all registered MCP servers                            |
+| Computer use        | Screenshot capture and analysis for desktop control             |
+| Sub-agent spawning  | Claude Code instances for parallel agent execution              |
+| Background tasks    | Long-running operations via background execution                |
+
+### 8.3 Remote Bridge
+
+The remote bridge enables the CEO to interact with the system from any device.
+
+```
+┌──────────────┐     ┌─────────────────┐     ┌──────────────────┐
+│ CEO's Phone  │────▶│  Remote Bridge   │────▶│  CEO Brain       │
+│ / Laptop     │◀────│  (Secure Relay)  │◀────│  (Mac mini)      │
+└──────────────┘     └─────────────────┘     └──────────────────┘
+```
+
+| Feature           | Implementation                                 |
+| ----------------- | ---------------------------------------------- |
+| Command channel   | Encrypted message queue (CEO to Sophie)        |
+| Response channel  | Encrypted message queue (Sophie to CEO)        |
+| Approval workflow | Structured approval/reject messages via bridge |
+| Kill switch       | Remote halt command via bridge                 |
+| Status queries    | On-demand system status reports                |
+
+Remote bridge code and configuration reside in `/Users/sophie/sophie-ai/remote-bridge/`.
+
+### 8.4 External APIs
+
+| API              | Purpose                                     | Auth Method         |
+| ---------------- | ------------------------------------------- | ------------------- |
+| Anthropic API    | Claude model access for agent reasoning     | API key (encrypted) |
+| Polygon.io       | Market data (prices, news, fundamentals)    | API key             |
+| Alpaca Markets   | Brokerage data (positions, orders, account) | OAuth / API key     |
+| Google Workspace | Gmail, Calendar, Drive                      | OAuth 2.0           |
+| GitHub           | Repository operations                       | PAT / GitHub App    |
+| Slack            | Workspace communication                     | Bot token + OAuth   |
+| News APIs        | Competitive and market intelligence         | API keys            |
+
+### 8.5 Claude Code Plugins
+
+Custom plugins extend the system's capabilities:
+
+```
+plugins/
+├── sophie-ai-tools/     # Custom tools for executive operations
+├── desktop-control/     # macOS desktop automation tools
+├── knowledge-ops/       # Knowledge base management tools
+└── governance/          # Approval and audit trail tools
+```
+
+Plugin configurations and source reside in `/Users/sophie/sophie-ai/plugins/`.
+
+---
+
+## 9. Security Architecture
+
+### 9.1 Threat Model
+
+| Threat                             | Severity | Mitigation                                              |
+| ---------------------------------- | -------- | ------------------------------------------------------- |
+| Credential theft from filesystem   | Critical | macOS Keychain + encrypted secrets store                |
+| Unauthorised system access         | Critical | SSH key auth, no password login, firewall rules         |
+| Agent prompt injection             | High     | Input sanitisation, output validation, sandboxed agents |
+| Data exfiltration via agent action | High     | Outbound communication gating, audit logging            |
+| Privilege escalation by agent      | High     | Role-based tool access, governance layer enforcement    |
+| Man-in-the-middle on API calls     | Medium   | TLS everywhere, certificate pinning where possible      |
+| Physical access to Mac mini        | Medium   | Physical security, FileVault encryption, auto-lock      |
+| Supply chain attack on MCP servers | Medium   | Pin MCP server versions, review before update           |
+
+### 9.2 Secrets Management
+
+```
+Secrets storage hierarchy:
+  1. macOS Keychain (preferred) — API keys, OAuth tokens, credentials
+  2. Encrypted env files — Environment-specific configuration
+  3. NEVER in plaintext files, git history, or agent context
+
+Secrets access pattern:
+  Agent → requests secret by name → Governance Layer validates access → Keychain retrieval → inject into tool call → secret never enters log or memory
+```
+
+**Critical rule:** No secret, credential, or token is ever written to the knowledge base, log files, agent context, or any file in the sophie-ai directory tree in plaintext.
+
+### 9.3 Access Control
+
+| Principal               | Access Level                                                  |
+| ----------------------- | ------------------------------------------------------------- |
+| Sophie (core agent)     | Full read, gated write, orchestration authority               |
+| Domain VP agents        | Domain-scoped read, domain-scoped write, no escalation bypass |
+| Specialist Workers      | Task-scoped read, task-scoped write only                      |
+| CEO (Mehran) via bridge | Full override authority, approval authority                   |
+| System administrator    | SSH access, launchd management, no agent impersonation        |
+
+### 9.4 Audit Logging
+
+All logs are written to `/Users/sophie/sophie-ai/logs/` with the following guarantees:
+
+- **Append-only** — Log files are never modified after writing, only rotated
+- **Structured format** — JSON lines for machine parsing, human-readable summaries
+- **Retention** — 6 years minimum (regulatory requirement per DFSA)
+- **Integrity** — Daily log checksums stored separately
+- **Categories:**
+  - `audit.log` — All governance-relevant actions (communications, approvals, escalations)
+  - `agent.log` — Agent lifecycle events (spawn, assign, complete, error)
+  - `desktop.log` — Desktop control actions (app interactions, UI operations)
+  - `perception.log` — Ingest events (what was observed, when, from where)
+  - `error.log` — System errors, failures, recovery actions
+  - `core.stdout.log` / `core.stderr.log` — Raw process output
+
+### 9.5 Encryption
+
+| Data Category         | At Rest                          | In Transit           |
+| --------------------- | -------------------------------- | -------------------- |
+| Secrets / Credentials | macOS Keychain (hardware-backed) | TLS 1.3              |
+| Knowledge base        | FileVault (full-disk encryption) | N/A (local)          |
+| Logs                  | FileVault (full-disk encryption) | N/A (local)          |
+| API communications    | N/A                              | TLS 1.3              |
+| Remote bridge         | N/A                              | End-to-end encrypted |
+| Backups               | AES-256 encrypted archives       | TLS 1.3 for transfer |
+
+### 9.6 Network Security
+
+- macOS firewall enabled; only required ports open (SSH, HTTPS outbound)
+- No inbound connections except SSH (key-auth only) and remote bridge relay
+- DNS-over-HTTPS to prevent DNS-based monitoring
+- All API traffic over TLS; no plaintext HTTP
+- VPN for administrative access when off-network
+
+---
+
+## 10. Resilience and Recovery
+
+### 10.1 Health Check System
+
+The watchdog process runs independently of the main CEO Brain runtime and monitors system health.
+
+| Check                   | Frequency  | Failure Action                                               |
+| ----------------------- | ---------- | ------------------------------------------------------------ |
+| Core process alive      | 30 seconds | Restart via launchd (automatic)                              |
+| Disk space > 20% free   | 5 minutes  | Alert + log rotation + old output archival                   |
+| Network connectivity    | 1 minute   | Alert; queue outbound actions; retry with backoff            |
+| Memory usage < 80%      | 1 minute   | Alert; graceful restart if persistent                        |
+| Slack API accessible    | 5 minutes  | Fall back to desktop control                                 |
+| Gmail API accessible    | 5 minutes  | Fall back to browser control                                 |
+| MCP servers responsive  | 5 minutes  | Restart unresponsive server; fall back to CLI tools          |
+| Log directory writable  | 5 minutes  | Critical alert; attempt repair; halt actuation if persistent |
+| Kill switch file absent | 10 seconds | If present: execute halt per switch type                     |
+| Screen unlocked         | 1 minute   | Unlock if locked; alert if unable                            |
+| Clock sync (NTP)        | 1 hour     | Alert if drift > 5 seconds                                   |
+
+### 10.2 Watchdog Process
+
+```xml
+<!-- ~/Library/LaunchAgents/com.adaptic.sophie-ai.watchdog.plist -->
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.adaptic.sophie-ai.watchdog</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>/Users/sophie/sophie-ai/scripts/watchdog.sh</string>
+    </array>
+    <key>StartInterval</key>
+    <integer>30</integer>
+    <key>KeepAlive</key>
+    <true/>
+    <key>RunAtLoad</key>
+    <true/>
+</dict>
+</plist>
+```
+
+The watchdog is a lightweight shell script (no dependency on Claude or Python). It checks process health, disk, memory, and network, and can restart the core process or trigger alerts independently.
+
+### 10.3 State Persistence
+
+The system is designed to survive restarts without data loss:
+
+| State Category           | Persistence Method                                     | Recovery                             |
+| ------------------------ | ------------------------------------------------------ | ------------------------------------ |
+| Strategic memory         | Files in `knowledge/` (git-tracked)                    | Always available on restart          |
+| Execution queues         | Files in `teams/` with structured status               | Resume from last known state         |
+| Working memory           | Session state file written at checkpoints              | Reload on session restart            |
+| Scheduled workflow state | Filesystem markers (last-run timestamps)               | Detect missed runs, execute catch-up |
+| Desktop state            | Screenshot before shutdown                             | Restore from screenshot analysis     |
+| Pending approvals        | Files in `outputs/communications/` with pending status | Re-surface in next briefing          |
+| Decision log             | Append-only files in `knowledge/decisions/`            | Always available                     |
+| Audit logs               | Append-only files in `logs/`                           | Always available                     |
+
+### 10.4 Recovery Procedures
+
+#### 10.4.1 Graceful Restart
+
+```
+1. Flush working memory to episodic memory
+2. Write session checkpoint (current tasks, pending items, queue state)
+3. Log restart reason
+4. Terminate agent sessions
+5. [Restart occurs via launchd]
+6. Load session checkpoint
+7. Verify knowledge base integrity
+8. Resume scheduled workflows (catch up any missed)
+9. Notify CEO: "System restarted at [time]. Reason: [reason]. All state recovered."
+```
+
+#### 10.4.2 Crash Recovery
+
+```
+1. [launchd detects process death, restarts within 30 seconds]
+2. Load last session checkpoint
+3. Scan for incomplete operations (partial file writes, unsent messages)
+4. Roll back incomplete operations
+5. Resume from last clean state
+6. Audit log gap analysis (identify any unlogged period)
+7. Notify CEO: "System crash recovery at [time]. Gap: [duration]. Review needed: [items]"
+```
+
+#### 10.4.3 Full System Recovery (from backup)
+
+```
+1. Restore macOS from Time Machine or archived backup
+2. Verify FileVault decryption
+3. Verify Keychain access (secrets intact)
+4. Run integrity check on knowledge/ directory
+5. Verify launchd agents registered
+6. Start watchdog
+7. Start core process
+8. Run full health check suite
+9. Notify CEO via all channels: "Full system recovery complete. Manual audit recommended."
+```
+
+### 10.5 Backup Strategy
+
+| Data                 | Method                                | Frequency       | Retention      |
+| -------------------- | ------------------------------------- | --------------- | -------------- |
+| Full system          | Time Machine to encrypted external    | Hourly          | 30 days        |
+| Knowledge base       | Git push to private remote            | On every commit | Permanent      |
+| Logs and audit trail | Compressed archive to encrypted store | Daily           | 6 years (DFSA) |
+| Configuration        | Git push to private remote            | On every change | Permanent      |
+| Secrets / Keychain   | macOS Keychain backup (encrypted)     | Weekly          | 1 year         |
+
+---
+
+## 11. Directory Structure Reference
+
+```
+/Users/sophie/sophie-ai/
+├── agents/                          # Agent definitions and configurations
+│   ├── sophie-chief-of-staff/       # Executive Cortex (Tier 1)
+│   ├── strategic-planning/          # Domain VP (Tier 2)
+│   ├── capital-raising/             # Domain VP (Tier 2)
+│   ├── corporate-development/       # Domain VP (Tier 2)
+│   ├── engineering-coordination/    # Domain VP (Tier 2)
+│   ├── product-strategy/            # Domain VP (Tier 2)
+│   ├── regulatory-dfsa/             # Domain VP (Tier 2)
+│   ├── fund-ops/                    # Domain VP (Tier 2)
+│   ├── communications/              # Domain VP (Tier 2)
+│   ├── hiring-org-design/           # Domain VP (Tier 2)
+│   ├── risk-register/               # Domain VP (Tier 2)
+│   ├── ceo-briefing/                # Specialist Worker (Tier 3)
+│   ├── competitive-intelligence/    # Specialist Worker (Tier 3)
+│   ├── market-research/             # Specialist Worker (Tier 3)
+│   ├── rollup-target-sourcing/      # Specialist Worker (Tier 3)
+│   ├── board-prep/                  # Specialist Worker (Tier 3)
+│   ├── legal-structuring/           # Specialist Worker (Tier 3)
+│   ├── partnerships/                # Specialist Worker (Tier 3)
+│   ├── decision-log/                # Specialist Worker (Tier 3)
+│   ├── founder-voice/               # Specialist Worker (Tier 3)
+│   ├── pmo-execution/               # Specialist Worker (Tier 3)
+│   ├── platform-architecture/       # Specialist Worker (Tier 3)
+│   ├── workflow-automation/         # Specialist Worker (Tier 3)
+│   ├── desktop-operator/            # Desktop Specialist (Tier 3)
+│   ├── slack-operator/              # Desktop Specialist (Tier 3)
+│   ├── gmail-operator/              # Desktop Specialist (Tier 3)
+│   ├── whatsapp-operator/           # Desktop Specialist (Tier 3)
+│   ├── browser-operator/            # Desktop Specialist (Tier 3)
+│   └── calendar-ops/               # Desktop Specialist (Tier 3)
+├── config/                          # System configuration files
+├── dashboards/                      # Dashboard definitions and templates
+├── desktop-control/                 # Desktop automation scripts and state
+├── docs/                            # Documentation
+│   ├── architecture/                # System architecture (this document)
+│   ├── business-synthesis/          # Business context documents
+│   ├── governance/                  # Governance policies and procedures
+│   ├── operating-model/             # Operating model definitions
+│   ├── prompts/                     # Prompt templates and libraries
+│   ├── runbooks/                    # Operational runbooks
+│   ├── vision/                      # Vision and strategy documents
+│   └── workflows/                   # Workflow documentation
+├── ingest/                          # Raw ingested data (perception layer)
+├── knowledge/                       # Persistent knowledge base
+│   ├── decisions/                   # Decision memory (append-only)
+│   ├── entities/                    # Entity profiles and maps
+│   ├── memory/                      # Episodic memory entries
+│   ├── sources/                     # Source documents and research
+│   └── syntheses/                   # Cross-source synthesis documents
+├── logs/                            # System and audit logs
+├── mcp/                             # MCP server configurations
+├── outputs/                         # Generated deliverables
+│   ├── board/                       # Board materials
+│   ├── briefs/                      # CEO briefs (morning/evening)
+│   ├── communications/              # Draft communications
+│   ├── followups/                   # Follow-up tracking
+│   └── memos/                       # Strategic and operational memos
+├── plugins/                         # Claude Code plugin extensions
+├── policies/                        # Governance policies (machine-readable)
+├── remote-bridge/                   # Remote access bridge
+├── schedules/                       # Schedule definitions and state
+├── scripts/                         # System scripts (watchdog, maintenance)
+├── teams/                           # Agent team orchestration state
+├── tests/                           # System tests and validation
+└── workflows/                       # Workflow definitions by cadence
+    ├── daily/
+    ├── weekly/
+    ├── monthly/
+    ├── quarterly/
+    └── event-driven/
+```
+
+---
+
+## Appendix A: Technology Stack Summary
+
+| Component            | Technology                                           |
+| -------------------- | ---------------------------------------------------- |
+| AI Runtime           | Claude Code CLI (Anthropic)                          |
+| Model                | Claude (latest available via Anthropic API)          |
+| Integration Protocol | MCP (Model Context Protocol)                         |
+| Desktop Control      | AppleScript, Accessibility API, CGEvent              |
+| Process Supervision  | launchd (macOS native)                               |
+| Scheduling           | launchd + workflow engine                            |
+| Secrets Management   | macOS Keychain                                       |
+| Disk Encryption      | FileVault 2                                          |
+| Version Control      | Git (knowledge base, config, agent definitions)      |
+| Log Format           | JSON Lines (structured) + plaintext (human-readable) |
+| Backup               | Time Machine + git remote + encrypted archives       |
+| Network Security     | macOS firewall + TLS 1.3 + SSH key auth              |
+| File Watching        | `fswatch` (macOS)                                    |
+| Operating System     | macOS 14+ (Sonoma)                                   |
+| Hardware             | Apple Silicon Mac mini                               |
+
+## Appendix B: Configuration Checklist (Initial Deployment)
+
+- [ ] Mac mini provisioned with macOS 14+, FileVault enabled
+- [ ] User account `sophie` created with admin privileges
+- [ ] Accessibility permissions granted to Claude Code and Terminal
+- [ ] Screen lock disabled or auto-unlock configured
+- [ ] Claude Code CLI installed and authenticated
+- [ ] All MCP servers installed and configured in `/Users/sophie/sophie-ai/mcp/`
+- [ ] API keys stored in macOS Keychain (Anthropic, Slack, Google, GitHub, Polygon, Alpaca)
+- [ ] OAuth tokens provisioned (Google Workspace, Slack, GitHub)
+- [ ] launchd agents installed (core process, watchdog)
+- [ ] SSH key-only access configured; password login disabled
+- [ ] Firewall rules configured (outbound HTTPS; inbound SSH only)
+- [ ] Time Machine backup configured to encrypted external drive
+- [ ] Git remote configured for knowledge base and config
+- [ ] All agent directories populated with system prompts
+- [ ] Governance policies written to `/Users/sophie/sophie-ai/policies/`
+- [ ] Kill switch mechanism tested (create and remove lock files)
+- [ ] Remote bridge configured and tested
+- [ ] Watchdog script deployed and tested
+- [ ] Full health check suite passing
+- [ ] CEO (Mehran) can reach system via Slack, WhatsApp, and remote bridge
+- [ ] First CEO Morning Brief generated successfully
+
+---
+
+> This document is the authoritative reference for the CEO Brain system architecture. All implementation must conform to the specifications herein. Changes to this document require review and approval.