# Cài CASAN kiểu tool (global install + `casan init`) — Plan-21

Mô hình **hybrid**: cài harness **một lần** vào máy (`$CASAN_HOME`), sau đó mỗi
dự án chỉ chạy `casan init` để ghi **config riêng của dự án** — harness KHÔNG bị
copy vào từng repo. Giống trải nghiệm codegraph.

## 1. Cài đặt (một lần cho mỗi máy)

```bash
# macOS / Linux
curl -fsSL https://<your-gitea>/admin/casan5/raw/branch/main/install.sh | sh

# Windows (PowerShell)
irm https://<your-gitea>/admin/casan5/raw/branch/main/install.ps1 | iex
```

Hoặc từ một checkout CASAN có sẵn:

```bash
sh install.sh                 # macOS/Linux
pwsh .\install.ps1            # Windows
```

Chọn **level đóng gói** để cài (theo `packaging/levels.json`):

```bash
sh install.sh --level core      # L1: harness + gates + CLI (casan run/gate/verify)
sh install.sh --level devkit    # L2 (mặc định): + adoption tooling (casan init, CI, domain-pack)
sh install.sh --level platform  # L3 preview: từ chối — là service, deploy riêng
sh install.sh --level enterprise# L4 future: từ chối (chưa ship)
```

Levels là cumulative (devkit ⊃ core). `casan init` là tính năng của **L2 (devkit)**;
cài `--level core` sẽ không có `casan init` (báo rõ ràng).

Installer sẽ:

- Copy harness vào `$CASAN_HOME/versions/<version>` (mặc định `~/.casan`,
  Windows: `%LOCALAPPDATA%\casan`) và trỏ `current` vào version đó.
- Ghi **hash toàn vẹn** của gate-code (`.harness-hash`) — mỏ neo cho pin+verify.
- Ghi level đã cài vào `.casan-level`.
- Tạo launcher `casan` (tự định vị install của chính nó) và đưa lên PATH
  (`~/.local/bin` hoặc `$CASAN_HOME/bin`).

Installer dùng allowlist `packaging/runtime-layout.json`. Runtime global không
chứa `tests/`, legacy `level5/`, internal test/CI runners, Platform dashboard/local
lab, source docs hay bản sao installer. Policy cần thiết đã được chuẩn hóa vào
`packages/casan-harness/config/`.

> Windows cần **Git for Windows (Git Bash)** để *chạy* harness (xem
> [CASAN_AGENTIC_CLIENTS_WINDOWS.md](CASAN_AGENTIC_CLIENTS_WINDOWS.md)) — không
> cần WSL2. Cả hai OS cần `python3`.

Biến môi trường hữu ích: `CASAN_HOME` (đổi nơi cài), `CASAN_SRC` (cài từ checkout
cục bộ), `CASAN_DIST_URL` (tải tarball), `CASAN_NO_PATH_LINK=1` (không tự thêm PATH).

## 2. Adopt vào một dự án bất kỳ

```bash
cd <dự-án-của-bạn>
casan init                       # interactive: chọn Claude, Codex, VS Code/Copilot
# hoặc chọn level áp dụng cho project:
casan init --level 1 --project my-app --client claude
casan init --level 2 --project my-app --client claude,codex
casan init --project my-app --client vscode-copilot --vscode-install yes
casan level show                        # xem level đã cài + level project
casan level set 2                       # đổi level project (không cần init lại)
```

**Áp dụng cho dự án ĐÃ có vỏ (agents/skills/hook sẵn):** an toàn.
- `init` **KHÔNG index/parse code, KHÔNG sửa source, KHÔNG dựng lại vỏ** — chỉ thêm config.
- Hook được **MERGE** idempotent vào `.claude/settings.json` / `.codex/hooks.json`
  hiện có (giữ nguyên hook/agents/skills/khóa khác của bạn), không ghi đè. Chạy
  `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).

`casan init` chỉ ghi **config per-project** (không copy harness):

| File | Vai trò |
|---|---|
| `.casan/config.json` | project id, enforcement/integration mode, clients |
| `.casan/version.lock` | **pin** harness version + hash gate-code |
| `.casan/agentic.env` | feature flags bridge Plan-20 |
| `.casan/casan-hook.py` | bootstrap stdlib: load config, resolve + verify harness global, dispatch adapter |
| `.specify/` | thư mục state runtime (logs/trace/admission) |
| `.claude/settings.json` | hook Claude Code (Plan-20) |
| `.codex/hooks.json` | hook Codex theo schema hiện hành; cần review/trust bằng `/hooks` |
| `.vscode/extensions.json` | recommendations cho IDE đã chọn |

Tham số `--client` có thể lặp hoặc comma-separated:
`claude`, `codex`, `vscode-copilot`, `all`, `none`. Khi chạy `casan init` trực
tiếp trong terminal, CLI hiển thị menu chọn. Trong automation không có TTY,
mặc định tương thích ngược là `claude,codex`.

Các command dành cho người vận hành (`init`, `doctor`, `verify-harness`,
`level show`, `uninstall`) mặc định in bản tóm tắt dễ đọc. Thêm `--json` sau
command để lấy payload đầy đủ cho automation, ví dụ:

```bash
casan init --client claude,codex --json
casan doctor --json
casan level show --json
```

`--mode observe|enforce` mặc định `enforce`; dùng `observe` chỉ cho pilot
telemetry-only. `--integration-mode` nhận
`project_hook|managed_hook|casan_owned`; `--target <dir>` mặc định là thư mục
hiện tại.

Bootstrap `.casan/casan-hook.py` tự đọc `config.json`; developer không còn phải
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`.

### Capability theo client

| Lựa chọn | Trải nghiệm | Bước trust/cài đặt bắt buộc |
|---|---|---|
| `claude` | Claude Code CLI và extension chính thức dùng project hooks | Mở trusted project; hook chạy tự động |
| `codex` | Codex CLI và IDE extension dùng `.codex/hooks.json` | Mở `/hooks`, review và trust đúng hook hash |
| `vscode-copilot` | GitHub Copilot Chat qua route **explicit `@casan`** | Cài VSIX do init tạo/cài; dùng `@casan <prompt>` |

GitHub Copilot Chat mặc định **không** có public API để CASAN intercept mọi
prompt. Chỉ route `@casan` là `casan_owned`; participant detection/built-in
Copilot không được quảng bá là certified.

Kiểm tra sau init:

```bash
casan doctor
casan doctor --client claude
casan doctor --client codex
casan doctor --client vscode-copilot
```

### Gỡ khỏi project

```bash
casan uninstall
```

Command này xóa CASAN project hooks, bootstrap và config nhưng giữ nguyên hook
người dùng, CI/domain files, `.casan-bak`, VS Code extension dùng chung và
`.specify` evidence. Dùng `--purge` nếu chủ động muốn xóa runtime logs/state;
dùng `--remove-vscode-extension` nếu chắc chắn không project nào khác trên máy
còn dùng route `@casan`.

## 3. Pin + Verify (giữ đảm bảo bảo mật khi harness ở ngoài repo)

Vì harness không nằm trong repo, dự án **pin** version + hash gate-code lúc
`init`. Kiểm tra bất cứ lúc nào:

```bash
casan verify-harness
```

- Khớp → hiển thị `Harness integrity verified` (rc 0); `--json` trả
  `"status": "ok"`.
- Harness global bị đổi/tamper so với pin → `HARNESS_INTEGRITY_DRIFT` (rc 3).

`verify-harness` **luôn tính lại hash từ file thật** (không tin hash cache), nên
sửa lén một gate script sẽ bị phát hiện. Nên chạy `verify-harness` trong CI trước
khi tin bất kỳ trace nào là certified.

> Bước làm mạnh tiếp theo (chưa bật mặc định): ký `.harness-hash` bằng khóa tổ
> chức để verify cả *chữ ký* chứ không chỉ nội dung — dùng hạ tầng ký của Plan-16.

## 4. So sánh với mô hình vendored cũ

| | Vendored (`devkit/install.sh`) | Hybrid (`casan init`) |
|---|---|---|
| Repo | Nặng (copy cả harness) | Nhẹ (chỉ config) |
| Nâng cấp | Mỗi repo tự drift | 1 chỗ (`$CASAN_HOME`) |
| Bảo mật | Gate commit + ký trong repo | Gate global + **pin+verify** trong repo |
| CI/offline | Tự chứa | Cần cài harness trên runner (hoặc verify pin) |

Cả hai vẫn dùng chung lõi harness + `casan-paths.sh` (tách `CASAN_HARNESS_ROOT`
= code, `CASAN_STATE_ROOT` = state trong repo, `CASAN_DOMAIN_ROOT` = dữ liệu dự
án). Chọn mô hình theo nhu cầu triển khai.

## 5. Kiểm thử

```bash
bash packages/casan-devkit/tests/hybrid-install-tests.sh
```