create-quiver 0.15.0 → 0.15.1

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,6 +177,10 @@ 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 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. |
@@ -218,6 +242,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,10 +25,14 @@ 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.
 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.
@@ -43,7 +48,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,7 +166,7 @@ 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>`
 14. Use `npx create-quiver ai plan --phase technical-plan --dry-run`

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,10 @@ 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 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 +82,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.

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,8 +146,12 @@ 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`.

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/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)

package/docs/reference/commands.md

@@ -2,6 +2,25 @@
 
 Usá `npx --yes create-quiver@latest --help` para ver la lista viva de comandos soportados por la versión instalada.
 
+## npx vs instalación local
+
+Quiver está pensado para ejecutarse principalmente con `npx`:
+
+```bash
+npx --yes create-quiver@latest <comando>
+```
+
+En ese modo npm descarga o reutiliza el CLI desde su caché y no lo instala en `node_modules`. Eso es normal: `create-quiver` es una herramienta de workflow, no una dependencia runtime de la app.
+
+Instalalo como dependencia de desarrollo solo si querés fijar una versión para el equipo:
+
+```bash
+npm install --save-dev create-quiver
+npx create-quiver <comando>
+```
+
+Más detalle: [Instalación y uso con npx](../getting-started/installation.md).
+
 ## Configuración inicial
 
 | Comando | Para qué sirve |
@@ -26,7 +45,15 @@ Usá `npx --yes create-quiver@latest --help` para ver la lista viva de comandos
 | `npx --yes create-quiver@latest ai prepare-context --with-planner --dry-run` | Previsualiza una propuesta docs-only generada por el planner sin escribir archivos. |
 | `npx --yes create-quiver@latest ai prepare-context --with-planner --print-prompt` | Imprime el prompt exacto para ejecutar el planner en otro entorno. |
 | `npx --yes create-quiver@latest ai prepare-context --with-planner --review --interactive` | Ejecuta planner, abre revisión humana y pide confirmación antes de escribir docs permitidos. |
-| `npx --yes create-quiver@latest ai agent set <role> --provider <provider> --model "<label>"` | Guarda un perfil de agente sin secretos. |
+| `npx --yes create-quiver@latest ai models list` | Lista proveedores y modelos conocidos por Quiver sin afirmar disponibilidad en la cuenta. |
+| `npx --yes create-quiver@latest ai models list --provider codex` | Filtra el catálogo local por proveedor. |
+| `npx --yes create-quiver@latest ai models list --json` | Emite el catálogo local en JSON parseable. |
+| `npx --yes create-quiver@latest ai agent set <role>` | En TTY, guía la selección de proveedor, modelo conocido por Quiver o modelo custom. |
+| `npx --yes create-quiver@latest ai agent set <role> --provider <provider> --model <model-id>` | Guarda un perfil de agente sin secretos en modo script/no-TTY. |
+| `npx --yes create-quiver@latest ai agent set planner --provider codex --model gpt-5.5 --dry-run` | Previsualiza la escritura del perfil sin modificar `.quiver/agents/profiles.json`. |
+| `npx --yes create-quiver@latest ai agent doctor` | Diagnostica perfiles de agentes, alias visuales, proveedores faltantes y modelos custom no validados. |
+| `npx --yes create-quiver@latest ai agent doctor --json` | Emite el diagnóstico de perfiles como JSON parseable. |
+| `npx --yes create-quiver@latest ai agent repair --dry-run` | Previsualiza reparaciones seguras de perfiles, como normalizar `model: "GPT 5.5"` a `model: "gpt-5.5"` y `displayName: "GPT 5.5"`. |
 | `npx --yes create-quiver@latest ai run create --input <file>` | Inicia una ejecución persistente de IA. |
 | `npx --yes create-quiver@latest ai status` | Muestra el estado de la ejecución actual. |
 | `npx --yes create-quiver@latest ai plan --phase acceptance --input <file>` | Genera criterios de aceptación. |
@@ -76,6 +103,7 @@ Usá `npx --yes create-quiver@latest --help` para ver la lista viva de comandos
 | `--methodology wdd-sdd` | Declara la metodología soportada por comandos interactivos o automatizados. |
 | `--no-color` | Desactiva colores ANSI en salida humana. |
 | `--provider codex\|claude\|gemini` | Selecciona CLI local de proveedor. |
+| `--model <model-id>` | Selecciona el identificador técnico del modelo para `ai agent set` o ejecución de proveedor. Quiver normaliza alias conocidos, pero no garantiza acceso en la cuenta del proveedor. |
 | `--commit` | Permite que Quiver commitee trabajo validado del slice. |
 | `--mode manual` | Imprime prompts para asignación manual de ejecutores. |
 | `--mode delegated` | Usa ejecución delegada con worktrees temporales cuando es seguro. |

package/package.json

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