optimize docs

docs/casan/CASAN_INSTALL_HYBRID.md

@@ -69,6 +69,9 @@ casan level set 2                       # đổi level project (không cần ini
   `init` nhiều lần không nhân đôi hook.
 - **Guardrail:** `init` **từ chối** khi target chính là một CASAN source hub (để
   không tự chặn agent đang phát triển CASAN); dùng `--force` nếu thực sự cần.
+- Project cũ có vendored `packages/casan-harness` **không bị xem là source hub**:
+  init tự migrate sang hybrid, giữ nguyên harness/CI/scripts cũ để tương thích và
+  không yêu cầu `--force`.
 
 `--level 3` (platform) chỉ áp base L2 + nhắc rằng platform là service deploy riêng;
 `--level 4` (enterprise) bị từ chối (chưa ship).
@@ -100,6 +103,33 @@ Bootstrap `.casan/casan-hook.py` tự đọc `config.json`; developer không cò
 source `.casan/agentic.env` trước khi mở IDE. Mỗi invocation kiểm tra live hash
 của harness global so với `version.lock` trước khi chạy adapter.
 
+### Project đã có `.claude`, `.github`, agents, skills hoặc CASAN vendored
+
+Chỉ cần commit/backup trạng thái hiện tại, cài CASAN global rồi chạy init tại
+project root, kể cả khi đường dẫn có khoảng trắng:
+
+```bash
+cd '/path/to/Basic Design (Screen&Report)_v2.7'
+casan init --project basic-design-v27 --client claude,codex,vscode-copilot
+casan doctor
+```
+
+Quy tắc migration:
+
+- `.claude/agents`, `.claude/skills`, `.claude/commands`, `.github/**` và
+  workflow hiện hữu không bị xóa hoặc ghi đè.
+- CASAN chỉ merge handler của mình vào `.claude/settings.json` và
+  `.codex/hooks.json`; cấu hình/hook không thuộc CASAN được giữ nguyên.
+- Nếu có CASAN vendored cũ, `packages/casan-harness`, `bin/casan-chat`, CI và
+  evidence cũ được giữ lại. Chỉ xóa chúng sau khi CI/scripts/domain smoke đã
+  chuyển sang harness global.
+- Block legacy nằm đúng giữa marker
+  `CASAN_PROMPT_ENFORCEMENT_START/END` được nâng cấp tự động.
+- Prose legacy nằm ngoài marker không bị sửa âm thầm; `init` và `doctor` liệt kê
+  file cần review. Đặc biệt phải bỏ tuyên bố cũ rằng Claude/Codex direct chat
+  luôn nằm ngoài CASAN, vì Plan-20 project hooks đã thay đổi hành vi đó.
+- Codex vẫn cần `/hooks` trust; Copilot built-in vẫn cần explicit `@casan`.
+
 Sau `init`, developer gõ prompt bình thường trong client — trace H1→H7 + H6 theo
 Plan-20. Repo chỉ có mấy file config nhỏ; nâng cấp harness làm ở `$CASAN_HOME`.