@iseoane/agent-depot 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-12
+
+### Added
+
+- The TUI fills the terminal and shows five numbered views. Switch with `1` through `5` or Tab/Shift+Tab. Resizing updates the layout. Xeo colors distinguish resource roles and status; `y` confirmations use bold green.
+- Sources lists Git Sources and App recipes together. Approve recipes there; Catalog offers installation only for approved recipes verified absent. Installations retains installed Apps when approval expires and separates installation status from version evidence.
+- Profile v2 can include identity-only replica intent for installed Skills, Apps and Packages. Export carries individual Skill selections and complete Package origin declarations, not installed state or approvals. The parser accepts Profile v1; v1-only readers reject v2. Import does not transfer approval or automatically install Apps or Packages.
+
+### Changed
+
+- App recipe, refresh and update previews require review of every physical row before confirmation. After a resize, review any rows not yet displayed. Arrow keys and PageUp/PageDown move by visible pages.
+- `u` in Updates opens the selected batch preview. It does not apply updates until the user reviews the preview and confirms.
+- The Import/Export view groups Source choices, Skills, Apps and Packages under a collapsed Sources parent. Installed replicas and export notes have separate groups. Replica entries carry identity only and do not claim that the destination has installed those resources.
+
+### Fixed
+
+- The TUI fills the terminal from startup and recalculates its layout on resize. Unmanaged Skill symlinks are marked distinctly in Installations.
+- The real-terminal test harness waits for fully rendered frames and isolates test state from inherited user paths. Cleanup waits for views to unmount before removing temporary state.
+
+## [0.5.2] - 2026-10-11
+
+### Added
+
+- `agent-depot self update [--yes]` checks npm and updates only a verified npm global installation after explicit confirmation. Other installation methods receive manual guidance; downgrades are refused.
+- A Pi Package containing the `/agents` panel, with a versioned snapshot-provider contract, measured telemetry, active-first newest-first ordering and stable selection. Migrating from the former pstack panel requires the coordinated adapter described in `docs/pi-agents-panel.md`.
+- Manual npm trusted publishing through GitHub Actions OIDC, with version, source commit and tarball integrity checks, without stored npm tokens.
+
+### Changed
+
+- Agent instructions use focused context pointers and a disclosed workflow guide. English and Spanish usage docs describe current Package ownership, TUI controls and delegated-command safety limits.
+
+### Fixed
+
+- `doctor-md-agents` analyzes Pi correction history and reports missing or unsupported sources explicitly. `doctor-md-skill` follows the active Pi session branch rather than scoring abandoned branches.
+- Installed Pi Packages with local changes display the version declared at verified Git HEAD, qualified as HEAD-only evidence. Local modifications still prevent update assessment and never become persisted verified installation evidence.
+- TUI tests wait for a complete resized frame and unmount views before deleting their temporary state, avoiding CI teardown races.
+
 ## [0.5.1] - 2026-10-07
 
 ### Changed

package/README.es.md

@@ -20,11 +20,12 @@ Qué hace:
 - **Instalaciones existentes**: informa de los Skills no gestionados que ya hay en
   disco, adopta los que coinciden exactamente con una Source o los elimina mediante
   una ruta explícita.
-- **Apps**: instala, actualiza y desinstala aplicaciones globales de usuario mediante
-  App recipes escritas por el usuario que deben aprobarse antes de ejecutarse.
+- **Apps**: gestiona aplicaciones globales de usuario mediante App recipes escritas
+  por el usuario. Aprobar una receta autoriza sus comandos, pero no instala la App;
+  la instalación tiene su propia previsualización y confirmación.
 - **Packages**: instala, actualiza y desinstala bundles nativos del Host (paquetes de
   Pi y plugins de Claude Code) delegando el ciclo de vida en la CLI de cada Host y
-  leyendo la versión instalada de los propios archivos de estado del Host. Un bundle
+  leyendo evidencia de instalación y versión propiedad del Host. Un bundle
   reserva sus Skills solo mientras lo hayas seleccionado o un Host demuestre que está
   instalado, así que los Skills de un bundle no seleccionado siguen siendo instalables
   por separado.
@@ -32,8 +33,13 @@ Qué hace:
   de Packages globales de usuario a un archivo portable e impórtalos, solo añadiendo,
   en otra máquina.
 
-Agent Depot nunca sobrescribe ni elimina contenido sin una previsualización y una
-confirmación, y rechaza rutas y enlaces inseguros.
+Agent Depot previsualiza y confirma los cambios del sistema de archivos que
+gestiona. Esta garantía no cubre los efectos de comandos delegados. Los métodos de
+Skill proporcionados por el usuario, las App recipes aprobadas y los comandos de
+Host aprobados para Packages se ejecutan como procesos hijos. Agent Depot no puede
+previsualizar por completo ni revertir los efectos que queden fuera de sus propios
+cambios gestionados. Agent Depot rechaza rutas y enlaces inseguros en sus
+operaciones gestionadas del sistema de archivos.
 
 Requiere Node.js >= 24 (Active LTS). La [TUI interactiva](#tui-interactiva)
 necesita un terminal interactivo.
@@ -68,13 +74,23 @@ npx @iseoane/agent-depot@latest tui
 pnpm dlx @iseoane/agent-depot@latest tui
 ```
 
-Una instalación global se actualiza con el gestor de paquetes que la instaló:
+Comprueba y actualiza una instalación global de npm con Agent Depot:
 
 ```sh
-npm install --global @iseoane/agent-depot@latest
-pnpm add --global @iseoane/agent-depot@latest
+agent-depot self update
+agent-depot self update --yes
 ```
 
+El primer comando consulta el registro público de npm y previsualiza una versión más
+reciente sin actualizar. El segundo repite la comprobación, previsualiza el destino
+exacto y lo instala. Agent Depot solo admite este flujo si la ruta del paquete cargado
+coincide con el directorio global que informa npm. Para las demás instalaciones,
+incluidas las de pnpm, npx, locales de proyecto, mediante enlace o de procedencia
+desconocida, muestra instrucciones manuales. La actualización invoca npm sin shell,
+desactiva los scripts del paquete y no solicita privilegios elevados ni cambia la
+configuración de npm. Si npm falla durante la instalación, el paquete global puede
+quedar actualizado solo en parte; Agent Depot no puede revertir los cambios de npm.
+
 Un Agent Depot en ejecución nunca degrada los Skills integrados: un Skill instalado
 por un Agent Depot más reciente se notifica como no actualizable (actualiza primero
 Agent Depot).
@@ -94,10 +110,10 @@ agent-depot source remove git:<source-id> --yes
 agent-depot source remove git:<source-id> --skill <id|path> --yes
 agent-depot source migrate git:<old-source-id> git:<new-source-id> --skill <path> --yes
 agent-depot discover builtin:agent-depot git:<source-id>
-agent-depot install --scope project --source builtin:agent-depot --skill architecture --host pi --version latest --portable-v1 --yes
-agent-depot install --scope user-global --source builtin:agent-depot --skill architecture --host pi --version latest --portable-v1 --yes
+agent-depot install --scope project --source builtin:agent-depot --skill agent-depot-apprecipe --host pi --version latest --portable-v1 --yes
+agent-depot install --scope user-global --source builtin:agent-depot --skill agent-depot-apprecipe --host pi --version latest --portable-v1 --yes
 # Only for an explicitly reviewed, untracked real-directory conflict:
-agent-depot install --scope project --source builtin:agent-depot --skill architecture --host pi --version latest --portable-v1 --overwrite --yes
+agent-depot install --scope project --source builtin:agent-depot --skill agent-depot-apprecipe --host pi --version latest --portable-v1 --overwrite --yes
 agent-depot install --scope project --manifest --portable-v1 --yes
 agent-depot update check --scope project
 agent-depot update apply --scope project --all --yes
@@ -251,7 +267,7 @@ actualizable. Solo para `--scope user-global`, la comprobación también informa
 directorios de Skill reales `Unmanaged` encontrados en ubicaciones absolutas exactas
 bajo las raíces globales de usuario admitidas. Estos no son candidatos a
 actualización, no se incluyen en los recuentos de estado de los gestionados y nunca
-se buscan a través de una Source. Las comprobaciones de proyecto no inventarían ni
+se buscan a través de una Source. Las comprobaciones de proyecto no examinan ni
 informan de directorios no gestionados.
 
 Las entradas globales omitidas o inseguras se muestran por separado con
@@ -328,7 +344,7 @@ un único objeto de método JSON estricto, por ejemplo:
 
 ```sh
 agent-depot install --scope user-global --source builtin:agent-depot \
-  --skill architecture --host pi --version latest \
+  --skill agent-depot-apprecipe --host pi --version latest \
   --method '{"kind":"command","argv":["node","scripts/install.mjs"],"cwd":"tools"}' \
   --portable-v1 --yes
 ```
@@ -391,7 +407,7 @@ directorio real sin registrar cuyo contenido difiere, el reemplazo requiere tant
 
 ```sh
 agent-depot install --scope project --source builtin:agent-depot \
-  --skill architecture --host pi --version latest --portable-v1 --overwrite --yes
+  --skill agent-depot-apprecipe --host pi --version latest --portable-v1 --overwrite --yes
 ```
 
 La previsualización es explícita sobre esta distinción: sin `--yes` no se modifica
@@ -491,29 +507,38 @@ agent-depot tui
 
 La TUI es un front end de [Ink](https://github.com/vadimdemedes/ink) (React para
 terminales) sobre las mismas operaciones que la CLI. Necesita Node.js >= 24 y un
-terminal interactivo; en caso contrario, `tui` falla con un error. Cambia de vista
-con `1`-`5` y sal con `q` (no mientras haya un aviso abierto). Toda lista se
-desplaza cuando es más alta que el terminal. `j`/`k` o las flechas mueven la
-selección.
+terminal interactivo; en caso contrario, `tui` falla con un error. Usa la pantalla
+alternativa del terminal y vuelve a la pantalla anterior al salir. Se adapta al
+redimensionado del terminal. El encabezado con bordes muestra la versión activa del
+paquete en ejecución y las cinco vistas numeradas. Cambia de vista con `1`-`5` o Tab/Shift+Tab,
+y sal con `q` (no mientras haya un aviso abierto). La paleta Xeo distingue roles y
+estados; las confirmaciones con `y` se muestran en negrita y verde. Las listas se
+desplazan cuando superan la altura del terminal. En Sources, Catalog, Installations y Updates,
+`j`/`k` o las flechas mueven
+una fila; `PageUp` y `PageDown` avanzan una página visible. Usa un terminal de al
+menos 40 columnas para revisar las notas de exportación de Profile; con 24 columnas,
+se recortan la pestaña del encabezado y el título de la nota.
 
 | Vista | Propósito |
 | --- | --- |
 | 1 Sources | Sources de Git (sus skills y Packages) y recetas App del usuario en una sola lista, con tipos `skills`/`app` y acciones contextuales. |
-| 2 Catalog | Skills que se pueden instalar: los que aún no están instalados, como Source y luego Skills. Cada Source muestra además un grupo Packages, y los Skills que posee un bundle se marcan y se atenúan. |
-| 3 Installations | Lo que hay en disco: instalaciones gestionadas (globales de usuario y de proyecto), selecciones de Packages y skills globales de usuario no gestionados. |
-| 4 Updates | Skills y Packages gestionados con una versión más reciente disponible, para el ámbito global de usuario y de proyecto. |
-| 5 Import/Export | Transferir las elecciones portables de Sources globales de usuario, las selecciones de Skills, las App recipes y las selecciones de Packages. |
+| 2 Catalog | Skills y Packages disponibles, además de App recipes aplicables y aprobadas cuya ausencia se ha verificado. La instalación de una App tiene una previsualización y confirmación separadas. Las recetas inválidas o sin aprobar permanecen en Sources; un estado desconocido nunca se trata como ausencia. Los Packages que el Host confirma como instalados se ocultan; los seleccionados o con estado desconocido siguen visibles. Los Skills propiedad de Packages conservan su comportamiento actual. |
+| 3 Installations | Apps cuya instalación está confirmada, instalaciones de Skills gestionadas (globales de usuario y de proyecto), selecciones de Packages con pertenencia al Host y evidencia de versión mostradas por separado, y Skills globales de usuario no gestionados. Un registro de instalación de App permanece visible aunque caduque la aprobación de la receta, pero sus acciones siguen exigiendo aprobación vigente. |
+| 4 Updates | Skills gestionados en el ámbito global de usuario y de proyecto, además de Apps y Packages instalados globales de usuario con una versión más reciente disponible. Las Apps desconocidas o no verificadas no se tratan como instaladas. |
+| 5 Profile | Exportar o importar elecciones portables de Sources globales de usuario, selecciones individuales de Skills, App recipes y selecciones de Packages. Las réplicas solo identifican recursos cuya instalación se confirmó en el origen. |
 
 Teclas por vista (los avisos también aceptan `Esc` para cancelar y `y`/`n` para
 confirmar):
 
 | Vista | Teclas |
 | --- | --- |
-| Sources | `j`/`k` recorren Sources de Git y recetas App, sin cambiar de sección con Tab. `Enter` abre el Catálogo de una Source de Git (sus skills y Packages) o previsualiza/aprueba una receta. `n` añade una Source de Git reutilizable o guía la creación de recetas; `r` refresca Sources o recarga el estado de recetas; `d` elimina. `space`/`a` solo marcan Sources de Git. |
-| Catalog | `Enter`/flechas expandir y contraer, `space` marcar, `a` marcar todos los listados, `i` instalar las Skills marcadas (o el skill resaltado) o previsualizar el bundle de Package resaltado, `/` filtrar, `s` alternar entre una Source o todas (cuando se abre desde una Source) |
-| Installations | `Enter`/flechas expandir y contraer, `u` desinstalar (todos los Hosts o los Hosts elegidos) o eliminar un skill no gestionado, `h` o `i` añadir Hosts a una instalación, `A` o `Enter` adoptar un skill no gestionado, `space` marca una hoja y `a` marca todas las hojas visibles: con marcas, `u` y `h` actúan sobre todas ellas con una única previsualización combinada y una única confirmación (las instalaciones de proyecto se omiten con un motivo). En una fila de Package: `i` previsualiza el plan de instalación congelado y lo ejecuta, aprobando antes el recibo si falta; `Enter` solo aprueba la declaración de instalación; `U` actualiza, `u` desinstala, `f` olvida el registro de selección. Las filas de Package no se pueden marcar para acciones por lotes. |
-| Updates | `space` marcar, `a` marcar todo, `t`/`p`/`g` mostrar todo, proyecto o global de usuario, `Enter` previsualizar las marcas, `r` comprobar de nuevo, las flechas pliegan la línea "cannot assess". Un Package marcado se une al lote y se aprueba antes de ejecutar su actualización. |
-| Import/Export | `e` exportar, `i` importar; introduce una ruta de archivo, `space` alterna opciones, `a` alterna todas, `Enter` previsualiza, `y` aplica; `j`/`k` desplazan las previsualizaciones y los resultados |
+| Sources | `j`/`k` recorren Sources de Git y recetas App. `Enter` abre el Catálogo de una Source de Git o previsualiza/aprueba una receta App. Aprobarla no instala la App. `n` añade una Source reutilizable o guía la creación de recetas; `r` refresca Sources o recarga el estado de recetas; `d` elimina. `space`/`a` solo marcan Sources de Git. La previsualización de refresco muestra todas las Sources seleccionadas; usa `j`/`k` o PgUp/PgDn para revisarlas antes de `y`; `n` cancela. |
+| Catalog | `Enter`/flechas expanden y contraen; `space` marca el Skill disponible resaltado; `a` marca o desmarca los Skills disponibles visibles de su Source; `i` inicia la instalación de los Skills marcados o del Skill, Package o App aprobada cuya ausencia se verificó y que está resaltada. Confirma la instalación de una App por separado con `y`. `/` filtra y `s` amplía la vista de una Source a todas. Las marcas de otras Sources se conservan y no se instalan Skills ocultos por el filtro. |
+| Installations | `Enter`/flechas expanden y contraen. En filas globales de usuario, `u` inicia la desinstalación de una App o Skill gestionada, o elimina un Skill no gestionado; los Skills de proyecto no se pueden eliminar. `h` o `i` añade Hosts a una instalación global de usuario, y `A` o `Enter` adopta un Skill no gestionado. `space` marca una hoja y `a` marca todas las hojas visibles; las acciones por lotes omiten instalaciones de proyecto con un motivo. En una fila de App, `u` previsualiza la desinstalación y `h` selecciona setup/teardown; las recetas modificadas requieren una nueva aprobación. En una fila de Package, `i` previsualiza el plan de instalación congelado y lo ejecuta, aprobando antes el recibo si falta; `Enter` solo aprueba la declaración de instalación; `U` actualiza, `u` desinstala y `f` olvida el registro de selección. Las filas de Package no se pueden marcar para acciones por lotes. |
+| Updates | `space` marca una actualización, `a` marca todas las actualizaciones disponibles y `t`/`p`/`g` selecciona todo, el ámbito de proyecto o el global de usuario. `Enter` previsualiza las filas marcadas; `u` previsualiza el lote seleccionado; ninguna aplica actualizaciones. `r` vuelve a comprobar y las flechas izquierda/derecha pliegan o despliegan el grupo "cannot be checked". En una previsualización, las flechas o PageUp/PageDown avanzan una página visible y `j`/`k` una fila. Revisa todas las filas antes de `y`; `n` cancela. Las filas desconocidas son informativas. Packages y Apps solo se gestionan en el ámbito global de usuario; Packages requieren aprobación de acción antes de ejecutar una actualización. |
+| Profile | `e` exportar, `i` importar; introduce una ruta de archivo, `space` alterna opciones, `a` alterna todas, `Enter` previsualiza, `y` aplica; `j`/`k` desplazan las previsualizaciones y los resultados |
+
+Las previsualizaciones desplazables muestran todas las declaraciones y los términos de ejecución. Usa `j`/`k` para avanzar una fila, o las flechas y `PageUp`/`PageDown` para avanzar una página visible. Confirma solo después de mostrar cada fila física. Si cambias el tamaño del terminal, revisa las filas que aún no se han mostrado.
 
 Al eliminar una receta App se comprueban su comando de versión aprobado y su
 seguimiento. Si la App está instalada o sigue registrada, la TUI ofrece el flujo
@@ -659,8 +684,8 @@ agent-depot app teardown example --host pi --yes
 ```
 
 Cada paso previsualiza su texto argv/manual, el ejecutable resuelto, el directorio de
-trabajo (el personal del usuario) y el entorno. El recurso manual solo se produce
-cuando un proceso no puede lanzarse, nunca tras una salida con código distinto de
+trabajo (el directorio personal del usuario) y el entorno. Las instrucciones
+manuales solo se ofrecen cuando un proceso no puede iniciarse, nunca tras una salida con código distinto de
 cero (que se notifica con stdout/stderr). Ejecuta tú mismo las instrucciones manuales
 mostradas y después certifica la finalización sin volver a ejecutar el argv:
 
@@ -738,10 +763,12 @@ nunca cambian el seguimiento de Apps instaladas.
 ## Packages
 
 Un Package es un bundle nativo del Host descubierto dentro de una Source registrada:
-un paquete de Pi (un `package.json` con una clave `pi`, o los directorios
-convencionales `extensions/`, `skills/`, `prompts/` y `themes/`) o un plugin de Claude
-Code (un `.claude-plugin/plugin.json` vinculado por un
-`.claude-plugin/marketplace.json` dentro del repositorio). Un mismo repositorio puede
+un paquete de Pi (un `package.json` con una clave `pi`, la palabra clave
+`pi-package` o un directorio convencional específico de Pi, como `extensions/` o
+`prompts/`) o un plugin de Claude Code (un `.claude-plugin/plugin.json` vinculado
+por un `.claude-plugin/marketplace.json` dentro del repositorio). Los directorios
+`skills/` y `themes/` también son convencionales en Claude Code, por lo que un
+repositorio que solo contiene Skills compartidos no se identifica como paquete de Pi. Un mismo repositorio puede
 ser ambas cosas, como `pstack-claude`. V1 solo admite los Hosts Pi y Claude Code; el
 empaquetado de Codex y OpenCode, los paquetes de Pi procedentes de npm y los Packages
 de ámbito de proyecto quedan aplazados.
@@ -749,10 +776,28 @@ de ámbito de proyecto quedan aplazados.
 Agent Depot no copia el contenido de un bundle. Lee el manifiesto del bundle en un
 inventario de componentes tipado, deriva los comandos propios del Host a partir de esa
 declaración, los ejecuta mediante el ejecutor de comandos sin shell tras la aprobación
-y lee la versión instalada de los archivos de estado del Host. El Host posee lo que
-está instalado. Agent Depot posee el registro de selección y el recibo de lo que
-delegó. Los Skills propios de un bundle nunca se ofrecen para adopción ni se instalan
-por segunda vez, porque el Host posee sus archivos y ubicaciones.
+y lee el estado instalado de archivos propiedad del Host. Agent Depot lee esos
+archivos y nunca los escribe. Para Pi, el ajuste `packages` de
+`~/.pi/agent/settings.json` identifica un paquete configurado. Agent Depot verifica
+después el checkout bajo `$PI_CODING_AGENT_DIR/git` (o `~/.pi/agent/git` si la
+variable no está definida): la raíz del checkout, `origin`, el commit `HEAD` y el
+`package.json` de ese commit. Si no puede verificar la raíz, el origen o `HEAD`, el
+paquete sigue instalado, pero su versión no está disponible. Si los cambios locales
+hacen que el checkout esté modificado, Agent Depot muestra la versión de `HEAD`, pero
+no usa el commit para evaluar actualizaciones. Installations y `package inspect`
+indican `(HEAD; local changes)` en la etiqueta. La fila de Installations muestra
+`update not checked · local changes`; Updates sigue indicando `cannot assess` y no
+ofrece el Package para actualizar. Tanto los cambios en archivos controlados como
+los archivos sin seguimiento cuentan; Agent Depot no ignora archivos
+de bloqueo ni otros archivos locales. La versión del manifiesto sirve para mostrar
+información, pero no demuestra que el checkout coincida con la Source seleccionada.
+La evaluación de actualizaciones compara el commit de un checkout limpio con el
+commit disponible de la Source mediante la ascendencia en el historial en caché.
+Para Claude, Agent Depot lee los archivos de estado de plugins y marketplaces. El
+Host posee lo que está instalado. Agent Depot posee el registro de selección y el
+recibo de lo que delegó. Mientras un Package está seleccionado o confirmado como instalado, sus
+Skills declarados no pueden adoptarse ni instalarse por separado. Un descriptor
+descubierto, por sí solo, no reserva sus Skills.
 
 ### Añadir una Source y descubrir sus bundles
 
@@ -834,8 +879,12 @@ evidencia de versión que Agent Depot registró. La evidencia en vivo procede de
 `~/.pi/agent/settings.json` y `~/.claude/plugins/installed_plugins.json`, que Agent
 Depot lee y nunca escribe. Un archivo de Host ausente es una vista vacía. Un archivo
 desviado o ilegible deja la búsqueda afectada en `unknown` y nunca lanza una
-excepción. Un paquete git de Pi sin versión se informa como `unknown`, nunca como
-`current`.
+excepción. Un paquete Git de Pi cuyo manifiesto no declara versión aún puede tener evidencia
+de commit verificada. Si Agent Depot verifica la identidad del checkout, pero detecta
+cambios locales, puede mostrar la versión del manifiesto de `HEAD`, pero no comparar
+el checkout para buscar actualizaciones. Si no puede verificar la raíz, el origen o
+`HEAD`, la versión instalada no está disponible. En ambos casos, el estado de
+actualización es `cannot assess`, no `current`.
 
 Una actualización registra una versión nueva solo cuando el estado del Host cambió de
 una forma que Agent Depot puede verificar, es decir, cuando las dos observaciones
@@ -863,8 +912,14 @@ comando del Host y deja la instalación del Host tal cual.
   de pin admitida por Claude.
 - Un plugin de Claude sin vinculación a un marketplace dentro del repositorio se
   informa pero no es instalable.
-- Agent Depot no lee la salida en prosa de la CLI del Host, incluido `pi list`. La
-  evidencia instalada procede solo de los archivos de estado del Host.
+- Agent Depot no usa la salida en prosa de la CLI del Host, incluido `pi list`, como
+evidencia del estado instalado. Para Pi, combina el ajuste de solo lectura con
+evidencia del checkout verificado. Para Claude, lee los archivos de estado del Host.
+Nunca escribe esos archivos.
+
+## Panel de agentes de Pi
+
+Agent Depot también incluye una extensión de Pi con el panel `/agents`. Muestra estado, actividad y consumo medido desde un proveedor conectado, con los agentes en ejecución primero y los más nuevos antes que los antiguos. Es un Package, no un Skill ni una App. Instalarlo junto a pstack requiere el adaptador coordinado de snapshots para evitar dos comandos `/agents`; sin proveedor, informa de que no hay datos disponibles. Consulta los [detalles de instalación y del proveedor](docs/pi-agents-panel.md).
 
 ## Exportar un Profile global de usuario
 
@@ -886,16 +941,22 @@ combinar el filtro de inclusión de un bloque con su indicador `--no-*` son erro
 
 La salida estándar contiene solo JSON; stderr muestra la previsualización y los
 motivos de exclusión. `--out` requiere un archivo nuevo (los archivos existentes y
-los enlaces simbólicos no se reemplazan). Los Profiles contienen URL de Git
-canónicas con su inclusión en el descubrimiento, las políticas de versión/Hosts/
-métodos de usuario registrados de los Skills, recipes de App completas, incluidas
-las recipes de otras plataformas, y selecciones de Package solo como declaraciones:
-su Source, coordenadas de Host y política de versión. La exportación por CLI siempre
-escribe
-`included: true`; las elecciones de descubrimiento son transitorias, mientras que la
+los enlaces simbólicos no se reemplazan). Los Profiles contienen URL de Git canónicas con su inclusión en el descubrimiento,
+selecciones individuales de Skills con sus políticas de versión, Hosts y métodos de
+usuario registrados, recipes de App completas (incluidas las de otras plataformas) y
+selecciones de Package como declaraciones, con su origen Source completo,
+coordenadas de Host y política de versión. Un Profile v2 también puede incluir
+intención de réplica, solo con la identidad de Skills, Apps y Packages cuya
+instalación se confirmó en la máquina de origen. No incluye estado de instalación,
+recibos, aprobaciones ni rutas locales. El parser actual lee los
+Profiles v1 anteriores; los lectores antiguos que solo admiten v1 rechazan los v2.
+La exportación por CLI siempre escribe `included: true`; las elecciones de descubrimiento son transitorias, mientras que la
 TUI puede pasar elecciones de inclusión explícitas al núcleo de exportación
-compartido. La exportación no refresca Sources ni ejecuta comandos de Apps, y un
-recibo de Package nunca viaja en un Profile.
+compartido. La exportación no refresca Sources ni ejecuta comandos del ciclo de vida.
+Puede ejecutar la sonda existente de versión de App aprobada e inspeccionar Packages
+sin escritura para determinar la intención de réplica actual; un estado desconocido no
+se considera instalado y la inspección no reconcilia registros. Los recibos de Package
+nunca viajan en un Profile.
 
 Las rutas locales y las credenciales evidentes no son portables. Los elementos no
 portables o inválidos se excluyen con sus motivos, al igual que los Skills no
@@ -959,9 +1020,15 @@ registro; la previsualización nombra las Sources no registradas que se obtendr
 registrarse. Las filas de Sources existentes explican cuándo la inclusión en el
 descubrimiento difiere pero no se importa.
 
-La pestaña **5 Import/Export** de la TUI ofrece listas de verificación agrupadas y
-las mismas previsualizaciones del núcleo compartido que la CLI. Las exclusiones y los
-conflictos no pueden seleccionarse. La exportación solo crea un archivo nuevo; las
+La pestaña **5 Import/Export** de la TUI empieza con el grupo padre **Sources**
+contraído. Dentro contiene grupos anidados para elecciones de Source, Skills, Apps y
+Packages; cada recurso muestra la identidad de su Source. **Installed replicas** y las
+notas de exportación son grupos separados. Usa las mismas previsualizaciones del núcleo
+compartido que la CLI. Las réplicas identifican recursos cuya instalación se confirmó
+en la máquina de origen; no incluyen el estado de instalación, las aprobaciones ni el
+contenido completo de la máquina. La importación solo añade; nunca transfiere
+aprobaciones ni instala automáticamente Apps o Packages. Las exclusiones y los conflictos
+no pueden seleccionarse. La exportación solo crea un archivo nuevo; las
 exportaciones vacías no escriben nada (la CLI informa de un error). La importación
 añade las elecciones que faltan sin reemplazar las existentes. Las recipes importadas
 permanecen sin aprobar y la importación nunca instala Apps. Las selecciones de Package

package/README.md

@@ -19,19 +19,24 @@ What it does:
   needs explicit confirmation.
 - **Existing installations**: report unmanaged Skills already on disk, adopt the
   ones that exactly match a Source, or remove them by explicit path.
-- **Apps**: install, update and uninstall user-global applications through
-  user-written App recipes that must be approved before they run.
+- **Apps**: manage user-global applications through user-written App recipes.
+  Approval authorizes recipe commands but does not install an App; installation
+  has its own preview and confirmation.
 - **Packages**: install, update and uninstall host-native bundles (Pi packages and
   Claude Code plugins) by delegating the lifecycle to each Host's own CLI and
-  reading the installed version from the Host's own state files. A bundle reserves
+  reading Host-owned installation and version evidence. A bundle reserves
   its Skills only while you have selected it or a Host proves it installed, so an
   unselected bundle's Skills stay installable on their own.
 - **Profiles**: export your user-global Sources, Skill selections, App recipes and
   Package selections to a portable file and import them, add-only, on another
   machine.
 
-Agent Depot never overwrites or deletes content without a preview and confirmation,
-and refuses unsafe paths and links.
+Agent Depot previews and confirms the filesystem changes it manages. This
+guarantee does not cover side effects from delegated commands. User-provided Skill
+methods, approved App recipes, and approved Package Host commands run as child
+processes. Agent Depot cannot fully preview or roll back their effects outside its
+managed changes. Agent Depot rejects unsafe paths and links in its managed
+filesystem operations.
 
 Requires Node.js >= 24 (Active LTS). The [interactive TUI](#interactive-tui)
 needs an interactive terminal.
@@ -66,13 +71,22 @@ npx @iseoane/agent-depot@latest tui
 pnpm dlx @iseoane/agent-depot@latest tui
 ```
 
-A global install is updated with the package manager that installed it:
+Check and update an npm global installation with Agent Depot:
 
 ```sh
-npm install --global @iseoane/agent-depot@latest
-pnpm add --global @iseoane/agent-depot@latest
+agent-depot self update
+agent-depot self update --yes
 ```
 
+The first command checks the public npm registry and previews a newer version without
+updating. The second repeats the check, previews its exact target, and applies it.
+Agent Depot supports this flow only when its loaded package directory matches the
+global directory reported by npm. It prints manual guidance for other installations,
+including pnpm, npx, project-local, linked, and unknown installations. The update uses
+npm without a shell, disables package lifecycle scripts, and never requests elevated
+privileges or changes npm configuration. If npm fails during installation, the global
+package may be left partially updated; Agent Depot cannot roll back npm's changes.
+
 A running Agent Depot never downgrades built-in Skills: a Skill installed by a newer
 Agent Depot is reported as not updatable (update Agent Depot first).
 
@@ -91,10 +105,10 @@ agent-depot source remove git:<source-id> --yes
 agent-depot source remove git:<source-id> --skill <id|path> --yes
 agent-depot source migrate git:<old-source-id> git:<new-source-id> --skill <path> --yes
 agent-depot discover builtin:agent-depot git:<source-id>
-agent-depot install --scope project --source builtin:agent-depot --skill architecture --host pi --version latest --portable-v1 --yes
-agent-depot install --scope user-global --source builtin:agent-depot --skill architecture --host pi --version latest --portable-v1 --yes
+agent-depot install --scope project --source builtin:agent-depot --skill agent-depot-apprecipe --host pi --version latest --portable-v1 --yes
+agent-depot install --scope user-global --source builtin:agent-depot --skill agent-depot-apprecipe --host pi --version latest --portable-v1 --yes
 # Only for an explicitly reviewed, untracked real-directory conflict:
-agent-depot install --scope project --source builtin:agent-depot --skill architecture --host pi --version latest --portable-v1 --overwrite --yes
+agent-depot install --scope project --source builtin:agent-depot --skill agent-depot-apprecipe --host pi --version latest --portable-v1 --overwrite --yes
 agent-depot install --scope project --manifest --portable-v1 --yes
 agent-depot update check --scope project
 agent-depot update apply --scope project --all --yes
@@ -299,7 +313,7 @@ method object, for example:
 
 ```sh
 agent-depot install --scope user-global --source builtin:agent-depot \
-  --skill architecture --host pi --version latest \
+  --skill agent-depot-apprecipe --host pi --version latest \
   --method '{"kind":"command","argv":["node","scripts/install.mjs"],"cwd":"tools"}' \
   --portable-v1 --yes
 ```
@@ -358,7 +372,7 @@ requires both `--overwrite` and `--yes`:
 
 ```sh
 agent-depot install --scope project --source builtin:agent-depot \
-  --skill architecture --host pi --version latest --portable-v1 --overwrite --yes
+  --skill agent-depot-apprecipe --host pi --version latest --portable-v1 --overwrite --yes
 ```
 
 The preview is explicit about this distinction: without `--yes`, zero files or
@@ -446,27 +460,35 @@ agent-depot tui
 
 The TUI is an [Ink](https://github.com/vadimdemedes/ink) (React for terminals)
 front end over the same operations as the CLI. It needs Node.js >= 24 and an
-interactive terminal; otherwise `tui` fails with an error. Switch views with
-`1`-`5`, quit with `q` (not while a prompt is open). Every list scrolls when it is
-taller than the terminal. `j`/`k` or the arrow keys move.
+interactive terminal; otherwise `tui` fails with an error. It uses the terminal's
+alternate screen and returns to the previous screen when you quit. It adjusts to
+terminal resizing. The bordered header shows the running package version and all five numbered views.
+Switch views with `1`-`5` or Tab/Shift+Tab, and quit with `q` (not while a prompt
+is open). The Xeo palette distinguishes resource roles and status; `y` confirmations
+are bold green. Lists scroll when they are taller than the terminal. In Sources, Catalog,
+Installations, and Updates, `j`/`k` or the arrows move one row; `PageUp` and
+`PageDown` move by one visible page. Use a terminal at least 40 columns wide to
+review Profile export notes; at 24 columns, the app header tab and note title clip.
 
 | View | Purpose |
 | --- | --- |
 | 1 Sources | Git Sources (their skills and Packages) and user-owned App recipes in one list, with `skills`/`app` kinds and contextual actions. |
-| 2 Catalog | Skills that can be installed: those not installed yet, as Source, then Skills. Each Source also shows a Packages group, and the Skills a bundle owns are marked and dimmed. |
-| 3 Installations | What is on disk: managed installations (user-global and project), Package selections and unmanaged user-global skills. |
-| 4 Updates | Managed skills and Packages with a newer version available, for user-global and project scope. |
-| 5 Import/Export | Transfer portable user-global Source choices, Skill selections, App recipes and Package selections. |
+| 2 Catalog | Available Skills and Packages, plus applicable approved App recipes verified as not installed. App installation has a separate preview and confirmation. Invalid or unapproved recipes remain in Sources; unknown App state is never treated as absence. Host-confirmed installed Packages are hidden; selected-only or unknown-state Packages remain visible. Package-owned Skills keep their existing behavior. |
+| 3 Installations | Confirmed installed Apps, managed Skill installations (user-global and project), Package selections with Host membership and version evidence shown separately, and unmanaged user-global Skills. App installation records remain visible if recipe approval later expires, but recipe actions still require current approval. |
+| 4 Updates | Managed Skills in project and user-global scope, plus user-global installed Apps and Packages with a newer version available. Unknown or unverified Apps are not treated as installed. |
+| 5 Profile | Export or import portable user-global Source choices, individual Skill selections, App recipes and Package selections. Replica entries report confirmed origin-machine identities only. |
 
 Keys per view (prompts also accept `Esc` to cancel and `y`/`n` to confirm):
 
 | View | Keys |
 | --- | --- |
-| Sources | `j`/`k` move through Git Sources and App recipes (no Tab section switch). `Enter` opens the Catalog for a Git Source (its skills and Packages) or previews/approves an App recipe. `n` adds a reusable Git Source or guides recipe authoring; `r` refreshes Sources or reloads recipe status; `d` removes. `space`/`a` mark Git Sources only. |
-| Catalog | `Enter`/arrows expand and collapse, `space` mark, `a` mark all listed, `i` install the marked Skills (or the highlighted skill) or preview the highlighted Package bundle, `/` filter, `s` toggle one Source or all (when opened from a Source) |
-| Installations | `Enter`/arrows expand and collapse, `u` uninstall (all Hosts or chosen Hosts) or remove an unmanaged skill, `h` or `i` add Hosts to an installation, `A` or `Enter` adopt an unmanaged skill, `space` marks a leaf and `a` marks all visible leaves: with marks, `u` and `h` act on all of them with one combined preview and one confirmation (project installations are skipped with a reason). On a Package row: `i` previews the frozen install plan and runs it, approving the receipt first when it is missing, `Enter` approves the install declaration only, `U` update, `u` uninstall, `f` forget the selection record. Package rows are not markable for bulk actions. |
-| Updates | `space` mark, `a` mark all, `t`/`p`/`g` show all, project or user-global, `Enter` preview the marks, `r` check again, arrows fold the "cannot assess" line. A marked Package joins the batch and is approved before its update runs. |
-| Import/Export | `e` export, `i` import; enter a file path, `space` toggle choices, `a` toggle all, `Enter` preview, `y` apply; `j`/`k` scroll previews and results |
+| Sources | `j`/`k` move through Git Sources and App recipes. `Enter` opens the Catalog for a Git Source or previews/approves an App recipe. Approval does not install the App. `n` adds a Git Source or guides recipe authoring; `r` refreshes Sources or reloads recipe status; `d` removes. `space`/`a` mark Git Sources only. Refresh previews show every selected Source; review every physical row before `y`. `n` cancels. |
+| Catalog | `Enter`/arrows expand and collapse, `space` marks the highlighted loose Skill, `a` marks or clears the visible loose Skills in its Source, and `i` starts installation for marked Skills or the highlighted Skill, Package, or verified-absent approved App. Confirm an App install separately with `y`. `/` filters and `s` widens a Source view to all Sources. Marks in other Sources remain unchanged; Skills hidden by the filter are not installed. |
+| Installations | `Enter`/arrows expand and collapse. On user-global rows, `u` starts an App or managed Skill uninstall, or removes an unmanaged Skill; project Skills cannot be removed. `h` or `i` adds Hosts to a user-global Skill installation, and `A` or `Enter` adopts an unmanaged Skill. `space` marks a leaf and `a` marks all visible leaves; bulk actions skip project installations with a reason. On an App row, `u` previews uninstall and `h` selects setup/teardown; changed recipes must be approved again before commands run. On a Package row, `i` previews the frozen install plan and runs it, approving the receipt first when it is missing; `Enter` approves the install declaration only, `U` updates, `u` uninstalls, and `f` forgets the selection record. Package rows are not markable for bulk actions. |
+| Updates | `space` marks an update, `a` marks all available updates, and `t`/`p`/`g` selects all, project, or user-global scope. `Enter` previews the marked rows; `u` previews the selected batch; neither applies updates. `r` checks again, and left/right arrows fold or unfold the "cannot be checked" group. In a preview, arrows or PageUp/PageDown move by a visible page and `j`/`k` move one row. Review every row before `y`; `n` cancels. Unknown rows are informational. Packages and Apps are user-global only; Packages need action approval before update execution. |
+| Profile | `e` export, `i` import; enter a file path, `space` toggle choices, `a` toggle all, `Enter` preview, `y` apply; `j`/`k` scroll previews and results |
+
+Scrollable previews show every declaration and execution term. Use `j`/`k` to move one row, or the arrows and `PageUp`/`PageDown` to move by a visible page. Confirm only after every physical row has been displayed. Resizing a preview requires reviewing any rows that have not yet been displayed.
 
 Removing an App recipe checks its approved version command and tracked state.
 If the App is installed or tracked, the TUI offers the existing uninstall flow;
@@ -682,11 +704,26 @@ deferred.
 
 Agent Depot does not copy a bundle's contents. It reads the bundle manifest into a
 typed component inventory, derives the Host's own commands from that declaration,
-runs them through the no-shell command runner after approval, and reads the
-installed version back from the Host's state files. The Host owns what is
-installed. Agent Depot owns the selection record and the receipt for what it
-delegated. A bundle's own Skills are never offered for adoption or installed a
-second time, because the Host owns their files and locations.
+runs them through the no-shell command runner after approval, and reads installed
+state from Host-owned files. Agent Depot reads those files and never writes them.
+For Pi, the `packages` setting in `~/.pi/agent/settings.json` identifies a
+configured package. Agent Depot then verifies the checkout under
+`$PI_CODING_AGENT_DIR/git` (or `~/.pi/agent/git` when unset): the checkout root,
+`origin`, `HEAD` commit, and `package.json` at that commit. If the root, origin, or
+`HEAD` cannot be verified, the package remains installed but its version is
+unavailable. If local changes make the checkout dirty, Agent Depot still displays
+the version from `HEAD` but withholds the commit, so Updates reports `cannot assess`.
+Installations and `package inspect` mark that label as `(HEAD; local changes)`. The
+Installations row says `update not checked · local changes`; Updates still reports
+`cannot assess` and does not offer the Package for update. Tracked and untracked
+changes both count; Agent Depot does not ignore lockfiles or other local files. A manifest version is display evidence, not proof that the
+checkout matches the selected Source. Update assessment compares a clean checkout's
+commit with the available Source commit using ancestry in the cached Source history.
+For Claude, Agent Depot reads the plugin and marketplace state files. The Host owns
+what is installed. Agent Depot owns the selection record and the receipt for what it
+delegated. While a Package is selected or confirmed
+installed, its declared Skills cannot be adopted or installed separately. A
+discovered descriptor alone does not reserve its Skills.
 
 ### Add a Source and discover its bundles
 
@@ -767,7 +804,12 @@ evidence Agent Depot recorded. Live evidence comes from
 `~/.pi/agent/settings.json` and `~/.claude/plugins/installed_plugins.json`, which
 Agent Depot reads and never writes. A missing Host file is an empty view. A
 drifted or undecodable file leaves the affected lookup `unknown` and never throws.
-An unversioned Pi git package is reported as `unknown`, never as `current`.
+A Pi git package with no version in its manifest can still have verified commit
+evidence. If Agent Depot verifies the checkout identity but finds local changes, it
+can display the manifest version from `HEAD` but cannot use that checkout for update
+comparison. If it cannot verify the checkout root, origin, or `HEAD`, the installed
+version is unavailable. In either case, the update status is `cannot assess`, not
+`current`.
 
 An update records a new version only when the Host state changed in a way Agent
 Depot can verify, meaning the two observations agree on a version or a
@@ -793,8 +835,14 @@ and leaves the Host install as it is.
   fixed pin for a Pi selection, until a supported Claude pin form is verified.
 - A Claude plugin with no in-repo marketplace binding is reported but not
   installable.
-- Agent Depot does not read Host CLI prose output, including `pi list`. Installed
-  evidence comes from the Host state files only.
+- Agent Depot does not use Host CLI prose output, including `pi list`, as
+installed-state evidence. For Pi, it combines the read-only settings entry with
+verified checkout evidence. For Claude, it reads Host state files. Agent Depot
+never writes those Host files.
+
+## Pi agents panel
+
+Agent Depot also contains a Pi extension with an `/agents` panel. It displays agent status, activity and measured usage from a connected provider, placing running agents first and newer agents before older ones. This is a Package, not a Skill or App. Installing it alongside pstack requires the coordinated snapshot adapter to avoid duplicate `/agents` commands; without a provider, it reports unavailable data. See [installation and provider details](docs/pi-agents-panel.md).
 
 ## Export a user-global Profile
 
@@ -816,13 +864,20 @@ independently. Unknown selections and combining a block's inclusion filter with
 
 Stdout contains JSON only; stderr shows the preview and exclusion reasons.
 `--out` requires a new file (existing files and symlinks are not replaced).
-Profiles contain canonical Git URLs with discovery inclusion, recorded Skill
-version policies/Hosts/user methods, complete App recipes, including recipes for
-other platforms, and Package selections as declarations only: their Source, host
-coordinates and version policy. CLI export always writes `included: true`; discovery choices are transient, while
+Profiles contain canonical Git URLs with discovery inclusion, individual Skill
+selections with recorded version policies, Hosts and user methods, complete App
+recipes (including recipes for other platforms), and Package selections as
+declarations only, with their full Source origin, Host coordinates and version
+policy. A v2 Profile may also contain identity-only replica intent for Skills, Apps
+and Packages confirmed installed on the exporting machine. These entries do not
+carry installed state, receipts, approvals or local paths.
+The current parser reads legacy v1 files; v1-only older readers reject v2 files.
+CLI export always writes `included: true`; discovery choices are transient, while
 the TUI may pass explicit inclusion choices to the shared export core.
-Export neither refreshes Sources nor runs App commands, and a Package receipt never
-travels in a Profile.
+Export neither refreshes Sources nor runs lifecycle commands. It may run the existing
+approved App version probe and read-only Package inspection to determine current
+replica intent; unknown state is not treated as installed, and inspection does not
+reconcile records. Package receipts never travel in a Profile.
 
 Local paths and obvious credentials are not portable. Nonportable/invalid items
 are excluded with reasons, as are unmanaged/App-owned and project Skills,
@@ -876,8 +931,13 @@ so omitting their Source block does not force registration; the preview names
 unregistered Sources that will be fetched without registering. Existing Source
 rows explain when discovery inclusion differs but is not imported.
 
-The **5 Import/Export** TUI tab offers grouped checklists and the same shared-core
-previews as the CLI. Exclusions and conflicts cannot be selected. Export creates
+The **5 Import/Export** TUI tab starts with a collapsed **Sources** parent. It
+contains nested Source choices, Skills, Apps, and Packages groups; resource rows show
+their Source identities. **Installed replicas** and export notes are separate groups.
+Replica entries identify resources confirmed installed on the exporting machine.
+They do not contain installed state, approvals, or full machine contents. Import is
+add-only; it never transfers approval or automatically installs Apps or Packages.
+Exclusions and conflicts cannot be selected. Export creates
 a new file only; empty exports write nothing (CLI reports an error). Import adds missing choices without replacing existing ones.
 Imported recipes remain unapproved and Apps are never installed by import.
 Imported Package selections are recorded without installing a bundle and without