create-quiver 0.17.1 → 0.17.3

package/copys-landing-page.md

@@ -0,0 +1,244 @@
+# Copys para Landing Page de Quiver
+
+> Basados exclusivamente en funcionalidades y propuesta de valor documentadas en el proyecto.  
+> Los campos marcados con `[Completar con información real del producto]` requieren datos del equipo.
+
+---
+
+## 1. Hero Section
+
+### Título principal
+
+**"Que la IA trabaje rápido. Pero con orden."**
+
+---
+
+### Subtítulo
+
+Los agentes de IA aceleran el desarrollo, pero sin estructura generan caos. Quiver convierte el trabajo asistido por IA en un flujo guiado: requerimientos, criterios, plan técnico, specs, slices, commits y pull requests — todo visible, todo verificable.
+
+---
+
+### CTA principal
+
+**Empezar ahora** → `npx create-quiver@latest init --name "Mi Proyecto"`
+
+---
+
+### CTA secundario
+
+**Ver la guía completa** → [docs/workflows/full-ai-spec-to-pr.md]
+
+---
+
+## 2. Propuesta de Valor
+
+### Bloque 1 — Del caos al flujo repetible
+
+**"Un proceso que se puede repetir, auditar y mejorar."**
+
+En lugar de pedirle a un agente "hacé esto y vemos qué pasa", Quiver define un camino repetible: entender el repositorio, preparar contexto, planificar con aprobaciones humanas, generar specs, ejecutar slice por slice, validar con evidencia y abrir el PR.
+
+---
+
+### Bloque 2 — El humano siempre aprueba lo importante
+
+**"IA rápida, decisiones humanas."**
+
+Quiver separa los pasos que necesitan aprobación humana (criterios de aceptación, plan técnico) de los que puede automatizar la IA (ejecución de slices, commits, validación). El humano mantiene el control sin perder velocidad.
+
+---
+
+### Bloque 3 — Contexto mínimo, resultados máximos
+
+**"El agente ejecutor solo lee lo que necesita."**
+
+Quiver entrega a cada agente un contexto acotado: el slice exacto, sus dependencias y su alcance aprobado. Sin ruido. Sin contexto incorrecto. Sin implementaciones que se desvían del plan.
+
+---
+
+### Bloque 4 — Documentación generada, no escrita
+
+**"El proyecto se documenta solo mientras se trabaja."**
+
+Quiver crea y mantiene `AI_CONTEXT.md`, `PROJECT_MAP.md`, `AGENTS.md`, briefs de ejecución y reportes de evidencia como parte del flujo normal de trabajo. No como tarea adicional.
+
+---
+
+### Bloque 5 — Compatible con tu stack y tu equipo
+
+**"Funciona donde ya trabajás."**
+
+Quiver se ejecuta con `npx` sin instalación. Soporta macOS, Linux y Windows. Compatible con npm, yarn, pnpm y bun. Funciona con Codex, Claude, Gemini y cualquier CLI de proveedor que soporte.
+
+---
+
+## 3. Beneficios Principales
+
+- **Trazabilidad completa:** cada cambio tiene una spec aprobada, un slice definido y evidencia de validación asociada.
+- **Sin sorpresas en el PR:** el alcance del pull request está definido antes de que el agente escriba una sola línea.
+- **Onboarding instantáneo para agentes:** `AGENTS.md` y `AI_ONBOARDING_PROMPT.md` generados automáticamente le dan a cualquier agente el contexto necesario en segundos.
+- **Independiente de cualquier proveedor de IA:** Quiver orquesta el flujo; los proveedores (Codex, Claude, Gemini) hacen el trabajo de generación.
+- **Flujo verificable en cualquier momento:** `quiver flow`, `quiver dashboard` y `quiver doctor` muestran el estado real del proyecto en cualquier momento.
+- **Sin API keys en el repositorio:** las credenciales viven en los CLIs de proveedor y en el sistema operativo, nunca en los archivos de Quiver.
+- **Soporte en inglés y español:** output del CLI, documentación generada y mensajes de error disponibles en ambos idiomas.
+- **Funciona con proyectos nuevos y existentes:** `init` para proyectos nuevos, `migrate` para los que ya tienen código.
+
+---
+
+## 4. Sección de Problema
+
+### "¿Por qué los agentes de IA fallan en proyectos reales?"
+
+Los agentes de IA pueden escribir código rápido. Pero suelen fallar por motivos sorprendentemente mundanos:
+
+- **Leen demasiado contexto o el contexto incorrecto.** El agente procesa miles de líneas que no tienen que ver con la tarea.
+- **Implementan antes de cerrar criterios de aceptación.** El equipo no sabe qué construyó el agente hasta que ya está hecho.
+- **Saltean la aprobación del plan.** No hay una fase donde el humano valide qué se va a cambiar antes de que se cambie.
+- **Mezclan cambios no relacionados en el mismo PR.** Un pull request que toca diez cosas distintas es imposible de revisar.
+- **Olvidan qué se decidió en fases anteriores.** Sin estado persistente, cada sesión empieza de cero.
+- **Generan código sin evidencia de validación.** Nadie puede auditar si los tests pasaron, cuánto tardaron o qué salida produjeron.
+- **Dejan al equipo reconstruyendo qué pasó.** El historial de chat se pierde. El contexto desaparece.
+
+El resultado: trabajo más rápido en el corto plazo, caos técnico que crece con cada iteración.
+
+---
+
+## 5. Sección de Solución
+
+### "Quiver convierte el trabajo asistido por IA en un flujo con estructura."
+
+Quiver no reemplaza al agente. Lo ordena.
+
+Combina dos metodologías complementarias:
+- **WDD (Workflow-Driven Development):** primero se define cómo se trabaja, después se trabaja.
+- **SDD (Spec-Driven Development):** el trabajo se describe como specs y slices antes de implementarse.
+
+En la práctica, Quiver separa dos roles de agentes:
+
+- Un **agente planificador** prepara criterios de aceptación, plan técnico, specs, slices, briefs y el cuerpo del PR. El humano aprueba en cada fase importante.
+- Un **agente ejecutor** recibe solo el contexto mínimo de un slice y modifica código dentro del alcance exacto que fue aprobado.
+
+El resultado es un flujo visible de principio a fin: requerimiento → criterios aprobados → plan aprobado → spec generada → slices ejecutados → evidencia validada → PR abierto → spec cerrada.
+
+Cada paso es verificable. Cada decisión es auditable. El equipo mantiene el control.
+
+---
+
+## 6. Features Destacadas
+
+### `quiver flow` — Tu brújula de workflow
+
+Ejecutá `quiver flow` en cualquier momento para saber exactamente en qué etapa está el proyecto y cuál es el próximo comando seguro. Funciona como un GPS para el flujo de trabajo: siempre te dice dónde estás y hacia dónde ir.
+
+---
+
+### `quiver ai plan` — El planner genera el plan, el humano lo aprueba
+
+En lugar de pedirle al agente que "haga algo", Quiver hace que el agente proponga criterios de aceptación y un plan técnico estructurado. Guardás los borradores, los revisás, y aprobás la versión que querés usar como base para la implementación. Sin aprobación, no hay avance.
+
+---
+
+### `quiver spec create` — De plan aprobado a spec lista para ejecutar
+
+Una vez aprobado el plan técnico, `spec create` genera automáticamente la estructura de spec: directorio, slices numerados, briefs de ejecución, cuerpo del PR y plan de ejecución en olas. Todo listo para que el ejecutor trabaje slice por slice.
+
+---
+
+### `quiver ai execute-slice` — Ejecución controlada, un slice por vez
+
+El agente ejecutor recibe solo el contexto del slice que tiene que implementar: archivos en scope, dependencias, criterios de validación. Ejecuta, valida y commitea. El alcance está definido de antemano; si el agente se desvía, Quiver lo detecta.
+
+---
+
+### `quiver evidence run` — Validación con registro
+
+Ejecutá cualquier comando (tests, builds, linters) y Quiver registra automáticamente el código de salida, la duración y el output redactado como archivo de evidencia Markdown. Sin capturas de pantalla, sin copy-paste. Evidencia reproducible por defecto.
+
+---
+
+### `quiver dashboard` — Estado consolidado en un vistazo
+
+Un resumen compacto de specs, slices, runs, aprobaciones y agentes configurados. Filtrable por sección, spec y cantidad de items. Con `--json` para integrarlo en dashboards externos.
+
+---
+
+### `quiver ai agent set` — Configura tus agentes una sola vez
+
+Configurá un perfil de planner, ejecutor, revisor y doctor con proveedor y modelo técnico. Quiver les pasa el modelo exacto al CLI del proveedor en cada ejecución. Sin configurar lo mismo en cada sesión. Sin guardar API keys en el repositorio.
+
+---
+
+### `quiver doctor` — Diagnóstico del contrato del proyecto
+
+Valida que la estructura del proyecto esté sana: archivos requeridos, scripts de `package.json`, estado de Quiver. Con `--fix` aplica reparaciones seguras y no destructivas. Con `--json` es integrable en pipelines de CI.
+
+---
+
+## 7. Sección de Confianza
+
+### Construido con el mismo flujo que describe
+
+Quiver se desarrolla usando Quiver. El repositorio es la demostración del producto: cada spec visible en `specs/`, cada slice ejecutado con evidencia, cada PR abierto siguiendo el flujo documentado.
+
+---
+
+### Transparencia de implementación
+
+Todo el código de Quiver es código abierto bajo licencia MIT. Los specs, slices y evidencias del desarrollo del framework están en el repositorio. Podés ver exactamente qué se implementó, cómo, y por qué.
+
+---
+
+### Independiente de cualquier proveedor
+
+Quiver no te ata a un proveedor de IA. Hoy podés usar Codex, mañana Claude, pasado Gemini. Las credenciales viven en los CLIs de cada proveedor. Quiver solo orquesta el flujo.
+
+---
+
+### Sin datos de proyecto enviados a servicios externos
+
+`quiver flow`, `quiver doctor`, `quiver plan` y `quiver dashboard` son comandos que solo leen el estado local del proyecto. No envían datos a ningún servicio externo. El código y el contexto de tu proyecto no salen de tu máquina salvo cuando vos explícitamente invocás un proveedor de IA.
+
+---
+
+### Disponible en npm desde el día uno
+
+```bash
+npx create-quiver@latest --help
+```
+
+Sin registro. Sin trial. Sin tarjeta de crédito. Ejecutable en segundos desde cualquier terminal con Node.js.
+
+---
+
+### Soporte en múltiples plataformas
+
+macOS · Linux · Windows PowerShell · Windows Git Bash · WSL
+
+Documentación de instalación paso a paso para cada plataforma.
+
+---
+
+## 8. CTA Final
+
+### "Tu próximo feature. Con IA. Con orden."
+
+No necesitás cambiar tu stack, tu repositorio ni tu equipo.
+
+Solo necesitás correr un comando desde la raíz de tu proyecto:
+
+```bash
+npx create-quiver@latest init --name "Mi Proyecto"
+```
+
+En minutos tenés el contexto de IA preparado, el flujo definido y el primer paso claro.
+
+**[Empezar gratis →]** `npx create-quiver@latest init`
+
+**[Leer la guía completa →]** Ver documentación
+
+**[Ver el código →]** [Completar con información real del producto: URL del repositorio]
+
+---
+
+> *Quiver es MIT. No hay costos de licencia. El único costo es el de los proveedores de IA que elijas usar.*

package/docs/CLI_UX_GUIDE.md

@@ -94,7 +94,7 @@ Reglas:
 |---|---:|---:|---:|---|
 | `init` | no | si | no | Interactive guia modo de proyecto, metodologia `wdd-sdd`, perfil inicial y proximo paso de perfiles de agentes. |
 | `migrate` | no | no | no | En TTY confirma antes de escribir; en CI/no-TTY requiere `--yes`. `--dry-run` no pide confirmacion ni escribe. |
-| `ai analyze-project` | no | no | si | `--dry-run` es read-only y no ejecuta proveedor; `--review` exige JSON con evidencia, diff final, confirmacion, snapshot y validacion post-write. |
+| `ai analyze-project` | no | no | si | `--dry-run` es read-only y no ejecuta proveedor; `--apply-docs` muestra selector en TTY; `--review` queda como modo avanzado de edicion JSON. |
 | `ai prepare-context` | si | si | si | Modo deterministico por defecto; planner opcional con contrato docs-only. |
 | `ai plan` | si | si | si | El planner ya es implicito; `--with-planner` se acepta por consistencia. |
 | `spec create` | si | si | si | Consume un plan tecnico aprobado del planner; no vuelve a ejecutar proveedor. Review previsualiza el paquete antes de escribir. |
@@ -124,10 +124,20 @@ Analisis profundo de un proyecto existente:
 ```bash
 npx create-quiver ai analyze-project --deep --dry-run
 npx create-quiver ai analyze-project --deep --dry-run --json
-npx create-quiver ai analyze-project --deep --review
+npx create-quiver ai analyze-project --deep --save-proposal --provider codex --model gpt-5.5
+npx create-quiver ai analyze-project --deep --apply-docs --provider codex --model gpt-5.5
+npx create-quiver ai analyze-project apply --run <run-id>
 ```
 
-`ai analyze-project` debe mantener estas garantias: en `--dry-run` no escribe ni ejecuta proveedor; con proveedor no lee `.env`, dependencias, caches, binarios ni outputs generados; toda conclusion importante cita evidencia o queda como `unknown`; las escrituras se limitan a docs aprobados, usan bloques gestionados por Quiver, muestran diff y crean snapshot previo.
+`ai analyze-project` debe mantener estas garantias: en `--dry-run` no escribe ni ejecuta proveedor; el modo provider normal genera auditoria y propuesta pero no escribe docs finales; con proveedor no lee `.env`, dependencias, caches, binarios ni outputs generados; toda conclusion importante cita evidencia o queda como `unknown`; las escrituras se limitan a docs aprobados, usan bloques gestionados por Quiver, muestran diff y crean snapshot previo.
+
+Opciones de aplicacion:
+
+- `--apply-docs` en TTY muestra opciones explicadas: aplicar, ver diff, guardar propuesta, editar propuesta o cancelar.
+- `--apply-docs --yes` aplica en automatizacion despues de validar propuesta, hashes, snapshot y post-write.
+- `--save-proposal` guarda `.quiver/runs/<run-id>/proposal/*` sin escribir docs finales.
+- `ai analyze-project apply --run <run-id>` aplica una propuesta guardada sin ejecutar proveedor ni requerir `--provider` o `--model`.
+- `--review` se mantiene como modo avanzado: abre la propuesta JSON en editor, revalida el JSON editado, muestra diff final y pide confirmacion.
 
 Modo deterministico:
 

package/docs/TROUBLESHOOTING.md

@@ -68,3 +68,97 @@ Para usar la versión fijada por el proyecto:
 ```bash
 npx create-quiver --version
 ```
+
+## `ai analyze-project` falla con JSON inválido del proveedor
+
+### Síntoma
+
+El comando:
+
+```bash
+npx --yes create-quiver@latest ai analyze-project --deep --provider codex --model gpt-5.5
+```
+
+termina con un error como:
+
+```text
+provider analysis JSON does not match the required schema
+```
+
+### Explicación
+
+Quiver trata la salida del proveedor como dato no confiable. Primero intenta validar el JSON, luego repara solo drift estructural seguro, como claves `notes` no permitidas, `claim` usado como `name` faltante o `confidence` en paths donde el schema no lo permite. Después reintenta como máximo de forma acotada cuando el error puede corregirse con feedback de schema.
+
+Si el JSON final sigue inválido, Quiver falla sin escribir docs finales. Los detalles quedan bajo `.quiver/runs/run-.../`:
+
+- `context/selected-context.json`: muestra qué contexto se envió y qué se excluyó.
+- `raw/`: guarda salida del proveedor redactada, truncada con head/tail y hash para auditoría.
+- `repair/analyze-project-repair.json`: registra claves removidas si hubo repair.
+- `retry/analyze-project-retry.json`: registra intentos cuando hubo retry.
+- `validation/analyze-project-validation.json`: guarda todos los errores de validación.
+- `status.json`: resume el estado final del run.
+
+### Qué hacer
+
+Inspeccioná primero el contexto seleccionado:
+
+```bash
+npx --yes create-quiver@latest ai analyze-project --deep --dry-run --json
+```
+
+Después podés reducir el presupuesto si el provider se desvía por exceso de contexto:
+
+```bash
+npx --yes create-quiver@latest ai analyze-project --deep --max-files 40 --max-bytes 150000 --provider codex --model gpt-5.5
+```
+
+Si `package-lock.json` aparece como problema, no deberías incluirlo completo. En versiones actuales debe aparecer resumido en `detected.lockfiles` y omitido como `sampling:lockfile-metadata`.
+
+Cuando el análisis sea válido y quieras escribir documentación:
+
+```bash
+npx --yes create-quiver@latest ai analyze-project --deep --apply-docs --provider codex --model gpt-5.5
+```
+
+`--apply-docs` muestra opciones explicadas en TTY: aplicar documentación, ver diff, guardar propuesta, editar propuesta o cancelar. Si elegís aplicar, Quiver revalida la propuesta, crea snapshot y escribe solo docs permitidos.
+
+Para guardar primero y aplicar después sin volver a ejecutar el proveedor:
+
+```bash
+npx --yes create-quiver@latest ai analyze-project --deep --save-proposal --provider codex --model gpt-5.5
+npx --yes create-quiver@latest ai analyze-project apply --run <run-id>
+```
+
+`--review` sigue disponible como modo avanzado si querés editar la propuesta JSON manualmente antes de escribir.
+
+## `ai analyze-project` no completa `docs/CONTEXTO.md` ni crea `docs/ARCHITECTURE.md`
+
+### Síntoma
+
+Después de ejecutar:
+
+```bash
+npx --yes create-quiver@latest ai analyze-project --deep --provider codex --model gpt-5.5
+```
+
+los docs finales siguen con placeholders o falta `docs/ARCHITECTURE.md`.
+
+### Explicación
+
+Ese comando ejecuta el análisis, valida la respuesta IA y guarda artifacts auditados en `.quiver/runs`, pero no escribe documentación final por defecto. Es intencional: evita cambios sorpresivos en repos reales.
+
+### Qué hacer
+
+Usá uno de estos caminos seguros:
+
+```bash
+npx --yes create-quiver@latest ai analyze-project --deep --apply-docs --provider codex --model gpt-5.5
+npx --yes create-quiver@latest ai analyze-project --deep --apply-docs --yes --provider codex --model gpt-5.5
+npx --yes create-quiver@latest ai analyze-project --deep --save-proposal --provider codex --model gpt-5.5
+npx --yes create-quiver@latest ai analyze-project apply --run <run-id>
+```
+
+- `--apply-docs` en TTY muestra opciones explicadas antes de escribir.
+- `--apply-docs --yes` aplica en automatización si la propuesta y los docs destino son seguros.
+- `--save-proposal` guarda `.quiver/runs/<run-id>/proposal/*` sin tocar docs finales.
+- `apply --run <run-id>` aplica una propuesta guardada sin ejecutar proveedor ni pedir `--provider` o `--model`.

package/docs/reference/commands.md

@@ -49,7 +49,7 @@ El contenido curado fuera de los marcadores se mantiene manual y no debe ser ree
 | AI lifecycle | `ai active-slice status\|reconcile` | Inspect or dry-run reconcile local active-slice state from every supported source. |
 | AI lifecycle | `ai status` | Show current AI lifecycle phase, approved versions, blockers, and next command. |
 | AI lifecycle | `ai resume` | Resume guidance from the last valid lifecycle phase without chat memory. |
-| AI lifecycle | `ai analyze-project` | Read and explain a bounded project sample without provider execution or writes. |
+| AI lifecycle | `ai analyze-project` | Analyze a bounded project sample and generate audited documentation proposals. |
 | AI lifecycle | `ai onboard` | Run or print the planner onboarding prompt with a token-aware context pack. |
 | AI lifecycle | `ai prepare-context` | Preview or write docs-only AI context updates with assumptions and risks. |
 | AI lifecycle | `ai agent set\|list\|show\|doctor\|repair` | Manage, diagnose, and dry-run repair planner, executor, reviewer, and doctor provider profiles without secrets. |
@@ -199,17 +199,77 @@ En `--dry-run`, Quiver no escribe archivos, no ejecuta proveedor y muestra qué
 Para generar docs desde IA:
 
 ```bash
-npx --yes create-quiver@latest ai analyze-project --deep --review
-npx --yes create-quiver@latest ai analyze-project --deep --review --strict
+npx --yes create-quiver@latest ai analyze-project --deep --save-proposal --provider codex --model gpt-5.5
+npx --yes create-quiver@latest ai analyze-project --deep --apply-docs --provider codex --model gpt-5.5
+npx --yes create-quiver@latest ai analyze-project apply --run <run-id>
 ```
 
-El modo con proveedor exige JSON validado por schema, evidencia por conclusión, niveles `confirmed`, `inferred`, `unknown` o `conflict`, revisión editable, diff final, confirmación humana, snapshot previo en `.quiver/runs`, artefactos redactados y validación post-write. `--strict` convierte conflictos importantes de docs en error. El resultado puede quedar como `unknown` o `needs_confirmation` cuando el código no prueba una conclusión.
+El modo con proveedor exige JSON validado por schema, evidencia por conclusión, niveles `confirmed`, `inferred`, `unknown` o `conflict`, artifacts auditados en `.quiver/runs`, diff, snapshot previo cuando se escribe y validación post-write. `--strict` convierte conflictos importantes de docs en error. El resultado puede quedar como `unknown` o `needs_confirmation` cuando el código no prueba una conclusión.
+
+Garantías del flujo con proveedor:
+
+- `--dry-run` no escribe archivos ni ejecuta proveedor.
+- El contexto enviado al proveedor se redacta, se acota por presupuesto y se guarda como manifest sin contenido crudo.
+- Los lockfiles no consumen el presupuesto principal por defecto; Quiver los resume como metadata de package manager, cantidad estimada de dependencias y dependencias principales.
+- Los docs generados por Quiver se priorizan por debajo de entrypoints, componentes, contexts/state, lib/data layer, auth, DB/integraciones y documentación humana del producto.
+- En TTY muestra loader; en no-TTY imprime progreso lineal para lectura, estructura, muestra, provider, schema, repair/retry y artifacts.
+- Si el proveedor devuelve JSON con drift seguro como `notes`, `claim` usado como `name` faltante, o `confidence` en paths no permitidos, Quiver lo repara, registra el repair y revalida.
+- Si el JSON sigue inválido pero el error es retryable, Quiver hace 1 retry por defecto, con cap duro de 2 retries.
+- Si el JSON final es inválido, Quiver falla sin escribir docs finales y deja manifests de validación/retry/repair en `.quiver/runs`.
+- El modo provider normal no escribe docs finales por defecto; usá `--apply-docs`, `--save-proposal` o `--review` para decidir qué hacer con la propuesta validada.
+- `--apply-docs` en TTY muestra opciones explicadas para aplicar, ver diff, guardar propuesta, editar propuesta o cancelar.
+- `--apply-docs --yes` aplica en automatización después de validar propuesta, paths permitidos, hashes, snapshot y post-write.
+- `--save-proposal` guarda `.quiver/runs/<run-id>/proposal/*` sin escribir docs finales.
+- `ai analyze-project apply --run <run-id>` aplica una propuesta guardada sin ejecutar proveedor ni requerir `--provider` o `--model`.
+- `--review` abre una propuesta JSON editable, revalida el JSON editado, muestra diff final y pide confirmación antes de escribir docs permitidos.
+- Las escrituras aprobadas crean snapshot con hashes y se escriben con rename atómico.
+
+Benchmark recomendado:
+
+- CI debe usar fixtures determinísticas: JSON válido, `notes` extra, fences, texto alrededor del JSON, JSON truncado, campos faltantes, confianza inválida, contenido tipo secreto, retry exitoso y retry agotado.
+- El smoke live contra un repo real, por ejemplo `nika-erp`, es evidencia de release opcional. No debe ser gate obligatorio de CI porque depende del proveedor, credenciales, red y modelo disponible.
+
+Smoke de release recomendado:
+
+```bash
+mkdir -p /tmp/quiver-smoke
+rsync -a --delete --exclude .git --exclude node_modules --exclude .next --exclude .quiver "/Users/fabrijk/Documents/Work/Proyectos Personales/nika/nika-erp/nika-erp/" /tmp/quiver-smoke/nika-erp/
+cd /tmp/quiver-smoke/nika-erp
+npx --yes create-quiver@latest ai analyze-project --deep --dry-run --json
+npx --yes create-quiver@latest ai analyze-project --deep --provider codex --model gpt-5.5
+npx --yes create-quiver@latest ai analyze-project --deep --save-proposal --provider codex --model gpt-5.5
+npx --yes create-quiver@latest ai analyze-project --deep --apply-docs --provider codex --model gpt-5.5
+npx --yes create-quiver@latest ai analyze-project apply --run <run-id>
+```
+
+También podés usar una rama descartable en el repo real. No ejecutes el smoke de aplicación sobre el checkout principal de `nika-erp`.
+
+Evidencia esperada:
+
+- `--dry-run --json` parsea como JSON, `provider_execution` queda `skipped`, `writes` queda vacío y no crea docs finales.
+- `package-lock.json` aparece en `detected.lockfiles` y en omitidos con `sampling:lockfile-metadata`, no en contenido enviado al provider.
+- El modo provider escribe artifacts auditados en `.quiver/runs`, redactados y con tamaño controlado, pero no escribe docs finales sin `--apply-docs`, `--review` o `apply --run`.
+- Si el provider devuelve drift no reparable, el comando falla con path/tipo/causa probable y próximo comando seguro, sin escribir docs finales.
+- `--save-proposal` debe crear `.quiver/runs/<run-id>/proposal/*` sin modificar docs finales.
+- `--apply-docs` debe mostrar selector explicado en TTY o requerir `--yes` en automatización.
+- `apply --run <run-id>` debe aplicar la propuesta guardada sin volver a ejecutar proveedor.
+
+Rollback de release:
+
+- Si el smoke live escribe docs inesperadamente sin `--review`, filtra secretos, omite artifacts críticos o falla con ruido masivo de schema, no publiques `latest`.
+- Publicá una corrección como canary o revertí la versión npm afectada según el proceso de release vigente.
+- Para usuarios impactados, indicar `npx create-quiver ai analyze-project --deep --dry-run --json` como siguiente comando seguro y pedir `.quiver/runs/run-.../validation/analyze-project-validation.json` redactado como evidencia.
 
 | Comando | Para qué sirve |
 |---|---|
 | `npx --yes create-quiver@latest ai analyze-project --deep --dry-run` | Previsualiza descubrimiento y muestreo del repo sin escribir ni ejecutar proveedor. |
 | `npx --yes create-quiver@latest ai analyze-project --deep --dry-run --json` | Emite el plan de análisis como JSON parseable para automatización. |
 | `npx --yes create-quiver@latest ai analyze-project --deep --review` | Ejecuta proveedor, valida análisis JSON con evidencia, abre revisión humana y escribe solo docs permitidos tras confirmación. |
+| `npx --yes create-quiver@latest ai analyze-project --deep --provider codex --model gpt-5.5` | Ejecuta proveedor y genera propuesta auditada en `.quiver/runs`; no escribe docs finales sin `--review`. |
+| `npx --yes create-quiver@latest ai analyze-project --deep --save-proposal --provider codex --model gpt-5.5` | Guarda una propuesta validada en `.quiver/runs/<run-id>/proposal` sin escribir docs finales. |
+| `npx --yes create-quiver@latest ai analyze-project --deep --apply-docs --provider codex --model gpt-5.5` | En TTY debe mostrar opciones explicadas para aplicar, ver diff, guardar, editar o cancelar. |
+| `npx --yes create-quiver@latest ai analyze-project --deep --apply-docs --yes --provider codex --model gpt-5.5` | Aplica docs validados en modo automatizado, con snapshots y validación post-write. |
+| `npx --yes create-quiver@latest ai analyze-project apply --run <run-id>` | Aplica una propuesta guardada sin ejecutar proveedor ni requerir `--provider` o `--model`. |
 | `npx --yes create-quiver@latest ai analyze-project --scope apps/web --max-files 80 --max-bytes 300000 --include-tests --dry-run` | Acota el análisis por workspace/ruta y presupuesto de muestra. |
 | `npx --yes create-quiver@latest ai prepare-context --dry-run` | Previsualiza actualizaciones documentales de contexto para IA. |
 | `npx --yes create-quiver@latest ai prepare-context` | Escribe actualizaciones documentales de contexto para IA. |
@@ -289,6 +349,10 @@ Base branch policy: `--base <branch>` always wins. Without `--base`, slice readi
 | `--include-source` | En `ai analyze-project`, incluye código fuente sin requerir `--deep`. |
 | `--include-tests` | En `ai analyze-project`, incluye tests en la muestra. |
 | `--include-db` | En `ai analyze-project`, incluye schemas, migraciones y archivos DB. |
+| `--apply-docs` | En `ai analyze-project`, habilita el flujo seguro para aplicar propuestas documentales validadas. |
+| `--save-proposal` | En `ai analyze-project`, guarda la propuesta validada como artifacts sin escribir docs finales. |
+| `--diff` | En `ai analyze-project`, muestra o guarda el diff documental propuesto cuando el flujo lo soporta. |
+| `--allow-dirty-docs` | En `ai analyze-project`, permite continuar con docs destino modificados solo donde el flujo seguro lo soporte. |
 | `--scope <path\|name>` | En `ai analyze-project`, restringe el análisis a una ruta o workspace. |
 | `--strict` | En validaciones soportadas, convierte conflictos importantes en errores. |
 | `--with-planner` | Activa comportamiento asistido por planner solo en comandos que lo soportan. |