VI EN

## 📋 Kiểm tra trước khi cài

Trước khi bắt đầu, bạn cần 3 thứ sau:

- ✅ Claude Code CLI hoặc IDE extension đã cài + login (verify: gõ `claude --version` trong terminal hoặc thấy icon Claude trong VS Code/JetBrains)
- ✅ Bash shell:
  - Linux/macOS: có sẵn (terminal default)
  - Windows: cài Git for Windows (bao gồm Git Bash) hoặc enable WSL
- ✅ Git (verify: `git --version`)
- ⚪ Optional: Python ≥ 3.9 (chỉ cần khi dùng `scripts/validate.py` + trace tools)

Nếu KHÔNG có Bash trên Windows → xem phần Khi gặp lỗi thường gặp phần "Windows native (không Bash)".

## 📥 Cách dễ nhất: Cài one-command từ latest release

Bạn chỉ cần 1 lệnh để tải + giải nén + cài tự động từ bản phát hành mới nhất trên GitHub.

Linux / macOS one-liner

    curl -fsSL https://github.com/philngt/contextd/releases/latest/download/install.sh | sh

Windows PowerShell one-liner

    iwr https://github.com/philngt/contextd/releases/latest/download/install.ps1 -UseBasicParsing | iex

Các URL này luôn trỏ tới installer mới nhất đã publish.

Hoặc tải zip thủ công nếu cần, rồi chạy installer như cũ.

⬇️ Download contextd-latest.zip

Link này hoạt động khi bạn mở file trên máy hoặc host thư mục có chứa `release/`.

1

#### Giải nén zip

Giải nén vào thư mục tuỳ ý — vd `~/wiki` trên Linux/macOS hoặc `D:\tool\wiki-template` trên Windows.

    mkdir -p ~/wiki && unzip contextd-latest.zip -d ~/wiki
    # Zip chứa folder gốc 'wiki-template' → unzip sẽ tạo ~/wiki/wiki-template/
    cd ~/wiki/wiki-template

    # PowerShell
    Expand-Archive -Path contextd-latest.zip -DestinationPath D:\tool
    # Tạo D:\tool\wiki-template\
    cd D:\tool\wiki-template

    # Hoặc Git Bash
    unzip contextd-latest.zip -d /d/tool

Hoặc click chuột phải file zip → "Extract All..." trong File Explorer.

2

#### Chạy trình cài đặt

Giống Step 2 cách Git clone — file `scripts/install-to-claude.sh` đã có trong zip:

    bash scripts/install-to-claude.sh

Verify giống cách Git: `cat ~/.claude/wiki-global.json` phải thấy `"wiki_root"` đúng path bạn vừa extract.

3

#### Setup codebase

Giống Step 3 bên dưới — gõ `/contextd-setup` trong codebase.

⚠️ Cập nhật sau này: phải download zip mới mỗi lần update — KHÔNG có `git pull`. Khuyên dùng dùng cách Git clone nếu bạn sẽ update thường xuyên.
💡 Cho quản trị: tạo zip mới bằng `bash scripts/package-release.sh`. Output ghi vào `release/wiki-template-{version}.zip` + `release/contextd-latest.zip`. Auto-exclude `.git/`, evidence raw, workspaces khác `wiki/`, runs/cache/log files. Xem `scripts/package-release.sh --help`.

## 🔧 Cách ổn định cho người dùng kỹ thuật: Git clone

Nếu bạn có Git và muốn cập nhật dễ hơn về sau, dùng cách này.

1

## Tải repo về máy

Chọn 1 thư mục gốc tuỳ ý — vd `~/wiki` trên Linux/macOS hoặc `D:\tool\wiki-template` trên Windows.

    git clone https://github.com/philngt/contextd ~/contextd
    cd ~/contextd

    git clone https://github.com/philngt/contextd /d/tool/contextd
    cd /d/tool/contextd

Trong Git Bash, Windows path `D:\tool\` viết là `/d/tool/` (forward slash).

Repo này KHÔNG cần build, KHÔNG cần install dependency — chỉ là markdown + bash scripts.

2

## Chạy trình cài đặt

Chạy 1 lệnh sau (có thể chạy lại nhiều lần, vẫn an toàn):

    bash scripts/install-to-claude.sh

Lệnh này sẽ tự làm 3 việc:

- Sync slash commands + subagents vào `~/.claude/commands/` và `~/.claude/agents/` — Claude Code tự đọc folder này
- Tạo `~/.claude/wiki-global.json` với `wiki_root` trỏ về repo bạn vừa clone
- An toàn khi chạy lại: chạy lại sau mỗi `git pull` để cập nhật slash mới

#### Kiểm tra cài đặt

Kiểm tra cấu hình đã đúng đường dẫn:

    cat ~/.claude/wiki-global.json

    # PowerShell
    type $env:USERPROFILE\.claude\wiki-global.json

    # Hoặc Git Bash
    cat ~/.claude/wiki-global.json

Phải thấy field `"wiki_root"` với absolute path đúng repo bạn vừa clone. Vd:

    {
      "wiki_root": "/home/user/wiki",
      "default_workspace": null,
      "obsidian": { ... }
    }

Mở Claude Code, gõ `/contextd-setup` → nếu slash command hiện ra trong autocomplete = OK.

3

## Kết nối vào dự án đầu tiên

Vào thư mục codebase bạn muốn dùng wiki, mở Claude Code (hoặc IDE extension) tại đó, gõ:

    /contextd-setup

Hệ thống sẽ hướng dẫn bạn từng bước:

- Tự nhận diện tên dự án + loại công nghệ từ `package.json` / `pom.xml` / `Cargo.toml` / ...
- Hỏi chọn workspace có sẵn — hoặc tạo workspace mới qua `/new-workspace {name}`
- Bước 4.5 (Manage packs): hiện checkbox UI cho mọi pack có sẵn; auto-detect và pre-tick theo stack
- Tạo `<codebase>/.claude/wiki.json` với cấu hình hoàn chỉnh + packs override per-codebase

💡 Mỗi dự án chỉ cần chạy 1 lần. Sau đó wiki tự work — bạn chỉ gõ slash command bình thường (`/use-contextd`, `/find`, `/tool-design`, ...).

Tiếp theo: mở index.html để chọn đường đi theo persona (PM / Engineer / Wiki Owner / Solo Builder).

## 🔧 Khi gặp lỗi thường gặp

### Windows không có Bash

Nếu bạn chưa có Git Bash hoặc WSL, làm thủ công 4 bước sau:

1. Copy `templates\wiki-global.json` → `%USERPROFILE%\.claude\wiki-global.json`
2. Mở file vừa copy bằng Notepad, sửa `"wiki_root"` thành absolute path tới repo. Nhớ dùng \\ thay cho \:

       {
         "wiki_root": "D:\\tool\\wiki-template",
         ...
       }

3. Copy folder `.claude\commands\` và `.claude\agents\` sang `%USERPROFILE%\.claude\`:

       xcopy /E /I /Y .claude\commands %USERPROFILE%\.claude\commands
       xcopy /E /I /Y .claude\agents %USERPROFILE%\.claude\agents

4. Verify: `type %USERPROFILE%\.claude\wiki-global.json`

Khuyên dùng: cài Git for Windows (free) để có Git Bash → installer chạy 1 lệnh đơn giản hơn nhiều.

### Lệnh không hiện trong Claude Code

- Check folder `~/.claude/commands/` có file `.md` không (vd `contextd-setup.md`)
- Restart Claude Code (CLI: gõ `/exit` rồi mở lại; IDE: reload window)
- Re-run installer: `bash scripts/install-to-claude.sh`
- Check log Claude Code có error nào không (CLI: stderr; IDE: Output panel)

### Lỗi `wiki_root not found` khi gõ slash

- Mở `~/.claude/wiki-global.json`, confirm `"wiki_root"` là absolute path (KHÔNG dùng `~`, KHÔNG dùng relative)
- Path phải tới folder gốc của repo wiki-template (folder chứa `CLAUDE.md`, `packs/`, `workspaces/`)
- Verify path tồn tại: `ls "$(jq -r .wiki_root ~/.claude/wiki-global.json)"`

### `/contextd-setup` báo "workspace not found"

- Chưa có workspace nào — chạy `/new-workspace {name}` trước (vd `/new-workspace acme-corp`)
- Hoặc list workspaces có sẵn: `/list-workspaces`

### Lỗi quyền khi chạy trình cài đặt

- Linux/macOS: `chmod +x scripts/install-to-claude.sh` rồi chạy lại
- Hoặc force bash: `bash scripts/install-to-claude.sh` (không cần executable bit)

## 🔄 Cập nhật sau này

Sau mỗi `git pull` trên repo wiki-template, re-run installer để sync slash commands mới:

    cd ~/wiki
    git pull
    bash scripts/install-to-claude.sh   # idempotent — cập nhật tất cả

💡 Khi nào cần cập nhật?

- Wiki-template repo có slash command mới (vd `/tool-design` mới ship)
- Có pack mới được thêm vào `packs/`
- Engine constraints / coding-rules update (validator rules mới)

Workspaces của bạn (`workspaces/{your-ws}/`) là dữ liệu — KHÔNG bị ảnh hưởng bởi update engine.

← Quay về Onboarding QUICKSTART.md (text) README.md GitHub Repository