docs: add initial project architecture, concepts, and quick-start documentation

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.

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.