create-quiver 0.15.0 → 0.15.2

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.

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

@@ -0,0 +1,59 @@
+# EXECUTION_BRIEF - slice-07 Tests, smokes, package dry-run, and release readiness
+
+## Context
+
+The v31 changes touch core AI command behavior and agent profile setup. Release readiness must prove backward compatibility, no-TTY safety, JSON cleanliness, and package safety.
+
+## Objective
+
+Close v31 with full validation, evidence, and release readiness without publishing npm.
+
+## Scope
+
+- tests and smoke suites
+- final docs/evidence updates
+- `CHANGELOG.md`
+- `README_FOR_AI.md`
+- `ROADMAP.md`
+- v31 spec closure files
+
+## Acceptance Criteria
+
+- Full test suite passes.
+- Smoke suites pass.
+- Package smoke and npm pack dry-run pass.
+- Spec validation passes.
+- Final evidence is recorded.
+- Known remaining risks are documented.
+
+## Technical Plan Summary
+
+Run final validation after every implementation and docs slice, then update status/evidence/PR body/closure briefs.
+
+## Suggested Steps
+
+1. Run focused tests from prior slices if needed.
+2. Run full suite.
+3. Run smoke suites.
+4. Run package safety and npm pack dry-run.
+5. Validate spec.
+6. Update final evidence and status.
+
+## Restrictions
+
+- Do not publish npm.
+- Do not skip failed tests.
+- Do not add new product scope.
+
+## Risks
+
+- Live provider validation depends on local provider auth and should be documented separately.
+- Catalog staleness remains a known operational risk.
+
+## Completion Checklist
+
+- [ ] Full tests pass.
+- [ ] Smokes pass.
+- [ ] Package dry-run passes.
+- [ ] Evidence report completed.
+- [ ] PR body updated.

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

@@ -0,0 +1,94 @@
+{
+  "slice_id": "slice-07-tests-smokes-release-readiness",
+  "ticket": "QUIVER-31-07",
+  "type": "release",
+  "title": "Tests, smokes, package dry-run, and release readiness",
+  "objective": "Close the v31 spec with comprehensive validation, evidence, and package readiness.",
+  "description": "Runs full tests, smoke suites, package safety, npm pack dry-run, spec validation, and final docs/evidence closure.",
+  "git": {
+    "branch_type": "feature",
+    "base_branch": "main",
+    "branch_slug": "v31-tests-smokes-release-readiness",
+    "branch_name": "feature/QUIVER-31-07-v31-tests-smokes-release-readiness"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/commands/flow.js",
+    "tests/**",
+    "scripts/ci/**",
+    "specs/quiver-v31-ai-model-catalog-agent-selection/**"
+  ],
+  "expected_read_paths": [
+    "SPEC.md",
+    "README_FOR_AI.md",
+    "CHANGELOG.md",
+    "ROADMAP.md",
+    "scripts/release-quiver.sh",
+    "scripts/package-quiver.sh",
+    "tests/**"
+  ],
+  "allowed_write_paths": [
+    "CHANGELOG.md",
+    "README_FOR_AI.md",
+    "ROADMAP.md",
+    "src/create-quiver/index.js",
+    "src/create-quiver/commands/ai.js",
+    "src/create-quiver/commands/flow.js",
+    "tests/**",
+    "scripts/ci/**",
+    "specs/quiver-v31-ai-model-catalog-agent-selection/**"
+  ],
+  "depends_on": [
+    "slice-02-interactive-agent-set-selectors",
+    "slice-03-agent-doctor-repair",
+    "slice-04-shared-preflight-provider-errors",
+    "slice-05-ai-models-list",
+    "slice-06-docs-templates-alignment"
+  ],
+  "parallel_safe": "no",
+  "parallel_safe_reason": "Final release validation depends on every implementation and docs slice.",
+  "must": [
+    "Run full test suite.",
+    "Run smoke suites.",
+    "Run package safety and npm pack dry-run.",
+    "Validate spec.",
+    "Update evidence report, status, closure briefs, and PR body.",
+    "Do not publish npm without explicit release approval."
+  ],
+  "not_included": [
+    "Publishing npm.",
+    "Skipping failed tests.",
+    "Adding new product scope."
+  ],
+  "acceptance": [
+    "Full suite passes.",
+    "Smoke suites pass.",
+    "Package smoke and npm pack dry-run pass.",
+    "Spec validation passes.",
+    "Final evidence is recorded.",
+    "Known remaining risks are documented."
+  ],
+  "tests": [
+    "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"
+  ],
+  "validation_hints": [
+    "Include legacy bad-profile fixture coverage.",
+    "Document any live provider smoke separately from automated tests."
+  ],
+  "estimated_hours": 6,
+  "status": "completed",
+  "blocked_reason": null,
+  "actual_hours": 5,
+  "completed_at": "2026-05-27"
+}

package/specs/quiver-v32-npx-installation-guidance/EVIDENCE_REPORT.md

@@ -0,0 +1,26 @@
+# Evidence Report - Quiver v32 npx Installation Guidance
+
+## Summary
+
+Documentation-only change. No product code was modified.
+
+## Evidence
+
+| Command | Status | Notes |
+|---|---|---|
+| `git diff --check` | Passed | No whitespace errors. |
+| `node bin/create-quiver.js spec validate specs/quiver-v32-npx-installation-guidance` | Passed | Spec package validated with one completed slice. |
+
+## Slice Evidence
+
+| Slice | Status | Evidence |
+|---|---|---|
+| `slice-00-installation-docs` | Completed | README, installation guide, troubleshooting, templates, command reference, source-of-truth docs, and PR body updated. |
+
+## Manual Review
+
+- README now explains `npx` vs local installation.
+- A dedicated installation guide explains when `node_modules` is expected.
+- Troubleshooting includes the `node_modules` confusion case.
+- Generated documentation templates include the same guidance.
+- `README_FOR_AI.md` is synchronized.

package/specs/quiver-v32-npx-installation-guidance/SPEC.md

@@ -0,0 +1,55 @@
+# Quiver v32 - npx Installation Guidance
+
+## Objective
+
+Clarify the expected installation behavior of Quiver when users run it with `npx`, especially why it does not appear in project `node_modules` unless installed explicitly as a development dependency.
+
+## Problem
+
+Users can run:
+
+```bash
+npx --yes create-quiver@latest ...
+```
+
+and expect the package to appear in `node_modules`. That is not how `npx` works, but the repository documentation did not explain the distinction clearly enough.
+
+## Scope
+
+- Add concise public-facing guidance to `README.md`.
+- Add a deeper installation guide under `docs/getting-started/`.
+- Add troubleshooting guidance for the common `node_modules` confusion.
+- Update generated-project troubleshooting and command templates.
+- Keep `README_FOR_AI.md` synchronized as the AI source of truth.
+
+## Non-Scope
+
+- No product code changes.
+- No npm publication.
+- No changes to package installation behavior.
+- No automatic local install changes.
+
+## Acceptance Criteria
+
+- Given a user runs Quiver with `npx --yes create-quiver@latest`, when they read the README, then they understand why Quiver may not appear in `node_modules`.
+- Given a team wants a pinned Quiver version, when they read the installation guide, then they can install `create-quiver` as a `devDependency`.
+- Given a user searches troubleshooting, when they see the `node_modules` entry, then they get the expected behavior, recovery path, and relevant links.
+- Given generated project docs are created from templates, when troubleshooting and command docs are inspected, then the same `npx` vs local install contract is represented.
+- Given an AI agent uses `README_FOR_AI.md`, when it explains installation, then it does not recommend global install and correctly distinguishes `npx` from local devDependency usage.
+
+## Files
+
+- `README.md`
+- `README_FOR_AI.md`
+- `docs/getting-started/installation.md`
+- `docs/reference/commands.md`
+- `docs/TROUBLESHOOTING.md`
+- `docs/TROUBLESHOOTING.md.template`
+- `docs/COMMANDS.md.template`
+- `specs/quiver-v32-npx-installation-guidance/**`
+
+## Validation
+
+- `git diff --check`
+- `node bin/create-quiver.js spec validate specs/quiver-v32-npx-installation-guidance`
+- Documentation review for link consistency and scope.

package/specs/quiver-v32-npx-installation-guidance/STATUS.md

@@ -0,0 +1,23 @@
+# Status - Quiver v32 npx Installation Guidance
+
+**Overall status:** Completed, pending PR
+**Created:** 2026-05-27
+**Current slice:** slice-00 completed
+
+## Summary
+
+This documentation-only spec clarifies that `npx --yes create-quiver@latest` runs Quiver from npm's execution cache and does not install it into project `node_modules`. It documents when teams should install `create-quiver` as a local `devDependency`.
+
+## Slice Status
+
+| Slice | Status | Notes |
+|---|---|---|
+| slice-00-installation-docs | Completed | README, installation guide, troubleshooting, templates, command reference, source-of-truth docs, and PR body updated. |
+
+## Current Blockers
+
+- None.
+
+## Next Step
+
+Open the documentation PR.