docs: explain how to use CASAN for real projects

README.md

@@ -2,9 +2,15 @@
 
 AI-SDLC (AI Software Development Life Cycle) - Applying AI to the software development process.
 
+> **Bắt đầu từ đây nếu bạn muốn dùng CASAN:**
+> [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).
+> CASAN core không phụ thuộc Codex, VS Code hay Claude Code; các agent được mô tả
+> dưới đây là flow demo/legacy có thể đặt phía sau CASAN governance.
+
 ## Table of Contents
 
 - [Project Objectives](#project-objectives)
+- [Dùng CASAN cho dự án thực tế](docs/guides/CASAN_USING_FOR_REAL_PROJECTS_VI.md)
 - [Requirements](#requirements)
 - [Input for Flow](#input-for-flow)
 - [Output for FLow](#output-for-flow)
@@ -34,7 +40,9 @@ Apply AI to the SDLC process to automate and optimize the creation of software p
 
 ## Requirements
 - **Flow + Prompt + Template**: **Spec-Kit**
-- **AI Tool**: Using **Claude Code** as the main AI assistant
+- **AI Tool của flow demo/legacy**: **Claude Code** là assistant chính; CASAN
+  harness và Control Panel có thể chạy độc lập bằng browser/CLI/CI hoặc dùng model
+  local/OmniRoute.
 - **AI-SDLC**: AI-integrated SDLC process **Spec-Kit Modified** (Add IPA Gen + Review Loop + Orchestrator)
 - **IPA Template**: Following IPA (Information-technology Promotion Agency) template standards
 

docs/guides/CASAN_LOCAL_FULL_STACK.md

@@ -1,5 +1,9 @@
 # CASAN local full stack (macOS)
 
+> Nếu bạn chưa rõ CASAN được dùng thế nào trong một dự án thực tế, đọc
+> [Dùng CASAN để làm dự án](CASAN_USING_FOR_REAL_PROJECTS_VI.md) trước tài liệu
+> cài đặt này.
+
 This guide runs the entire currently implemented CASAN stack on one Mac. It is
 a local production-like lab, not a production compliance claim. The Linux
 server is deliberately not used in this phase.

docs/guides/CASAN_USING_FOR_REAL_PROJECTS_VI.md

@@ -0,0 +1,286 @@
+# Dùng CASAN để làm dự án — giải thích thực tế, dễ hiểu
+
+Tài liệu này trả lời thẳng ba câu hỏi:
+
+1. CASAN có phải là một IDE hay một coding agent thay Codex/Claude Code không?
+2. Có thể dùng CASAN mà không cần Codex, VS Code hoặc Claude Code không?
+3. Với một dự án cụ thể, người dùng phải thao tác như thế nào?
+
+## 1. Câu trả lời ngắn gọn
+
+**CASAN không phải IDE. CASAN là lớp điều phối và kiểm soát quá trình dùng AI để
+làm phần mềm.**
+
+- VS Code là nơi con người mở và sửa file.
+- Codex/Claude Code là coding agent có thể đọc, sửa và chạy code.
+- Model local/OpenAI/OmniRoute là bộ máy sinh nội dung.
+- CASAN quyết định model/agent được làm gì, quét input/output, yêu cầu approval,
+  chạy test, ghi audit, lưu evidence và chặn hành động không an toàn.
+
+Do đó:
+
+- **Không cần Codex hoặc Claude Code:** có thể chạy CASAN bằng browser, CLI và CI.
+- **Không cần VS Code:** có thể dùng terminal hoặc bất kỳ trình soạn thảo nào.
+- **Muốn browser tự xây trọn một dự án:** phiên bản hiện tại **chưa hoàn thành
+  bước này**. Chat mới sinh và chứng nhận `CODEGEN_DRAFT`; nó chưa được phép tự
+  ghi tùy ý vào source tree.
+
+Điểm cuối cùng là chủ ý bảo mật, không phải lỗi giao diện. “Model sinh được code”
+khác với “model được quyền thay đổi repository”. CASAN tách hai quyền này.
+
+## 2. Hình dung CASAN như một dây chuyền có kiểm soát
+
+![Luồng dùng CASAN cho dự án](assets/casan-project-usage-flow.svg)
+
+```mermaid
+flowchart LR
+  U["Người dùng mô tả yêu cầu"] --> I["Control Panel hoặc bin/casan"]
+  I --> R{"CASAN phân loại ý định"}
+  R --> M["Model local / OmniRoute tùy chọn"]
+  M --> D["Sinh câu trả lời hoặc bản nháp"]
+  D --> G{"H4 bảo mật + H5 audit + H3/test/loop gate"}
+  G -- "Không đạt" --> X["Chặn, sửa hoặc yêu cầu người duyệt"]
+  G -- "Đạt: chỉ đọc" --> E["Trả kết quả kèm evidence"]
+  G -- "Đạt: có ghi file" --> A{"Registered action + approval"}
+  A -- "Đã được cho phép" --> W["Ghi workspace, chạy test, tạo commit"]
+  A -- "Chưa có action" --> H["Giữ draft, chưa thay đổi dự án"]
+```
+
+Model chỉ là một công nhân trong dây chuyền. CASAN là cổng kiểm soát, nhật ký,
+người điều phối và bộ tiêu chí nghiệm thu.
+
+## 3. Những gì dùng được ngay hôm nay
+
+| Nhu cầu | Browser Control Panel | Terminal `bin/casan` | Trạng thái |
+|---|---:|---:|---|
+| Hỏi về trạng thái, plan, audit, evidence | Có | Có | Hoàn chỉnh |
+| Chọn agent, skill và model provider | Có | Có qua tham số/config | Có policy và audit |
+| Chạy bộ test đã đăng ký | Có | Có | Hoàn chỉnh |
+| Build/verify Evidence Pack | Có | Có | Hoàn chỉnh |
+| Sinh code draft qua model | Có | Có | Có, nhưng draft chưa tự apply |
+| Tự sửa bất kỳ file nào bằng chat | Không | Chỉ qua command/action được cho phép | Chưa mở tự do |
+| Tạo toàn bộ dự án từ chat rồi test/commit | Chưa | Có thể ghép thủ công bằng CLI | Project Builder chưa hoàn thành |
+| Chạy CI, CVE scan, SBOM, attestation | Xem evidence | CI thực hiện | Đã có pipeline |
+
+Ba agent hiện tại:
+
+| Agent | Dùng khi nào | Quyền |
+|---|---|---|
+| Evidence Reader | Hỏi đáp, đọc plan/evidence | Chỉ đọc |
+| Ops Operator | Chạy test, build pack, verify pack | Chỉ action đã đăng ký |
+| Codegen Draft | Yêu cầu sinh code | Tạo draft trong vùng state; không tự ghi source |
+
+## 4. Cách chạy hệ thống local mà không cần Codex/Claude Code
+
+Bạn chỉ cần Docker và browser. Terminal được dùng để bật dịch vụ một lần.
+
+```bash
+cd /Users/thanhnguyen/Documents/AI/HarnessHkt/Harness_Hakathon/Output_CASAN5_REFINED
+bash packages/casan-harness/scripts/bash/local-full.sh start
+bash packages/casan-harness/scripts/bash/local-full.sh status
+```
+
+Sau đó mở:
+
+- Control Panel: `https://localhost:18443`
+- Trang Chat: `https://localhost:18443/chat`
+- AgentOps dashboard: `http://localhost:18080`
+- OmniRoute dashboard: `http://localhost:20128`
+
+Local dùng chứng thư self-signed nên browser có thể yêu cầu xác nhận lần đầu. Mock
+OIDC đăng nhập local với quyền `org-admin` để thử nghiệm.
+
+Nếu UI chưa thấy selector Agent/Skill/Model mới, chạy lại `local-full.sh start` để
+rebuild image Control Panel từ source mới nhất.
+
+## 5. Case 1 — chỉ dùng browser để kiểm tra và vận hành dự án
+
+Đây là case đã chạy đầy đủ nhất.
+
+### Hỏi đáp trên evidence
+
+1. Mở `/chat`.
+2. Chọn Agent `Evidence Reader`.
+3. Chọn Skill `evidence-summary`.
+4. Chọn model:
+   - `local` để dùng Ornith/Ollama trên máy Mac;
+   - `omniroute` nếu key và gateway đã được truyền vào container.
+5. Hỏi: `Summarize the remaining production gaps and cite the evidence.`
+
+CASAN sẽ quét câu hỏi, lấy context trong whitelist, gọi model nếu provider sẵn
+sàng, quét câu trả lời và chỉ đánh dấu `certified` khi đạt gate.
+
+### Chạy một action an toàn
+
+1. Chọn Agent `Ops Operator`.
+2. Chọn Skill `registered-actions`.
+3. Gõ đúng một trigger đã đăng ký:
+   - `run tests`
+   - `build evidence pack`
+   - `verify evidence pack`
+
+Chat không biến câu chữ thành shell command tùy ý. Nó ánh xạ vào
+`operator-actions.yaml`, chạy `action-gate`, rồi mới thực thi command cố định.
+
+### Sinh code draft
+
+1. Chọn Agent `Codegen Draft`.
+2. Chọn Skill `sourcegen-draft`.
+3. Chọn provider `local` hoặc `omniroute`.
+4. Gõ: `Generate code for a small ticket SLA validation function.`
+
+Kết quả nằm trong vùng runtime dưới
+`.specify/logs/chat/codegen-artifacts/` (hoặc tenant state tương ứng). Draft đi
+qua artifact scan và loop certification, nhưng **không được tự chép vào source
+tree**.
+
+## 6. Case 2 — áp CASAN vào một repository đã có sẵn
+
+Ví dụ repository hiện có là `my-ticketing`.
+
+### Bước 1: cài harness vào repository
+
+Chạy từ CASAN source hub:
+
+```bash
+packages/casan-devkit/install.sh \
+  --target ../my-ticketing \
+  --project ticketing \
+  --domain "Ticketing"
+```
+
+Lệnh này thêm:
+
+```text
+my-ticketing/
+├── bin/casan
+├── packages/casan-harness/
+├── apps/ticketing/domain/
+└── .gitea/workflows/casan-ci.yml
+```
+
+Nó không bắt buộc repository phải dùng VS Code, Codex hoặc Claude Code.
+
+### Bước 2: khai báo domain của dự án
+
+Điền các file sau:
+
+- `input/requirement.md`: danh sách `FR-xx`.
+- `input/architecture.md`: kiến trúc và constraint.
+- `traceability-map.json`: FR nào được thực hiện bởi code/test nào.
+- `golden-runs/`: output chuẩn để phát hiện drift.
+- `corpus/`: dữ liệu benign và red-team riêng của domain.
+
+### Bước 3: chạy governance gate
+
+```bash
+cd ../my-ticketing
+CASAN_DOMAIN_ROOT=apps/ticketing/domain bin/casan gate
+bin/casan reuse
+```
+
+Kết quả đúng phải có `CI_GATE_SUMMARY ... FAIL=0` và, khi registry có ít nhất hai
+dự án active hợp lệ, `HARNESS_REUSE_VALID`.
+
+### Bước 4: bọc một command bằng CASAN
+
+Ví dụ chạy test mà vẫn đi qua security, governance, telemetry và output scan:
+
+```bash
+printf 'Run the ticketing test suite\n' > /tmp/casan-ticketing-input.txt
+bin/casan run \
+  /tmp/casan-ticketing-input.txt \
+  /tmp/casan-ticketing-result.txt \
+  test_ticketing -- npm test
+```
+
+CASAN không cần biết command được gõ từ Terminal, Jenkins, Gitea Actions hay một
+coding agent. Miễn command đi qua harness, evidence được ghi theo cùng contract.
+
+## 7. Case 3 — dự án Service Desk thật đã có trong repository này
+
+Đây là bằng chứng CASAN không chỉ dùng được cho OKR:
+
+```bash
+node --test apps/service-desk/test/ticket.test.mjs
+
+python3 packages/casan-harness/scripts/bash/traceability-matrix.py \
+  --requirements apps/service-desk/domain/input/service-desk-requirement.md \
+  --map apps/service-desk/domain/traceability-map.json \
+  --out /tmp/service-desk-traceability.json \
+  --gate
+
+bash packages/casan-harness/scripts/bash/verify-harness-reuse.sh
+```
+
+Service Desk có source/test riêng và Domain Pack riêng. Nó dùng chung đúng một
+harness version với OKR. Không có gate nào được copy riêng cho Service Desk.
+
+## 8. Case 4 — muốn model thực sự “xây dự án cho tôi”
+
+Mục tiêu mong muốn sẽ là:
+
+```text
+Browser Chat
+  → mô tả dự án
+  → chọn Project Builder + model + skill
+  → sinh nhiều file vào workspace tạm
+  → H4 scan từng file
+  → chạy build/test/H3 evaluation
+  → hiển thị diff
+  → con người approve
+  → apply vào repository
+  → commit + CI + evidence pack
+```
+
+**Luồng này chưa hoàn chỉnh trong bản hiện tại.** Những phần đã có là model
+router, agent/skill binding, RBAC, codegen draft, action gate, approval inbox,
+loop gate, tests, audit và evidence. Những phần còn thiếu để browser-only là:
+
+1. Workspace service quản lý nhiều file/diff.
+2. Skill `project-scaffold` và `apply-patch` được đăng ký rõ quyền.
+3. Action chạy build/test theo project, không phải command tự do.
+4. Approval để apply diff vào source tree.
+5. Git commit/revert gắn với provenance.
+6. Streaming token/delta và progress của từng bước build/test.
+
+Cho tới khi sáu phần này hoàn thành, cách dùng đúng là: **Chat tạo draft và
+evidence; con người hoặc một registered automation áp draft vào project.** Coding
+agent là tùy chọn, không phải dependency của CASAN.
+
+## 9. Cách dùng khuyến nghị cho môi trường hiện tại
+
+### Nếu bạn là người quản lý/kiểm soát
+
+Dùng browser Control Panel. Không cần IDE hay coding agent. Hỏi evidence, xem
+security/FinOps, duyệt proposal, chạy registered action và theo dõi audit.
+
+### Nếu bạn là developer nhưng không muốn dùng coding agent
+
+Dùng editor bất kỳ + `bin/casan gate` + `bin/casan run`. Bạn tự sửa code, CASAN
+kiểm soát quá trình và chứng minh kết quả.
+
+### Nếu bạn muốn AI hỗ trợ mạnh
+
+Dùng Chat với local/OmniRoute để sinh draft, sau đó review và apply. Có thể thay
+Chat bằng Codex/Claude Code nếu muốn; cả hai vẫn phải chạy command qua CASAN để
+giữ governance và evidence.
+
+### Nếu bạn muốn hoàn toàn browser-only
+
+Cần hoàn thiện Project Builder ở mục 8. Đây là một sản phẩm phía trên CASAN core,
+không phải chỉ thêm một prompt hoặc bật quyền ghi file cho model.
+
+## 10. Kết luận
+
+CASAN dùng độc lập được mà không cần Codex, VS Code hay Claude Code cho các chức
+năng governance, chat evidence, vận hành, test, CI và evidence pack. Nhưng bản
+hiện tại chưa phải một “AI IDE trên browser” có thể tự xây toàn bộ repository.
+
+Cách hiểu đúng nhất:
+
+> **Coding tool tạo thay đổi. CASAN quyết định thay đổi đó có được tin, được chạy,
+> được áp dụng và được phát hành hay không.**
+
+Mục tiêu Project Builder sẽ đưa luôn bước tạo thay đổi vào Control Panel, nhưng
+vẫn giữ nguyên nguyên tắc: model không có đường ghi file hoặc chạy command tự do.

docs/guides/assets/casan-project-usage-flow.mmd

@@ -0,0 +1,11 @@
+flowchart LR
+  U["Người dùng mô tả yêu cầu"] --> I["Control Panel hoặc bin/casan"]
+  I --> R{"CASAN phân loại ý định"}
+  R --> M["Model local / OmniRoute tùy chọn"]
+  M --> D["Sinh câu trả lời hoặc bản nháp"]
+  D --> G{"H4 bảo mật + H5 audit + H3/test/loop gate"}
+  G -- "Không đạt" --> X["Chặn, sửa hoặc yêu cầu người duyệt"]
+  G -- "Đạt: chỉ đọc" --> E["Trả kết quả kèm evidence"]
+  G -- "Đạt: có ghi file" --> A{"Registered action + approval"}
+  A -- "Đã được cho phép" --> W["Ghi workspace, chạy test, tạo commit"]
+  A -- "Chưa có action" --> H["Giữ draft, chưa thay đổi dự án"]