feat: add comprehensive documentation for AI Workspace, including architecture, memory model, profiles, services, and security guidelines

docs/architecture.md

@@ -0,0 +1,68 @@
+# Architecture
+
+AI Workspace is organized around explicit boundaries: profile configuration, raw evidence, canonical memory, derived retrieval, local services, and AI client adapters.
+
+## System Flow
+
+```text
+Communication / screenshots / archives / manual notes
+        ↓
+Raw inbox evidence
+        ↓
+Agent or human curation
+        ↓
+Canonical Markdown project knowledge
+        ↓
+Derived local index
+        ↓
+Read-only MCP context server
+        ↓
+AI clients and agent workflows
+```
+
+## Responsibility Boundaries
+
+| Layer | Responsibility | Canonical? |
+|---|---|---|
+| `core/` | Reusable architecture and operating model | yes, for workspace design |
+| `profiles/<profile>/` | Project-specific configuration and assumptions | yes, for profile config |
+| `project-knowledge/` | Human-readable project memory for the active profile | yes, for project facts |
+| `ai/inbox/` | Raw evidence captured from connectors | no |
+| `.aiw/indexes/` | Rebuildable search indexes | no |
+| `.aiw/runtime/` | PID files, logs, local service state | no |
+| `scripts/aiw/` | Profile-aware service/index utilities | code source |
+| `scripts/mcp/` | MCP servers exposing local context | code source |
+| `apps/` | Local UI surfaces such as the macOS menu bar app | code source |
+
+## Current Repository Shape
+
+The current repo still keeps the first real profile's vault at root-level `project-knowledge/`. That is acceptable during migration, but reusable code should increasingly resolve paths from profile configuration rather than hardcoding Fidelity-specific locations.
+
+Target direction:
+
+```text
+profiles/<profile>/workspace.json   # where profile data lives
+workspaces/<profile>/project-knowledge/
+workspaces/<profile>/inbox/
+.aiw/indexes/<profile>/
+```
+
+## Design Principles
+
+- Keep the smallest useful context loaded by default.
+- Prefer just-in-time retrieval over dumping the entire workspace into prompts.
+- Keep human-readable Markdown as the project source of truth.
+- Keep raw evidence outside canonical memory until explicitly promoted.
+- Keep profile-specific facts out of `core/` and generic scripts.
+- Make local services observable through a single service manager.
+- Treat cloud memory systems as optional, not authoritative.
+
+## Why This Shape
+
+Current AI workflow guidance emphasizes context engineering: the model should receive the smallest high-signal context needed for the task. This workspace supports that by combining:
+
+- structured Markdown memory for durable facts;
+- raw evidence stores for auditability;
+- local indexes for retrieval;
+- MCP tools/resources for AI clients;
+- profile-specific boundaries for reuse across projects.