cairn-ai 0.1.11 → 0.2.0

package/.agents/workflows/cairn-doctor.md

@@ -2,17 +2,7 @@
 
 Goal: diagnose Cairn installation status.
 
-Run:
-
-```sh
-bunx cairn-ai@latest doctor
-```
-
-When running from local source:
-
-```sh
-node scripts/cairn.mjs doctor
-```
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Invoke Node directly with the absolute `entrypoints.cli` value and `["doctor"]`; do not build a shell-interpolated command from the path.
 
 Checks:
 
@@ -20,3 +10,4 @@ Checks:
 - Claude Code commands and agents mirror files.
 - Antigravity skills and workflows mirror files.
 - Antigravity CLI skills and workflows mirror files.
+- Installed runtime locators and the referenced scripts, templates, and model guidance.

package/.agents/workflows/cairn-install.md

@@ -8,10 +8,6 @@ Run:
 bunx cairn-ai@latest install
 ```
 
-When running from local source:
-
-```sh
-node scripts/cairn.mjs install
-```
+Installation must run from the package/global source because the cached plugin is the destination. Do not copy Cairn runtime files into the target project and do not invoke install from a cached plugin locator.
 
 After installation, check status with the `cairn-doctor` workflow.

package/.agents/workflows/cairn-memory.md

@@ -2,6 +2,8 @@
 
 Use the `cairn-memory` skill.
 
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Cairn scripts and policy resources must be resolved through that locator, not from the target project.
+
 Goal: create or update repository memory without asking the user for discoverable facts.
 
 Procedure:

package/.agents/workflows/cairn-plan.md

@@ -2,15 +2,17 @@
 
 Use the `cairn-plan` skill.
 
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve Cairn scripts, model guidance, templates, commands, and agents through that locator; only repository state such as `MEMORY.md`, `PLAN.md`, and `docs/plan/` belongs to the target project.
+
 Goal: leave a decision-complete plan for the current task in files before non-trivial implementation.
 
 Procedure:
 
 1. Every agent must read the project-root `MEMORY.md` for domain knowledge and repository policy before repository exploration, tool selection, work, or delegation.
 2. Read relevant `docs/memory/*.md`.
-3. If the active or assigned model is Claude-family, read `docs/model-guidance/claude.md`; if Codex-family, read `docs/model-guidance/codex.md`.
-4. Run `node scripts/cairn.mjs toolcheck` when available.
-5. If required LSP/check tools are missing, run `node scripts/cairn.mjs toolcheck --install` or a repository-native install command before accepting a fallback.
+3. If the active or assigned model is Claude-family, read `claude.md` under the locator's `resources.modelGuidance`; if Codex-family, read `codex.md` there.
+4. Invoke Node directly with the locator's absolute `entrypoints.cli`, `toolcheck`, and `--root` for the target repository.
+5. If required LSP/check tools are missing, follow the installed toolcheck policy before any explicitly approved installation attempt.
 6. Explore before asking the user.
 7. Understand the whole work and affected surfaces first, then classify it into small executable tasks. If a task is still too broad to verify cleanly, split it into sub-tasks.
 8. Run complexity triage before applying agent, plugin, or delegated workflow guidance, and record it before mutating files.

package/.agents/workflows/cairn-review.md

@@ -2,6 +2,8 @@
 
 Use the `cairn-review` skill.
 
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Cairn scripts and policy resources must be resolved through that locator, not from the target project.
+
 Goal: review completed work against plan, memory, policy, and evidence.
 
 Procedure:

package/.agents/workflows/cairn-toolcheck.md

@@ -2,16 +2,8 @@
 
 Goal: detect repository stacks and check required LSP, typecheck, lint, dry-run, and verification tools.
 
-Run the local command first:
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Invoke Node directly with the absolute `entrypoints.cli` value, `toolcheck`, and an explicit `--root` argument for the target repository; do not build a shell-interpolated command from the path.
 
-```sh
-node scripts/cairn.mjs toolcheck
-```
-
-If required tools are missing, attempt repository-native installation:
-
-```sh
-node scripts/cairn.mjs toolcheck --install
-```
+If required tools are missing, follow the installed command policy before any explicitly approved installation attempt.
 
 Record detected stacks, missing tools, install attempts, and blockers in the related `docs/plan/<topic>.md`.

package/.agents/workflows/cairn-uninstall.md

@@ -2,16 +2,6 @@
 
 Goal: remove the Codex, Claude Code, and Antigravity entries installed by Cairn.
 
-Run:
-
-```sh
-bunx cairn-ai@latest uninstall
-```
-
-When running from local source:
-
-```sh
-node scripts/cairn.mjs uninstall
-```
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Invoke Node directly with the absolute `entrypoints.cli` value and `["uninstall"]`; do not build a shell-interpolated command from the path.
 
 The source work folder and user-created `MEMORY.md`, `PLAN.md`, `docs/memory`, and `docs/plan` files are not deleted.

package/.agents/workflows/cairn-upgrade.md

@@ -8,10 +8,6 @@ Run:
 bunx cairn-ai@latest upgrade
 ```
 
-When running from local source:
-
-```sh
-node scripts/cairn.mjs upgrade
-```
+Upgrade must run from the package/global source because the cached plugin is replaced. Do not invoke upgrade from a cached plugin locator.
 
 After upgrade, check status with the `cairn-doctor` workflow.

package/.agents/workflows/cairn-work.md

@@ -2,6 +2,8 @@
 
 Use the `cairn-work` skill.
 
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve Cairn scripts and policy resources through that locator; only work artifacts and state belong to the target project.
+
 Goal: execute the next incomplete module task in `PLAN.md` without bypassing the recorded complexity triage.
 
 Procedure:
@@ -10,7 +12,7 @@ Procedure:
 2. Read `PLAN.md`, the detailed plan, and relevant memory notes.
 3. Read the Codex or Claude model guidance recorded in the plan.
 4. Select one small module task.
-5. Confirm required tool readiness. If a required LSP/check tool is missing, run `node scripts/cairn.mjs toolcheck --install` or a repository-native install command before accepting a fallback.
+5. Confirm required tool readiness by invoking Node directly with the locator's absolute `entrypoints.cli`, `toolcheck`, and `--root` for the target repository. Follow the installed toolcheck policy before any explicitly approved installation attempt.
 6. Confirm the complexity triage and selected Light/Heavy Path recorded in the plan. If missing, update the plan before mutating files.
 7. For Light Path, keep the user-called/main agent in the orchestrator role and delegate implementation edits to one bounded `worker` whenever subagent tools are available, then run focused verification.
 8. For Heavy Path, follow the plan's staged implementation and review gates without role-mapping shortcuts.

package/.claude/agents/explorer.md

@@ -4,4 +4,4 @@ Read-only discovery agent for codebase questions, impact analysis, pattern searc
 
 Before any task, read the project-root `MEMORY.md` for domain knowledge and repository policy.
 
-Refer to `agents/explorer.md`.
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve `resources.agents` from that JSON object and follow `explorer.md` in that directory. Do not resolve Cairn agent files from the target project.

package/.claude/agents/worker.md

@@ -4,4 +4,4 @@ Focused execution agent for search, small edits, command checks, and QA artifact
 
 Before any task, read the project-root `MEMORY.md` for domain knowledge and repository policy.
 
-Refer to `agents/worker.md`.
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve `resources.agents` from that JSON object and follow `worker.md` in that directory. Do not resolve Cairn agent files from the target project.

package/.claude/commands/cairn-doctor.md

@@ -2,12 +2,4 @@
 
 Diagnose Cairn installation status.
 
-```sh
-node scripts/cairn.mjs doctor
-```
-
-Published package:
-
-```sh
-bunx cairn-ai@latest doctor
-```
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Invoke Node directly with the absolute `entrypoints.cli` value and the argument array `["doctor"]`; do not build a shell-interpolated command from the path.

package/.claude/commands/cairn-install.md

@@ -2,11 +2,7 @@
 
 Install Cairn into Codex, Claude Code, and Antigravity.
 
-```sh
-node scripts/cairn.mjs install
-```
-
-Published package:
+Installation must run from the package/global source because the cached installation is the destination. Do not copy runtime files into the target project and do not invoke install from the cached plugin locator.
 
 ```sh
 bunx cairn-ai@latest install

package/.claude/commands/cairn-memory.md

@@ -2,4 +2,4 @@
 
 Create or update `MEMORY.md` and `docs/memory/<domain>.md`.
 
-Follow plugin command `commands/cairn-memory.md`.
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve `resources.commands` from that JSON object and follow `cairn-memory.md` in that directory. Do not resolve Cairn command files from the target project.

package/.claude/commands/cairn-plan.md

@@ -2,4 +2,4 @@
 
 Start by reading the project-root `MEMORY.md`, then create or update `PLAN.md` and `docs/plan/<topic>.md` before non-trivial implementation, including Light/Heavy Path complexity triage and tool readiness.
 
-Follow plugin command `commands/cairn-plan.md`.
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve `resources.commands` from that JSON object and follow `cairn-plan.md` in that directory. Resolve model guidance and templates through the same locator. Do not resolve Cairn runtime resources from the target project.

package/.claude/commands/cairn-review.md

@@ -2,4 +2,4 @@
 
 Review completed tasks against memory, plan, policy, tool readiness, and evidence.
 
-Follow plugin command `commands/cairn-review.md`.
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve `resources.commands` from that JSON object and follow `cairn-review.md` in that directory. Do not resolve Cairn command files from the target project.

package/.claude/commands/cairn-toolcheck.md

@@ -2,9 +2,6 @@
 
 Detect repository stacks and check required LSP, typecheck, lint, dry-run, and verification tools.
 
-```sh
-node scripts/cairn.mjs toolcheck
-node scripts/cairn.mjs toolcheck --install
-```
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Invoke Node directly with the absolute `entrypoints.cli` value, `toolcheck`, and an explicit `--root` pointing at the target repository; do not build a shell-interpolated command from the path.
 
-Use `--install` before accepting a missing required tool as unavailable.
+If required tools are missing, report the proposed install and obtain explicit user approval. Only then add `--install --yes` for a pinned/supported installer or use the approved repository-native command.

package/.claude/commands/cairn-uninstall.md

@@ -2,12 +2,4 @@
 
 Remove the Codex, Claude Code, and Antigravity entries installed by Cairn.
 
-```sh
-node scripts/cairn.mjs uninstall
-```
-
-Published package:
-
-```sh
-bunx cairn-ai@latest uninstall
-```
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Invoke Node directly with the absolute `entrypoints.cli` value and the argument array `["uninstall"]`; do not build a shell-interpolated command from the path.

package/.claude/commands/cairn-upgrade.md

@@ -2,11 +2,7 @@
 
 Update the Cairn installation from the current source.
 
-```sh
-node scripts/cairn.mjs upgrade
-```
-
-Published package:
+Upgrade must run from the package/global source because the cached installation is replaced. Do not invoke upgrade from the cached plugin locator.
 
 ```sh
 bunx cairn-ai@latest upgrade

package/.claude/commands/cairn-work.md

@@ -4,4 +4,4 @@ Start by reading the project-root `MEMORY.md`, then execute the next incomplete
 
 If the user asks a side question, status question, or narrow clarification while a task is still active, answer it briefly and then resume the previous active work unless the user explicitly asks to pause, stop, or switch tasks.
 
-Follow plugin command `commands/cairn-work.md`.
+Read the installed Cairn runtime locator at `{{CAIRN_RUNTIME_LOCATOR_JSON}}`. Resolve `resources.commands` from that JSON object and follow `cairn-work.md` in that directory. Do not resolve Cairn command files from the target project.

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cairn",
-  "version": "0.1.11",
+  "version": "0.2.0",
   "description": "Token-efficient agent harness with tool readiness for Codex, Claude Code, and Antigravity.",
   "author": {
     "name": "WkNam"
@@ -24,6 +24,7 @@
       "Use Cairn to create MEMORY.md and PLAN.md for this repository.",
       "At the start of each task, every agent must read the project-root MEMORY.md for domain knowledge and repository policy before planning, implementation, review, or delegation.",
       "Run cairn-toolcheck before planning implementation work.",
+      "Resolve Cairn scripts, templates, commands, agents, and model guidance from the installed plugin runtime locator; never search for those runtime files in the target repository. Keep the target repository root separate and pass it explicitly to Cairn commands.",
       "Before non-trivial implementation, run cairn-plan for this task without asking me for discoverable facts.",
       "When planning, first understand the whole work, then classify it into small executable tasks; if a task needs further breakdown, split it into sub-tasks.",
       "The user-called/main agent is the orchestrator: plan, assign, verify, and record evidence; actual implementation edits must be delegated to worker subagents whenever subagent tools are available, on both Light Path and Heavy Path.",
@@ -33,6 +34,10 @@
       "If subagent tools are unavailable, the main agent takes over implementation directly and records that takeover in evidence; do not stop before local implementation solely because subagent tools are unavailable.",
       "Record Light Path or Heavy Path complexity triage in docs/plan/<topic>.md before mutating files.",
       "Run cairn-work from the current PLAN.md and pass dry-run/check, module acceptance, and surface integration gates.",
+      "For implementation requests, persist one active Cairn goal with stable task IDs. After a task passes its required bound receipts, advance immediately to the next task and continue until goal-level final review completes; active is never a completion state.",
+      "Missing, failed, skipped, stale, or placeholder evidence never completes a task. A worker may report only its assigned task; the main agent reviews the handoff and advances the goal.",
+      "If progress cannot continue, explicitly pause, block with a concrete reason, or cancel the Cairn goal instead of silently stopping. Do not repeatedly block a re-entered stop hook in the same turn.",
+      "Tool installation is an external-state change: report the proposal and obtain explicit user approval before using a pinned/supported installer.",
       "If I ask a side question, status question, or narrow clarification while a plan or task is still active, answer it briefly and then resume the previous active work unless I explicitly ask you to pause, stop, or switch tasks."
     ]
   }

package/README.de.md

@@ -33,8 +33,8 @@ Der gewählte path und die Begründung werden in `docs/plan/<topic>.md` festgeha
 `cairn toolcheck` untersucht das aktuelle repository auf JavaScript-, TypeScript-, Python-, PHP-, Java-, Kotlin-, Swift-, Go- und Rust-stacks und prüft die passenden LSP- und verification tools.
 
 ```sh
-cairn toolcheck
-cairn toolcheck --install
+cairn toolcheck --root .
+cairn toolcheck --install --yes --root .
 ```
 
 - `toolcheck` meldet detected stacks und missing tools.
@@ -57,7 +57,7 @@ Cairn wendet model-specific adjustment nur auf Claude-family und Codex-family mo
 - Claude-family: geeignet für long context, policy interpretation und plan/evidence review.
 - Codex-family: geeignet für small implementation tasks, explicit file edits, command-based verification und bounded `worker` tasks.
 
-Details stehen in `docs/model-guidance/README.md`, `docs/model-guidance/claude.md` und `docs/model-guidance/codex.md`.
+Details stehen im installierten Plugin unter `cairn://docs/model-guidance/README.md`, `cairn://docs/model-guidance/claude.md` und `cairn://docs/model-guidance/codex.md`.
 
 ## Repository Artifacts
 
@@ -65,7 +65,7 @@ Das harness erstellt und pflegt diese files im Ziel-repository root.
 
 - `MEMORY.md`: kurzer Index persistent domain knowledge.
 - `docs/memory/*.md`: detailliertes Wissen je domain.
-- `docs/model-guidance/*.md`: Claude- und Codex-model adjustment guidance.
+- `.cairn/state.json`: git-ignorierter Goal-, Task- und Receipt-Status für Wiederaufnahme und scoped stop gates.
 - `PLAN.md`: kurzer Index aktiver und abgeschlossener work topics.
 - `docs/plan/*.md`: detailed execution plans.
 

package/README.es.md

@@ -33,8 +33,8 @@ El path seleccionado y su justificación se registran en `docs/plan/<topic>.md`
 `cairn toolcheck` inspecciona el repositorio actual para stacks JavaScript, TypeScript, Python, PHP, Java, Kotlin, Swift, Go y Rust, y luego revisa los LSP y verification tools correspondientes.
 
 ```sh
-cairn toolcheck
-cairn toolcheck --install
+cairn toolcheck --root .
+cairn toolcheck --install --yes --root .
 ```
 
 - `toolcheck` reporta detected stacks y missing tools.
@@ -57,7 +57,7 @@ Cairn solo aplica ajustes específicos de modelo a modelos Claude-family y Codex
 - Claude-family: útil para long context, policy interpretation y plan/evidence review.
 - Codex-family: útil para small implementation tasks, explicit file edits, command-based verification y bounded `worker` tasks.
 
-La guía detallada vive en `docs/model-guidance/README.md`, `docs/model-guidance/claude.md` y `docs/model-guidance/codex.md`.
+La guía detallada vive en el plugin instalado y se referencia como `cairn://docs/model-guidance/README.md`, `cairn://docs/model-guidance/claude.md` y `cairn://docs/model-guidance/codex.md`.
 
 ## Repository Artifacts
 
@@ -65,7 +65,7 @@ El harness crea y mantiene estos archivos en la raíz del repositorio objetivo.
 
 - `MEMORY.md`: índice corto de conocimiento persistente del dominio.
 - `docs/memory/*.md`: conocimiento detallado por dominio.
-- `docs/model-guidance/*.md`: guía de ajuste de modelos Claude y Codex.
+- `.cairn/state.json`: estado git-ignored de goal, task y receipt para reanudación y stop gates acotados.
 - `PLAN.md`: índice corto de temas activos y completados.
 - `docs/plan/*.md`: planes de ejecución detallados.
 

package/README.fr.md

@@ -33,8 +33,8 @@ Le path choisi et sa justification sont enregistrés dans `docs/plan/<topic>.md`
 `cairn toolcheck` inspecte le repository courant pour les stacks JavaScript, TypeScript, Python, PHP, Java, Kotlin, Swift, Go et Rust, puis vérifie les LSP et verification tools correspondants.
 
 ```sh
-cairn toolcheck
-cairn toolcheck --install
+cairn toolcheck --root .
+cairn toolcheck --install --yes --root .
 ```
 
 - `toolcheck` signale les detected stacks et missing tools.
@@ -57,7 +57,7 @@ Cairn applique des ajustements spécifiques uniquement aux modèles Claude-famil
 - Claude-family : utile pour long context, policy interpretation et plan/evidence review.
 - Codex-family : utile pour small implementation tasks, explicit file edits, command-based verification et bounded `worker` tasks.
 
-Les détails se trouvent dans `docs/model-guidance/README.md`, `docs/model-guidance/claude.md` et `docs/model-guidance/codex.md`.
+Les détails se trouvent dans le plugin installé sous `cairn://docs/model-guidance/README.md`, `cairn://docs/model-guidance/claude.md` et `cairn://docs/model-guidance/codex.md`.
 
 ## Repository Artifacts
 
@@ -65,7 +65,7 @@ Le harness crée et maintient ces fichiers à la racine du repository cible.
 
 - `MEMORY.md` : index court de persistent domain knowledge.
 - `docs/memory/*.md` : connaissances détaillées par domaine.
-- `docs/model-guidance/*.md` : guidance d'ajustement pour les modèles Claude et Codex.
+- `.cairn/state.json` : état git-ignored des goals, tasks et receipts pour la reprise et les stop gates ciblés.
 - `PLAN.md` : index court des sujets actifs et terminés.
 - `docs/plan/*.md` : detailed execution plans.
 

package/README.ja.md

@@ -33,8 +33,8 @@ Cairn は execution policy では LazyCodex と異なります。LazyCodex の r
 `cairn toolcheck` は現在の repository から JavaScript、TypeScript、Python、PHP、Java、Kotlin、Swift、Go、Rust stacks を検出し、対応する LSP と verification tools を確認します。
 
 ```sh
-cairn toolcheck
-cairn toolcheck --install
+cairn toolcheck --root .
+cairn toolcheck --install --yes --root .
 ```
 
 - `toolcheck` は detected stacks と missing tools を報告します。
@@ -57,7 +57,7 @@ Cairn は Claude-family と Codex-family models にのみ model-specific adjustm
 - Claude-family: long context、policy interpretation、plan/evidence review に有用です。
 - Codex-family: small implementation tasks、explicit file edits、command-based verification、bounded `worker` tasks に有用です。
 
-詳細は `docs/model-guidance/README.md`、`docs/model-guidance/claude.md`、`docs/model-guidance/codex.md` にあります。
+詳細はインストール済みプラグインの `cairn://docs/model-guidance/README.md`、`cairn://docs/model-guidance/claude.md`、`cairn://docs/model-guidance/codex.md` にあります。
 
 ## Repository Artifacts
 
@@ -65,7 +65,7 @@ harness は対象 repository root に次の files を作成して維持します
 
 - `MEMORY.md`: persistent domain knowledge の短い index。
 - `docs/memory/*.md`: domain ごとの詳細 knowledge。
-- `docs/model-guidance/*.md`: Claude と Codex model adjustment guidance。
+- `.cairn/state.json`: 再開と scoped stop gate のための git-ignored goal/task/receipt 状態。
 - `PLAN.md`: active/completed work topics の短い index。
 - `docs/plan/*.md`: detailed execution plans。
 

package/README.ko.md

@@ -37,12 +37,14 @@ subagent 도구가 progress-reporting channel을 제공하면 subagent는 작업
 `cairn toolcheck`는 현재 저장소에서 JavaScript, TypeScript, Python, PHP, Java, Kotlin, Swift, Go, Rust 스택을 감지하고, 해당 LSP와 검증 도구를 확인합니다.
 
 ```sh
-cairn toolcheck
-cairn toolcheck --install
+cairn toolcheck --root .
+# 명시적 승인을 받은 경우에만:
+cairn toolcheck --install --yes --root .
 ```
 
 - `toolcheck`는 감지된 스택과 누락 도구를 보고합니다.
-- `toolcheck --install`은 package manager dev dependency, Composer dev dependency, `uv`, Java LSP bootstrap, `go install`, `rustup component add` 같은 가장 가까운 프로젝트 로컬 또는 저장소 네이티브 설치 경로를 시도합니다.
+- 기본 검사는 읽기 전용이고 timeout으로 제한되며, 저장소 로컬 wrapper를 단순 탐지를 위해 실행하지 않습니다.
+- `toolcheck --install`은 사용자의 명시적 승인과 `--yes`를 모두 요구합니다. 버전이 고정되지 않았거나 checksum이 없는 installer는 `latest`를 내려받는 대신 사용할 수 없는 것으로 보고합니다.
 - Cairn 계획은 감지된 스택, 필요한 도구, 설치 명령, blocker를 기록합니다.
 - LSP server가 없다는 사실만으로 정밀한 코드베이스 탐색을 건너뛸 수 없습니다. 설치 또는 동등한 symbol-aware fallback을 먼저 시도해야 합니다.
 
@@ -61,7 +63,7 @@ Cairn은 Claude-family와 Codex-family 모델에만 모델별 조정을 적용
 - Claude-family: 긴 컨텍스트, 정책 해석, 계획/증거 검토에 유용합니다.
 - Codex-family: 작은 구현 작업, 명시적 파일 편집, command 기반 검증, 제한된 `worker` 작업에 유용합니다.
 
-자세한 가이드는 `docs/model-guidance/README.md`, `docs/model-guidance/claude.md`, `docs/model-guidance/codex.md`에 있습니다.
+자세한 가이드는 설치된 플러그인에 있으며 `cairn://docs/model-guidance/README.md`, `cairn://docs/model-guidance/claude.md`, `cairn://docs/model-guidance/codex.md`로 참조합니다.
 
 ## Repository Artifacts
 
@@ -69,11 +71,11 @@ Cairn은 Claude-family와 Codex-family 모델에만 모델별 조정을 적용
 
 - `MEMORY.md`: 지속 도메인 지식의 짧은 색인.
 - `docs/memory/*.md`: 도메인별 상세 지식.
-- `docs/model-guidance/*.md`: Claude와 Codex 모델 조정 가이드.
 - `PLAN.md`: 활성/완료 작업 주제의 짧은 색인.
 - `docs/plan/*.md`: 상세 실행 계획.
+- `.cairn/state.json`: 중단 재개와 범위가 제한된 종료 게이트에 쓰는 git-ignored 버전드 goal/task/receipt 상태.
 
-루트 파일은 짧게 유지하고 상세 내용은 `docs/` 아래로 이동해, 에이전트가 필요한 컨텍스트만 읽도록 합니다.
+런타임 script, template, command, agent, model guidance는 설치된 플러그인 루트에 유지합니다. 각 표면의 locator가 같은 설치본을 가리키므로 대상 저장소에 Cairn 내부 파일을 복사하지 않습니다.
 
 ## Commands
 
@@ -103,12 +105,13 @@ cairn toolcheck
 - `cairn doctor`: Codex 설정, 설치, hook trust state, Claude Code mirror 파일, Antigravity mirror 파일을 진단합니다.
 - `cairn uninstall`: Cairn이 추가한 Codex 설정, cache, Claude Code mirror 파일, Antigravity mirror 파일을 제거합니다.
 - `cairn toolcheck`: 저장소 스택을 감지하고 필요한 LSP와 검증 도구를 확인하거나 설치합니다.
+- `cairn goal ...`: 저장소의 영속 goal을 시작·조회·일시정지·재개·차단·취소·완료합니다. task 완료에는 현재 goal/task/plan에 바인딩된 성공 receipt가 필요합니다.
 - `cairn-memory`: 도메인 지식을 탐색하고 `MEMORY.md`를 갱신합니다.
 - `cairn-plan`: `docs/plan/` 아래에 decision-complete plan을 만듭니다.
 - `cairn-work`: 현재 `PLAN.md`의 다음 모듈 작업을 실행하고 두 검증 게이트를 확보합니다.
 - `cairn-review`: 계획, memory, 증거를 기준으로 완료된 작업을 검토합니다.
 
-`install`과 `upgrade`는 `~/.codex/config.toml`을 수정하기 전에 `*.cairn-backup-*` 백업을 만듭니다. 소스 플러그인 manifest는 validator-friendly 상태를 유지하고, 설치된 cache copy에만 Codex hook 활성화를 위한 `hooks` field가 추가됩니다.
+`install`과 `upgrade`는 `~/.codex/config.toml`을 수정하기 전에 `*.cairn-backup-*` 백업을 만들고 각 표면의 runtime locator를 갱신합니다. 소스 플러그인 manifest는 validator-friendly 상태를 유지하고, 설치된 cache copy에만 Codex hook 활성화를 위한 `hooks` field가 추가됩니다. 현재 custom lifecycle은 유지하며, upgrade는 교체 대상인 cache copy가 아니라 게시/전역 package에서 실행해야 합니다.
 
 Codex는 `skills/`와 `commands/`를 사용합니다. Claude Code는 `.claude/` 아래의 mirror command와 agent definition을 사용합니다. Antigravity는 `.agents/workflows`와 global skills mirror를 사용합니다.
 

package/README.md

@@ -45,12 +45,14 @@ When a delegated subagent finishes, it provides a final report before leaving. A
 `cairn toolcheck` inspects the current repository for JavaScript, TypeScript, Python, PHP, Java, Kotlin, Swift, Go, and Rust stacks, then checks the matching LSP and verification tools.
 
 ```sh
-cairn toolcheck
-cairn toolcheck --install
+cairn toolcheck --root .
+# After explicit approval only:
+cairn toolcheck --install --yes --root .
 ```
 
 - `toolcheck` reports detected stacks and missing tools.
-- `toolcheck --install` attempts the closest project-local or repository-native install path, such as package-manager dev dependencies, Composer dev dependencies, `uv`, Java LSP bootstrap, `go install`, or `rustup component add`.
+- Default checks are read-only, bounded by a timeout, and do not execute repository-local wrappers merely to discover them.
+- `toolcheck --install` requires both `--yes` and explicit user approval. Unpinned or checksum-free installers are unavailable rather than silently downloading `latest`.
 - Cairn plans record detected stack, required tools, install commands, and blockers.
 - A missing LSP server is not a valid reason to skip precise codebase exploration until installation or an equivalent symbol-aware fallback has been attempted.
 
@@ -69,7 +71,7 @@ Cairn only applies model-specific adjustment to Claude-family and Codex-family m
 - Claude-family: useful for long context, policy interpretation, and plan/evidence review.
 - Codex-family: useful for small implementation tasks, explicit file edits, command-based verification, and bounded `worker` tasks.
 
-Detailed guidance lives in `docs/model-guidance/README.md`, `docs/model-guidance/claude.md`, and `docs/model-guidance/codex.md`.
+Detailed guidance lives in the installed plugin and is referenced as `cairn://docs/model-guidance/README.md`, `cairn://docs/model-guidance/claude.md`, and `cairn://docs/model-guidance/codex.md`.
 
 ## Repository Artifacts
 
@@ -77,11 +79,11 @@ The harness creates and maintains these files at the target repository root.
 
 - `MEMORY.md`: short index of persistent domain knowledge.
 - `docs/memory/*.md`: detailed knowledge by domain.
-- `docs/model-guidance/*.md`: Claude and Codex model adjustment guidance.
 - `PLAN.md`: short index of active and completed work topics.
 - `docs/plan/*.md`: detailed execution plans.
+- `.cairn/state.json`: git-ignored, versioned active goal/task/receipt state used for interruption recovery and scoped stop gates.
 
-Root files stay short and details move under `docs/`, so agents only read the context they need.
+Runtime scripts, templates, commands, agents, and model guidance stay in the installed plugin root. Runtime locator files let Codex, Claude Code, and Antigravity share that installed copy without copying Cairn internals into the target repository.
 
 ## Commands
 
@@ -111,12 +113,13 @@ cairn toolcheck
 - `cairn doctor`: diagnoses Codex settings, installation, hook trust state, Claude Code mirror files, and Antigravity mirror files.
 - `cairn uninstall`: removes Cairn-added Codex settings, cache, Claude Code mirror files, and Antigravity mirror files.
 - `cairn toolcheck`: detects repository stacks and checks or installs required LSP and verification tools.
+- `cairn goal ...`: starts, inspects, pauses, resumes, blocks, cancels, and completes a persisted repository goal; task completion requires bound successful receipts.
 - `cairn-memory`: explores domain knowledge and updates `MEMORY.md`.
 - `cairn-plan`: creates a decision-complete plan under `docs/plan/`.
 - `cairn-work`: executes the next module task in the current `PLAN.md` with two verification gates.
 - `cairn-review`: reviews completed tasks against plan, memory, and evidence.
 
-Install and upgrade create `*.cairn-backup-*` backups before modifying `~/.codex/config.toml`. The source plugin manifest stays validator-friendly; only the installed cache copy gets a `hooks` field to activate Codex hooks.
+Install and upgrade create `*.cairn-backup-*` backups before modifying `~/.codex/config.toml`. They also write runtime locators for every surface. The source plugin manifest stays validator-friendly; only the installed cache copy gets a `hooks` field to activate Codex hooks. The current custom lifecycle remains in use; lifecycle upgrade should run from the published/global package, not from the cached copy that it replaces.
 
 Codex uses `skills/` and `commands/`. Claude Code uses mirrored commands and agent definitions under `.claude/`. Antigravity uses `.agents/workflows` and global skills mirrors.
 

package/README.pt.md

@@ -33,8 +33,8 @@ O path escolhido e sua justificativa sao registrados em `docs/plan/<topic>.md` q
 `cairn toolcheck` inspeciona o repositorio atual para stacks JavaScript, TypeScript, Python, PHP, Java, Kotlin, Swift, Go e Rust, depois verifica os LSP e verification tools correspondentes.
 
 ```sh
-cairn toolcheck
-cairn toolcheck --install
+cairn toolcheck --root .
+cairn toolcheck --install --yes --root .
 ```
 
 - `toolcheck` informa detected stacks e missing tools.
@@ -57,7 +57,7 @@ Cairn aplica model-specific adjustment apenas a modelos Claude-family e Codex-fa
 - Claude-family: util para long context, policy interpretation e plan/evidence review.
 - Codex-family: util para small implementation tasks, explicit file edits, command-based verification e bounded `worker` tasks.
 
-A orientacao detalhada fica em `docs/model-guidance/README.md`, `docs/model-guidance/claude.md` e `docs/model-guidance/codex.md`.
+A orientação detalhada fica no plugin instalado em `cairn://docs/model-guidance/README.md`, `cairn://docs/model-guidance/claude.md` e `cairn://docs/model-guidance/codex.md`.
 
 ## Repository Artifacts
 
@@ -65,7 +65,7 @@ O harness cria e mantem estes arquivos na raiz do repositorio alvo.
 
 - `MEMORY.md`: indice curto de persistent domain knowledge.
 - `docs/memory/*.md`: conhecimento detalhado por dominio.
-- `docs/model-guidance/*.md`: Claude and Codex model adjustment guidance.
+- `.cairn/state.json`: estado git-ignored de goal, task e receipt para retomada e stop gates com escopo.
 - `PLAN.md`: indice curto de active and completed work topics.
 - `docs/plan/*.md`: detailed execution plans.
 

package/README.zh.md

@@ -33,8 +33,8 @@ Cairn 在 execution policy 上刻意不同于 LazyCodex。它不采用 LazyCodex
 `cairn toolcheck` 会检查当前 repository 中的 JavaScript、TypeScript、Python、PHP、Java、Kotlin、Swift、Go 和 Rust stacks，然后检查匹配的 LSP 和 verification tools。
 
 ```sh
-cairn toolcheck
-cairn toolcheck --install
+cairn toolcheck --root .
+cairn toolcheck --install --yes --root .
 ```
 
 - `toolcheck` 报告 detected stacks 和 missing tools。
@@ -57,7 +57,7 @@ Cairn 只对 Claude-family 和 Codex-family models 应用 model-specific adjustm
 - Claude-family: 适合 long context、policy interpretation 和 plan/evidence review。
 - Codex-family: 适合 small implementation tasks、explicit file edits、command-based verification 和 bounded `worker` tasks。
 
-详细指南位于 `docs/model-guidance/README.md`、`docs/model-guidance/claude.md` 和 `docs/model-guidance/codex.md`。
+详细指南位于已安装插件的 `cairn://docs/model-guidance/README.md`、`cairn://docs/model-guidance/claude.md` 和 `cairn://docs/model-guidance/codex.md`。
 
 ## Repository Artifacts
 
@@ -65,7 +65,7 @@ harness 会在目标 repository root 创建并维护这些文件。
 
 - `MEMORY.md`: persistent domain knowledge 的短索引。
 - `docs/memory/*.md`: 按 domain 记录的详细 knowledge。
-- `docs/model-guidance/*.md`: Claude 和 Codex model adjustment guidance。
+- `.cairn/state.json`: 用于中断恢复和 scoped stop gate 的 git-ignored goal/task/receipt 状态。
 - `PLAN.md`: active 和 completed work topics 的短索引。
 - `docs/plan/*.md`: detailed execution plans。
 

package/commands/cairn-doctor.md

@@ -2,13 +2,7 @@
 
 Goal: diagnose Cairn installation status.
 
-Run:
-
-```sh
-node scripts/cairn.mjs doctor
-```
-
-With the published package:
+Run from the published or global package:
 
 ```sh
 bunx cairn-ai@latest doctor
@@ -26,3 +20,4 @@ Checks:
 - hook trust state.
 - Claude Code commands and agents mirror files.
 - Antigravity IDE/CLI skills and workflows mirror files.
+- Installed runtime locators and their referenced scripts, templates, and model guidance.