create-quiver 0.15.0 → 0.15.2

package/.github/workflows/ci.yml

@@ -43,6 +43,9 @@ jobs:
         with:
           node-version: 22
 
+      - name: Install dependencies
+        run: npm ci
+
       - name: Run cross-platform smoke
         run: node scripts/ci/smoke-cross-platform.js
 

package/CHANGELOG.md

@@ -6,6 +6,9 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 
+- Implemented v31 AI model catalog and guided agent setup under `specs/quiver-v31-ai-model-catalog-agent-selection/`.
+- Local known-model catalog for Codex, Claude, and Gemini, with role metadata, alias normalization, and `ai models list`.
+- Guided provider/model selection for `ai agent set <role>`, plus `ai agent doctor` and `ai agent repair --dry-run` for legacy or invalid profiles.
 - Implemented v30 interactive CLI UX and agent selection under `specs/quiver-v30-interactive-cli-ux-agent-selection/`.
 - Multiple named agent profiles for Planner, Executor, Reviewer, and Doctor, including display names, defaults, selectors, and model labels.
 - Visible progress output for planner, reviewer, executor, execution-plan, and PR flows in human TTY mode.
@@ -14,6 +17,9 @@ All notable changes to this project will be documented in this file.
 
 ### Changed
 
+- Agent profiles now distinguish the technical `model` id passed to provider CLIs from the human `displayName` shown in Quiver output.
+- Live AI commands now normalize safe CLI model aliases, block persisted display aliases before provider execution, and surface invalid-model provider failures more clearly.
+- Public docs, generated templates, CLI help, and smoke checks now describe model catalog entries as known by Quiver, not guaranteed account availability.
 - Provider model selection now affects real provider invocations when supported, and blocks safely when a selected model cannot be applied.
 - CLI output now follows the shared Quiver palette and hierarchy while keeping `--json`, CI, no-TTY, and `--no-color` output clean.
 - Command docs now cover human-vs-machine output, selectors, Doctor output, and cross-platform usage.

package/README.md

@@ -16,6 +16,7 @@
 
 <p align="center">
   <a href="#primeros-pasos">Primeros pasos</a> ·
+  <a href="./docs/getting-started/installation.md">Instalación</a> ·
   <a href="./docs/workflows/existing-project.md">Proyecto existente</a> ·
   <a href="./docs/workflows/full-ai-spec-to-pr.md">Flujo completo</a> ·
   <a href="./docs/reference/commands.md">Comandos</a> ·
@@ -124,6 +125,25 @@ La inicialización crea un contrato visible para humanos y agentes, más estado
 
 Las specs se crean después, cuando los criterios de aceptación y el plan técnico ya fueron aprobados.
 
+## Uso con npx vs instalación local
+
+El uso recomendado es ejecutar Quiver con `npx`:
+
+```bash
+npx --yes create-quiver@latest --help
+```
+
+Cuando usás `npx`, npm descarga y ejecuta el CLI desde su caché. Por eso Quiver puede funcionar aunque no aparezca dentro de `node_modules` del proyecto. Es esperado: `create-quiver` actúa como una herramienta de bootstrap y workflow, no como una dependencia runtime de tu app.
+
+Si tu equipo quiere fijar una versión dentro del proyecto, podés instalarlo como dependencia de desarrollo:
+
+```bash
+npm install --save-dev create-quiver
+npx create-quiver --help
+```
+
+La guía completa está en [Instalación y uso con npx](./docs/getting-started/installation.md).
+
 ## Elegí tu sistema operativo
 
 Empezá por acá si estás configurando Quiver por primera vez en una máquina:
@@ -157,9 +177,15 @@ Usá la guía que corresponda al estado de tu proyecto:
 | `npx --yes create-quiver@latest flow` | Indica el próximo paso seguro. |
 | `npx --yes create-quiver@latest ai prepare-context --dry-run` | Previsualiza contexto de onboarding para IA sin tocar código de producto. |
 | `npx --yes create-quiver@latest ai prepare-context --with-planner --dry-run` | Previsualiza una propuesta de contexto generada por el planner. |
+| `npx --yes create-quiver@latest ai models list` | Lista proveedores y modelos conocidos por Quiver para configurar agentes. |
+| `npx --yes create-quiver@latest ai agent set planner --provider codex --model gpt-5.5 --dry-run` | Previsualiza un perfil de planner sin guardar credenciales ni escribir archivos. |
+| `npx --yes create-quiver@latest ai agent doctor` | Diagnostica perfiles de agentes existentes. |
+| `npx --yes create-quiver@latest ai agent repair --dry-run` | Previsualiza reparaciones seguras para perfiles heredados o mal configurados. |
 | `npx --yes create-quiver@latest ai plan --phase acceptance` | Genera un borrador de criterios de aceptación. |
+| `npx --yes create-quiver@latest ai approve --phase acceptance` | En TTY lista drafts y recomienda la versión current/latest aprobable. |
 | `npx --yes create-quiver@latest ai plan --phase technical-plan` | Genera un borrador de plan técnico. |
 | `npx --yes create-quiver@latest ai review-plan` | Revisa el plan técnico antes de aprobarlo. |
+| `npx --yes create-quiver@latest ai approve --phase technical-plan` | En TTY muestra drafts con datos de review; en CI usá `--version <n>`. |
 | `npx --yes create-quiver@latest spec create` | Crea spec, slices, briefs, plan de ejecución y cuerpo del PR. |
 | `npx --yes create-quiver@latest spec create --interactive` | Guía la selección de metodología, input aprobado y revisión antes de escribir la spec. |
 | `npx --yes create-quiver@latest spec start specs/<spec>` | Crea o reutiliza el worktree de una spec. |
@@ -218,6 +244,13 @@ Quiver puede trabajar con CLIs locales de proveedores como:
 
 Las credenciales las manejan esos CLIs. Quiver no guarda API keys en los perfiles de agentes.
 
+Los perfiles de agentes separan dos datos:
+
+- `model`: identificador técnico que Quiver pasa al CLI del proveedor, por ejemplo `gpt-5.5`.
+- `displayName`: nombre humano que Quiver muestra en selectores y reportes, por ejemplo `GPT 5.5`.
+
+`ai models list` muestra modelos conocidos por Quiver. Eso no garantiza que el proveedor o tu cuenta tengan acceso a todos esos modelos. Para revisar configuraciones existentes, usá `ai agent doctor`; para perfiles viejos con alias visuales guardados como modelo técnico, empezá con `ai agent repair --dry-run`.
+
 ## Requisitos
 
 - Node.js y npm.

package/README_FOR_AI.md

@@ -7,6 +7,7 @@ The first AI job in a generated project is context preparation, not product impl
 Important: slice numbering resets inside each spec. `slice-00` is the mandatory documentary foundation for a spec; `slice-01` is the first implementation slice, not a global repo counter.
 The canonical installer entrypoint is `npx create-quiver` run from the target project root.
 Do not recommend global installation; use `npx` or a project-local devDependency when the team needs a pinned version.
+If users ask why Quiver is not in `node_modules`, explain that `npx --yes create-quiver@latest` runs the CLI from npm's execution cache; it appears in `node_modules` only after `npm install --save-dev create-quiver`.
 The package also exposes `quiver` as a binary alias to the same CLI. Treat it as a local installed shortcut, not as a replacement for the bootstrap command `npx create-quiver`.
 The root `README.md` is the public landing/onboarding page: keep it concise, Spanish-first, AI-first, and focused on what Quiver is, what problem it solves, the WDD + SDD flow, core commands, and links to deeper guides. Long step-by-step instructions live in `docs/getting-started/`, `docs/workflows/`, and `docs/reference/commands.md`; do not duplicate every procedural detail in the root README.
 The post-init contract is validated with `npx create-quiver doctor` from the project root. Use `npx create-quiver doctor --fix --dry-run` to preview safe non-destructive repairs, then `npx create-quiver doctor --fix` only after reviewing the plan.
@@ -24,15 +25,21 @@ The v27 spec is implemented under `specs/quiver-v27-reliability-ai-workflow-hard
 The v28 spec is implemented under `specs/quiver-v28-pixel-quiver-feedback-reconciliation/` and shipped in `create-quiver@0.14.0`; it captures the Pixel Quiver follow-up reconciliation with active-slice reconciliation, stale `ai inspect` recovery, structured review closure, stricter technical-plan approval, spec/worktree validation hardening, agent-safe commands, GitHub auth/alias guidance, and package-readiness evidence.
 The v29 spec is implemented under `specs/quiver-v29-planner-prepare-context-cli-ux/` and shipped in `create-quiver@0.14.1`; it adds shared CLI UX primitives, Quiver palette usage, guarded UX flags, planner-assisted `ai prepare-context`, and review/interactive adoption for selected planner/spec/PR commands.
 The v30 spec is implemented under `specs/quiver-v30-interactive-cli-ux-agent-selection/` and is release-ready pending package publication; it adds production-grade interactive CLI UX with visible IA progress, Quiver-branded output, configured Planner/Executor/Reviewer/Doctor selectors, real provider model-selection contracts, Doctor human/JSON parity, guided init/spec-create selectors, and cross-platform release readiness.
+The v31 spec is implemented and release-ready pending PR/package publication under `specs/quiver-v31-ai-model-catalog-agent-selection/`; slice-00 through slice-07 are completed. Implemented scope includes the local AI model catalog, alias normalization, guided provider/model selection for `ai agent set <role>`, `ai agent doctor`, `ai agent repair --dry-run`, shared live-command model preflight, clearer provider errors for invalid model ids, `ai models list`, aligned README/reference/generated-template guidance, and final smoke/package readiness.
+The v32 documentation spec is implemented under `specs/quiver-v32-npx-installation-guidance/`; it clarifies why `npx --yes create-quiver@latest` does not install Quiver into project `node_modules`, when to install `create-quiver` as a `devDependency`, and where users should look when troubleshooting that behavior.
 Guided AI workflow behavior is available: prepare, approvals, production-readiness plan review, spec worktrees, executor commits, execution waves, PR creation, spec close, and package safety.
 Generated projects also get `quiver:*` npm scripts that call the Node CLI directly; prefer those for repeatable project workflows, including `quiver:flow` for the read-only guided entrypoint, `quiver:plan` for sequential planning, `quiver:graph` for parallel-level inspection, `quiver:next` for the next ready slice, `quiver:evidence` for local command evidence, `quiver:spec:create` for real spec generation, `quiver:spec:validate` for full spec validation, and the AI family `quiver:ai:agent`, `quiver:ai:inspect`, `quiver:ai:export`, `quiver:ai:specs`, `quiver:ai:slices`, `quiver:ai:trace`, `quiver:ai:onboard`, `quiver:ai:prepare-context`, `quiver:ai:plan`, `quiver:ai:review-plan`, `quiver:ai:approve`, `quiver:ai:prompt-slice`, `quiver:ai:execute-slice`, `quiver:ai:execute-plan`, `quiver:ai:pr`, and `quiver:ai:doctor`. Use `quiver:graph --format mermaid` for PR-ready Markdown or `quiver:graph --format dot` for Graphviz source.
 `quiver:ai:execute-plan` supports `--mode manual` for paste-ready executor prompts and `--mode delegated` for temporary worktrees on parallel-ready waves; unsafe waves fall back to sequential execution.
-Agent profiles live in `.quiver/agents/profiles.json`; they store role, provider, model label, context label, display label, profile id, and default profile only. Do not store API keys, tokens, or credentials there.
+Agent profiles live in `.quiver/agents/profiles.json`; they store role, provider, technical `model`, human `displayName`, context label, profile id, and default profile only. Do not store API keys, tokens, or credentials there.
+`model` is the technical id passed to the provider CLI, for example `gpt-5.5`. `displayName` is the human label shown in Quiver output, for example `GPT 5.5`.
+`npx create-quiver ai models list` shows models known by Quiver, not models guaranteed available in the user's provider account. Use `npx create-quiver ai agent doctor` to diagnose profile issues and `npx create-quiver ai agent repair --dry-run` to preview safe legacy-profile alias normalization before writing anything.
 Provider/model selection must be honest: dry-runs can preview a selected model without provider auth, but live IA execution must pass the selected model through the provider adapter or fail with actionable guidance instead of silently ignoring it.
 Planner-oriented live IA commands must show visible TTY progress with the selected profile/model name, completed preparation checks, and a provider-running spinner. `--dry-run`, `--print-prompt`, CI, JSON, and non-TTY output must remain clean and automation-safe.
+This progress standard applies to `ai plan`, `ai revise`, `ai review-plan`, and `ai repair-plan`; do not add fake loaders to dry-runs or prompt-only output.
 Executor and PR live commands follow the same standard: show truthful TTY progress for slice execution, validation, commits, GitHub preflight, and PR creation while preserving scope gates, provider errors, `gh` errors, and clean machine output.
-Planner drafts are versioned under `.quiver/approvals/<phase>/drafts/`; review the technical-plan draft with `npx create-quiver ai review-plan --dry-run` before approving it, then approve a concrete version with `npx create-quiver ai approve --phase <phase> --version <n>` when reviewing iterations.
+Planner drafts are versioned under `.quiver/approvals/<phase>/drafts/`; review the technical-plan draft with `npx create-quiver ai review-plan --dry-run` before approving it. In TTY, `npx create-quiver ai approve --phase <phase>` can list saved drafts and recommend the current/latest eligible version; in CI/no-TTY, pass `--version <n>` explicitly.
 `ai review-plan` stores structured closure metadata under `.quiver/approvals/plan-review/meta.json`: `approval_recommendation` is `approve`, `approve-with-risk`, or `revise`; required fixes block technical-plan approval, while optional hardening does not.
+Use `npx create-quiver ai approvals`, `npx create-quiver flow`, `npx create-quiver ai status`, and `npx create-quiver ai resume` to read the same approval-candidate guidance before choosing the next command. `spec create --interactive` must show the reviewed approved technical-plan input, approved version, and review summary before writing.
 AI lifecycle runs are persisted under `.quiver/runs/<run-id>/`; use `npx create-quiver ai run create --input <requirements.md>` to start one explicitly, `npx create-quiver ai status` to inspect it, `npx create-quiver ai resume` to continue from the last valid phase without relying on chat memory, and `npx create-quiver ai export --format json|markdown` when another agent, PR, or dashboard needs the current specs/slices/runs state.
 Use `npx create-quiver ai active-slice reconcile --dry-run` when `docs/ai/ACTIVE_SLICE.md`, `ACTIVE_SLICES.md`, worktrees, or `ai inspect` appear out of sync. The command is dry-run-first and reports preserve, close, replace, or blocked decisions without writing files.
 When generating commands for another AI agent, prefer non-interactive package-pinned examples such as `npx --yes create-quiver@<version> ai prompt-slice --slice <slice.json> --dry-run`.
@@ -43,7 +50,7 @@ The project map is the single source of truth for stack, package manager, comman
 The raw analyzer output is internal machinery at `.quiver/scans/PROJECT_SCAN.json`; read it only when the visible map is not enough.
 `npx create-quiver analyze --dry-run` must remain read-only and only preview the scan/project-map/context writes. `npx create-quiver flow` reports the context source/freshness and the package-manager-aware generated script command so agents can see whether the project map is current, stale, partial, legacy, invalid, or missing.
 `npx create-quiver ai prepare-context --dry-run` remains the deterministic default and must not execute provider CLIs. `npx create-quiver ai prepare-context --with-planner --dry-run` previews planner-assisted context preparation. `--with-planner --print-prompt` prints the exact prompt without provider auth; live planner writes should use `--review` and/or `--interactive` when the human wants review before docs-only writes.
-`npx create-quiver ai agent set <role> --provider <provider> --model "<label>" --dry-run` must preview `.quiver/agents/profiles.json` changes without writing. Use it before saving planner/executor/reviewer/doctor profiles.
+`npx create-quiver ai agent set <role> --provider <provider> --model <model-id> --dry-run` must preview `.quiver/agents/profiles.json` changes without writing. In TTY mode, `npx create-quiver ai agent set <role>` can guide provider/model selection; in CI/no-TTY, require explicit `--provider` and `--model`. Use dry-run before saving planner/executor/reviewer/doctor profiles.
 GitHub PR diagnostics must stay cross-platform: auth failures should point to likely account, scope, and SSH alias issues; path examples with spaces must be copy-safe for macOS/Linux, Windows PowerShell, Git Bash, and WSL.
 CLI UX standard lives in `docs/CLI_UX_GUIDE.md`. Supported Quiver colors are `#86C8F2`, `#6BADEB`, `#7F9EE8`, `#9B82E6`, and `#D56AB0`; output must respect `--no-color`, `NO_COLOR`, CI, and no-TTY environments.
 UX flags are intentionally limited: `ai prepare-context`, `ai plan`, and `spec create` support `--with-planner`, `--interactive`, and `--review`; `ai pr` supports `--interactive` and `--review` but rejects `--with-planner`; read-only commands such as `flow`, `next`, `graph`, `ai inspect`, `ai export`, `ai specs list`, `ai slices list`, and `ai trace report` reject these UX flags. `--json` must reject `--interactive` and `--review` before writing human output.
@@ -161,12 +168,12 @@ After initialization, the user should:
 8. Ask the AI agent to execute `docs/AI_ONBOARDING_PROMPT.md`
 9. Review context docs before creating the first implementation slice
 10. Open and merge the documentation PR that establishes the workflow files
-11. Preview reusable provider choices with `npx create-quiver ai agent set <role> --provider <provider> --model "<label>" --dry-run`, then save planner/executor/doctor profiles without `--dry-run` after review
+11. Inspect reusable provider choices with `npx create-quiver ai models list`, diagnose existing profiles with `npx create-quiver ai agent doctor`, preview reusable provider choices with `npx create-quiver ai agent set <role> --provider <provider> --model <model-id> --dry-run`, then save planner/executor/doctor profiles without `--dry-run` after review
 12. Use `npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run`; use `--print-prompt` when you need the exact prompt without provider auth and `--review --interactive` when the human should edit or confirm before saving
-13. If the human asks for changes, create a new draft with `npx create-quiver ai revise --phase acceptance --input feedback.md --dry-run`; after human approval, save the selected current draft with `npx create-quiver ai approve --phase acceptance --version <n>`
+13. If the human asks for changes, create a new draft with `npx create-quiver ai revise --phase acceptance --input feedback.md --dry-run`; after human approval, run `npx create-quiver ai approve --phase acceptance` in TTY or `--version <n>` in CI/no-TTY
 14. Use `npx create-quiver ai plan --phase technical-plan --dry-run`
 15. Review the technical plan with `npx create-quiver ai review-plan --dry-run`, inspect exact prompt with `--print-prompt` if needed, then run it without `--dry-run` when ready
-16. After human approval, save the reviewed plan version with `npx create-quiver ai approve --phase technical-plan --version <n>`
+16. After human approval, save the reviewed plan version with `npx create-quiver ai approve --phase technical-plan` in TTY or `--version <n>` in CI/no-TTY; if review recommends `revise`, run `ai revise --phase technical-plan --input feedback.md --dry-run` first
 17. Use `npx create-quiver spec create --dry-run` to preview the real spec, slices, handoffs, execution plan, and PR body; use `--review --interactive` when the human should inspect the package before writing
 18. Run `npx create-quiver spec start specs/<spec-slug> --dry-run` to inspect the planned worktree, then run without `--dry-run` to create or reuse it
 19. Run `npx create-quiver plan` or `npm run quiver:plan`

package/ROADMAP.md

@@ -89,6 +89,10 @@
 
 - **v30** — Interactive CLI UX and agent selection: visible progress for long-running IA commands, selected Planner/Executor/Reviewer/Doctor display names, profile/spec/slice/methodology selectors, provider model-selection correctness, Doctor human/JSON parity, cross-platform automation safety, and release-readiness evidence live in `specs/quiver-v30-interactive-cli-ux-agent-selection/`.
 
+## v0.16 — AI Model Catalog and Guided Agent Setup (release-ready, pending package publication)
+
+- **v31** — AI model catalog and guided agent setup: local known-model catalog for Codex, Claude, and Gemini, technical model id vs display name separation, provider/model selectors, alias normalization, agent profile doctor/repair dry-run, shared live-command model preflight, better provider errors, model listing, docs/templates, tests, smokes, and package readiness live in `specs/quiver-v31-ai-model-catalog-agent-selection/`.
+
 ## Post-Checkpoint Plan (do not execute before validating v14)
 
 > This section now records the follow-up line from the v14-era plan.
@@ -108,6 +112,7 @@
 - **v28 — Pixel Quiver Feedback Reconciliation** (shipped in `0.14.0`): active-slice reconciliation, stale inspect recovery, structured review closure, validation/worktree hardening, agent-safe commands, GitHub auth guidance, and release-readiness evidence live in `specs/quiver-v28-pixel-quiver-feedback-reconciliation/`.
 - **v29 — Planner Context and CLI UX Standard** (shipped in `0.14.1`): planner-assisted `ai prepare-context`, CLI UX primitives, guarded UX flags, human review/interactive flows, and final docs/smoke readiness live in `specs/quiver-v29-planner-prepare-context-cli-ux/`.
 - **v30 — Interactive CLI UX and Agent Selection** (release-ready, pending package publication): visible IA progress, Quiver-branded output, profile/spec/slice selectors, provider model-selection correctness, Doctor human/JSON parity, and cross-platform release readiness live in `specs/quiver-v30-interactive-cli-ux-agent-selection/`.
+- **v31 — AI Model Catalog and Guided Agent Setup** (release-ready, pending package publication): known-model catalog, provider/model selectors, alias normalization, agent profile doctor/repair, shared model preflight, better provider errors, docs/templates, smokes, and release readiness live in `specs/quiver-v31-ai-model-catalog-agent-selection/`.
 
 The shipped v20/v21/v22/v23 work is no longer pending. The older context-diagnostics and slice-archaeology ideas remain deferred until real demand justifies them.
 

package/docs/AI_CONTEXT.md.template

@@ -27,6 +27,9 @@ This file is the main context pack after `AGENTS.md` and `docs/PROJECT_MAP.md`.
 - `docs/STATUS.md` tracks progress, blockers, and the current slice.
 - `npx create-quiver ai prepare-context --dry-run` previews docs-only context drafts before writing.
 - `npx create-quiver ai prepare-context --with-planner --dry-run` previews an optional planner-generated context proposal. Use `--print-prompt` to run the prompt elsewhere, `--review` to inspect the proposal, and `--interactive` to confirm before writing.
+- `npx create-quiver ai models list` shows provider/model ids known by Quiver. It is a local catalog, not a guarantee of account-level access.
+- Agent profiles live in `.quiver/agents/profiles.json` without credentials. `model` is the technical id passed to the provider CLI; `displayName` is the human label shown in selectors and reports.
+- `npx create-quiver ai agent doctor` diagnoses profile issues. `npx create-quiver ai agent repair --dry-run` previews safe legacy-profile repairs before any write mode exists.
 
 ## Critical Rules
 
@@ -39,6 +42,7 @@ This file is the main context pack after `AGENTS.md` and `docs/PROJECT_MAP.md`.
 - If a command or path is ambiguous, prefer the local project root and the generated docs.
 - Context preparation must stay in docs/context files and should use TODO, Assumption, or Pending confirmation markers for uncertain statements.
 - Planner-assisted context proposals must remain docs-only. Do not accept product-code, dependency, build, runtime, lockfile, generated-output, absolute-path, or traversal writes.
+- Do not treat model names from chat or screenshots as technical ids until `ai models list` or the provider docs confirms the spelling. Use `ai agent doctor` when a profile looks suspicious.
 
 ## What To Update After A Slice
 

package/docs/AI_ONBOARDING_PROMPT.md.template

@@ -17,6 +17,8 @@ Actúa como asistente de onboarding de IA para este proyecto. Tu objetivo es com
    - Lee `docs/AI_CONTEXT.md`, `docs/AI_ONBOARDING_PROMPT.md`, `docs/WORKFLOW.md`, `docs/STATUS.md` y `docs/DECISIONS.md` solo cuando existan y sean relevantes para la tarea.
    - Si usás `npx create-quiver ai prepare-context`, empezá con `--dry-run`, revisá los borradores propuestos antes de escribir y mantené las escrituras limitadas a docs/context.
    - Usá `--with-planner` solo cuando el humano quiera una propuesta generada por un planner IA; combiná `--review` y `--interactive` antes de aplicar escrituras.
+   - Si la tarea usa agentes IA configurados por Quiver, revisá `npx create-quiver ai models list`, `npx create-quiver ai agent list` y `npx create-quiver ai agent doctor` antes de ejecutar proveedores.
+   - No asumas que un modelo listado por `ai models list` está disponible en la cuenta del proveedor. El catálogo local solo indica modelos conocidos por Quiver.
    - Lee specs, slices o handoffs solo si la tarea actual lo requiere.
    - No leas todo `docs/` por defecto.
    - Si un documento referenciado no existe, repórtalo como deuda documental.
@@ -77,6 +79,11 @@ npm run quiver:ai:prepare-context -- --dry-run
 npm run quiver:ai:prepare-context -- --with-planner --dry-run
 npm run quiver:ai:prepare-context -- --with-planner --print-prompt
 npm run quiver:ai:prepare-context -- --with-planner --review --interactive
+npx create-quiver ai models list
+npx create-quiver ai models list --provider codex
+npx create-quiver ai agent doctor
+npx create-quiver ai agent repair --dry-run
+npm run quiver:ai:agent -- set planner --provider codex --model gpt-5.5 --dry-run
 npm run quiver:ai:onboard -- --dry-run
 npm run quiver:ai:inspect
 npm run quiver:ai:export -- --format json
@@ -113,6 +120,7 @@ npm run quiver:spec:close -- specs/{{PROJECT_SLUG}} --dry-run
 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.
 9. Cuando prepares contexto, marca las incertidumbres como `TODO`, `Assumption` o `Pending confirmation` y evita tocar código de producto.
+10. Cuando configures perfiles de agentes, usa `model` para el identificador técnico que se pasa al proveedor y `displayName` para el nombre humano mostrado por Quiver.
 
 ## Validación
 

package/docs/CLI_UX_GUIDE.md

@@ -53,6 +53,11 @@ Reglas:
 | `ai pr` | no | si | si | Review edita `pr.md`; interactive confirma `gh pr create`. |
 | `ai execute-slice` | no | si | no | Interactive puede seleccionar un slice listo y un executor configurado. |
 | `ai execute-plan` | no | si | no | Interactive queda reservado para estrategia/seleccion; JSON sigue limpio. |
+| `ai agent set` | no | si | no | En TTY puede guiar proveedor/modelo; en CI/no-TTY requiere `--provider` y `--model`. |
+| `ai approve` | no | no | no | Si falta `--version` y hay TTY, abre selector de drafts; en CI/no-TTY exige `--version <n>`. |
+| `ai agent doctor` | no | no | no | Diagnostica perfiles sin escribir; `--json` usa el mismo modelo de hallazgos. |
+| `ai agent repair` | no | no | no | Por ahora solo `--dry-run`; muestra before/after sin escribir. |
+| `ai models list` | no | no | no | Lista el catalogo local conocido por Quiver; no valida acceso de cuenta. |
 | `doctor` | no | no | no | Renderiza `Quiver Doctor`, `Checks` y `Suggested fixes`; `--json` usa el mismo modelo de hallazgos. |
 | `flow`, `next`, `graph` | no | no | no | Lectura/inspeccion; no deben exponer flags decorativas. |
 | `ai inspect`, `ai export`, `ai specs list`, `ai slices list`, `ai trace report` | no | no | no | Superficies read-only o machine-readable. |
@@ -78,10 +83,21 @@ El planner debe devolver una propuesta validable. Quiver solo acepta cambios en
 
 ## Seleccion de agentes, proveedores y modelos
 
-Los perfiles de agente son configuracion de DX, no almacenamiento de credenciales. Deben guardar solo rol, proveedor, etiqueta de modelo, contexto, nombre visible y perfil por defecto.
+Los perfiles de agente son configuracion de DX, no almacenamiento de credenciales. Deben guardar solo rol, proveedor, identificador tecnico de modelo, nombre visible, contexto, profile id y perfil por defecto.
+
+Contrato de datos:
+
+- `model` es el identificador tecnico que Quiver pasa al CLI del proveedor, por ejemplo `gpt-5.5`.
+- `displayName` es el nombre humano que Quiver muestra en selectores, loaders y reportes, por ejemplo `GPT 5.5`.
+- `ai models list` muestra modelos conocidos por Quiver. Eso no significa que el proveedor o la cuenta del usuario tengan acceso real a todos ellos.
+- Un modelo custom esta permitido, pero debe quedar marcado como custom/no validado hasta que una ejecucion real lo pruebe.
 
 Reglas:
 
+- En TTY, `ai agent set <role>` puede abrir selectores de proveedor y modelo cuando faltan flags.
+- En no-TTY/CI, `ai agent set <role>` debe exigir `--provider` y `--model`; no debe quedarse esperando input.
+- `ai agent doctor` debe identificar perfiles heredados con alias visuales guardados en `model`.
+- `ai agent repair --dry-run` debe mostrar cambios before/after y no escribir archivos.
 - Si un comando usa un perfil con modelo, el dry-run debe mostrar proveedor, modelo, comando y si el adapter puede aplicar ese modelo.
 - En ejecucion real, Quiver debe pasar el modelo al CLI del proveedor cuando el adapter lo soporta.
 - Si un adapter no puede aplicar el modelo seleccionado, la ejecucion real debe bloquearse con un proximo paso claro.
@@ -101,11 +117,22 @@ Reglas:
 `spec create --interactive` debe:
 
 - seleccionar la metodologia real soportada: `WDD + SDD`;
-- mostrar el input aprobado que se usara para generar la spec;
+- mostrar el input aprobado que se usara para generar la spec, la version aprobada y el resumen de review;
 - permitir elegir confirmacion directa o `--review`;
 - mostrar resumen antes de escribir;
 - bloquearse en no-TTY/CI/JSON con mensaje accionable en lugar de abrir prompts.
 
+## Aprobaciones planner
+
+`ai approve` conserva el modo script con `--version <n>`, pero en una terminal humana puede guiar la eleccion cuando falta `--version`:
+
+- `ai approve --phase acceptance` lista drafts versionados y recomienda el current/latest elegible.
+- `ai approve --phase technical-plan` agrega estado de `plan-review`, recomendacion, fixes requeridos, hardening opcional y riesgos.
+- CI/no-TTY nunca espera input; falla temprano con el comando explicito `--version <n>`.
+- Las versiones historicas pueden mostrarse como contexto, pero solo el draft current/latest es aprobable.
+- Los snippets o previews de candidatos deben estar truncados y redactados.
+- `ai approvals`, `flow`, `ai status`, `ai resume` y `spec create --interactive` deben usar el mismo modelo de candidatos para no contradecir el proximo paso.
+
 ## Loaders y prompts
 
 Usar loaders solo cuando aportan claridad:
@@ -128,6 +155,8 @@ Usar prompts interactivos cuando hay una decision humana real:
 
 No usar prompts para informacion que ya se pueda expresar con flags.
 
+Los comandos provider-backed `ai plan`, `ai revise`, `ai review-plan` y `ai repair-plan` deben seguir el mismo patron de progreso en TTY: checks de preparacion reales y spinner solo durante ejecucion del proveedor. `--dry-run`, `--print-prompt`, CI, no-TTY y JSON no deben mostrar loaders falsos.
+
 ## Salida de Doctor
 
 `doctor` debe mostrar una jerarquia estable para humanos:

package/docs/COMMANDS.md.template

@@ -44,8 +44,13 @@ This document is the canonical command reference for the orchestration roadmap.
 | `quiver:plan -- --include-completed` | Shows completed slices for audit/demo history | macOS, Linux, Windows | v0.11 | `npm run quiver:plan -- --include-completed --spec <spec>` |
 | `quiver:graph -- --include-completed` | Includes completed slices in the dependency graph history view | macOS, Linux, Windows | v0.11 | `npm run quiver:graph -- --include-completed --spec <spec>` |
 | `quiver:next -- --include-completed` | Keeps actionable next-slice output and appends completed history | macOS, Linux, Windows | v0.11 | `npm run quiver:next -- --include-completed --spec <spec>` |
-| `quiver:ai:agent -- set <role> ... --dry-run` | Previews planner/executor/reviewer/doctor provider profile writes without creating `.quiver/agents/profiles.json` | macOS, Linux, Windows | v0.13 | `npm run quiver:ai:agent -- set planner --provider codex --model "planner-model" --dry-run` |
-| `quiver:ai:agent` | Stores reusable planner/executor/reviewer/doctor provider profiles without secrets | macOS, Linux, Windows | v0.11 | `npm run quiver:ai:agent -- set planner --provider codex --model "planner-model"` |
+| `npx create-quiver ai models list` | Lists provider/model ids known by Quiver without claiming account availability | macOS, Linux, Windows | next | `npx create-quiver ai models list --provider codex` |
+| `npx create-quiver ai models list --json` | Emits the local known-model catalog as clean machine-readable JSON | macOS, Linux, Windows | next | `npx create-quiver ai models list --json` |
+| `quiver:ai:agent -- set <role>` | Guides provider/model selection in an interactive TTY without storing credentials | macOS, Linux, Windows | next | `npm run quiver:ai:agent -- set planner` |
+| `quiver:ai:agent -- set <role> ... --dry-run` | Previews planner/executor/reviewer/doctor provider profile writes without creating `.quiver/agents/profiles.json` | macOS, Linux, Windows | v0.13 | `npm run quiver:ai:agent -- set planner --provider codex --model gpt-5.5 --dry-run` |
+| `quiver:ai:agent` | Stores reusable planner/executor/reviewer/doctor provider profiles without secrets | macOS, Linux, Windows | v0.11 | `npm run quiver:ai:agent -- set planner --provider codex --model gpt-5.5` |
+| `quiver:ai:agent -- doctor` | Diagnoses stored agent profiles, legacy display aliases, custom unvalidated models, duplicate labels, and provider CLI readiness | macOS, Linux, Windows | next | `npm run quiver:ai:agent -- doctor` |
+| `quiver:ai:agent -- repair --dry-run` | Previews safe profile repairs, such as normalizing display aliases into technical model ids, without writing files | macOS, Linux, Windows | next | `npm run quiver:ai:agent -- repair --dry-run` |
 | `quiver:ai:inspect` | Shows actionable lifecycle state through the generated npm script | macOS, Linux, Windows | v0.13 | `npm run quiver:ai:inspect` |
 | `quiver:ai:export` | Exports lifecycle state as JSON or Markdown through the generated npm script | macOS, Linux, Windows | v0.13 | `npm run quiver:ai:export -- --format json` |
 | `quiver:ai:specs` | Lists specs through the generated npm script | macOS, Linux, Windows | v0.13 | `npm run quiver:ai:specs` |
@@ -98,7 +103,7 @@ This document is the canonical command reference for the orchestration roadmap.
 | `--spec <slug>` | `plan`, `graph`, `spec create` | Restrict output to one spec or override the generated spec slug |
 | `--format <tree\|mermaid\|dot\|json\|markdown>` | `graph`, `ai export` | Select graph or lifecycle export output format |
 | `--provider <codex\|claude\|gemini>` | `ai onboard`, `ai plan`, `ai revise`, `ai review-plan`, `ai execute-slice`, `ai execute-plan` | Select the local AI CLI adapter |
-| `--model <label>` | `ai agent set` | Store a free-form model label in an agent profile; Quiver does not verify model availability |
+| `--model <model-id>` | `ai agent set`, provider-backed AI commands | Store or pass the technical model id. Quiver normalizes known display aliases, but the catalog is known by Quiver and does not guarantee account availability |
 | `--label <label>` | `ai agent set` | Store a display label for the profile |
 | `--dry-run` | init, analyze, migrate, prepare, spec, demo, AI, PR, worktree, and repair commands that support preview | Preview planned actions without writes, provider execution, PR creation, or irreversible changes |
 | `--with-planner` | `ai prepare-context`, `ai plan`, `spec create` | Enable planner-assisted behavior only on commands that explicitly support it |
@@ -125,6 +130,7 @@ This document is the canonical command reference for the orchestration roadmap.
 ## Notes
 
 - Add new rows here only when a command is officially shipped.
+- `npx --yes create-quiver@latest` runs Quiver from npm's execution cache and does not install it into the project `node_modules`. Install `create-quiver` as a `devDependency` only when the team needs a pinned local workflow tool.
 - The `quiver` binary is an alias to the same package CLI after local installation. Keep `npx create-quiver` as the bootstrap command.
 - Keep the table concise and cross-platform.
 - Shared graph library: `src/create-quiver/lib/slice-graph.js`.
@@ -140,11 +146,16 @@ This document is the canonical command reference for the orchestration roadmap.
 - `init --interactive` and `spec create --interactive` are human-only wrappers. They fail in no-TTY/CI/JSON and always keep `WDD + SDD` as the only methodology option.
 - Quiver human output uses the palette `#86C8F2`, `#6BADEB`, `#7F9EE8`, `#9B82E6`, and `#D56AB0`; respect `--no-color`, `NO_COLOR`, CI, and no-TTY environments.
 - `quiver:flow` reports the detected package manager and the matching generated project script, for example `npm run quiver:flow`, `pnpm run quiver:flow`, `yarn run quiver:flow`, or `bun run quiver:flow`.
+- `npx create-quiver ai models list` shows the local catalog of provider/model ids known by Quiver. It does not prove account-level access in Codex, Claude, or Gemini.
+- Agent profiles separate `model` and `displayName`: `model` is the technical id passed to the provider CLI, while `displayName` is the human label used in selectors and reports.
 - `quiver:ai:agent -- set ... --dry-run` previews provider/model profile changes without writing `.quiver/agents/profiles.json`.
-- `quiver:ai:agent` stores provider/model labels under `.quiver/agents/profiles.json`; credentials stay in the provider CLI or OS credential store.
+- `quiver:ai:agent` stores provider/model configuration under `.quiver/agents/profiles.json`; credentials stay in the provider CLI or OS credential store.
+- `quiver:ai:agent -- doctor` diagnoses bad or legacy profiles. Start there when live IA commands fail before provider execution.
+- `quiver:ai:agent -- repair --dry-run` previews safe normalizations such as `model: "GPT 5.5"` to `model: "gpt-5.5"` plus `displayName: "GPT 5.5"`; it does not write files.
 - `quiver:ai:inspect`, `quiver:ai:specs`, `quiver:ai:slices`, and `quiver:ai:trace` are read-only inspection surfaces for humans and agents.
 - `quiver:ai:export -- --format json` is the dashboard/agent-friendly state contract; `--format markdown` is the PR/docs-friendly version.
-- Planner drafts are versioned under `.quiver/approvals/<phase>/drafts/`; use `quiver:ai:review-plan -- --dry-run` before approving a technical-plan draft, then `quiver:ai:approve -- --phase technical-plan --version 1` to approve the reviewed version. Plan reviews store structured recommendations: `approve`, `approve-with-risk`, or `revise`.
+- Planner drafts are versioned under `.quiver/approvals/<phase>/drafts/`; in TTY, `quiver:ai:approve -- --phase <phase>` lists drafts and recommends the current/latest eligible version, while CI/no-TTY must pass `--version <n>`. Use `quiver:ai:review-plan -- --dry-run` before approving a technical-plan draft. Plan reviews store structured recommendations: `approve`, `approve-with-risk`, or `revise`.
+- `quiver:ai:approvals`, `quiver:flow`, `quiver:ai:status`, `quiver:ai:resume`, and `quiver:spec:create -- --interactive` use the same approval-candidate data so next-step guidance stays consistent.
 - `quiver:ai:prompt-slice -- --dry-run` prints a paste-ready manual executor prompt and does not call a provider.
 - For commands pasted into another AI agent, prefer a non-interactive pinned form such as `npx --yes create-quiver@<version> ai prompt-slice --slice specs/<spec>/slices/<slice>/slice.json --dry-run`.
 - `quiver:evidence -- run -- <command>` preserves the wrapped command exit code. Redaction is best effort; avoid commands that intentionally print secrets.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,70 @@
+# Troubleshooting
+
+Usá esta guía cuando una instalación, primer uso o comando de Quiver no se comporta como esperabas.
+
+## Quiver no aparece en node_modules
+
+### Síntoma
+
+Ejecutaste un comando como:
+
+```bash
+npx --yes create-quiver@latest --help
+```
+
+El comando funciona, pero no encontrás `create-quiver` en:
+
+```text
+node_modules/create-quiver
+```
+
+### Explicación
+
+Es esperado. Cuando usás `npx`, npm descarga y ejecuta el paquete desde su caché de ejecución. Eso permite usar Quiver sin modificar el `package.json` ni instalarlo dentro del proyecto.
+
+Quiver funciona como CLI de workflow y bootstrap. No es una dependencia runtime que tu aplicación tenga que importar.
+
+### Qué hacer
+
+Si solo querés usar Quiver, no hace falta hacer nada más:
+
+```bash
+npx --yes create-quiver@latest flow
+```
+
+Si querés fijar una versión en el proyecto, instalalo como dependencia de desarrollo:
+
+```bash
+npm install --save-dev create-quiver
+```
+
+Después de eso sí va a aparecer en `node_modules` y podés usarlo desde scripts del proyecto.
+
+### Ver también
+
+- [Instalación y uso con npx](./getting-started/installation.md)
+- [Referencia de comandos](./reference/commands.md)
+
+## Quiver ejecuta una versión distinta a la esperada
+
+### Síntoma
+
+`npx create-quiver --version` y `npx --yes create-quiver@latest --version` muestran versiones diferentes.
+
+### Explicación
+
+`npx create-quiver` puede resolver una versión local si existe en el proyecto. En cambio, `npx --yes create-quiver@latest` pide explícitamente la última versión publicada en npm.
+
+### Qué hacer
+
+Para probar la última versión publicada:
+
+```bash
+npx --yes create-quiver@latest --version
+```
+
+Para usar la versión fijada por el proyecto:
+
+```bash
+npx create-quiver --version
+```

package/docs/TROUBLESHOOTING.md.template

@@ -5,6 +5,26 @@
 
 Use this guide when a first-run bootstrap or gate check fails. The recovery paths below follow the smoke-tested flows in this repository.
 
+## Quiver Does Not Appear In node_modules
+
+### Symptom
+
+- `npx --yes create-quiver@latest ...` works
+- `node_modules/create-quiver` does not exist
+- The project `package.json` does not list `create-quiver`
+
+### Recovery
+
+1. Treat this as expected when using `npx`; npm runs the CLI from its execution cache.
+2. Keep using `npx --yes create-quiver@latest` when you want the latest published Quiver without adding a project dependency.
+3. Install Quiver only when the team wants a pinned local workflow tool:
+
+```bash
+npm install --save-dev create-quiver
+```
+
+4. After a local install, use `npx create-quiver --help` or project scripts backed by the local `devDependency`.
+
 ## Path Normalization Failure
 
 ### Symptom

package/docs/WORKFLOW.md.template

@@ -35,10 +35,10 @@ Use maps, metadata, diffs, and summaries first. Open full files only when the sm
 1. Run `npx create-quiver flow` when the next safe command is unclear.
 2. Triage the request.
 3. Save reusable planner/executor provider choices with `ai agent set` when the team has preferred local AI CLIs.
-4. Use `ai plan --phase acceptance` to draft criteria, then save the approved version with `ai approve --phase acceptance`.
+4. Use `ai plan --phase acceptance` to draft criteria, then save the approved version with `ai approve --phase acceptance` in TTY or `--version <n>` in CI/no-TTY.
 5. Use `ai plan --phase technical-plan` to draft the plan.
 6. Use `ai review-plan` to review the technical-plan draft for production readiness without changing product code. Treat `approve` and `approve-with-risk` as approvable states; treat `revise` or required fixes as blockers.
-7. Save the reviewed plan version with `ai approve --phase technical-plan --version <n>` only after the review recommendation is approvable.
+7. Save the reviewed plan version with `ai approve --phase technical-plan` in TTY or `--version <n>` in CI/no-TTY only after the review recommendation is approvable.
 8. Use `spec create` to generate the spec, mandatory `slice-00`, implementation slices, handoffs, execution plan, and `pr.md`.
 9. Open and merge the documentation PR or commit that establishes `slice-00` before running implementation slices.
 10. Read the AI context pack, support matrix, and troubleshooting guide before the first slice if the environment is new or uncertain.

package/docs/getting-started/installation.md

@@ -0,0 +1,86 @@
+# Instalación y uso con npx
+
+Esta guía explica por qué Quiver normalmente se ejecuta con `npx`, cuándo aparece en `node_modules` y cuándo conviene instalarlo como dependencia del proyecto.
+
+## Uso recomendado
+
+Para usar la última versión publicada de Quiver, ejecutá:
+
+```bash
+npx --yes create-quiver@latest --help
+```
+
+Qué hace:
+
+- descarga o reutiliza `create-quiver` desde la caché de npm;
+- ejecuta el CLI sin agregarlo al `package.json`;
+- evita instalar una dependencia que la aplicación no necesita para correr.
+
+Este es el modo recomendado para inicializar, analizar, diagnosticar, preparar contexto, crear specs, ejecutar slices y abrir PRs.
+
+## Por qué no aparece en node_modules
+
+Si ejecutás Quiver con:
+
+```bash
+npx --yes create-quiver@latest ...
+```
+
+el paquete no se instala dentro del proyecto. npm lo ejecuta desde su caché temporal o global de ejecución. Por eso no vas a encontrarlo en:
+
+```text
+node_modules/create-quiver
+```
+
+Esto es normal para CLIs de bootstrap como `create-quiver`. Quiver organiza el workflow del proyecto, pero no es una librería que tu app importe en runtime.
+
+## Cuándo instalarlo como devDependency
+
+Instalalo localmente solo si el equipo quiere una versión fijada en el proyecto o scripts reproducibles sin depender de `@latest`:
+
+```bash
+npm install --save-dev create-quiver
+```
+
+Después podés usar:
+
+```bash
+npx create-quiver --help
+```
+
+O agregar scripts al `package.json`, por ejemplo:
+
+```json
+{
+  "scripts": {
+    "quiver:doctor": "create-quiver doctor",
+    "quiver:flow": "create-quiver flow"
+  }
+}
+```
+
+Qué cambia:
+
+- `create-quiver` aparece en `devDependencies`;
+- npm lo instala dentro de `node_modules`;
+- los scripts del proyecto usan la versión fijada por `package-lock.json`.
+
+## Qué opción elegir
+
+| Necesidad | Recomendación |
+|---|---|
+| Probar Quiver rápidamente | `npx --yes create-quiver@latest` |
+| Inicializar un proyecto nuevo | `npx --yes create-quiver@latest init --name "Mi Proyecto"` |
+| Usar siempre la última versión publicada | `npx --yes create-quiver@latest` |
+| Fijar una versión para el equipo | `npm install --save-dev create-quiver` |
+| Evitar dependencia local de workflow | Usar `npx` |
+
+## Qué no hace Quiver
+
+Quiver no se instala globalmente por defecto, no modifica credenciales de npm y no agrega una dependencia runtime a tu app salvo que lo pidas explícitamente con npm.
+
+## Siguiente paso
+
+- [Proyecto nuevo desde cero](../workflows/new-project.md)
+- [Proyecto existente sin Quiver](../workflows/existing-project.md)
+- [Referencia de comandos](../reference/commands.md)