create-quiver 0.14.1 → 0.15.1

package/CHANGELOG.md

@@ -6,6 +6,28 @@ 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.
+- `doctor --json` with a stable parseable diagnostics contract, backed by the same findings as the human `Quiver Doctor` output.
+- `init --interactive`, `spec create --interactive`, and `--methodology wdd-sdd` for guarded human choices.
+
+### 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.
+
+## [0.14.1] - 2026-05-26
+
+### Added
+
 - v29 planner-assisted context and CLI UX standard under `specs/quiver-v29-planner-prepare-context-cli-ux/`.
 - Shared Quiver-branded CLI UX helpers, color tokens, editor review support, and guarded UX flag matrix.
 - Optional `ai prepare-context --with-planner` flow with prompt printing, review, interactive approval, and docs-only proposal validation.

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:
@@ -149,16 +169,23 @@ Usá la guía que corresponda al estado de tu proyecto:
 | `npx --yes create-quiver@latest --help` | Muestra la lista pública de comandos. |
 | `npx --yes create-quiver@latest --version` | Muestra la versión del CLI. |
 | `npx --yes create-quiver@latest init --name "Proyecto"` | Inicializa Quiver en un proyecto. |
+| `npx --yes create-quiver@latest init --interactive` | Abre una guía humana para elegir modo, metodología `wdd-sdd`, perfil inicial y próximos pasos de agentes. |
 | `npx --yes create-quiver@latest migrate --dry-run` | Previsualiza la migración de un proyecto Quiver anterior. |
 | `npx --yes create-quiver@latest analyze` | Genera el mapa del proyecto usado por humanos y agentes. |
 | `npx --yes create-quiver@latest doctor` | Revisa si el contrato de Quiver está sano. |
+| `npx --yes create-quiver@latest doctor --json` | Devuelve el diagnóstico como JSON para automatizaciones. |
 | `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. |
 | `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. |
 | `npx --yes create-quiver@latest next --all-ready --spec <spec>` | Lista los slices listos para ejecutar. |
 | `npx --yes create-quiver@latest ai execute-slice --slice <slice.json> --commit` | Ejecuta un slice aprobado y lo commitea después de validar. |
@@ -176,6 +203,7 @@ Quiver usa un estándar único para que los comandos sean claros tanto para huma
 - `--with-planner` activa un modo asistido por planner solo en comandos que lo soportan.
 - `--review` abre o prepara una revisión humana antes de escrituras persistentes.
 - `--interactive` habilita confirmaciones explícitas cuando el comando puede cambiar estado.
+- `--methodology wdd-sdd` declara la metodología soportada por los flujos guiados.
 - `--json` mantiene salida legible por máquinas y no se combina con `--interactive` ni `--review`.
 - `--no-color` desactiva colores cuando el entorno no los necesita.
 
@@ -214,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,9 +7,12 @@ 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.
+`doctor` must render the human hierarchy `Quiver Doctor` -> `Checks` -> `Suggested fixes`, and `doctor --json` must emit the same diagnostics as stable parseable JSON without colors, prompts, or human prose.
+`init --interactive` and `spec create --interactive` are explicit human-only wrappers. They must not run in CI/no-TTY/JSON, must show only the real methodology `WDD + SDD` (`--methodology wdd-sdd`), and must summarize choices before persistent writes.
 If the project already exists from an older Quiver version and was previously initialized by Quiver, run `npx create-quiver migrate` before `analyze` from the project root.
 If the project was never initialized by Quiver, do not use `migrate` as bootstrap; run `npx create-quiver init --name "Project Name"` first.
 Use `npx create-quiver evidence run -- <command>` to capture validation evidence with command, exit code, duration, truncated output, and best-effort redaction. The safe default output is `.quiver/evidence/`; use `--output <file>` when a slice needs a specific evidence artifact.
@@ -20,11 +23,19 @@ The v25 spec is implemented under `specs/quiver-v25-ai-first-lifecycle-orchestra
 The v26 hotfix spec is implemented under `specs/quiver-v26-0121-smoke-hardening/` and shipped in `create-quiver@0.12.1`; it covers smoke hardening for CLI help/version output, generated doc links, AI approval/review guidance, local validation, slice brief validation, demo readiness, scoped plan/graph performance, and release smoke coverage.
 The v27 spec is implemented under `specs/quiver-v27-reliability-ai-workflow-hardening/` and shipped in `create-quiver@0.13.0`; it captures Pixel Quiver dogfooding findings (`QP-001` to `QP-019`, `QIS-001` to `QIS-022`) and includes shared state resolution, canonical statuses, schema v2 exports, structured spec creation, AI artifact cleanup, worktree locks, validation gates, context diagnostics, cross-platform DX, fixtures, smoke suites, and package/tarball release readiness.
 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 is pending package publication; 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 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, and display label 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.
 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.
 `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.
 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.
@@ -37,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.
@@ -155,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

@@ -80,10 +80,19 @@
 - Published package `0.14.0`.
 - **v28** — Follow-up hardening from Pixel Quiver dogfooding: active-slice reconciliation, spec-aware `ai inspect` recovery, structured plan-review closure, safer technical-plan approval, stronger spec/worktree validation, agent-safe command examples, GitHub auth/alias guidance, and final release-readiness evidence live in `specs/quiver-v28-pixel-quiver-feedback-reconciliation/`.
 
-## v0.15 — Planner Context and CLI UX Standard (in progress)
+## v0.14.1 — Planner Context and CLI UX Standard (shipped 2026-05-26)
 
+- Published package `0.14.1`.
 - **v29** — Planner-assisted context preparation and CLI UX standard: shared output helpers, Quiver palette, guarded `--with-planner` / `--interactive` / `--review` flags, optional planner-generated `ai prepare-context`, review/interactive adoption for selected commands, docs, tests, and smoke readiness live in `specs/quiver-v29-planner-prepare-context-cli-ux/`.
 
+## v0.15 — Interactive CLI UX and Agent Selection (release-ready, pending package publication)
+
+- **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.
@@ -101,7 +110,9 @@
 - **v26 — 0.12.1 Smoke Hardening** (shipped in `0.12.1`): first-use hardening from clean npm smoke testing, covering CLI help/version output, generated doc links, AI approval/review guidance, local validation, slice brief validation, demo readiness, scoped plan/graph performance, and release smoke coverage live in `specs/quiver-v26-0121-smoke-hardening/`.
 - **v27 — Reliability and AI Workflow Hardening** (shipped in `0.13.0`): Pixel Quiver dogfooding follow-up covering resolver/export/spec-create/AI-artifact/worktree/validation/context/DX hardening lives in `specs/quiver-v27-reliability-ai-workflow-hardening/`.
 - **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** (in progress): 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/`.
+- **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

@@ -36,6 +36,7 @@ Reglas:
 | `--with-planner` | Activa comportamiento asistido por planner cuando el comando lo soporta. | No debe ser decorativo. Si no cambia el comportamiento o contrato del comando, debe rechazarse. |
 | `--interactive` | Habilita prompts humanos de confirmacion o eleccion. | Nunca se activa por defecto. Debe tener alternativa no interactiva. |
 | `--review` | Abre o prepara revision humana antes de escrituras persistentes. | Debe usar `$VISUAL`, `$EDITOR` o dejar un artefacto revisable cuando no haya TTY. |
+| `--methodology <name>` | Selecciona metodologia cuando el comando necesita exponer esa decision. | Hoy solo se acepta `wdd-sdd`; no listar metodologias no soportadas. |
 | `--dry-run` | Previsualiza sin escribir ni ejecutar acciones irreversibles. | Debe ser seguro y no requerir credenciales salvo que el comando lo documente. |
 | `--print-prompt` | Imprime el prompt exacto sin ejecutar proveedor. | Debe evitar auth/provider execution. |
 | `--json` | Emite salida machine-readable. | Incompatible con `--interactive` y `--review`. |
@@ -45,10 +46,18 @@ Reglas:
 
 | Comando | `--with-planner` | `--interactive` | `--review` | Notas |
 |---|---:|---:|---:|---|
+| `init` | no | si | no | Interactive guia modo de proyecto, metodologia `wdd-sdd`, perfil inicial y proximo paso de perfiles de agentes. |
 | `ai prepare-context` | si | si | si | Modo deterministico por defecto; planner opcional con contrato docs-only. |
 | `ai plan` | si | si | si | El planner ya es implicito; `--with-planner` se acepta por consistencia. |
 | `spec create` | si | si | si | Consume un plan tecnico aprobado del planner; no vuelve a ejecutar proveedor. Review previsualiza el paquete antes de escribir. |
 | `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. |
 
@@ -71,15 +80,57 @@ npx create-quiver ai prepare-context --with-planner --review --interactive
 
 El planner debe devolver una propuesta validable. Quiver solo acepta cambios en documentación/contexto permitida y rechaza rutas de producto, dependencias, build, runtime, lockfiles, salidas generadas, rutas absolutas y traversal.
 
+## Seleccion de agentes, proveedores y modelos
+
+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.
+- `--print-prompt` y `--dry-run` no deben exigir autenticacion del proveedor.
+- Si no hay modelo seleccionado, los comandos existentes deben conservar su comportamiento anterior.
+
+## Init y spec create interactivos
+
+`init --interactive` debe ser un wrapper opt-in sobre flags existentes:
+
+- modo de proyecto: proyecto existente, proyecto nuevo o solo validar estructura;
+- metodologia: solo `WDD + SDD`;
+- perfil inicial: default, minimal o full compatibility;
+- guia opcional de comandos `ai agent set` sin guardar credenciales ni ejecutar proveedores;
+- resumen antes de escribir.
+
+`spec create --interactive` debe:
+
+- seleccionar la metodologia real soportada: `WDD + SDD`;
+- mostrar el input aprobado que se usara para generar la spec;
+- 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.
+
 ## Loaders y prompts
 
 Usar loaders solo cuando aportan claridad:
 
 ```text
-Analizando estructura del proyecto...
-Leyendo contexto base...
-Preparando prompt para planner...
-Ejecutando agente...
+◇ Ejecutando onboarding con GPT 5.5
+✓ Leyendo docs base
+✓ Detectando estructura
+✓ Preparando prompt
+⠋ Ejecutando agente...
 ```
 
 Usar prompts interactivos cuando hay una decision humana real:
@@ -92,6 +143,30 @@ Usar prompts interactivos cuando hay una decision humana real:
 
 No usar prompts para informacion que ya se pueda expresar con flags.
 
+## Salida de Doctor
+
+`doctor` debe mostrar una jerarquia estable para humanos:
+
+```text
+◆ Quiver Doctor
+
+Checks
+  ✓ Layout: new
+  ✓ Specs: none yet
+  ! Warning: project analysis artifacts not found; run analyze when you need the visible project map
+
+Suggested fixes
+  • Analyze the project first: npx create-quiver analyze
+  • Check the next ready slice: npx create-quiver next
+```
+
+Reglas:
+
+- La salida humana debe incluir siempre `Quiver Doctor`, `Checks` y `Suggested fixes`.
+- `doctor --json` debe emitir solo JSON parseable, sin colores, prompts ni texto humano.
+- La salida humana y JSON deben salir del mismo modelo de checks, warnings, errors y suggested fixes.
+- Warnings no deben romper automatizacion; errores bloqueantes deben usar `exit_code: 1` y `process.exitCode = 1`.
+
 ## Revision con editor
 
 Los comandos con `--review` deben:

package/docs/COMMANDS.md.template

@@ -10,6 +10,7 @@ This document is the canonical command reference for the orchestration roadmap.
 | Command | Purpose | OS | Since | Example |
 |---------|---------|----|-------|---------|
 | `npx create-quiver init --name "<project>"` | Creates the default AI-first Quiver contract for a project | macOS, Linux, Windows | current | `npx create-quiver init --name "{{PROJECT_NAME}}"` |
+| `npx create-quiver init --interactive` | Guides project mode, methodology `wdd-sdd`, init profile, and agent-profile next steps without running providers | macOS, Linux, Windows | next | `npx create-quiver init --interactive` |
 | `npx create-quiver --name "<project>"` | Compatibility alias for the recommended init flow | macOS, Linux, Windows | current | `npx create-quiver --name "{{PROJECT_NAME}}"` |
 | `npx create-quiver --version` | Prints the installed CLI version | macOS, Linux, Windows | current | `npx create-quiver --version` |
 | `npx create-quiver --help` | Lists all public commands with descriptions, key options, and recommended examples | macOS, Linux, Windows | current | `npx create-quiver --help` |
@@ -21,6 +22,7 @@ This document is the canonical command reference for the orchestration roadmap.
 | `quiver:flow` | Runs the guided flow entrypoint through the generated npm script | macOS, Linux, Windows | v0.11 | `npm run quiver:flow` |
 | `quiver:prepare` | Runs guided setup diagnostics and context preparation | macOS, Linux, Windows | v0.10 | `npm run quiver:prepare -- --dry-run --provider codex` |
 | `quiver:doctor` | Validates the Quiver contract and reports layout or migration guidance | macOS, Linux, Windows | v0.8 | `npm run quiver:doctor` |
+| `quiver:doctor -- --json` | Emits the Doctor checks and suggested fixes as stable machine-readable JSON | macOS, Linux, Windows | next | `npm run quiver:doctor -- --json` |
 | `quiver:doctor -- --fix --dry-run` | Previews safe non-destructive repairs without writing files | macOS, Linux, Windows | v0.11 | `npm run quiver:doctor -- --fix --dry-run` |
 | `quiver:doctor -- --fix` | Applies safe idempotent repairs after review | macOS, Linux, Windows | v0.11 | `npm run quiver:doctor -- --fix` |
 | `quiver:evidence -- run -- <command>` | Captures command validation evidence with exit code, duration, redacted/truncated output, and a local Markdown record | macOS, Linux, Windows | v0.11 | `npm run quiver:evidence -- run -- npm test` |
@@ -42,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` |
@@ -66,6 +73,7 @@ This document is the canonical command reference for the orchestration roadmap.
 | `quiver:ai:pr` | Validates `gh`, reads `pr.md`, prints a PR plan, and creates a PR only with `--create` | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:pr -- --dry-run --input specs/<spec>/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work` |
 | `quiver:ai:pr -- --review` | Opens `pr.md` for human review and rebuilds the PR plan from the edited body | macOS, Linux, Windows | next | `npm run quiver:ai:pr -- --review --dry-run --input specs/<spec>/pr.md` |
 | `quiver:spec:create` | Creates the real spec tree from the reviewed approved technical plan | macOS, Linux, Windows | v0.11 | `npm run quiver:spec:create -- --dry-run` |
+| `quiver:spec:create -- --interactive` | Guides methodology `wdd-sdd`, approved technical-plan input, and direct-vs-review mode before writing | macOS, Linux, Windows | next | `npm run quiver:spec:create -- --interactive` |
 | `quiver:spec:create -- --review --interactive` | Reviews the generated spec package preview and asks before writing files | macOS, Linux, Windows | next | `npm run quiver:spec:create -- --review --interactive` |
 | `quiver:spec:start` | Creates or reuses the dedicated worktree for one spec | macOS, Linux, Windows | v0.10 | `npm run quiver:spec:start -- specs/<spec>` |
 | `quiver:spec:status` | Shows spec worktree, branch, `slice-00`, and pending slices | macOS, Linux, Windows | v0.10 | `npm run quiver:spec:status -- specs/<spec>` |
@@ -95,12 +103,13 @@ 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 |
-| `--interactive` | `ai prepare-context`, `ai plan`, `spec create`, `ai pr` | Enable human prompts for confirmation or choices |
+| `--interactive` | `init`, `ai prepare-context`, `ai plan`, `spec create`, `ai pr`, `ai execute-slice`, `ai execute-plan` | Enable human prompts for confirmation or choices |
 | `--review` | `ai prepare-context`, `ai plan`, `spec create`, `ai pr` | Open or prepare human review before persistent writes |
+| `--methodology wdd-sdd` | `init`, `spec create` | Select the only supported methodology exposed by guided flows |
 | `--no-color` | all human-output commands | Disable ANSI color in human output |
 | `--print-prompt` | `ai onboard`, `ai prepare-context`, `ai plan`, `ai revise`, `ai review-plan` | Print the exact provider prompt and exit without executing provider CLIs or requiring provider auth |
 | `--role <planner\|executor\|reviewer\|doctor>` | `ai onboard`, `ai plan`, `ai revise`, `ai execute-slice`, `ai execute-plan` | Select an AI role; execution requires executor |
@@ -121,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`.
@@ -132,10 +142,16 @@ This document is the canonical command reference for the orchestration roadmap.
 - `quiver:ai:prepare-context -- --dry-run` previews deterministic docs-only context drafts, diff snippets, assumptions, risks, contradictions, and omitted paths. Write mode stores snapshots under `.quiver/runs/<run-id>/snapshots/` and preserves human-authored content by appending or refreshing a Quiver-managed block.
 - `quiver:ai:prepare-context -- --with-planner` invokes a planner provider and only accepts a validated docs-only proposal. Use `--print-prompt` for external planners, `--review` to inspect the proposal before writing, and `--interactive` to require confirmation.
 - UX flags are centralized: `--with-planner`, `--interactive`, and `--review` are accepted only by commands where they add real behavior. Read-only inspection commands reject them with an actionable next step. `spec create --with-planner` consumes an already approved planner output and does not call a provider again. `--json` is incompatible with `--interactive` and `--review`.
+- `doctor --json` emits the same checks and suggested fixes as human `Quiver Doctor` output without colors, prompts, spinners, or prose.
+- `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