cairn-ai 0.5.0 → 0.7.0

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

@@ -4,10 +4,13 @@ Goal: diagnose Cairn installation status.
 
 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.
 
+The first output line is `Hosts: <ids>`; only the selected hosts are checked. A legacy installation is reported with a hint to run `cairn upgrade`.
+
 Checks:
 
+- Canonical runtime under `~/.cairn/install/runtime/<version>/`.
 - Codex plugin, marketplace, hook trust state.
-- Claude Code commands and agents mirror files.
+- Claude Code commands and agents mirror files, plugin registration, and `Claude plugin cache version`.
 - 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,6 +8,8 @@ Run:
 bunx cairn-ai@latest 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.
+Add `--hosts all` or a comma list of `codex`, `claude`, `antigravity` to choose hosts; without it a first install at a terminal asks once, and non-interactive runs install every host. The canonical runtime goes to `~/.cairn/install/runtime/<version>/` (`CAIRN_HOME` overrides `~/.cairn`), and automatic upgrades are on by default (`cairn auto-upgrade status|on|off|run`). If the installed version is newer than this CLI, install refuses without changes; add `--allow-downgrade` to install this version anyway.
+
+Installation must run from the package/global source because the installed copy (`~/.cairn/install/` or the Codex plugin cache) 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

@@ -12,6 +12,6 @@ Procedure:
 2. Every agent reads project-root `MEMORY.md` when present and continues without repository memory when absent before assigned discovery or update work.
 3. Explore repository facts with focused tools.
 4. Use `explorer` for read-only domain discovery and contradiction checks when available; use `worker` for exact references, command checks, and bounded evidence capture. When subagent tools are available, each agent may recursively delegate bounded sub-tasks to subagents. Tell every delegated agent and child subagent to read the project-root `MEMORY.md` before work, keep scope, and preserve others' edits.
-5. Write details to `docs/memory/<domain>.md`. When a lesson or correction recurs and is machine-checkable, encode it as a test, lint rule, script, or hook instead of more prose; memory keeps judgment rules and a pointer to the enforcing check.
-6. Keep `MEMORY.md` as a short index.
+5. Write details to `docs/memory/<domain>.md` with a `Summary:` line under the H1 (one line, at most 120 characters: what the note answers and when to read it). When a lesson or correction recurs and is machine-checkable, encode it as a test, lint rule, script, or hook instead of more prose; memory keeps judgment rules and a pointer to the enforcing check.
+6. Keep `MEMORY.md` as a short index: one line per note under `## Domain Knowledge`; a note link in another section is a mention that `index` never rewrites. Run the installed Cairn CLI with `memory index --root <repoRoot>` to add unlisted notes and refresh changed summaries (`--dry-run` previews; it never deletes entries and writes nothing when the insertion point is inside an unclosed code fence), then `memory check --root <repoRoot>` and fix the unindexed notes, dead links, duplicates, stale summaries, or control characters it reports.
 7. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts unless the user asks for another language.

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

@@ -13,9 +13,9 @@ Complexity is staged: request checkpoint, planning checkpoint after exploration,
 Procedure:
 
 1. Every agent reads project-root `MEMORY.md` when present and continues without repository memory when absent before repository exploration, tool selection, work, or delegation.
-2. For non-trivial implementation or continuation of planned work, write an initial `docs/plan/<topic>.md` and `PLAN.md` entry with `triage-plan` as the first active task. This initial plan is decision-complete for triage and explicitly not implementation-ready.
+2. For non-trivial implementation or continuation of planned work, write an initial `docs/plan/<topic>.md` and `PLAN.md` entry with `triage-plan` as the first active task. The `PLAN.md` entry is one line of 200 characters or fewer under `## Active Plans`; the installed Cairn CLI's `plan index --root <repoRoot>` adds missing entries and `plan check --root <repoRoot>` verifies them. This initial plan is decision-complete for triage and explicitly not implementation-ready.
 3. Before exploration, toolcheck, triage, or delegation, call Codex `update_plan` and then `create_goal` when available (main agent only; subagents skip), and start the repository Cairn goal with the same roadmap. Copy the session-start hook's `Cairn CLI:` prefix literally into each command; never store it in a shell variable. `--root` may be omitted when the cwd is inside the repository. Fold new work into an unfinished goal with `goal replan` instead of cancelling it; when a hook reports another session owns the goal you continue, run `goal claim --session <id>`.
-4. Read relevant `docs/memory/*.md` and, under the locator's `resources.modelGuidance`, `claude.md` for Claude-family or `codex.md` for Codex-family models; invoke Node with the locator's absolute `entrypoints.cli`, `toolcheck`, and `--root` for the target repository (installation only with explicit approval), and explore before asking the user.
+4. Reuse before exploring: pick related `docs/memory` notes from the `MEMORY.md` entries and at most 3 completed plans from `PLAN.md` (older ones in `docs/plan/ARCHIVE.md`) that changed the same modules or solved the same kind of problem; read only those plans' goal, design decisions, and evidence, and record the picks in the plan's `## Memory Inputs` with `Related completed plans:` (or `none related`). Read the picked notes and, under the locator's `resources.modelGuidance`, `claude.md` for Claude-family or `codex.md` for Codex-family models; invoke Node with the locator's absolute `entrypoints.cli`, `toolcheck`, and `--root` for the target repository (installation only with explicit approval), and explore before asking the user.
 5. Classify the whole work into executable tasks with `dependsOn`, `writeScope`, and handoff files, finalize triage, and update the same plan and `update_plan` roadmap to a decision-complete implementation plan: selected path, checked Heavy Path signals, tool readiness, file scope, dry-run/check, module acceptance, surface integration, stable IDs, and fail-closed evidence. Heavy Path adds an explicit automated test command and `Tests:` evidence line.
 6. Resolve the skill's reference files through the locator's `pluginRoot` and read them only when needed: `cairn://skills/cairn-plan/planning-rules.md` when finalizing, `cairn://skills/cairn-plan/delegation.md` before dispatching, `cairn://skills/cairn-plan/heavy-path.md` only on a Heavy signal or route change.
 7. The user-called/main agent orchestrates; implementation edits go to `worker` when subagent tools are available, otherwise the main agent takes over and records it. Advance a UI step only after the matching repository task transition succeeds with its required bound evidence.

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

@@ -9,7 +9,7 @@ Goal: review completed work against plan, memory, policy, and evidence.
 Procedure:
 
 1. Every agent reads project-root `MEMORY.md` when present and continues without repository memory when absent before review work, then reads the plan task and available memory inputs.
-2. Check changed files, tool readiness evidence, and verification evidence. Inspect test, fixture, and verification-command diffs and reject any weakening without a recorded plan reason. For defect fixes, confirm the same-rule sweep was performed and its result recorded.
+2. Check changed files, tool readiness evidence, and verification evidence. Inspect test, fixture, and verification-command diffs and reject any weakening without a recorded plan reason. For defect fixes, confirm the same-rule sweep was performed and its result recorded. Confirm the plan's Evidence has a filled `Memory promotion:` line (`docs/memory/<domain>.md` or `none: <reason>`) and that the installed Cairn CLI's `memory check --root <repoRoot>` and `plan check --root <repoRoot>` exit 0. A `none: <reason>` decision is acceptable: do not create a note or demand one; flag a missing or placeholder line, or a named note that does not exist.
 3. Delegate independent read-only review to `explorer` when it materially improves speed or quality; use `worker` only for scoped verification reruns or QA artifacts. When subagent tools are available, each agent may recursively delegate bounded sub-tasks to subagents. Tell every delegated agent and child subagent to read the project-root `MEMORY.md` before work, keep scope, and preserve others' edits.
 4. Report findings first, ordered by severity, with file and line references. If no issues are found, say so clearly and mention remaining test gaps or residual risk.
 5. Record review evidence in `docs/plan/<topic>.md`.

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

@@ -4,4 +4,6 @@ Goal: remove the Codex, Claude Code, and Antigravity entries installed by Cairn.
 
 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.
+Uninstall removes the managed entries of the recorded hosts and retained runtimes, then removes `~/.cairn/install/` only when it is empty. It removes the auto-upgrade state files in `~/.cairn/update/`, removes `update/stage/` only when no auto-upgrade runner holds `update/update.lock`, and removes `~/.cairn/update/` only when it is empty. An installation made by Cairn 0.6.0 or earlier is removed in place without migrating.
+
+The source work folder, user-created `MEMORY.md`, `PLAN.md`, `docs/memory`, and `docs/plan` files, goal state in `~/.cairn/projects/`, and `~/.cairn/config.json` are not deleted.

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

@@ -8,6 +8,8 @@ Run:
 bunx cairn-ai@latest upgrade
 ```
 
-Upgrade must run from the package/global source because the cached plugin is replaced. Do not invoke upgrade from a cached plugin locator.
+Upgrade keeps the recorded hosts unless `--hosts` changes them, moves an installation made by Cairn 0.6.0 or earlier to `~/.cairn/install/` in one run, keeps the previous runtime for 3 days, and refreshes a stale Claude Code plugin cache. If the installed version is newer than this CLI, upgrade refuses without changes; add `--allow-downgrade` to move back to this version anyway. Restart sessions that were open during a migration.
+
+Upgrade must run from the package/global source because the installed copy (`~/.cairn/install/` or the Codex plugin cache) 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

@@ -18,7 +18,7 @@ Procedure:
 6. Run module acceptance and surface integration through `goal verify -- ...`; `--kind "moduleAcceptance|surfaceIntegration"` records both from one run. Treat tool exit codes as authoritative and expand context only around failing tests. Heavy Path records explicit `Tests:` evidence.
 7. Never edit, weaken, skip, or delete existing tests, fixtures, or verification commands to make a gate pass unless the plan records the contract change. Reproduce reported defects before fixing, and after a fix search for other implementations of the same rule or pattern.
 8. Inspect package lifecycle scripts and run normal `npm pack --dry-run` by default. Content-producing or unknown lifecycle scripts must never use `--ignore-scripts`; only absent or proven content-neutral scripts may use it while the full check remains fresh.
-9. Relevant mutation makes the current task's evidence stale; rerun it before completing the task. Do not rerun earlier tasks' checks; finish with one goal-level check through `goal finish -- ...`. Missing, failed, skipped, stale, or placeholder evidence never completes work. `goal stats` measures receipt reruns.
+9. Relevant mutation makes the current task's evidence stale; rerun it before completing the task. Do not rerun earlier tasks' checks; finish with one goal-level check through `goal finish -- ...`. Missing, failed, skipped, stale, or placeholder evidence never completes work. `goal stats` measures receipt reruns; `goal stats --history` compares finished goals of the repository.
 10. Resolve the skill's reference files through the locator's `pluginRoot` and read them only when needed: `cairn://skills/cairn-work/verification.md`, `cairn://skills/cairn-work/delegation.md`, `cairn://skills/cairn-work/recovery.md`, and `cairn://skills/cairn-work/heavy-path.md` (Heavy route only).
-11. Update the plan, goal state, and `PLAN.md` only after evidence exists. If the user asks a side question, status question, or narrow clarification while this 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.
+11. Before `goal finish`, record the memory promotion decision in the plan's Evidence: `Memory promotion: docs/memory/<domain>.md` when the goal produced reusable repository knowledge (write the note with a `Summary:` line, then run `memory index --root <repoRoot>`), otherwise `Memory promotion: none: <reason>`. The line is required and the note is optional: do not create a note when nothing qualifies. Update the plan, goal state, and `PLAN.md` only after evidence exists. If the user asks a side question, status question, or narrow clarification while this 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.
 12. Use the OS locale for user-visible responses and generated or updated documentation, plans, and memory artifacts unless the user asks for another language.

package/.claude/agents/explorer.md

@@ -2,6 +2,6 @@
 
 Read-only discovery agent for codebase questions, impact analysis, pattern search, and verification.
 
-Before any task, read project-root `MEMORY.md` when present; continue without repository memory when absent.
+Before any task, read project-root `MEMORY.md` when present and open only the `docs/memory/*.md` notes whose entries match the task or that the assignment names; continue without repository memory when absent.
 
 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. If the shared runtime or locator is missing, unreadable, or inconsistent, stop all dependent mirrors and recover with published/global `cairn doctor` followed by `cairn upgrade`; do not repair through another mirror.

package/.claude/agents/worker.md

@@ -2,6 +2,6 @@
 
 Focused execution agent for search, small edits, command checks, and QA artifacts.
 
-Before any task, read project-root `MEMORY.md` when present; continue without repository memory when absent.
+Before any task, read project-root `MEMORY.md` when present and open only the `docs/memory/*.md` notes whose entries match the task or that the assignment names; continue without repository memory when absent.
 
 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. If the shared runtime or locator is missing, unreadable, or inconsistent, stop all dependent mirrors and recover with published/global `cairn doctor` followed by `cairn upgrade`; do not repair through another mirror.

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cairn",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Token-efficient agent harness with tool readiness for Codex, Claude Code, and Antigravity.",
   "author": {
     "name": "WkNam"
@@ -21,7 +21,7 @@
       "Tool Readiness"
     ],
     "defaultPrompt": [
-      "Use Cairn's repository-local PLAN.md and persisted goal state as the recovery spine; read root MEMORY.md first when it exists, and continue without repository memory when it does not.",
+      "Use Cairn's repository-local PLAN.md and persisted goal state as the recovery spine; read root MEMORY.md first when it exists (it indexes docs/memory notes; PLAN.md indexes docs/plan plans — open only the entries the task needs), and continue without repository memory when it does not.",
       "For non-trivial work, load the phase skill (cairn-plan, cairn-work, or cairn-review), then restore the active plan and current-task references before acting.",
       "After compaction, restart, handoff, or delegation, restore optional MEMORY.md → phase skill → active plan → current task references; do not rely on conversation recall.",
       "A missing MEMORY.md never blocks work; fail closed only when active state, its skill, plan, or a required task reference is missing, unreadable, or inconsistent.",

package/README.de.md

@@ -63,11 +63,19 @@ Details stehen im installierten Plugin unter `cairn://docs/model-guidance/README
 
 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.
+- `MEMORY.md`: kurzer Index persistent domain knowledge: eine Zeile pro Notiz unter `## Domain Knowledge` (`- [<name>](docs/memory/<name>.md): <summary>`) plus die `## Policy` des Repositorys.
+- `docs/memory/*.md`: detailliertes Wissen je domain. Jede Notiz beginnt mit einer einzeiligen `Summary:` (höchstens 120 Zeichen), die Index und Hook anzeigen.
 - `~/.cairn/projects/<project-id>/worktrees/<worktree-id>/state.json`: user-home Active-Goal/Task/Evidence-State, getrennt nach Projekt und Worktree, für Wiederaufnahme und scoped stop gates. Der Working Tree besitzt keinen Runtime-State.
-- `PLAN.md`: kurzer Index aktiver und abgeschlossener work topics.
+- `PLAN.md`: kurzer Index der Arbeitspläne: eine Zeile mit höchstens 200 Zeichen pro Plan unter `## Active Plans` und `## Completed Plans`. Planungsregeln stehen im Skill `cairn-plan`, nicht in `PLAN.md`.
 - `docs/plan/*.md`: detailed execution plans.
+- `docs/plan/ARCHIVE.md`: ältere abgeschlossene Einträge, die `cairn plan index --archive` aus `PLAN.md` verschoben hat, neueste zuerst, dazu der Inhalt eines legacy Abschnitts `## Planning Rules` unter `## Legacy Planning Rules`. Listenzeilen vor der ersten `## `-Überschrift gelten weiterhin als indexiert.
+- `~/.cairn/projects/<project-id>/worktrees/<worktree-id>/history.jsonl`: ein Zusammenfassungsdatensatz pro abgeschlossenem oder abgebrochenem goal (die neuesten 200 je Worktree) für `goal stats --history`.
+
+Halten Sie `## Completed Plans` neueste zuerst. `cairn plan index --archive` behält die ersten 20 Einträge und verschiebt den Rest, ohne etwas zu löschen, nach `docs/plan/ARCHIVE.md`; eine älteste-zuerst geführte Liste würde daher die neuesten Pläne archivieren. Prüfen Sie vorher mit `--dry-run`. Bestehende `MEMORY.md`/`PLAN.md` funktionieren ohne Migration: `init` schreibt sie nie um, und `check` meldet das alte Format nur als warning.
+
+Bei `SessionStart` teilt der Hook dem Agenten mit, welche Memory-Notizen existieren (Name und `Summary:`, bei langen Listen eine Zeile nur mit Namen), und ergänzt ohne aktives goal eine Zeile zum Plan-Index: Anzahl der Pläne, aktive Pläne, die zuletzt abgeschlossenen Pläne und `docs/plan/ARCHIVE.md`, falls vorhanden. Bei einem active, paused, blocked oder einer anderen Session gehörenden goal kommt nur die Memory-Liste hinzu, und die Kapsel einer fremden Session zeigt nie Plan-Namen. Ein `UserPromptSubmit` ohne goal ergänzt einen Satz mit der Anzahl der Notizen. Der Hook liest nur Indexdateien und Verzeichnislisten, nie Notizinhalte, und schreibt nichts; ein Repository ohne Notizen und Pläne erhält dieselbe Ausgabe wie bisher.
+
+Vor `goal finish` hält `cairn-work` pro goal einmal eine memory promotion Entscheidung in der Evidence des Plans fest: `Memory promotion: docs/memory/<domain>.md`, wenn das goal wiederverwendbares Repository-Wissen ergeben hat, sonst `Memory promotion: none: <reason>`. Die Entscheidung ist Pflicht, eine Notiz zu schreiben ist optional. Wenn ein goal abgeschlossen wird und seine Plan-Datei keine ausgefüllte Zeile `Memory promotion:` hat, geben `goal finish` und `goal complete` eine einzeilige Erinnerung auf stderr aus, ohne exit code oder stdout zu ändern.
 
 Root files bleiben kurz, Details wandern unter `docs/`, damit agents nur den benötigten context lesen.
 
@@ -94,14 +102,19 @@ cairn upgrade
 cairn doctor
 cairn uninstall
 cairn toolcheck
+cairn auto-upgrade status
 ```
 
-- `cairn install`: installiert transaktional custom marketplace source, versioned runtime, Cairn-eigene config sections und aktuelle host mirrors.
-- `cairn upgrade`: ersetzt nur unveränderte Einträge des ownership manifest nach staged validation und nutzt rollback bei Fehlern.
-- `cairn doctor`: prüft ownership digests, effektive Codex features, den tatsächlichen plugin status und runtime locators ohne Reparatur.
-- `cairn uninstall`: entfernt nur unveränderte verwaltete Einträge; modified oder unmanaged Ziele bleiben als conflict erhalten.
+- `cairn install [--hosts all|codex,claude,antigravity]`: installiert transaktional custom marketplace source, versioned runtime, Cairn-eigene config sections und aktuelle host mirrors. Die canonical runtime liegt unter `~/.cairn/install/`; der Rest wird nur für die gewählten hosts installiert. Ohne `--hosts` fragt die erste Installation in einem Terminal nach den hosts; nicht interaktive Läufe und CI installieren alle hosts.
+- `cairn upgrade [--hosts all|codex,claude,antigravity]`: ersetzt nur unveränderte Einträge des ownership manifest nach staged validation und nutzt rollback bei Fehlern. Behält die aufgezeichneten hosts, sofern `--hosts` sie nicht ändert, migriert eine Installation von Cairn 0.6.0 oder älter und aktualisiert einen Claude Code plugin cache, der noch eine andere Version enthält. Ist die installierte Version neuer als diese CLI, verweigern `install` und `upgrade` ohne Änderung; `--allow-downgrade` installiert trotzdem die Version dieser CLI.
+- `cairn doctor`: prüft ownership digests, effektive Codex features, den tatsächlichen plugin status und runtime locators ohne Reparatur. Gibt zuerst `Hosts: <ids>` aus und prüft nur die gewählten hosts (einschließlich `Claude plugin cache version`). Eine legacy-Installation wird mit dem Hinweis gemeldet, sie mit `cairn upgrade` zu migrieren.
+- `cairn uninstall`: prüft zuerst jeden Nicht-config-Eintrag des ownership manifest gegen seinen installed digest und verweigert das ganze uninstall ohne Änderung, wenn ein managed artifact verändert oder entfernt wurde. Andernfalls entfernt es die verwalteten Einträge und retained runtimes bzw. stellt sie wieder her, räumt leere managed scaffolds auf, bewahrt unmanaged Ziele und ihre übergeordneten Verzeichnisse und nutzt rollback bei Fehlern vor dem commit. Entfernt auch `~/.cairn/update/` und behält `~/.cairn/config.json` und `~/.cairn/projects/`. Eine Installation im legacy layout wird ohne Migration an Ort und Stelle entfernt.
+- `cairn auto-upgrade status|on|off|run`: `status` gibt Einstellung, installierte Version, letzte Prüfung und ausstehende Meldung als JSON aus; `on`/`off` schreiben `autoUpgrade` in `~/.cairn/config.json` und geben denselben Bericht aus; `run` prüft npm sofort, ohne 24-Stunden-Intervall und backoff abzuwarten. Exit 0 bedeutet Erfolg, 1 einen Ausführungsfehler oder fehlgeschlagenen Lauf, 2 einen Verwendungsfehler.
 - `cairn toolcheck`: erkennt repository stacks und prüft required tools; Installation läuft nur für einen genehmigten unterstützten installer, sonst gilt `installer-unavailable`.
 - `cairn cleanup --root <repo>`: meldet standardmäßig read-only legacy projektlokale `.cairn`-Reste. `--yes` migriert/gleicht gültigen active state mit dem user-home store ab, entfernt nur bekannte state/lock/tool-Reste, bewahrt unbekannte Dateien und entfernt das Verzeichnis nur, wenn es leer ist.
+- `cairn memory check|index [--root <repo>]`: `check` gleicht `MEMORY.md` mit `docs/memory/*.md` ab und gibt einen JSON-Bericht aus; bei nicht indexierten Notizen, dead links, Duplikaten, veralteten Zusammenfassungen, Steuerzeichen in Zusammenfassungen oder unsicheren Pfaden endet es mit exit 1, warnings schlagen nur mit `--strict` fehl. Einträge sind Listenzeilen unter `## Domain Knowledge` (in einer älteren Datei ohne diesen Abschnitt alle Listenzeilen); ein Notizlink in einem anderen Abschnitt ist eine Erwähnung, die `index` nie umschreibt. `index` ergänzt fehlende Notizen und ersetzt bei geändertem `Summary:` nur die Zusammenfassung nach dem Link (eine Zeile mit mehreren Links bleibt unverändert); es entfernt nur exakt passende Cairn-Platzhalterzeilen in diesem Abschnitt, löscht nie Einträge oder dead links und erhält den Rest Byte für Byte. `--dry-run` zeigt eine Vorschau. Liegt die Einfügestelle in einem nicht geschlossenen Codeblock, schreibt `index` nichts und endet mit exit 1 und `unclosed-fence`. Usage-Fehler enden mit exit 2; `cairn memory` ohne Unterbefehl gibt weiterhin den Hinweis aus.
+- `cairn plan check|index [--archive] [--root <repo>]`: dasselbe für `PLAN.md` und `docs/plan/*.md`, deren Einträge Listenzeilen unter `## `-Überschriften sind, die auf `Plans` enden (etwa `## Superseded Plans`). `index` setzt einen Plan, dessen Checkboxen alle abgehakt sind, an den Anfang von `## Completed Plans` und jeden anderen unter `## Active Plans`; nur `--archive` verschiebt Zeilen nach `docs/plan/ARCHIVE.md`: abgeschlossene Einträge jenseits der neuesten 20 samt eingerückten Absätzen und den Inhalt eines legacy Abschnitts `## Planning Rules`. `check` warnt, wenn `## Completed Plans` mehr als 20 Einträge hat oder ein legacy Abschnitt `## Planning Rules` übrig ist.
+- `cairn goal ...`: verwaltet das Repository-goal (`cairn goal --help`). `goal stats --history [--limit N]` fasst die beendeten goals des Repositorys über alle Worktrees zusammen: Anzahl completed/cancelled, Median und p90 der Dauer, Mediane von tasks und receipts, Rerun-Rate, memory promotion Entscheidungen, einen older/newer `trend` ab 4 abgeschlossenen goals und die letzten goals; ohne Historie gibt es `{"schemaVersion":1,"scope":"repository","goals":0}` aus. `completionCriteria` (`goal start --criteria`) ist `advisory`: Cairn zeichnet es auf, erzwingt es aber nicht, und der Abschluss hängt nur von der erforderlichen Evidence ab.
 - `cairn-memory`: erkundet domain knowledge und aktualisiert `MEMORY.md`.
 - `cairn-plan`: erstellt einen decision-complete plan unter `docs/plan/`.
 - `cairn-work`: führt den nächsten module task im aktuellen `PLAN.md` mit zwei verification gates aus.
@@ -109,10 +122,35 @@ cairn toolcheck
 
 Der custom marketplace lifecycle hält source und versioned runtime getrennt. Staged validation geht jedem commit voraus, das ownership manifest bindet alle managed digests, und ein Fehler führt zu reverse-order rollback. Modified oder unmanaged artifacts werden preserved und als conflict gemeldet. Cairn ändert nur eigene TOML sections und erzwingt keine öffentlichen feature/agent settings.
 
-Clean uninstall entfernt den Cairn marketplace cache root nur, wenn alle managed scaffold directories leer sind; unmanaged Inhalte bleiben erhalten. Source repository, repository `MEMORY.md`/`PLAN.md` und user-home Cairn goal state, das globale `cairn-ai` package, package-manager caches sowie legacy backups/settings außerhalb des aktuellen ownership manifest werden nicht automatisch gelöscht.
+Clean uninstall entfernt `~/.cairn/install/` und den Codex cache root `$CODEX_HOME/plugins/cache/cairn` nur, wenn alle managed scaffold directories leer sind; unmanaged Inhalte bleiben erhalten. Source repository, repository `MEMORY.md`/`PLAN.md` und user-home Cairn goal state, das globale `cairn-ai` package, package-manager caches sowie legacy backups/settings außerhalb des aktuellen ownership manifest werden nicht automatisch gelöscht.
 
 Codex verwendet `skills/` und `commands/`. Claude Code verwendet gespiegelte commands und agent definitions unter `.claude/`. Antigravity verwendet `.agents/workflows` und globale skills mirrors.
 
+## Install Layout And Auto-Upgrade
+
+Cairn legt seine Installation unter `CAIRN_HOME` (Standard `~/.cairn`) ab. Die Pfade der einzelnen hosts setzen weiterhin getrennt `CODEX_HOME`, `CLAUDE_HOME`, `ANTIGRAVITY_HOME`, `ANTIGRAVITY_CLI_HOME` und `CODEX_CONFIG_PATH`.
+
+```text
+~/.cairn/
+  install/                  vom lifecycle verwaltete Dateien
+    lifecycle.json          ownership manifest (schema 2: hosts, origin, retained runtimes)
+    lifecycle.lock, transaction.json, transactions/
+    runtime/<version>/      canonical runtime für alle runtime locators und die Claude Code hooks
+    codex/                  Codex local marketplace source
+    claude/                 Claude Code local marketplace
+  projects/                 goal state
+  config.json               Benutzereinstellungen ("autoUpgrade")
+  update/                   auto-upgrade-Zustand
+$CODEX_HOME/plugins/cache/cairn/cairn/<version>/   Kopie im Codex plugin cache (nur wenn Codex gewählt ist)
+```
+
+- Hosts: Nur `install` und `upgrade` akzeptieren `--hosts`, mit `all` oder einer Kommaliste aus `codex`, `claude` und `antigravity`. Die Auswahl steht im ownership manifest, und `upgrade`, `doctor` und `uninstall` folgen ihr. Geändert wird sie mit `cairn upgrade --hosts <list>`; eine veränderte verwaltete Datei eines abgewählten hosts führt zur Ablehnung. Der interaktive prompt (alle als Standard, nur Claude Code, nur Codex, nur Antigravity oder eine Liste) erscheint nur, wenn noch nichts installiert ist.
+- Migration: Eine Installation von Cairn 0.6.0 oder älter (alles unter `$CODEX_HOME/plugins/cache/cairn`) wandert mit einem einzigen `cairn upgrade` nach `~/.cairn/install/`, das auch das Claude Code plugin vom neuen marketplace-Pfad neu registriert. Eine fehlgeschlagene oder unterbrochene Migration wird wiederhergestellt, und veränderte verwaltete Dateien lehnen sie ohne Änderung ab. Die legacy-Installation migriert mit allen hosts; ein teilweises `--hosts` folgt im nächsten Lauf. Danach die Installation nur mit einem Cairn CLI verwalten, das dieses layout kennt, und während der Migration offene sessions neu starten.
+- Aufbewahrung: Ein upgrade mit Versionswechsel behält die vorherige canonical runtime und die Kopie im Codex cache 3 Tage lang (höchstens 3 je Art), damit vorher gestartete sessions weiterlaufen. Das nächste install oder upgrade entfernt abgelaufene, uninstall entfernt alle. Eine Codex-cache-Kopie gleich oder über der neuen Version wird nie behalten, weil Codex die höchste Version im cache lädt.
+- Claude Code plugin cache: Enthält er noch eine andere Version, aktualisiert `cairn upgrade` ihn mit `claude plugin marketplace update cairn` und `claude plugin update cairn@cairn --scope user`. Schlägt das fehl, bleibt die aktualisierte Installation bestehen, die Befehle zum manuellen Abschluss werden ausgegeben und der Exit-Code ist 1.
+- Auto-upgrade: standardmäßig an. Höchstens einmal alle 24 Stunden (und nicht in den 24 Stunden nach einem install oder upgrade) startet `SessionStart` einen abgetrennten Prozess, der die neueste `cairn-ai`-Version von npm liest, genau diese Version mit `--ignore-scripts` nach `~/.cairn/update/stage/` installiert, sie prüft und ihr `cairn-lifecycle.mjs upgrade --auto` ausführt. Jede neuere Version wird angewendet, auch major, und es gibt nie ein downgrade. Der nächste `SessionStart` meldet das Ergebnis (`updated`, `failed` oder `manual`) einmal in einer Zeile. Für Installationen aus einem git checkout (`origin: "checkout"`) und Läufe aus einem source checkout läuft es nicht.
+- Abschalten: `cairn auto-upgrade off`, `CAIRN_AUTO_UPGRADE=0` (auch `false`, `off` oder `no`) oder `"autoUpgrade": false` in `~/.cairn/config.json`. Eine unlesbare `config.json` schaltet es ebenfalls ab. Zustand und Log des letzten Laufs liegen in `~/.cairn/update/`.
+
 ## Antigravity Compatibility
 
 Antigravity unterstützt `SKILL.md`-basierte Agent Skills und Workflows, die als `/workflow-name` aufgerufen werden. Cairn installiert für diese Oberfläche die folgenden paths.

package/README.es.md

@@ -63,11 +63,19 @@ La guía detallada vive en el plugin instalado y se referencia como `cairn://doc
 
 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.
+- `MEMORY.md`: índice corto de conocimiento persistente del dominio: una línea por nota bajo `## Domain Knowledge` (`- [<name>](docs/memory/<name>.md): <summary>`) más la `## Policy` del repositorio.
+- `docs/memory/*.md`: conocimiento detallado por dominio. Cada nota empieza con una línea `Summary:` (120 caracteres como máximo) que muestran el índice y el hook.
 - `~/.cairn/projects/<project-id>/worktrees/<worktree-id>/state.json`: estado active goal/task/evidence en user-home, aislado por proyecto y worktree, para recuperación y scoped stop gates. El working tree no posee runtime state.
-- `PLAN.md`: índice corto de temas activos y completados.
+- `PLAN.md`: índice corto de planes de trabajo: una línea de 200 caracteres o menos por plan bajo `## Active Plans` y `## Completed Plans`. Las reglas de planificación viven en el skill `cairn-plan`, no en `PLAN.md`.
 - `docs/plan/*.md`: planes de ejecución detallados.
+- `docs/plan/ARCHIVE.md`: entradas completadas antiguas que `cairn plan index --archive` movió desde `PLAN.md`, de la más nueva a la más antigua, más el cuerpo de una sección legacy `## Planning Rules` bajo `## Legacy Planning Rules`. Las líneas de lista antes de su primer encabezado `## ` siguen contando como indexadas.
+- `~/.cairn/projects/<project-id>/worktrees/<worktree-id>/history.jsonl`: un registro resumen por goal completado o cancelado (los 200 más recientes por worktree) para `goal stats --history`.
+
+Mantén `## Completed Plans` de la más nueva a la más antigua. `cairn plan index --archive` conserva las primeras 20 entradas y mueve el resto a `docs/plan/ARCHIVE.md` sin borrar nada, así que una lista ordenada de la más antigua a la más nueva archivaría los planes más recientes; revisa antes con `--dry-run`. Los `MEMORY.md`/`PLAN.md` existentes funcionan sin migración: `init` nunca los reescribe y `check` solo avisa del formato antiguo con warnings.
+
+En `SessionStart`, el hook indica al agente qué notas de memoria existen (nombre y `Summary:`, o una sola línea con nombres cuando la lista es larga) y, sin goal activo, añade una línea sobre el índice de planes: número de planes, planes activos, los últimos planes completados y `docs/plan/ARCHIVE.md` si existe. Con un goal active, paused, blocked o de otra sesión solo se añade la lista de memoria, y la cápsula de otra sesión nunca muestra nombres de planes. Un `UserPromptSubmit` sin goal añade una frase con el número de notas. El hook solo lee los archivos índice y los listados de directorio, nunca el cuerpo de las notas, y no escribe nada; un repositorio sin notas ni planes recibe la misma salida que antes.
+
+Antes de `goal finish`, `cairn-work` registra una decisión de memory promotion por goal en la Evidence del plan: `Memory promotion: docs/memory/<domain>.md` cuando el goal produjo conocimiento reutilizable del repositorio, o `Memory promotion: none: <reason>` en caso contrario. La decisión es obligatoria; escribir una nota es opcional. Si un goal se completa y su archivo de plan no tiene una línea `Memory promotion:` rellenada, `goal finish` y `goal complete` imprimen un recordatorio de una línea en stderr sin cambiar el exit code ni stdout.
 
 Los archivos raíz se mantienen cortos y los detalles pasan a `docs/`, para que los agentes lean solo el contexto que necesitan.
 
@@ -94,14 +102,19 @@ cairn upgrade
 cairn doctor
 cairn uninstall
 cairn toolcheck
+cairn auto-upgrade status
 ```
 
-- `cairn install`: instala de forma transaccional custom marketplace source, versioned runtime, secciones config propias de Cairn y mirrors actuales.
-- `cairn upgrade`: reemplaza solo entradas sin modificar del ownership manifest tras staged validation y usa rollback al fallar.
-- `cairn doctor`: valida ownership digests, features efectivos de Codex, el estado real del plugin y runtime locators sin reparar.
-- `cairn uninstall`: elimina solo entradas gestionadas sin modificar; los objetivos modified o unmanaged se preservan como conflict.
+- `cairn install [--hosts all|codex,claude,antigravity]`: instala de forma transaccional custom marketplace source, versioned runtime, secciones config propias de Cairn y mirrors actuales. El canonical runtime vive en `~/.cairn/install/` y el resto se instala solo para los hosts elegidos. Sin `--hosts`, la primera instalación en una terminal pregunta los hosts; las ejecuciones no interactivas y CI instalan todos.
+- `cairn upgrade [--hosts all|codex,claude,antigravity]`: reemplaza solo entradas sin modificar del ownership manifest tras staged validation y usa rollback al fallar. Mantiene los hosts registrados salvo que `--hosts` los cambie, migra una instalación de Cairn 0.6.0 o anterior y actualiza un Claude Code plugin cache que aún tenga otra versión. Si la versión instalada es más nueva que esta CLI, `install` y `upgrade` se niegan sin cambiar nada; `--allow-downgrade` instala de todos modos la versión de esta CLI.
+- `cairn doctor`: valida ownership digests, features efectivos de Codex, el estado real del plugin y runtime locators sin reparar. Imprime primero `Hosts: <ids>` y solo revisa los hosts elegidos (incluido `Claude plugin cache version`). Si hay una instalación legacy, indica migrarla con `cairn upgrade`.
+- `cairn uninstall`: primero compara cada entrada no config del ownership manifest con su installed digest y rechaza todo el uninstall, sin cambiar nada, si algún managed artifact fue modificado o eliminado. Si no, elimina o restaura las entradas gestionadas y los retained runtimes, limpia los managed scaffolds vacíos, preserva los objetivos unmanaged y sus directorios padre, y aplica rollback a los fallos anteriores al commit. También elimina `~/.cairn/update/`, y conserva `~/.cairn/config.json` y `~/.cairn/projects/`. Una instalación con layout legacy se elimina en su sitio sin migrarla.
+- `cairn auto-upgrade status|on|off|run`: `status` imprime en JSON la configuración, la versión instalada, la última comprobación y el aviso pendiente; `on`/`off` escriben `autoUpgrade` en `~/.cairn/config.json` e imprimen el mismo informe; `run` consulta npm ahora, sin esperar el intervalo de 24 horas ni el backoff. Exit 0 es éxito, 1 un error de ejecución o una ejecución fallida y 2 un error de uso.
 - `cairn toolcheck`: detecta repository stacks y revisa required tools; solo ejecuta un installer compatible aprobado, o devuelve `installer-unavailable`.
 - `cairn cleanup --root <repo>`: por defecto informa en modo read-only el residuo legacy `.cairn` local al proyecto. `--yes` migra/reconcilia active state válido al almacén user-home, elimina solo residuos conocidos de state/lock/tool, conserva archivos desconocidos y poda el directorio solo si queda vacío.
+- `cairn memory check|index [--root <repo>]`: `check` compara `MEMORY.md` con `docs/memory/*.md` e imprime un informe JSON; sale con 1 ante notas sin indexar, dead links, duplicados, resúmenes desactualizados, caracteres de control en resúmenes o rutas inseguras, y los warnings solo fallan con `--strict`. Las entradas son líneas de lista bajo `## Domain Knowledge` (o todas las líneas de lista en un archivo antiguo sin esa sección); un enlace a una nota en otra sección es una mención que `index` nunca reescribe. `index` añade las notas que faltan y, si el `Summary:` cambió, reemplaza solo el resumen tras el enlace (una línea con varios enlaces queda como está); solo elimina líneas placeholder de Cairn que coinciden exactamente dentro de esa sección, nunca borra entradas ni dead links y conserva el resto byte a byte. `--dry-run` muestra una vista previa. Si el punto de inserción está dentro de un bloque de código sin cerrar, `index` no escribe nada y sale con 1 con `unclosed-fence`. Los errores de uso salen con 2; `cairn memory` sin subcomando sigue mostrando la guía.
+- `cairn plan check|index [--archive] [--root <repo>]`: lo mismo para `PLAN.md` y `docs/plan/*.md`, cuyas entradas son líneas de lista bajo encabezados `## ` que terminan en `Plans` (como `## Superseded Plans`). `index` coloca un plan con todas sus casillas marcadas al principio de `## Completed Plans` y cualquier otro en `## Active Plans`; solo `--archive` mueve líneas a `docs/plan/ARCHIVE.md`: las entradas completadas más allá de las 20 más nuevas, con sus párrafos sangrados, y el cuerpo de una sección legacy `## Planning Rules`. `check` avisa cuando `## Completed Plans` supera 20 entradas o queda una sección legacy `## Planning Rules`.
+- `cairn goal ...`: gestiona el goal del repositorio (`cairn goal --help`). `goal stats --history [--limit N]` agrega los goals terminados del repositorio en todos sus worktrees: recuentos completed/cancelled, mediana y p90 de duración, medianas de tasks y receipts, tasa de reruns, decisiones de memory promotion, un `trend` older/newer desde 4 goals completados y los goals recientes; sin historial imprime `{"schemaVersion":1,"scope":"repository","goals":0}`. `completionCriteria` (`goal start --criteria`) es `advisory`: Cairn lo registra pero no lo hace cumplir, y la finalización depende solo de la evidencia requerida.
 - `cairn-memory`: explora domain knowledge y actualiza `MEMORY.md`.
 - `cairn-plan`: crea un decision-complete plan bajo `docs/plan/`.
 - `cairn-work`: ejecuta el siguiente module task del `PLAN.md` actual con dos verification gates.
@@ -109,10 +122,35 @@ cairn toolcheck
 
 El custom marketplace lifecycle mantiene separados source y versioned runtime. Staged validation precede cada commit, el ownership manifest vincula todos los managed digests y un fallo aplica reverse-order rollback. Los artifacts modified o unmanaged se preservan y se reportan como conflict. Cairn modifica solo sus propias TOML sections y no fuerza feature/agent settings públicos.
 
-Clean uninstall elimina el Cairn marketplace cache root solo cuando todos los managed scaffold directories están vacíos; cualquier contenido unmanaged se conserva. No elimina el source repository, los `MEMORY.md`/`PLAN.md` del repository ni el Cairn goal state de user-home, el paquete global `cairn-ai`, los package-manager caches ni legacy backups/settings fuera del ownership manifest actual.
+Clean uninstall elimina `~/.cairn/install/` y el Codex cache root `$CODEX_HOME/plugins/cache/cairn` solo cuando todos los managed scaffold directories están vacíos; cualquier contenido unmanaged se conserva. No elimina el source repository, los `MEMORY.md`/`PLAN.md` del repository ni el Cairn goal state de user-home, el paquete global `cairn-ai`, los package-manager caches ni legacy backups/settings fuera del ownership manifest actual.
 
 Codex usa `skills/` y `commands/`. Claude Code usa comandos reflejados y definiciones de agentes bajo `.claude/`. Antigravity usa `.agents/workflows` y mirrors globales de skills.
 
+## Install Layout And Auto-Upgrade
+
+Cairn guarda la instalación bajo `CAIRN_HOME` (por defecto `~/.cairn`). Las rutas de cada host siguen definiéndose por separado con `CODEX_HOME`, `CLAUDE_HOME`, `ANTIGRAVITY_HOME`, `ANTIGRAVITY_CLI_HOME` y `CODEX_CONFIG_PATH`.
+
+```text
+~/.cairn/
+  install/                  archivos gestionados por el lifecycle
+    lifecycle.json          ownership manifest (schema 2: hosts, origin, retained runtimes)
+    lifecycle.lock, transaction.json, transactions/
+    runtime/<version>/      canonical runtime que usan todos los runtime locators y los hooks de Claude Code
+    codex/                  Codex local marketplace source
+    claude/                 Claude Code local marketplace
+  projects/                 goal state
+  config.json               ajustes del usuario ("autoUpgrade")
+  update/                   estado de auto-upgrade
+$CODEX_HOME/plugins/cache/cairn/cairn/<version>/   copia en el Codex plugin cache (solo si se elige Codex)
+```
+
+- Hosts: solo `install` y `upgrade` aceptan `--hosts`, con `all` o una lista separada por comas de `codex`, `claude` y `antigravity`. La selección queda en el ownership manifest y `upgrade`, `doctor` y `uninstall` la siguen. Se cambia con `cairn upgrade --hosts <list>`; si un archivo gestionado de un host retirado fue modificado, se rechaza. El prompt interactivo (todos por defecto, solo Claude Code, solo Codex, solo Antigravity o una lista) aparece solo cuando aún no hay nada instalado.
+- Migración: una instalación de Cairn 0.6.0 o anterior (todo bajo `$CODEX_HOME/plugins/cache/cairn`) pasa a `~/.cairn/install/` con un solo `cairn upgrade`, que también vuelve a registrar el plugin de Claude Code desde la nueva ruta del marketplace. Una migración fallida o interrumpida se restaura, y archivos gestionados modificados la rechazan sin cambios. La instalación legacy migra con todos los hosts, así que un `--hosts` parcial se indica en la siguiente ejecución. Después, gestiona la instalación solo con un Cairn CLI que conozca este layout y reinicia las sesiones abiertas durante la migración.
+- Retención: un upgrade que cambia de versión conserva el canonical runtime anterior y la copia del Codex cache durante 3 días (como máximo 3 de cada tipo) para que las sesiones iniciadas antes sigan funcionando. El siguiente install o upgrade elimina las vencidas y uninstall las elimina todas. Nunca se conserva una copia del Codex cache igual o superior a la nueva versión, porque Codex carga la versión más alta del cache.
+- Claude Code plugin cache: si aún tiene otra versión, `cairn upgrade` lo actualiza con `claude plugin marketplace update cairn` y `claude plugin update cairn@cairn --scope user`. Si falla, la instalación actualizada se mantiene, se imprimen los comandos para terminar a mano y sale con exit 1.
+- Auto-upgrade: activado por defecto. Como máximo una vez cada 24 horas (y no en las 24 horas siguientes a un install o upgrade), `SessionStart` lanza un proceso separado que lee la última versión de `cairn-ai` en npm, instala esa versión exacta con `--ignore-scripts` en `~/.cairn/update/stage/`, la verifica y ejecuta su `cairn-lifecycle.mjs upgrade --auto`. Aplica todas las versiones nuevas, incluidas las major, y nunca hace downgrade. El siguiente `SessionStart` muestra el resultado (`updated`, `failed` o `manual`) en una línea, una sola vez. No funciona en instalaciones desde un git checkout (`origin: "checkout"`) ni al ejecutar desde un source checkout.
+- Desactivar: `cairn auto-upgrade off`, `CAIRN_AUTO_UPGRADE=0` (también `false`, `off` o `no`) o `"autoUpgrade": false` en `~/.cairn/config.json`. Un `config.json` ilegible también lo desactiva. El estado y el log de la última ejecución están en `~/.cairn/update/`.
+
 ## Antigravity Compatibility
 
 Antigravity soporta Agent Skills y Workflows basados en `SKILL.md` invocados como `/workflow-name`. Cairn instala estas rutas para esa superficie.

package/README.fr.md

@@ -63,11 +63,19 @@ Les détails se trouvent dans le plugin installé sous `cairn://docs/model-guida
 
 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.
+- `MEMORY.md` : index court de persistent domain knowledge : une ligne par note sous `## Domain Knowledge` (`- [<name>](docs/memory/<name>.md): <summary>`), plus la `## Policy` du dépôt.
+- `docs/memory/*.md` : connaissances détaillées par domaine. Chaque note commence par une ligne `Summary:` (120 caractères au maximum) que l'index et le hook affichent.
 - `~/.cairn/projects/<project-id>/worktrees/<worktree-id>/state.json` : état active goal/task/evidence dans user-home, isolé par projet et worktree, pour la reprise et les scoped stop gates. Le working tree ne possède pas le runtime state.
-- `PLAN.md` : index court des sujets actifs et terminés.
+- `PLAN.md` : index court des plans de travail : une ligne de 200 caractères au plus par plan sous `## Active Plans` et `## Completed Plans`. Les règles de planification vivent dans le skill `cairn-plan`, pas dans `PLAN.md`.
 - `docs/plan/*.md` : detailed execution plans.
+- `docs/plan/ARCHIVE.md` : anciennes entrées terminées déplacées hors de `PLAN.md` par `cairn plan index --archive`, de la plus récente à la plus ancienne, plus le corps d'une section legacy `## Planning Rules` sous `## Legacy Planning Rules`. Les lignes de liste avant son premier titre `## ` comptent toujours comme indexées.
+- `~/.cairn/projects/<project-id>/worktrees/<worktree-id>/history.jsonl` : un enregistrement de synthèse par goal terminé ou annulé (les 200 plus récents par worktree) pour `goal stats --history`.
+
+Gardez `## Completed Plans` de la plus récente à la plus ancienne. `cairn plan index --archive` conserve les 20 premières entrées et déplace le reste vers `docs/plan/ARCHIVE.md` sans rien supprimer ; une liste tenue de la plus ancienne à la plus récente archiverait donc les plans les plus récents. Vérifiez d'abord avec `--dry-run`. Les `MEMORY.md`/`PLAN.md` existants fonctionnent sans migration : `init` ne les réécrit jamais et `check` signale l'ancien format uniquement par des warnings.
+
+Au `SessionStart`, le hook indique à l'agent quelles notes de mémoire existent (nom et `Summary:`, ou une seule ligne de noms quand la liste est longue) et, sans goal actif, ajoute une ligne sur l'index des plans : nombre de plans, plans actifs, derniers plans terminés et `docs/plan/ARCHIVE.md` s'il existe. Avec un goal active, paused, blocked ou détenu par une autre session, seule la liste de mémoire est ajoutée, et la capsule d'une autre session n'affiche jamais de noms de plans. Un `UserPromptSubmit` sans goal ajoute une phrase avec le nombre de notes. Le hook lit uniquement les fichiers d'index et les listes de répertoires, jamais le corps des notes, et n'écrit rien ; un dépôt sans notes ni plans reçoit la même sortie qu'avant.
+
+Avant `goal finish`, `cairn-work` consigne une décision de memory promotion par goal dans l'Evidence du plan : `Memory promotion: docs/memory/<domain>.md` quand le goal a produit une connaissance réutilisable du dépôt, sinon `Memory promotion: none: <reason>`. La décision est obligatoire ; écrire une note est facultatif. Quand un goal se termine et que son fichier de plan n'a pas de ligne `Memory promotion:` renseignée, `goal finish` et `goal complete` affichent un rappel d'une ligne sur stderr sans changer l'exit code ni stdout.
 
 Les fichiers racine restent courts et les détails vont sous `docs/`, afin que les agents ne lisent que le contexte nécessaire.
 
@@ -94,14 +102,19 @@ cairn upgrade
 cairn doctor
 cairn uninstall
 cairn toolcheck
+cairn auto-upgrade status
 ```
 
-- `cairn install` : installe transactionnellement custom marketplace source, versioned runtime, sections config propres à Cairn et mirrors actuels.
-- `cairn upgrade` : remplace uniquement les entrées intactes du ownership manifest après staged validation, avec rollback en cas d'échec.
-- `cairn doctor` : valide ownership digests, features Codex effectives, état réel du plugin et runtime locators sans réparation.
-- `cairn uninstall` : supprime uniquement les entrées gérées intactes ; les cibles modified ou unmanaged sont préservées comme conflict.
+- `cairn install [--hosts all|codex,claude,antigravity]` : installe transactionnellement custom marketplace source, versioned runtime, sections config propres à Cairn et mirrors actuels. Le canonical runtime se trouve sous `~/.cairn/install/` et le reste n'est installé que pour les hosts choisis. Sans `--hosts`, une première installation dans un terminal demande les hosts ; les exécutions non interactives et la CI installent tous les hosts.
+- `cairn upgrade [--hosts all|codex,claude,antigravity]` : remplace uniquement les entrées intactes du ownership manifest après staged validation, avec rollback en cas d'échec. Conserve les hosts enregistrés sauf si `--hosts` les change, migre une installation faite par Cairn 0.6.0 ou antérieur et met à jour un Claude Code plugin cache resté sur une autre version. Si la version installée est plus récente que cette CLI, `install` et `upgrade` refusent sans rien changer ; `--allow-downgrade` installe quand même la version de cette CLI.
+- `cairn doctor` : valide ownership digests, features Codex effectives, état réel du plugin et runtime locators sans réparation. Affiche d'abord `Hosts: <ids>` et ne vérifie que les hosts choisis (y compris `Claude plugin cache version`). Une installation legacy est signalée avec l'indication de la migrer par `cairn upgrade`.
+- `cairn uninstall` : compare d'abord chaque entrée non config du ownership manifest à son installed digest et refuse tout l'uninstall, sans rien changer, si un managed artifact a été modifié ou supprimé. Sinon, supprime ou restaure les entrées gérées et les retained runtimes, nettoie les managed scaffolds vides, préserve les cibles unmanaged et leurs répertoires parents, et applique un rollback aux échecs avant commit. Supprime aussi `~/.cairn/update/`, et conserve `~/.cairn/config.json` et `~/.cairn/projects/`. Une installation au layout legacy est supprimée sur place, sans migration.
+- `cairn auto-upgrade status|on|off|run` : `status` affiche en JSON le réglage, la version installée, la dernière vérification et la notification en attente ; `on`/`off` écrivent `autoUpgrade` dans `~/.cairn/config.json` et affichent le même rapport ; `run` interroge npm immédiatement, sans attendre l'intervalle de 24 heures ni le backoff. Exit 0 signifie succès, 1 une erreur d'exécution ou une exécution échouée, 2 une erreur d'usage.
 - `cairn toolcheck` : détecte repository stacks et vérifie required tools ; seul un installer approuvé et pris en charge s'exécute, sinon `installer-unavailable`.
 - `cairn cleanup --root <repo>` : signale par défaut, en lecture seule, les résidus legacy `.cairn` locaux au projet. `--yes` migre/réconcilie le valid active state vers le stockage user-home, supprime uniquement les résidus connus state/lock/tool, préserve les fichiers inconnus et ne supprime le répertoire que s'il est vide.
+- `cairn memory check|index [--root <repo>]` : `check` compare `MEMORY.md` à `docs/memory/*.md` et affiche un rapport JSON ; il sort avec 1 en cas de notes non indexées, dead links, doublons, résumés périmés, caractères de contrôle dans les résumés ou chemins non sûrs, et les warnings n'échouent qu'avec `--strict`. Les entrées sont les lignes de liste sous `## Domain Knowledge` (ou toutes les lignes de liste d'un ancien fichier sans cette section) ; un lien vers une note dans une autre section est une mention que `index` ne réécrit jamais. `index` ajoute les notes manquantes et, si le `Summary:` a changé, remplace seulement le résumé après le lien (une ligne à plusieurs liens reste telle quelle) ; il ne supprime que les lignes placeholder de Cairn exactement identiques dans cette section, jamais d'entrées ni de dead links, et conserve le reste octet pour octet. `--dry-run` donne un aperçu. Si le point d'insertion est dans un bloc de code non fermé, `index` n'écrit rien et sort avec 1 avec `unclosed-fence`. Les erreurs d'usage sortent avec 2 ; `cairn memory` sans sous-commande affiche toujours le guide.
+- `cairn plan check|index [--archive] [--root <repo>]` : la même chose pour `PLAN.md` et `docs/plan/*.md`, dont les entrées sont les lignes de liste sous les titres `## ` finissant par `Plans` (comme `## Superseded Plans`). `index` place un plan dont toutes les cases sont cochées en tête de `## Completed Plans` et tout autre plan dans `## Active Plans` ; seul `--archive` déplace des lignes vers `docs/plan/ARCHIVE.md` : les entrées terminées au-delà des 20 plus récentes, avec leurs paragraphes indentés, et le corps d'une section legacy `## Planning Rules`. `check` avertit quand `## Completed Plans` dépasse 20 entrées ou qu'une section legacy `## Planning Rules` subsiste.
+- `cairn goal ...` : gère le goal du dépôt (`cairn goal --help`). `goal stats --history [--limit N]` agrège les goals terminés du dépôt sur tous ses worktrees : nombres completed/cancelled, médiane et p90 de durée, médianes de tasks et de receipts, taux de reruns, décisions de memory promotion, un `trend` older/newer dès 4 goals terminés et les goals récents ; sans historique il affiche `{"schemaVersion":1,"scope":"repository","goals":0}`. `completionCriteria` (`goal start --criteria`) est `advisory` : Cairn l'enregistre sans l'imposer, et la complétion dépend uniquement des preuves requises.
 - `cairn-memory` : explore domain knowledge et met à jour `MEMORY.md`.
 - `cairn-plan` : crée un decision-complete plan sous `docs/plan/`.
 - `cairn-work` : exécute le prochain module task du `PLAN.md` courant avec deux verification gates.
@@ -109,10 +122,35 @@ cairn toolcheck
 
 Le custom marketplace lifecycle sépare source et versioned runtime. Staged validation précède chaque commit, le ownership manifest lie tous les managed digests et un échec déclenche un reverse-order rollback. Les artifacts modified ou unmanaged sont preserved et signalés comme conflict. Cairn ne modifie que ses propres TOML sections et ne force aucun feature/agent setting public.
 
-Clean uninstall supprime le Cairn marketplace cache root uniquement lorsque tous les managed scaffold directories sont vides ; tout contenu unmanaged est conservé. Il ne supprime ni le source repository, les `MEMORY.md`/`PLAN.md` du repository ou le Cairn goal state de user-home, ni le package global `cairn-ai`, les package-manager caches ou les legacy backups/settings hors du ownership manifest courant.
+Clean uninstall supprime `~/.cairn/install/` et le Codex cache root `$CODEX_HOME/plugins/cache/cairn` uniquement lorsque tous les managed scaffold directories sont vides ; tout contenu unmanaged est conservé. Il ne supprime ni le source repository, les `MEMORY.md`/`PLAN.md` du repository ou le Cairn goal state de user-home, ni le package global `cairn-ai`, les package-manager caches ou les legacy backups/settings hors du ownership manifest courant.
 
 Codex utilise `skills/` et `commands/`. Claude Code utilise les commandes miroir et définitions d'agents sous `.claude/`. Antigravity utilise `.agents/workflows` et les global skills mirrors.
 
+## Install Layout And Auto-Upgrade
+
+Cairn place son installation sous `CAIRN_HOME` (par défaut `~/.cairn`). Les chemins de chaque host restent définis séparément par `CODEX_HOME`, `CLAUDE_HOME`, `ANTIGRAVITY_HOME`, `ANTIGRAVITY_CLI_HOME` et `CODEX_CONFIG_PATH`.
+
+```text
+~/.cairn/
+  install/                  fichiers gérés par le lifecycle
+    lifecycle.json          ownership manifest (schema 2: hosts, origin, retained runtimes)
+    lifecycle.lock, transaction.json, transactions/
+    runtime/<version>/      canonical runtime utilisé par tous les runtime locators et les hooks Claude Code
+    codex/                  Codex local marketplace source
+    claude/                 Claude Code local marketplace
+  projects/                 goal state
+  config.json               réglages utilisateur ("autoUpgrade")
+  update/                   état de l'auto-upgrade
+$CODEX_HOME/plugins/cache/cairn/cairn/<version>/   copie dans le Codex plugin cache (seulement si Codex est choisi)
+```
+
+- Hosts : seuls `install` et `upgrade` acceptent `--hosts`, avec `all` ou une liste séparée par des virgules de `codex`, `claude` et `antigravity`. La sélection est enregistrée dans le ownership manifest et suivie par `upgrade`, `doctor` et `uninstall`. On la change avec `cairn upgrade --hosts <list>` ; un fichier géré modifié d'un host retiré entraîne un refus. Le prompt interactif (tous par défaut, Claude Code seul, Codex seul, Antigravity seul ou une liste) n'apparaît que si rien n'est encore installé.
+- Migration : une installation faite par Cairn 0.6.0 ou antérieur (tout sous `$CODEX_HOME/plugins/cache/cairn`) passe sous `~/.cairn/install/` en un seul `cairn upgrade`, qui réenregistre aussi le plugin Claude Code depuis le nouveau chemin du marketplace. Une migration échouée ou interrompue est restaurée, et des fichiers gérés modifiés la refusent sans rien changer. L'installation legacy migre avec tous les hosts ; un `--hosts` partiel se choisit donc à l'exécution suivante. Ensuite, gérez l'installation uniquement avec un Cairn CLI qui connaît ce layout et redémarrez les sessions ouvertes pendant la migration.
+- Rétention : un upgrade qui change de version garde le canonical runtime précédent et la copie du Codex cache pendant 3 jours (au plus 3 de chaque type) pour que les sessions démarrées avant continuent de fonctionner. Le install ou upgrade suivant supprime ceux qui ont expiré, et uninstall les supprime tous. Une copie du Codex cache égale ou supérieure à la nouvelle version n'est jamais gardée, car Codex charge la version la plus haute du cache.
+- Claude Code plugin cache : s'il contient encore une autre version, `cairn upgrade` le met à jour avec `claude plugin marketplace update cairn` et `claude plugin update cairn@cairn --scope user`. En cas d'échec, l'installation mise à jour est conservée, les commandes pour terminer à la main sont affichées et la sortie est exit 1.
+- Auto-upgrade : activé par défaut. Au plus une fois toutes les 24 heures (et pas dans les 24 heures qui suivent un install ou un upgrade), `SessionStart` lance un processus détaché qui lit la dernière version de `cairn-ai` sur npm, installe cette version exacte avec `--ignore-scripts` dans `~/.cairn/update/stage/`, la vérifie, puis exécute son `cairn-lifecycle.mjs upgrade --auto`. Toutes les nouvelles versions sont appliquées, major comprises, sans jamais de downgrade. Le `SessionStart` suivant affiche le résultat (`updated`, `failed` ou `manual`) en une ligne, une seule fois. Rien ne s'exécute pour une installation depuis un git checkout (`origin: "checkout"`) ni depuis un source checkout.
+- Désactiver : `cairn auto-upgrade off`, `CAIRN_AUTO_UPGRADE=0` (ou `false`, `off`, `no`) ou `"autoUpgrade": false` dans `~/.cairn/config.json`. Un `config.json` illisible le désactive aussi. L'état et le log de la dernière exécution se trouvent dans `~/.cairn/update/`.
+
 ## Antigravity Compatibility
 
 Antigravity prend en charge les Agent Skills et Workflows basés sur `SKILL.md`, invoqués comme `/workflow-name`. Cairn installe ces paths pour cette surface.

package/README.ja.md

@@ -63,11 +63,19 @@ Cairn は Claude-family と Codex-family models にのみ model-specific adjustm
 
 harness は対象 repository root に次の files を作成して維持します。
 
-- `MEMORY.md`: persistent domain knowledge の短い index。
-- `docs/memory/*.md`: domain ごとの詳細 knowledge。
+- `MEMORY.md`: persistent domain knowledge の短い index。`## Domain Knowledge` の下に note ごとに 1 行(`- [<name>](docs/memory/<name>.md): <summary>`)を置き、repository の `## Policy` も含みます。
+- `docs/memory/*.md`: domain ごとの詳細 knowledge。各 note は H1 の下に 1 行の `Summary:`(120 文字以内)を置き、index と hook がそれを表示します。
 - `~/.cairn/projects/<project-id>/worktrees/<worktree-id>/state.json`: 中断復旧と scoped stop gate に使う user-home の project/worktree 別 active goal/task/evidence 状態。project working tree は runtime state を所有しません。
-- `PLAN.md`: active/completed work topics の短い index。
+- `PLAN.md`: work plans の短い index。`## Active Plans` と `## Completed Plans` の下に plan ごとに 200 文字以内の 1 行を置きます。planning rules は `PLAN.md` ではなく `cairn-plan` skill にあります。
 - `docs/plan/*.md`: detailed execution plans。
+- `docs/plan/ARCHIVE.md`: `cairn plan index --archive` が `PLAN.md` から移した古い completed entries を新しい順に保持し、legacy `## Planning Rules` section の本文を `## Legacy Planning Rules` の下に置きます。最初の `## ` 見出しより前の list 行は index 済みとして扱われます。
+- `~/.cairn/projects/<project-id>/worktrees/<worktree-id>/history.jsonl`: completed/cancelled goal ごとの要約 record(worktree ごとに最新 200 件)。`goal stats --history` が読みます。
+
+`## Completed Plans` は新しい順に保ちます。`cairn plan index --archive` は先頭 20 件を残し、残りを何も削除せずに `docs/plan/ARCHIVE.md` へ移すため、古い順に並べた list では最新の plans が archive されます。先に `--dry-run` で確認してください。既存の `MEMORY.md`/`PLAN.md` は migration なしで動作します。`init` は既存 file を書き換えず、`check` は古い形式を warning としてのみ報告します。
+
+`SessionStart` で hook は、どの memory notes があるか(name と `Summary:`、list が長い場合は name だけの 1 行)を agent に知らせ、active goal がなければ plan index の 1 行(plan 数、active plans、最新の completed plans、存在すれば `docs/plan/ARCHIVE.md`)を追加します。active・paused・blocked goal や別 session が所有する goal がある場合は memory list だけを載せ、別 session の capsule に plan 名は出しません。goal がないときの `UserPromptSubmit` は note 数を伝える 1 文だけを追加します。hook は index files と directory listing だけを読み、note 本文は読まず、何も書き込みません。notes と plans がない repository の hook 出力は以前と同じです。
+
+`cairn-work` は `goal finish` の前に goal ごとに 1 回、memory promotion の決定を plan の Evidence に記録します。再利用できる repository knowledge ができた場合は `Memory promotion: docs/memory/<domain>.md`、そうでなければ `Memory promotion: none: <reason>` です。決定の記録は必須で、note の作成は任意です。goal が完了したのに plan file に記入済みの `Memory promotion:` 行がない場合、`goal finish` と `goal complete` は stderr に 1 行の reminder を出しますが、exit code と stdout は変わりません。
 
 root files は短く保ち、詳細は `docs/` に移すことで、agents が必要な context だけを読めるようにします。
 
@@ -94,14 +102,19 @@ cairn upgrade
 cairn doctor
 cairn uninstall
 cairn toolcheck
+cairn auto-upgrade status
 ```
 
-- `cairn install`: custom marketplace source、versioned runtime、Cairn-owned config sections、現行 host mirrors を transaction で install します。
-- `cairn upgrade`: staged validation 後、ownership manifest の未変更 entry だけを置換し、失敗時は rollback します。
-- `cairn doctor`: ownership digests、effective Codex features、実際の plugin status、runtime locators を修復せず診断します。
-- `cairn uninstall`: 未変更の managed entry だけを削除し、modified または unmanaged target は conflict として preserve します。
+- `cairn install [--hosts all|codex,claude,antigravity]`: custom marketplace source、versioned runtime、Cairn-owned config sections、現行 host mirrors を transaction で install します。 canonical runtime は `~/.cairn/install/` に置き、上記は選択した host の分だけ install します。`--hosts` がない場合、terminal での最初の install は host を尋ね、非対話実行と CI はすべての host を install します。
+- `cairn upgrade [--hosts all|codex,claude,antigravity]`: staged validation 後、ownership manifest の未変更 entry だけを置換し、失敗時は rollback します。 `--hosts` で変えない限り記録された hosts を維持し、Cairn 0.6.0 以前の install を移行し、別 version を持つ Claude Code plugin cache を更新します。 install 済み version がこの CLI より新しい場合、`install` と `upgrade` は何も変えずに拒否し、それでもこの CLI の version を入れるには `--allow-downgrade` を付けます。
+- `cairn doctor`: ownership digests、effective Codex features、実際の plugin status、runtime locators を修復せず診断します。 最初の行に `Hosts: <ids>` を出力し、選択された host だけを検査します(`Claude plugin cache version` を含む)。legacy install があれば `cairn upgrade` での移行を案内します。
+- `cairn uninstall`: まず config 以外のすべての ownership manifest entry を installed digest と照合し、変更または削除された managed artifact が一つでもあれば何も変えずに uninstall 全体を拒否します。そうでなければ managed entry と retained runtimes を削除・復元し、空の managed scaffold を整理し、unmanaged target とその親ディレクトリは preserve し、commit 前の失敗は rollback します。 `~/.cairn/update/` も削除し、`~/.cairn/config.json` と `~/.cairn/projects/` は残します。legacy layout の install は移行せずにその場で削除します。
+- `cairn auto-upgrade status|on|off|run`: `status` は設定、installed version、最終確認、保留中の notice を JSON で出力します。`on`/`off` は `~/.cairn/config.json` の `autoUpgrade` を書き換えて同じ report を出力し、`run` は 24 時間周期と backoff を無視して今すぐ npm を確認します。exit 0 は成功、1 は実行エラーまたは失敗した run、2 は usage error です。
 - `cairn toolcheck`: repository stacks と required tools を確認し、承認済み supported installer だけを実行します。それ以外は `installer-unavailable` です。
 - `cairn cleanup --root <repo>`: 既定では legacy project-local `.cairn` residue を read-only で報告します。`--yes` は valid active state を user-home store に移行・調整し、known state/lock/tool residue のみ削除し、unknown files を保持して空の場合だけ directory を削除します。
+- `cairn memory check|index [--root <repo>]`: `check` は `MEMORY.md` と `docs/memory/*.md` を照合して JSON report を 1 つ出力します。unindexed notes、dead links、duplicates、stale summaries、summary 内の制御文字、unsafe paths があれば exit 1 で、warnings は `--strict` のときだけ失敗します。entries は `## Domain Knowledge` の下の list 行です(その section がない古い file ではすべての list 行)。他の section の note link は言及であり、`index` は書き換えません。`index` は抜けている notes を追加し、`Summary:` が変わると link の後ろの summary 部分だけを置き換えます(link が複数ある行はそのまま)。その section 内で完全に一致する Cairn placeholder 行だけを削除し、entries や dead links は削除せず、それ以外は byte 単位で保持します。`--dry-run` で事前確認できます。挿入位置が閉じていない code fence の中なら、`index` は何も書かず `unclosed-fence` で exit 1 になります。usage error は exit 2 で、subcommand なしの `cairn memory` は従来の案内を出力します。
+- `cairn plan check|index [--archive] [--root <repo>]`: `PLAN.md` と `docs/plan/*.md` に同じ check と index を適用し、entries は見出しが `Plans` で終わる `## ` section(`## Superseded Plans` など)の list 行です。`index` は checkbox がすべて checked の plan を `## Completed Plans` の先頭に、それ以外を `## Active Plans` に追加します。行を移動するのは `--archive` だけで、最新 20 件を超える completed entries(インデントされた段落を含む)と legacy `## Planning Rules` section の本文を `docs/plan/ARCHIVE.md` へ移します。`check` は `## Completed Plans` が 20 件を超えるか legacy `## Planning Rules` section が残っていると warning を出します。
+- `cairn goal ...`: repository goal を管理します(`cairn goal --help`)。`goal stats --history [--limit N]` は repository のすべての worktree で終了した goals を集計します。completed/cancelled 数、所要時間の median と p90、task と receipt の median、rerun rate、memory promotion の決定数、completed goal が 4 件以上のときの older/newer `trend`、最近の goals です。history がなければ `{"schemaVersion":1,"scope":"repository","goals":0}` を出力します。`completionCriteria`(`goal start --criteria`)は `advisory` です。Cairn は記録するだけで強制せず、完了は required evidence だけで判定されます。
 - `cairn-memory`: domain knowledge を探索し `MEMORY.md` を更新します。
 - `cairn-plan`: `docs/plan/` に decision-complete plan を作成します。
 - `cairn-work`: 現在の `PLAN.md` の次の module task を実行し、2 つの verification gates を取得します。
@@ -109,10 +122,35 @@ cairn toolcheck
 
 custom marketplace lifecycle は source と versioned runtime を分離します。各 commit 前に staged validation を行い、ownership manifest が全 managed digest を結び、失敗時は reverse-order rollback します。modified または unmanaged artifacts は preserve して conflict として報告します。Cairn-owned TOML sections だけを変更し、public feature/agent settings は強制しません。
 
-Clean uninstall は、すべての managed scaffold directory が空の場合に限り Cairn marketplace cache root を削除し、unmanaged content は保持します。source repository と repository `MEMORY.md`/`PLAN.md`、user-home Cairn goal state、global `cairn-ai` package、package-manager cache、現在の ownership manifest 外の legacy backup/settings は自動削除しません。
+Clean uninstall は、すべての managed scaffold directory が空の場合に限り `~/.cairn/install/` と Codex cache root `$CODEX_HOME/plugins/cache/cairn` を削除し、unmanaged content は保持します。source repository と repository `MEMORY.md`/`PLAN.md`、user-home Cairn goal state、global `cairn-ai` package、package-manager cache、現在の ownership manifest 外の legacy backup/settings は自動削除しません。
 
 Codex は `skills/` と `commands/` を使います。Claude Code は `.claude/` 配下の mirrored commands と agent definitions を使います。Antigravity は `.agents/workflows` と global skills mirrors を使います。
 
+## Install Layout And Auto-Upgrade
+
+Cairn は install を `CAIRN_HOME`(既定 `~/.cairn`)の下に置きます。host の paths は引き続き `CODEX_HOME`、`CLAUDE_HOME`、`ANTIGRAVITY_HOME`、`ANTIGRAVITY_CLI_HOME`、`CODEX_CONFIG_PATH` で個別に設定します。
+
+```text
+~/.cairn/
+  install/                  lifecycle が管理する files
+    lifecycle.json          ownership manifest (schema 2: hosts, origin, retained runtimes)
+    lifecycle.lock, transaction.json, transactions/
+    runtime/<version>/      すべての runtime locator と Claude Code hooks が使う canonical runtime
+    codex/                  Codex local marketplace source
+    claude/                 Claude Code local marketplace
+  projects/                 goal state
+  config.json               user settings ("autoUpgrade")
+  update/                   auto-upgrade state
+$CODEX_HOME/plugins/cache/cairn/cairn/<version>/   Codex plugin cache copy (Codex を選択した場合のみ)
+```
+
+- Hosts: `--hosts` は `install` と `upgrade` だけが受け付け、値は `all` または `codex`、`claude`、`antigravity` のカンマ区切りです。選択は ownership manifest に記録され、`upgrade`、`doctor`、`uninstall` がそれに従います。変更は `cairn upgrade --hosts <list>` で、外す host の managed file が変更されていれば拒否します。対話 prompt(すべて(既定)、Claude Code のみ、Codex のみ、Antigravity のみ、カンマ区切り)は、まだ何も install されていないときだけ表示されます。
+- 移行: Cairn 0.6.0 以前の install(`$CODEX_HOME/plugins/cache/cairn` 配下)は `cairn upgrade` 1 回で `~/.cairn/install/` へ移り、Claude Code plugin も新しい marketplace path で再登録されます。失敗・中断した移行は復元され、変更された managed file があれば何も変えずに拒否します。legacy install はすべての host のまま移行するため、全体でない `--hosts` は次の実行で指定します。移行後はこの layout を扱える Cairn CLI だけで管理し、移行中に開いていた session は再起動してください。
+- 猶予: version が変わる upgrade は、直前の canonical runtime と Codex cache copy を 3 日間(種類ごとに最大 3 個)残し、upgrade 前に始まった session が動き続けるようにします。期限切れは次の install/upgrade が削除し、uninstall はすべて削除します。新しい version 以上の Codex cache copy は残しません(Codex は cache の中で最も高い version を読み込むため)。
+- Claude Code plugin cache: 別 version が残っていれば `cairn upgrade` が `claude plugin marketplace update cairn` と `claude plugin update cairn@cairn --scope user` で更新します。失敗した場合は upgrade 済みの install を残し、手動で完了する command を出力して exit 1 になります。
+- Auto-upgrade: 既定で有効です。`SessionStart` が 24 時間に 1 回まで(install・upgrade 直後の 24 時間は除く)detached process を起動し、npm の最新 `cairn-ai` をその version 固定で `--ignore-scripts` 付きで `~/.cairn/update/stage/` に install・検証してから、その package の `cairn-lifecycle.mjs upgrade --auto` を実行します。major を含むすべての新しい version を適用し、downgrade はしません。次の `SessionStart` が結果(`updated`、`failed`、`manual`)を 1 行で 1 回だけ知らせます。git checkout からの install(`origin: "checkout"`)と source checkout からの実行では動作しません。
+- 無効化: `cairn auto-upgrade off`、`CAIRN_AUTO_UPGRADE=0`(`false`、`off`、`no` も可)、または `~/.cairn/config.json` の `"autoUpgrade": false`。読めない `config.json` も無効として扱います。状態と最後の実行 log は `~/.cairn/update/` にあります。
+
 ## Antigravity Compatibility
 
 Antigravity は `/workflow-name` で呼び出される `SKILL.md` based Agent Skills and Workflows をサポートします。Cairn はこの surface に次の paths を install します。