diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..f0aa207
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,31 @@
+# AIWorkspace Documentation
+
+AIWorkspace is a local context platform for developers. It connects project evidence, canonical human-readable memory, local services, and AI clients without making any single AI tool the source of truth.
+
+This documentation describes the target production architecture: reusable AIWorkspace core separated from project-specific AI context packs.
+
+## Start Here
+
+- [Concepts: Overview](concepts/overview.md)
+- [Concepts: Workspace vs Context Pack](concepts/workspace-vs-context-pack.md)
+- [Architecture: Storage Model](architecture/storage-model.md)
+- [Guide: Quick Start](guides/quick-start.md)
+- [Reference: Project Manifest](reference/project-manifest.md)
+
+## Documentation Map
+
+```text
+docs/
+  concepts/       Product concepts and user-facing mental model
+  architecture/   System boundaries, storage, services, and security
+  guides/         Task-oriented setup and usage guides
+  reference/      File formats, CLI, manifests, and environment variables
+```
+
+## Core Principle
+
+```text
+AIWorkspace provides context. Project context packs own project memory.
+```
+
+The core product should remain reusable and shareable. Project-specific facts, connector settings, people, channels, raw evidence, and prompts belong in separate context packs.
diff --git a/docs/architecture/storage-model.md b/docs/architecture/storage-model.md
new file mode 100644
index 0000000..b6c9017
--- /dev/null
+++ b/docs/architecture/storage-model.md
@@ -0,0 +1,98 @@
+# Storage Model
+
+AIWorkspace uses different storage locations for different kinds of data. This keeps the product shareable, the project context auditable, and local runtime state disposable.
+
+## Storage Responsibilities
+
+| Data | Target Location | Git? | Notes |
+|---|---|---:|---|
+| Core product code | `~/Developer/ai-workspace` | yes | Shared reusable product. |
+| Project manifest | `<context-pack>/aiw.project.json` | yes | Project identity and relative paths. |
+| Canonical memory | `<context-pack>/knowledge/` | usually yes | Human-readable Markdown. |
+| Raw evidence | `<context-pack>/inbox/` | usually no/private | Captured messages, screenshots, exports. |
+| Connector config | `<context-pack>/connectors/` | depends | Safe config can be tracked; secrets must not be tracked. |
+| Project prompts/agents | `<context-pack>/prompts/`, `<context-pack>/agents/` | depends | Track if safe for the team. |
+| User registry | `~/Library/Application Support/AIWorkspace/` | no | Local project registration and preferences. |
+| Logs | `~/Library/Logs/AIWorkspace/` | no | Service and app logs. |
+| Caches/indexes | `~/Library/Caches/AIWorkspace/` | no | Rebuildable derived data. |
+| Runtime/PIDs | `~/Library/Application Support/AIWorkspace/runtime/` | no | Local service state. |
+
+## Canonical Memory
+
+Canonical memory is the durable project source of truth for humans and AI.
+
+Target structure:
+
+```text
+knowledge/
+  current/
+  work-items/
+  systems/
+  workstreams/
+  people/
+  decisions/
+  daily/
+  templates/
+```
+
+Canonical memory should be:
+
+- readable without AIWorkspace;
+- reviewable in Git when shared;
+- explicit about uncertainty;
+- updated by humans or agents using small auditable changes.
+
+## Raw Evidence
+
+Raw evidence is input, not truth.
+
+Examples:
+
+```text
+inbox/
+  mattermost/
+  slack/
+  photos/
+  documents/
+  screenshots/
+```
+
+Raw evidence should not be promoted automatically into durable memory unless a workflow explicitly classifies it as high-confidence and project-relevant.
+
+## Derived Indexes
+
+Indexes are rebuildable.
+
+They should live outside the context pack by default:
+
+```text
+~/Library/Caches/AIWorkspace/indexes/<project>/
+```
+
+This prevents large derived artifacts from polluting project memory repositories.
+
+## Runtime State
+
+Service logs, PID files, and health snapshots should be local machine state.
+
+Target locations:
+
+```text
+~/Library/Logs/AIWorkspace/
+~/Library/Application Support/AIWorkspace/runtime/
+```
+
+Runtime state should not be used as project memory.
+
+## Secrets
+
+Secrets should not be stored in context packs unless they are encrypted and explicitly supported.
+
+Preferred approaches:
+
+- macOS Keychain references;
+- ignored local `.env` files;
+- environment variables;
+- enterprise-approved credential stores.
+
+Documentation, manifests, and generated configs should refer to secret names, not secret values.
diff --git a/docs/concepts/overview.md b/docs/concepts/overview.md
new file mode 100644
index 0000000..4dbd1d8
--- /dev/null
+++ b/docs/concepts/overview.md
@@ -0,0 +1,65 @@
+# AIWorkspace Overview
+
+AIWorkspace helps developers give AI tools the right project context at the right time.
+
+It is designed for teams and individuals who use multiple AI clients—OpenCode, GitHub Copilot, Claude Code, Cursor, VS Code, or others—but do not want project knowledge scattered across chat histories, prompt files, and product repositories.
+
+## What AIWorkspace Does
+
+AIWorkspace provides a local platform to:
+
+- connect communication and evidence sources;
+- keep canonical project memory in human-readable Markdown;
+- index that memory for fast retrieval;
+- expose bounded context through MCP;
+- generate AI client configuration when needed;
+- run local services such as context servers, capture proxies, and inbox receivers;
+- keep raw evidence separate from curated project knowledge.
+
+## What AIWorkspace Is Not
+
+AIWorkspace is not:
+
+- a replacement for a product repository;
+- a replacement for project documentation;
+- a cloud memory system;
+- a single-agent framework that forces one AI workflow;
+- a place to store secrets in Git;
+- a dumping ground for raw chat exports.
+
+## Target User Flow
+
+```text
+Developer installs AIWorkspace
+        ↓
+Registers or creates a project context pack
+        ↓
+Connects evidence sources and local repos
+        ↓
+AIWorkspace captures evidence and maintains indexes
+        ↓
+AI clients ask AIWorkspace MCP for project context
+        ↓
+Humans and agents update canonical project memory
+```
+
+## Key Concepts
+
+| Concept | Meaning |
+|---|---|
+| AIWorkspace Core | The reusable app, CLI, scripts, MCP server, connectors, templates, and documentation. |
+| User Registry | Local app configuration that remembers registered projects, paths, preferences, and service state. |
+| Project Context Pack | A project-specific folder or repo containing canonical memory, connector config, prompts, and optional raw evidence. |
+| Canonical Memory | Human-readable Markdown that represents current durable project knowledge. |
+| Raw Evidence | Captured messages, screenshots, exports, logs, or documents before curation. |
+| AI Client | Any tool that consumes context: OpenCode, Copilot, Claude Code, Cursor, VS Code, etc. |
+
+## Design Goal
+
+AIWorkspace should be plug-and-play for a new developer:
+
+1. install the app and CLI;
+2. register an existing context pack or create a new one;
+3. connect sources such as Mattermost, Slack, tickets, email, calendar, or local folders;
+4. let AIWorkspace detect repositories and services;
+5. use any AI client with project-aware context through MCP.
diff --git a/docs/concepts/workspace-vs-context-pack.md b/docs/concepts/workspace-vs-context-pack.md
new file mode 100644
index 0000000..9880023
--- /dev/null
+++ b/docs/concepts/workspace-vs-context-pack.md
@@ -0,0 +1,127 @@
+# Workspace vs Context Pack
+
+AIWorkspace separates the installed product, user-local settings, and project memory.
+
+This distinction keeps the system simple, shareable, and safe for unrelated projects such as `client-mobile` and `it-support`.
+
+## Three-Layer Model
+
+```text
+AIWorkspace Core
+  reusable installed product
+
+User/App Registry
+  local machine settings and registered context packs
+
+Project Context Packs
+  one isolated context package per project, client, or workstream
+```
+
+## AIWorkspace Core
+
+The core is the reusable product. It can be shared with a team.
+
+Typical location during development:
+
+```text
+~/Developer/ai-workspace
+```
+
+It contains:
+
+```text
+apps/
+scripts/
+connectors/
+templates/
+docs/
+examples/
+```
+
+It should not contain real project memory, captured messages, customer names, ticket details, or private prompts.
+
+## User/App Registry
+
+The registry is local to one developer machine. It records which context packs are available and which project is active.
+
+On macOS, the target location is:
+
+```text
+~/Library/Application Support/AIWorkspace/
+```
+
+Example registry:
+
+```json
+{
+  "schema": "aiworkspace.projects.v1",
+  "default_project": "client-mobile",
+  "projects": [
+    {
+      "id": "client-mobile",
+      "context_path": "/Users/david/Developer/client-mobile-ai-context"
+    },
+    {
+      "id": "it-support",
+      "context_path": "/Users/david/Developer/it-support-ai-context"
+    }
+  ]
+}
+```
+
+The registry is not intended for Git.
+
+## Project Context Pack
+
+A context pack is the portable project-specific unit. It may be a private repo, a team-shared repo, or a local folder.
+
+Example:
+
+```text
+client-mobile-ai-context/
+  aiw.project.json
+  knowledge/
+  inbox/
+  connectors/
+  agents/
+  prompts/
+```
+
+Each context pack owns its own:
+
+- canonical memory;
+- raw evidence;
+- connector definitions;
+- people/channel/system maps;
+- prompts and agent instructions specific to that project.
+
+## Why Not Store Everything In One Workspace Repo?
+
+One developer can work on unrelated projects. A single monolithic workspace can accidentally mix:
+
+- channels from different organizations;
+- people maps from unrelated clients;
+- raw evidence with different privacy rules;
+- prompts that only make sense for one domain;
+- AI behavior learned from one project but harmful in another.
+
+Context packs prevent this by making project boundaries explicit.
+
+## Optional Product Repository Binding
+
+Product repositories should stay clean by default. If useful, a repo can contain a small optional binding file:
+
+```text
+.aiworkspace.json
+```
+
+Example:
+
+```json
+{
+  "project": "client-mobile",
+  "context_path": "/Users/david/Developer/client-mobile-ai-context"
+}
+```
+
+This file should point to context. It should not contain memory, secrets, or raw evidence.
diff --git a/docs/guides/quick-start.md b/docs/guides/quick-start.md
new file mode 100644
index 0000000..c48d2d3
--- /dev/null
+++ b/docs/guides/quick-start.md
@@ -0,0 +1,121 @@
+# Quick Start
+
+This guide describes the target production flow for a new developer using AIWorkspace.
+
+The current repository still contains an active project-specific implementation. During refactor, these commands may be implemented incrementally.
+
+## 1. Install AIWorkspace
+
+Install the app, CLI, and local services from the reusable core repo:
+
+```bash
+git clone <team-ai-workspace-repo> ~/Developer/ai-workspace
+cd ~/Developer/ai-workspace
+```
+
+The target CLI entry point is:
+
+```bash
+aiw
+```
+
+During development, commands may still be run through Python scripts.
+
+## 2. Register Or Create A Project Context Pack
+
+Register an existing context pack:
+
+```bash
+aiw project register ~/Developer/client-mobile-ai-context
+```
+
+Or create a new one:
+
+```bash
+aiw project create it-support --display-name "IT Support" --path ~/Developer/it-support-ai-context
+```
+
+The context pack contains project memory and project-specific connector configuration.
+
+## 3. Connect Evidence Sources
+
+Add only the connectors this project needs:
+
+```bash
+aiw connector add mattermost --project client-mobile
+aiw connector add photos --project client-mobile
+```
+
+For another project, the connector set may be completely different:
+
+```bash
+aiw connector add tickets --project it-support
+aiw connector add calendar --project it-support
+```
+
+## 4. Detect Local Repositories
+
+AIWorkspace should help detect local repos and associate them with projects:
+
+```bash
+aiw repo scan ~/Developer --project it-support
+```
+
+For projects whose source code lives on another machine, the context pack should say so explicitly in `aiw.project.json`.
+
+## 5. Start Context Services
+
+Start services for the active project:
+
+```bash
+aiw services start --project client-mobile
+aiw services status --project client-mobile
+```
+
+The service manager should start only capabilities configured for that project.
+
+## 6. Configure AI Clients
+
+Generate AI client integration files on demand:
+
+```bash
+aiw agent configure opencode --project client-mobile
+aiw agent configure copilot --project client-mobile
+aiw mcp config --client vscode
+```
+
+The preferred integration path is MCP, so AI clients can request current context without copying memory into product repositories.
+
+## 7. Use AIWorkspace From Any AI Tool
+
+The AI client should call MCP with a project id:
+
+```json
+{
+  "project": "client-mobile"
+}
+```
+
+Example tool calls:
+
+```text
+project_current_context(project="client-mobile")
+project_search_memory(project="it-support", query="printer onboarding")
+communication_latest(project="client-mobile")
+```
+
+## 8. Keep Canonical Memory Clean
+
+Project memory lives in the context pack:
+
+```text
+<context-pack>/knowledge/
+```
+
+Raw evidence lives separately:
+
+```text
+<context-pack>/inbox/
+```
+
+Do not treat raw captures, indexes, logs, or AI chat history as canonical memory.
diff --git a/docs/reference/project-manifest.md b/docs/reference/project-manifest.md
new file mode 100644
index 0000000..949d7cc
--- /dev/null
+++ b/docs/reference/project-manifest.md
@@ -0,0 +1,125 @@
+# Project Manifest Reference
+
+Each project context pack is described by an `aiw.project.json` file at the root of the context pack.
+
+The manifest defines project identity, storage paths, connectors, code locations, and AI client preferences. Paths are relative to the context pack unless explicitly absolute.
+
+## Minimal Manifest
+
+```json
+{
+  "schema": "aiworkspace.project.v1",
+  "id": "my-project",
+  "display_name": "My Project",
+  "knowledge_dir": "knowledge",
+  "inbox_dir": "inbox"
+}
+```
+
+## Full Example
+
+```json
+{
+  "schema": "aiworkspace.project.v1",
+  "id": "client-mobile",
+  "display_name": "Client Mobile",
+  "description": "Project context pack for a mobile application team.",
+  "knowledge_dir": "knowledge",
+  "inbox_dir": "inbox",
+  "connectors_dir": "connectors",
+  "prompts_dir": "prompts",
+  "agents_dir": "agents",
+  "connectors": {
+    "mattermost": {
+      "enabled": true,
+      "config": "connectors/mattermost.json"
+    },
+    "photos": {
+      "enabled": true,
+      "config": "connectors/photos.json"
+    }
+  },
+  "code_locations": [
+    {
+      "name": "Development machine",
+      "availability": "remote-machine"
+    }
+  ],
+  "ai_clients": {
+    "opencode": {
+      "enabled": true
+    },
+    "copilot": {
+      "enabled": true
+    }
+  }
+}
+```
+
+## Fields
+
+| Field | Required | Description |
+|---|---:|---|
+| `schema` | yes | Manifest schema version. Current target: `aiworkspace.project.v1`. |
+| `id` | yes | Stable lowercase project id used by CLI and MCP. |
+| `display_name` | yes | Human-friendly project name. |
+| `description` | no | Short project description. |
+| `knowledge_dir` | yes | Canonical Markdown memory directory. |
+| `inbox_dir` | yes | Raw evidence directory. |
+| `connectors_dir` | no | Directory for connector configs. Defaults to `connectors`. |
+| `prompts_dir` | no | Directory for project prompts. Defaults to `prompts`. |
+| `agents_dir` | no | Directory for project agent config. Defaults to `agents`. |
+| `connectors` | no | Connector registry for this project. |
+| `code_locations` | no | Local or remote code locations associated with this project. |
+| `ai_clients` | no | AI client integration preferences. |
+
+## Code Locations
+
+Code may be local, remote, or unavailable on the current machine.
+
+```json
+{
+  "name": "iOS App",
+  "path": "/Users/dev/Developer/app-ios",
+  "role": "consumer-app",
+  "availability": "local"
+}
+```
+
+Supported target availability values:
+
+- `local`
+- `remote-machine`
+- `not-configured`
+- `unknown`
+
+## Connector Configs
+
+Connector definitions should describe source behavior without storing secrets.
+
+Example `connectors/mattermost.json`:
+
+```json
+{
+  "schema": "aiworkspace.connector.mattermost.v1",
+  "enabled": true,
+  "context_channels": [
+    "team-standup",
+    "team-code-review"
+  ],
+  "secret_refs": {
+    "session": "keychain:aiworkspace/mattermost/session"
+  }
+}
+```
+
+## Validation Rules
+
+A production-ready manifest validator should check:
+
+- required fields exist;
+- project id is stable and path-safe;
+- configured directories exist or can be created;
+- connector config files exist when enabled;
+- secrets are referenced, not embedded;
+- code locations are explicit about local vs remote availability.