@iseoane/agent-depot 0.5.2 → 0.6.1

package/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-10-13
+
+### Added
+
+- The Profile TUI guides export through a folder picker and editable filename,
+  then shows the full destination and a confirmation preview. Import filters for
+  JSON files, can show all files, and keeps the picker open with inline read or
+  parse errors.
+
+### Changed
+
+- `e` exports the complete Profile selection from any checklist row. `Enter`
+  expands groups or previews notes without starting export.
+- Profile export and import previews use semantic colors for resource names,
+  Hosts, version policies, and fields, including wrapped continuation rows.
+
+### Fixed
+
+- Profile import applies the exact previewed subset, including selections after
+  unselected entries.
+- Export ignores stale filename checks after edits and refuses existing files
+  or symlinks without overwriting them. Folder navigation follows symlinked
+  directories and keeps the guidance visible in narrow terminals.
+- Moved bundled-skill tests to `tests/skills/`. `pnpm test:skills` runs each
+  suite in its own Python process with bytecode writes disabled, so tests no
+  longer alter skill trees and cause source-versus-packed hash checks to report
+  false updates.
+
+## [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

package/README.es.md

@@ -20,8 +20,9 @@ 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 evidencia de instalación y versión propiedad del Host. Un bundle
@@ -508,29 +509,100 @@ 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. Usa la pantalla
 alternativa del terminal y vuelve a la pantalla anterior al salir. Se adapta al
-redimensionado del terminal. Cambia de vista con `1`-`5` y sal con `q` (no mientras
-haya un aviso abierto). 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.
+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 y Packages disponibles, agrupados por Source. Los Packages que el Host confirma como instalados se ocultan; los que solo están seleccionados siguen visibles. Un Skill propiedad de un Package activo conserva el contraste normal y muestra una insignia breve; no se puede marcar ni instalar por separado. Sitúa el cursor encima para ver el motivo. |
-| 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 | Exporta o importa elecciones globales de usuario. Consulta el [flujo de Profile](#flujo-de-profile) para ver la lista y los pasos del selector de archivos. |
 
 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` alternar el Skill disponible resaltado, `a` alternar todos los Skills disponibles de la Source resaltada que coincidan con el filtro actual, `i` instalar los Skills marcados que coincidan con el filtro o el Skill disponible resaltado, o previsualizar el Package resaltado, `/` filtrar, `s` alternar una Source o todas (si se abrió desde una Source). Las marcas de otras Sources se conservan. |
-| 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 el grupo "cannot be checked". Sus filas son informativas y no se pueden marcar para actualizar. 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 | Pulsa `e` para exportar o `i` para importar. Consulta el [flujo de Profile](#flujo-de-profile) para ver la navegación, la selección, las previsualizaciones y las cancelaciones. |
+
+### Flujo de Profile
+
+La vista Profile transfiere elecciones portables globales de usuario. No
+transfiere instalaciones ni aprobaciones. Exportación e importación empiezan en
+la raíz del proyecto, salvo que la aplicación indique otro directorio inicial.
+
+#### Exportar
+
+1. Pulsa `e` en la vista Profile para crear y abrir la lista de exportación.
+   El grupo **Sources**, contraído al inicio, contiene grupos anidados para
+   Sources, Skills, Apps y Packages. **Installed replicas** y **Export notes**
+   son grupos separados. Pulsa `Enter` o las flechas para expandir o contraer un
+   grupo. `Enter` sobre una nota de exportación muestra sus detalles; nunca
+   inicia la exportación.
+2. Usa `j`/`k` o las flechas para moverte, `space` para alternar una fila
+   seleccionable y `a` para seleccionar todo o borrar la selección. Los
+   elementos excluidos y las filas informativas no se pueden seleccionar.
+   Pulsa `e` para exportar las filas seleccionadas. Si no hay ningún recurso
+   portable seleccionado, no se escribe nada. Pulsa `Esc` para salir de la
+   lista.
+3. Elige una carpeta de destino. Muévete con `j`/`k` o las flechas; pulsa
+   `Enter` para abrir una carpeta o selecciona **Use this folder** para elegir
+   la carpeta actual. Usa Izquierda o Retroceso para subir a la carpeta
+   superior. Pulsa `p` para mostrar la ruta completa y otra vez `p` para volver
+   al listado. `Esc` vuelve a la lista de exportación.
+4. Edita el nombre del archivo. El valor predeterminado es
+   `agent-depot-profile.json`. `Ctrl+U` borra el nombre y se añade `.json` si
+   falta una extensión. El editor muestra la ruta completa de destino. Pulsa
+   `Enter` para revisarla. Si la ruta ya existe, incluido un enlace simbólico,
+   aparece un error en línea y puedes elegir otro nombre; la exportación nunca
+   sobrescribe. `Esc` vuelve al selector de carpetas.
+5. Revisa la previsualización de exportación, incluidas las exclusiones y
+   advertencias. Usa `j`/`k` para avanzar una fila y las flechas o
+   `PageUp`/`PageDown` para avanzar una página visible. Pulsa `y` para escribir
+   el archivo nuevo. Pulsa `n` o `Esc` para cancelar y volver al editor del
+   nombre. Los resultados muestran la ruta final.
+
+#### Importar
+
+1. Pulsa `i` en la vista Profile para abrir el selector de archivos. Al
+   principio muestra archivos `.json` y carpetas. Pulsa `f` para mostrar todos
+   los archivos y otra vez `f` para filtrar de nuevo por `.json`. Navega con
+   `j`/`k` o las flechas; pulsa `Enter` para abrir una carpeta o seleccionar un
+   archivo, e Izquierda o Retroceso para subir a la carpeta superior. Pulsa `p`
+   para mostrar la ruta completa y otra vez `p` para volver. `Esc` vuelve a la
+   vista Profile.
+2. El archivo seleccionado se analiza y previsualiza. Si no se puede leer o
+   no es válido, aparece un error en línea y el selector permanece abierto para
+   elegir otro archivo. La lista de importación marca cada elemento como
+   **add**, **same** (omitido) o **conflict** (omitido, con las diferencias).
+   Solo se pueden seleccionar las adiciones. Usa `space` para alternar una
+   fila, `a` para seleccionar todas las adiciones o borrar la selección, y
+   `Enter` para previsualizar las adiciones seleccionadas. `Esc` vuelve a la
+   vista Profile.
+3. Revisa la previsualización exacta de importación. Usa `j`/`k` para avanzar
+   una fila y las flechas o `PageUp`/`PageDown` para una página visible. Pulsa
+   `y` para aplicar las adiciones seleccionadas, o `n`/`Esc` para cancelar y
+   volver a la lista de importación. Se informa del resultado de cada elemento;
+   un fallo no detiene las demás adiciones.
+
+Las recetas importadas siguen sin aprobarse. La importación no instala Apps ni
+Packages ni ejecuta comandos del Host. Las réplicas solo describen identidades
+en la máquina de origen; no transfieren aprobaciones ni estado de instalación.
+
+Las demás previsualizaciones desplazables de la TUI 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
@@ -604,8 +676,14 @@ Desde un checkout de código fuente, compila y ejecuta la CLI directamente:
 pnpm install
 pnpm build
 node dist/src/cli.js --version
+pnpm test:skills
 ```
 
+`pnpm test:skills` ejecuta los tests de la biblioteca estándar de Python
+ubicados en `tests/skills/`. Inicia un proceso Python separado para cada skill
+incluida y define `PYTHONDONTWRITEBYTECODE=1`, por lo que los tests no crean
+archivos de bytecode en los directorios de las skills.
+
 ## Análisis estático
 
 [Fallow](https://docs.fallow.tools) 3.30.0 se ejecuta mediante `npx --yes fallow@3.30.0`
@@ -777,8 +855,10 @@ variable no está definida): la raíz del checkout, `origin`, el commit `HEAD` y
 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. Tanto los cambios en archivos
-controlados como los archivos sin seguimiento cuentan; Agent Depot no ignora archivos
+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
@@ -931,16 +1011,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
@@ -1004,11 +1090,28 @@ 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
-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
-importadas se registran sin instalar ningún bundle y sin ejecutar ningún comando del
-Host.
+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.
+`e` exporta toda la selección marcada desde cualquier fila; `Enter` solo expande un grupo
+o previsualiza una nota, así que navegar nunca inicia una escritura. 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 y la importación comparten un navegador de directorios que empieza en la
+raíz del proyecto, lista carpetas (y, al importar, archivos `.json`) y se mueve con
+`j`/`k` o las flechas. La exportación elige una carpeta y luego rellena
+`agent-depot-profile.json` en un campo editable que muestra el destino completo;
+`Ctrl+U` lo borra, un nombre sin extensión recibe `.json`, y un archivo o enlace
+simbólico existente se rechaza en ese paso para volver a escribirlo. La importación
+navega hasta un archivo existente; `f` alterna entre archivos `.json` y todos los
+archivos, y un archivo mal formado informa en línea mientras el navegador sigue abierto.
+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 importadas se registran sin instalar ningún
+bundle y sin ejecutar ningún comando del Host.

package/README.md

@@ -19,8 +19,9 @@ 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 Host-owned installation and version evidence. A bundle reserves
@@ -461,28 +462,90 @@ 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. It uses the terminal's
 alternate screen and returns to the previous screen when you quit. It adjusts to
-terminal resizing. Switch views with `1`-`5`, quit with `q` (not while a prompt is
-open). Lists scroll when they are taller than the terminal. In Sources, Catalog,
+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.
+`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 | Available Skills and Packages, grouped by Source. Host-confirmed installed Packages are hidden; selected-only Packages remain visible. An active Package-owned Skill stays at normal contrast with a compact owner badge; it cannot be marked or installed separately. Move the cursor to it to see why. |
-| 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 choices. See [Profile workflow](#profile-workflow) for the complete checklist and file-picker steps. |
 
 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` toggle the highlighted loose Skill, `a` toggle all loose Skills in the highlighted Source that match the current filter, `i` install marked Skills that match the filter or the highlighted loose Skill, or preview the highlighted Package, `/` filter, `s` toggle one Source or all (when opened from a Source). Marks in other Sources remain unchanged. |
-| 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 be checked" group. Rows in that group are informational and cannot be marked for an update. 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 | Press `e` to export or `i` to import. See [Profile workflow](#profile-workflow) for navigation, selection, previews, and cancellation. |
+
+### Profile workflow
+
+The Profile view transfers portable user-global choices. It does not transfer
+installed state or approvals. Export and import begin in the project root, unless
+the application supplies another start directory.
+
+#### Export
+
+1. Press `e` in the Profile view to build and open the export checklist. Its
+   collapsed **Sources** group contains nested Source, Skill, App, and Package
+   choices. **Installed replicas** and **Export notes** are separate groups.
+   Expand or collapse a group with `Enter` or the arrow keys. `Enter` on an
+   export note opens its details; it never starts an export.
+2. Use `j`/`k` or the arrows to navigate, `space` to toggle a selectable row,
+   and `a` to select all or clear all. Excluded items and informational rows
+   cannot be selected. Press `e` to export the selected rows. If no portable
+   resource is selected, nothing is written. Press `Esc` to leave the checklist.
+3. Choose a destination folder. Move with `j`/`k` or the arrows, press `Enter`
+   to open a folder, or select **Use this folder** to choose the current one.
+   Use Left or Backspace to go to the parent. Press `p` to show the full
+   directory path; press `p` again to return to the listing. `Esc` returns to
+   the checklist.
+4. Edit the file name. The default is `agent-depot-profile.json`. `Ctrl+U`
+   clears the name, and a name without an extension gets `.json`. The editor
+   shows the complete destination path. Press `Enter` to review it. If the path
+   already exists, including a symlink, the view reports an inline error and
+   lets you choose another name; export never overwrites. `Esc` returns to the
+   folder picker.
+5. Review the export preview, including exclusions and warnings. Use `j`/`k`
+   to move one row and the arrows or `PageUp`/`PageDown` to move by a visible
+   page. Press `y` to write the new file, `n` or `Esc` to cancel and return to
+   the name editor. Results show the final path.
+
+#### Import
+
+1. Press `i` in the Profile view to open the file picker. It initially lists
+   `.json` files and folders. Press `f` to show every file, `f` again to filter
+   back to `.json`. Navigate with `j`/`k` or the arrows, use `Enter` to open a
+   folder or select a file, and Left or Backspace to go to the parent. Press
+   `p` to show the full directory path and `p` again to return. `Esc` returns
+   to the Profile view.
+2. The selected file is parsed and previewed. If it is invalid or cannot be
+   read, an inline error appears and the picker stays open so you can choose
+   another file. The import list marks entries as **add**, **same** (skipped), or
+   **conflict** (skipped with differences). Only additions can be selected. Use
+   `space` to toggle a row, `a` to select all additions or clear them, and
+   `Enter` to preview the selected additions. Press `Esc` to return to the
+   Profile view.
+3. Review the exact import preview. Use `j`/`k` for one row and the arrows or
+   `PageUp`/`PageDown` for a visible page. Press `y` to apply the selected
+   additions, or `n`/`Esc` to cancel and return to the import list. Each result
+   is reported; an item failure does not stop the remaining additions.
+
+Imported recipes remain unapproved. Import does not install Apps or Packages or
+run Host commands. Replica entries describe identity on the exporting machine
+only. They do not confer approval or installed state.
+
+Scrollable previews elsewhere in the TUI 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;
@@ -552,8 +615,14 @@ From a source checkout, build and run the CLI directly:
 pnpm install
 pnpm build
 node dist/src/cli.js --version
+pnpm test:skills
 ```
 
+`pnpm test:skills` runs the Python standard-library tests from `tests/skills/`.
+It starts a separate Python process for each bundled skill and sets
+`PYTHONDONTWRITEBYTECODE=1`, so the tests do not create bytecode files in the
+skill directories.
+
 ## Static analysis
 
 [Fallow](https://docs.fallow.tools) 3.30.0 runs through `npx --yes fallow@3.30.0`
@@ -707,9 +776,10 @@ configured package. Agent Depot then verifies the checkout under
 `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)`.
-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
+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
@@ -857,13 +927,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,
@@ -917,9 +994,23 @@ 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
-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
-running a Host command.
+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.
+`e` exports the whole marked selection from any row; `Enter` only expands a group or
+previews a note, so browsing never starts a write. 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 and import share one directory browser that starts at the project root, lists
+folders (and, for import, `.json` files), and moves with `j`/`k` or the arrows. Export
+picks a folder, then pre-fills `agent-depot-profile.json` in an editable name field that
+shows the complete destination; `Ctrl+U` clears it, a name without an extension gains
+`.json`, and an existing file or symlink is refused at that step so you can retype.
+Import browses to an existing file; `f` switches between `.json` files and every file,
+and a malformed file reports inline while the browser stays open. 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 running a Host command.