# Dùng CASAN local để làm dự án — hướng dẫn từng bước

Tài liệu này dành cho môi trường local hiện tại: macOS chạy Control Panel và model local, Docker chạy hạ tầng, máy Linux `thanhnv@192.168.1.5` là tài nguyên mở rộng khi cần. Production là một giai đoạn riêng.

## 1. Hiểu CASAN trong một phút

CASAN không phải là một model AI mới. CASAN là lớp điều phối và kiểm soát nằm giữa người dùng, model và công cụ.

```mermaid
flowchart LR
    U["Mục tiêu / câu hỏi"] --> H1["H1 Context"]
    H1 --> H2["H2 Local worker / tools"]
    H2 --> H3["H3 Cloud review / eval"]
    H3 --> H4["H4 Security"]
    H4 --> H5["H5 Governance + audit"]
    H5 --> H6["H6 Runtime + cost"]
    H6 --> H7["H7 Governed outcome"]
    H2 -. private first pass .-> L["Ollama local"]
    H3 -. independent review .-> C["Codex / Claude / cloud API"]
```

Control Panel hiện có bốn bề mặt chính:

| Màn hình | Dùng khi nào | Có ghi/sửa source code không? |
|---|---|---|
| **Ask CASAN** | Hỏi tài liệu, kiến trúc, bằng chứng, trạng thái hệ thống | Không; read-only |
| **Goal orchestrator** | Đưa một mục tiêu để local worker và cloud reviewer cùng lập lời giải | Không; tạo kết quả và audit, chưa tự sửa workspace |
| **Run observability** | Xem một input đã đi qua H1–H7 và dừng/cảnh báo ở đâu | Không |
| **Settings / Approvals** | Quản trị cấu hình và quyết định có kiểm soát | Chỉ các action đã đăng ký và đủ quyền |

Điểm quan trọng: bạn có thể dùng ba luồng trên hoàn toàn trong trình duyệt, không cần mở Codex, VS Code hay Claude Code. Tuy nhiên, phiên bản hiện tại chưa có “workspace executor” được cấp quyền tự tạo/sửa source code từ Goal orchestrator. Kết quả của Goal orchestrator là kế hoạch/lời giải đã được hai model kiểm tra. Bước ghi code vẫn phải đi qua một action có approval hoặc một coding agent bên ngoài.

## 2. Chuẩn bị một lần

Kiểm tra các thành phần sau:

```bash
docker version
docker compose version
codex --version
claude --version
curl -fsS http://localhost:20128/v1/models
```

Model local mặc định hiện dùng Ollama ở `host.docker.internal:11434`. OmniRoute có Dashboard tại `http://localhost:20128` và API base `http://localhost:20128/v1`.

Không ghi API key vào Git, file Markdown hay biến build frontend. API key chỉ nhập qua màn hình Model connections; backend mã hóa theo tenant trước khi lưu.

## 3. Khởi động toàn bộ local stack

Từ thư mục gốc repository:

```bash
packages/casan-harness/scripts/bash/local-full.sh start
packages/casan-harness/scripts/bash/local-full.sh status
packages/casan-harness/scripts/bash/local-full.sh verify
```

Các địa chỉ chính:

- Control Panel: `https://localhost:18443`
- Dashboard hạ tầng: `http://127.0.0.1:18080`
- MinIO Console: `http://127.0.0.1:19091`
- OmniRoute: `http://localhost:20128`

Local Control Panel dùng chứng chỉ self-signed. Lần đầu, mở URL bằng trình duyệt và chấp nhận chứng chỉ local thủ công. Không dùng cách bỏ qua cảnh báo chứng chỉ cho production.

Khi cần dừng:

```bash
packages/casan-harness/scripts/bash/local-full.sh stop
```

Lệnh `stop` xóa bridge token. Lần `start` tiếp theo sinh token mới.

## 4. Kết nối model

### 4.1 Tài khoản Codex hoặc Claude

1. Mở **Ask CASAN**.
2. Chọn **Manage model connections**.
3. Trong **Local account connector**, xem trạng thái Codex và Claude.
4. Nếu chưa đăng nhập, chọn **Login**. Browser login chính thức của CLI sẽ mở và redirect theo cơ chế của Codex/Claude.
5. Control Panel chỉ nhận trạng thái đã được làm sạch. Credential OAuth vẫn thuộc CLI trên Mac, không nằm trong browser hoặc container.

Goal orchestrator ưu tiên một tài khoản cloud đã đăng nhập. Nếu cả hai sẵn sàng, Claude được ưu tiên làm reviewer; nếu Claude chưa đăng nhập thì dùng Codex. Nếu account connector không sẵn sàng, hệ thống mới dùng cloud/gateway connection đã cấu hình.

### 4.2 Ollama local

Trong **Model connections**:

1. Chọn **Ollama Local**.
2. Endpoint local Docker: `http://host.docker.internal:11434`.
3. Chọn **Refresh** để tải danh sách model.
4. Đặt model mặc định, ví dụ `ornith:9b`.

### 4.3 OmniRoute hoặc cloud API key

Với OmniRoute:

- Endpoint: `http://host.docker.internal:20128/v1`
- Model được lấy từ `/models`.
- OmniRoute là fallback khi account connector không dùng được.

Với OpenAI/Anthropic API:

- Chỉ dùng endpoint chính thức được allowlist.
- API key được gửi thẳng tới backend qua HTTPS local và lưu mã hóa theo tenant.
- UI không đọc lại hoặc hiển thị key đã lưu.

## 5. Case 1 — Hỏi hệ thống mà không cần IDE

Mở **Ask CASAN**, chọn model và hỏi:

> Hạ tầng local hiện có những thành phần nào, phần nào chưa có bằng chứng chạy thật?

CASAN sẽ:

1. phân loại prompt;
2. chỉ đọc nguồn nằm trong allowlist;
3. chạy security scan input/output;
4. trả câu trả lời có source;
5. ghi audit và telemetry.

Sau khi có câu trả lời, chọn **Open live H1–H7 trace** để xem đường đi.

## 6. Case 2 — Chỉ đưa mục tiêu, local và cloud cùng giải quyết

Mở **Goal orchestrator** và nhập một mục tiêu, ví dụ:

> Lập kế hoạch đưa ứng dụng OKR hiện tại lên production, có rollback, theo dõi lỗi và tiêu chí nghiệm thu rõ ràng.

Luồng thực tế:

1. H1 kiểm tra hợp đồng mục tiêu và độ dài.
2. H4 quét mục tiêu trước khi đưa cho model.
3. Ollama local tạo phương án đầu tiên.
4. Output local được quét lại.
5. Codex/Claude account hoặc cloud connection phản biện và viết kết quả cuối.
6. Kết quả cuối được H4 quét lần nữa.
7. H5 tạo audit hash; H6 ghi runtime/token; H7 kết thúc.

Trạng thái có ý nghĩa như sau:

- `completed`: local và cloud đều đóng góp thành công;
- `degraded`: local thành công nhưng cloud/gateway không sẵn sàng; kết quả local được giữ lại và cảnh báo rõ;
- `failed`: security hoặc local worker không cho phép tiếp tục.

## 7. Case 3 — Tìm chính xác input bị dừng ở đâu

Có hai cách mở Trace Explorer:

- từ nút **Open live H1–H7 trace** sau câu trả lời;
- từ **Run observability**, chọn **Open H1–H7** ở một run.

Mỗi H có thể click để xem:

- trạng thái mới nhất;
- lý do pass/warning/blocked/error;
- thời gian;
- evidence an toàn như model, token, latency, hash và decision.

Trace không đưa raw prompt, API key hoặc credential vào evidence.

## 8. Thêm một app mới trong cùng workspace

Không cần di chuyển app OKR đang có. Với app độc lập, tạo domain pack riêng thay vì trộn yêu cầu vào `apps/okr`:

```text
apps/<app-slug>/
├── domain/
│   ├── input/          # yêu cầu nguồn
│   ├── corpus/         # tài liệu dùng làm evidence
│   └── golden-runs/    # case chuẩn để đánh giá
├── config/             # cấu hình riêng của app
├── src/                # code riêng nếu app dùng cấu trúc package
└── test/               # test riêng
```

Sau đó thêm project vào `packages/casan-harness/config/project-registry.json` với `domain_root` trỏ tới `apps/<app-slug>/domain`, rồi chạy:

```bash
packages/casan-harness/scripts/bash/verify-harness-reuse.sh
```

Không làm các việc sau:

- đặt yêu cầu app mới trong `apps/okr/domain/input`;
- dùng chung secret hoặc state giữa hai tenant/project;
- sửa gate H1–H7 chỉ để một app mới pass;
- copy toàn bộ harness vào app mới.

## 9. Khi nào cần máy Linux `192.168.1.5`

Giữ Control Panel và account connector trên Mac trong giai đoạn local. Dùng máy Linux khi cần:

- chạy model hoặc workload nặng;
- thử Docker/Kubernetes gần production hơn;
- chạy worker riêng trong LAN;
- kiểm tra backup/restore hoặc benchmark.

Không copy credential Codex/Claude từ Mac sang Linux. Với production, dùng API credential trong Vault/KMS hoặc workload identity, không dùng developer browser login.

## 10. Troubleshooting nhanh

### Control Panel không mở

```bash
packages/casan-harness/scripts/bash/local-full.sh status
docker compose -f docker-compose.control-panel.local.yml ps
docker logs --tail 100 output_casan5_refined-control-panel-api-1
```

### Codex/Claude không hiện đã login

```bash
codex login status
claude auth status --json
curl -fsS http://127.0.0.1:20130/healthz
```

Nếu CLI chưa login, thực hiện login từ Control Panel hoặc CLI chính thức. Không copy token vào cấu hình CASAN.

### Goal dừng ở `degraded`

Mở H3 trong Trace Explorer. Các nguyên nhân thường gặp:

- account CLI chưa login;
- account model bridge bận hoặc rate limited;
- OmniRoute/provider đang unavailable;
- cloud preflight chặn dữ liệu nhạy cảm.

Kết quả `degraded` không được trình bày như kết quả hai-model hoàn chỉnh.

### Trace cũ chỉ có một H

Đó là legacy trace được sinh trước khi event schema H1–H7 được thêm. Các chat/goal mới tự động có event chi tiết.

## 11. Checklist trước khi dùng hàng ngày

- [ ] `local-full.sh verify` pass.
- [ ] Ollama connected và có default model.
- [ ] Ít nhất Codex/Claude account hoặc một cloud connection sẵn sàng.
- [ ] Một Goal smoke có local worker và cloud reviewer đều `pass`.
- [ ] Trace của smoke đạt 7/7.
- [ ] Không có API key trong Git diff.
- [ ] Chưa dùng cấu hình local này như production.

## 12. Tài liệu chính thức về đăng nhập CLI

- [OpenAI Codex authentication](https://developers.openai.com/codex/auth)
- [Claude Code getting started and authentication](https://docs.anthropic.com/en/docs/claude-code/getting-started)
- [Claude Code CLI reference](https://docs.anthropic.com/en/docs/claude-code/cli-usage)