@nucleoabierto/teleprompter 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gildardo Adrian Maravilla Jacome
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,88 @@
+# Teleprompter
+
+Instalador de paquetes de configuración para repositorios.
+
+Teleprompter lleva un paquete —un directorio con un manifiesto
+`teleprompter.json` y recursos como skills o archivos de configuración—
+a un repositorio con trabajo previo. Calcula el plan completo antes de
+escribir nada, resuelve las colisiones con lo que ya existe y deja un
+registro auditable de la instalación en `teleprompter-lock.json`.
+
+## Requisitos
+
+- Node.js 22 o superior.
+
+## Instalación
+
+No hace falta instalar nada: el CLI se ejecuta directamente con `npx`:
+
+```sh
+npx @nucleoabierto/teleprompter install <paquete> <destino>
+```
+
+También puede instalarse como herramienta global:
+
+```sh
+npm install -g @nucleoabierto/teleprompter
+teleprompter install <paquete> <destino>
+```
+
+## Uso
+
+`install` recibe el directorio del paquete y la raíz del repositorio
+destino. 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
+verificado: mi-paquete@1.0.0
+plan de instalación:
+  mkdir          .agents/skills/
+  create         .agents/skills/mi-skill/SKILL.md
+  identical      .agents/skills/otro-skill/SKILL.md
+  conflict       .agents/config.json
+```
+
+El plan muestra `mkdir` para las rutas de precondición a crear y una
+marca por recurso: `create`, `identical`, `conflict` o `managed-update`
+(el destino contiene lo que una instalación anterior registró y el
+paquete ofrece una versión igual o posterior). Cuando hay
+colisiones —el destino existe con contenido distinto y no consta como
+instalado por Teleprompter, o fue modificado desde la instalación— una
+consola interactiva pregunta por cada
+recurso; sin ella, la operación aborta sin escribir nada. Dos opciones
+mutuamente excluyentes resuelven las colisiones por adelantado:
+
+| Opción    | Efecto                                               |
+|-----------|------------------------------------------------------|
+| `--force` | El recurso del paquete sobrescribe cada colisión     |
+| `--skip`  | Cada colisión se omite y la omisión queda registrada |
+
+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.
+
+### Códigos de salida
+
+| Código | Significado                                          |
+|--------|------------------------------------------------------|
+| `0`    | Éxito                                                |
+| `1`    | Manifiesto inválido                                  |
+| `2`    | Plan no ejecutable (precondiciones o colisiones)     |
+| `3`    | Error de ejecución                                   |
+| `4`    | Error de invocación (argumentos o rutas)             |
+
+## Documentación
+
+- [manual/](manual/README.md) — guía de uso y referencia completa de la
+  operación `install`.
+- [docs/especificacion-paquete.md](docs/especificacion-paquete.md) —
+  cómo escribir el manifiesto `teleprompter.json` de un paquete propio.
+
+## Licencia
+
+[MIT](LICENSE).

package/bin/teleprompter.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+import { createAsker } from '../src/prompt.js';
+
+try {
+  process.exitCode = await main(process.argv.slice(2), {
+    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    createAsker,
+  });
+} catch (error) {
+  console.error(`error inesperado: ${error.message}`);
+  process.exitCode = 3;
+}

package/docs/domains/001-paquete.md

@@ -0,0 +1,73 @@
+# Paquete
+
+## Propósito
+
+El formato declarativo en que se describe una pieza transferible de
+configuración —qué contiene, dónde va cada recurso y qué exige el
+destino— para que una instalación sea inspectable y repetible.
+
+## Referencia del modelo
+
+- **Lenguaje ubicuo:**
+  - **Paquete:** un directorio con un manifiesto `teleprompter.json`
+    cuyo `name` coincide con el nombre del directorio.
+    - Ancla: `checkName` en `src/manifest.js`; `packages/ciclo-tareas/`
+    - Origen: épica `docs/epics/001-formato-paquete.md`
+  - **Manifiesto:** el JSON `teleprompter.json` con `name`, `version`,
+    `install` obligatorios y `format`, `description`, `license`,
+    `author`, `requires`, `personalization`, `metadata`, `collection`
+    opcionales.
+    - Ancla: `TOP_LEVEL_FIELDS` y `VALIDATORS` en `src/manifest.js`;
+      contrato en `docs/especificacion-paquete.md`
+  - **Colección:** un manifiesto con `collection: true` describe un
+    conjunto de paquetes y no es instalable.
+    - Ancla: `checkCollection` en `src/manifest.js`
+  - **Entrada install:** par `source` (ruta dentro del paquete que debe
+    existir) → `target` (ruta relativa dentro del destino).
+    - Ancla: `checkInstallEntry` en `src/manifest.js`
+  - **Precondición:** entrada `requires.paths` con `path` obligatorio y
+    `create` booleano opcional; `create: true` difiere la creación de
+    la ruta al plan en lugar de abortar.
+    - Ancla: `checkRequiresEntry` en `src/manifest.js` y
+      `checkRequires` en `src/requires.js`
+  - **Ruta segura:** ruta relativa sin segmentos `..`, ni absoluta
+    POSIX, ni absoluta Windows (`C:\`) ni UNC (`\\`).
+    - Ancla: `isSafeRelative` en `src/paths.js`
+- **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`
+    sin prefijos ni rangos.
+    - Ancla: `SEMVER_RE` en `src/manifest.js`
+- **Invariantes:**
+  - Toda ruta del manifiesto es una ruta segura —nada puede escribirse
+    fuera de la raíz de destino ni leerse fuera del paquete.
+    - Ancla: `checkRelativePath` en `src/manifest.js`
+  - `name` es kebab-case, ≤64 caracteres, e igual al directorio que lo
+    contiene. Ancla: `NAME_RE` en `src/manifest.js`
+  - `install` es una lista no vacía de entradas bien formadas cuyo
+    `source` existe. Ancla: `checkInstall` en `src/manifest.js`
+  - `format`, si está presente, vale `teleprompter-package@1`.
+    Ancla: `KNOWN_FORMAT` en `src/manifest.js`
+- **Operaciones:**
+  - Cargar y validar el manifiesto de un directorio de paquete:
+    `loadManifest` en `src/manifest.js` —devuelve errores, avisos y el
+    manifiesto; nunca lanza.
+
+## Explicación del dominio
+
+- **Fronteras:**
+  - Dentro: la forma del manifiesto, la seguridad de rutas y las
+    precondiciones declaradas.
+  - Fuera: qué se hace con un paquete válido (dominio de instalación)
+    y el contenido de las instrucciones de personalización, que el
+    formato solo referencia.
+  - Relaciones: la instalación consume el resultado de la validación
+    del paquete sin revalidarlo.
+- **Decisiones relevantes:**
+  - `docs/decisions/D001–D004` — manifiesto JSON puro, cardinalidad,
+    semver explícita, mapa `install`.
+
+## Estado de salud
+
+- Última revisión: 2026-09-28
+- Divergencias conocidas: Ninguna

package/docs/domains/002-instalacion.md

@@ -0,0 +1,118 @@
+# Instalación
+
+## Propósito
+
+Llevar un paquete válido a un repositorio con trabajo previo sin
+pisarlo: verificar, presentar un plan completo antes de escribir,
+resolver colisiones con una política declarada y dejar registro de lo
+instalado.
+
+## Referencia del modelo
+
+- **Lenguaje ubicuo:**
+  - **Plan:** la lista completa de acciones calculada antes de tocar
+    el destino; incluye los `mkdir` de las precondiciones con
+    `create: true` y una entrada por recurso con su marca.
+    - Ancla: `buildPlan` en `src/plan.js`; contrato en
+      `docs/instalador.md` sección «El plan»
+    - Origen: tarea `docs/tasks/009-plan-de-instalacion.md`
+  - **Marca del plan:** estado de cada recurso —`create` (destino
+    libre), `identical` (contenido igual), `managed-update` (propio y
+    sin tocar, versión igual o posterior) o `conflict` (contenido
+    distinto ajeno o propio modificado).
+    - 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`
+  - **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
+  - **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`
+- **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`
+  - 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
+    independiente del orden de lectura.
+    - Ancla: `hashPath` en `src/hash.js`
+- **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`
+  - «Existe» significa «hay una entrada en el directorio», sin seguir
+    enlaces: un enlace colgado ocupa su ruta.
+    Ancla: `hasEntry` en `src/paths.js`
+  - `--force` y `--skip` son mutuamente excluyentes; el error es de
+    invocación (código 4). Ancla: `parseArgs` en `src/cli.js`
+  - `managed-update` exige hash registrado coincidente **y** versión
+    del paquete ≥ versión registrada; un downgrade es `conflict`.
+    Ancla: `semverAtLeast` en `src/plan.js`
+  - Una respuesta interactiva que no es afirmativa significa `skip`:
+    el defecto ante trabajo ajeno es no sobrescribir.
+    Ancla: `createAsker` en `src/prompt.js`
+  - Un lock ilegible o con estructura inesperada degrada a «sin
+    historia» con aviso, nunca a crash.
+    Ancla: `readLock`/`isValidLock` en `src/lock.js`
+  - Ninguna escritura puede salir de la raíz por un enlace en la
+    cadena de padres: el ancestro existente más profundo debe
+    resolver a un directorio dentro del destino, en el plan y en la
+    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`
+  - 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`
+- **Operaciones:**
+  - `teleprompter install <paquete> <destino> [--force|--skip]
+    [--dry-run]` — verifica, planea, resuelve, ejecuta y registra.
+    - 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`
+  - Registrar la instalación: fusiona el lock preservando otros
+    paquetes; `identical` no se registra y `skip` va sin hash.
+    - Ancla: `writeLock` en `src/lock.js`
+  - Códigos de salida: 0 éxito, 1 manifiesto inválido, 2 plan no
+    ejecutable, 3 error de ejecución, 4 invocación.
+    - Ancla: `EXIT_*` en `src/cli.js`; contrato en
+      `docs/instalador.md` «Resultado y errores»
+
+## Explicación del dominio
+
+- **Fronteras:**
+  - Dentro: verificación, plan, resolución de colisiones, ejecución y
+    registro de una instalación.
+  - Fuera: la forma del manifiesto (dominio del paquete), el contenido
+    de la personalización y la distribución del CLI.
+  - Relaciones: consume el dominio del paquete a través del resultado
+    estructurado de `verifyPackage`; la invocación (`bin/`) es una
+    capa delgada sin dominio.
+- **Decisiones relevantes:**
+  - `docs/decisions/D005` — plan completo antes de escribir, aborto
+    total.
+  - `docs/decisions/D006` — política de colisiones: interactiva,
+    aborto sin consola, `--force`/`--skip` excluyentes.
+  - `docs/decisions/D007` — `teleprompter-lock.json` como memoria de
+    propiedad.
+  - `docs/decisions/D008` — implementación JavaScript vía `npx` como
+    `@nucleoabierto/teleprompter`.
+
+## Estado de salud
+
+- Última revisión: 2026-09-28
+- 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
+  el paquete viejo, que es conservador pero puede sorprender.

package/docs/domains/README.md

@@ -0,0 +1,9 @@
+# Dominios
+
+Documentación viva del modelo del producto: un documento por dominio,
+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.

package/docs/especificacion-paquete.md

@@ -0,0 +1,169 @@
+# Especificación del formato de paquete
+
+Un **paquete** es un directorio de configuración trasladable entre
+repositorios: un agente o instalador lo inspecciona, verifica sus
+precondiciones y copia sus recursos a las rutas que el manifiesto
+declara. Este documento es el contrato completo: quien lo sigue puede
+producir un paquete válido sin conocer nada más del sistema.
+
+## Un paquete
+
+Un paquete es un directorio que contiene un manifiesto
+`teleprompter.json` en su raíz y cualquier disposición de recursos:
+
+```text
+mi-paquete/
+├── teleprompter.json    # manifiesto (obligatorio)
+└── <recursos>           # archivos y subdirectorios libres
+```
+
+No hay disposición fija para los recursos: el manifiesto declara, para
+cada origen, dónde se instala en el repositorio destino.
+
+## El manifiesto `teleprompter.json`
+
+El manifiesto es JSON puro: no ejecuta nada. Según el valor del campo
+`collection`, el archivo describe un paquete (ausente o `false`) o una
+colección (`true`, véase «Colecciones»). Primero el contrato de paquete.
+
+### Campos obligatorios
+
+| Campo | Tipo | Regla |
+|---|---|---|
+| `name` | string | Identificador del paquete: minúsculas, números y guiones, máx. 64 caracteres, sin guiones al inicio ni al final. Debe coincidir con el nombre del directorio del paquete. |
+| `version` | string | Versión semver explícita `x.y.z`. La autoridad de la versión es el manifiesto, no el VCS. |
+| `install` | array | Lista no vacía de entradas `{ "source", "target" }`. Véase abajo. Un paquete sin `install` o con la lista vacía es inválido. |
+
+Cada entrada de `install` declara una copia:
+
+- `source` — ruta dentro del paquete, relativa a su raíz. Puede ser un
+  archivo o un directorio; un directorio se instala con todo su
+  contenido.
+- `target` — ruta relativa a la raíz del repositorio destino donde se
+  instala.
+
+La barra final en `source` y `target` es una convención legible para
+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.
+
+### Campos opcionales
+
+| Campo | Tipo | Descripción |
+|---|---|---|
+| `format` | string | Versión del formato del manifiesto: `"teleprompter-package@1"`. Su ausencia equivale a la primera versión del formato. |
+| `description` | string | Descripción corta del paquete. |
+| `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`. |
+| `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 `..`):
+
+- Si la ruta no existe y `create` es `false` o está ausente, la
+  instalación aborta.
+- Si la ruta no existe y `create` es `true`, el instalador la crea
+  antes de instalar.
+
+### Campos desconocidos
+
+Política mixta:
+
+- **Nivel superior** del manifiesto (de paquete o de colección): el
+  campo desconocido se ignora y el validador emite un aviso.
+- **Dentro de un objeto conocido** (`author`, `requires`, una entrada
+  de `requires.paths`, una entrada de `install`, una entrada de
+  `packages` en una colección): el campo desconocido es un error y el
+  manifiesto no es válido.
+
+## Colecciones
+
+Un repositorio puede alojar un paquete o varios. Solo hay un nombre de
+archivo que buscar —`teleprompter.json`— y un campo que discrimina qué
+describe:
+
+- `collection` ausente o `false` → el manifiesto describe un paquete.
+- `collection: true` → el manifiesto describe una **colección**: un
+  índice de paquetes por ruta.
+
+Un directorio es una cosa o la otra: la colección es un contenedor
+puro, no instalable como paquete. Un manifiesto de colección admite los
+campos `name`, `description`, `license`, `author`, `metadata` y
+`format` —con la misma semántica que en un paquete, con una excepción:
+el `name` de una colección es cosmético y no debe coincidir con el
+nombre de ningún directorio— más:
+
+| Campo | Tipo | Regla |
+|---|---|---|
+| `collection` | boolean | Obligatorio y `true`. Es el discriminador. |
+| `packages` | array | Obligatorio. Lista de entradas `{ "path": "..." }` con la ruta relativa al directorio de cada paquete; `path` no admite rutas absolutas ni `..`. |
+
+La entrada solo declara la ruta: el `name` y la `version` de cada
+paquete se leen de su propio `teleprompter.json`, nunca del índice.
+Los campos propios de paquete (`version`, `install`, `requires`,
+`personalization`) en un manifiesto de colección son un error.
+
+## Ejemplo completo
+
+Estructura de un paquete con tres recursos:
+
+```text
+ciclo-tareas/
+├── teleprompter.json
+└── skills/
+    ├── crear-tareas/
+    ├── ejecutar-tareas/
+    └── commit/
+```
+
+Su manifiesto:
+
+```json
+{
+  "format": "teleprompter-package@1",
+  "name": "ciclo-tareas",
+  "version": "1.0.0",
+  "description": "Ciclo de tareas del proyecto: creación, ejecución con revisión dual y commit",
+  "license": "MIT",
+  "install": [
+    {
+      "source": "skills/crear-tareas/",
+      "target": ".agents/skills/crear-tareas/"
+    },
+    {
+      "source": "skills/ejecutar-tareas/",
+      "target": ".agents/skills/ejecutar-tareas/"
+    },
+    {
+      "source": "skills/commit/",
+      "target": ".agents/skills/commit/"
+    }
+  ],
+  "requires": {
+    "paths": [{ "path": ".agents/skills/", "create": true }]
+  },
+  "metadata": { "origin": "teleprompter" }
+}
+```
+
+## Lista de verificación de un paquete válido
+
+1. `teleprompter.json` en la raíz del directorio del paquete, JSON
+   válido.
+2. `name` en kebab-case, igual al nombre del directorio.
+3. `version` semver `x.y.z`.
+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 `..`.
+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).
+7. En una colección: `collection: true`, `packages` con rutas válidas
+   y ningún campo propio de paquete.

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

@@ -0,0 +1,69 @@
+# Instalar un paquete
+
+El usuario ejecuta `teleprompter install <paquete> <destino>` 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
+[dominio de paquete](https://github.com/nucleoabierto/teleprompter/blob/master/docs/domains/001-paquete.md) y
+[dominio de instalación](https://github.com/nucleoabierto/teleprompter/blob/master/docs/domains/002-instalacion.md); la
+mecánica detallada, en la [referencia](referencia-install.md).
+
+## Escenarios
+
+- **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»
+- **El plan se presenta antes de escribir, con una marca por recurso.**
+  En un destino vacío todo es `create`. — módulo `test/plan.test.js`,
+  «plan marks every resource create on an empty destination»
+- **Reinstalar es inocuo:** lo que ya coincide se marca `identical` y
+  no se escribe. — módulos `test/plan.test.js` («plan marks identical
+  when the destination already holds the same content») y
+  `test/execute.test.js` («reinstalling the same package reports
+  identical and keeps the recorded entry»)
+- **Lo instalado por Teleprompter se actualiza sin preguntar** cuando
+  el paquete trae una versión igual o posterior y el destino sigue
+  siendo lo que el registro anotó. — módulo `test/plan.test.js`, «plan
+  marks managed-update when the destination still holds what the lock
+  recorded»
+- **Lo modificado a mano es una colisión,** aunque el registro lo
+  reconozca como instalado. — módulo `test/plan.test.js`, «plan marks
+  conflict when a recorded resource was modified locally»
+- **Las colisiones se resuelven una a una en consola interactiva.** —
+  módulo `test/plan.test.js`, «an interactive console resolves each
+  conflict per answer»
+- **Sin forma de preguntar ni opciones de resolución, las colisiones
+  abortan la operación sin escribir.** — módulo `test/plan.test.js`,
+  «an interactive console without an asker reports conflicts and
+  aborts»
+- **`--force` y `--skip` resuelven todas las colisiones por adelantado**
+  y son mutuamente excluyentes. — módulos `test/plan.test.js`
+  («--force resolves every conflict as overwrite», «--skip resolves
+  every conflict as skip») y `test/cli.test.js` («main exits with usage
+  error on unknown or mutually exclusive flags»)
+- **`--dry-run` muestra el plan y termina sin escribir ni registrar.**
+  — módulo `test/plan.test.js`, «--dry-run prints the plan and exits
+  without writing»
+- **Un manifiesto inválido aborta con código 1 sin tocar el destino.**
+  — módulo `test/cli.test.js`, «main exits 1 on an invalid manifest
+  without writing to the destination»
+- **Una precondición incumplida aborta con código 2 sin escribir;** con
+  `create: true` la ruta se crea como parte del plan. — módulo
+  `test/cli.test.js` («main exits 2 on an unmet precondition without
+  writing», «main passes when a missing precondition path allows
+  creation»)
+- **Un error de invocación —argumentos ausentes, de más o rutas que no
+  son directorios— sale con código 4.** — módulo `test/cli.test.js`,
+  «main exits with usage error on missing, wrong, or excess arguments»
+- **Cada instalación escribe `teleprompter-lock.json`** con los
+  recursos instalados, sus acciones y sus hashes, y conserva lo
+  registrado por otros paquetes. — módulo `test/execute.test.js`
+  («install copies every resource and writes the lock on an empty
+  destination», «writeLock preserves records belonging to other
+  packages»)
+- **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»

package/manual/README.md

@@ -0,0 +1,27 @@
+# Manual de Teleprompter
+
+Documentación de usuario del instalador Teleprompter. Para una primera
+instalación, empezar por la guía de uso.
+
+## Guías
+
+- [Guía de uso](guia-de-uso.md) — instalar un paquete paso a paso, con
+  el paquete de referencia del repositorio como ejemplo.
+
+## Referencia
+
+- [Referencia de `install`](referencia-install.md) — la operación
+  completa: fases, marcas del plan, resolución de colisiones, registro
+  y códigos de salida.
+
+## Funcionalidades
+
+- [001 — Instalar un paquete](001-instalar-un-paquete.md) — qué hace
+  `install` y los escenarios que la suite de pruebas verifica.
+
+## Documentos relacionados
+
+- [docs/domains/](../docs/domains/README.md) — el modelo del producto:
+  qué es un paquete y qué es una instalación.
+- [docs/especificacion-paquete.md](../docs/especificacion-paquete.md) —
+  cómo escribir el manifiesto `teleprompter.json` de un paquete propio.