claudekit · kaitranntt · Jul 11, 2026 · Jul 11, 2026
diff --git a/src/content/docs-vi/cli/doctor.md b/src/content/docs-vi/cli/doctor.md
@@ -84,6 +84,18 @@ Xác thực cài đặt ClaudeKit:
 - **Phiên bản**: Phiên bản đã cài đặt là hiện tại
 - **Skills**: Cấu trúc thư mục skills chính xác
 
+### Kiểm Tra Chế Độ Cài Đặt
+
+Với Engineer global, `ck doctor` hiển thị preference đã lưu, Kỹ năng thông thường đã copy, trạng thái plugin Claude và trạng thái plugin Codex. Chỉ preference `plugin` rõ ràng mới duy trì plugin; preference bị thiếu, sai định dạng, `auto`, hoặc `legacy` đều có nghĩa là Kỹ năng thông thường.
+
+Nếu cả skill đã copy và `ck@claudekit` cùng hoạt động, trở lại chế độ mặc định bằng:
+
+```bash
+ck init -g --kit engineer --install-mode legacy
+```
+
+CLI chỉ xóa registration/cache plugin do ClaudeKit quản lý và giữ nguyên file người dùng hoặc skill đã chỉnh sửa.
+
 ### Kiểm Tra Xác Thực
 
 Xác thực xác thực GitHub:

diff --git a/src/content/docs-vi/cli/init.md b/src/content/docs-vi/cli/init.md
@@ -56,6 +56,7 @@ ck init [OPTIONS]
 | `--beta` | Bao gồm phiên bản beta trong lựa chọn | `false` |
 | `--refresh` | Buộc làm mới cache cho các bản phát hành | `false` |
 | `--global` / `-g` | Cài đặt vào thư mục người dùng (`~/.claude/`) | `false` (cục bộ) |
+| `--install-mode <mode>` | `plugin` để chủ động chọn plugin; `auto`/`legacy` dùng Kỹ năng thông thường | Kỹ năng thông thường |
 | `--yes` / `-y` | Chế độ không tương tác với giá trị mặc định | `false` |
 | `--fresh` | Xóa `.claude/` hiện có trước khi cài đặt | `false` |
 | `--exclude <pattern>` | Loại trừ tệp khớp với mẫu (có thể lặp lại) | Không có |
@@ -140,6 +141,32 @@ Chế độ toàn cục hữu ích cho:
 - Sử dụng lệnh ClaudeKit ở mọi nơi
 - Quản lý skill tập trung
 
+### Chế Độ Cài Đặt Engineer
+
+- **Kỹ năng thông thường (khuyến nghị)**: copy vào `~/.claude/skills/`.
+- **Plugin Claude và Codex (nâng cao)**: chỉ bật khi người dùng chủ động chọn và được giữ lại cho các lần cập nhật sau.
+
+```bash
+# Mặc định/khuyến nghị
+ck init -g --kit engineer
+
+# Chủ động chọn plugin
+ck init -g --kit engineer --install-mode plugin
+
+# Trở lại Kỹ năng thông thường
+ck init -g --kit engineer --install-mode legacy
+```
+
+Cài mới có tương tác sẽ giải thích hai lựa chọn. `ck init --yes` và các lần chạy không tương tác chọn Kỹ năng thông thường nếu không truyền rõ `--install-mode plugin`. Các giá trị tương thích `auto` và `legacy` cũng chọn Kỹ năng thông thường.
+
+Chỉ preference `plugin` đã lưu mới được duy trì. Preference bị thiếu, sai định dạng, `auto`, hoặc `legacy` đều hội tụ về Kỹ năng thông thường. Khi chuyển về chế độ này, CLI chỉ xóa trạng thái plugin do ClaudeKit quản lý và giữ nguyên file người dùng hoặc skill đã chỉnh sửa.
+
+Chế độ thông thường không cài plugin Codex. Đồng bộ skill sang Codex bằng:
+
+```bash
+ck migrate --agent codex
+```
+
 ### Cài Đặt Mới Hoàn Toàn
 
 Xóa tất cả tệp ClaudeKit hiện có và cài đặt lại:

diff --git a/src/content/docs-vi/cli/update.md b/src/content/docs-vi/cli/update.md
@@ -42,6 +42,10 @@ Lệnh `ck update`:
 5. Thực thi lệnh cập nhật của trình quản lý gói
 6. Xác minh cài đặt
 
+Với Engineer global, bước `ck init` tiếp theo chỉ duy trì plugin khi metadata ghi nhận lựa chọn `plugin` rõ ràng. Preference bị thiếu, sai định dạng, `auto`, hoặc `legacy` đều hội tụ về Kỹ năng thông thường trong `~/.claude/skills/`.
+
+Dùng `ck init -g --kit engineer --install-mode plugin` để chủ động chọn plugin, hoặc `--install-mode legacy` để trở lại Kỹ năng thông thường. Quá trình chuyển đổi chỉ dọn trạng thái do ClaudeKit quản lý và không xóa file người dùng hoặc skill đã chỉnh sửa.
+
 ## Cú Pháp
 
 ```bash

diff --git a/src/content/docs-vi/getting-started/installation.md b/src/content/docs-vi/getting-started/installation.md
@@ -170,6 +170,23 @@ ck init -g --kit engineer --version v1.0.0
 
 > ✅ **Mẹo:** Chế độ global lý tưởng cho phát triển cá nhân. Cài đặt một lần, sử dụng mọi nơi.
 
+#### Chế Độ Cài Đặt Engineer
+
+**Kỹ năng thông thường (Normal skills) là lựa chọn mặc định và được khuyến nghị.** Các skill được copy vào `~/.claude/skills/`. Ở lần cài mới có tương tác, CLI cho phép chọn Kỹ năng thông thường hoặc plugin nâng cao; chế độ không tương tác luôn chọn Kỹ năng thông thường nếu bạn không truyền `--install-mode plugin`.
+
+```bash
+# Mặc định/khuyến nghị
+ck init -g --kit engineer
+
+# Chủ động chọn plugin nâng cao
+ck init -g --kit engineer --install-mode plugin
+
+# Trở lại Kỹ năng thông thường
+ck init -g --kit engineer --install-mode legacy
+```
+
+Chỉ lựa chọn `plugin` được lưu rõ ràng mới duy trì plugin trong các lần cập nhật sau. Preference bị thiếu, sai định dạng, `auto`, hoặc `legacy` đều hội tụ về Kỹ năng thông thường. Để đồng bộ skill thông thường sang đường dẫn native của Codex, chạy `ck migrate --agent codex`.
+
 ---
 
 ### Lựa Chọn B: Cài Đặt Local (Project-Specific)

diff --git a/src/content/docs/cli/doctor.md b/src/content/docs/cli/doctor.md
@@ -82,7 +82,7 @@ Validates ClaudeKit installation:
 - **Metadata**: Installation metadata is valid
 - **Version**: Installed version is current
 - **Skills**: Skills directory structure is correct
-- **Install mode**: Global Engineer preference, Claude plugin state, legacy copied files, and Codex plugin state
+- **Install mode**: Global Engineer preference, Normal copied skills, Claude plugin state, and Codex plugin state
 
 ### Auth Checks
 
@@ -311,18 +311,18 @@ For global Engineer installs, `ck doctor` reports the persisted install mode pre
 
 - `preference: auto|plugin|legacy`
 - Claude plugin registration and enabled/disabled status
-- Legacy copied skill state
+- Normal copied skill state
 - Codex plugin state, including missing, disabled, stale version, or stale source
 
-If both copied CK skills and the `ck@claudekit` plugin are active, run:
+If both copied CK skills and the `ck@claudekit` plugin are active, return to the recommended Normal skills mode with:
 
 ```bash
-ck init -g --kit engineer --install-mode auto
+ck init -g --kit engineer --install-mode legacy
 ```
 
-Use `--install-mode legacy` if you intentionally want copied skills and no owned plugin state.
+Only an explicit persisted `plugin` preference preserves plugin mode. Missing, malformed, `auto`, and `legacy` preferences resolve to Normal skills. Doctor cleanup removes CK-owned plugin registration/cache state without deleting user-created or modified skill files.
 
-For the full migration checklist, see [Engineer Kit Plugin Migration](/docs/engineer/configuration/plugin-migration).
+For the full mode and transition checklist, see [Engineer Kit Install Modes](/docs/engineer/configuration/plugin-migration).
 
 Issues that require manual intervention:
 

diff --git a/src/content/docs/cli/init.md b/src/content/docs/cli/init.md
@@ -55,7 +55,7 @@ ck init [OPTIONS]
 | `--beta` | Include beta versions in selection | `false` |
 | `--refresh` | Force cache refresh for releases | `false` |
 | `--global` / `-g` | Install to user directory (`~/.claude/`) | `false` (local) |
-| `--install-mode <mode>` | Global Engineer install mode: `auto`, `plugin`, or `legacy` | `auto` |
+| `--install-mode <mode>` | Global Engineer mode: `plugin` opts in; `auto`/`legacy` use Normal skills | Normal skills |
 | `--yes` / `-y` | Non-interactive mode with defaults | `false` |
 | `--fresh` | Create a recovery backup, remove CK-managed files, then reinstall | `false` |
 | `--exclude <pattern>` | Exclude files matching pattern (repeatable) | None |
@@ -142,17 +142,31 @@ Global mode is useful for:
 
 ### Engineer Install Mode
 
-Global Engineer installs can run as Claude/Codex plugins or as copied legacy files:
+Global Engineer installs offer two user-facing choices:
+
+- **Normal skills (recommended)** — copy skills to `~/.claude/skills/`.
+- **Claude and Codex plugins (advanced opt-in)** — register runtime plugins and preserve that explicit preference for later updates.
 
 ```bash
-ck init -g --kit engineer --install-mode auto
+# Recommended/default
+ck init -g --kit engineer
+
+# Advanced explicit opt-in
 ck init -g --kit engineer --install-mode plugin
+
+# Return an opted-in installation to Normal skills
 ck init -g --kit engineer --install-mode legacy
 ```
 
-Use `auto` for normal installs. ClaudeKit prefers plugins when Claude Code or Codex supports them, keeps copied skills as fallback until plugin verification succeeds, and removes duplicate CK-owned legacy skill files after a verified migration.
+Fresh interactive installs explain both choices. `ck init --yes` and other non-interactive runs choose Normal skills unless `--install-mode plugin` is supplied. The compatibility inputs `auto` and `legacy` also resolve to Normal skills.
+
+Only a persisted explicit `plugin` choice keeps plugin mode on later `ck init` or `ck update` runs. Missing, malformed, `auto`, and `legacy` preferences converge to Normal skills. Switching back removes only ClaudeKit-owned plugin state after the copied install is ready; user files and modified skills are preserved.
 
-Use `plugin` when plugin verification should be required for supported runtimes. Use `legacy` when you want copied files in `~/.claude/` to remain the active install and owned plugin state removed.
+Normal mode does not install a Codex plugin. Sync skills to Codex's native directory with:
+
+```bash
+ck migrate --agent codex
+```
 
 ### Fresh Installation
 

diff --git a/src/content/docs/cli/update.md b/src/content/docs/cli/update.md
@@ -42,9 +42,9 @@ The `ck update` command:
 6. Verifies installation
 7. Offers or runs the matching `ck init` follow-up when installed kit content needs updating or self-healing
 
-For global Engineer installs, the follow-up init preserves your saved install mode preference. `legacy` stays legacy across version updates, while `auto` and `plugin` can self-heal missing, disabled, stale-version, or stale-source `ck@claudekit` plugin state.
+For global Engineer installs, the follow-up init preserves plugins only when metadata contains explicit `plugin` consent. Missing, malformed, `auto`, and `legacy` preferences converge to the recommended Normal skills installation in `~/.claude/skills/`.
 
-Existing Engineer users moving from copied skills to the plugin format can use `ck update` as the normal migration entry point. See [Engineer Kit Plugin Migration](/docs/engineer/configuration/plugin-migration).
+Use `ck init -g --kit engineer --install-mode plugin` to opt in to plugins, or `--install-mode legacy` to return to Normal skills. The transition removes only ClaudeKit-owned state and preserves user-created or modified files. See [Engineer Kit Install Modes](/docs/engineer/configuration/plugin-migration).
 
 ## Syntax
 

diff --git a/src/content/docs/engineer/configuration/plugin-migration.md b/src/content/docs/engineer/configuration/plugin-migration.md
@@ -1,114 +1,87 @@
 ---
-title: "Engineer Kit Plugin Migration"
-description: "Move Engineer Kit installs from legacy copied skills to the Claude Code plugin format"
+title: "Engineer Kit Install Modes"
+description: "Choose Normal copied skills or explicitly opt in to Claude and Codex plugins"
 section: engineer
 kit: engineer
 category: configuration
 order: 5
 published: true
 ---
 
-# Engineer Kit Plugin Migration
+# Engineer Kit Install Modes
 
-ClaudeKit Engineer now ships as a Claude Code plugin. This keeps `/ck:*` skills grouped under the `ck@claudekit` plugin, restores slash-menu descriptions, and gives the CLI one owned install surface to update.
+Global Engineer installs support two modes. **Normal skills are recommended and selected by default.** Plugin mode is an advanced option that requires explicit consent.
 
-## What You Need To Do
+## Normal Skills (Recommended)
 
-Run:
+Normal mode copies ClaudeKit skills to `~/.claude/skills/`, where Claude Code discovers them directly:
 
 ```bash
-ck update
+ck init -g --kit engineer
 ```
 
-For normal global Engineer installs, that is enough. The CLI updates itself, then offers or runs the matching `ck init` follow-up needed to migrate or self-heal the installed kit content.
+Fresh interactive installs show Normal skills first and explain both choices. Non-interactive installs, including `--yes`, select Normal skills unless `--install-mode plugin` is supplied.
 
-## How To Verify
-
-Open Claude Code and type:
-
-```text
-/ck:plan
-```
-
-The slash menu should show the `ck:plan` skill with its description. You can also check the plugin registration:
+The compatibility inputs `auto` and `legacy` also select Normal skills:
 
 ```bash
-claude plugin list
+ck init -g --kit engineer --install-mode auto
+ck init -g --kit engineer --install-mode legacy
 ```
 
-Look for `ck@claudekit` in the installed plugin list.
-
-## What Changed
-
-Older global installs copied ClaudeKit-managed skills directly into `~/.claude/skills/`. Current global Engineer installs use a Claude Code plugin registration instead. The CLI still preserves your preferences and custom files; the migration only changes how ClaudeKit-owned kit content is installed and updated.
-
-Local project installs continue to work through the project `.claude/` directory.
-
-## Troubleshooting
-
-### Slash Menu Still Shows No Hint
-
-Run the kit self-heal path:
+Normal mode does not install a Codex plugin. Sync the skills to Codex's native directory separately:
 
 ```bash
-ck init -g --kit engineer --install-mode auto
+ck migrate --agent codex
 ```
 
-Then restart Claude Code and try `/ck:plan` again.
+## Plugin Mode (Advanced Opt-In)
 
-### Doctor Reports Mixed State
-
-Mixed state means copied ClaudeKit skills and the `ck@claudekit` plugin are both visible. Run:
+Choose plugin mode explicitly when you want ClaudeKit to register supported Claude Code and Codex plugins:
 
 ```bash
-ck doctor
-ck init -g --kit engineer --install-mode auto
+ck init -g --kit engineer --install-mode plugin
 ```
 
-`ck init` prunes stale ClaudeKit-owned files and keeps user-owned custom skills intact.
+The CLI persists this explicit choice. Later `ck init` and `ck update` runs preserve plugin mode only while the saved preference is `plugin`. Missing, malformed, `auto`, and `legacy` preferences converge to Normal skills rather than inferring consent.
 
-### Plugin Disabled Or Missing
+## Return To Normal Skills
 
-Run:
+To leave plugin mode, run:
 
 ```bash
-ck doctor --fix
+ck init -g --kit engineer --install-mode legacy
 ```
 
-If the plugin is still missing after the fix pass, rerun:
+ClaudeKit installs the copied replacement, then removes CK-owned Claude and Codex plugin registration/cache state. Cleanup is limited to tracked ClaudeKit files; user-created and modified files are preserved.
 
-```bash
-ck init -g --kit engineer --install-mode plugin
-```
+Restart Claude Code after changing modes so its skill and plugin discovery state reloads.
 
-### Need A Temporary Rollback
+## Diagnose Mixed State
 
-Use legacy mode only when you intentionally need copied skills:
+If copied skills and `ck@claudekit` both appear active, run:
 
 ```bash
+ck doctor
 ck init -g --kit engineer --install-mode legacy
 ```
 
-Return to the plugin path with:
+Use explicit plugin mode instead only when that remains your intended choice:
 
 ```bash
-ck init -g --kit engineer --install-mode auto
+ck init -g --kit engineer --install-mode plugin
 ```
 
 ## FAQ
 
-### Can I Still Use `~/.claude/skills/`?
-
-Yes. Your own skills can still live there. ClaudeKit-managed `ck:*` skills are managed by the plugin in the default global install mode so updates can remove stale files cleanly.
-
 ### Does This Affect Project-Local Installs?
 
-Project-local installs still place kit content inside that project's `.claude/` directory. The plugin migration mainly affects global Engineer installs.
+No. This choice applies to global Engineer installs. Project-local installs continue to place kit content inside the project's `.claude/` directory.
 
 ### Do I Need To Delete Old Files Manually?
 
-No. Use `ck update` or `ck init -g --kit engineer --install-mode auto`. The CLI knows which ClaudeKit-owned legacy paths can be removed.
+No. Let `ck init` perform the transition. It knows which CK-owned paths are safe to remove and preserves unknown or modified files.
 
-### What If I Pinned Legacy Mode?
+### Why Does Metadata Say `legacy`?
 
-Legacy mode remains available for compatibility. If you previously chose `legacy`, the CLI preserves that preference until you opt into `auto` or `plugin`.
+`legacy` is the stored compatibility value for the user-facing Normal skills choice. It does not mean the installation is unsupported or deprecated.
diff --git a/src/content/docs/getting-started/installation.md b/src/content/docs/getting-started/installation.md
@@ -8,7 +8,7 @@ published: true
 ---
 # Installation
 
-ClaudeKit is installed via the **ClaudeKit CLI** (`ck`). The CLI downloads the kit you select from AgentKit releases and copies skills, agents, and configuration into your Claude Code environment.
+ClaudeKit is installed via the **ClaudeKit CLI** (`ck`). The CLI downloads the kit you select and copies skills, agents, and configuration into your Claude Code environment.
 
 ## Requirements
 
@@ -118,7 +118,7 @@ Then invoke skills with `/ck:` prefix:
 /ck:test
 ```
 
-> **Engineer Kit plugin install:** Current global Engineer installs use the Claude Code plugin format. Existing users can migrate with `ck update`; details are in the [Engineer Kit Plugin Migration guide](/docs/engineer/configuration/plugin-migration).
+> **Engineer install mode:** Normal copied skills in `~/.claude/skills/` are the recommended default. Fresh interactive installs let you choose Normal skills or the advanced plugin option; non-interactive installs choose Normal skills. Use `--install-mode plugin` only to opt in explicitly. See [Engineer Kit Install Modes](/docs/engineer/configuration/plugin-migration).
 
 Initialize project documentation (optional but recommended):
 
@@ -141,6 +141,12 @@ ls .claude/skills/      # Local
 claude --version
 ```
 
+To sync a Normal skills install to Codex's native skills directory, run:
+
+```bash
+ck migrate --agent codex
+```
+
 ## Update ClaudeKit
 
 Re-run `ck init` to pull the latest release:
@@ -225,6 +231,6 @@ If empty, re-run `ck init -g --kit engineer`.
 
 ## Next Steps
 
-- [AgentKit Architecture](/docs/getting-started/agentkit-overview) — Understand how kits, skills, and agents fit together
+- [ClaudeKit Concepts](/docs/getting-started/concepts) — Understand how kits, skills, and agents fit together
 - [Quick Start](/docs/getting-started/quick-start) — Build your first feature
 - [Skills Overview](/docs/engineer/skills) — Browse all available skills
diff --git a/src/content/docs/support/faq.md b/src/content/docs/support/faq.md
@@ -47,11 +47,11 @@ claudekit init
 - Works with your existing projects
 - Preserves your custom commands
 
-### Q: Do I need to do anything for the Engineer Kit plugin migration?
-**A:** Run `ck update`. For normal global Engineer installs, the CLI updates itself and guides the needed kit self-heal. See the [Engineer Kit Plugin Migration guide](/docs/engineer/configuration/plugin-migration).
+### Q: Are plugins required for the Engineer Kit?
+**A:** No. Normal copied skills in `~/.claude/skills/` are recommended and selected by default. Use `ck init -g --kit engineer --install-mode plugin` only when you explicitly want the advanced plugin mode. See [Engineer Kit Install Modes](/docs/engineer/configuration/plugin-migration).
 
 ### Q: Can I still use `~/.claude/skills/`?
-**A:** Yes. User-owned skills can still live there. ClaudeKit-managed `ck:*` skills are managed through the plugin by default so updates can cleanly remove stale files.
+**A:** Yes. It is the default global location for Normal Engineer skills, and user-owned skills can live there too. ClaudeKit preserves user-created or modified files during mode changes.
 
 ### Q: What are the system requirements?
 **A:**