create-quiver 0.15.0 → 0.15.1

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-03-agent-doctor-repair/slice.json

@@ -0,0 +1,77 @@
+{
+  "slice_id": "slice-03-agent-doctor-repair",
+  "ticket": "QUIVER-31-03",
+  "type": "feature",
+  "title": "Agent profile doctor and repair dry-run",
+  "objective": "Diagnose existing agent profile issues and preview safe repairs without writing files.",
+  "description": "Adds `ai agent doctor` and `ai agent repair --dry-run` for missing data, unsupported providers, display aliases stored as model ids, custom unvalidated models, duplicate labels, and missing provider CLIs.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v31-agent-doctor-repair",
+    "branch_name": "feature/QUIVER-31-03-v31-agent-doctor-repair"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/agent-profiles.js",
+    "src/create-quiver/lib/ai/model-catalog.js",
+    "tests/commands/ai-agent.test.js",
+    "tests/lib/agent-profiles.test.js"
+  ],
+  "expected_read_paths": [
+    "SPEC.md",
+    "src/create-quiver/lib/agent-profiles.js",
+    "src/create-quiver/lib/ai/model-catalog.js",
+    "src/create-quiver/lib/cli/ux.js",
+    "tests/commands/ai-agent.test.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/agent-profiles.js",
+    "src/create-quiver/lib/ai/model-catalog.js",
+    "tests/commands/ai-agent.test.js",
+    "tests/lib/agent-profiles.test.js",
+    "specs/quiver-v31-ai-model-catalog-agent-selection/**"
+  ],
+  "depends_on": [
+    "slice-01-model-catalog-alias-normalization",
+    "slice-02-interactive-agent-set-selectors"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Doctor and repair depend on catalog issue classification and may share command wiring with selectors.",
+  "must": [
+    "Add human and JSON output for `ai agent doctor`.",
+    "Evaluate every profile, not only defaults.",
+    "Classify findings as error, warning, or info.",
+    "Set exit code 1 when errors exist.",
+    "Add `ai agent repair --dry-run` with before/after proposed changes.",
+    "Prevent repair writes without explicit confirmation or `--yes` if write mode is implemented.",
+    "Use v30 human output hierarchy with Checks and Suggested fixes."
+  ],
+  "not_included": [
+    "Remote validation against provider APIs.",
+    "Automatic destructive profile rewrites.",
+    "Installing provider CLIs."
+  ],
+  "acceptance": [
+    "Doctor reports unsupported providers as errors.",
+    "Doctor reports custom unvalidated models as warnings.",
+    "Doctor detects `model: \"GPT 5.5\"` and suggests repair.",
+    "Repair dry-run shows normalized `model: gpt-5.5` and `displayName: GPT 5.5` without writing.",
+    "`--json` outputs parseable JSON without human prose.",
+    "Human output uses Quiver Doctor-style sections."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-agent.test.js tests/lib/agent-profiles.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Include fixtures for multiple profiles and duplicate display names.",
+    "Include the real bug profile with `model: \"GPT 5.5\"`."
+  ],
+  "estimated_hours": 8,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 7,
+  "completed_at": "2026-05-27"
+}

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-04-shared-preflight-provider-errors/CLOSURE_BRIEF.md

@@ -0,0 +1,35 @@
+# CLOSURE_BRIEF - slice-04 Shared model preflight and provider error extraction
+
+## Summary
+
+Implemented shared model alias resolution and provider error extraction across planner and executor runtime paths.
+
+## Validation Against Acceptance Criteria
+
+- [x] Live commands preflight profile models before provider execution.
+- [x] Legacy profile display aliases block before provider execution with a repair suggestion.
+- [x] CLI `--model` display aliases normalize to technical ids in dry-runs.
+- [x] Provider invalid-model errors are surfaced ahead of secondary MCP/tool noise.
+- [x] Provider error text redacts common secret patterns.
+- [x] Existing successful provider runs keep working.
+
+## Relevant Changes
+
+- Added provider model alias normalization and blocking policy.
+- Added provider error cause extraction for invalid model, auth, missing CLI, timeout, and generic failures.
+- Added provider failure serialization for non-zero provider exits with stderr but no process error.
+- Applied profile-alias blocking to planner, reviewer, repair-plan, execute-slice, and execute-plan flows.
+- Added tests for CLI alias normalization, legacy profile blocking, invalid model extraction, and secret redaction.
+
+## Pending
+
+- None for this slice.
+
+## Remaining Risks
+
+- Provider stderr formats can change; new failures should be added as fixtures.
+- Custom model ids still rely on provider-side validation because Quiver cannot know account entitlement locally.
+
+## Future Recommendations
+
+Track provider stderr patterns as test fixtures when new provider failures are observed.

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-04-shared-preflight-provider-errors/EXECUTION_BRIEF.md

@@ -0,0 +1,55 @@
+# EXECUTION_BRIEF - slice-04 Shared model preflight and provider error extraction
+
+## Context
+
+The real dogfooding failure surfaced as `provider run failed` even though Codex emitted a useful invalid-model error. Live AI commands need shared preflight and better error extraction.
+
+## Objective
+
+Apply model resolution before live provider execution and surface actionable provider errors.
+
+## Scope
+
+- `src/create-quiver/lib/ai/providers.js`
+- `src/create-quiver/lib/ai/executor.js`
+- `src/create-quiver/lib/ai/execution-plan.js`
+- `src/create-quiver/commands/ai.js`
+- related tests
+
+## Acceptance Criteria
+
+- Live commands block before provider execution for known bad display aliases.
+- CLI `--model "GPT 5.5"` is normalized or blocked with guidance.
+- Dry-runs show the real command and technical model id.
+- Invalid model errors are prioritized over secondary MCP/tool noise.
+- Secrets are redacted from provider errors.
+
+## Technical Plan Summary
+
+Create one shared provider/model resolution path and one provider-error extraction path, then adopt them across planner, reviewer, executor, and execution-plan flows.
+
+## Suggested Steps
+
+1. Add shared model preflight helper.
+2. Add provider error extractor.
+3. Adopt helper in planner/reviewer commands.
+4. Adopt helper in executor/execution-plan flows.
+5. Add tests with fake provider output.
+
+## Restrictions
+
+- Do not require real provider auth in tests.
+- Do not change provider prompt content except for validation/preflight.
+- Do not remove custom model support.
+
+## Risks
+
+- Over-eager blocking can prevent legitimate custom models.
+- Provider stderr formats can change.
+
+## Completion Checklist
+
+- [ ] Shared preflight implemented.
+- [ ] Provider error extraction implemented.
+- [ ] Planner and executor paths adopted.
+- [ ] Regression test covers `GPT 5.5`.

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-04-shared-preflight-provider-errors/slice.json

@@ -0,0 +1,84 @@
+{
+  "slice_id": "slice-04-shared-preflight-provider-errors",
+  "ticket": "QUIVER-31-04",
+  "type": "feature",
+  "title": "Shared model preflight and provider error extraction",
+  "objective": "Apply model resolution and useful provider errors before every live AI command.",
+  "description": "Adds shared preflight for profile and CLI model overrides plus provider error extraction that prioritizes invalid model and auth causes over noisy secondary logs.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v31-shared-preflight-provider-errors",
+    "branch_name": "feature/QUIVER-31-04-v31-shared-preflight-provider-errors"
+  },
+  "files": [
+    "src/create-quiver/lib/ai/providers.js",
+    "src/create-quiver/lib/ai/executor.js",
+    "src/create-quiver/lib/ai/execution-plan.js",
+    "src/create-quiver/commands/ai.js",
+    "tests/lib/ai-providers.test.js",
+    "tests/commands/ai-prepare-context-planner.test.js",
+    "tests/commands/ai-plan.test.js",
+    "tests/commands/ai-execute-slice.test.js"
+  ],
+  "expected_read_paths": [
+    "SPEC.md",
+    "src/create-quiver/lib/ai/providers.js",
+    "src/create-quiver/lib/ai/model-catalog.js",
+    "src/create-quiver/lib/ai/executor.js",
+    "src/create-quiver/commands/ai.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/lib/ai/providers.js",
+    "src/create-quiver/lib/ai/executor.js",
+    "src/create-quiver/lib/ai/execution-plan.js",
+    "src/create-quiver/commands/ai.js",
+    "tests/lib/ai-providers.test.js",
+    "tests/commands/ai-prepare-context-planner.test.js",
+    "tests/commands/ai-plan.test.js",
+    "tests/commands/ai-review-plan.test.js",
+    "tests/commands/ai-execute-slice.test.js",
+    "tests/commands/ai-execute-plan.test.js",
+    "specs/quiver-v31-ai-model-catalog-agent-selection/**"
+  ],
+  "depends_on": [
+    "slice-01-model-catalog-alias-normalization",
+    "slice-03-agent-doctor-repair"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Touches shared provider and AI command runtime behavior.",
+  "must": [
+    "Create shared provider/model selection resolution used by live AI commands.",
+    "Apply normalization or blocking to profile models and CLI `--model` overrides.",
+    "Block before provider execution for known display aliases that can be corrected.",
+    "Keep dry-run output truthful with the real command and model args.",
+    "Extract invalid model, auth, missing CLI, timeout, and secondary warning causes.",
+    "Redact secrets in surfaced provider errors.",
+    "Preserve JSON/no-TTY cleanliness."
+  ],
+  "not_included": [
+    "Changing provider CLI install process.",
+    "Guaranteeing account-level access without live validation.",
+    "Changing prompt content unrelated to model selection."
+  ],
+  "acceptance": [
+    "Live AI commands block before provider execution for `model: \"GPT 5.5\"` with Codex.",
+    "CLI override `--model \"GPT 5.5\"` is normalized or blocked with a concrete suggestion.",
+    "Dry-run shows the real command and technical model id.",
+    "Provider stderr with invalid model plus MCP noise reports invalid model as primary cause.",
+    "Existing successful provider runs keep working."
+  ],
+  "tests": [
+    "node --test tests/lib/ai-providers.test.js tests/commands/ai-prepare-context-planner.test.js tests/commands/ai-plan.test.js tests/commands/ai-review-plan.test.js tests/commands/ai-execute-slice.test.js tests/commands/ai-execute-plan.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Use fake provider runners for failure cases.",
+    "Do not require real provider auth in automated tests."
+  ],
+  "estimated_hours": 10,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 8,
+  "completed_at": "2026-05-27"
+}

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-05-ai-models-list/CLOSURE_BRIEF.md

@@ -0,0 +1,32 @@
+# CLOSURE_BRIEF - slice-05 AI models list command
+
+## Summary
+
+Implemented `ai models list` with human and JSON output for Quiver's local model catalog.
+
+## Validation Against Acceptance Criteria
+
+- [x] Models list command works and groups by provider.
+- [x] Provider filter works for `--provider codex`.
+- [x] JSON output parses and includes catalog metadata.
+- [x] Help includes the command.
+- [x] Human output says models are known by Quiver and does not claim availability.
+
+## Relevant Changes
+
+- Added `runModelsList` command handler.
+- Added `ai models list` parser and command routing.
+- Updated CLI help and command contract tests.
+- Added `tests/commands/ai-models.test.js`.
+
+## Pending
+
+- None for this slice.
+
+## Remaining Risks
+
+- The catalog remains local and can become stale until a remote/update mechanism exists.
+
+## Future Recommendations
+
+Use this command as the future integration point for a remote model catalog API.

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-05-ai-models-list/EXECUTION_BRIEF.md

@@ -0,0 +1,52 @@
+# EXECUTION_BRIEF - slice-05 AI models list command
+
+## Context
+
+Users need a discoverable way to see Quiver's known providers and model ids without reading source files.
+
+## Objective
+
+Add `ai models list` with human and JSON output.
+
+## Scope
+
+- `src/create-quiver/commands/ai.js`
+- `src/create-quiver/lib/ai/model-catalog.js`
+- command/help tests
+
+## Acceptance Criteria
+
+- `ai models list` groups models by provider.
+- `ai models list --provider codex` filters to Codex.
+- `ai models list --json` emits valid JSON with `catalogVersion` and `lastUpdated`.
+- Human output says known by Quiver, not available.
+- Help output includes the command.
+
+## Technical Plan Summary
+
+Render the catalog through the existing CLI UX primitives and keep JSON output free of colors/prompts/prose.
+
+## Suggested Steps
+
+1. Add command routing.
+2. Add provider filter validation.
+3. Add human renderer.
+4. Add JSON renderer.
+5. Add tests for output and help contract.
+
+## Restrictions
+
+- Do not call provider CLIs.
+- Do not implement remote catalog lookup.
+- Do not call models available without validation.
+
+## Risks
+
+- Human output can become too noisy if metadata is excessive.
+
+## Completion Checklist
+
+- [ ] Human output implemented.
+- [ ] JSON output implemented.
+- [ ] Provider filtering tested.
+- [ ] Help contract updated.

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-05-ai-models-list/slice.json

@@ -0,0 +1,72 @@
+{
+  "slice_id": "slice-05-ai-models-list",
+  "ticket": "QUIVER-31-05",
+  "type": "feature",
+  "title": "AI models list command",
+  "objective": "Expose Quiver's known model catalog through human and JSON CLI output.",
+  "description": "Adds `ai models list` with provider filtering, role metadata, catalog version, last updated date, and clean machine output.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v31-ai-models-list",
+    "branch_name": "feature/QUIVER-31-05-v31-ai-models-list"
+  },
+  "files": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/model-catalog.js",
+    "tests/commands/ai-models.test.js",
+    "tests/commands/cli-contract.test.js"
+  ],
+  "expected_read_paths": [
+    "SPEC.md",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/model-catalog.js",
+    "src/create-quiver/lib/cli/ux.js"
+  ],
+  "allowed_write_paths": [
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/lib/ai/model-catalog.js",
+    "tests/commands/ai-models.test.js",
+    "tests/commands/cli-contract.test.js",
+    "specs/quiver-v31-ai-model-catalog-agent-selection/**"
+  ],
+  "depends_on": [
+    "slice-01-model-catalog-alias-normalization"
+  ],
+  "parallel_safe": "yes",
+  "parallel_safe_reason": "Can run after catalog and mostly touches list output/tests.",
+  "must": [
+    "Add `ai models list` command.",
+    "Support `--provider <id>` filtering.",
+    "Support `--json` clean output.",
+    "Human output must group by provider and show recommended roles.",
+    "JSON output must include catalogVersion and lastUpdated.",
+    "Use wording `known by Quiver`, not `available`.",
+    "Update CLI help/contract tests."
+  ],
+  "not_included": [
+    "Remote model catalog API.",
+    "Live model availability checks.",
+    "Interactive profile setup."
+  ],
+  "acceptance": [
+    "`ai models list` groups models by provider.",
+    "`ai models list --provider codex` only shows Codex models.",
+    "`ai models list --json` outputs valid JSON without colors/prose.",
+    "Unknown provider filter fails with supported provider guidance.",
+    "Help output includes the new command."
+  ],
+  "tests": [
+    "node --test tests/commands/ai-models.test.js tests/commands/cli-contract.test.js",
+    "git diff --check"
+  ],
+  "validation_hints": [
+    "Validate JSON parsing in tests.",
+    "Validate human output does not say available."
+  ],
+  "estimated_hours": 4,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 3,
+  "completed_at": "2026-05-27"
+}

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-06-docs-templates-alignment/CLOSURE_BRIEF.md

@@ -0,0 +1,33 @@
+# CLOSURE_BRIEF - slice-06 Documentation and generated template alignment
+
+## Summary
+
+Updated public docs, source-of-truth AI guidance, command reference, CLI UX guide, generated templates, roadmap, and v31 status to describe the new model catalog and agent profile setup contract.
+
+## Validation Against Acceptance Criteria
+
+- [x] Docs explain `model` vs `displayName`.
+- [x] Docs explain catalog limitations: models are known by Quiver, not guaranteed available in the user's provider account.
+- [x] Commands are documented: `ai models list`, `ai agent doctor`, and `ai agent repair --dry-run`.
+- [x] Generated templates are aligned with current setup, no-TTY/script setup, and legacy-profile repair guidance.
+
+## Relevant Changes
+
+- Updated `README.md` with concise agent setup commands and profile data guidance.
+- Updated `docs/reference/commands.md` with model listing, interactive agent setup, profile doctor, and repair dry-run commands.
+- Updated `docs/CLI_UX_GUIDE.md` with the canonical profile data contract and UX matrix rows.
+- Updated generated templates `docs/COMMANDS.md.template`, `docs/AI_ONBOARDING_PROMPT.md.template`, and `docs/AI_CONTEXT.md.template`.
+- Updated `README_FOR_AI.md`, `ROADMAP.md`, and this spec status to reflect completed docs/templates alignment without claiming package publication.
+
+## Pending
+
+Final release-readiness validation remains in `slice-07-tests-smokes-release-readiness`.
+
+## Remaining Risks
+
+- The local model catalog can become stale until Quiver has a remote or update mechanism.
+- Account-level model access still depends on the provider CLI/account and can only be proven by live execution.
+
+## Future Recommendations
+
+Keep model catalog docs close to command references so users do not treat catalog entries as guaranteed access.

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-06-docs-templates-alignment/EXECUTION_BRIEF.md

@@ -0,0 +1,58 @@
+# EXECUTION_BRIEF - slice-06 Documentation and generated template alignment
+
+## Context
+
+The new model catalog and agent setup behavior must be discoverable in the public README, AI source of truth, command reference, CLI UX guide, and generated project docs.
+
+## Objective
+
+Document the finalized v31 behavior without duplicating long procedural content in the root README.
+
+## Scope
+
+- `README.md`
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+- `docs/CLI_UX_GUIDE.md`
+- `docs/reference/commands.md`
+- `docs/COMMANDS.md.template`
+- generated onboarding/context templates where relevant
+
+## Acceptance Criteria
+
+- Docs explain `model` vs `displayName`.
+- Docs explain known catalog vs account availability.
+- Docs include interactive and no-TTY setup.
+- Docs include `ai models list`, `ai agent doctor`, and `ai agent repair --dry-run`.
+- Generated templates include current guidance where appropriate.
+- Source-of-truth docs are synchronized.
+
+## Technical Plan Summary
+
+Update the canonical docs after command contracts settle. Keep README concise and put details in references/templates.
+
+## Suggested Steps
+
+1. Update command reference.
+2. Update CLI UX guide.
+3. Update generated command/onboarding templates.
+4. Update README_FOR_AI and ROADMAP.
+5. Add concise README mention only if useful.
+6. Run docs validation and spec validation.
+
+## Restrictions
+
+- Do not claim npm publication.
+- Do not add implementation code.
+- Do not duplicate full procedure in root README.
+
+## Risks
+
+- Generated templates can drift from root docs.
+
+## Completion Checklist
+
+- [ ] Repo docs updated.
+- [ ] Generated templates updated.
+- [ ] README_FOR_AI synchronized.
+- [ ] Spec validation passes.

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-06-docs-templates-alignment/slice.json

@@ -0,0 +1,84 @@
+{
+  "slice_id": "slice-06-docs-templates-alignment",
+  "ticket": "QUIVER-31-06",
+  "type": "documentation",
+  "title": "Documentation and generated template alignment",
+  "objective": "Document the new agent model setup contract in repo docs and generated project guidance.",
+  "description": "Explains model ids vs display names, known catalog limitations, interactive setup, script setup, model listing, doctor, repair, and legacy-profile repair guidance.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v31-docs-templates-alignment",
+    "branch_name": "feature/QUIVER-31-06-v31-docs-templates-alignment"
+  },
+  "files": [
+    "README.md",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "docs/CLI_UX_GUIDE.md",
+    "docs/reference/commands.md",
+    "docs/COMMANDS.md.template",
+    "docs/AI_ONBOARDING_PROMPT.md.template",
+    "docs/AI_CONTEXT.md.template"
+  ],
+  "expected_read_paths": [
+    "SPEC.md",
+    "README_FOR_AI.md",
+    "README.md",
+    "docs/CLI_UX_GUIDE.md",
+    "docs/reference/commands.md",
+    "docs/COMMANDS.md.template"
+  ],
+  "allowed_write_paths": [
+    "README.md",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "docs/CLI_UX_GUIDE.md",
+    "docs/reference/commands.md",
+    "docs/COMMANDS.md.template",
+    "docs/AI_ONBOARDING_PROMPT.md.template",
+    "docs/AI_CONTEXT.md.template",
+    "specs/quiver-v31-ai-model-catalog-agent-selection/**"
+  ],
+  "depends_on": [
+    "slice-04-shared-preflight-provider-errors",
+    "slice-05-ai-models-list"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Docs should be written after final command contracts settle.",
+  "must": [
+    "Update README only with concise public-facing guidance if needed.",
+    "Update README_FOR_AI as source of truth.",
+    "Update command reference and CLI UX guide.",
+    "Update generated command templates.",
+    "Document known catalog vs available account model.",
+    "Document no-TTY/script-safe setup.",
+    "Document legacy repair flow for projects with bad profile models."
+  ],
+  "not_included": [
+    "Implementation code.",
+    "Long duplicated step-by-step content in root README.",
+    "Claiming npm publication."
+  ],
+  "acceptance": [
+    "Docs explain `model` vs `displayName`.",
+    "Docs explain catalog entries are known by Quiver, not guaranteed available.",
+    "Docs include `ai models list`, `ai agent doctor`, and `ai agent repair --dry-run`.",
+    "Generated project guidance includes current setup flow where appropriate.",
+    "README_FOR_AI stays synchronized with implemented behavior."
+  ],
+  "tests": [
+    "git diff --check",
+    "node bin/create-quiver.js --help",
+    "node bin/create-quiver.js spec validate specs/quiver-v31-ai-model-catalog-agent-selection"
+  ],
+  "validation_hints": [
+    "Keep root README concise.",
+    "Do not say v31 is shipped until release publication is complete."
+  ],
+  "estimated_hours": 5,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 3,
+  "completed_at": "2026-05-27"
+}

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-07-tests-smokes-release-readiness/CLOSURE_BRIEF.md

@@ -0,0 +1,32 @@
+# CLOSURE_BRIEF - slice-07 Tests, smokes, package dry-run, and release readiness
+
+## Summary
+
+Completed v31 release-readiness validation, updated package smoke coverage for the new model/profile help contract, and recorded final evidence.
+
+## Validation Against Acceptance Criteria
+
+- [x] Full test suite passed.
+- [x] Smoke suites passed.
+- [x] Package smoke passed.
+- [x] npm pack dry-run passed.
+- [x] Evidence report completed.
+
+## Relevant Changes
+
+- Corrected CLI help and flow guidance so `--model` is documented as a technical model id.
+- Updated tests and smoke script expectations to assert current `ai agent doctor`, `ai agent repair`, `ai models list`, and `--model <model-id>` help output.
+- Updated `CHANGELOG.md`, `README_FOR_AI.md`, `ROADMAP.md`, `STATUS.md`, `EVIDENCE_REPORT.md`, and `pr.md` for v31 release readiness.
+
+## Pending
+
+PR creation and npm publication require explicit human approval.
+
+## Remaining Risks
+
+- Catalog entries are known by Quiver and can become stale.
+- Account-level model availability still depends on provider CLI/account access and should be validated live only when the user opts in.
+
+## Future Recommendations
+
+Publish only after the human confirms release intent and npm authentication is ready.