Update CASAN usage guide

README.md

@@ -1,15 +1,17 @@
-# AI-SDLC Project
+# CASAN AI-SDLC
 
-AI-SDLC (AI Software Development Life Cycle) - Applying AI to the software development process.
+CASAN là governance harness cho AI Software Development Life Cycle. Harness có
+thể được cài một lần ở máy developer rồi adopt vào nhiều dự án hiện hữu mà không
+copy toàn bộ CASAN hoặc dựng lại project shell.
 
-> **Bắt đầu từ đây nếu bạn muốn dùng CASAN:**
+> **Bắt đầu nhanh:** xem [CASAN Quick Start](#casan-quick-start). Tài liệu chi
-> [Dùng CASAN để làm dự án — giải thích thực tế, dễ hiểu](docs/guides/CASAN_USING_FOR_REAL_PROJECTS_VI.md).
+> tiết: [cài đặt hybrid](docs/casan/CASAN_INSTALL_HYBRID.md),
-> [Tạo project shell production đa dự án](docs/guides/CASAN_PROJECT_SHELL_PRODUCTION.md).
+> [dùng CASAN cho dự án thực tế](docs/guides/CASAN_USING_FOR_REAL_PROJECTS_VI.md)
-> CASAN core không phụ thuộc Codex, VS Code hay Claude Code; các agent được mô tả
+> và [tạo project shell production](docs/guides/CASAN_PROJECT_SHELL_PRODUCTION.md).
-> dưới đây là flow demo/legacy có thể đặt phía sau CASAN governance.
 
 ## Table of Contents
 
+- [CASAN Quick Start](#casan-quick-start)
 - [Project Objectives](#project-objectives)
 - [Dùng CASAN cho dự án thực tế](docs/guides/CASAN_USING_FOR_REAL_PROJECTS_VI.md)
 - [CASAN Project Shell production](docs/guides/CASAN_PROJECT_SHELL_PRODUCTION.md)
@@ -26,15 +28,104 @@ AI-SDLC (AI Software Development Life Cycle) - Applying AI to the software devel
 - [AI-SDLC Usage Guide](#ai-sdlc-usage-guide)
 - [Directory Structure](#directory-structure)
   - [Directory Details](#directory-details)
-- [FPT Deliverable List for NES](#fpt-deliverable-list-for-nes)
+- [OKR Web Application — Quick Start](#okr-web-application--quick-start)
-  - [A. Development Deliverables](#a-development-deliverables)
-  - [B. Process Records (Required)](#b-process-records-required)
-  - [C. Process Design Document](#c-process-design-document)
-  - [D. Specification Files](#d-specification-files)
-  - [E. Review & Insights](#e-review--insights)
-  - [Optional Deliverables](#optional-deliverables)
-- [License](#license)
 
+## CASAN Quick Start
+
+### 1. Cài CASAN một lần trên máy developer
+
+Yêu cầu chung: Python 3. Trên macOS/Linux cần Bash; trên Windows cần PowerShell
+và Git for Windows (Git Bash).
+
+macOS/Linux, chạy từ checkout CASAN:
+
+```bash
+sh install.sh --level devkit
+# Nếu installer báo launcher chưa nằm trên PATH:
+export PATH="${CASAN_HOME:-$HOME/.casan}/bin:$PATH"
+casan version
+```
+
+Windows PowerShell, chạy từ checkout CASAN:
+
+```powershell
+pwsh .\install.ps1
+```
+
+Sau lần cài đầu tiên trên Windows, mở PowerShell mới rồi kiểm tra:
+
+```powershell
+casan version
+```
+
+Mặc định harness được cài tại `~/.casan` trên macOS/Linux và
+`%LOCALAPPDATA%\casan` trên Windows.
+
+### 2. Adopt CASAN vào dự án
+
+Chạy tại root của dự án cần bảo vệ:
+
+```bash
+cd <project-root>
+casan init
+```
+
+Trong terminal tương tác, `casan init` hiển thị menu cho phép chọn một hoặc
+nhiều integration:
+
+1. Claude Code
+2. Codex
+3. GitHub Copilot trong VS Code
+
+Có thể cấu hình không tương tác:
+
+```bash
+casan init --client claude
+casan init --client claude,codex
+casan init --client vscode-copilot --vscode-install yes
+casan init --client all
+```
+
+Mặc định production là `--mode enforce`. Chỉ dùng `--mode observe` cho giai
+đoạn pilot telemetry-only.
+
+`casan init` an toàn với dự án đã có project shell, agents, skills hoặc hooks:
+
+- Không sửa source code và không dựng lại vỏ dự án.
+- Merge idempotent vào `.claude/settings.json`, `.codex/hooks.json` và
+  `.vscode/extensions.json`.
+- Giữ nguyên cấu hình/hook của dự án; chạy lại không tạo hook CASAN trùng lặp.
+- Chỉ ghi bootstrap/config per-project; harness vẫn dùng bản global đã pin hash.
+
+Nếu ứng dụng tự gọi LLM API qua backend riêng, ngoài Claude Code/Codex/Copilot,
+luồng đó không tự động đi qua project hooks và cần adapter CASAN riêng.
+
+### 3. Hành vi chat theo client
+
+| Client đã enable | Prompt đi qua CASAN | Onboarding bắt buộc |
+|---|---|---|
+| Claude Code CLI/extension | Tự động với chat bình thường | Mở project ở trusted workspace |
+| Codex CLI/extension | Tự động với chat bình thường | Mở `/hooks`, review và trust đúng hook hash |
+| GitHub Copilot Chat | Chỉ khi gửi `@casan <prompt>` | Cài CASAN VSIX; built-in Copilot chat không bị global-intercept |
+
+Không cần chỉ định một “CASAN agent” khi chat bằng Claude Code hoặc Codex.
+GitHub Copilot là ngoại lệ: VS Code không cung cấp API cho extension intercept
+mọi built-in Copilot prompt, nên CASAN cung cấp route explicit `@casan`.
+
+### 4. Kiểm tra sau khi init
+
+```bash
+casan doctor
+casan verify-harness
+```
+
+Với Codex, `doctor` kiểm tra config/bootstrap/runtime nhưng bước trust vẫn phải
+thực hiện trong `/hooks`. Với Copilot, nếu máy chưa có `code` CLI, init trả về
+đường dẫn VSIX để cài bằng lệnh **Extensions: Install from VSIX...**.
+
+Khi nâng cấp global CASAN, chạy lại `casan init` trong project để cập nhật
+bootstrap và pin hash mới. Xem đầy đủ tùy chọn và troubleshooting tại
+[CASAN_INSTALL_HYBRID.md](docs/casan/CASAN_INSTALL_HYBRID.md).
 
 ## Project Objectives
 
@@ -56,7 +147,7 @@ Apply AI to the SDLC process to automate and optimize the creation of software p
 - `docs/technical_architecture.md` — Technical stack decisions and constraints
 - `apps/okr/domain/input/change-request/` — Change requests (e.g., `change-0406.md`)
 
-## Output for FLow 
+## Output for Flow
 
 | Output | Location | Description |
 |--------|----------|-------------|
@@ -188,11 +279,12 @@ The entire flow is orchestrated by **`casan.pipeline`**, which executes all step
 
 ## AI-SDLC Usage Guide
 
-1. **Prepare Input**: Place raw requirements in `apps/okr/domain/input/okr-requirement.md` and tech stack in `docs/technical_architecture.md`
+1. **Adopt governance**: Run `casan init`, select the IDE clients, complete any trust/VSIX onboarding, then run `casan doctor`
-2. **Configuration**: Set up the project constitution first, keep specifications focused on what and why, and only decide technical stack where the input explicitly requires it
+2. **Prepare Input**: Place raw requirements in `apps/okr/domain/input/okr-requirement.md` and tech stack in `docs/technical_architecture.md`
-3. **(One-time) Generate System SRS**: Run `casan.srs` to generate system-wide SRS → `docs/output/srs-systems/`
+3. **Configuration**: Set up the project constitution first, keep specifications focused on what and why, and only decide technical stack where the input explicitly requires it
-4. **Run AI Flow**: Invoke `casan.pipeline` to execute the full 13-step flow automatically, with strict TDD enforced across specification, planning, task generation, and implementation
+4. **(One-time) Generate System SRS**: Run `casan.srs` to generate system-wide SRS → `docs/output/srs-systems/`
-5. **Output**:
+5. **Run AI Flow**: Invoke `casan.pipeline` to execute the full 13-step flow automatically, with strict TDD enforced across specification, planning, task generation, and implementation
+6. **Output**:
    - `docs/output/ipa-docs/` — IPA design documents (SRS, BD, DD, Test Cases)
    - `docs/output/output_logs/` — AI agent execution logs
    - `docs/output/srs-systems/` — System-wide SRS (generated once)
@@ -337,8 +429,8 @@ The **OKR Web Application** is a full-stack web app for managing Objectives and
 ### Quick Start (Docker)
 
 ```bash
-# Clone the repository and navigate to project root
+# Navigate to the repository root
-cd AINative_OKR_Claude_GHCP
+cd <repo-root>
 
 # Build and start all services (MySQL + Backend + Frontend)
 docker compose up --build
@@ -376,7 +468,7 @@ Docker Compose will automatically:
 #### Backend
 
 ```bash
-cd backend
+cd apps/okr/backend
 
 # Install dependencies
 npm install
@@ -398,7 +490,7 @@ npm run start:dev
 #### Frontend
 
 ```bash
-cd frontend
+cd apps/okr/frontend
 
 # Install dependencies
 npm install