cairn-ai 0.6.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-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/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cairn",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Token-efficient agent harness with tool readiness for Codex, Claude Code, and Antigravity.",
   "author": {
     "name": "WkNam"

package/README.de.md

@@ -102,12 +102,14 @@ 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.
@@ -120,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

@@ -102,12 +102,14 @@ 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.
@@ -120,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

@@ -102,12 +102,14 @@ 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.
@@ -120,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

@@ -102,12 +102,14 @@ 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` は従来の案内を出力します。
@@ -120,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 します。

package/README.ko.md

@@ -92,7 +92,7 @@ Cairn은 Claude-family와 Codex-family 모델에만 모델별 조정을 적용
 
 `cairn-work`는 `goal finish` 전에 goal마다 한 번 메모리 승격 결정을 계획의 Evidence에 기록합니다. 다시 쓸 저장소 지식이 생겼으면 `Memory promotion: docs/memory/<domain>.md`, 아니면 `Memory promotion: none: <reason>`입니다. 결정 기록은 필수이고 노트 작성은 선택입니다. goal이 완료됐는데 계획 파일에 채워진 `Memory promotion:` 줄이 없으면 `goal finish`와 `goal complete`가 stderr에 한 줄 알림을 내며, exit code와 stdout은 바뀌지 않습니다.
 
-런타임 script, template, command, agent, model guidance는 설치된 플러그인 루트에 유지합니다. 각 표면의 locator가 같은 설치본을 가리키므로 대상 저장소에 Cairn 내부 파일을 복사하지 않습니다. 공유 런타임 또는 locator가 없거나 읽을 수 없거나 불일치하면 이를 가리키는 모든 mirror 사용을 중단하고 게시 패키지에서 `bunx cairn-ai@latest doctor` 후 `bunx cairn-ai@latest upgrade`를 실행해 복구합니다. 다른 host mirror나 대상 저장소를 복구 원본으로 사용하지 않습니다.
+런타임 script, template, command, agent, model guidance는 설치된 canonical runtime `~/.cairn/install/runtime/<version>/`에 유지합니다. 각 표면의 locator가 같은 설치본을 가리키므로 대상 저장소에 Cairn 내부 파일을 복사하지 않습니다. 공유 런타임 또는 locator가 없거나 읽을 수 없거나 불일치하면 이를 가리키는 모든 mirror 사용을 중단하고 게시 패키지에서 `bunx cairn-ai@latest doctor` 후 `bunx cairn-ai@latest upgrade`를 실행해 복구합니다. 다른 host mirror나 대상 저장소를 복구 원본으로 사용하지 않습니다.
 
 ## Commands
 
@@ -115,12 +115,14 @@ cairn upgrade
 cairn doctor
 cairn uninstall
 cairn toolcheck
+cairn auto-upgrade status
 ```
 
-- `cairn install`: custom marketplace source, versioned Codex runtime cache, Cairn-owned config section, Claude Code mirror와 플러그인, 현재 Antigravity IDE/CLI skill 표면을 transaction으로 설치합니다.
-- `cairn upgrade`: ownership manifest의 installed digest와 현재 값이 같은 항목만 교체하며, staged validation과 역순 rollback을 적용합니다.
-- `cairn doctor`: ownership manifest, managed digest, 유효 Codex feature, 실제 plugin installed/enabled/version, mirror/runtime locator를 수정 없이 진단합니다.
-- `cairn uninstall`: 먼저 config 외 모든 ownership manifest 항목을 설치 digest와 대조하고, 수정되거나 삭제된 managed artifact가 하나라도 있으면 아무것도 바꾸지 않고 uninstall 전체를 거부합니다. 그렇지 않으면 managed 항목을 제거·복원하고 빈 managed cache scaffold를 정리하며, unmanaged target과 그 상위 디렉터리는 보존하고 commit 전 실패는 rollback합니다.
+- `cairn install [--hosts all|codex,claude,antigravity]`: canonical runtime을 `~/.cairn/install/` 아래에 설치하고, 선택한 호스트에 대해 Codex marketplace source, versioned Codex runtime cache, Cairn-owned config section, Claude Code mirror와 플러그인, 현재 Antigravity IDE/CLI skill 표면을 transaction으로 설치합니다. `--hosts`가 없으면 터미널에서 처음 설치할 때 호스트를 묻고, 비대화형 실행과 CI는 모든 호스트를 설치합니다.
+- `cairn upgrade [--hosts all|codex,claude,antigravity]`: ownership manifest의 installed digest와 현재 값이 같은 항목만 교체하며, staged validation과 역순 rollback을 적용합니다. `--hosts`로 바꾸지 않으면 기록된 호스트를 유지하고, Cairn 0.6.0 이하에서 만든 설치를 이전하며, 다른 버전을 담은 Claude Code 플러그인 캐시를 갱신합니다. 설치본 버전이 이 CLI보다 높으면 `install`과 `upgrade`는 아무것도 바꾸지 않고 거부하며, 그래도 이 CLI 버전으로 내리려면 `--allow-downgrade`를 붙입니다.
+- `cairn doctor`: 첫 줄에 `Hosts: <ids>`를 출력한 뒤 선택된 호스트의 ownership manifest, managed digest, 유효 Codex feature, 실제 plugin installed/enabled/version(`Claude plugin cache version` 포함), mirror/runtime locator를 수정 없이 진단합니다. legacy 설치가 있으면 `cairn upgrade`로 이전하라는 안내를 출력합니다.
+- `cairn uninstall`: 먼저 config 외 모든 ownership manifest 항목을 설치 digest와 대조하고, 수정되거나 삭제된 managed artifact가 하나라도 있으면 아무것도 바꾸지 않고 uninstall 전체를 거부합니다. 그렇지 않으면 managed 항목과 유예 중인 runtime을 제거·복원하고 빈 managed scaffold를 정리하며, unmanaged target과 그 상위 디렉터리는 보존하고 commit 전 실패는 rollback합니다. `~/.cairn/update/`도 지우며 `~/.cairn/config.json`과 `~/.cairn/projects/`는 남깁니다. legacy 레이아웃 설치는 이전하지 않고 그 자리에서 제거합니다.
+- `cairn auto-upgrade status|on|off|run`: `status`는 설정, 설치 버전, 마지막 확인, 대기 중인 알림을 JSON으로 출력합니다. `on`과 `off`는 `~/.cairn/config.json`에 `autoUpgrade`를 쓰고 같은 보고를 출력합니다. `run`은 하루 주기와 backoff를 무시하고 지금 npm을 확인해 결과를 출력합니다. exit 0은 성공, 1은 실행 오류 또는 실패한 실행, 2는 사용법 오류입니다.
 - `cairn toolcheck`: 저장소 스택과 필요한 LSP·검증 도구를 확인하며, 승인된 지원 installer만 실행합니다.
 - `cairn cleanup --root <repo>`: 기본값은 legacy 프로젝트 로컬 `.cairn` 잔여물을 읽기 전용으로 보고합니다. `--yes`는 유효한 활성 상태를 사용자 홈 저장소로 조정·이관하고 알려진 상태/lock/tool 잔여물만 제거하며, 알 수 없는 파일은 보존하고 비었을 때만 디렉터리를 정리합니다. `state.lock`은 이 host에서 owner 프로세스가 종료된 유효한 lock 레코드일 때만 삭제하고, 격리된 `state.lock.stale.*` 파일은 유효한 레코드의 nonce가 파일 이름과 일치할 때만 삭제합니다. owner가 살아 있거나 다른 host의 lock, 파싱할 수 없는 lock은 보존하고 `preservedReasons`에 사유를 남깁니다. `--help`와 `--version`은 exit 0, 사용법 오류는 exit 2, 실행 오류는 `Cairn cleanup error:` 한 줄과 exit 1입니다.
 - `cairn goal ...`: 저장소의 영속 goal을 시작·조회·일시정지·재개·차단·취소·완료합니다. `goal claim --session <id>`는 같은 작업을 이어받는 session(재개·압축·handoff·fork)에 미완료 goal의 소유권을 넘기며, 미완료 goal 중에 들어온 새 작업은 goal을 취소하지 않고 `goal replan`으로 합칩니다. 기본 tool-bound 정책은 `goal verify -- <argv>`가 명령을 직접 실행해 성공 증거를 기록합니다. `goal receipt`는 기존 선언 증거를 가져오는 호환 명령입니다. 모든 `goal` 하위 명령에서 `--root`는 선택이며, 생략하면 `HARNESS_REPO_ROOT`, 없으면 cwd에서 가장 가까운 `.git` 상위 디렉터리로 결정됩니다. `goal verify --kind "moduleAcceptance|surfaceIntegration" -- <argv>`는 한 번 실행으로 kind마다 receipt를 기록하며, evidence scope는 `task`와 `goal`뿐입니다. `goal finish [--watch "<path|path>"] [--timeout-ms N] -- <argv>`는 active task를 완료하고(필수 증거가 fresh여야 함) argv를 한 번 실행해 goal requiredEvidence의 모든 kind(기본 `finalReview`)를 goal scope로 기록한 뒤 goal을 완료합니다. 이 goal scope 증거가 모든 task receipt 이후에 기록되면 이전 task 검사를 다시 실행하지 않습니다. `goal stats`는 현재 goal의 receipt 수, 재실행, stale receipt를 JSON으로 출력합니다. `goal stats --history [--limit N]`은 저장소의 모든 worktree에서 끝난 goal을 집계합니다: 완료·취소 수, 소요 시간 중앙값과 p90, task·receipt 중앙값, 재실행 비율, 메모리 승격 결정 수, 완료 goal이 4개 이상일 때의 이전/최근 `trend`, 최근 goal 목록입니다. 이력이 없으면 `{"schemaVersion":1,"scope":"repository","goals":0}`을 출력합니다. `completionCriteria`(`goal start --criteria`)는 `advisory`입니다. Cairn은 이를 기록만 하고 강제하지 않으며, 완료는 필수 증거로만 판정합니다. task는 `dependsOn`(생략 시 이전 task)과 `writeScope`를 선언하고, `goal ready`는 active/ready/blocked task id를 출력하며, write scope가 겹치지 않는 ready task는 같은 worktree에서 최대 4개까지 병렬로 active가 될 수 있습니다.
@@ -135,13 +137,37 @@ cairn toolcheck
 
 토큰 효율 실행에서는 구현보다 먼저 요구사항·불변식·경계·실패 모드로 집중 실행 test contract를 설계하는 데 추론을 배분합니다. 구현에는 실패 계약과 제한된 파일 범위만 전달하고 통과에 필요한 최소 변경을 요구합니다. 성공 여부는 도구 exit code와 기계적 요약으로 판정하며 성공 출력은 축약하고 실패할 때만 컨텍스트를 확장합니다. 명시적 `--watch`가 없으면 Git fingerprint는 ignored file을 제외하므로 주장에 필요한 ignored artifact는 각각 `--watch <path>` 또는 명시적인 상위 디렉터리로 지정해야 합니다. package 검증 전 lifecycle script를 검사하고 기본적으로 정상 `npm pack --dry-run`을 실행합니다. content-producing 또는 미분류 script에는 `--ignore-scripts`를 사용하면 안 되며, script가 없거나 content-neutral임을 입증했고 전체 검사 증거가 여전히 유효할 때만 사용할 수 있습니다. 성공한 상태 변경은 `--quiet`를 지원하므로 커지는 goal JSON이 대화 토큰을 소모하지 않습니다.
 
-`install`과 `upgrade`는 custom marketplace lifecycle을 유지하며 `codex plugin add`를 호출하지 않습니다. candidate를 staging에서 검증한 뒤 commit하고, 현재 managed destination과 digest를 ownership manifest에 기록하며 실패 시 완료된 phase를 역순 rollback합니다. 별도의 고정된 SHA-256 release 0.2.2 file-hash allowlist는 정확한 legacy file set 검증 전용이며 현재 package file list나 암호학적 서명이 아닙니다. 수정되지 않은 지원 legacy 설치만 release-integrity 검증 뒤 인수하고, 수정되거나 알 수 없는 artifact는 보존한 채 거부합니다. Cairn-owned TOML section만 편집하고 public feature/agent 설정은 강제하지 않습니다. lifecycle command는 교체 대상 cache copy가 아니라 게시/전역 package에서 실행해야 합니다.
+`install`과 `upgrade`는 custom marketplace lifecycle을 유지하며 `codex plugin add`를 호출하지 않습니다. candidate를 staging에서 검증한 뒤 commit하고, 현재 managed destination과 digest를 ownership manifest에 기록하며 실패 시 완료된 phase를 역순 rollback합니다. 별도의 고정된 SHA-256 release 0.2.2 file-hash allowlist는 정확한 legacy file set 검증 전용이며 현재 package file list나 암호학적 서명이 아닙니다. 수정되지 않은 지원 legacy 설치만 release-integrity 검증 뒤 인수하고, 수정되거나 알 수 없는 artifact는 보존한 채 거부합니다. Cairn-owned TOML section만 편집하고 public feature/agent 설정은 강제하지 않습니다. lifecycle command는 교체 대상인 `~/.cairn/install/` 아래 설치본이나 Codex plugin cache가 아니라 게시/전역 package에서 실행해야 합니다.
 
-Clean uninstall은 모든 managed scaffold가 비었을 때만 recursive 삭제 없이 빈 디렉터리 제거로 Cairn marketplace cache root를 정리합니다. 소스 저장소와 저장소의 `MEMORY.md`/`PLAN.md`, 사용자 홈 Cairn goal 상태, 전역 `cairn-ai` package, package-manager download cache, legacy backup, 현재 ownership manifest 밖의 legacy shared setting은 지우지 않으며 별도의 명시적 정리 판단이 필요합니다.
+Clean uninstall은 모든 managed scaffold가 비었을 때만 recursive 삭제 없이 빈 디렉터리 제거로 `~/.cairn/install/`과 Codex cache root `$CODEX_HOME/plugins/cache/cairn`을 정리합니다. 소스 저장소와 저장소의 `MEMORY.md`/`PLAN.md`, 사용자 홈 Cairn goal 상태, 전역 `cairn-ai` package, package-manager download cache, legacy backup, 현재 ownership manifest 밖의 legacy shared setting은 지우지 않으며 별도의 명시적 정리 판단이 필요합니다.
 
 Codex는 `skills/`와 `commands/`를 사용합니다. Claude Code는 `~/.claude/` 아래의 mirror command·agent definition과 Claude Code 플러그인 `cairn@cairn`을 사용합니다. Antigravity는 `.agents/workflows`와 global skills mirror를 사용합니다.
 
-Claude Code 플러그인은 Cairn이 소유한 로컬 marketplace `~/.codex/plugins/cache/cairn/claude`에 생성되며, Cairn skill 4개와 SessionStart·UserPromptSubmit·PostToolUse·Stop·SubagentStop hook을 담습니다. hook은 설치된 버전 런타임을 절대경로로 호출합니다. 파일 commit 뒤 `cairn install`/`upgrade`가 `claude plugin marketplace add`와 `claude plugin install cairn@cairn --scope user`로 등록하므로 다음 세션부터 Claude Code 터미널·데스크톱 앱·IDE 플러그인 목록에 표시됩니다. `claude` CLI가 없으면 등록을 건너뛰고 수동 명령을 안내하며, 이미 `cairn`이라는 다른 marketplace가 있으면 건드리지 않습니다. `cairn uninstall`은 파일 제거 전에 Cairn 소유 marketplace만 등록 해제하고, uninstall이 rollback되면 다시 등록합니다. `cairn doctor`는 `Claude plugin files`, `Claude plugin registered`, `Claude plugin enabled`를 보고합니다.
+Claude Code 플러그인은 Cairn이 소유한 로컬 marketplace `~/.cairn/install/claude`에 생성되며, Cairn skill 4개와 SessionStart·UserPromptSubmit·PostToolUse·Stop·SubagentStop hook을 담습니다. hook은 canonical runtime을 절대경로로 호출합니다. 파일 commit 뒤 `cairn install`/`upgrade`가 `claude plugin marketplace add`와 `claude plugin install cairn@cairn --scope user`로 등록하므로 다음 세션부터 Claude Code 터미널·데스크톱 앱·IDE 플러그인 목록에 표시됩니다. `claude` CLI가 없으면 등록을 건너뛰고 수동 명령을 안내하며, 이미 `cairn`이라는 다른 marketplace가 있으면 건드리지 않습니다. `cairn uninstall`은 파일 제거 전에 Cairn 소유 marketplace만 등록 해제하고, uninstall이 rollback되면 다시 등록합니다. Claude Code 플러그인 캐시에 다른 버전이 있으면 `cairn upgrade`가 `claude plugin marketplace update cairn`과 `claude plugin update cairn@cairn --scope user`로 갱신합니다. 갱신에 실패하면 업그레이드된 설치는 그대로 두고 수동으로 마칠 명령을 출력하며 exit 1입니다. `cairn doctor`는 `Claude plugin files`, `Claude plugin registered`, `Claude plugin enabled`, `Claude plugin cache version`을 보고합니다.
+
+## Install Layout And Auto-Upgrade
+
+Cairn은 설치본을 `CAIRN_HOME`(기본 `~/.cairn`) 아래에 둡니다. `CODEX_HOME`, `CLAUDE_HOME`, `ANTIGRAVITY_HOME`, `ANTIGRAVITY_CLI_HOME`, `CODEX_CONFIG_PATH`는 여전히 각 호스트 경로를 따로 정합니다.
+
+```text
+~/.cairn/
+  install/                  lifecycle 관리 파일
+    lifecycle.json          ownership manifest (schema 2: hosts, origin, 유예 runtime)
+    lifecycle.lock, transaction.json, transactions/
+    runtime/<version>/      모든 runtime locator와 Claude Code hook이 쓰는 canonical runtime
+    codex/                  Codex 로컬 marketplace source
+    claude/                 Claude Code 로컬 marketplace
+  projects/                 goal 상태
+  config.json               사용자 설정 ("autoUpgrade")
+  update/                   자동 업그레이드 상태
+$CODEX_HOME/plugins/cache/cairn/cairn/<version>/   Codex 플러그인 캐시 사본 (Codex를 선택했을 때만)
+```
+
+- 호스트: `--hosts`는 `install`과 `upgrade`에서만 받으며 값은 `all` 또는 `codex`, `claude`, `antigravity`의 쉼표 목록입니다. 선택은 ownership manifest에 기록되고 `upgrade`, `doctor`, `uninstall`이 따릅니다. `cairn upgrade --hosts <list>`는 호스트를 추가하고 빠진 호스트를 제거합니다(빠지는 호스트의 관리 파일이 수정됐으면 거부). 대화형 prompt는 전체(기본), Claude Code만, Codex만, Antigravity만, 쉼표 목록을 제시하며 아직 아무것도 설치되지 않았을 때만 나옵니다.
+- 이전: Cairn 0.6.0 이하에서 만든 설치(`$CODEX_HOME/plugins/cache/cairn` 아래 전체)는 `cairn upgrade` 한 번으로 `~/.cairn/install/`로 옮겨지고, Claude Code 플러그인도 새 marketplace 경로로 다시 등록됩니다. 이전이 실패하거나 중단되면 원래 상태로 복구하고, 수정된 관리 파일이 있으면 아무것도 바꾸지 않고 거부합니다. legacy 설치는 모든 호스트를 가진 채 이전되므로 전체가 아닌 `--hosts`는 거부되며, 다음 실행에서 고릅니다. 이전한 뒤에는 이 레이아웃을 아는 Cairn CLI로만 설치본을 다루고, 이전 중 열려 있던 세션은 다시 시작합니다.
+- 유예: 버전이 바뀌는 업그레이드는 직전 canonical runtime과 Codex 캐시 사본을 3일 동안(종류별 최대 3개) 남겨, 업그레이드 전에 시작한 세션이 계속 동작하게 합니다. 기간이 지난 것은 다음 install이나 upgrade가 제거하고, uninstall은 모두 제거합니다. 새 버전과 같거나 높은 Codex 캐시 사본은 남기지 않습니다. Codex는 캐시에서 가장 높은 버전을 로드하기 때문입니다.
+- 자동 업그레이드: 기본으로 켜져 있습니다. 24시간에 한 번 이하로(설치·업그레이드 직후 24시간은 제외) `SessionStart`가 분리 프로세스를 시작합니다. 이 프로세스는 npm에서 `cairn-ai` 최신 버전을 읽고, 그 정확한 버전을 `--ignore-scripts`로 `~/.cairn/update/stage/`에 설치해 검증한 뒤, 그 패키지의 `cairn-lifecycle.mjs upgrade --auto`를 실행합니다. major를 포함한 모든 새 버전을 적용하며 다운그레이드하지 않습니다. 다음 `SessionStart`는 결과를 한 줄로 한 번만 알립니다: `updated`, `failed`, `manual`(설치됐지만 Claude Code 플러그인 캐시에 `claude plugin update cairn@cairn`이 필요함). npm 조회·설치 실패는 알림 없이 backoff하고, 업그레이드 실패는 backoff하며 버전마다 한 번 알립니다. git 체크아웃에서 설치한 설치본(`origin: "checkout"`)과 소스 체크아웃 실행에서는 동작하지 않습니다.
+- 끄기: `cairn auto-upgrade off`, `CAIRN_AUTO_UPGRADE=0`(`false`, `off`, `no`도 가능), 또는 `~/.cairn/config.json`의 `"autoUpgrade": false`. 읽을 수 없는 `config.json`도 자동 업그레이드를 끕니다. 상태와 마지막 실행 출력은 `~/.cairn/update/`(`state.json`, `notice.json`, `last-run.log`, `update.lock`, `stage/`)에 있습니다.
 
 ## Antigravity Compatibility
 

package/README.md

@@ -100,7 +100,7 @@ At `SessionStart`, the hook tells the agent which memory notes exist (name and `
 
 Before `goal finish`, `cairn-work` records one memory promotion decision per goal in the plan's Evidence: `Memory promotion: docs/memory/<domain>.md` when the goal produced reusable repository knowledge, otherwise `Memory promotion: none: <reason>`. The decision is required; writing a note is optional. When a goal completes and its plan file has no filled `Memory promotion:` line, `goal finish` and `goal complete` print a one-line reminder on stderr without changing the exit code or stdout.
 
-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. If the shared runtime or a locator is missing, unreadable, or inconsistent, stop using every mirror that points to it. Run `bunx cairn-ai@latest doctor` from the published package, then `bunx cairn-ai@latest upgrade` to recover it; do not repair one host from another mirror or search the target repository for runtime files.
+Runtime scripts, templates, commands, agents, and model guidance stay in the installed canonical runtime, `~/.cairn/install/runtime/<version>/`. Runtime locator files let Codex, Claude Code, and Antigravity share that installed copy without copying Cairn internals into the target repository. If the shared runtime or a locator is missing, unreadable, or inconsistent, stop using every mirror that points to it. Run `bunx cairn-ai@latest doctor` from the published package, then `bunx cairn-ai@latest upgrade` to recover it; do not repair one host from another mirror or search the target repository for runtime files.
 
 ## Commands
 
@@ -123,12 +123,14 @@ cairn upgrade
 cairn doctor
 cairn uninstall
 cairn toolcheck
+cairn auto-upgrade status
 ```
 
-- `cairn install`: transactionally installs the custom marketplace source, versioned Codex runtime cache, Cairn-owned config sections, Claude Code mirrors and plugin, and current Antigravity IDE/CLI skill surfaces.
-- `cairn upgrade`: replaces only ownership-manifest entries whose installed digests still match, with staged validation and reverse-order rollback on failure.
-- `cairn doctor`: validates the ownership manifest, managed digests, effective Codex features, actual installed/enabled/version plugin state, and mirror/runtime locators without repairing them.
-- `cairn uninstall`: verifies every non-config ownership-manifest entry against its installed digest first and refuses the whole uninstall, changing nothing, if any managed artifact was modified or removed. Otherwise it removes or restores the managed entries, prunes empty managed cache scaffolds, preserves unmanaged targets and their parent directories, and rolls back pre-commit failures.
+- `cairn install [--hosts all|codex,claude,antigravity]`: transactionally installs the canonical runtime under `~/.cairn/install/` and, for the selected hosts, the Codex marketplace source, versioned Codex runtime cache, and Cairn-owned config sections, the Claude Code mirrors and plugin, and the current Antigravity IDE/CLI skill surfaces. Without `--hosts`, a first install at a terminal asks which hosts to use; non-interactive runs and CI install every host.
+- `cairn upgrade [--hosts all|codex,claude,antigravity]`: replaces only ownership-manifest entries whose installed digests still match, with staged validation and reverse-order rollback on failure. It keeps the recorded hosts unless `--hosts` changes them, migrates an installation made by Cairn 0.6.0 or earlier, and refreshes a Claude Code plugin cache that still holds another version. When the installed version is newer than this CLI, `install` and `upgrade` refuse without changing anything; `--allow-downgrade` installs this CLI's version anyway.
+- `cairn doctor`: prints `Hosts: <ids>` first, then validates the ownership manifest, managed digests, effective Codex features, actual installed/enabled/version plugin state (including `Claude plugin cache version`), and mirror/runtime locators of the selected hosts without repairing them. A legacy installation is reported with a hint to run `cairn upgrade`.
+- `cairn uninstall`: verifies every non-config ownership-manifest entry against its installed digest first and refuses the whole uninstall, changing nothing, if any managed artifact was modified or removed. Otherwise it removes or restores the managed entries and retained runtimes, prunes empty managed scaffolds, preserves unmanaged targets and their parent directories, and rolls back pre-commit failures. It also removes `~/.cairn/update/` and keeps `~/.cairn/config.json` and `~/.cairn/projects/`. A legacy-layout installation is removed in place without migrating.
+- `cairn auto-upgrade status|on|off|run`: `status` prints the setting, installed version, last check, and pending notice as JSON; `on` and `off` write `autoUpgrade` to `~/.cairn/config.json` and print the same report; `run` checks npm now, ignoring the daily interval and backoff, and prints the result. Exit 0 is success, 1 an execution error or a failed run, 2 a usage error.
 - `cairn toolcheck`: detects repository stacks and checks required LSP and verification tools; installation runs only for an approved supported installer.
 - `cairn cleanup --root <repo>`: reports legacy project-local `.cairn` residue without changing it; `--yes` migrates/reconciles valid active state into the user-home store, removes only known Cairn state/lock/tool residue, preserves unknown files, and prunes the directory only when empty. A `state.lock` is removed only when it holds a valid lock record whose owner process on this host is dead, and a quarantined `state.lock.stale.*` file only when its valid record's nonce matches its name; live-owner, foreign-host, and unparsable locks are preserved and listed with a reason in `preservedReasons`. `--help` and `--version` exit 0; usage errors exit 2 and runtime errors exit 1 with one `Cairn cleanup error:` line.
 - `cairn goal ...`: starts, inspects, pauses, resumes, blocks, cancels, and completes a persisted repository goal. `goal claim --session <id>` hands an unfinished goal to the session that continues the same work (resume, compaction, handoff, fork); new work that arrives during an unfinished goal is folded in with `goal replan` instead of cancelling it. State lives under user-home `.cairn`, separated by repository and Git worktree; state without `worktreeId` and state copied from another worktree are stale and removed on the next hook/goal start. Successful completion or cancellation removes active state because completed evidence already lives in the plan document, while paused/blocked state remains resumable. The default tool-bound policy records successful evidence by executing `goal verify -- <argv>`. The legacy `goal receipt` command imports declared evidence only. `--root` is optional for every `goal` subcommand (it resolves via `HARNESS_REPO_ROOT`, else the nearest ancestor containing `.git`). `goal verify --kind "moduleAcceptance|surfaceIntegration" -- <argv>` records one receipt per kind from one run; evidence scopes are `task` and `goal`. `goal finish [--watch "<path|path>"] [--timeout-ms N] -- <argv>` completes the active task (its evidence must be fresh), runs the argv once, records every goal requiredEvidence kind (default `finalReview`) at goal scope, and completes the goal; once that goal-scope evidence is recorded after every task receipt, earlier task checks are not rerun. `goal stats` prints JSON receipt counts, reruns, and stale receipts for the current goal. `goal stats --history [--limit N]` aggregates the repository's finished goals across worktrees: completed/cancelled counts, median and p90 duration, task and receipt medians, rerun rate, memory promotion decisions, an older/newer `trend` once 4 goals have completed, and the most recent goals; with no history it prints `{"schemaVersion":1,"scope":"repository","goals":0}`. `completionCriteria` (`goal start --criteria`) is `advisory`: Cairn records it but does not enforce it, and completion is gated only by required evidence. Tasks declare `dependsOn` (omitted = previous task) and `writeScope`; `goal ready` prints active/ready/blocked task ids, and up to 4 ready tasks with disjoint write scopes can be active in parallel in the same worktree.
@@ -143,13 +145,37 @@ On every `UserPromptSubmit`, Cairn injects model-visible guidance that non-trivi
 
 For token-efficient execution, Cairn puts reasoning into a focused executable test contract—requirements, invariants, boundaries, and failure modes—before implementation. Implementation receives the failing contract and bounded file scope, then makes the minimum passing change. Tool exit codes and machine summaries decide success; successful output stays concise and only failures expand context. Verification climbs from focused tests to one final full check. With no explicit `--watch`, a Git workspace fingerprint covers tracked and non-ignored untracked files; ignored artifacts are excluded. Any ignored artifact needed by the claim must be named with an explicit `--watch <path>` (or an explicit containing directory). Before package verification, inspect lifecycle scripts and run normal `npm pack --dry-run` by default: content-producing or unknown scripts must never use `--ignore-scripts`; only absent or proven content-neutral scripts may use it while the full-check evidence remains fresh. Successful state mutations support `--quiet` so growing goal JSON does not consume the conversation budget.
 
-Install and upgrade keep the custom marketplace lifecycle; they do not invoke `codex plugin add`. Candidates are staged and validated before commit, every current managed destination and digest is recorded in an ownership manifest, and committed phases roll back in reverse order on failure. The separate pinned SHA-256 release 0.2.2 file-hash allowlist verifies the exact legacy file set only; it is not the current package file list and is not a cryptographic signature. An exact unmodified supported legacy installation can be adopted after release-integrity validation; modified or unknown artifacts are preserved and rejected. Cairn edits only its own TOML sections and never forces public feature or agent settings. The source plugin manifest stays validator-friendly; only the installed cache copy gets a `hooks` field. Lifecycle commands must run from the published/global package, not from the cached copy that they replace.
+Install and upgrade keep the custom marketplace lifecycle; they do not invoke `codex plugin add`. Candidates are staged and validated before commit, every current managed destination and digest is recorded in an ownership manifest, and committed phases roll back in reverse order on failure. The separate pinned SHA-256 release 0.2.2 file-hash allowlist verifies the exact legacy file set only; it is not the current package file list and is not a cryptographic signature. An exact unmodified supported legacy installation can be adopted after release-integrity validation; modified or unknown artifacts are preserved and rejected. Cairn edits only its own TOML sections and never forces public feature or agent settings. The source plugin manifest stays validator-friendly; only the installed copies get a `hooks` field. Lifecycle commands must run from the published/global package, not from an installed copy under `~/.cairn/install/` or the Codex plugin cache that they replace.
 
-Clean uninstall removes the Cairn marketplace cache root only when every managed scaffold is empty, using empty-directory removal rather than recursive deletion. It does not delete the source repository, repository `MEMORY.md`/`PLAN.md`, user-home Cairn goal state, the global `cairn-ai` package, package-manager download caches, legacy backups, or legacy shared settings outside the current ownership manifest; those require a separate explicit cleanup decision.
+Clean uninstall removes `~/.cairn/install/` and the Codex cache root `$CODEX_HOME/plugins/cache/cairn` only when every managed scaffold is empty, using empty-directory removal rather than recursive deletion. It does not delete the source repository, repository `MEMORY.md`/`PLAN.md`, user-home Cairn goal state, the global `cairn-ai` package, package-manager download caches, legacy backups, or legacy shared settings outside the current ownership manifest; those require a separate explicit cleanup decision.
 
 Codex uses `skills/` and `commands/`. Claude Code uses mirrored commands and agent definitions under `~/.claude/` plus a Claude Code plugin, `cairn@cairn`. Antigravity uses `.agents/workflows` and global skills mirrors.
 
-The Claude Code plugin is generated in a Cairn-owned local marketplace at `~/.codex/plugins/cache/cairn/claude` and carries the four Cairn skills and the SessionStart, UserPromptSubmit, PostToolUse, Stop, and SubagentStop hooks, which call the installed versioned runtime by absolute path. After the files commit, `cairn install`/`upgrade` registers it through `claude plugin marketplace add` and `claude plugin install cairn@cairn --scope user`, so it appears in the Claude Code terminal, desktop app, and IDE plugin lists from the next session. Registration is skipped with a manual command when the `claude` CLI is missing, and a different marketplace already named `cairn` is never touched. `cairn uninstall` unregisters only Cairn's own marketplace before removing files, and re-registers it if the uninstall rolls back. `cairn doctor` reports `Claude plugin files`, `Claude plugin registered`, and `Claude plugin enabled`.
+The Claude Code plugin is generated in a Cairn-owned local marketplace at `~/.cairn/install/claude` and carries the four Cairn skills and the SessionStart, UserPromptSubmit, PostToolUse, Stop, and SubagentStop hooks, which call the canonical runtime by absolute path. After the files commit, `cairn install`/`upgrade` registers it through `claude plugin marketplace add` and `claude plugin install cairn@cairn --scope user`, so it appears in the Claude Code terminal, desktop app, and IDE plugin lists from the next session. Registration is skipped with a manual command when the `claude` CLI is missing, and a different marketplace already named `cairn` is never touched. `cairn uninstall` unregisters only Cairn's own marketplace before removing files, and re-registers it if the uninstall rolls back. When the Claude Code plugin cache holds a different version, `cairn upgrade` refreshes it with `claude plugin marketplace update cairn` and `claude plugin update cairn@cairn --scope user`; if the refresh fails, the upgrade stays installed, prints those commands to finish by hand, and exits 1. `cairn doctor` reports `Claude plugin files`, `Claude plugin registered`, `Claude plugin enabled`, and `Claude plugin cache version`.
+
+## Install Layout And Auto-Upgrade
+
+Cairn keeps its installation under `CAIRN_HOME` (default `~/.cairn`). `CODEX_HOME`, `CLAUDE_HOME`, `ANTIGRAVITY_HOME`, `ANTIGRAVITY_CLI_HOME`, and `CODEX_CONFIG_PATH` still set the host paths independently.
+
+```text
+~/.cairn/
+  install/                  lifecycle-managed files
+    lifecycle.json          ownership manifest (schema 2: hosts, origin, retained runtimes)
+    lifecycle.lock, transaction.json, transactions/
+    runtime/<version>/      canonical runtime used by every runtime locator and the Claude Code hooks
+    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 (only when Codex is selected)
+```
+
+- Hosts: `--hosts` takes `all` or a comma list of `codex`, `claude`, and `antigravity`, on `install` and `upgrade` only. The selection is recorded in the ownership manifest, and `upgrade`, `doctor`, and `uninstall` follow it; `cairn upgrade --hosts <list>` adds hosts and removes deselected ones (a modified artifact of a deselected host is refused). The interactive prompt offers all hosts (default), Claude Code only, Codex only, Antigravity only, or a comma list, and appears only when nothing is installed yet.
+- Migration: an installation made by Cairn 0.6.0 or earlier (everything under `$CODEX_HOME/plugins/cache/cairn`) moves to `~/.cairn/install/` with one `cairn upgrade`, which also re-registers the Claude Code plugin from its new marketplace path. A failed or interrupted migration is restored, and modified managed files refuse the migration without changes. A legacy installation migrates with every host, so a narrower `--hosts` is refused until the next run. After migration, manage the installation only with a Cairn CLI that knows this layout, and restart sessions that were open during it.
+- Retention: an upgrade that changes the version keeps the previous canonical runtime and Codex cache copy for 3 days (at most 3 of each) so sessions started before it keep working. The next install or upgrade removes expired ones, and uninstall removes all of them. A Codex cache copy at or above the new version is never kept, because Codex loads the highest cached version.
+- Auto-upgrade: on by default. At most once every 24 hours (and not within 24 hours of an install or upgrade), `SessionStart` starts a detached process that reads the latest `cairn-ai` version from npm, installs that exact version into `~/.cairn/update/stage/` with `--ignore-scripts`, verifies the staged package, and runs its `cairn-lifecycle.mjs upgrade --auto`. Every newer release is applied, major versions included, and it never downgrades. The next `SessionStart` shows one line, once: `updated`, `failed`, or `manual` (installed, but the Claude Code plugin cache still needs `claude plugin update cairn@cairn`). npm lookup and install failures back off silently; a failed upgrade backs off and is announced once per version. It never runs for an installation from a git checkout (`origin: "checkout"`) or from a source checkout.
+- Turning it off: `cairn auto-upgrade off`, `CAIRN_AUTO_UPGRADE=0` (also `false`, `off`, or `no`), or `"autoUpgrade": false` in `~/.cairn/config.json`. A `config.json` that cannot be read also turns it off. State and the last run's output live in `~/.cairn/update/` (`state.json`, `notice.json`, `last-run.log`, `update.lock`, `stage/`).
 
 ## Antigravity Compatibility