CASAN/docs/casan/CASAN_INSTALL_HYBRID.md

Cài CASAN production (managed hoặc vendored Core) — Plan-21

CASAN cài CLI/DevKit một lần vào máy ($CASAN_HOME). Mỗi project chạy casan init và chọn một runtime contract rõ ràng:

• managed (mặc định): Core nằm trong global install, project pin version/hash.
• vendored: Core production-only nằm tại .casan/runtime/casan-core, dành cho offline, air-gapped hoặc repository cần self-contained.

Capability level và runtime placement là hai khái niệm độc lập. Project mặc định dùng Level 1/Core dù global package phải là DevKit để có lệnh init.

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

# 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:

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

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

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) — 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ỳ

cd <dự-án-của-bạn>
casan init                       # project mới: interactive chọn runtime rồi client
# 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 init --runtime vendored --project offline-app --client claude,codex
casan level show                        # xem level đã cài + level project
casan level set 2                       # đổi level project (không cần init lại)

Project mới chạy trong terminal tương tác sẽ được hỏi vị trí Core trước: Managed (Recommended) hoặc Vendored, sau đó mới chọn client. Nhấn Enter dùng Managed và Claude+Codex. Nhập sai sẽ được hỏi lại thay vì kết thúc bằng payload khó đọc.

init và level show luôn in runtime mode/path. Project mới mặc định managed; chạy lại init giữ nguyên mode đã chọn và không hỏi lại runtime. Chuyển mode phải explicit:

casan init --runtime managed
casan init --runtime vendored

Áp dụng cho dự án ĐÃ có vỏ (agents/skills/hook sẵn): an toàn.

• Mặc định casan init áp dụng Level 1/core: governance config + hooks, không thêm .gitea workflow hoặc domain-pack. Level cài global vẫn phải là DevKit vì lệnh adoption nằm trong DevKit.
• 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 uninstall xóa workflow CASAN trong .gitea và các scaffold file còn nguyên checksum, sau đó prune thư mục rỗng. Workflow của project và scaffold file đã chỉnh sửa được giữ lại. Thêm --purge để xóa cả runtime evidence .specify/logs và .specify/state.

casan init luôn ghi config per-project:

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 Core managed/vendored, 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
.casan/runtime/casan-core/	Chỉ mode vendored: CLI + Core runtime production-only

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, dùng --non-interactive và khai báo rõ runtime/client:

casan init --non-interactive --level core --runtime managed \
  --mode enforce --client claude,codex

--non-interactive, --json hoặc môi trường không có TTY không bao giờ chờ input. Khi không truyền lựa chọn, mặc định là Managed và 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ụ:

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 resolve Core theo runtime mode rồi kiểm tra live hash so với version.lock trước khi chạy adapter. Codex gọi bootstrap bằng đường dẫn tương đối từ project root, không phụ thuộc git rev-parse; Git vẫn được khuyến nghị để có provenance, diff và rollback đáng tin cậy.

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:

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. Managed mode nâng cấp runtime ở $CASAN_HOME; vendored mode được nâng cấp có chủ đích bằng cách chạy lại casan init --runtime vendored từ release đã duyệt.

Capability theo client

Lựa chọn	Local surface được hỗ trợ	Bước trust/cài đặt bắt buộc
claude	Claude Code CLI, VS Code extension và JetBrains integration dùng chung project settings/hooks	Mở trusted project; hook chạy tự động
codex	Codex desktop app (Local), CLI và IDE extension (Local) 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>

Không gắn badge project-hook cho Codex Cloud/Web, Claude Desktop hoặc claude.ai. Các surface đó không chạy local project hook; muốn support phải có remote/managed integration riêng và một qualification suite riêng.

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:

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

Với Codex, doctor đọc trạng thái hiệu lực bằng API hooks/list của chính codex app-server. Nếu toàn bộ CASAN hook của project đang trusted, kết quả là READY và không yêu cầu Allow lại. Action /hooks chỉ xuất hiện khi hook thực sự untrusted/modified, bị tắt, hoặc máy hiện tại không thể xác minh trust state. Hash toàn file .codex/hooks.json trong init-manifest.json là checksum ownership phục vụ uninstall an toàn; nó không phải per-hook trusted_hash mà Codex dùng để quyết định trust.

Gỡ khỏi project

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. Nếu project dùng vendored mode, toàn bộ .casan/runtime/casan-core cũng bị xóa. 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:

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. Chọn runtime mode

	Vendored (casan init --runtime vendored)	Managed (casan init)
Repo	Tự chứa Core production-only	Nhẹ, chỉ config/lock/hooks
Nâng cấp	Explicit theo từng repo	Tập trung ở $CASAN_HOME
Bảo mật	Core local + pin/hash verify	Core global + pin/hash verify
CI/offline	Phù hợp air-gapped	Runner phải cài đúng CASAN release
Khuyến nghị	Khách hàng offline/regulated	Mặc định cho workstation và managed CI

Cả hai dùng đúng cùng production allowlist và lõi harness; không mode nào mang theo tests, legacy level5, internal runners hay Platform-only helpers.

5. Kiểm thử

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