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

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.