alp-code 0.9.0

package/skills/git/references/safety-protocols.md

@@ -0,0 +1,86 @@
+# Luật an toàn git
+
+## Quét secret
+
+```bash
+git diff --cached | grep -iE '(AKIA|api[_-]?key|token|password|secret|credential|private[_-]?key|mongodb://|postgres://|mysql://|redis://|-----BEGIN)'
+```
+
+| Nhóm | Mẫu | Ví dụ |
+|---|---|---|
+| API key | `api[_-]?key`, `apiKey` | `API_KEY=abc123` |
+| AWS | `AKIA[0-9A-Z]{16}` | `AKIAIOSFODNN7EXAMPLE` |
+| Token | `token`, `auth_token`, `jwt` | `AUTH_TOKEN=xyz` |
+| Mật khẩu | `password`, `passwd`, `pwd` | `DB_PASSWORD=…` |
+| Private key | `-----BEGIN PRIVATE KEY-----` | file PEM |
+| Chuỗi kết nối DB | `mongodb://`, `postgres://`, `mysql://` | có kèm credential |
+| OAuth | `client_secret`, `oauth_token` | `CLIENT_SECRET=…` |
+
+**File luôn phải cảnh báo:** `.env`, `.env.*` (trừ `.env.example`) · `*.key`, `*.pem`,
+`*.p12` · `credentials.json`, `secrets.json` · `config/private.*`
+
+### Khi phát hiện
+
+1. **Chặn commit ngay.**
+2. In dòng khớp: `git diff --cached | grep -B2 -A2 <mẫu>`
+3. Báo principal: thêm vào `.gitignore` hay chuyển sang biến môi trường.
+4. Đề xuất bỏ stage: `git reset HEAD <file>` — **hỏi trước khi chạy**.
+5. Nếu secret **đã từng được commit** thì xoá file là chưa đủ: nó nằm trong lịch sử. Nói
+   thẳng điều đó và khuyến nghị xoay khoá.
+
+## Hai đường dẫn không bao giờ được commit — riêng của alp-code
+
+| Đường dẫn | Vì sao |
+|---|---|
+| `memory/**` | trí nhớ là dữ liệu cục bộ từng máy. Đẩy lên remote là rò dữ liệu của principal |
+| `~/.alp/executions/**` | `settings.json`, `.acl-stamp`, `skills/` đều do `npm run build` sinh, chứa path tuyệt đối của máy này |
+
+Thấy chúng trong `git diff --cached` nghĩa là `.gitignore` hỏng. Báo principal, không tự
+`git rm` — xoá nhầm `memory/` là mất thật, không khôi phục từ remote được.
+
+## Bảo vệ nhánh
+
+**Không bao giờ force push lên:** `main`, `master`, `production`, `prod`, `release/*`.
+
+Force push trên nhánh feature: chỉ khi principal nói thẳng, và dùng `--force-with-lease`
+chứ không phải `-f`. `--force-with-lease` từ chối ghi đè khi remote có commit bạn chưa thấy.
+
+## So bằng remote, không so bằng local
+
+```
+✅ git diff origin/main...origin/feature
+❌ git diff main...HEAD          # dính cả thay đổi local chưa push
+```
+
+Trước khi merge, thử khô:
+
+```bash
+git merge --no-commit --no-ff origin/<nhánh> && git merge --abort
+```
+
+## Khôi phục
+
+| Việc | Lệnh | Mức nguy hiểm |
+|---|---|---|
+| bỏ commit cuối, giữ thay đổi đã stage | `git reset --soft HEAD~1` | an toàn |
+| bỏ commit cuối, giữ thay đổi chưa stage | `git reset HEAD~1` | an toàn |
+| huỷ merge đang dở | `git merge --abort` | an toàn |
+| bỏ thay đổi một file | `git checkout -- <file>` | **mất việc chưa lưu** |
+| bỏ toàn bộ thay đổi | `git reset --hard HEAD` | **mất việc chưa lưu** |
+
+Hai dòng cuối là **khó đảo ngược**: phải hỏi principal từng lần (HOUSE-RULES §1.2).
+`git reset --soft HEAD~1` chỉ áp dụng cho commit **chưa push** — đã push rồi thì việc sửa
+lịch sử ảnh hưởng người khác, hỏi trước.
+
+## Stash trong worktree
+
+alp-code dùng worktree, và **stash stack là dùng chung giữa mọi worktree**. `git stash pop`
+trần có thể lấy nhầm việc của phiên khác đang chạy song song.
+
+Cần cất việc tạm → tạo commit WIP. Buộc phải stash thì đặt tên và lấy lại theo SHA:
+
+```bash
+git stash push -u -m "<nhãn riêng>"
+git stash list --format='%H %gs'      # lấy SHA của đúng entry mình vừa tạo
+git stash apply <sha>                 # apply, KHÔNG pop
+```

package/skills/git/references/workflow-commit.md

@@ -0,0 +1,89 @@
+# Quy trình commit
+
+Tự chạy. Không có subagent nào để đẩy output sang.
+
+## 1. Stage và phân nhóm
+
+```bash
+git add -A && \
+echo "=== ĐÃ STAGE ===" && git diff --cached --stat && \
+echo "=== SECRET ===" && \
+git diff --cached | grep -c -iE '(api[_-]?key|token|password|secret|credential)' | awk '{print "SECRET:"$1}' && \
+echo "=== NHÓM ===" && \
+git diff --cached --name-only | awk -F'/' '{
+  if ($0 ~ /^memory\//) print "CẤM:"$0
+  else if ($0 ~ /^identity\/[^\/]+\/\.claude\//) print "CẤM:"$0
+  else if ($0 ~ /\.(md|txt)$/) print "docs:"$0
+  else if ($0 ~ /test|spec/) print "test:"$0
+  else if ($0 ~ /^(scripts|hooks)\//) print "code:"$0
+  else if ($0 ~ /package\.json|lock/) print "deps:"$0
+  else print "code:"$0
+}'
+```
+
+**SECRET > 0** → DỪNG, in các dòng khớp, chặn commit, báo principal.
+
+**Có dòng `CẤM:`** → `.gitignore` đang hỏng. Hai thứ này không bao giờ được vào commit:
+
+| Đường dẫn | Vì sao |
+|---|---|
+| `memory/**` | trí nhớ là dữ liệu cục bộ từng máy, không đi theo git |
+| `~/.alp/executions/**` | sản phẩm của `npm run build`, chứa path tuyệt đối của máy này |
+
+Báo principal. **Không tự `git rm`** — xoá nhầm trí nhớ là mất thật.
+
+## 2. Quyết định tách
+
+**Một commit:** cùng type và scope, ≤ 3 file, ≤ 50 dòng.
+
+**Nhiều commit:** trộn type/scope → tách theo nhóm, commit theo thứ tự này:
+
+| Thứ tự | Nhóm | Prefix |
+|---|---|---|
+| 1 | deps | `chore(deps): …` |
+| 2 | code | `feat|fix|refactor(scope): …` |
+| 3 | test | `test: …` |
+| 4 | docs | `docs: …` |
+
+Deps trước code vì code có thể phụ thuộc deps mới — commit ngược thứ tự thì có một commit
+ở giữa không build được.
+
+Scope trong alp-code lấy theo vùng thật: `agents`, `delegation`, `runtime`, `installer`,
+`hooks`, `skills`. Xem `git log --oneline -20` để theo scope đã dùng, đừng tự đặt scope mới.
+
+## 3. Commit
+
+Một commit:
+
+```bash
+git commit -m "type(scope): mô tả"
+```
+
+Nhiều commit — làm tuần tự, mỗi nhóm một lần:
+
+```bash
+git reset && git add <file…> && git commit -m "type(scope): mô tả"
+```
+
+`git reset` ở đây chỉ bỏ stage, **không** đụng working tree. Đừng nhầm với
+`git reset --hard`.
+
+## 4. Push
+
+```bash
+git push
+```
+
+**Chỉ push khi principal nói thẳng trong phiên này** — "push", "commit rồi push".
+Được duyệt lần trước không tính cho lần này (HOUSE-RULES §1.2).
+
+Không push lên `main`/`master`. Không `--force`.
+
+## Báo cáo
+
+```
+✓ staged: N file (+X/−Y dòng)
+✓ secret: sạch
+✓ commit: <hash> type(scope): mô tả
+✗ push: CHƯA — chờ principal duyệt
+```

package/skills/git/references/workflow-merge.md

@@ -0,0 +1,63 @@
+# Quy trình merge
+
+**Merge vào nhánh chính là hành động khó đảo ngược.** Phải được principal nói thẳng trong
+phiên này. Không tự merge, kể cả khi thấy "rõ ràng là xong rồi".
+
+Biến: `TO` = nhánh đích (mặc định `main`) · `FROM` = nhánh nguồn (mặc định nhánh hiện tại).
+
+## 1. Đồng bộ với remote
+
+```bash
+git fetch origin
+git checkout {TO}
+git pull origin {TO}
+```
+
+## 2. Thử khô trước
+
+```bash
+git merge --no-commit --no-ff origin/{FROM}
+git merge --abort
+```
+
+Biết trước có xung đột hay không **trước khi** bắt đầu merge thật. Đây là bước rẻ nhất
+trong cả quy trình và là bước hay bị bỏ nhất.
+
+## 3. Merge
+
+```bash
+git merge origin/{FROM} --no-ff -m "merge: {FROM} vào {TO}"
+```
+
+**Vì sao `origin/{FROM}` chứ không phải `{FROM}`:** để chắc chỉ merge thứ đã commit *và* đã
+push. Merge nhánh local có thể kéo theo WIP chưa ai thấy.
+
+## 4. Xung đột
+
+Có xung đột → **báo principal, không tự chọn bên**. Chọn sai bên trong một merge là mất
+code mà `git diff` sau đó không cho thấy.
+
+Principal quyết rồi thì:
+
+```bash
+git add <file đã giải quyết> && git commit
+```
+
+Không dùng `git add .` sau khi giải quyết xung đột — nó nuốt luôn file khác đang dở.
+
+## 5. Push
+
+Xem `workflow-push.md`. Vẫn cần duyệt riêng — duyệt merge không phải duyệt push.
+
+## Xử lý lỗi
+
+| Lỗi | Làm gì |
+|---|---|
+| xung đột | báo principal, không tự chọn bên |
+| không tìm thấy nhánh | kiểm tên, chắc là đã push lên remote chưa |
+| push bị từ chối | `git pull --rebase` — hỏi trước |
+
+## Worktree
+
+alp-code dùng worktree. Merge trong một worktree vẫn ảnh hưởng repo chung — nhánh là dùng
+chung, chỉ có working tree là riêng. Đừng nghĩ mình đang ở chỗ cô lập nên merge nào cũng an toàn.

package/skills/git/references/workflow-pr.md

@@ -0,0 +1,70 @@
+# Quy trình mở Pull Request
+
+Mở PR là **đưa việc ra ngoài** — cần principal duyệt như push (HOUSE-RULES §1.2).
+
+Biến: `BASE` = nhánh đích (mặc định `main`) · `HEAD` = nhánh nguồn (mặc định nhánh hiện tại).
+
+## Luật lõi: so bằng diff REMOTE
+
+PR dựng trên nhánh **trên remote**. Diff local có cả thứ chưa push, nên mô tả PR viết theo
+diff local sẽ kể những thay đổi mà người review không nhìn thấy.
+
+**Không dùng để soạn nội dung PR:** `git diff main...HEAD` · `git diff --cached` ·
+`git status`. Ba lệnh này đều so với working tree local.
+
+## 1. Đồng bộ và phân tích
+
+```bash
+git fetch origin && \
+BASE=${BASE:-main} && \
+HEAD=$(git rev-parse --abbrev-ref HEAD) && \
+echo "=== PR: $HEAD → $BASE ===" && \
+echo "=== COMMIT ===" && \
+git log origin/$BASE...origin/$HEAD --oneline && \
+echo "=== FILE ===" && \
+git diff origin/$BASE...origin/$HEAD --stat
+```
+
+Báo "nhánh chưa có trên remote" → push trước (cần duyệt), rồi chạy lại.
+
+Diff rỗng → dừng, báo principal "không có thay đổi nào để mở PR". Đừng mở PR rỗng.
+
+## 2. Soạn nội dung
+
+**Tiêu đề:** conventional commit, dưới 72 ký tự, tiếng Việt cho phần mô tả, **không** kèm
+số phiên bản.
+
+**Thân:** tóm tắt gạch đầu dòng + checklist kiểm chứng. Trả lời *vì sao*, không phải *làm
+gì* — diff đã nói làm gì.
+
+## 3. Tạo PR
+
+```bash
+gh pr create --base "$BASE" --head "$HEAD" --title "…" --body "$(cat <<'EOF'
+## Tóm tắt
+- …
+
+## Kiểm chứng
+- [ ] …
+
+## Câu hỏi còn mở
+- …
+EOF
+)"
+```
+
+Mở **draft PR** (`--draft`) khi việc chưa xong hẳn — rẻ hơn nhiều so với mở PR thật rồi
+phải đóng.
+
+## Xử lý lỗi
+
+| Lỗi | Làm gì |
+|---|---|
+| nhánh chưa có trên remote | push trước (xin duyệt), rồi chạy lại |
+| diff rỗng | dừng, báo principal |
+| push bị từ chối | `git pull --rebase` — hỏi trước |
+| `gh` chưa đăng nhập | `gh auth status`; báo principal, đừng tự đăng nhập |
+
+## Sau khi tạo
+
+Báo principal **URL của PR**. Không tự merge PR vừa mở — xem `workflow-merge.md`.

package/skills/git/references/workflow-push.md

@@ -0,0 +1,62 @@
+# Quy trình push
+
+**Push là hành động khó đảo ngược** — ra khỏi máy, người khác thấy ngay. Phải được
+principal duyệt **trong phiên này** (HOUSE-RULES §1.2). Không có "lần trước đã duyệt rồi".
+
+## 1. Kiểm tra trạng thái
+
+```bash
+git status && \
+git log origin/$(git rev-parse --abbrev-ref HEAD)..HEAD --oneline 2>/dev/null || echo "CHƯA_CÓ_UPSTREAM"
+```
+
+- Còn thay đổi chưa commit → báo principal, đề xuất commit trước.
+- `CHƯA_CÓ_UPSTREAM` → dùng `git push -u origin HEAD`.
+
+Đọc danh sách commit sắp push **trước khi push**. Push nhầm một commit chứa `memory/` là
+đẩy dữ liệu cục bộ của principal lên remote.
+
+## 2. Push
+
+```bash
+git push origin HEAD
+```
+
+**Không push lên `main`/`master`.** Nhánh chính chỉ principal đụng.
+
+## Xử lý lỗi
+
+| Lỗi | Nguyên nhân | Làm gì |
+|---|---|---|
+| `rejected - non-fast-forward` | remote có commit mới hơn | đề xuất `git pull --rebase` — **hỏi trước khi chạy**, rebase viết lại commit của bạn |
+| `no upstream branch` | nhánh chưa track | `git push -u origin HEAD` |
+| `Authentication failed` | sai credential | kiểm `gh auth status` hoặc SSH key — báo principal, đừng tự đổi cấu hình auth |
+| `Repository not found` | sai remote | kiểm `git remote -v` |
+| `Permission denied` | không có quyền ghi | báo principal |
+
+## Force push
+
+**Không bao giờ force push lên `main`/`master`/nhánh production.** Không có ngoại lệ.
+
+Trên nhánh feature, chỉ khi principal nói thẳng:
+
+```bash
+git push --force-with-lease origin HEAD
+```
+
+Dùng `--force-with-lease`, **không** dùng `-f` trần: `--force-with-lease` từ chối ghi đè
+nếu remote có commit bạn chưa thấy. `-f` thì ghi đè bất chấp — đó là cách xoá việc của
+người khác mà không ai biết.
+
+Cảnh báo principal trước: force push viết lại lịch sử, ai đang làm trên nhánh đó có thể mất
+việc.
+
+## Báo cáo
+
+```
+✓ pushed: N commit → origin/<nhánh>
+  - abc123 feat(acl): …
+  - def456 fix(hooks): …
+```
+
+Không push thì nói rõ chưa push và vì sao.

package/skills/gkg/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: gkg
+description: Điều hướng code theo ngữ nghĩa bằng GitLab Knowledge Graph — tìm định nghĩa, tìm mọi chỗ gọi, phân tích ảnh hưởng trước khi refactor. Kích hoạt khi ripgrep trả quá nhiều kết quả trùng tên hoặc khi cần chắc đã tìm hết call-site.
+---
+
+# gkg — tìm theo ngữ nghĩa, không theo chuỗi
+
+Công cụ **bổ sung** cho `rg`/`Grep`, không thay thế.
+
+Khi nào nó hơn `rg`: tên symbol trùng với từ thông thường, cùng tên ở nhiều module, hoặc
+câu hỏi là "sửa chỗ này thì vỡ những đâu" — `rg` trả chuỗi khớp, `gkg` trả quan hệ thật
+trong AST.
+
+Khi nào `rg` đủ và nhanh hơn: tên đủ hiếm, tìm trong một thư mục, tìm chuỗi trong config
+hay tài liệu. **Mặc định vẫn là `rg`** — `gkg` phải index trước, và index tốn thời gian.
+
+## Kiểm tra trước khi dùng
+
+```bash
+gkg --version
+```
+
+Chưa cài thì **báo lại, đừng tự cài**. Cài phần mềm là hành động khó đảo ngược
+(HOUSE-RULES §1.2). Cứ trả lời bằng `rg` và nói rõ trong báo cáo là chưa có `gkg`.
+
+Cài (chỉ khi đã được duyệt):
+
+```bash
+curl -fsSL https://gitlab.com/gitlab-org/rust/knowledge-graph/-/raw/main/install.sh | bash
+```
+
+## Quy trình
+
+```bash
+gkg index <đường dẫn workspace> --stats   # index — chỉ workspace trong loadout
+gkg server start                          # bật server để query
+# query qua HTTP API: http://localhost:27495
+gkg server stop                           # PHẢI dừng trước khi index lại
+```
+
+**Chỉ index workspace có trong `workspaces.read` của `compiled AgentDefinition`.** Index một repo ngoài
+danh sách là đọc thứ mình không được đọc, kể cả khi filesystem không chặn.
+
+Dữ liệu index nằm ở `~/.gkg/` — ngoài repo, nên nó sống qua nhiều phiên. Index lại khi code
+đã đổi nhiều, đừng index mỗi phiên.
+
+## Ba việc chính
+
+| Việc | Cách |
+|---|---|
+| Tìm định nghĩa | index → `server start` → query symbol |
+| Tìm mọi chỗ gọi | query `get_references` cho symbol đó |
+| Phân tích ảnh hưởng | `get_references` cho từng symbol sắp đổi, đọc hết call-site trước khi kết luận |
+
+Phân tích ảnh hưởng là chỗ skill này đáng giá nhất: ai đó sắp refactor và cần biết vỡ
+những đâu. Trả lời "tôi grep thấy 3 chỗ" khi thật ra có 11 chỗ gọi gián tiếp là kiểu sai
+đắt nhất mà một lượt truy xuất có thể gây ra.
+
+## Hỗ trợ ngôn ngữ — đọc kỹ trước khi tin kết quả
+
+| Ngôn ngữ | Tham chiếu chéo file |
+|---|---|
+| Ruby, Java, Kotlin | đầy đủ |
+| Python, TypeScript, JavaScript | **chưa xong** |
+
+Với TS/JS/Python, `gkg` **có thể bỏ sót** call-site chéo file. Dùng thì phải đối chiếu thêm
+bằng `rg`, và trong báo cáo phải ghi rõ là kết quả chưa chắc đầy đủ. Đây là beta công khai,
+không phải công cụ đã chín.
+
+## Ràng buộc
+
+- Phải `server stop` trước khi index lại.
+- Cần repo đã `git init`.
+- Chưa nối tham chiếu **giữa các repo**.
+- Loadout không cấp MCP thì dùng HTTP API qua `Bash`, không dùng MCP tool.
+
+## Tham chiếu
+
+| File | Nội dung |
+|---|---|
+| `references/cli-commands.md` | `gkg index`, `gkg server`, `gkg remove`, `gkg clean` |
+| `references/http-api.md` | REST endpoint để query |
+| `references/language-support.md` | chi tiết từng ngôn ngữ |
+
+## Báo cáo
+
+Kết luận ngắn, bằng chứng `path:line`, và **nói rõ phần chưa chắc**. Thêm một dòng: tìm bằng `gkg` hay bằng `rg`, vì độ tin cậy hai đường khác nhau.

package/skills/gkg/references/cli-commands.md

@@ -0,0 +1,92 @@
+# Lệnh CLI của gkg
+
+## `gkg index`
+
+Đưa repo vào knowledge graph.
+
+```bash
+gkg index                      # thư mục hiện tại
+gkg index /đường/dẫn           # đường dẫn cụ thể
+gkg index --stats              # kèm thống kê
+gkg index --stats stats.json   # ghi thống kê ra JSON
+gkg index -v                   # log chi tiết
+gkg index --threads 4          # số luồng (mặc định = số nhân CPU)
+```
+
+**Chỉ index workspace có trong `workspaces.read` của `compiled AgentDefinition`.** Index repo ngoài
+danh sách là đọc thứ mình không được đọc, kể cả khi filesystem không chặn.
+
+Tự nhận diện: đường dẫn là workspace (nhiều repo) hay một repo đơn.
+
+Dữ liệu ra: `~/.gkg/{workspace_hash}/{project_hash}/` — **ngoài repo**, nên nó sống qua
+nhiều phiên. Index lại khi code đã đổi nhiều, đừng index mỗi phiên.
+
+## `gkg server`
+
+```bash
+gkg server start          # mặc định http://localhost:27495
+gkg server start --register-mcp
+gkg server stop
+gkg server status
+```
+
+Cổng 27495 (`0x6b67` = "kg"). Bận thì tự rơi sang cổng khác — nên **luôn chạy
+`gkg server status`** để biết cổng thật trước khi gọi API.
+
+**Phải `gkg server stop` trước khi index lại.**
+
+`--register-mcp` chỉ có nghĩa khi loadout cấp MCP. Không có thì gọi HTTP API qua `Bash`.
+
+## `gkg remove`
+
+```bash
+gkg remove --workspace /đường/dẫn
+gkg remove --project /đường/dẫn --workspace-folder /workspace
+```
+
+Xoá dữ liệu đã index. **Khó đảo ngược** (index lại tốn thời gian) — báo lại trước, đừng
+tự dọn.
+
+## `gkg clean`
+
+```bash
+gkg clean --dry-run     # xem trước — CHẠY CÁI NÀY TRƯỚC
+gkg clean               # dọn thật
+```
+
+Luôn `--dry-run` trước. Xem nó định xoá gì rồi mới chạy thật.
+
+## Quy trình thường dùng
+
+**Lần đầu**
+
+```bash
+gkg index --stats
+gkg server start
+```
+
+**Index lại sau khi code đổi**
+
+```bash
+gkg server stop
+gkg index
+gkg server start
+```
+
+**Workspace nhiều repo** — index thư mục cha:
+
+```bash
+gkg index /đường/tới/workspace
+```
+
+## Xử lý sự cố
+
+| Vấn đề | Cách |
+|---|---|
+| tốn nhiều bộ nhớ | giảm `--threads` |
+| index chậm | tăng `--threads`, hoặc `-v` để xem nó đang làm gì |
+| xung đột cổng | `gkg server stop` trước |
+| dữ liệu cũ, kết quả lạ | `gkg clean --dry-run` rồi `gkg clean` |
+
+Chạy lâu bất thường hoặc lỗi lặp lại → **báo lại**, đừng ngồi thử đi thử lại. Giá trị của
+một lượt truy xuất nằm ở tốc độ; kẹt thì trả lời bằng `rg` và nói rõ `gkg` không dùng được.

package/skills/gkg/references/http-api.md

@@ -0,0 +1,99 @@
+# HTTP API của gkg
+
+Base URL: `http://localhost:27495` — nhưng **kiểm cổng thật trước** bằng
+`gkg server status`, vì cổng bận thì server tự rơi sang cổng khác.
+
+Loadout không cấp MCP thì gọi API bằng `curl` qua `Bash`.
+
+## Chỉ dùng endpoint ĐỌC
+
+| Loại | Endpoint | Dùng |
+|---|---|---|
+| **Đọc** | `GET /api/info`, `/api/workspace/list`, `/api/graph/*`, `/api/events` | tự do |
+| **Ghi / xoá** | `POST /api/workspace/index`, mọi `DELETE` | **không tự gọi** — báo lại |
+
+Đây là việc truy xuất, không phải quản trị dữ liệu index. Cần index lại thì dùng
+`gkg index` ở CLI (xem `cli-commands.md`), và chỉ với workspace có trong loadout.
+
+## Thông tin server
+
+```
+GET /api/info
+```
+
+Trả về cổng và phiên bản.
+
+## Workspace
+
+```
+GET /api/workspace/list
+```
+
+Liệt kê mọi workspace và project đã index. Chạy cái này trước khi query — nếu thứ bạn cần
+chưa được index thì mọi truy vấn sau đều trả rỗng, và rỗng dễ bị đọc nhầm thành "không có
+chỗ nào gọi".
+
+## Truy vấn đồ thị — phần dùng nhiều nhất
+
+**Tìm định nghĩa theo mẫu**
+
+```
+GET /api/graph/search?pattern=MyClass&project=/đường/dẫn
+```
+
+**Lấy node lân cận** — đi từ một định nghĩa ra các chỗ liên quan:
+
+```
+GET /api/graph/neighbors?node_id=xxx&project=/đường/dẫn
+```
+
+Đây là cặp dùng cho **phân tích ảnh hưởng**: `search` tìm symbol, `neighbors` cho biết
+những gì nối vào nó.
+
+**Dữ liệu đồ thị ban đầu**
+
+```
+GET /api/graph/initial?project=/đường/dẫn
+```
+
+**Thống kê**
+
+```
+GET /api/graph/stats?project=/đường/dẫn
+```
+
+Trả số file, số định nghĩa, số quan hệ. Dùng để kiểm nhanh xem index có đầy đủ không —
+số file lệch hẳn so với `git ls-files | wc -l` nghĩa là index thiếu.
+
+## Sự kiện thời gian thực
+
+```
+GET /api/events
+```
+
+Luồng Server-Sent Events: `gkg-connection` (trạng thái kết nối) · `gkg-event` (tiến độ
+index).
+
+Đây là luồng **không tự đóng**. Gọi bằng `curl` trong `Bash` sẽ treo phiên — thêm
+`--max-time` nếu buộc phải dùng.
+
+## Lỗi
+
+| Mã | Nghĩa |
+|---|---|
+| 200 | thành công |
+| 400 | request sai |
+| 404 | không tìm thấy |
+| 500 | lỗi server |
+
+```json
+{ "error": "…", "code": "ERROR_CODE" }
+```
+
+404 thường nghĩa là **project chưa được index**, không phải symbol không tồn tại. Kiểm
+`/api/workspace/list` trước khi kết luận.
+
+## CORS và xác thực
+
+Chấp nhận origin localhost, không cần xác thực khi chạy cục bộ. Server này **không có lớp
+bảo vệ nào** — đừng mở nó ra ngoài localhost.