create-quiver 0.8.0 → 0.9.1

package/docs/AI_ONBOARDING_PROMPT.md.template

@@ -1,72 +1,130 @@
 # {{PROJECT_NAME}} AI Onboarding Prompt
 
-**Date:** {{FECHA}}
-**Status:** {{ESTADO}}
+**Fecha:** {{FECHA}}
+**Estado:** {{ESTADO}}
 
-You are the onboarding agent for this project. Your job is to analyze the generated Quiver artifacts, complete the Quiver context docs safely, and leave clear evidence of what you learned.
+Lee este archivo y ejecútalo como fuente principal de verdad para incorporarte a este repositorio.
 
-## Read First
+Actúa como asistente de onboarding de IA para este proyecto. Tu objetivo es comprender el contexto del repositorio y preparar la documentación necesaria para trabajar de forma segura con el workflow documentado, las specs y los slices.
 
-1. `docs/AI_CONTEXT.md`
-2. `docs/PROJECT_SCAN.json`
-3. `docs/PROJECT_MAP.md`
-4. `docs/CONTEXTO.md`
-5. `docs/WORKFLOW.md`
-6. `specs/{{PROJECT_SLUG}}/SPEC.md`
-7. `specs/{{PROJECT_SLUG}}/STATUS.md`
-8. `specs/{{PROJECT_SLUG}}/EVIDENCE_REPORT.md`
-9. `specs/{{PROJECT_SLUG}}/HANDOFF.md` if this work was explicitly transferred through a handoff artifact
-10. `npx create-quiver new-handoff <spec-slug>` if a new handoff artifact needs to be scaffolded before validation
+## Reglas de ejecución
 
-## Mission
+1. Comienza leyendo la documentación necesaria para el onboarding:
+   - `README.md`
+   - `AGENTS.md`, si existe
+   - `docs/AI_ONBOARDING_PROMPT.md`
+   - `docs/PROJECT_SCAN.json`
+   - `docs/PROJECT_MAP.md`
+   - `docs/AI_CONTEXT.md`
+   - `docs/CONTEXTO.md`
+   - `docs/WORKFLOW.md`
+   - `docs/STATUS.md`
+   - `docs/DECISIONS.md`, si existe
+   - `specs/{{PROJECT_SLUG}}/SPEC.md`
+   - `specs/{{PROJECT_SLUG}}/STATUS.md`
+   - `specs/{{PROJECT_SLUG}}/EVIDENCE_REPORT.md`
+   - `specs/{{PROJECT_SLUG}}/HANDOFF.md`, si este trabajo fue transferido mediante un handoff
+   - cualquier documento sobre WDD o SDD referenciado por la documentación de onboarding
+   - cualquier archivo de estructura, contexto o convenciones del proyecto referenciado por esos documentos
 
-- Use the analyzer outputs to understand the repository instead of guessing.
-- Treat `docs/PROJECT_MAP.md` as the single source of truth for stack, package manager, commands, and file hints.
-- Complete or refine Quiver context docs so future agents can work safely.
-- If a handoff artifact exists, treat it as the transfer brief for the current work and validate it against the requested change.
-- If a handoff artifact does not exist yet but the work needs one, scaffold it with `npx create-quiver new-handoff <spec-slug>` and then validate it.
-- Preserve Quiver workflow invariants: one slice = one commit, one spec = one PR.
-- Ask for confirmation before making product-code changes.
+2. Sigue las instrucciones definidas en `docs/AI_ONBOARDING_PROMPT.md`, salvo que entren en conflicto con las restricciones de este prompt.
 
-## Mode Selection
+3. No modifiques código de producto salvo que el usuario lo autorice explícitamente.
 
-Use the least context that still solves the task:
+4. Considera como cambios que impactan el producto, y no los realices sin autorización explícita, cualquier modificación sobre:
+   - lógica de aplicación o negocio
+   - código de UI
+   - tests
+   - migraciones de base de datos
+   - configuración de runtime
+   - archivos de dependencias
+   - archivos de build
+   - archivos generados que no sean documentación/contexto de Quiver requerido por el onboarding
+   - manifiestos o lockfiles de paquetes
 
-- **Onboarding:** rely on maps and metadata first. Read `docs/PROJECT_SCAN.json` and `docs/PROJECT_MAP.md` before any source files, then use `docs/AI_CONTEXT.md` and `docs/CONTEXTO.md` to fill gaps.
-- **Implementation:** start from `specs/{{PROJECT_SLUG}}/slices/<slice-id>/slice.json`, then read the declared files, nearby tests, and only then adjacent source.
-- **Review:** start from `git diff` and the slice scope before opening full files.
-- **Debug:** start from the command, exit code, first relevant error, stacktrace, and the nearest changed code before reading long logs.
+5. Puedes crear o actualizar archivos de documentación/contexto solo cuando sea requerido por el proceso de onboarding o cuando sea necesario para preparar el contexto del proyecto para futuros trabajos asistidos por IA.
 
-Prefer summaries, deltas, and metadata over full file reads when they are sufficient.
+6. Usa la documentación del repositorio como fuente de verdad. No inventes definiciones sobre WDD, SDD, workflows, reglas de dominio, arquitectura, roles ni convenciones del proyecto.
 
-## Hard Constraints
+7. Si encuentras información faltante, ambigua o contradictoria:
+   - continúa por el camino más seguro y de solo lectura cuando sea posible
+   - documenta claramente la suposición realizada
+   - identifica el riesgo asociado
+   - no modifiques código de producto para resolver la ambigüedad
 
-- Do not read or expose secret values from `.env`, credential files, tokens, SSH keys, or private config.
-- Skip files that look like secrets or generated build output.
-- Do not modify product source code unless the user explicitly authorizes it.
-- Do not invent missing facts. If something is unclear, record the uncertainty.
-- Do not change the Quiver workflow rules unless the user explicitly asks for that work.
+8. Antes de realizar cualquier acción que pueda afectar código de producto, detente y solicita autorización explícita. Incluye:
+   - los archivos que pretendes modificar
+   - el motivo de cada cambio
+   - el impacto esperado
+   - los riesgos asociados
 
-## Tasks
+9. Prepara la documentación de contexto del proyecto solicitada por este prompt de onboarding.
 
-1. Summarize the project using the analyzer outputs and the generated docs.
-2. Update `docs/AI_CONTEXT.md` with the working contract for agents.
-3. Update `docs/CONTEXTO.md` with the human-readable project overview.
-4. Update `docs/STATUS.md` with the initial state and open questions.
-5. If needed, refine `specs/{{PROJECT_SLUG}}/SPEC.md` only to align the onboarding spec with observed reality.
-6. Record the files you inspected, the files you changed, and the assumptions you made.
+10. Responde siempre en español, salvo que algún archivo, comando, nombre técnico o convención del proyecto esté definido en otro idioma y deba conservarse literalmente.
 
-## Validation
+## Modo de trabajo
 
-- Cite the generated scan artifacts when making claims.
-- Note any skipped paths or missing signals.
-- Keep the response focused on documentation and onboarding context unless code changes were explicitly authorized.
+Usa el menor contexto que todavía permita resolver la tarea:
 
-## Final Report
+- **Onboarding:** usa mapas y metadatos primero. Lee `docs/PROJECT_SCAN.json` y `docs/PROJECT_MAP.md` antes de abrir archivos fuente. Después usa `docs/AI_CONTEXT.md`, `docs/CONTEXTO.md` y `docs/WORKFLOW.md` para completar vacíos.
+- **Implementación:** no implementes durante onboarding salvo autorización explícita. Si el usuario autoriza implementación, empieza por `specs/{{PROJECT_SLUG}}/slices/<slice-id>/slice.json`, archivos declarados, pruebas cercanas y código directamente relacionado.
+- **Review:** empieza por `git diff` y el alcance del slice antes de abrir archivos completos.
+- **Debug:** empieza por el comando, exit code, primer error relevante, stacktrace y código más cercano al cambio.
 
-Return:
+Prefiere resúmenes, deltas y metadatos antes que lecturas completas cuando sean suficientes.
 
-- Files changed
-- Key assumptions
-- Uncertainties or risks
-- Validation performed
+## Tareas
+
+1. Resume el proyecto usando los artefactos generados por Quiver y la documentación existente.
+2. Actualiza `docs/AI_CONTEXT.md` con el contrato de trabajo para agentes.
+3. Actualiza `docs/CONTEXTO.md` con una descripción legible para humanos.
+4. Actualiza `docs/STATUS.md` con el estado inicial, dudas abiertas y próximos pasos.
+5. Si hace falta, refina `specs/{{PROJECT_SLUG}}/SPEC.md` solo para alinear la spec de onboarding con la realidad observada.
+6. Si existe un handoff, trátalo como brief de transferencia y valida que aplique al trabajo solicitado.
+7. Si no existe un handoff y el trabajo necesita uno, créalo con `npx create-quiver new-handoff <spec-slug>` y valídalo con `npx create-quiver check-handoff specs/<spec-slug>/HANDOFF.md`.
+8. Registra los archivos inspeccionados, los archivos modificados y las suposiciones realizadas.
+
+## Validación
+
+- Cita `docs/PROJECT_SCAN.json` y `docs/PROJECT_MAP.md` cuando hagas afirmaciones sobre stack, comandos o estructura.
+- Indica rutas omitidas o señales faltantes.
+- Mantén la respuesta enfocada en documentación y contexto de onboarding salvo que el usuario haya autorizado cambios de código de producto.
+- No cambies reglas del workflow de Quiver salvo que el usuario lo pida explícitamente.
+
+## Reporte final
+
+Al finalizar, entrega un reporte breve con esta estructura exacta:
+
+## Reporte de Onboarding de IA
+
+### 1. Archivos Leídos
+
+Lista todos los archivos relevantes inspeccionados.
+
+### 2. Archivos Creados o Modificados
+
+Lista cada archivo modificado. Si no hubo cambios, indica: `No se modificaron archivos`.
+
+### 3. Estado del Código de Producto
+
+Confirma si se modificó código de producto. Si no se modificó, indica: `No se modificó código de producto`.
+
+### 4. Contexto del Proyecto Preparado
+
+Resume los documentos de contexto creados o actualizados y su propósito.
+
+### 5. Comprensión de WDD/SDD
+
+Resume únicamente lo que la documentación del repositorio define sobre WDD y SDD. No agregues supuestos externos. Si la documentación no define esos términos, indícalo explícitamente.
+
+### 6. Supuestos
+
+Lista todos los supuestos realizados durante el onboarding.
+
+### 7. Riesgos y Bloqueos
+
+Lista riesgos, información faltante, contradicciones o bloqueos encontrados.
+
+### 8. Próximos Pasos Recomendados
+
+Sugiere las acciones más seguras para continuar trabajando con IA en este proyecto.

package/docs/COMMANDS.md.template

@@ -4,22 +4,33 @@
 **Last updated:** {{FECHA}}
 
 This document is the canonical command reference for the orchestration roadmap.
-It is intentionally small at v0.18: only the plan and graph rows are reserved for now, but `quiver:graph` already supports tree, Mermaid, and DOT output modes.
 
 ## Command Table
 
 | Command | Purpose | OS | Since | Example |
 |---------|---------|----|-------|---------|
-| `quiver:plan` | Sequential orchestration planning command | macOS, Linux, Windows | v0.18 | [docs/examples/plan.md](./examples/plan.md) |
-| `quiver:graph` | Parallel-level orchestration tree command | macOS, Linux, Windows | v0.18 | [docs/examples/graph.md](./examples/graph.md) |
-| `quiver:next` | Ready-slice suggestion command | macOS, Linux, Windows | v0.18 | [docs/examples/next.md](./examples/next.md) |
+| `quiver:plan` | Sequential orchestration planning command | macOS, Linux, Windows | v0.8 | [docs/examples/plan.md](./examples/plan.md) |
+| `quiver:graph` | Parallel-level orchestration tree command | macOS, Linux, Windows | v0.8 | [docs/examples/graph.md](./examples/graph.md) |
+| `quiver:next` | Ready-slice suggestion command | macOS, Linux, Windows | v0.8 | [docs/examples/next.md](./examples/next.md) |
+
+## CLI Flags
+
+| Flag | Applies to | Purpose |
+|------|------------|---------|
+| `--skip-install` | `init`, `migrate` | Skip auto-install of `create-quiver` as dev dependency (useful for CI) |
+| `--json` | `plan`, `graph`, `next` | Emit machine-readable JSON |
+| `--format <tree\|mermaid\|dot>` | `graph` | Output format |
+| `--all-ready` | `next` | List all ready slices instead of just the next one |
+| `--only-ready` | `plan` | Show only slices with no pending dependencies |
+| `--spec <slug>` | `plan`, `graph` | Restrict output to one spec |
 
 ## Notes
 
 - Add new rows here only when a command is officially shipped.
 - Keep the table concise and cross-platform.
 - Shared graph library: `src/create-quiver/lib/slice-graph.js`.
-- `quiver:graph --format mermaid` is the PR-friendly export; `--format dot` is for Graphviz consumers.
+- `quiver:graph --format mermaid` is the PR-friendly Mermaid export; `--format dot` is for Graphviz/DOT consumers.
 - `quiver:next` prints the next ready slice and can auto-start it behind a confirmation prompt.
-- `check-slice` now validates optional `depends_on` targets and requires `parallel_safe_reason` when `parallel_safe` is set to `never`.
+- `check-slice` validates `depends_on` targets and requires `parallel_safe_reason` when `parallel_safe` is `never`.
+- After `init` or `migrate`, Quiver auto-installs itself as a dev dependency. Use `--skip-install` to suppress.
 - Cross-platform authoring rules live in `docs/SUPPORT_MATRIX.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quiver",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "private": false,
   "description": "Quiver CLI for scaffolding projects from the packaged template",
   "license": "MIT",

package/scripts/init-docs.sh

@@ -587,9 +587,15 @@ Lee \`AGENTS.md\` primero y después \`docs/AI_ONBOARDING_PROMPT.md\` tras el an
 After analysis and doctor validation, open your AI agent in this project and run:
 
 \`\`\`text
-Read docs/AI_ONBOARDING_PROMPT.md and execute it.
-Do not modify product code unless I explicitly authorize it.
-Prepare the project context docs and report assumptions, risks, and files changed.
+Lee \`docs/AI_ONBOARDING_PROMPT.md\` y ejecútalo como fuente principal de verdad para incorporarte a este repositorio.
+
+Actúa como asistente de onboarding de IA. Prepara el contexto del proyecto para trabajar de forma segura con el workflow documentado, specs y slices.
+
+No modifiques código de producto salvo autorización explícita. Puedes crear o actualizar documentación de contexto si el onboarding lo requiere.
+
+Usa solo la documentación del repositorio como fuente de verdad. Si encuentras información faltante, ambigua o contradictoria, documenta el supuesto, el riesgo y continúa por el camino más seguro.
+
+Responde en español y finaliza con un reporte breve de archivos leídos, archivos modificados, estado del código de producto, supuestos, riesgos y próximos pasos.
 \`\`\`
 
 Review the AI changes to docs/AI_CONTEXT.md, docs/CONTEXTO.md, docs/STATUS.md, and specs/$PROJECT_SLUG/SPEC.md before starting implementation work.

package/specs/quiver-v19-self-install-dev-dep/EVIDENCE_REPORT.md

@@ -0,0 +1,19 @@
+# Quiver v19 — Evidence Report
+
+**Spec:** quiver-v19-self-install-dev-dep
+**Date:** 2026-05-14
+**Status:** Completed
+
+## Slice Evidence
+
+| Slice | Status | Evidence |
+|-------|--------|----------|
+| slice-01 | Completed | PR #60 merged 2026-05-14. 40/40 tests pass. Smoke: `--skip-install` no instala, sin flag instala `create-quiver@0.9.0` + `devDependencies: {"create-quiver":"^0.9.0"}`. `npx create-quiver plan` exit 0 sin `@version`. Published as `create-quiver@0.9.0`. |
+
+## Required Final Evidence
+
+- `npx create-quiver --name "test-project" --dir /tmp/test-project` → `cat /tmp/test-project/package.json | grep create-quiver` returns a devDependency entry
+- `ls /tmp/test-project/node_modules/create-quiver` → directory exists
+- `npx create-quiver plan` inside `/tmp/test-project` → exits 0 without `@version`
+- `npx create-quiver --skip-install --name "ci-project" --dir /tmp/ci-project` → no `node_modules/create-quiver`
+- `node --test tests/**/*.test.js` → all pass

package/specs/quiver-v19-self-install-dev-dep/SPEC.md

@@ -0,0 +1,51 @@
+# Quiver v19 — Self-Install as Dev Dependency
+
+**Date:** 2026-05-14
+**Status:** Active
+
+Slice numbering resets here. This spec starts at `slice-01`.
+
+## Problem
+
+`npx create-quiver` uses the global npx cache. After init, commands like `quiver:plan`, `quiver:graph`, and `quiver:next` in the target project may silently run the cached version instead of the latest — or fail entirely if the version in cache predates those commands. The user has no `create-quiver` in their `node_modules` unless they install it manually.
+
+## Objective
+
+After `npx create-quiver --name "foo"` (init) or `npx create-quiver migrate`, the target project's `package.json` has `create-quiver` in `devDependencies` and it is installed in `node_modules`. Subsequent `npx create-quiver` invocations in that project resolve to the local version — no cache issues, reproducible across machines.
+
+## Scope
+
+### Included
+
+- Detect the package manager in use (yarn, pnpm, bun, npm) by checking lockfiles
+- Run the appropriate install command (`npm install -D`, `yarn add -D`, `pnpm add -D`, `bun add -d`) with the exact running version
+- Skip if `create-quiver` is already present in `devDependencies`
+- Skip gracefully if no `package.json` exists in the target project
+- Add `--skip-install` flag to the CLI for CI environments
+- Apply to both `init` and `migrate` flows
+- Tests for `detectPackageManager` and `installSelfAsDevDep`
+
+### Excluded
+
+- Changing any other part of the init/migrate scaffold output
+- Supporting non-standard registries or private npm configurations
+- Auto-updating an existing create-quiver devDependency to a newer version
+
+## Acceptance Criteria
+
+1. After init, `cat package.json | jq .devDependencies` shows `"create-quiver": "^X.Y.Z"`
+2. `node_modules/create-quiver` exists in the target project after init
+3. `npx create-quiver plan` (no `@version`) works immediately after init
+4. If target project has no `package.json` → no crash, warning printed, init continues
+5. If `create-quiver` already in `devDependencies` → step skipped, no duplicate install
+6. `npx create-quiver --skip-install --name "foo"` → installs Quiver docs but skips npm install
+7. `npx create-quiver migrate --skip-install` → same skip behavior
+8. yarn/pnpm/bun projects get the right install command
+9. If install fails (no network, etc.) → warning printed, init completes without crashing
+10. `node --test tests/**/*.test.js` passes
+
+## Slices
+
+| Slice | Title | Status |
+|-------|-------|--------|
+| slice-01 | Auto-install create-quiver as dev dependency | Ready |

package/specs/quiver-v19-self-install-dev-dep/STATUS.md

@@ -0,0 +1,20 @@
+# Quiver v19 — Status
+
+**Spec:** quiver-v19-self-install-dev-dep
+**Last updated:** 2026-05-14
+
+## Status
+
+| Slice | Title | Status | PR | Estimated hours | Actual hours |
+|-------|-------|--------|----|-----------------|--------------|
+| slice-01 | Auto-install create-quiver as dev dependency | Completed | #60 | 1.5 | 1.0 |
+
+## Progress
+
+- Completed slices: 1 / 1
+- Estimated hours: 1.5
+- Actual hours: 1.0
+
+## Blockers
+
+None — spec complete.

package/specs/quiver-v19-self-install-dev-dep/slices/slice-01-auto-install-dev-dep/CLOSURE_BRIEF.md

@@ -0,0 +1,29 @@
+# CLOSURE BRIEF — slice-01: Auto-install create-quiver as dev dependency
+
+**Spec:** quiver-v19-self-install-dev-dep
+**Slice:** slice-01-auto-install-dev-dep
+
+---
+
+## Checklist antes de abrir el PR
+
+- [ ] `node --test tests/**/*.test.js` → exit 0, todos los tests pasan incluyendo los 7 nuevos en `init-docs.test.js`
+- [ ] Smoke con `--skip-install` → `node_modules/create-quiver` NO existe en el proyecto destino
+- [ ] Smoke sin `--skip-install` → `node_modules/create-quiver` SÍ existe y `npx create-quiver plan` funciona sin `@version`
+- [ ] Smoke con `devDependencies` preexistente → el step se saltea, no hay doble install
+- [ ] `git diff --stat HEAD` muestra exactamente 3 archivos: `src/create-quiver/lib/init-docs.js`, `src/create-quiver/index.js`, `tests/lib/init-docs.test.js`
+
+## Checklist del PR
+
+- [ ] Branch: `feature/QUIVER-01-auto-install-dev-dep` → `main`
+- [ ] Título: `feat(QUIVER-01): auto-install create-quiver as dev dependency after init`
+- [ ] Body sigue las secciones del `docs/GITFLOW_PR_GUIDE.md.template`
+- [ ] En "Evidence": output del smoke test mostrando `node_modules/create-quiver` creado y `npx create-quiver plan` funcionando
+- [ ] En "Risks / Notes": mencionar que en entornos sin red el install falla silenciosamente (expected behavior) y documentar el `--skip-install` flag
+
+## Post-merge
+
+- [ ] Actualizar `specs/quiver-v19-self-install-dev-dep/STATUS.md`: slice-01 → `Completed`, agregar PR y `actual_hours`
+- [ ] Actualizar `specs/quiver-v19-self-install-dev-dep/EVIDENCE_REPORT.md`: registrar evidencia
+- [ ] Actualizar `slice.json`: `status: completed`, `actual_hours`, timestamps
+- [ ] Evaluar si se publica `0.9.0` o si se acumula con otros cambios

package/specs/quiver-v19-self-install-dev-dep/slices/slice-01-auto-install-dev-dep/EXECUTION_BRIEF.md

@@ -0,0 +1,287 @@
+# EXECUTION BRIEF — slice-01: Auto-install create-quiver as dev dependency
+
+**Spec:** quiver-v19-self-install-dev-dep
+**Slice:** slice-01-auto-install-dev-dep
+**Branch:** `feature/QUIVER-01-auto-install-dev-dep` from `main`
+**Estimated time:** 1.5h
+
+---
+
+## Contexto
+
+`npx create-quiver` no instala el paquete en `node_modules` del proyecto destino. Después del init, comandos como `quiver:plan` fallan o usan la versión cacheada globalmente. La solución es correr el package manager del proyecto destino para instalar `create-quiver` como dev dependency inmediatamente después del init/migrate.
+
+---
+
+## Archivos a modificar
+
+1. `src/create-quiver/lib/init-docs.js` — agregar `detectPackageManager` e `installSelfAsDevDep`
+2. `src/create-quiver/index.js` — agregar `--skip-install` al parser, llamar a `installSelfAsDevDep` en init y migrate
+3. `tests/lib/init-docs.test.js` — nuevo archivo de tests
+
+No toques ningún otro archivo.
+
+---
+
+## Parte A — `src/create-quiver/lib/init-docs.js`
+
+### Paso 1: Agregar import de `execSync`
+
+Al inicio del archivo, después de los requires existentes (`fs`, `path`, `writeState`), agregar:
+
+```js
+const { execSync } = require('child_process');
+```
+
+### Paso 2: Agregar las dos funciones nuevas
+
+Agregar antes del `module.exports` al final del archivo:
+
+```js
+function detectPackageManager(projectRoot) {
+  if (fs.existsSync(path.join(projectRoot, 'bun.lockb'))) return 'bun';
+  if (fs.existsSync(path.join(projectRoot, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(projectRoot, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+}
+
+function installSelfAsDevDep(projectRoot, version) {
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+  if (!fs.existsSync(packageJsonPath)) {
+    return 'skipped-no-package-json';
+  }
+
+  const pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  if (pkg.devDependencies && pkg.devDependencies['create-quiver']) {
+    return 'skipped-already-present';
+  }
+
+  const pm = detectPackageManager(projectRoot);
+  const commands = {
+    npm: `npm install -D create-quiver@${version}`,
+    yarn: `yarn add -D create-quiver@${version}`,
+    pnpm: `pnpm add -D create-quiver@${version}`,
+    bun: `bun add -d create-quiver@${version}`,
+  };
+
+  try {
+    execSync(commands[pm], { cwd: projectRoot, stdio: 'inherit' });
+    return 'installed';
+  } catch {
+    return 'failed';
+  }
+}
+```
+
+### Paso 3: Exportar las funciones nuevas
+
+Encontrá el `module.exports` actual y agregá las dos funciones nuevas:
+
+```js
+module.exports = {
+  // ... exports existentes ...
+  detectPackageManager,
+  installSelfAsDevDep,
+};
+```
+
+---
+
+## Parte B — `src/create-quiver/index.js`
+
+### Paso 1: Importar `installSelfAsDevDep`
+
+En la línea 10 donde se importa `runInitDocs`, extender el destructuring para incluir la función nueva:
+
+```js
+// Antes (aproximado):
+const { runInitDocs } = require('./lib/init-docs');
+
+// Después:
+const { runInitDocs, installSelfAsDevDep } = require('./lib/init-docs');
+```
+
+### Paso 2: Agregar `--skip-install` al parser de args
+
+Dentro de la función `parseArgs`, en el bloque donde se manejan los flags (el loop que analiza `arg`), agregar el caso nuevo junto a los otros flags booleanos (`--yes`, etc.):
+
+```js
+if (arg === '--skip-install') {
+  result.skipInstall = true;
+  continue;
+}
+```
+
+### Paso 3: Llamar a `installSelfAsDevDep` en el flujo de init
+
+El flujo init en index.js (cerca de la línea 1416) actualmente es:
+
+```js
+runInitDocs(targetDir, projectName);
+console.log(`Installed Quiver into ${targetDir}`);
+printInitNextSteps(targetDir, projectName);
+```
+
+Reemplazarlo por:
+
+```js
+runInitDocs(targetDir, projectName);
+
+if (!args.skipInstall) {
+  const installResult = installSelfAsDevDep(targetDir, CLI_VERSION);
+  if (installResult === 'installed') {
+    console.log(`Added create-quiver@${CLI_VERSION} as dev dependency`);
+  } else if (installResult === 'failed') {
+    console.warn(`Warning: could not install create-quiver automatically. Run: npm install -D create-quiver@${CLI_VERSION}`);
+  }
+}
+
+console.log(`Installed Quiver into ${targetDir}`);
+printInitNextSteps(targetDir, projectName);
+```
+
+Nota: `CLI_VERSION` ya existe en `index.js` — no lo reimportes.
+
+### Paso 4: Llamar a `installSelfAsDevDep` en el flujo de migrate
+
+Buscá el flujo de migrate en index.js (buscar `runInitDocs` con `migrateMode: true` o similar). Aplicar el mismo patrón después del call de init/migrate.
+
+---
+
+## Parte C — `tests/lib/init-docs.test.js` (archivo nuevo)
+
+Crear este archivo con el patrón del repo (`node:test`, `node:assert/strict`):
+
+```js
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const test = require('node:test');
+
+const { detectPackageManager, installSelfAsDevDep } = require('../../src/create-quiver/lib/init-docs');
+
+function makeTmpDir() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'quiver-init-test-'));
+  return { dir, cleanup: () => fs.rmSync(dir, { recursive: true, force: true }) };
+}
+
+test('detectPackageManager returns npm when no lockfile exists', () => {
+  const { dir, cleanup } = makeTmpDir();
+  try {
+    assert.equal(detectPackageManager(dir), 'npm');
+  } finally {
+    cleanup();
+  }
+});
+
+test('detectPackageManager returns yarn when yarn.lock exists', () => {
+  const { dir, cleanup } = makeTmpDir();
+  try {
+    fs.writeFileSync(path.join(dir, 'yarn.lock'), '');
+    assert.equal(detectPackageManager(dir), 'yarn');
+  } finally {
+    cleanup();
+  }
+});
+
+test('detectPackageManager returns pnpm when pnpm-lock.yaml exists', () => {
+  const { dir, cleanup } = makeTmpDir();
+  try {
+    fs.writeFileSync(path.join(dir, 'pnpm-lock.yaml'), '');
+    assert.equal(detectPackageManager(dir), 'pnpm');
+  } finally {
+    cleanup();
+  }
+});
+
+test('detectPackageManager returns bun when bun.lockb exists', () => {
+  const { dir, cleanup } = makeTmpDir();
+  try {
+    fs.writeFileSync(path.join(dir, 'bun.lockb'), '');
+    assert.equal(detectPackageManager(dir), 'bun');
+  } finally {
+    cleanup();
+  }
+});
+
+test('installSelfAsDevDep returns skipped-no-package-json when no package.json', () => {
+  const { dir, cleanup } = makeTmpDir();
+  try {
+    const result = installSelfAsDevDep(dir, '0.8.0');
+    assert.equal(result, 'skipped-no-package-json');
+  } finally {
+    cleanup();
+  }
+});
+
+test('installSelfAsDevDep returns skipped-already-present when create-quiver in devDeps', () => {
+  const { dir, cleanup } = makeTmpDir();
+  try {
+    fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({
+      name: 'test',
+      devDependencies: { 'create-quiver': '^0.7.0' },
+    }));
+    const result = installSelfAsDevDep(dir, '0.8.0');
+    assert.equal(result, 'skipped-already-present');
+  } finally {
+    cleanup();
+  }
+});
+
+test('installSelfAsDevDep returns failed when install command fails', () => {
+  const { dir, cleanup } = makeTmpDir();
+  try {
+    fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: 'test' }));
+    // Force failure: set PATH to empty so no package manager can be found
+    const original = process.env.PATH;
+    process.env.PATH = '';
+    const result = installSelfAsDevDep(dir, '0.8.0');
+    process.env.PATH = original;
+    assert.equal(result, 'failed');
+  } finally {
+    cleanup();
+  }
+});
+```
+
+---
+
+## Verificaciones
+
+```bash
+# Tests
+node --test tests/**/*.test.js
+
+# Smoke: --skip-install no instala
+mkdir -p /tmp/quiver-skip-test && echo '{"name":"test","scripts":{}}' > /tmp/quiver-skip-test/package.json
+node bin/create-quiver.js --skip-install --name test --dir /tmp/quiver-skip-test
+ls /tmp/quiver-skip-test/node_modules/create-quiver 2>/dev/null && echo "FAIL: se instaló igual" || echo "OK: no instaló"
+
+# Smoke: sin --skip-install sí instala (requiere red)
+mkdir -p /tmp/quiver-install-test && echo '{"name":"test","scripts":{}}' > /tmp/quiver-install-test/package.json
+node bin/create-quiver.js --name test --dir /tmp/quiver-install-test
+ls /tmp/quiver-install-test/node_modules/create-quiver && echo "OK: instalado" || echo "FAIL"
+```
+
+---
+
+## Restricciones
+
+- No toques `mergePackageJson` — la lógica de install va en `installSelfAsDevDep`, no en el merge de package.json
+- No hagas `npm install` general — solo `npm install -D create-quiver@VERSION`
+- No elimines ni renombres ningún export existente de `init-docs.js`
+- No agregues dependencias externas — solo `child_process` (built-in de Node)
+- Un solo commit con los tres archivos
+
+## Mensaje de commit sugerido
+
+```
+feat(QUIVER-01): auto-install create-quiver as dev dependency after init
+
+After init or migrate, detect the target project's package manager
+(yarn/pnpm/bun/npm) and install create-quiver as a dev dependency.
+Skippable with --skip-install for CI environments.
+Resolves the npx cache issue: subsequent quiver commands in the project
+resolve to the local version without requiring @version suffix.
+```