repo-harness 0.2.0 → 0.2.2

package/README.es.md

@@ -34,14 +34,23 @@ repo-local que él mismo genera para los proyectos downstream.
   1KB o consulta el índice, en vez de gastar miles de tokens redescubriendo la
   estructura.
 
-## Novedades en 0.2.0
+## Novedades en 0.2.1
 
-- **Script de instalación (`scripts/setup-plugins.sh`).** Un solo comando hace el
-  bootstrap completo del entorno global de Claude: essential plugins, policy
+- **Comando de inicialización global (`repo-harness init`).** Un solo comando
+  inicializa el entorno global de Claude: essential plugins, policy
   hooks configurables (worktree guard, atomic commit/pending), LSP plugins
   opcionales según el tipo de proyecto y cuatro hook profiles (`standard`,
   `minimal`, `biome`, `biome-strict`). Ejecuta
-  `bash scripts/setup-plugins.sh [--with-optional] [--hooks <profile>]`.
+  `npx -y repo-harness init`; no necesitas clonar el repositorio fuente.
+- **Comando de refresco del repo (`repo-harness update`).** La instalación y el
+  refresco de repos existentes tienen su propia superficie de comando, manteniendo
+  la ruta de migración repo-local anterior mientras `init` queda dedicado al
+  runtime global.
+- **Auto-recuperación del índice CodeGraph.** Si el prompt hook detecta intención
+  de navegación estructural y el repo no tiene índice `.codegraph`, inicializa el
+  índice con el binario CodeGraph local o visible en PATH antes de emitir la pista.
+  Sigue siendo advisory: no instala dependencias, no ejecuta el readiness probe
+  pesado y no bloquea el prompt si CodeGraph no está disponible.
 - **Centinela de seguridad (`repo-harness security scan` + `security-sentinel.sh`).**
   Una verificación de solo lectura sobre las superficies de inyección de
   configuración de alto valor (`~/.claude/settings.json`, `~/.codex/hooks.json`,
@@ -91,7 +100,7 @@ En conjunto hay tres capas:
 1. **Capa del paquete fuente**: este repositorio mantiene la CLI, los command
    skill facades, los templates, los hook assets, el workflow contract, los tests
    y el release gate.
-2. **Capa del contract del repositorio objetivo**: `repo-harness init` o la
+2. **Capa del contract del repositorio objetivo**: `repo-harness update` o la
    migración escribe `docs/spec.md`, `plans/`, `tasks/`, `.ai/context/`,
    `.ai/harness/`, helper scripts y `.ai/hooks/`.
 3. **Capa del host adapter**: el `~/.claude/settings.json` y el
@@ -178,14 +187,13 @@ npx -y repo-harness init
 ```
 
 La npm package release line es ahora `0.2.x`; el workflow compatibility model line
-generado se rastrea por separado como `5.x`. `repo-harness@0.2.0` añade el script
-global de instalación de plugin/hook (`scripts/setup-plugins.sh`), el centinela de
-seguridad de configuración de solo lectura (`repo-harness security scan`) y el
-ciclo de vida draft-plan explícito de Claude/Codex, sobre la CLI ya renombrada, el
-bootstrap del hook adapter a nivel de usuario, los AI-native scaffold overlays, el
-typed prompt-guard decision engine, el naming de task artifacts por plan-stem, los
-`REPO_HARNESS_*` runtime aliases, el sync de Waza runtime skills, y el release gate
-que usa el maintainer antes de publicar en npm.
+generado se rastrea por separado como `5.x`. `repo-harness@0.2.1` separa el
+bootstrap global inicial (`repo-harness init`) del refresco repo-local
+(`repo-harness update`), conserva el instalador global de plugin/hook
+(`scripts/setup-plugins.sh`), el centinela de seguridad de configuración de solo
+lectura (`repo-harness security scan`), el ciclo de vida draft-plan explícito de
+Claude/Codex y añade inicialización no bloqueante del índice CodeGraph para el
+routing estructural de prompts.
 
 Si trabajas desde un checkout del código fuente:
 
@@ -220,13 +228,13 @@ del runtime `project-initializer` ya retirado los limpia
 En un repositorio existente, ejecuta desde el repo root:
 
 ```bash
-npx -y repo-harness init --dry-run
+npx -y repo-harness update --dry-run
 ```
 
 Aplica solo después de que el reporte del dry-run sea correcto:
 
 ```bash
-npx -y repo-harness init
+npx -y repo-harness update
 ```
 
 Para un proyecto o módulo nuevo, usa el command skill `repo-harness-scaffold`. Para
@@ -263,6 +271,15 @@ Si la salida del dry-run no es correcta, detente aquí primero y lee
 - Codex debe confiar en `~/.codex/hooks.json` en sus Settings para que los hooks se ejecuten.
 - Orden de depuración: user-level adapter config -> `repo-harness-hook` o el fallback `repo-harness hook` -> route registry -> `.ai/hooks/*`.
 
+`SessionStart` ejecuta dos scripts ordenados antes de empezar el trabajo:
+
+```mermaid
+flowchart LR
+  SessionStart["Claude/Codex SessionStart"] --> Ctx["session-start-context.sh<br/>contexto de resume + handoff"]
+  Ctx --> Sec["security-sentinel.sh<br/>escaneo de configuración de solo lectura, fingerprint-gated"]
+  Sec --> SSOut["SessionStart additionalContext<br/>estado de la sesión anterior + hallazgos de SecurityConfig"]
+```
+
 El prompt guard tiene un paso interno adicional:
 
 ```mermaid
@@ -274,6 +291,7 @@ flowchart LR
   Shell --> Decision["repo-harness-hook prompt-guard-decide<br/>TypeScript decision table"]
   Decision --> Action["single action enum"]
   Action --> Shell
+  Shell --> RouteHint["Waza route hint<br/>think/planning explícito coincide primero → /think"]
   Shell --> HostOutput["host-safe allow, advice, block, or done gate output"]
 ```
 
@@ -310,7 +328,7 @@ Guards habituales:
 
 ## Release actual
 
-- npm package: `repo-harness@0.2.0`
+- npm package: `repo-harness@0.2.1`
 - Generated workflow compatibility: `5.2.3`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
@@ -325,7 +343,7 @@ Guards habituales:
   - `assets/workflow-contract.v1.json`
 - Los generated repos usan por defecto el repo-local harness flow:
   - `docs/spec.md -> plans/ -> tasks/contracts/ -> tasks/reviews/ -> .ai/context/context-map.json -> .ai/harness/*`
-- `repo-harness init` refresca las runtime pieces:
+- `repo-harness update` refresca las runtime pieces:
   - los `repo-harness` skill aliases
   - los global Codex/Claude hook adapters
   - las Waza skills: `check`, `design`, `health`, `hunt`, `learn`, `read`, `think`, `write`

package/README.fr.md

@@ -34,14 +34,24 @@ workflow repo-local qu'il génère lui-même pour les projets en aval.
   1 Ko ou interroge l'index, au lieu de dépenser des milliers de tokens à
   redécouvrir la structure.
 
-## Nouveautés de la 0.2.0
+## Nouveautés de la 0.2.1
 
-- **Script d'installation (`scripts/setup-plugins.sh`).** Une seule commande
-  effectue tout le bootstrap de l'environnement Claude global : essential plugins,
+- **Commande d'initialisation globale (`repo-harness init`).** Une seule commande
+  amorce l'environnement Claude global : essential plugins,
   policy hooks configurables (worktree guard, atomic commit/pending), LSP plugins
   optionnels selon le type de projet, et quatre hook profiles (`standard`,
   `minimal`, `biome`, `biome-strict`). Exécutez
-  `bash scripts/setup-plugins.sh [--with-optional] [--hooks <profile>]`.
+  `npx -y repo-harness init` ; aucun clone du dépôt source n'est nécessaire.
+- **Commande de rafraîchissement du dépôt (`repo-harness update`).** L'installation
+  et le rafraîchissement des dépôts existants ont leur propre surface de commande,
+  tout en conservant l'ancien chemin de migration repo-local et en gardant `init`
+  dédié au runtime global.
+- **Auto-réparation de l'index CodeGraph.** Quand le prompt hook détecte une
+  intention de navigation structurelle et que le dépôt n'a pas d'index
+  `.codegraph`, il initialise l'index avec le binaire CodeGraph local ou visible
+  dans PATH avant d'émettre l'indication de route. Cela reste advisory : pas
+  d'installation de dépendances, pas de readiness probe lourd, et pas de blocage
+  du prompt si CodeGraph est indisponible.
 - **Sentinelle de sécurité (`repo-harness security scan` +
   `security-sentinel.sh`).** Une vérification en lecture seule sur les surfaces
   d'injection de configuration à forte valeur (`~/.claude/settings.json`,
@@ -92,7 +102,7 @@ L'ensemble se découpe en trois couches :
 1. **Couche package source** : ce dépôt maintient le CLI, les command skill
    facades, les templates, les hook assets, le workflow contract, les tests et le
    release gate.
-2. **Couche contrat du dépôt cible** : `repo-harness init` ou une migration écrit
+2. **Couche contrat du dépôt cible** : `repo-harness update` ou une migration écrit
    `docs/spec.md`, `plans/`, `tasks/`, `.ai/context/`, `.ai/harness/`, les helper
    scripts et `.ai/hooks/`.
 3. **Couche host adapter** : les `~/.claude/settings.json` et `~/.codex/hooks.json`
@@ -181,13 +191,16 @@ npx -y repo-harness init
 ```
 
 La release line du package npm est désormais `0.2.x` ; la generated workflow
-compatibility model line est suivie séparément en `5.x`. `repo-harness@0.2.0`
-ajoute le script d'installation global de plugin/hook (`scripts/setup-plugins.sh`),
-la sentinelle de sécurité de configuration en lecture seule
-(`repo-harness security scan`), ainsi que le cycle de vie draft-plan explicite de
-Claude/Codex, le tout par-dessus le CLI renommé, le bootstrap de l'adapter de hook
-de niveau utilisateur, les AI-native scaffold overlays, le typed prompt-guard
-decision engine, le nommage des task artifacts par plan-stem, les runtime aliases
+compatibility model line est suivie séparément en `5.x`. `repo-harness@0.2.1`
+sépare le bootstrap global initial (`repo-harness init`) du rafraîchissement
+repo-local (`repo-harness update`), conserve l'installateur global de plugin/hook
+(`scripts/setup-plugins.sh`), la sentinelle de sécurité en lecture seule
+(`repo-harness security scan`), le cycle de vie draft-plan explicite de
+Claude/Codex, et ajoute l'initialisation non bloquante de l'index CodeGraph pour
+le routing structurel des prompts. Ces capacités reposent sur le CLI renommé, le
+bootstrap de l'adapter de hook de niveau utilisateur, les AI-native scaffold
+overlays, le typed prompt-guard decision engine, le nommage des task artifacts par
+plan-stem, les runtime aliases
 `REPO_HARNESS_*`, la Waza runtime skill sync, et le release gate que le maintainer
 utilise avant de publier sur npm.
 
@@ -224,13 +237,13 @@ répertoires du runtime `project-initializer` retiré sont nettoyés par
 Pour un dépôt existant, exécutez depuis le repo root :
 
 ```bash
-npx -y repo-harness init --dry-run
+npx -y repo-harness update --dry-run
 ```
 
 Appliquez seulement une fois que le rapport du dry-run est correct :
 
 ```bash
-npx -y repo-harness init
+npx -y repo-harness update
 ```
 
 Pour un nouveau projet ou un nouveau module, utilisez la command skill
@@ -267,6 +280,15 @@ Si la sortie du dry-run est incorrecte, arrêtez-vous ici et lisez
 - Codex doit faire confiance à `~/.codex/hooks.json` dans Settings pour que les hooks s'exécutent.
 - Ordre de débogage : user-level adapter config -> `repo-harness-hook` ou fallback `repo-harness hook` -> route registry -> `.ai/hooks/*`.
 
+`SessionStart` exécute deux scripts ordonnés avant le début du travail :
+
+```mermaid
+flowchart LR
+  SessionStart["Claude/Codex SessionStart"] --> Ctx["session-start-context.sh<br/>resume + handoff context"]
+  Ctx --> Sec["security-sentinel.sh<br/>read-only config scan, fingerprint-gated"]
+  Sec --> SSOut["SessionStart additionalContext<br/>prior-session state + SecurityConfig findings"]
+```
+
 Le prompt guard ajoute une étape interne supplémentaire :
 
 ```mermaid
@@ -278,6 +300,7 @@ flowchart LR
   Shell --> Decision["repo-harness-hook prompt-guard-decide<br/>TypeScript decision table"]
   Decision --> Action["single action enum"]
   Action --> Shell
+  Shell --> RouteHint["Waza route hint<br/>explicit think/planning matched first → /think"]
   Shell --> HostOutput["host-safe allow, advice, block, or done gate output"]
 ```
 
@@ -314,7 +337,7 @@ Guards courants :
 
 ## Release actuelle
 
-- npm package : `repo-harness@0.2.0`
+- npm package : `repo-harness@0.2.1`
 - Generated workflow compatibility : `5.2.3`
 - GitHub repository : `Ancienttwo/repo-harness`
 - Release history : [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
@@ -329,7 +352,7 @@ Guards courants :
   - `assets/workflow-contract.v1.json`
 - Les generated repos utilisent par défaut le repo-local harness flow :
   - `docs/spec.md -> plans/ -> tasks/contracts/ -> tasks/reviews/ -> .ai/context/context-map.json -> .ai/harness/*`
-- `repo-harness init` rafraîchit les runtime pieces :
+- `repo-harness update` rafraîchit les runtime pieces :
   - les `repo-harness` skill aliases
   - les global Codex/Claude hook adapters
   - les Waza skills : `check`, `design`, `health`, `hunt`, `learn`, `read`, `think`, `write`

package/README.ja.md

@@ -27,13 +27,20 @@ skill runtime を提供します。
   触ったときだけ読み込まれる capability ブロックが加わる構成です。agent は構造を把握し直すために数千
   token を費やすのではなく、1KB の capability contract を読むか index に問い合わせます。
 
-## 0.2.0 の新機能
+## 0.2.1 の新機能
 
-- **インストールスクリプト（`scripts/setup-plugins.sh`）。** グローバルな Claude 環境の bootstrap を
+- **Global init コマンド（`repo-harness init`）。** グローバルな Claude 環境を
   1 コマンドで完了します。essential plugins、設定可能な policy hooks（worktree guard、atomic
   commit/pending）、プロジェクト種別ごとのオプション LSP plugins、そして 4 段階の hook profile
   （`standard`、`minimal`、`biome`、`biome-strict`）を扱います。
-  実行は `bash scripts/setup-plugins.sh [--with-optional] [--hooks <profile>]`。
+  実行は `npx -y repo-harness init`。source checkout は不要です。
+- **Repo refresh コマンド（`repo-harness update`）。** 既存 repo の install / refresh は
+  独立した command surface になり、従来の repo-local migration path を保ちながら
+  `init` は global runtime setup に集中します。
+- **CodeGraph index の自己修復。** prompt hook が構造的な code-navigation intent を検出し、
+  repo に `.codegraph` index がない場合、route hint を出す前に repo-local または PATH 上の
+  CodeGraph binary で index を初期化します。これは advisory のままで、依存関係の install や
+  重い readiness probe は実行せず、CodeGraph が使えない場合も prompt を block しません。
 - **セキュリティ哨兵（`repo-harness security scan` + `security-sentinel.sh`）。** 高価値の設定インジェクション面
   （`~/.claude/settings.json`、`~/.codex/hooks.json`、repo-local の `.vscode/tasks.json`、そして legacy な
   プロジェクトレベルの `.claude`/`.codex` adapter）に対する読み取り専用のチェックです。危険なコマンド
@@ -72,7 +79,7 @@ product boundary は意図的に地味です。対象リポジトリを検査し
 
 1. **ソースパッケージ層**：本リポジトリが CLI、command skill facades、templates、hook assets、
    workflow contract、tests、release gate を所有します。
-2. **対象リポジトリ contract 層**：`repo-harness init` または migration が、`docs/spec.md`、
+2. **対象リポジトリ contract 層**：`repo-harness update` または migration が、`docs/spec.md`、
    `plans/`、`tasks/`、`.ai/context/`、`.ai/harness/`、helper scripts、`.ai/hooks/` といった
    repo-local ファイルを書き込みます。
 3. **Host adapter 層**：user-level の `~/.claude/settings.json` と `~/.codex/hooks.json` が
@@ -153,12 +160,11 @@ npx -y repo-harness init
 ```
 
 npm package の release line は現在 `0.2.x` です。生成される workflow compatibility model line は
-別途 `5.x` として追跡されます。`repo-harness@0.2.0` は、グローバルな plugin/hook インストールスクリプト
-（`scripts/setup-plugins.sh`）、読み取り専用の設定セキュリティ哨兵（`repo-harness security scan`）、
-そして明示的な Claude/Codex draft-plan ライフサイクルを、改名後の CLI、user-level hook adapter
-bootstrap、AI-native scaffold overlays、typed prompt-guard decision engine、plan-stem task artifact
-命名、`REPO_HARNESS_*` runtime aliases、Waza runtime skill sync、そして maintainer が npm 公開前に
-使う release gate の上に追加します。
+別途 `5.x` として追跡されます。`repo-harness@0.2.1` は、初回 global bootstrap
+（`repo-harness init`）と repo-local refresh（`repo-harness update`）を分離し、グローバルな
+plugin/hook インストールスクリプト（`scripts/setup-plugins.sh`）、読み取り専用の設定セキュリティ哨兵
+（`repo-harness security scan`）、明示的な Claude/Codex draft-plan ライフサイクルを保ち、
+構造的 prompt routing 用の非ブロッキング CodeGraph index 初期化を追加します。
 
 ソースの checkout から作業する場合：
 
@@ -191,13 +197,13 @@ symlink に裏打ちされた runtime entrypoint です。退役した `project-
 既存リポジトリでは repo root から実行します。
 
 ```bash
-npx -y repo-harness init --dry-run
+npx -y repo-harness update --dry-run
 ```
 
 dry-run のレポートが正しいことを確認してから適用します。
 
 ```bash
-npx -y repo-harness init
+npx -y repo-harness update
 ```
 
 新しいプロジェクトやモジュールには `repo-harness-scaffold` command skill を使います。既存リポジトリには
@@ -234,6 +240,15 @@ dry-run の出力がおかしい場合は、ここで一旦止め、
 - Codex は Settings で `~/.codex/hooks.json` を信頼済みにしないと、hooks は実行されません。
 - デバッグの順序：user-level adapter config -> `repo-harness-hook` または fallback の `repo-harness hook` -> route registry -> `.ai/hooks/*`。
 
+`SessionStart` は作業開始前に 2 つの script を順番に実行します。
+
+```mermaid
+flowchart LR
+  SessionStart["Claude/Codex SessionStart"] --> Ctx["session-start-context.sh<br/>resume + handoff context"]
+  Ctx --> Sec["security-sentinel.sh<br/>read-only config scan, fingerprint-gated"]
+  Sec --> SSOut["SessionStart additionalContext<br/>prior-session state + SecurityConfig findings"]
+```
+
 Prompt guard には内部ステップが 1 つ増えます。
 
 ```mermaid
@@ -245,6 +260,7 @@ flowchart LR
   Shell --> Decision["repo-harness-hook prompt-guard-decide<br/>TypeScript decision table"]
   Decision --> Action["single action enum"]
   Action --> Shell
+  Shell --> RouteHint["Waza route hint<br/>explicit think/planning matched first → /think"]
   Shell --> HostOutput["host-safe allow, advice, block, or done gate output"]
 ```
 
@@ -279,7 +295,7 @@ hook がブロックしたときは、まず terminal の構造化された出
 
 ## 現在の Release
 
-- npm package：`repo-harness@0.2.0`
+- npm package：`repo-harness@0.2.1`
 - Generated workflow compatibility：`5.2.3`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
@@ -294,7 +310,7 @@ hook がブロックしたときは、まず terminal の構造化された出
   - `assets/workflow-contract.v1.json`
 - Generated repos はデフォルトで repo-local harness flow を使います：
   - `docs/spec.md -> plans/ -> tasks/contracts/ -> tasks/reviews/ -> .ai/context/context-map.json -> .ai/harness/*`
-- `repo-harness init` は runtime pieces をリフレッシュします：
+- `repo-harness update` は runtime pieces をリフレッシュします：
   - `repo-harness` skill aliases
   - global Codex/Claude hook adapters
   - Waza skills：`check`、`design`、`health`、`hunt`、`learn`、`read`、`think`、`write`

package/README.md

@@ -34,13 +34,25 @@ This repository now dogfoods its own tasks-first contract. It is both:
   read a 1KB capability contract or query the index instead of spending thousands of
   tokens rediscovering structure.
 
-## What's New in 0.2.0
+## What's New in 0.2.2
 
-- **Install script (`scripts/setup-plugins.sh`).** One command bootstraps the global
+- **Safer global init defaults.** `repo-harness init` now streams setup progress
+  directly to the terminal and no longer installs the Superpowers Claude
+  marketplace plugin by default. Use `repo-harness init --with-superpowers` only
+  when you explicitly want that marketplace plugin.
+- **Global init command (`repo-harness init`).** One command bootstraps the global
   Claude environment: essential plugins, configurable policy hooks (worktree guard,
   atomic commit/pending), optional LSP plugins by project type, and four hook profiles
   (`standard`, `minimal`, `biome`, `biome-strict`).
-  Run `bash scripts/setup-plugins.sh [--with-optional] [--hooks <profile>]`.
+  Run `npx -y repo-harness init`; no source checkout is required.
+- **Repo refresh command (`repo-harness update`).** Existing-repo install and
+  refresh now has its own command surface, preserving the previous repo-local
+  harness migration path while keeping `init` focused on global runtime setup.
+- **CodeGraph index self-heal.** When the prompt hook detects structural
+  code-navigation intent and the repo has no `.codegraph` index, it initializes
+  the index with the local or PATH-visible CodeGraph binary before emitting the
+  route hint. This remains advisory: no dependency install, no heavy readiness
+  probe, and no prompt block if CodeGraph is unavailable.
 - **Security sentinel (`repo-harness security scan` + `security-sentinel.sh`).** A
   read-only check over high-value config injection surfaces (`~/.claude/settings.json`,
   `~/.codex/hooks.json`, repo-local `.vscode/tasks.json`, and legacy project-level
@@ -81,7 +93,7 @@ The design has three layers:
 
 1. **Source package**: this repository owns the CLI, command skill facades,
    templates, hook assets, workflow contract, tests, and release gate.
-2. **Target repo contract**: `repo-harness init` or migration writes repo-local
+2. **Target repo contract**: `repo-harness update` or migration writes repo-local
    files such as `docs/spec.md`, `plans/`, `tasks/`, `.ai/context/`,
    `.ai/harness/`, helper scripts, and `.ai/hooks/`.
 3. **Host adapters**: user-level `~/.claude/settings.json` and
@@ -159,26 +171,47 @@ flowchart TD
 This is the fastest path for an AI tooling owner evaluating whether the workflow is
 safe to adopt in a real repo.
 
-### Install or refresh the local runtime
+### Initial bootstrap
 
 ```bash
 npx -y repo-harness init
 ```
 
+`init` is the first-run global bootstrap path. It runs the packaged
+`scripts/setup-plugins.sh`, installs global Claude plugins and hook profiles, and
+defaults to `--hooks standard`. Use `--hooks <profile>` or `--no-hooks` when you
+need a different hook profile.
+
+### Install or refresh a repo-local harness
+
+```bash
+npx -y repo-harness update --dry-run
+npx -y repo-harness update
+```
+
+`update` is the existing-repo install and refresh path. Run it from a target
+repository to install or refresh workflow files, hook assets, host adapters,
+skill aliases, and repo-local verification surfaces from the current npm package.
+
 The npm package release line is now `0.2.x`; generated workflow compatibility is
-tracked separately as the `5.x` model line. The `0.2.0` package adds the global
-plugin/hook install script (`scripts/setup-plugins.sh`), the read-only config
-security sentinel (`repo-harness security scan`), and the explicit Claude/Codex
-draft-plan lifecycle, on top of the renamed `repo-harness` CLI, user-level hook
+tracked separately as the `5.x` model line. The `0.2.2` package splits first-run
+global bootstrap (`repo-harness init`) from repo-local refresh
+(`repo-harness update`), keeps the global plugin/hook installer
+(`scripts/setup-plugins.sh`), the read-only config security sentinel
+(`repo-harness security scan`), the explicit Claude/Codex draft-plan lifecycle,
+adds non-blocking CodeGraph index initialization for structural prompt routing,
+and keeps Superpowers behind the explicit `--with-superpowers` opt-in flag.
+These sit on top of the renamed `repo-harness` CLI, user-level hook
 adapter bootstrap, AI-native scaffold overlays, the typed prompt-guard decision
 engine, plan-stem task artifact naming, `REPO_HARNESS_*` runtime aliases, Waza
-runtime skill sync, and the maintainer release gate. When working from a source
-checkout instead of npm, run:
+runtime skill sync, and the maintainer release gate.
+
+Only maintainers editing the package need a source checkout:
 
 ```bash
 git clone https://github.com/Ancienttwo/repo-harness.git ~/Projects/repo-harness
 cd ~/Projects/repo-harness
-bun src/cli/index.ts init
+bun src/cli/index.ts update
 ```
 
 Local path model:
@@ -208,13 +241,13 @@ The retired `project-initializer` directories under `~/.codex/skills` and
 For an existing repo, run from the repo root:
 
 ```bash
-npx -y repo-harness init --dry-run
+npx -y repo-harness update --dry-run
 ```
 
 Apply only after the dry-run report looks correct:
 
 ```bash
-npx -y repo-harness init
+npx -y repo-harness update
 ```
 
 For a new project or module, use the `repo-harness-scaffold` command skill. For
@@ -252,6 +285,15 @@ before applying anything.
 - Codex must mark `~/.codex/hooks.json` as trusted in Codex Settings before those hooks run.
 - Debug in this order: user-level adapter config -> `repo-harness-hook` (or fallback `repo-harness hook`) -> route registry -> `.ai/hooks/*`.
 
+`SessionStart` runs two ordered scripts before work begins:
+
+```mermaid
+flowchart LR
+  SessionStart["Claude/Codex SessionStart"] --> Ctx["session-start-context.sh<br/>resume + handoff context"]
+  Ctx --> Sec["security-sentinel.sh<br/>read-only config scan, fingerprint-gated"]
+  Sec --> SSOut["SessionStart additionalContext<br/>prior-session state + SecurityConfig findings"]
+```
+
 Prompt guard has one extra internal step:
 
 ```mermaid
@@ -263,6 +305,7 @@ flowchart LR
   Shell --> Decision["repo-harness-hook prompt-guard-decide<br/>TypeScript decision table"]
   Decision --> Action["single action enum"]
   Action --> Shell
+  Shell --> RouteHint["Waza route hint<br/>explicit think/planning matched first → /think"]
   Shell --> HostOutput["host-safe allow, advice, block, or done gate output"]
 ```
 
@@ -297,7 +340,7 @@ Most common guards:
 
 ## Current Release
 
-- npm package: `repo-harness@0.2.0`
+- npm package: `repo-harness@0.2.2`
 - Generated workflow compatibility: `5.2.3`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
@@ -328,7 +371,7 @@ Most common guards:
   - `complex -> gstack`
   - `simple -> Waza` with Codex-first runtime copies in `~/.codex/skills`
   - `knowledge -> gbrain`
-- `repo-harness init` bootstraps the Codex/Claude runtime pieces needed for the
+- `repo-harness update` bootstraps the Codex/Claude runtime pieces needed for the
   default workflow:
   - refreshes `repo-harness` skill aliases
   - installs global Codex/Claude hook adapters

package/README.zh-CN.md

@@ -23,12 +23,20 @@ repo-local workflow 的自托管样例。
   做渐进式上下文加载：一份小而稳定的 root context（约 12KB），加上只在改到对应文件时才加载的
   capability 块。agent 读一份 1KB 的 capability 合约或查索引，而不是花上千 token 重新摸清结构。
 
-## 0.2.0 新特性
+## 0.2.2 新特性
 
-- **安装脚本（`scripts/setup-plugins.sh`）。** 一条命令完成全局 Claude 环境引导：essential plugins、
+- **更安全的全局初始化默认值。** `repo-harness init` 现在会把 setup 进度直接输出到终端，
+  不再默认安装 Superpowers Claude marketplace plugin。只有你明确需要它时，才使用
+  `repo-harness init --with-superpowers`。
+- **全局初始化命令（`repo-harness init`）。** 一条命令引导全局 Claude 环境：essential plugins、
   可配置 policy hooks（worktree guard、atomic commit/pending）、按项目类型可选的 LSP plugins，以及
   四档 hook profile（`standard`、`minimal`、`biome`、`biome-strict`）。运行
-  `bash scripts/setup-plugins.sh [--with-optional] [--hooks <profile>]`。
+  `npx -y repo-harness init`，不需要 clone 源码仓库。
+- **仓库刷新命令（`repo-harness update`）。** 已有仓库的安装/刷新入口独立成命令，继续复用
+  原 repo-local harness migration 路径，同时让 `init` 专注于全局 runtime setup。
+- **CodeGraph index 自愈。** prompt hook 检测到结构化代码导航意图、且仓库还没有 `.codegraph`
+  index 时，会先用 repo-local 或 PATH 上的 CodeGraph binary 初始化 index，再发路由提示。这个动作仍是
+  advisory：不安装依赖、不跑重 readiness probe，CodeGraph 不可用时也不阻塞 prompt。
 - **安全哨兵（`repo-harness security scan` + `security-sentinel.sh`）。** 对高价值配置注入面做只读检查
   （`~/.claude/settings.json`、`~/.codex/hooks.json`、仓库本地 `.vscode/tasks.json`，以及 legacy 项目级
   `.claude`/`.codex` adapter）。它标记危险命令模式——远程 shell 管道、base64 解码执行、`osascript`、
@@ -62,7 +70,7 @@ repo-local hooks，然后验证这些 workflow surfaces 仍然一致。
 
 1. **源码包层**：本仓库维护 CLI、command skill facades、templates、hook assets、
    workflow contract、tests 和 release gate。
-2. **目标仓库合约层**：`repo-harness init` 或 migration 会写入 `docs/spec.md`、
+2. **目标仓库合约层**：`repo-harness update` 或 migration 会写入 `docs/spec.md`、
    `plans/`、`tasks/`、`.ai/context/`、`.ai/harness/`、helper scripts 和
    `.ai/hooks/`。
 3. **Host adapter 层**：user-level `~/.claude/settings.json` 和 `~/.codex/hooks.json`
@@ -135,26 +143,42 @@ flowchart TD
 
 这是评估一个真实仓库是否适合接入该 workflow 的最快路径。
 
-### 安装或刷新本地 runtime
+### 初次引导
 
 ```bash
 npx -y repo-harness init
 ```
 
+`init` 是首次全局引导入口。它运行 npm 包里自带的 `scripts/setup-plugins.sh`，
+安装全局 Claude plugins 和 hook profiles，默认等价于 `--hooks standard`。
+需要不同 hook profile 时再传 `--hooks <profile>` 或 `--no-hooks`。
+
+### 安装或刷新 repo-local harness
+
+```bash
+npx -y repo-harness update --dry-run
+npx -y repo-harness update
+```
+
+`update` 是已有目标仓库的安装和刷新入口。从目标仓库根目录运行它，用当前 npm 包
+安装或刷新 workflow files、hook assets、host adapters、skill aliases 和
+repo-local verification surfaces。
+
 npm package release line 现在是 `0.2.x`；生成的 workflow compatibility model line
-单独以 `5.x` 追踪。`repo-harness@0.2.0` 新增了全局 plugin/hook 安装脚本
-（`scripts/setup-plugins.sh`）、只读的配置安全哨兵（`repo-harness security scan`），
-以及显式的 Claude/Codex draft-plan 生命周期，叠加在改名后的 CLI、user-level hook
-adapter bootstrap、AI-native scaffold overlays、typed prompt-guard decision engine、
-plan-stem task artifact 命名、`REPO_HARNESS_*` runtime aliases、Waza runtime skill
-sync，以及 maintainer 发布 npm 前使用的 release gate 之上。
+单独以 `5.x` 追踪。`repo-harness@0.2.2` 把首次全局引导（`repo-harness init`）
+和 repo-local 刷新（`repo-harness update`）拆开，同时保留全局 plugin/hook 安装脚本
+（`scripts/setup-plugins.sh`）、只读配置安全哨兵（`repo-harness security scan`）、
+显式 Claude/Codex draft-plan 生命周期，新增 prompt hook 的非阻塞 CodeGraph index 初始化，
+并把 Superpowers 放到显式 `--with-superpowers` opt-in 后面。这些能力叠加在改名后的 CLI、user-level hook adapter bootstrap、AI-native scaffold overlays、
+typed prompt-guard decision engine、plan-stem task artifact 命名、`REPO_HARNESS_*`
+runtime aliases、Waza runtime skill sync，以及 maintainer 发布 npm 前使用的 release gate 之上。
 
-如果从源码 checkout 工作：
+只有维护者需要在编辑 package 源码时使用 source checkout：
 
 ```bash
 git clone https://github.com/Ancienttwo/repo-harness.git ~/Projects/repo-harness
 cd ~/Projects/repo-harness
-bun src/cli/index.ts init
+bun src/cli/index.ts update
 ```
 
 本地路径模型：
@@ -180,13 +204,13 @@ symlink-backed runtime entrypoints。退休的 `project-initializer` runtime 目
 已有仓库从 repo root 执行：
 
 ```bash
-npx -y repo-harness init --dry-run
+npx -y repo-harness update --dry-run
 ```
 
 dry-run 报告正确后再应用：
 
 ```bash
-npx -y repo-harness init
+npx -y repo-harness update
 ```
 
 新项目或新模块使用 `repo-harness-scaffold` command skill。已有仓库使用
@@ -222,6 +246,15 @@ bun test
 - Codex 必须在 Settings 里信任 `~/.codex/hooks.json`，hooks 才会执行。
 - 调试顺序：user-level adapter config -> `repo-harness-hook` 或 fallback `repo-harness hook` -> route registry -> `.ai/hooks/*`。
 
+`SessionStart` 在开工前按顺序跑两个脚本：
+
+```mermaid
+flowchart LR
+  SessionStart["Claude/Codex SessionStart"] --> Ctx["session-start-context.sh<br/>恢复 + handoff 上下文"]
+  Ctx --> Sec["security-sentinel.sh<br/>只读配置扫描，按指纹门控"]
+  Sec --> SSOut["SessionStart additionalContext<br/>上次会话状态 + SecurityConfig 发现项"]
+```
+
 Prompt guard 多一个内部步骤：
 
 ```mermaid
@@ -233,6 +266,7 @@ flowchart LR
   Shell --> Decision["repo-harness-hook prompt-guard-decide<br/>TypeScript decision table"]
   Decision --> Action["single action enum"]
   Action --> Shell
+  Shell --> RouteHint["Waza 路由提示<br/>显式 think/规划优先匹配 → /think"]
   Shell --> HostOutput["host-safe allow, advice, block, or done gate output"]
 ```
 
@@ -267,7 +301,7 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
 
 ## 当前 Release
 
-- npm package：`repo-harness@0.2.0`
+- npm package：`repo-harness@0.2.2`
 - Generated workflow compatibility：`5.2.3`
 - GitHub repository：`Ancienttwo/repo-harness`
 - Release history：[`docs/CHANGELOG.md`](docs/CHANGELOG.md)
@@ -282,7 +316,7 @@ hook block 工作时，先看 terminal 里的结构化输出。核心字段是
   - `assets/workflow-contract.v1.json`
 - Generated repos 默认使用 repo-local harness flow：
   - `docs/spec.md -> plans/ -> tasks/contracts/ -> tasks/reviews/ -> .ai/context/context-map.json -> .ai/harness/*`
-- `repo-harness init` 会刷新 runtime pieces：
+- `repo-harness update` 会刷新 runtime pieces：
   - `repo-harness` skill aliases
   - global Codex/Claude hook adapters
   - Waza skills：`check`、`design`、`health`、`hunt`、`learn`、`read`、`think`、`write`

package/assets/hooks/post-edit-guard.sh

@@ -41,7 +41,9 @@ run_architecture_drift_sync() {
     if [[ -x "scripts/context-contract-sync.sh" ]]; then
       bash "scripts/context-contract-sync.sh" sync-latest || true
     fi
-    if command -v repo-harness >/dev/null 2>&1; then
+    if [[ -n "${REPO_HARNESS_CLI:-}" && -f "$REPO_HARNESS_CLI" ]] && command -v bun >/dev/null 2>&1; then
+      bun "$REPO_HARNESS_CLI" capability-context request --from-latest-architecture-event || true
+    elif command -v repo-harness >/dev/null 2>&1; then
       repo-harness capability-context request --from-latest-architecture-event || true
     elif command -v bun >/dev/null 2>&1 && [[ -f "src/cli/index.ts" ]]; then
       bun src/cli/index.ts capability-context request --from-latest-architecture-event || true

package/assets/hooks/prompt-guard.sh

@@ -642,6 +642,55 @@ is_nontrivial_code_task_intent() {
   echo "$PROMPT_INTENT_TEXT" | grep -qEi "(architecture|architectural|runtime|hook|hooks|shared contract|workflow contract|module boundary|route registry|multi[- ]?file|refactor|dependency path|架构|运行时|钩子|共享合约|工作流合约|模块边界|路由表|多文件|重构|依赖路径)"
 }
 
+resolve_codegraph_bin() {
+  if [[ -x "node_modules/.bin/codegraph" ]]; then
+    printf '%s\n' "node_modules/.bin/codegraph"
+    return 0
+  fi
+
+  command -v codegraph 2>/dev/null || return 1
+}
+
+run_codegraph_init_command() {
+  local codegraph_bin status cursor_dir_existed cursor_rules_dir_existed cursor_rule_existed
+  codegraph_bin="$(resolve_codegraph_bin)" || return 127
+
+  cursor_dir_existed=false
+  cursor_rules_dir_existed=false
+  cursor_rule_existed=false
+  [[ -d ".cursor" ]] && cursor_dir_existed=true
+  [[ -d ".cursor/rules" ]] && cursor_rules_dir_existed=true
+  [[ -e ".cursor/rules/codegraph.mdc" ]] && cursor_rule_existed=true
+
+  set +e
+  CODEGRAPH_NO_DAEMON=1 "$codegraph_bin" init -i .
+  status=$?
+  set -e
+
+  if [[ "$cursor_rule_existed" == "false" && -f ".cursor/rules/codegraph.mdc" ]]; then
+    rm -f ".cursor/rules/codegraph.mdc"
+    [[ "$cursor_rules_dir_existed" == "false" ]] && rmdir ".cursor/rules" 2>/dev/null || true
+    [[ "$cursor_dir_existed" == "false" ]] && rmdir ".cursor" 2>/dev/null || true
+  fi
+
+  return "$status"
+}
+
+ensure_codegraph_index_for_route() {
+  local output status
+
+  [[ -f ".codegraph/codegraph.db" ]] && return 0
+
+  output="$(run_codegraph_init_command 2>&1)"
+  status=$?
+
+  if [[ "$status" -eq 0 && -f ".codegraph/codegraph.db" ]]; then
+    echo "[CodegraphRoute] Initialized missing CodeGraph index before routing hint."
+  elif [[ "$status" -ne 127 ]]; then
+    echo "[CodegraphRoute] CodeGraph index init skipped or failed; run codegraph init -i . if structural tools are unavailable."
+  fi
+}
+
 emit_codegraph_route_hint() {
   local session_key session_file=".claude/.session-id"
 
@@ -652,7 +701,11 @@ emit_codegraph_route_hint() {
     return 0
   fi
 
-  if is_codegraph_route_intent || is_nontrivial_code_task_intent; then
+  if is_codegraph_route_intent; then
+    ensure_codegraph_index_for_route || true
+    echo "[CodegraphRoute] Structural code-navigation intent detected. Prefer CodeGraph context/search/callers/impact before grep/read when available."
+    session_state_mark_codegraph_nudged "$session_key" || true
+  elif is_nontrivial_code_task_intent; then
     echo "[CodegraphRoute] Structural code-navigation intent detected. Prefer CodeGraph context/search/callers/impact before grep/read when available."
     session_state_mark_codegraph_nudged "$session_key" || true
   fi

package/assets/templates/helpers/sync-brain-docs.sh

@@ -246,9 +246,32 @@ for (const entry of selected) {
     continue;
   }
 
-  const sourceContent = fs.readFileSync(entry.sourceFile, "utf8");
+  let sourceContent;
+  try {
+    sourceContent = fs.readFileSync(entry.sourceFile, "utf8");
+  } catch (error) {
+    const code = error && error.code ? ` (${error.code})` : "";
+    issue(`Entry ${entry.id} source file is unreadable: ${entry.sourcePath}${code}`);
+    continue;
+  }
+
   const targetExists = fs.existsSync(entry.targetPath);
-  const targetContent = targetExists ? fs.readFileSync(entry.targetPath, "utf8") : null;
+  let targetContent = null;
+  if (targetExists) {
+    try {
+      targetContent = fs.readFileSync(entry.targetPath, "utf8");
+    } catch (error) {
+      const code = error && error.code ? ` (${error.code})` : "";
+      const message = `Entry ${entry.id} brain file is unreadable: ${entry.brainPath}${code}`;
+      if (modeCheck && !requireVault) {
+        warn(`${message}; skipped sync drift check`);
+        skipped += 1;
+        continue;
+      }
+      issue(message);
+      continue;
+    }
+  }
 
   if (modeCheck) {
     if (!targetExists) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "repo-harness",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Installs, migrates, audits, and repairs repo-local agentic development harnesses",
   "license": "MIT",
   "repository": {

package/scripts/setup-plugins.sh

@@ -392,7 +392,7 @@ install_superpowers_plugin() {
     local settings_file="$CLAUDE_DIR/settings.json"
     local configured=false
 
-    echo -e "${BLUE}Configuring Superpowers plugin (default)...${NC}"
+    echo -e "${BLUE}Configuring Superpowers plugin...${NC}"
 
     if command_exists claude; then
         if claude plugin marketplace add "$SUPERPOWERS_MARKETPLACE" >/dev/null 2>&1; then
@@ -722,6 +722,7 @@ print_summary() {
 main() {
     local install_optional=false
     local install_obsidian=false
+    local install_superpowers=false
     local hook_type="standard"
 
     # Parse arguments
@@ -735,6 +736,10 @@ main() {
                 install_obsidian=true
                 shift
                 ;;
+            --with-superpowers)
+                install_superpowers=true
+                shift
+                ;;
             --hooks)
                 hook_type="$2"
                 shift 2
@@ -754,7 +759,7 @@ main() {
             --help)
                 echo "Usage: setup-plugins.sh [options]"
                 echo ""
-                echo "Default behavior: installs essential plugins + enables $SUPERPOWERS_PLUGIN_ID"
+                echo "Default behavior: installs essential plugins and hook-profile support"
                 echo "Runtime defaults: Plan-only, Codex platform default sandbox with approval on failure,"
                 echo "  Claude default permissions, worktree-warning mutations (opt-in enforcement),"
                 echo "  atomic checkpoint commits after green checks."
@@ -762,6 +767,7 @@ main() {
                 echo "Options:"
                 echo "  --with-optional    Install optional plugins (commit-commands, pr-review-toolkit, ralph-loop, etc.)"
                 echo "  --with-obsidian    Install Obsidian skills"
+                echo "  --with-superpowers Install the Superpowers Claude marketplace plugin"
                 echo "  --hooks TYPE       Hook type: standard (default), minimal, biome, biome-strict, none"
                 echo "  --no-hooks         Skip hook configuration"
                 echo "  --lsp PLUGIN       Install specific LSP plugin (e.g., typescript-lsp, pyright-lsp, gopls-lsp)"
@@ -930,9 +936,11 @@ main() {
     echo ""
     add_permissions
 
-    # Configure Superpowers marketplace plugin (default)
-    echo ""
-    install_superpowers_plugin
+    # Configure Superpowers marketplace plugin only when explicitly requested.
+    if [ "$install_superpowers" = true ]; then
+        echo ""
+        install_superpowers_plugin
+    fi
 
     # Print summary
     print_summary

package/scripts/sync-brain-docs.sh

@@ -246,9 +246,32 @@ for (const entry of selected) {
     continue;
   }
 
-  const sourceContent = fs.readFileSync(entry.sourceFile, "utf8");
+  let sourceContent;
+  try {
+    sourceContent = fs.readFileSync(entry.sourceFile, "utf8");
+  } catch (error) {
+    const code = error && error.code ? ` (${error.code})` : "";
+    issue(`Entry ${entry.id} source file is unreadable: ${entry.sourcePath}${code}`);
+    continue;
+  }
+
   const targetExists = fs.existsSync(entry.targetPath);
-  const targetContent = targetExists ? fs.readFileSync(entry.targetPath, "utf8") : null;
+  let targetContent = null;
+  if (targetExists) {
+    try {
+      targetContent = fs.readFileSync(entry.targetPath, "utf8");
+    } catch (error) {
+      const code = error && error.code ? ` (${error.code})` : "";
+      const message = `Entry ${entry.id} brain file is unreadable: ${entry.brainPath}${code}`;
+      if (modeCheck && !requireVault) {
+        warn(`${message}; skipped sync drift check`);
+        skipped += 1;
+        continue;
+      }
+      issue(message);
+      continue;
+    }
+  }
 
   if (modeCheck) {
     if (!targetExists) {

package/src/cli/commands/global-runtime.ts

@@ -0,0 +1,83 @@
+import { spawnSync, type StdioOptions } from 'child_process';
+import { existsSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+export const HOOK_PROFILES = ['standard', 'minimal', 'biome', 'biome-strict', 'none'] as const;
+export type HookProfile = (typeof HOOK_PROFILES)[number];
+
+export interface GlobalRuntimeOptions {
+  sourceRoot?: string;
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+  stdio?: 'pipe' | 'inherit';
+  withOptional?: boolean;
+  withObsidian?: boolean;
+  withSuperpowers?: boolean;
+  hooks?: string | false;
+  lsp?: string;
+  projectType?: string;
+}
+
+export interface GlobalRuntimeResult {
+  exitCode: number;
+  command: string[];
+  stdout: string;
+  stderr: string;
+}
+
+function defaultSourceRoot(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+}
+
+export function buildGlobalRuntimeArgs(opts: GlobalRuntimeOptions): string[] {
+  const args: string[] = [];
+  if (opts.withOptional === true) args.push('--with-optional');
+  if (opts.withObsidian === true) args.push('--with-obsidian');
+  if (opts.withSuperpowers === true) args.push('--with-superpowers');
+  if (opts.hooks === false) args.push('--no-hooks');
+  else if (typeof opts.hooks === 'string') args.push('--hooks', opts.hooks);
+  if (opts.lsp) args.push('--lsp', opts.lsp);
+  if (opts.projectType) args.push('--project-type', opts.projectType);
+  return args;
+}
+
+export function validateHookProfile(
+  value: string | false | undefined,
+  commandName = 'init',
+): string | null {
+  if (value === undefined || value === false) return null;
+  return HOOK_PROFILES.includes(value as HookProfile)
+    ? null
+    : `repo-harness ${commandName}: invalid --hooks "${value}" (expected: ${HOOK_PROFILES.join(', ')})`;
+}
+
+export function runGlobalRuntimeSetup(opts: GlobalRuntimeOptions): GlobalRuntimeResult {
+  const sourceRoot = opts.sourceRoot ?? defaultSourceRoot();
+  const scriptPath = join(sourceRoot, 'scripts', 'setup-plugins.sh');
+  const args = buildGlobalRuntimeArgs(opts);
+  const command = ['bash', scriptPath, ...args];
+
+  if (!existsSync(scriptPath)) {
+    return {
+      exitCode: 1,
+      command,
+      stdout: '',
+      stderr: `repo-harness init: script not found at ${scriptPath}`,
+    };
+  }
+
+  const result = spawnSync('bash', [scriptPath, ...args], {
+    cwd: opts.cwd ?? process.cwd(),
+    encoding: 'utf-8',
+    env: { ...process.env, ...(opts.env ?? {}) },
+    stdio: (opts.stdio ?? 'pipe') as StdioOptions,
+  });
+
+  return {
+    exitCode: result.status ?? 1,
+    command,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr || (result.error ? String(result.error.message || result.error) : ''),
+  };
+}

package/src/cli/commands/init.ts

@@ -1,9 +1,10 @@
 /**
- * `repo-harness init` — one-shot existing-repo harness bootstrap.
+ * Existing-repo harness bootstrap/update implementation.
  *
- * This is the CLI equivalent of the `repo-harness-init` skill facade: default
- * the target repo to cwd, install/refresh the machine runtime pieces, apply the
- * repo-local workflow migration, then verify the installed harness.
+ * This backs the public `repo-harness update` command and the legacy
+ * `repo-harness-init` skill facade: default the target repo to cwd,
+ * install/refresh the machine runtime pieces, apply the repo-local workflow
+ * migration, then verify the installed harness.
  */
 
 import { spawnSync } from "child_process";

package/src/cli/commands/status.ts

@@ -15,7 +15,7 @@ import { isManagedEntry, type HooksByEvent } from '../installer/managed-entries'
 import { readJsonOrEmpty } from '../installer/shared';
 import type { Location } from '../installer/types';
 
-export const CLI_VERSION = '0.2.0';
+export const CLI_VERSION = '0.2.2';
 
 const OPT_IN_MARKER = '.ai/harness/workflow-contract.json';
 

package/src/cli/index.ts

@@ -18,6 +18,7 @@ import { buildToolsCommand } from './commands/tools';
 import { buildBrainCommand } from './commands/brain';
 import { buildCapabilityContextCommand } from './commands/capability-context';
 import { formatSecurityScan, runSecurityScan } from './commands/security';
+import { HOOK_PROFILES, runGlobalRuntimeSetup, validateHookProfile } from './commands/global-runtime';
 import { runPromptGuardDecisionFromEnv } from './commands/prompt-guard-decision';
 import type { Location } from './installer/types';
 import type { HookEvent, RouteId } from './hook/route-registry';
@@ -30,6 +31,7 @@ export const SUBCOMMANDS = [
   'doctor',
   'migrate',
   'security',
+  'update',
   'tools',
   'brain',
   'capability-context',
@@ -44,12 +46,49 @@ export function buildProgram(): Command {
   program
     .name('repo-harness')
     .description('Repo-local agentic development harness CLI')
-    .version('0.2.0')
+    .version('0.2.2')
     .exitOverride();
 
   program
     .command('init')
-    .description('Install or refresh the repo-harness workflow in an existing repo')
+    .description('Bootstrap global Claude plugins and hook profiles from the npm package')
+    .option('--with-optional', 'Install optional plugins')
+    .option('--with-obsidian', 'Install Obsidian skills')
+    .option('--with-superpowers', 'Install the Superpowers Claude marketplace plugin')
+    .option('--hooks <profile>', `Hook profile: ${HOOK_PROFILES.join('|')}`, 'standard')
+    .option('--no-hooks', 'Skip hook configuration')
+    .option('--lsp <plugin>', 'Install a specific LSP plugin')
+    .option('--project-type <type>', 'Auto-select LSP by repo-harness project type')
+    .action((rawOpts: {
+      withOptional?: boolean;
+      withObsidian?: boolean;
+      withSuperpowers?: boolean;
+      hooks?: string | false;
+      lsp?: string;
+      projectType?: string;
+    }) => {
+      const validationError = validateHookProfile(rawOpts.hooks, 'init');
+      if (validationError) {
+        console.error(validationError);
+        process.exit(2);
+      }
+      const result = runGlobalRuntimeSetup({
+        withOptional: rawOpts.withOptional === true,
+        withObsidian: rawOpts.withObsidian === true,
+        withSuperpowers: rawOpts.withSuperpowers === true,
+        hooks: rawOpts.hooks,
+        lsp: rawOpts.lsp,
+        projectType: rawOpts.projectType,
+        stdio: 'inherit',
+      });
+      if (result.stdout) process.stdout.write(result.stdout);
+      if (result.stderr) process.stderr.write(result.stderr);
+      process.exit(result.exitCode);
+    });
+
+  program
+    .command('update')
+    .description('Install or refresh the repo-local harness workflow in an existing repo')
     .option('--repo <path>', 'Target repository path (defaults to cwd)')
     .option('--dry-run', 'Plan repo harness changes without applying them')
     .option('--target <target>', `Host target for adapters and external skills: ${VALID_TARGETS.join('|')}`, 'both')
@@ -82,12 +121,12 @@ export function buildProgram(): Command {
     }) => {
       if (!VALID_TARGETS.includes(rawOpts.target as InstallTargetSpec)) {
         console.error(
-          `repo-harness init: invalid --target "${rawOpts.target}" (expected: ${VALID_TARGETS.join(', ')})`,
+          `repo-harness update: invalid --target "${rawOpts.target}" (expected: ${VALID_TARGETS.join(', ')})`,
         );
         process.exit(2);
       }
       if (!['skip', 'manifest-only', 'install-gbrain-cli'].includes(rawOpts.brainMode ?? 'skip')) {
-        console.error('repo-harness init: invalid --brain-mode (expected: skip, manifest-only, install-gbrain-cli)');
+        console.error('repo-harness update: invalid --brain-mode (expected: skip, manifest-only, install-gbrain-cli)');
         process.exit(2);
       }
       const common = {