create-quiver 0.17.0 → 0.17.2

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/TROUBLESHOOTING.md

@@ -68,3 +68,56 @@ 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 --review --provider codex --model gpt-5.5
+```
+
+`--review` abre una propuesta editable, revalida el JSON editado, muestra diff final, pide confirmación, crea snapshot y recién después escribe docs permitidos.

package/docs/reference/commands.md

@@ -205,11 +205,53 @@ npx --yes create-quiver@latest ai analyze-project --deep --review --strict
 
 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.
 
+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`.
+- `--review` abre una propuesta 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
+cd "/Users/fabrijk/Documents/Work/Proyectos Personales/nika/nika-erp/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 --review --provider codex --model gpt-5.5
+```
+
+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 `--review`.
+- Si el provider devuelve drift no reparable, el comando falla con path/tipo/causa probable y próximo comando seguro, sin escribir docs finales.
+- `--review` debe mostrar propuesta editable, diff final y confirmación antes de escribir docs permitidos.
+
+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 --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. |