docs: document Engineer install modes

src/content/docs/cli/doctor.md

@@ -82,6 +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
 
 ### Auth Checks
 
@@ -304,6 +305,23 @@ Issues that can be automatically fixed:
 | Missing skill dependencies | Install packages in skill directories |
 | Invalid cache | Clear cache and refresh |
 
+### Install Mode Findings
+
+For global Engineer installs, `ck doctor` reports the persisted install mode preference and the live Claude/Codex state:
+
+- `preference: auto|plugin|legacy`
+- Claude plugin registration and enabled/disabled status
+- Legacy 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:
+
+```bash
+ck init -g --kit engineer --install-mode auto
+```
+
+Use `--install-mode legacy` if you intentionally want copied skills and no owned plugin state.
+
 Issues that require manual intervention:
 
 | Issue | Manual Fix |

src/content/docs/cli/init.md

@@ -55,6 +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` |
 | `--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 |
@@ -139,6 +140,20 @@ Global mode is useful for:
 - Using ClaudeKit commands everywhere
 - Centralized skill management
 
+### Engineer Install Mode
+
+Global Engineer installs can run as Claude/Codex plugins or as copied legacy files:
+
+```bash
+ck init -g --kit engineer --install-mode auto
+ck init -g --kit engineer --install-mode plugin
+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.
+
+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.
+
 ### Fresh Installation
 
 Create a recovery backup, remove existing ClaudeKit-managed files, and reinstall:

src/content/docs/cli/update.md

@@ -40,6 +40,9 @@ The `ck update` command:
 4. Prompts for confirmation (unless `--yes`)
 5. Executes package manager 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.
 
 ## Syntax