create-quiver 0.15.0 → 0.15.2

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.

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

@@ -0,0 +1,98 @@
+## Title
+
+Quiver v31: AI model catalog and guided agent setup
+
+## Summary
+
+- Adds a local Quiver model catalog for Codex, Claude, and Gemini.
+- Separates technical model ids from human display names.
+- Adds guided provider/model selection for agent profiles.
+- Adds diagnostics and repair dry-run for existing profile misconfigurations.
+- Improves live AI command preflight and provider error messages.
+
+## Scope
+
+- Local model catalog and alias normalization.
+- Interactive `ai agent set <role>` provider/model flow.
+- `ai models list`.
+- `ai agent doctor`.
+- `ai agent repair --dry-run`.
+- Shared model preflight for live AI commands.
+- Better invalid-model/provider error extraction.
+- Documentation, templates, tests, smokes, and package readiness.
+
+## Files
+
+Expected areas:
+
+- `src/create-quiver/lib/ai/model-catalog.js`
+- `src/create-quiver/lib/agent-profiles.js`
+- `src/create-quiver/lib/ai/providers.js`
+- `src/create-quiver/lib/cli/selectors.js`
+- `src/create-quiver/commands/ai.js`
+- `docs/**`
+- `README.md`
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+- `tests/**`
+- `specs/quiver-v31-ai-model-catalog-agent-selection/**`
+
+## How to Test (DETAILED - REQUIRED)
+
+### Required Environment
+
+- Node.js and npm.
+- Optional provider CLIs for live validation smoke tests.
+- A terminal that can run both TTY and no-TTY command checks.
+
+### Worktree Access
+
+- One dedicated branch/worktree for `quiver-v31-ai-model-catalog-agent-selection`.
+- One commit per slice.
+
+### Run the Project
+
+This is a CLI framework change. Run command-level tests and smoke commands from the Quiver repo root.
+
+### Use Cases
+
+- Configure a planner interactively with Codex and a known model.
+- Configure an executor with `custom`.
+- Run `ai agent doctor` against legacy profile fixtures.
+- Run `ai agent repair --dry-run` against `model: "GPT 5.5"`.
+- Run `ai models list` and `ai models list --json`.
+- Run `ai prepare-context --with-planner` with a bad display alias and verify Quiver blocks before Codex execution.
+- Verify no-TTY and JSON outputs do not prompt or colorize.
+
+### Technical Verification
+
+- `node --test tests/**/*.test.js`
+- `npm run smoke:create-quiver`
+- `npm run smoke:doctor-fixtures`
+- `npm run smoke:guided-workflow`
+- `npm run package:quiver`
+- `npm pack --dry-run`
+- `git diff --check`
+- `node bin/create-quiver.js spec validate specs/quiver-v31-ai-model-catalog-agent-selection`
+
+## Evidence
+
+- `node --test tests/**/*.test.js` passed: 482 tests.
+- `npm run smoke:create-quiver` passed.
+- `npm run smoke:doctor-fixtures` passed: 13 fixture states.
+- `npm run smoke:guided-workflow` passed.
+- `npm run package:quiver` passed.
+- `npm pack --dry-run` passed.
+- `git diff --check` passed.
+- `node bin/create-quiver.js spec validate specs/quiver-v31-ai-model-catalog-agent-selection` passed.
+
+## Rollback
+
+Revert slice commits in reverse order. Free-form custom model support and non-interactive profile setup must remain available during rollback.
+
+## Risks / Notes
+
+- Catalog models are known by Quiver, not guaranteed available for every account.
+- Live validation can consume tokens and must be opt-in.
+- Provider CLI behavior can change across versions.
+- Existing profiles can contain legitimate custom values and must not be overwritten without explicit confirmation.

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-00-spec-foundation/CLOSURE_BRIEF.md

@@ -0,0 +1,30 @@
+# CLOSURE_BRIEF - slice-00 Spec foundation and source-of-truth sync
+
+## Summary
+
+Created the approved v31 spec package and synchronized source-of-truth docs to record the planned AI model catalog and guided agent setup work.
+
+## Validation Against Acceptance Criteria
+
+- [x] Spec package exists and validates.
+- [x] Source-of-truth docs mention v31 as planned.
+- [x] No product code was modified.
+- [x] Evidence report updated.
+
+## Relevant Changes
+
+- Added `specs/quiver-v31-ai-model-catalog-agent-selection/**`.
+- Updated `README_FOR_AI.md`.
+- Updated `ROADMAP.md`.
+
+## Pending
+
+- Implement `slice-01-model-catalog-alias-normalization`.
+
+## Remaining Risks
+
+- Local `main` is ahead of `origin/main` by the prior `v0.15.0` release commit. This is unrelated to v31 implementation but should be resolved before the next package release.
+
+## Future Recommendations
+
+Execute implementation slices only after this documentary foundation is committed.

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-00-spec-foundation/EXECUTION_BRIEF.md

@@ -0,0 +1,51 @@
+# EXECUTION_BRIEF - slice-00 Spec foundation and source-of-truth sync
+
+## Context
+
+The v31 requirements and technical plan were approved to improve AI agent model selection after a real Codex failure caused by `model: "GPT 5.5"` instead of `model: "gpt-5.5"`.
+
+## Objective
+
+Publish the approved v31 spec package and synchronize source-of-truth docs without implementing product code.
+
+## Scope
+
+- `specs/quiver-v31-ai-model-catalog-agent-selection/**`
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+
+## Acceptance Criteria
+
+- The v31 spec package exists and validates.
+- Every slice has `slice.json`, `EXECUTION_BRIEF.md`, and `CLOSURE_BRIEF.md`.
+- Source-of-truth docs mention v31 as planned.
+- No product code is modified.
+
+## Technical Plan Summary
+
+Create the documentation foundation first so later executors can work from bounded slice handoffs.
+
+## Suggested Steps
+
+1. Review this spec package for completeness.
+2. Update `README_FOR_AI.md` and `ROADMAP.md` to mark v31 as planned.
+3. Run spec validation.
+4. Update `EVIDENCE_REPORT.md`, `STATUS.md`, and this closure brief.
+
+## Restrictions
+
+- Do not implement product code.
+- Do not change package version.
+- Do not claim npm publication.
+
+## Risks
+
+- Source-of-truth docs can drift if v31 is not mentioned.
+- The local repo may contain a pending release commit; do not alter it unless explicitly requested.
+
+## Completion Checklist
+
+- [ ] Source-of-truth docs synchronized.
+- [ ] Spec validation passes.
+- [ ] Evidence recorded.
+- [ ] No product code changed.

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-00-spec-foundation/slice.json

@@ -0,0 +1,62 @@
+{
+  "slice_id": "slice-00-spec-foundation",
+  "ticket": "QUIVER-31-00",
+  "type": "documentation",
+  "title": "Spec foundation and source-of-truth sync",
+  "objective": "Publish the approved v31 spec package and synchronize source-of-truth docs before implementation.",
+  "description": "Creates the spec, execution plan, PR body, evidence report, slice definitions, and handoffs for AI model catalog and guided agent setup.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v31-ai-model-catalog-agent-selection",
+    "branch_name": "feature/QUIVER-31-v31-ai-model-catalog-agent-selection"
+  },
+  "files": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "specs/quiver-v31-ai-model-catalog-agent-selection/**"
+  ],
+  "expected_read_paths": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "specs/quiver-v31-ai-model-catalog-agent-selection/SPEC.md"
+  ],
+  "allowed_write_paths": [
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "specs/quiver-v31-ai-model-catalog-agent-selection/**"
+  ],
+  "depends_on": [],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "The documentary foundation must land before every implementation slice.",
+  "must": [
+    "Commit the approved v31 spec package.",
+    "Ensure every slice has slice.json, EXECUTION_BRIEF.md, and CLOSURE_BRIEF.md.",
+    "Mark v31 as planned in source-of-truth docs without claiming implementation or npm publication.",
+    "Run spec validation and diff checks."
+  ],
+  "not_included": [
+    "Implementing product code.",
+    "Publishing npm.",
+    "Changing package version."
+  ],
+  "acceptance": [
+    "The v31 spec package exists and validates.",
+    "Source-of-truth docs mention v31 as planned.",
+    "No product code is modified.",
+    "Evidence report records documentation validation."
+  ],
+  "tests": [
+    "git diff --check",
+    "node bin/create-quiver.js spec validate specs/quiver-v31-ai-model-catalog-agent-selection"
+  ],
+  "validation_hints": [
+    "Confirm README_FOR_AI.md does not say v31 is implemented.",
+    "Confirm ROADMAP.md does not say v31 is shipped."
+  ],
+  "estimated_hours": 2,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 2,
+  "completed_at": "2026-05-27"
+}

package/specs/quiver-v31-ai-model-catalog-agent-selection/slices/slice-01-model-catalog-alias-normalization/CLOSURE_BRIEF.md

@@ -0,0 +1,32 @@
+# CLOSURE_BRIEF - slice-01 Local model catalog and alias normalization
+
+## Summary
+
+Implemented the local AI model catalog and connected known alias normalization to agent profile creation.
+
+## Validation Against Acceptance Criteria
+
+- [x] Catalog entries added.
+- [x] Alias normalization implemented.
+- [x] Custom models still allowed.
+- [x] Legacy profile compatibility preserved.
+
+## Relevant Changes
+
+- Added `src/create-quiver/lib/ai/model-catalog.js`.
+- Updated `src/create-quiver/lib/agent-profiles.js`.
+- Added `tests/lib/model-catalog.test.js`.
+- Updated `tests/lib/agent-profiles.test.js`.
+
+## Pending
+
+- Interactive setup, doctor/repair, live preflight, models list, and docs remain for later slices.
+
+## Remaining Risks
+
+- Catalog freshness remains a known operational risk until a future remote catalog exists.
+- Live provider availability is not guaranteed by catalog presence.
+
+## Future Recommendations
+
+Keep the catalog as the single source of truth until a remote catalog API exists.