@nucleoabierto/teleprompter 0.1.1 → 0.2.0

package/README.md

@@ -17,25 +17,42 @@ registro auditable de la instalación en `teleprompter-lock.json`.
 No hace falta instalar nada: el CLI se ejecuta directamente con `npx`:
 
 ```sh
-npx @nucleoabierto/teleprompter install <paquete> <destino>
+npx @nucleoabierto/teleprompter user/repo
 ```
 
 También puede instalarse como herramienta global:
 
 ```sh
 npm install -g @nucleoabierto/teleprompter
-teleprompter install <paquete> <destino>
+teleprompter user/repo
 ```
 
 ## Uso
 
-`install` recibe el directorio del paquete y la raíz del repositorio
-destino. Antes de escribir nada, el instalador verifica el manifiesto y
+El primer argumento es el origen del paquete. `user/repo` descarga el
+tarball público del repositorio de GitHub —sin git ni credenciales—
+y usa la raíz del árbol como paquete; la referencia se elige con
+`user/repo@ref` o `--ref <ref>` (la rama por defecto si no se indica).
+Para un paquete local se usa `--path <directorio>`, que no procesa el
+argumento `user/repo`. El segundo argumento posicional es el destino
+de la copia —la raíz del repositorio donde instalar— y por defecto es
+el directorio de trabajo:
+
+```sh
+teleprompter nucleoabierto/mi-paquete          # remoto, destino: pwd
+teleprompter nucleoabierto/mi-paquete ./destino
+teleprompter nucleoabierto/mi-paquete@v1.2.0 ./destino
+teleprompter --path ./mi-paquete ./destino     # local
+teleprompter install nucleoabierto/mi-paquete  # alias
+```
+
+Antes de escribir nada, el instalador verifica el manifiesto y
 las precondiciones del paquete, calcula el plan completo y lo presenta
 recurso a recurso:
 
 ```text
-$ teleprompter install ./mi-paquete ./mi-repo
+$ teleprompter nucleoabierto/mi-paquete ./mi-repo
+obteniendo: nucleoabierto/mi-paquete
 verificado: mi-paquete@1.0.0
 plan de instalación:
   mkdir          .agents/skills/
@@ -63,8 +80,21 @@ Independiente de ellas, `--dry-run` muestra el plan y termina sin
 escribir nada.
 
 Terminada la ejecución se escribe `teleprompter-lock.json` en la raíz
-del destino: qué recursos instaló Teleprompter, con qué acción y con
-qué hash.
+del destino: qué recursos instaló Teleprompter, con qué acción, con
+qué hash y desde qué origen. Si el paquete declara instrucciones de
+personalización, su contenido se entrega tal cual al final del
+resultado y queda consultable después —desde la raíz del destino— con
+`teleprompter guide [<paquete>]`. El propio registro se consulta con
+`teleprompter list`, que muestra una entrada por paquete instalado:
+nombre, versión, fecha de instalación y recursos escritos.
+`teleprompter check` confronta el registro con el disco e informa por
+cada recurso si sigue intacto, fue modificado, ya no existe o no
+puede verificarse. Y `teleprompter update <paquete>` lleva un paquete
+instalado a la versión que publica su origen —el registrado en la
+instalación, o uno explícito con `--path`/`user/repo[@ref]`—:
+calcula el plan de actualización recurso a recurso, sobrescribe lo
+intacto, pregunta por lo editado y retira lo que la versión nueva ya
+no trae.
 
 ### Códigos de salida
 
@@ -75,6 +105,7 @@ qué hash.
 | `2`    | Plan no ejecutable (precondiciones o colisiones)     |
 | `3`    | Error de ejecución                                   |
 | `4`    | Error de invocación (argumentos o rutas)             |
+| `5`    | Error de obtención del repositorio remoto            |
 
 ## Documentación
 

package/bin/teleprompter.js

@@ -4,6 +4,8 @@ import { createAsker } from '../src/prompt.js';
 
 try {
   process.exitCode = await main(process.argv.slice(2), {
+    cwd: process.cwd(),
+    fetch,
     interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
     createAsker,
   });

package/docs/domains/001-paquete.md

@@ -33,6 +33,12 @@ destino— para que una instalación sea inspectable y repetible.
   - **Ruta segura:** ruta relativa sin segmentos `..`, ni absoluta
     POSIX, ni absoluta Windows (`C:\`) ni UNC (`\\`).
     - Ancla: `isSafeRelative` en `src/paths.js`
+  - **Guía de personalización:** el archivo que `personalization`
+    declara —debe existir dentro del paquete y ser un archivo—; su
+    contenido es texto libre del mantenedor dirigido a un agente,
+    nunca validado ni ejecutado.
+    - Ancla: `checkPersonalization` en `src/manifest.js`; origen:
+      épica `docs/epics/003-personalizacion-guiada.md`
 - **Entidades / estado:**
   - El paquete es inmutable y sin estado: existe como directorio con
     archivos más su manifiesto. La versión es semver explícita `x.y.z`
@@ -48,6 +54,9 @@ destino— para que una instalación sea inspectable y repetible.
     `source` existe. Ancla: `checkInstall` en `src/manifest.js`
   - `format`, si está presente, vale `teleprompter-package@1`.
     Ancla: `KNOWN_FORMAT` en `src/manifest.js`
+  - Ningún `target` es `teleprompter-lock.json` ni cae dentro de
+    `.teleprompter/`: son espacios reservados a la herramienta.
+    Ancla: `checkInstall` en `src/manifest.js`; D010
 - **Operaciones:**
   - Cargar y validar el manifiesto de un directorio de paquete:
     `loadManifest` en `src/manifest.js` —devuelve errores, avisos y el
@@ -66,8 +75,10 @@ destino— para que una instalación sea inspectable y repetible.
 - **Decisiones relevantes:**
   - `docs/decisions/D001–D004` — manifiesto JSON puro, cardinalidad,
     semver explícita, mapa `install`.
+  - `docs/decisions/D010` — `.teleprompter/` como namespace gestionado
+    para la guía de personalización.
 
 ## Estado de salud
 
-- Última revisión: 2026-09-28
+- Última revisión: 2026-09-29
 - Divergencias conocidas: Ninguna

package/docs/domains/002-instalacion.md

@@ -23,23 +23,56 @@ instalado.
     - Ancla: `buildPlan` en `src/plan.js`
   - **Resolución:** la decisión sobre un `conflict` —`overwrite` o
     `skip`— por flag, por respuesta interactiva o por aborto.
-    - Ancla: `src/cli.js` (bucle de resolución) y `createAsker` en
-      `src/prompt.js`
+    - Ancla: `resolveConflicts` en `src/plan.js` (la asignación es
+      operación del plan), `settleConflicts` en `src/cli.js` (la
+      política) y `createAsker` en `src/prompt.js`
   - **Registro (lock):** `teleprompter-lock.json` en la raíz del
     destino; por paquete guarda `version`, `installedAt` y `files`
     con `target`, acción y `sha256` —las entradas `skip` no llevan
-    hash. Es la memoria que distingue lo propio de lo ajeno.
-    - Ancla: `readLock` y `isValidLock` en `src/lock.js`; D007
+    hash— y `personalization` con la ruta gestionada de la guía
+    cuando el manifiesto la declara; `origin` registra de dónde vino
+    la instalación —`{type:'github',repo,ref?}` o
+    `{type:'path',path}` absoluta—, opcional en entradas escritas
+    antes del campo. Es la memoria que distingue lo propio de lo
+    ajeno.
+    - Ancla: `readLock`, `isValidLock`, `writeLock`, `lockEntry` y
+      `lockEntries` en `src/lock.js` —la forma del registro solo se
+      navega desde ese módulo— y `originOf` en `src/cli.js`;
+      D007, D014
   - **Propiedad:** un recurso es propio cuando el destino actual
     hashea igual que lo que el registro anotó para él.
     - Ancla: `recorded.get(target) === destHash` en `src/plan.js`
+  - **Deriva:** el estado de un recurso registrado al confrontarlo
+    con el disco —`intact` (el hash coincide), `modified` (difiere),
+    `missing` (la ruta ya no existe) o `unverifiable` (sin `sha256`
+    registrado, lectura fallida o ruta que escapa del destino); el
+    informe los presenta como `intacto`, `modificado`, `ausente` y
+    `no verificable`.
+    - Ancla: `classifyResource` en `src/drift.js`, que aplica el
+      nivel cadena de la defensa de rutas registradas
+      (`recordedChainSafe` en `src/paths.js`); contrato en
+      `docs/instalador.md` «La verificación del estado»
+  - **Plan de actualización:** el plan de una versión entrante
+    distinta de la registrada; además de las marcas de instalación
+    añade `update` (la versión cambió el recurso y el destino sigue
+    intacto) y `retire` (registrado, retirado por la versión e
+    intacto → eliminación), y marca los retirados con deriva como
+    `conflict` de eliminación —`overwrite` quita, `skip` conserva—.
+    Versión igual a la registrada → `upToDate`, sin plan.
+    - Ancla: `buildUpdatePlan` en `src/plan.js`; contrato en
+      `docs/instalador.md` «El plan de actualización»; D015
 - **Entidades / estado:**
   - `VerificationResult` — `kind: 'ok'|'manifest'|'requires'`, el
     manifiesto validado, `warnings`, `errors`, `creates` y `failures`.
     - Ancla: `verifyPackage` en `src/verify.js`
   - `Plan` — `{ mkdirs, resources, conflicts }`; cada recurso lleva
     `source`, `target`, `status` y, tras resolver, `resolution`.
-    - Ancla: `buildPlan` en `src/plan.js`
+    - Ancla: `buildPlan` y `resolveConflicts` en `src/plan.js`
+  - `UpdatePlan` — `{ upToDate, mkdirs, resources, conflicts,
+    retired }`; `resources` incluye las entradas del manifiesto y
+    los retirados con deriva marcados `removal`, `retired` solo las
+    marcas `retire`.
+    - Ancla: `buildUpdatePlan` en `src/plan.js`
   - Hash de recurso — SHA-256 sobre dominios separados (`file\n`,
     `link\n`, `dir\n`) para que tipos distintos nunca colisionen;
     los árboles ordenan sus entradas para que el digest sea
@@ -48,7 +81,8 @@ instalado.
 - **Invariantes:**
   - El plan completo se calcula antes de escribir; un plan no
     ejecutable aborta sin escribir nada —ni recursos ni registro
-    (D005). Ancla: `main` en `src/cli.js`
+    (D005). Ancla: `runInstall`/`runUpdate` y las fases
+    `settleConflicts`/`checkGuideDestination` en `src/cli.js`
   - «Existe» significa «hay una entrada en el directorio», sin seguir
     enlaces: un enlace colgado ocupa su ruta.
     Ancla: `hasEntry` en `src/paths.js`
@@ -69,23 +103,95 @@ instalado.
     ejecución. Ancla: `resolvesUnder` en `src/paths.js`
   - Dos entradas `install` no pueden compartir `target`: el plan sería
     ambiguo. Ancla: `checkInstall` en `src/manifest.js`
+  - `.teleprompter/` es propiedad de la herramienta, igual que el lock:
+    la guía declarada se copia ahí fuera del plan y sin detección de
+    colisiones, pero su destino se verifica escribible **antes** de
+    escribir nada —un escape hace el plan no ejecutable (D005)—.
+    Ancla: `installPersonalization` en `src/execute.js` y la
+    pre-verificación en `src/cli.js`; D010
   - Un recurso `identical` conserva su registro previo —el contenido
     sigue siendo propio— pero no crea registro si nunca se escribió.
     Ancla: `writeLock` en `src/lock.js`
+  - Un recurso retirado por la versión solo se elimina intacto —propio
+    y sin tocar—; modificado o no verificable exige decisión. Quedan
+    excluidos las entradas `skip` y el target de `personalization`
+    que el manifiesto **entrante** siga declarando. Si la versión
+    declara otra guía, la registrada se retira incluso modificada
+    —deja de ser la guía y un `keep` la dejaría huérfana para
+    `guide`; solo un `unverifiable` —ruta insegura— sigue siendo
+    decisión—; si la versión abandona el campo, la guía registrada se
+    retira como cualquier otro recurso (D015). Ancla:
+    `buildUpdatePlan` en `src/plan.js`
 - **Operaciones:**
-  - `teleprompter install <paquete> <destino> [--force|--skip]
-    [--dry-run]` — verifica, planea, resuelve, ejecuta y registra.
+  - `teleprompter [install] <user/repo[@ref]> [destino]` o
+    `teleprompter [install] --path <paquete> [destino]` — obtiene el
+    paquete (tarball público de GitHub o directorio local), verifica,
+    planea, resuelve, ejecuta y registra; el destino por defecto es el
+    directorio de trabajo.
     - Ancla: `bin/teleprompter.js` → `main` en `src/cli.js`
   - Ejecutar el plan resuelto: `mkdirs` primero, luego cada recurso
     según su acción; `overwrite` elimina el destino antes de escribir
     —nunca a través de un enlace— y los enlaces se copian como
-    enlaces.
-    - Ancla: `executePlan` en `src/execute.js`
+    enlaces. Un fallo a mitad lanza `ExecutionError`, que transporta
+    las acciones ya aplicadas y el error original como `cause`, para
+    que el informe muestre el estado parcial.
+    - Ancla: `executePlan` y `ExecutionError` en `src/execute.js`
   - Registrar la instalación: fusiona el lock preservando otros
-    paquetes; `identical` no se registra y `skip` va sin hash.
+    paquetes; `identical` no se registra y `skip` va sin hash; la
+    guía gestionada se añade a `files` y al campo `personalization`
+    sin figurar entre las acciones del plan. La escritura es
+    atómica —temporal en el mismo directorio + `rename`—, así que un
+    corte a mitad deja el lock anterior o el nuevo, nunca uno
+    truncado.
     - Ancla: `writeLock` en `src/lock.js`
+  - Materializar y entregar la guía: `installPersonalization` copia
+    el archivo declarado a `.teleprompter/<paquete>/<archivo>` tras
+    ejecutar el plan, y el bloque final `personalización (<ruta>):`
+    entrega el contenido de la copia materializada —no el fuente,
+    que en origen remoto ya no existe—.
+    - Ancla: `installPersonalization` en `src/execute.js` y
+      `printGuide` en `src/cli.js`
+  - Consultar la guía: `teleprompter guide [<paquete>]` lee el campo
+    `personalization` del registro del directorio de trabajo y
+    muestra el mismo bloque; no hay destino ni opciones de
+    instalación. Sin guía que mostrar es código 4; la ruta
+    registrada insegura o el archivo ausente es código 3 —el lock
+    es dato versionado y se revalida antes de leer.
+    - Ancla: `showGuide` en `src/cli.js`, que aplica el nivel hoja de
+      la defensa de rutas registradas (`resolveRecordedPath` en
+      `src/paths.js`); D011
+  - Consultar el registro: `teleprompter list` lee el registro del
+    directorio de trabajo —sin argumentos ni opciones— y muestra una
+    entrada por paquete con `nombre@version`, `installedAt` y los
+    `target` escritos; las entradas `skip` no se listan —registran
+    una omisión— y no se exponen hashes ni acciones. Sin
+    instalaciones responde «no hay paquetes instalados» con código
+    0: es una respuesta, no un fallo.
+    - Ancla: `showList` en `src/cli.js`; D012
+  - Calcular el plan de actualización: confronta la versión entrante
+    con el registro y el disco; devuelve `upToDate` si la versión es
+    la registrada, o el plan clasificado con los retirados según su
+    deriva —sin escribir nada—.
+    - Ancla: `buildUpdatePlan` en `src/plan.js`; D015
+  - Actualizar: `teleprompter update <paquete> [<origen>]` opera
+    sobre el directorio de trabajo —sin destino—; resuelve la fuente
+    del `origin` registrado salvo que la invocación lo sobrescriba
+    (`--path`, `user/repo[@ref]` o `--ref`), y luego ejecuta el flujo
+    de instalación con el plan de actualización. Los conflicts
+    `removal` preguntan por quitar y resuelven `remove`/`keep`; el
+    registro queda a la versión nueva con el origen efectivo.
+    - Ancla: `runUpdate` en `src/cli.js`; D016
+  - Verificar el estado de lo instalado: `teleprompter check`
+    confronta el registro del directorio de trabajo con el disco
+    —sin argumentos ni opciones— y muestra por paquete una marca de
+    deriva por recurso registrado; las entradas `skip` no se
+    verifican y encontrar deriva no es un fallo —la consulta siempre
+    termina con código 0—.
+    - Ancla: `showCheck` en `src/cli.js` y `classifyResource` en
+      `src/drift.js`; D013
   - Códigos de salida: 0 éxito, 1 manifiesto inválido, 2 plan no
-    ejecutable, 3 error de ejecución, 4 invocación.
+    ejecutable, 3 error de ejecución, 4 invocación, 5 obtención del
+    repositorio remoto.
     - Ancla: `EXIT_*` en `src/cli.js`; contrato en
       `docs/instalador.md` «Resultado y errores»
 
@@ -108,10 +214,25 @@ instalado.
     propiedad.
   - `docs/decisions/D008` — implementación JavaScript vía `npx` como
     `@nucleoabierto/teleprompter`.
+  - `docs/decisions/D010` — `.teleprompter/` como ubicación gestionada
+    de la guía de personalización.
+  - `docs/decisions/D011` — `guide` como subcomando de consulta sobre
+    el directorio de trabajo.
+  - `docs/decisions/D012` — `list` como subcomando de consulta del
+    registro sobre el directorio de trabajo.
+  - `docs/decisions/D013` — `check` como subcomando de verificación
+    del estado de los recursos instalados.
+  - `docs/decisions/D014` — `origin` en el registro: la procedencia
+    reobtenible de cada instalación.
+  - `docs/decisions/D015` — vocabulario del plan de actualización y
+    política de retirados.
+  - `docs/decisions/D016` — `update` como subcomando: resolución del
+    origen y acciones `remove`/`keep`.
 
 ## Estado de salud
 
-- Última revisión: 2026-09-28
+- Última revisión: 2026-10-01 (revisión de arquitectura
+  `docs/architecture-reviews/002-instalacion-tras-el-ciclo-de-vida.md`)
 - Divergencias conocidas: cuando un paquete sobrescribe un recurso
   registrado por otro, la entrada del primero queda intacta aunque su
   contenido ya no coincida —el plan siguiente lo marcará `conflict` en

package/docs/domains/README.md

@@ -6,4 +6,4 @@ anclado al código que lo materializa.
 - [001 — Paquete](001-paquete.md): el formato declarativo del
   manifiesto, sus rutas seguras y sus precondiciones.
 - [002 — Instalación](002-instalacion.md): verificación, plan,
-  colisiones, ejecución y registro de una instalación.
+  colisiones, ejecución, registro y consulta de una instalación.

package/docs/especificacion-paquete.md

@@ -47,6 +47,8 @@ marcar directorios, no un requisito del formato.
 
 Ni `source` ni `target` admiten rutas absolutas ni `..`: el origen no
 puede salir del paquete y el destino no puede salir del repositorio.
+Además, ningún `target` puede ser `teleprompter-lock.json` ni caer
+dentro de `.teleprompter/`: son espacios reservados a la herramienta.
 
 ### Campos opcionales
 
@@ -57,12 +59,12 @@ puede salir del paquete y el destino no puede salir del repositorio.
 | `license` | string | Identificador SPDX (`"MIT"`, `"Apache-2.0"`) o referencia a un archivo de licencia. |
 | `author` | object | `{ "name": "...", "email": "...", "url": "..." }`. Solo `name` es obligatorio dentro del objeto. |
 | `requires` | object | Precondiciones del repositorio destino, verificables antes de instalar. De momento solo la clave `paths`. |
-| `personalization` | string | Ruta dentro del paquete al archivo o directorio con instrucciones de personalización. Solo declara que existe adaptación pendiente y dónde está documentada; no se instala salvo que también figure en `install`. |
+| `personalization` | string | Ruta dentro del paquete al archivo con las instrucciones de personalización. El archivo debe existir; su contenido es texto libre del mantenedor dirigido a un agente y nunca se valida ni se ejecuta. El instalador lo copia a `.teleprompter/<paquete>/<archivo>` en el destino, entrega su contenido tal cual al final de la instalación y recuerda su ubicación en `teleprompter-lock.json` —consultable después con `teleprompter guide`. |
 | `metadata` | object | Mapa libre clave→valor para datos del autor que el instalador no interpreta. |
 
 `requires.paths` es una lista de entradas `{ "path", "create"? }` sobre
 rutas relativas a la raíz del destino (`path` no admite rutas absolutas
-ni `..`):
+ni `..`, ni puede caer dentro de `.teleprompter/`):
 
 - Si la ruta no existe y `create` es `false` o está ausente, la
   instalación aborta.
@@ -114,6 +116,7 @@ Estructura de un paquete con tres recursos:
 ```text
 ciclo-tareas/
 ├── teleprompter.json
+├── PERSONALIZE.md
 └── skills/
     ├── crear-tareas/
     ├── ejecutar-tareas/
@@ -146,6 +149,7 @@ Su manifiesto:
   "requires": {
     "paths": [{ "path": ".agents/skills/", "create": true }]
   },
+  "personalization": "PERSONALIZE.md",
   "metadata": { "origin": "teleprompter" }
 }
 ```
@@ -159,9 +163,12 @@ Su manifiesto:
 4. `install` no vacío; cada entrada tiene solo `source` y `target`;
    cada `source` existe dentro del paquete; ninguna ruta es absoluta ni
    contiene `..`.
-5. `source` y `personalization` apuntan dentro del paquete; `target` y
-   `requires.paths[].path` son relativos a la raíz del destino; ninguna
-   de estas rutas es absoluta ni contiene `..`.
+5. `source` y `personalization` apuntan dentro del paquete —
+   `personalization` a un archivo existente cuyo enlace no resuelve
+   fuera del paquete—; `target` y `requires.paths[].path` son relativos
+   a la raíz del destino; ninguna de estas rutas es absoluta ni
+   contiene `..`, ningún `target` es `teleprompter-lock.json` y nada
+   cae dentro de `.teleprompter/`.
 6. Los campos opcionales presentes pertenecen al contrato; dentro de
    objetos conocidos no hay campos desconocidos (a nivel superior, un
    campo desconocido solo genera un aviso, no invalida el manifiesto).

package/manual/001-instalar-un-paquete.md

@@ -1,6 +1,7 @@
 # Instalar un paquete
 
-El usuario ejecuta `teleprompter install <paquete> <destino>` para
+El usuario ejecuta `teleprompter <user/repo> [destino]` —o
+`teleprompter --path <paquete> [destino]` para un paquete local— para
 llevar los recursos de un paquete a un repositorio existente, con el
 plan completo visible antes de escribir y un registro de lo instalado.
 Qué es un paquete y qué garantiza la instalación están definidos en
@@ -10,6 +11,35 @@ mecánica detallada, en la [referencia](referencia-install.md).
 
 ## Escenarios
 
+- **El paquete puede venir de un repositorio público de GitHub:**
+  `user/repo` descarga el tarball por HTTP —sin git— e instala la raíz
+  del árbol extraído. — módulo `test/cli.test.js`, «user/repo with OUT
+  installs into it»
+- **`install` es un alias de la forma corta.** — módulo
+  `test/cli.test.js`, «install is an alias of the short form»
+- **El destino por defecto es el directorio de trabajo.** — módulo
+  `test/cli.test.js`, «user/repo without OUT installs into the working
+  directory»
+- **`--path` instala un paquete local sin peticiones HTTP.** — módulo
+  `test/cli.test.js`, «--path installs the local package without any
+  HTTP request»
+- **La referencia se elige con `@ref` o `--ref`;** declarar ambas es un
+  error de invocación. — módulos `test/cli.test.js` («the ref reaches
+  the download URL via @ref or --ref», «declaring @ref and --ref at
+  once is a usage error») y `test/fetch.test.js` («fetchRepoTree asks
+  for the ref in the URL when given»)
+- **Un repositorio inaccesible o una referencia inexistente abortan
+  con código 5 sin escribir nada.** — módulo `test/cli.test.js` («a
+  missing repository exits 5 and writes nothing», «a network failure
+  exits 5 and writes nothing»)
+- **El temporal de extracción se elimina siempre:** tras éxito, error
+  y `--dry-run`. — módulos `test/cli.test.js` («a repo without
+  teleprompter.json exits 1 and cleans the temp dir», «--dry-run with
+  a remote origin writes nothing and cleans the temp dir») y
+  `test/fetch.test.js`
+- **Un archivo hostil no escribe fuera del temporal** — las rutas con
+  `..` no se extraen. — módulo `test/fetch.test.js`, «fetchRepoTree
+  does not let a hostile entry escape the temp dir»
 - **Un paquete se instala de principio a fin con el binario real.** —
   módulo `test/e2e.test.js`, «the reference package installs end to end
   through the real binary»
@@ -64,6 +94,22 @@ mecánica detallada, en la [referencia](referencia-install.md).
 - **Un error a mitad de ejecución sale con código 3 e informa de lo ya
   aplicado.** — módulo `test/execute.test.js`, «a mid-execution error
   exits 3 and reports what was applied»
-- **Si el paquete declara personalización, la salida informa de dónde
-  están las instrucciones.** — módulo `test/execute.test.js`, «install
-  reports the personalization instructions location»
+- **Si el paquete declara personalización, la guía se copia a
+  `.teleprompter/<paquete>/` y su contenido se entrega tal cual al
+  final del resultado.** — módulos `test/execute.test.js` («install
+  materializes the personalization guide in the managed namespace»)
+  y `test/cli.test.js` («install delivers the declared guide verbatim
+  after the result»)
+- **`--dry-run` no entrega la guía:** solo muestra el plan. — módulo
+  `test/cli.test.js`, «--dry-run shows the plan but never delivers
+  the guide»
+- **`teleprompter guide [<paquete>]` relee la guía instalada** desde
+  el directorio de trabajo, sin reinstalar ni redescargar. — módulo
+  `test/cli.test.js` («guide prints the installed guide from the
+  working directory», «guide \<paquete\> shows only that package's
+  guide», «guide without a package shows every installed guide»)
+- **La consulta distingue sus fallos:** sin guía que mostrar sale con
+  código 4; el archivo registrado ausente, con código 3. — módulo
+  `test/cli.test.js` («guide exits 4 without a lock, on unknown
+  packages, or without a guide», «guide exits 3 when the recorded
+  guide file is gone»)

package/manual/002-listar-paquetes-instalados.md

@@ -0,0 +1,44 @@
+# Listar los paquetes instalados
+
+El usuario ejecuta `teleprompter list` desde la raíz del
+repositorio destino para ver qué paquetes instaló Teleprompter —
+nombre, versión, fecha y recursos escritos— sin abrir
+`teleprompter-lock.json`. Qué contiene el registro está definido en
+el [dominio de instalación](https://github.com/nucleoabierto/teleprompter/blob/master/docs/domains/002-instalacion.md); la
+referencia completa del comando, en la
+[referencia de `list`](referencia-list.md).
+
+## Escenarios
+
+- **`list` muestra una entrada por paquete instalado** con su
+  `nombre@version`, el instante de la instalación y una línea por
+  recurso escrito. — módulo `test/cli.test.js` («list shows name,
+  version, date and written resources of a package», «list shows
+  one entry per installed package»)
+- **La salida es lenguaje de producto:** los recursos se listan por
+  su ruta, sin hashes ni acciones internas del registro. — módulo
+  `test/cli.test.js`, «list shows recorded targets without hashes
+  or internal actions»
+- **Los recursos omitidos por colisión no se listan:** el registro
+  anota la decisión, pero la herramienta no escribió nada ahí. —
+  módulo `test/cli.test.js`, «list does not list resources recorded
+  as skipped»
+- **Una entrada sin fecha registrada se lista sin ella.** — módulo
+  `test/cli.test.js`, «list shows an entry without installedAt
+  without a date»
+- **Un paquete con guía de personalización señala cómo consultarla**
+  con `guide`. — módulo `test/cli.test.js`, «list points to guide
+  for a package with personalization»
+- **Sin instalaciones registradas responde «no hay paquetes
+  instalados»** con código 0 —es una respuesta, no un fallo—; un
+  registro corrupto añade un aviso y responde lo mismo. — módulo
+  `test/cli.test.js` («list answers that nothing is installed when
+  there is no lock», «list warns on a corrupt lock and answers
+  nothing installed»)
+- **El listado no depende del origen de la instalación:** tras
+  instalar remoto o con `--path`, lee solo el registro del
+  directorio de trabajo. — módulo `test/cli.test.js`, «list reads
+  the working directory lock whatever the install origin»
+- **`list` no admite argumentos ni opciones:** cualquiera es un
+  error de invocación con código 4. — módulo `test/cli.test.js`,
+  «list rejects arguments and install options»

package/manual/003-verificar-recursos-instalados.md

@@ -0,0 +1,56 @@
+# Verificar el estado de los recursos instalados
+
+El usuario ejecuta `teleprompter check` desde la raíz del
+repositorio destino para saber en qué estado quedó cada recurso que
+Teleprompter escribió —intacto, modificado, ausente o no
+verificable— confrontando el registro con el disco, sin abrir
+`teleprompter-lock.json`. Qué contiene el registro está definido en
+el [dominio de instalación](https://github.com/nucleoabierto/teleprompter/blob/master/docs/domains/002-instalacion.md); la
+referencia completa del comando, en la
+[referencia de `check`](referencia-check.md).
+
+## Escenarios
+
+- **`check` muestra una entrada por paquete instalado** con su
+  `nombre@version` y una línea por recurso registrado con su marca
+  de estado. — módulo `test/cli.test.js` («check reports an
+  installed resource as intact», «check reports each state across
+  packages and resources»)
+- **Un recurso editado tras la instalación se marca `modificado`**
+  y uno borrado, `ausente`. — módulo `test/cli.test.js` («check
+  reports an edited resource as modified», «check reports a deleted
+  resource as missing»)
+- **La guía de personalización gestionada se verifica como un
+  recurso más,** porque está registrada en `files`. — módulo
+  `test/cli.test.js`, «check verifies the managed guide as a
+  recorded resource»
+- **Los recursos omitidos por colisión no se verifican:** el
+  registro anota la decisión, pero la herramienta no escribió nada
+  ahí. — módulo `test/cli.test.js`, «check does not report resources
+  recorded as skipped»
+- **Una entrada registrada sin hash se marca `no verificable`,** lo
+  mismo que un recurso presente que no se puede leer. — módulo
+  `test/cli.test.js` («check reports a recorded entry without
+  sha256 as unverifiable», «check reports an unreadable resource as
+  unverifiable»)
+- **Una ruta registrada que escapa del destino no se lee** —el
+  registro es dato versionado, no memoria confiable— y se marca
+  `no verificable`. — módulo `test/cli.test.js`, «check marks
+  recorded paths that escape the destination as unverifiable»
+- **La salida es lenguaje de producto:** marcas y rutas, sin hashes
+  ni acciones internas del registro. — módulo `test/cli.test.js`,
+  «check reports drift in product language, without hashes or
+  actions»
+- **Un registro escrito a mano se clasifica igual** que uno
+  producido por una instalación real. — módulo `test/cli.test.js`,
+  «check reports a hand-written lock entry whose hash differs as
+  modified»
+- **Sin instalaciones registradas responde «no hay paquetes
+  instalados»** con código 0 —es una respuesta, no un fallo—; un
+  registro corrupto añade un aviso y responde lo mismo. — módulo
+  `test/cli.test.js` («check answers that nothing is installed when
+  there is no lock», «check warns on a corrupt lock and answers
+  nothing installed»)
+- **`check` no admite argumentos ni opciones:** cualquiera es un
+  error de invocación con código 4. — módulo `test/cli.test.js`,
+  «check rejects arguments and install options»

package/manual/004-actualizar-un-paquete.md

@@ -0,0 +1,34 @@
+# Actualizar un paquete
+
+`teleprompter update <paquete>` lleva un paquete instalado a la
+versión que publica su origen —la registrada en `teleprompter-lock.json`,
+o una indicada en la invocación—. Se ejecuta desde la raíz del
+repositorio destino.
+
+## Escenarios que la suite verifica
+
+- Un paquete instalado desde un `--path` se actualiza desde ese
+  origen sin indicarlo: lo que la versión cambió y sigue intacto se
+  sobrescribe, lo nuevo se crea, lo retirado e intacto se elimina, y
+  el registro queda a la versión nueva.
+- Si la versión entrante coincide con la registrada, responde que el
+  paquete ya está en esa versión y no escribe nada.
+- Pedir un paquete no instalado, o uno sin origen registrado y sin
+  origen explícito, es un error de invocación.
+- `--path` o un `user/repo[@ref]` explícito sobrescriben el origen
+  registrado y quedan como el nuevo origen; `--ref` cambia solo el
+  ref de un origen de repositorio —con `--path` es un error—.
+- Una edición local sobre un recurso que la versión también cambió
+  se decide caso a caso: la consola interactiva pregunta, `--force`
+  sobrescribe, `--skip` conserva, y sin consola la operación aborta
+  sin escribir.
+- Un recurso retirado por la versión pero modificado localmente se
+  decide igual: quitar o conservar —conservarlo mantiene su registro
+  previo—.
+- `--dry-run` muestra el plan de actualización completo sin escribir
+  nada.
+- Si el origen publica un paquete con otro nombre, la invocación es
+  un error —no se actualiza nada—.
+
+Véase la [referencia de `update`](referencia-update.md) para la
+gramática completa y los códigos de salida.

package/manual/README.md

@@ -13,11 +13,26 @@ instalación, empezar por la guía de uso.
 - [Referencia de `install`](referencia-install.md) — la operación
   completa: fases, marcas del plan, resolución de colisiones, registro
   y códigos de salida.
+- [Referencia de `guide`](referencia-guide.md) — consultar las
+  instrucciones de personalización de los paquetes instalados.
+- [Referencia de `list`](referencia-list.md) — listar los paquetes
+  instalados con su versión, fecha y recursos.
+- [Referencia de `check`](referencia-check.md) — verificar el estado
+  de los recursos instalados: intactos, modificados, ausentes o no
+  verificables.
+- [Referencia de `update`](referencia-update.md) — actualizar un
+  paquete instalado a la versión que publica su origen.
 
 ## Funcionalidades
 
 - [001 — Instalar un paquete](001-instalar-un-paquete.md) — qué hace
   `install` y los escenarios que la suite de pruebas verifica.
+- [002 — Listar los paquetes instalados](002-listar-paquetes-instalados.md)
+  — qué muestra `list` y los escenarios que la suite verifica.
+- [003 — Verificar el estado de los recursos instalados](003-verificar-recursos-instalados.md)
+  — qué informa `check` y los escenarios que la suite verifica.
+- [004 — Actualizar un paquete](004-actualizar-un-paquete.md) — qué
+  hace `update` y los escenarios que la suite verifica.
 
 ## Documentos relacionados