feat(R10): implement CI Quality Gates, Contributor Recipes, E2E Smoke Tests, and update docs

README.md

@@ -1,30 +1,74 @@
 # Cowork Local
 
-Cowork Local is the internal AI cowork desktop platform owned by the Cowork Team. It provides the Cowork runtime, workspace and agent experiences, MCP/connectors, security controls, and model routing foundation.
+Cowork Local is the internal AI cowork desktop platform. It provides a local-first desktop runtime, multi-turn conversational agents, workspace isolation, task scheduling, MCP connectors, security guardrails, and model routing.
 
-The Cowork Team owns this product and its stable branch. The FSG AI Core Team contributes selected reusable capabilities through branches and Pull Requests; it is not the owner or final merger of this repository.
+---
 
-## Quick start
+## 🏛️ 4-Tier Clean Architecture
 
-The imported application is a Python/PySide6 package. Run it from the directory that contains `cowork_local`:
+The codebase strictly adheres to **Clean Architecture** with unidirectional inward dependencies:
+
+```text
+presentation/ (PySide6 UI, Shell, NavRail, Chat, Scheduling, Settings, Dashboard)
+      │
+      ▼
+application/ (Pure Python Orchestration: Conversations, Scheduling, Workspaces, Monitoring, Routing)
+      │
+      ▼
+domain/ (Pure Python: Entities, Immutable Execution Requests, Agent Events, Descriptors)
+      ▲
+      │
+infrastructure/ (Adapters, LLM Providers, Atomic Persistence, Keyring SecretStore, MCP)
+```
+
+- **Domain & Application Layers**: 100% Pure Python (zero Qt/UI imports).
+- **Single Responsibility**: Every production module is strictly `<= 400 LOC`.
+- **Security & Durability**: API keys stored in OS Keyring; atomic JSON disk persistence.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Run the Desktop Application
+From the repository root:
 
 ```bash
 python -m cowork_local
 ```
 
-The source snapshot does not include a complete runtime dependency manifest. Use the Cowork Team's supported runtime environment until that packaging contract is documented. The reliable automated test surface currently checked by CI is:
-
+### 2. Run Automated Tests
 ```bash
-python -m pip install -r cowork_local/requirements-test.txt
-python -m pytest cowork_local/tests -q
+python -m pip install -r requirements-test.txt
+pytest -q
 ```
 
-When already inside this repository, run `python -m pytest tests -q`.
+---
 
-Configuration and runtime data live under `~/.cowork_local/`. Provider keys and local unlock codes must be supplied through environment variables or an approved secret manager; see `.env.example`.
+## 🛡️ CASAN Quality Gate & Verification
 
-## Contributing
+Before submitting any Pull Request, run the unified CASAN Quality Gate:
 
-Start with [START_CONTRIBUTING.md](START_CONTRIBUTING.md), then read [CONTRIBUTING.md](CONTRIBUTING.md). Core AI task execution remains in [fsg-ai-core-assets](http://34.143.229.138/gitea-admin/fsg-ai-core-assets); source changes are reviewed as Pull Requests in this repository.
+```bash
+# Run all 4 quality gates (Clean Arch, Secrets, LOC, and Pytest Suite)
+python scripts/run_quality_gate.py
 
-Security concerns should follow [SECURITY.md](SECURITY.md). Ownership and completion rules are documented under `docs/governance/`.
+# Run static and architectural guards only (fast check)
+python scripts/run_quality_gate.py --skip-tests
+```
+
+Individual guard scripts:
+- **Clean Architecture Import Guard**: `python scripts/check_imports.py`
+- **Secrets & Plaintext Audit**: `python scripts/audit_security.py`
+- **Single Responsibility LOC Guard**: `python scripts/check_loc.py --max-lines 400`
+- **Release E2E Smoke Test**: `pytest tests/e2e/test_smoke.py -v`
+
+---
+
+## 🤝 Contributing & Recipes
+
+- **Quick Start Guide**: See [START_CONTRIBUTING.md](START_CONTRIBUTING.md).
+- **Contributor Recipes**: See [docs/governance/contributor-recipes.md](docs/governance/contributor-recipes.md) for step-by-step recipes to:
+  1. Add a new AI Model Provider.
+  2. Add a new Built-in Tool / MCP Server.
+  3. Add a new Screen / Tab / Widget.
+- **Security Policy**: See [SECURITY.md](SECURITY.md).