create-quiver 0.14.1 → 0.15.1

package/specs/quiver-v31-ai-model-catalog-agent-selection/EVIDENCE_REPORT.md

@@ -0,0 +1,185 @@
+# Evidence Report - Quiver v31 AI Model Catalog and Agent Selection
+
+## Summary
+
+This report starts with documentation-only evidence for `slice-00`. Product implementation evidence must be appended by each later slice.
+
+## slice-00 - Spec foundation
+
+### Completed
+
+- Created v31 spec package with `SPEC.md`, `STATUS.md`, `EXECUTION_PLAN.md`, `EVIDENCE_REPORT.md`, and `pr.md`.
+- Created 8 slice folders with `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- Synchronized `README_FOR_AI.md` and `ROADMAP.md` to mark v31 as planned work.
+
+### Validation
+
+- `find specs/quiver-v31-ai-model-catalog-agent-selection -name 'slice.json' -print -exec node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8')); console.log('ok', process.argv[1])" {} \;` passed for 8 slice files.
+- `node bin/create-quiver.js spec validate specs/quiver-v31-ai-model-catalog-agent-selection` passed and reported 8 slices.
+- `git diff --check` passed.
+
+### Risks Observed During Validation
+
+- The repo is currently ahead of `origin/main` by the local `v0.15.0` release commit from the prior npm publication attempt. This slice does not modify or resolve that release state.
+
+## Later Slices
+
+Each implementation slice must append:
+
+- commands executed;
+- tests or smokes run;
+- files changed;
+- validation result;
+- human and JSON output evidence when applicable;
+- remaining risks;
+- evidence location.
+
+## slice-01 - Local model catalog and alias normalization
+
+### Completed
+
+- Added `src/create-quiver/lib/ai/model-catalog.js` as the local, versioned model catalog source of truth.
+- Added Codex, Claude, and Gemini known model entries with aliases, role recommendations, cost/quality/stability metadata, and custom model support.
+- Added tolerant alias normalization for case, spaces, dashes, and punctuation.
+- Updated agent profile creation to normalize known visual aliases into technical model ids while preserving human `displayName`.
+- Preserved free-form custom model support and added optional profile metadata: `modelSource`, `modelAlias`, `validation_status`, `validated_at`, and `validation_error`.
+
+### Validation
+
+- `node --test tests/lib/model-catalog.test.js tests/lib/agent-profiles.test.js` passed: 10 tests.
+- `git diff --check` passed.
+
+### Risks
+
+- Catalog entries are local and can become stale. Later docs must keep the wording "known by Quiver" and avoid implying account-level availability.
+- Live provider validation and command preflight are intentionally deferred to later slices.
+
+## slice-02 - Interactive agent set provider and model selectors
+
+### Completed
+
+- Added interactive provider/model resolution for `ai agent set <role>`.
+- Added no-TTY/CI safeguards requiring explicit `--provider` and `--model`.
+- Added existing profile actions: update current, create new, change default, and cancel before writes.
+- Added provider CLI status hints in provider choices.
+- Added role-ordered model choices from the local catalog.
+- Added custom model id and display-name capture.
+- Added a write summary before saving profiles selected through prompts.
+- Made `ai agent` dispatch async-safe.
+
+### Validation
+
+- `node --test tests/commands/ai-agent.test.js tests/lib/cli-selectors.test.js tests/lib/model-catalog.test.js tests/lib/agent-profiles.test.js` passed: 30 tests.
+
+### Risks
+
+- Provider status is best-effort CLI detection and does not guarantee account-level model availability.
+- Interactive rendering is validated through injectable prompt helpers; real terminal behavior should be covered by smoke testing in the final slice.
+
+## slice-03 - Agent profile doctor and repair dry-run
+
+### Completed
+
+- Added pure profile diagnostics that evaluate every configured agent profile.
+- Added `ai agent doctor` with human output sections `Checks` and `Suggested fixes`.
+- Added `ai agent doctor --json` with parseable JSON output and no human prose.
+- Added exit code 1 when doctor errors are present.
+- Added `ai agent repair --dry-run` with before/after changes and no writes.
+- Added safe catalog-alias repair for legacy profiles such as `model: "GPT 5.5"`.
+- Added warnings for custom unvalidated models and provider CLI checks.
+- Updated CLI help for `ai agent doctor` and `ai agent repair`.
+
+### Validation
+
+- `node --test tests/commands/ai-agent.test.js tests/lib/agent-profiles.test.js tests/lib/model-catalog.test.js tests/lib/cli-selectors.test.js` passed: 36 tests.
+
+### Risks
+
+- Provider CLI checks are best-effort and do not prove selected model entitlement.
+- Repair write mode is intentionally unavailable until dry-run behavior is dogfooded.
+
+## slice-04 - Shared model preflight and provider error extraction
+
+### Completed
+
+- Added shared provider model alias resolution.
+- Added blocking policy for display aliases read from persisted profiles.
+- Added normalization for CLI `--model` display aliases in dry-run and invocation output.
+- Added provider error cause extraction for invalid model, auth, missing CLI, timeout, and generic failures.
+- Added provider failure serialization for non-zero exits where stderr contains the useful cause.
+- Applied model preflight options to planner, reviewer, repair-plan, execute-slice, and execute-plan runtime paths.
+- Added tests for `GPT 5.5` CLI override normalization, legacy profile blocking before provider execution, invalid model priority over MCP noise, and secret redaction.
+
+### Validation
+
+- `node --test tests/lib/ai-providers.test.js tests/commands/ai-prepare-context-planner.test.js tests/commands/ai-execute-slice.test.js` passed: 35 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` passed: 78 tests.
+
+### Risks
+
+- Provider stderr patterns can change; future observed failures should become fixtures.
+- Custom models remain allowed and can only be proven through live provider validation.
+
+## slice-05 - AI models list command
+
+### Completed
+
+- Added `ai models list`.
+- Added `--provider <id>` filtering for catalog providers.
+- Added `--json` clean machine output with `catalogVersion` and `lastUpdated`.
+- Updated CLI help and contract tests.
+- Added human output wording that says models are known by Quiver and avoids claiming availability.
+
+### Validation
+
+- `node --test tests/commands/ai-models.test.js tests/commands/cli-contract.test.js` passed: 11 tests.
+
+### Risks
+
+- The model catalog is local and can become stale until Quiver has a remote/update mechanism.
+
+## slice-06 - Documentation and generated template alignment
+
+### Completed
+
+- Updated `README.md` with concise public-facing model catalog, agent setup, doctor, and repair commands.
+- Updated `docs/reference/commands.md` with interactive and script-safe agent setup, `ai models list`, `ai agent doctor`, and `ai agent repair --dry-run`.
+- Updated `docs/CLI_UX_GUIDE.md` with the profile data contract: `model` is the provider technical id and `displayName` is the human label.
+- Updated generated project templates: `docs/COMMANDS.md.template`, `docs/AI_ONBOARDING_PROMPT.md.template`, and `docs/AI_CONTEXT.md.template`.
+- Updated `README_FOR_AI.md`, `ROADMAP.md`, `STATUS.md`, and the slice closure to reflect completed docs/templates alignment without claiming package publication.
+
+### Validation
+
+- `node bin/create-quiver.js --help` passed and exposed `ai models list`, `ai agent doctor`, and `ai agent repair --dry-run`.
+- `node bin/create-quiver.js ai models list --provider codex` passed and printed "Models are known by Quiver; provider account access is not guaranteed."
+- `node bin/create-quiver.js spec validate specs/quiver-v31-ai-model-catalog-agent-selection` passed with a warning before this evidence section was appended.
+- `git diff --check` passed.
+
+### Risks
+
+- The final release-readiness slice must verify the CLI help contract after docs alignment.
+- The local model catalog can become stale until Quiver has a remote/update mechanism.
+
+## slice-07 - Tests, smokes, package dry-run, and release readiness
+
+### Completed
+
+- Corrected remaining CLI help/flow guidance so `--model` is documented as a technical model id, not a free-form label.
+- Updated contract tests and `smoke:create-quiver` packaged-help assertions for `ai agent doctor`, `ai agent repair --dry-run`, `ai models list`, and `--model <model-id>`.
+- Updated release docs: `CHANGELOG.md`, `README_FOR_AI.md`, `ROADMAP.md`, `STATUS.md`, `pr.md`, and this evidence report.
+
+### Validation
+
+- `node --test tests/commands/cli-contract.test.js tests/commands/flow.test.js tests/commands/ai-agent.test.js tests/lib/agent-profiles.test.js` passed: 44 tests.
+- `node --test tests/**/*.test.js` passed: 482 tests.
+- `npm run smoke:doctor-fixtures` passed: 13 fixture states.
+- `npm run smoke:create-quiver` passed after updating packaged-help expectations.
+- `npm run smoke:guided-workflow` passed.
+- `npm run package:quiver` passed with package smoke.
+- `npm pack --dry-run` passed and generated dry-run tarball details for `create-quiver@0.15.0`.
+
+### Risks
+
+- npm publication was not performed and still requires explicit human approval.
+- Live provider model entitlement was not tested because it depends on provider CLI/account access and may consume tokens.
+- The local model catalog remains manually maintained until Quiver has a remote/update mechanism.

package/specs/quiver-v31-ai-model-catalog-agent-selection/EXECUTION_PLAN.md

@@ -0,0 +1,85 @@
+# Execution Plan - Quiver v31 AI Model Catalog and Agent Selection
+
+## Execution Order
+
+```mermaid
+flowchart TD
+    S00[slice-00: Spec foundation]
+    S01[slice-01: Model catalog and alias normalization]
+    S02[slice-02: Interactive agent set selectors]
+    S03[slice-03: Agent doctor and repair dry-run]
+    S04[slice-04: Shared preflight and provider errors]
+    S05[slice-05: AI models list]
+    S06[slice-06: Docs and templates alignment]
+    S07[slice-07: Tests, smokes, and release readiness]
+
+    S00 --> S01
+    S01 --> S02
+    S01 --> S03
+    S01 --> S04
+    S01 --> S05
+    S02 --> S03
+    S03 --> S04
+    S04 --> S06
+    S05 --> S06
+    S06 --> S07
+```
+
+## Waves
+
+### Wave 0 - Sequential
+
+1. `slice-00-spec-foundation`
+
+This slice must run first. It commits the approved spec, every slice, handoffs, execution plan, PR body, and source-of-truth documentation sync.
+
+### Wave 1 - Sequential Core
+
+1. `slice-01-model-catalog-alias-normalization`
+
+The catalog and model-resolution contract must exist before selectors, doctor, repair, or live command preflight can use it.
+
+### Wave 2 - Parallel after slice-01
+
+- `slice-02-interactive-agent-set-selectors`
+- `slice-05-ai-models-list`
+
+These can run in parallel if their write scopes stay separated.
+
+### Wave 3 - Sequential Diagnostics and Runtime
+
+1. `slice-03-agent-doctor-repair`
+2. `slice-04-shared-preflight-provider-errors`
+
+Doctor/repair should land before command preflight so existing-profile diagnostics and preflight reuse the same issue classification.
+
+### Wave 4 - Sequential Docs
+
+1. `slice-06-docs-templates-alignment`
+
+Docs depend on the final command names and output contracts.
+
+### Wave 5 - Sequential Close
+
+1. `slice-07-tests-smokes-release-readiness`
+
+Final validation is never parallel-safe.
+
+## Parallel Safety Notes
+
+- Do not run any implementation slice before `slice-00`.
+- Do not implement selectors before catalog helpers exist.
+- Do not add live command preflight before doctor/repair issue classification is stable.
+- `slice-02` and `slice-05` may both touch `commands/ai.js`; if conflicts are likely, run `slice-02` first.
+- `slice-07` must close the spec after all other slices.
+
+## Recommended Commit Order
+
+1. `docs: add v31 ai model catalog spec`
+2. `feat: add ai model catalog normalization`
+3. `feat: add interactive agent model selectors`
+4. `feat: add agent profile doctor repair`
+5. `feat: add ai model preflight errors`
+6. `feat: add ai models list`
+7. `docs: document ai model catalog setup`
+8. `docs: close v31 model catalog release readiness`

package/specs/quiver-v31-ai-model-catalog-agent-selection/SPEC.md

@@ -0,0 +1,337 @@
+# Spec - Quiver v31 AI Model Catalog and Agent Selection
+
+## Objective
+
+Make AI agent configuration safer and easier by letting users select providers and known models from Quiver-guided choices instead of memorizing provider-specific model ids.
+
+The immediate trigger is a real dogfooding failure: a project stored `model: "GPT 5.5"` for a Codex planner, but Codex requires the technical id `gpt-5.5`. Quiver showed `provider run failed` instead of explaining that the saved model looked like a display name.
+
+## Problem
+
+Quiver currently stores free-form `model` values in agent profiles. That is flexible, but it lets users accidentally save a human-friendly model name where the provider CLI expects an exact technical id.
+
+This causes:
+
+- live AI commands to fail late;
+- unclear `provider run failed` errors;
+- repeated trial and error;
+- poor first-run experience for Planner, Executor, Reviewer, and Doctor setup;
+- fragile profile reuse across projects.
+
+## Product Requirements
+
+### Known Providers
+
+The first iteration supports only providers already implemented by Quiver:
+
+- `codex`
+- `claude`
+- `gemini`
+
+Do not expose Qwen or other providers in the main selector until Quiver has a real provider adapter for them.
+
+### Known Model Catalog
+
+Add a local, versioned model catalog owned by Quiver. The catalog is advisory, not a guarantee that a model is enabled for the user's account.
+
+Required catalog metadata:
+
+- provider id;
+- model id;
+- display name;
+- aliases;
+- recommended roles;
+- cost tier;
+- quality tier;
+- stability;
+- notes;
+- catalog version;
+- last updated date.
+
+Required Codex entries:
+
+- `gpt-5.5` / `GPT 5.5`
+- `gpt-5.4` / `GPT 5.4`
+- `gpt-5.4-mini` / `GPT 5.4 mini`
+- `gpt-5.3-codex` / `GPT 5.3 Codex`
+- `gpt-5.3-codex-spark` / `GPT 5.3 Codex Spark`
+- `custom`
+
+Required Claude entries:
+
+- `opus` / `Claude Opus`
+- `sonnet` / `Claude Sonnet`
+- `haiku` / `Claude Haiku`
+- versioned known entries for Opus, Sonnet, and Haiku where Quiver documents them as known local catalog choices;
+- `custom`
+
+Required Gemini entries:
+
+- `gemini-3.1-pro-preview` / `Gemini 3.1 Pro Preview`
+- `gemini-3.5-flash` / `Gemini 3.5 Flash`
+- `gemini-3.1-flash-lite` / `Gemini 3.1 Flash-Lite`
+- `gemini-3.1-pro-preview-customtools` / `Gemini 3.1 Pro Custom Tools`
+- `custom`
+
+Use the phrase "known by Quiver" in human output. Do not call catalog entries "available" unless a live validation has passed.
+
+### Agent Profile Contract
+
+The persisted profile must separate technical and human values:
+
+```json
+{
+  "provider": "codex",
+  "model": "gpt-5.5",
+  "displayName": "GPT 5.5",
+  "modelSource": "catalog",
+  "validation_status": "not-tested"
+}
+```
+
+Rules:
+
+- `model` is the technical id sent to the provider CLI.
+- `displayName` is the human label shown in Quiver output.
+- Existing v2 profiles remain readable.
+- New fields must be optional unless a schema bump is required.
+- Profiles must never store provider secrets.
+
+### Interactive Agent Setup
+
+When a user runs:
+
+```bash
+npx create-quiver ai agent set planner
+```
+
+in an interactive terminal, Quiver should guide setup:
+
+1. show existing role profiles if present;
+2. ask whether to update current profile, create a new profile, change default, or cancel;
+3. show provider choices with CLI install status;
+4. show known models for the selected provider, ordered by the requested role;
+5. allow `custom`;
+6. show a summary before writing;
+7. optionally run a live validation test before saving.
+
+In CI/no-TTY, the same command must not hang. It must fail with an actionable message asking for explicit `--provider` and `--model`.
+
+### Alias Normalization
+
+Known aliases must be matched case-insensitively and tolerate spaces, dashes, and common title casing.
+
+Examples that must resolve to `gpt-5.5`:
+
+- `GPT 5.5`
+- `gpt 5.5`
+- `Gpt-5.5`
+- `gpt-5.5`
+
+When a command receives a known display alias through `--model`, Quiver must normalize it or block before provider execution with a concrete suggestion.
+
+### Custom Models
+
+Users can select or pass custom models. Quiver should allow them, but mark them as not validated unless a live provider test passes.
+
+For `custom`, prompt for:
+
+- technical model id;
+- display name, defaulting to the id.
+
+### Optional Live Validation
+
+Interactive setup may offer a live validation:
+
+```txt
+This test executes the provider and may consume tokens.
+```
+
+Validation prompt:
+
+```txt
+Respond exactly: ok
+```
+
+Default timeout: 60 seconds.
+
+If output contains `ok`, mark validation passed. If it fails, do not save by default and show the relevant provider error.
+
+### Agent Doctor and Repair
+
+Add diagnostics for existing profiles:
+
+- missing provider;
+- missing model;
+- unsupported provider;
+- display alias stored in `model`;
+- custom model not validated;
+- provider CLI missing;
+- provider model flag unsupported;
+- duplicate display names;
+- multiple profiles per role and default profile.
+
+Add dry-run repair:
+
+```bash
+npx create-quiver ai agent repair --dry-run
+```
+
+It must propose changes without writing files. If a write mode is added, it must require explicit confirmation or `--yes`.
+
+### AI Models List
+
+Add:
+
+```bash
+npx create-quiver ai models list
+npx create-quiver ai models list --provider codex
+npx create-quiver ai models list --json
+```
+
+Human output must group by provider and show recommended roles. JSON output must include `catalogVersion` and `lastUpdated`.
+
+### Shared Preflight
+
+The model resolution and preflight logic must be shared by profile setup and live AI commands:
+
+- `ai prepare-context`
+- `ai onboard`
+- `ai plan`
+- `ai review-plan`
+- `ai revise`
+- `ai repair-plan`
+- `ai execute-slice`
+- `ai execute-plan`
+
+Any live provider execution must block before invoking the provider when a known bad model/display alias can be corrected safely.
+
+### Provider Error Extraction
+
+Provider errors can include noisy secondary lines, for example MCP auth warnings. Quiver must prioritize actionable causes:
+
+1. invalid or unsupported model;
+2. provider auth;
+3. CLI missing;
+4. timeout;
+5. secondary tool/MCP warnings.
+
+When possible, replace generic `provider run failed` with the provider's useful message plus suggested Quiver commands.
+
+### Documentation
+
+Update repository docs and generated templates:
+
+- `README.md` when the public onboarding flow needs a short mention;
+- `README_FOR_AI.md` as source of truth;
+- `ROADMAP.md`;
+- `docs/CLI_UX_GUIDE.md`;
+- `docs/reference/commands.md`;
+- `docs/COMMANDS.md.template`;
+- generated onboarding docs/templates if agent setup guidance is exposed to new projects.
+
+Docs must explain:
+
+- `model` vs `displayName`;
+- known catalog vs account availability;
+- interactive setup;
+- no-TTY/script setup;
+- `ai models list`;
+- `ai agent doctor`;
+- `ai agent repair --dry-run`;
+- how to repair profiles from Quiver versions before this spec.
+
+## Acceptance Criteria
+
+### Interactive Setup
+
+- Given a Quiver project, when `ai agent set planner` runs in a TTY without provider/model flags, then Quiver shows an interactive provider selector.
+- Given the provider selector, when providers are listed, then Codex, Claude, and Gemini are shown with CLI install status.
+- Given a selected provider, when the model selector opens, then Quiver shows models known by Quiver plus `custom`.
+- Given a known model selection, when the profile is saved, then `model` contains the technical id and `displayName` contains the human label.
+- Given an existing profile, when interactive setup starts, then Quiver shows the current profile and lets the user update, create, change default, or cancel.
+- Given a canceled selector, then Quiver writes no files and reports configuration canceled.
+
+### Non-Interactive Safety
+
+- Given CI/no-TTY, when `ai agent set planner` lacks enough flags, then Quiver exits without hanging and prints explicit flag guidance.
+- Given a scripted command with `--provider` and `--model`, then Quiver preserves non-interactive behavior.
+- Given `--dry-run` and a known alias, then Quiver previews the normalized profile without writing.
+
+### Catalog and Alias Behavior
+
+- Given Codex, Claude, or Gemini, when models are listed, then the required catalog entries and `custom` are present.
+- Given `GPT 5.5`, `gpt 5.5`, `Gpt-5.5`, or `gpt-5.5`, when the value is normalized for Codex, then the technical id resolves to `gpt-5.5`.
+- Given an ambiguous alias, then Quiver does not choose automatically in non-interactive mode and requests explicit selection or a concrete model id.
+- Given `custom`, then Quiver asks for technical id and display name, defaulting display name to the id.
+- Given a catalog model that was not live-tested, then Quiver describes it as known by Quiver, not available.
+
+### Live Validation
+
+- Given a user chooses live validation, then Quiver warns that the test can consume tokens before provider execution.
+- Given the validation returns output containing `ok`, then Quiver marks the profile as validation passed.
+- Given validation fails or times out, then Quiver does not save a passing validation state and shows the relevant error.
+- Given provider stderr includes secrets or sensitive-looking tokens, then Quiver redacts them before output or saved evidence.
+
+### Doctor and Repair
+
+- Given multiple profiles per role, `ai agent doctor` evaluates every profile and identifies the default.
+- Given an unsupported provider, doctor marks it as `error`.
+- Given a custom model not validated, doctor marks it as `warning`.
+- Given a display alias stored in `model`, doctor reports the issue and suggests `ai agent repair --dry-run`.
+- Given `ai agent repair --dry-run`, Quiver shows proposed before/after changes without modifying files.
+- Given `ai agent repair` without `--dry-run`, Quiver does not write without explicit confirmation or `--yes`.
+
+### AI Models List
+
+- Given `ai models list`, output is grouped by provider and includes recommended roles.
+- Given `ai models list --provider codex`, output only includes Codex catalog entries.
+- Given `ai models list --json`, output is valid JSON without colors or prose and includes `catalogVersion` and `lastUpdated`.
+
+### Shared Preflight and Provider Errors
+
+- Given any live AI command receives `--model "GPT 5.5"`, Quiver normalizes or blocks with suggestion before invoking the provider.
+- Given a profile with `model: "GPT 5.5"`, `ai prepare-context --with-planner` blocks before calling Codex and suggests `model: gpt-5.5`, `displayName: GPT 5.5`.
+- Given the provider emits multiple errors and one is an invalid model, Quiver reports invalid model as the primary cause.
+- Given dry-run for a provider/model, Quiver shows the real command that would execute.
+
+### Documentation and Release Readiness
+
+- Given the docs are read after implementation, they explain `model` vs `displayName`, known catalog limitations, setup flows, doctor, repair, and model listing.
+- Given generated project templates are inspected, they include current agent setup guidance where appropriate.
+- Given package readiness runs, tests cover catalog, aliases, selectors, no-TTY, JSON, doctor, repair, provider error extraction, and legacy profile compatibility.
+- Given package dry-run runs, the catalog is included and local `.quiver/` state is not published.
+
+## Non-Scope
+
+- Remote API for dynamic model catalog updates.
+- Qwen provider support before an adapter exists.
+- Installing provider CLIs.
+- Editing provider credentials.
+- Guaranteeing account-level model access without a live validation.
+- Publishing npm as part of implementation.
+
+## Technical Plan
+
+1. Create `src/create-quiver/lib/ai/model-catalog.js` as the single source of truth.
+2. Add alias normalization and model resolution helpers.
+3. Extend agent profile setup with interactive provider/model selection.
+4. Preserve non-interactive/CI behavior and add no-TTY guardrails.
+5. Add `ai agent doctor` and `ai agent repair --dry-run`.
+6. Add shared model preflight for every live AI command.
+7. Improve provider error extraction and actionable messages.
+8. Add `ai models list` with human and JSON output.
+9. Update docs, templates, and source-of-truth guidance.
+10. Add tests, smokes, package dry-run, and final evidence.
+
+## Risks
+
+- Model catalogs can become stale.
+- Provider CLIs can change model flags or behavior.
+- Live validation can consume tokens.
+- Some accounts can lack access to catalog models.
+- Existing profiles may contain user-specific custom values.
+
+## Rollback
+
+Revert slice commits in reverse order. The current free-form `model` path must remain available through non-interactive flags and custom model support.

package/specs/quiver-v31-ai-model-catalog-agent-selection/STATUS.md

@@ -0,0 +1,30 @@
+# Status - Quiver v31 AI Model Catalog and Agent Selection
+
+**Overall status:** Release-ready, pending PR/package publication
+**Created:** 2026-05-27
+**Current slice:** slice-07 completed
+
+## Summary
+
+This spec improves AI agent setup by adding a local model catalog, provider/model selectors, alias normalization, profile diagnostics, repair dry-runs, shared model preflight, clearer provider errors, command documentation, generated-template guidance, and release-readiness evidence.
+
+## Slice Status
+
+| Slice | Status | Notes |
+|---|---|---|
+| slice-00-spec-foundation | Completed | Documentation package created, source-of-truth docs synchronized, validation passed. |
+| slice-01-model-catalog-alias-normalization | Completed | Local catalog, role metadata, aliases, custom model support, and profile normalization added. |
+| slice-02-interactive-agent-set-selectors | Completed | Guided `ai agent set <role>` provider/model flow, no-TTY guardrails, custom models, and profile actions added. |
+| slice-03-agent-doctor-repair | Completed | Profile diagnostics, JSON output, error exit codes, and dry-run alias repair added. |
+| slice-04-shared-preflight-provider-errors | Completed | Shared alias preflight, CLI override normalization, and provider error extraction added. |
+| slice-05-ai-models-list | Completed | `ai models list` human/JSON output, provider filter, and help contract added. |
+| slice-06-docs-templates-alignment | Completed | README, command reference, CLI UX guide, AI templates, roadmap, and AI source of truth aligned with the model/profile contract. |
+| slice-07-tests-smokes-release-readiness | Completed | Full suite, smokes, package safety, npm pack dry-run, spec validation, and final evidence completed. |
+
+## Current Blockers
+
+- None. Implementation must begin with `slice-00`.
+
+## Next Step
+
+Open the PR or publish only after explicit human approval.