create-quiver 0.10.0 → 0.12.0

package/README_FOR_AI.md

@@ -4,13 +4,22 @@ Use this guide when initializing a new project with Quiver or when explaining th
 
 The first AI job in a generated project is context preparation, not product implementation.
 
-Important: slice numbering resets inside each spec. `slice-01` is the first slice of that spec, not a global repo counter.
+Important: slice numbering resets inside each spec. `slice-00` is the mandatory documentary foundation for a spec; `slice-01` is the first implementation slice, not a global repo counter.
 The canonical installer entrypoint is `npx create-quiver` run from the target project root.
 Do not recommend global installation; use `npx` or a project-local devDependency when the team needs a pinned version.
-The post-init contract is validated with `npx create-quiver doctor` from the project root.
+The package also exposes `quiver` as a binary alias to the same CLI. Treat it as a local installed shortcut, not as a replacement for the bootstrap command `npx create-quiver`.
+The post-init contract is validated with `npx create-quiver doctor` from the project root. Use `npx create-quiver doctor --fix --dry-run` to preview safe non-destructive repairs, then `npx create-quiver doctor --fix` only after reviewing the plan.
 If the project already exists from an older Quiver version and was previously initialized by Quiver, run `npx create-quiver migrate` before `analyze` from the project root.
 If the project was never initialized by Quiver, do not use `migrate` as bootstrap; run `npx create-quiver init --name "Project Name"` first.
-Generated projects also get `quiver:*` npm scripts that call the Node CLI directly; prefer those for repeatable project workflows, including `quiver:plan` for sequential planning, `quiver:graph` for parallel-level inspection, `quiver:next` for the next ready slice, and the AI family `quiver:ai:onboard`, `quiver:ai:plan`, `quiver:ai:execute-slice`, `quiver:ai:pr`, and `quiver:ai:doctor`. Use `quiver:graph --format mermaid` for PR-ready Markdown or `quiver:graph --format dot` for Graphviz source.
+Use `npx create-quiver evidence run -- <command>` to capture validation evidence with command, exit code, duration, truncated output, and best-effort redaction. The safe default output is `.quiver/evidence/`; use `--output <file>` when a slice needs a specific evidence artifact.
+Use `npx create-quiver demo create spec-viewer --dry-run` to inspect the optional Quiver Spec Viewer demo scaffold, then add `--dir <target>` for a real run. The demo is not part of default init and must remain small, static, dependency-light, and non-destructive.
+The v20, v21, v22, and v23 specs are completed. `specs/quiver-v23-guided-flow-productization/` productized the manual planner/executor prompt workflow into guided Quiver commands, profiles, compact prompts, safe approvals, executor prompts, delegated execution modes, and release readiness evidence.
+The v24 spec is implemented under `specs/quiver-v24-dx-onboarding-hardening/`; it captures DX hardening found while dogfooding Quiver with Quiver Spec Viewer, including init hygiene, CLI ambiguity, local slice validation, analyzer quality, AI context preparation, evidence capture, and demo scaffolding. Do not claim a package release until npm publication actually happens.
+Guided AI workflow behavior is available: prepare, approvals, production-readiness plan review, spec worktrees, executor commits, execution waves, PR creation, spec close, and package safety.
+Generated projects also get `quiver:*` npm scripts that call the Node CLI directly; prefer those for repeatable project workflows, including `quiver:flow` for the read-only guided entrypoint, `quiver:plan` for sequential planning, `quiver:graph` for parallel-level inspection, `quiver:next` for the next ready slice, `quiver:evidence` for local command evidence, `quiver:spec:create` for real spec generation, and the AI family `quiver:ai:agent`, `quiver:ai:onboard`, `quiver:ai:prepare-context`, `quiver:ai:plan`, `quiver:ai:review-plan`, `quiver:ai:approve`, `quiver:ai:prompt-slice`, `quiver:ai:execute-slice`, `quiver:ai:execute-plan`, `quiver:ai:pr`, and `quiver:ai:doctor`. Use `quiver:graph --format mermaid` for PR-ready Markdown or `quiver:graph --format dot` for Graphviz source.
+`quiver:ai:execute-plan` supports `--mode manual` for paste-ready executor prompts and `--mode delegated` for temporary worktrees on parallel-ready waves; unsafe waves fall back to sequential execution.
+Agent profiles live in `.quiver/agents/profiles.json`; they store role, provider, model label, context label, and display label only. Do not store API keys, tokens, or credentials there.
+Planner drafts are versioned under `.quiver/approvals/<phase>/drafts/`; review the technical-plan draft with `npx create-quiver ai review-plan --dry-run` before approving it, then approve a concrete version with `npx create-quiver ai approve --phase <phase> --version <n>` when reviewing iterations.
 Maintain release notes and package publishing with `scripts/release-quiver.sh`.
 The primary generated project context for agents is `docs/AI_CONTEXT.md`.
 The project map is the single source of truth for stack, package manager, commands, and file hints: `docs/PROJECT_MAP.md`.
@@ -21,6 +30,7 @@ If a generated project has been analyzed, the exact agent handoff prompt is `doc
 Keep README copy-paste prompts short; the detailed onboarding contract lives in `docs/AI_ONBOARDING_PROMPT.md` generated from `docs/AI_ONBOARDING_PROMPT.md.template`.
 If a new bounded transfer is needed, scaffold `specs/<project-slug>/HANDOFF.md` with `npx create-quiver new-handoff <spec-slug>` and validate it with `npx create-quiver check-handoff specs/<project-slug>/HANDOFF.md`.
 Use `npx create-quiver check-handoff specs/<project-slug>/HANDOFF.md` to validate a transferred handoff before execution.
+Use `npx create-quiver check-slice --local <slice.json>` for structural validation in a new repo without remote/base branches; run normal `check-slice` before PR readiness so base/remote checks still happen.
 During onboarding, after reading `ROADMAP.md`, also read `BACKLOG.md` in the repository root: it tracks emerging patterns that are not yet scoped as specs. Before proposing a new spec, confirm the idea is not already parked or emerging there.
 
 ## Token-Efficient Reading Rules
@@ -48,12 +58,14 @@ Prefer maps, metadata, diffs, and summaries over full file reads when they are e
 - `specs/<project-slug>/HANDOFF.md` is reserved for exceptional context transfers between agents or phases.
 - Initial onboarding should complete context docs and report assumptions before any feature work starts.
 - The normal workflow runs from the project root without `--dir`; use `--dir` only when targeting another directory explicitly.
-- The cross-platform work targets native macOS, Linux, and Windows shells; Bash is a legacy compatibility path until the runtime slices land, and Windows support is only considered verified once the CI matrix is green.
+- The cross-platform contract targets native macOS, Linux, and Windows users through the Node CLI (`npx create-quiver ...`) and generated `quiver:*` npm scripts. Bash wrappers are legacy or optional compatibility, not the primary path. Keep root README examples clear about adapting SSH identity paths on Windows PowerShell, Git Bash, WSL, macOS, and Linux.
 - The support contract lives in `docs/SUPPORT_MATRIX.md` and `docs/TROUBLESHOOTING.md`.
-- Generated project npm scripts should prefer `quiver:*` names such as `quiver:analyze`, `quiver:plan`, `quiver:graph`, `quiver:next`, `quiver:doctor`, `quiver:start-slice`, `quiver:check-slice`, and `quiver:check-pr`.
+- Generated project npm scripts should prefer `quiver:*` names such as `quiver:analyze`, `quiver:flow`, `quiver:plan`, `quiver:graph`, `quiver:next`, `quiver:doctor`, `quiver:evidence`, `quiver:ai:agent`, `quiver:ai:prepare-context`, `quiver:ai:plan`, `quiver:ai:review-plan`, `quiver:ai:approve`, `quiver:ai:prompt-slice`, `quiver:ai:execute-slice`, `quiver:ai:execute-plan`, `quiver:spec:create`, `quiver:spec:start`, `quiver:spec:status`, `quiver:spec:close`, `quiver:start-slice`, `quiver:check-slice`, and `quiver:check-pr`.
+- Optional demos are created with `npx create-quiver demo create spec-viewer`; do not add demo output to the package or default init flow.
 - `quiver:graph` defaults to the tree view; choose `--format mermaid` or `--format dot` when you need exportable graph artifacts.
 - `quiver:next` prints the next ready slice and can auto-start it behind a confirmation prompt.
 - `quiver:next --all-ready` prints the whole ready level when you want to inspect every actionable slice at once.
+- Use `--include-completed` with `plan`, `graph`, or `next` only for audit/demo history; default output remains pending/actionable work.
 
 ## Initialization Flow
 
@@ -61,6 +73,7 @@ Prefer maps, metadata, diffs, and summaries over full file reads when they are e
 
 ```bash
 npx create-quiver init --name "Project Name"
+npx create-quiver flow
 ```
 
 The compatibility alias is still valid:
@@ -94,6 +107,7 @@ Default init creates the visible AI-first contract and Quiver internal state:
 - `docs/AI_ONBOARDING_PROMPT.md`
 - `docs/SUPPORT_MATRIX.md`
 - `docs/TROUBLESHOOTING.md`
+- `.gitignore`
 - `.quiver/config.json`
 - `.quiver/state.json`
 - `.quiver/.gitignore`
@@ -114,27 +128,37 @@ Init preserves existing target files and reports skipped copies instead of overw
 
 After initialization, the user should:
 
-1. Fill in `docs/AI_CONTEXT.md`
-2. Fill in `docs/AI_ONBOARDING_PROMPT.md`
-3. Fill in `docs/CONTEXTO.md`
-4. Fill in `docs/STATUS.md`
-5. Run `npx create-quiver analyze` if `docs/PROJECT_MAP.md` or `.quiver/scans/PROJECT_SCAN.json` is missing
-6. If the project already exists from an older Quiver version and was previously initialized by Quiver, run `npx create-quiver migrate`
-7. If the project was never initialized by Quiver, run `npx create-quiver init --name "Project Name"` instead of `migrate`
-8. Ask the AI agent to execute `docs/AI_ONBOARDING_PROMPT.md`
-9. Review context docs before creating the first implementation slice
-10. Open and merge the documentation PR that establishes the workflow files
-11. Use `npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run`
-12. After human approval, use `npx create-quiver ai plan --phase technical-plan --input acceptance-approved.md --dry-run`
-13. After human approval, use `npx create-quiver ai plan --phase spec --input technical-plan-approved.md --dry-run` to create the real spec, slices, handoffs, execution plan, and PR body
-14. Run `npx create-quiver plan` or `npm run quiver:plan`
-15. Run `npx create-quiver next` or `npm run quiver:next`
-16. Run `npx create-quiver start-slice [--allow-draft] <slice.json>` or `npm run quiver:start-slice -- [--allow-draft] <slice.json>`
-17. Make one commit per slice
-18. Open one PR per spec
-19. Validate the slice and the final PR with the workflow gates
+1. Run `npx create-quiver flow` when unsure about the next safe command
+2. Fill in `docs/AI_CONTEXT.md`
+3. Fill in `docs/AI_ONBOARDING_PROMPT.md`
+4. Fill in `docs/CONTEXTO.md`
+5. Fill in `docs/STATUS.md`
+6. Run `npx create-quiver analyze` if `docs/PROJECT_MAP.md` or `.quiver/scans/PROJECT_SCAN.json` is missing
+7. If the project already exists from an older Quiver version and was previously initialized by Quiver, run `npx create-quiver migrate`
+8. If the project was never initialized by Quiver, run `npx create-quiver init --name "Project Name"` instead of `migrate`
+9. Ask the AI agent to execute `docs/AI_ONBOARDING_PROMPT.md`
+10. Review context docs before creating the first implementation slice
+11. Open and merge the documentation PR that establishes the workflow files
+12. Save reusable provider choices with `npx create-quiver ai agent set planner --provider <provider> --model "<label>"` and `npx create-quiver ai agent set executor --provider <provider> --model "<label>"`
+13. Use `npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run`
+14. After human approval, save approved criteria with `npx create-quiver ai approve --phase acceptance --input acceptance-approved.md`
+15. Use `npx create-quiver ai plan --phase technical-plan --dry-run`
+16. Review the technical plan with `npx create-quiver ai review-plan --dry-run`, then run it without `--dry-run` when ready
+17. After human approval, save the reviewed plan version with `npx create-quiver ai approve --phase technical-plan --version <n>`
+18. Use `npx create-quiver spec create --dry-run` to preview the real spec, slices, handoffs, execution plan, and PR body, then run it without `--dry-run` when ready
+19. Run `npx create-quiver spec start specs/<spec-slug>` to create or reuse the spec worktree
+20. Run `npx create-quiver plan` or `npm run quiver:plan`
+21. Run `npx create-quiver next` or `npm run quiver:next`
+22. Run `npx create-quiver ai execute-plan --dry-run --commit --mode manual` to inspect prompts, or `npx create-quiver ai execute-plan --dry-run --commit --mode delegated` to inspect delegated execution waves
+23. For manual assignment, print a minimal executor prompt with `npx create-quiver ai prompt-slice --slice <slice.json> --dry-run`
+24. Execute one slice with `npx create-quiver ai execute-slice --slice <slice.json> --commit` or execute delegated waves with `npx create-quiver ai execute-plan --execute --commit --mode delegated`
+25. Keep one commit per slice
+26. Open one PR per spec with `npx create-quiver ai pr --dry-run --input specs/<spec-slug>/pr.md ...`, then `--create` only after review
+27. After merge, close the worktree with `npx create-quiver spec close specs/<spec-slug>`
+28. Validate the slice and the final PR with the workflow gates
 
 Bootstrap note: `start-slice` should resolve paths canonically, prefer a local `develop` or `main` base branch before reaching for `origin`, and reject `draft` slices unless `--allow-draft` is passed intentionally.
+Release note: `scripts/package-quiver.sh` runs package safety against the npm tarball and must fail if local AI state, env files, npm credentials, or worktree state would be published.
 
 ## Optional Files
 

package/ROADMAP.md

@@ -47,22 +47,33 @@
 - v13 slice-04 reconciled into v14 slice-05 (2026-04-23); v13 slice-02 narrowed to `DECISIONS.md` only
 - Validation checkpoint passed after real-world use and spec completion
 
-## Post-Checkpoint Plan (do not execute before validating v14)
+## v0.10 (shipped 2026-05-21)
+
+- Published package `0.10.0`.
+- Shipped v20 AI CLI orchestration: provider runner, planner/executor roles, context packs, phase-gated planning, spec/slice/handoff generation, execution planning, executor scope checks, and GitHub PR preflight.
+- Shipped v21 AI-first layout: smaller default init, `.quiver/` internal machinery, analyze scan relocation, optional legacy/full assets, and no placeholder specs by default.
+- Shipped v22 Guided AI Workflow after `0.10.0`: preparation diagnostics, approval state, spec worktrees, executor commits, execution waves, PR creation, post-merge cleanup, and release/package safety are implemented on the release branch.
+- Shipped v23 Guided Flow Productization after `0.10.0`: short `quiver` entrypoint, flow status, agent profiles, token-efficient onboarding, versioned planner drafts, production plan review, spec create, executor prompts, delegated worktrees, and final smoke/readiness coverage are implemented on the release branch and ready for the next package release.
+
+## v0.11 — DX Onboarding Hardening (implemented, pending package release)
 
-> This section is intentionally speculative. Every item below is pending
-> evidence from v14 in real use. Rescope or drop anything that does not
-> respond to observed friction.
+- **v24** — DX and onboarding hardening from real Quiver Spec Viewer dogfooding: init hygiene, CLI ambiguity, version mismatch checks, local slice validation, analyzer quality, AI context preparation, evidence capture, optional demo scaffolding, documentation, and smoke coverage are implemented on the release branch. No npm release is implied until publication happens.
+
+## Post-Checkpoint Plan (do not execute before validating v14)
 
-### Orchestration and Tooling (v19–v22, spec drafts created 2026-04-23)
+> This section now records the follow-up line from the v14-era plan.
+> Earlier speculative v20/v21 names were superseded by the actual shipped
+> specs listed below. v22 and v23 are now complete and await the next package release.
 
-Draft specs exist but are **not executed until v18 passes its validation checkpoint**. Each subsequent spec requires the previous one to pass its own checkpoint before it starts.
+### Orchestration and Tooling
 
-- **v19 — Project Visibility** (3 slices, ~11h): `quiver:status`, `quiver:estimate`, `quiver:lint-spec`
-- **v20 — Context Diagnostics** (3 slices, ~13h): `quiver:cost`, `quiver:diff-pack`, `quiver:replay`
-- **v21 — Slice Archaeology** (2 slices, ~7h): `quiver:archive`, `quiver:blame-slice`; `bisect-slice` documented via `git bisect run` in TROUBLESHOOTING
-- **v22 — Deferred Tooling** (3 slices, ~10h, evidence-gated): `quiver:fork-slice`, `quiver:squash-spec`, `quiver:share`
+- **v20 — AI CLI Orchestration** (completed): `quiver ai ...`, planner/executor roles, phase gates, context packs, executor scope checks, execution plans, and PR preflight.
+- **v21 — AI-First Layout** (completed): clean default init, `.quiver/` internals, analyze scan relocation, optional legacy assets, and no-spec-safe commands.
+- **v22 — Guided AI Workflow** (completed): guided preparation, approvals, spec worktrees, executor commits, execution waves, PR creation, cleanup, and release/package safety live in `specs/quiver-v22-guided-ai-workflow/`.
+- **v23 — Guided Flow Productization** (completed): AI-first flow command, agent profiles, compact onboarding/planning prompts, production plan review, explicit `spec create`, manual executor prompts, delegated worktree execution, and release readiness live in `specs/quiver-v23-guided-flow-productization/`.
+- **v24 — DX Onboarding Hardening** (implemented, pending package release): real-world dogfooding fixes for init/templates, CLI routing, doctor/prepare, local validation, analyzer, AI context preparation, evidence, and demos live in `specs/quiver-v24-dx-onboarding-hardening/`.
 
-Plan total: ~41h across 11 slices. Drafts parked on `drafts/v19-v22-orchestration-followups`. v22 stays deferred until BACKLOG.md records ≥1 occurrence per slice.
+The shipped v20/v21/v22/v23 work is no longer pending. The older context-diagnostics and slice-archaeology ideas remain deferred until real demand justifies them.
 
 ### v0.8 — Slice Orchestration Commands (shipped 2026-05-13)
 

package/docs/AI_CONTEXT.md.template

@@ -25,6 +25,7 @@ This file is the main context pack after `AGENTS.md` and `docs/PROJECT_MAP.md`.
 - `docs/AI_ONBOARDING_PROMPT.md` is the handoff after analysis.
 - `docs/DECISIONS.md` tracks durable choices so agents do not re-litigate them.
 - `docs/STATUS.md` tracks progress, blockers, and the current slice.
+- `npx create-quiver ai prepare-context --dry-run` previews docs-only context drafts before writing.
 
 ## Critical Rules
 
@@ -35,6 +36,7 @@ This file is the main context pack after `AGENTS.md` and `docs/PROJECT_MAP.md`.
 - Use canonical paths when a path matters.
 - Never overwrite user-authored content without checking whether the file is meant to be preserved.
 - If a command or path is ambiguous, prefer the local project root and the generated docs.
+- Context preparation must stay in docs/context files and should use TODO, Assumption, or Pending confirmation markers for uncertain statements.
 
 ## What To Update After A Slice
 

package/docs/AI_ONBOARDING_PROMPT.md.template

@@ -9,23 +9,16 @@ Actúa como asistente de onboarding de IA para este proyecto. Tu objetivo es com
 
 ## Reglas de ejecución
 
-1. Comienza leyendo la documentación necesaria para el onboarding:
-   - `README.md`
-   - `AGENTS.md`, si existe
-   - `docs/AI_ONBOARDING_PROMPT.md`
-   - `docs/PROJECT_MAP.md`
-   - `.quiver/scans/PROJECT_SCAN.json`, si existe y el mapa visible no alcanza
-   - `docs/AI_CONTEXT.md`
-   - `docs/CONTEXTO.md`
-   - `docs/WORKFLOW.md`
-   - `docs/STATUS.md`
-   - `docs/DECISIONS.md`, si existe
-   - `specs/{{PROJECT_SLUG}}/SPEC.md`
-   - `specs/{{PROJECT_SLUG}}/STATUS.md`
-   - `specs/{{PROJECT_SLUG}}/EVIDENCE_REPORT.md`
-   - `specs/{{PROJECT_SLUG}}/HANDOFF.md`, si este trabajo fue transferido mediante un handoff
-   - cualquier documento sobre WDD o SDD referenciado por la documentación de onboarding
-   - cualquier archivo de estructura, contexto o convenciones del proyecto referenciado por esos documentos
+1. Comienza con navegación index-first y lectura selectiva:
+   - Lee `README.md`.
+   - Lee `AGENTS.md`, si existe.
+   - Lee `docs/INDEX.md`, si existe, y úsalo como mapa para decidir qué abrir después.
+   - Lee `docs/PROJECT_MAP.md` para stack, comandos y estructura. Usa `.quiver/scans/PROJECT_SCAN.json` solo si el mapa visible no alcanza.
+   - Lee `docs/AI_CONTEXT.md`, `docs/AI_ONBOARDING_PROMPT.md`, `docs/WORKFLOW.md`, `docs/STATUS.md` y `docs/DECISIONS.md` solo cuando existan y sean relevantes para la tarea.
+   - Si usás `npx create-quiver ai prepare-context`, revisá los borradores propuestos antes de escribir y mantené las escrituras limitadas a docs/context.
+   - Lee specs, slices o handoffs solo si la tarea actual lo requiere.
+   - No leas todo `docs/` por defecto.
+   - Si un documento referenciado no existe, repórtalo como deuda documental.
 
 2. Sigue las instrucciones definidas en `docs/AI_ONBOARDING_PROMPT.md`, salvo que entren en conflicto con las restricciones de este prompt.
 
@@ -78,9 +71,22 @@ Prefiere resúmenes, deltas y metadatos antes que lecturas completas cuando sean
 Si usás los comandos de IA de Quiver, empezá con `--dry-run` para revisar provider, rol, context pack y transporte de prompt antes de ejecutar:
 
 ```bash
+npm run quiver:prepare -- --dry-run
+npm run quiver:ai:prepare-context -- --dry-run
 npm run quiver:ai:onboard -- --dry-run
 npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run
-npm run quiver:ai:execute-slice -- --slice specs/{{PROJECT_SLUG}}/slices/<slice-id>/slice.json --dry-run
+npm run quiver:ai:approve -- --phase acceptance --input acceptance-approved.md
+npm run quiver:ai:plan -- --phase technical-plan --dry-run
+npm run quiver:ai:review-plan -- --dry-run
+npm run quiver:ai:approve -- --phase technical-plan --version <n>
+npm run quiver:spec:create -- --dry-run
+npm run quiver:spec:start -- specs/{{PROJECT_SLUG}}
+npm run quiver:ai:prompt-slice -- --slice specs/{{PROJECT_SLUG}}/slices/<slice-id>/slice.json --dry-run
+npm run quiver:ai:execute-slice -- --slice specs/{{PROJECT_SLUG}}/slices/<slice-id>/slice.json --dry-run --commit
+npm run quiver:ai:execute-plan -- --dry-run --commit --mode manual
+npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated
+npm run quiver:ai:pr -- --dry-run --input specs/{{PROJECT_SLUG}}/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+npm run quiver:spec:close -- specs/{{PROJECT_SLUG}} --dry-run
 ```
 
 ## Tareas
@@ -93,6 +99,7 @@ npm run quiver:ai:execute-slice -- --slice specs/{{PROJECT_SLUG}}/slices/<slice-
 6. Si existe un handoff, trátalo como brief de transferencia y valida que aplique al trabajo solicitado.
 7. Si no existe un handoff y el trabajo necesita uno, créalo con `npx create-quiver new-handoff <spec-slug>` y valídalo con `npx create-quiver check-handoff specs/<spec-slug>/HANDOFF.md`.
 8. Registra los archivos inspeccionados, los archivos modificados y las suposiciones realizadas.
+9. Cuando prepares contexto, marca las incertidumbres como `TODO`, `Assumption` o `Pending confirmation` y evita tocar código de producto.
 
 ## Validación
 

package/docs/COMMANDS.md.template

@@ -11,16 +11,38 @@ This document is the canonical command reference for the orchestration roadmap.
 |---------|---------|----|-------|---------|
 | `npx create-quiver init --name "<project>"` | Creates the default AI-first Quiver contract for a project | macOS, Linux, Windows | current | `npx create-quiver init --name "{{PROJECT_NAME}}"` |
 | `npx create-quiver --name "<project>"` | Compatibility alias for the recommended init flow | macOS, Linux, Windows | current | `npx create-quiver --name "{{PROJECT_NAME}}"` |
+| `npx create-quiver flow` | Shows the read-only guided flow entrypoint and next safe command | macOS, Linux, Windows | v0.11 | `npx create-quiver flow` |
 | `quiver:analyze` | Writes raw analyzer data to `.quiver/scans/PROJECT_SCAN.json` and the visible project map to `docs/PROJECT_MAP.md` | macOS, Linux, Windows | v0.8 | `npm run quiver:analyze` |
+| `quiver:flow` | Runs the guided flow entrypoint through the generated npm script | macOS, Linux, Windows | v0.11 | `npm run quiver:flow` |
+| `quiver:prepare` | Runs guided setup diagnostics and context preparation | macOS, Linux, Windows | v0.10 | `npm run quiver:prepare -- --dry-run --provider codex` |
 | `quiver:doctor` | Validates the Quiver contract and reports layout or migration guidance | macOS, Linux, Windows | v0.8 | `npm run quiver:doctor` |
+| `quiver:doctor -- --fix --dry-run` | Previews safe non-destructive repairs without writing files | macOS, Linux, Windows | v0.11 | `npm run quiver:doctor -- --fix --dry-run` |
+| `quiver:doctor -- --fix` | Applies safe idempotent repairs after review | macOS, Linux, Windows | v0.11 | `npm run quiver:doctor -- --fix` |
+| `quiver:evidence -- run -- <command>` | Captures command validation evidence with exit code, duration, redacted/truncated output, and a local Markdown record | macOS, Linux, Windows | v0.11 | `npm run quiver:evidence -- run -- npm test` |
+| `npx create-quiver demo create spec-viewer --dry-run` | Previews the optional Quiver Spec Viewer demo scaffold without writing files | macOS, Linux, Windows | v0.11 | `npx create-quiver demo create spec-viewer --dry-run` |
+| `npx create-quiver demo create spec-viewer --dir <target>` | Creates a small static demo app with example specs, slices, and validation scripts | macOS, Linux, Windows | v0.11 | `npx create-quiver demo create spec-viewer --dir ./quiver-spec-viewer` |
 | `quiver:plan` | Sequential orchestration planning command | macOS, Linux, Windows | v0.8 | [docs/examples/plan.md](./examples/plan.md) |
 | `quiver:graph` | Parallel-level orchestration tree command | macOS, Linux, Windows | v0.8 | [docs/examples/graph.md](./examples/graph.md) |
 | `quiver:next` | Ready-slice suggestion command | macOS, Linux, Windows | v0.8 | [docs/examples/next.md](./examples/next.md) |
+| `quiver:plan -- --include-completed` | Shows completed slices for audit/demo history | macOS, Linux, Windows | v0.11 | `npm run quiver:plan -- --include-completed --spec <spec>` |
+| `quiver:graph -- --include-completed` | Includes completed slices in the dependency graph history view | macOS, Linux, Windows | v0.11 | `npm run quiver:graph -- --include-completed --spec <spec>` |
+| `quiver:next -- --include-completed` | Keeps actionable next-slice output and appends completed history | macOS, Linux, Windows | v0.11 | `npm run quiver:next -- --include-completed --spec <spec>` |
+| `quiver:ai:agent` | Stores reusable planner/executor/reviewer/researcher provider profiles without secrets | macOS, Linux, Windows | v0.11 | `npm run quiver:ai:agent -- set planner --provider codex --model "planner-model"` |
 | `quiver:ai:onboard` | Runs AI onboarding prompt through a supported local provider CLI | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:onboard -- --dry-run` |
+| `quiver:ai:prepare-context` | Prepares docs-only AI context drafts and reports assumptions, risks, files considered, and omitted paths | macOS, Linux, Windows | v0.11 | `npm run quiver:ai:prepare-context -- --dry-run` |
 | `quiver:ai:plan` | Runs phase-gated AI planning for acceptance criteria, technical plan, or spec generation | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:plan -- --phase acceptance --input requirements.md --dry-run` |
-| `quiver:ai:execute-slice` | Runs an executor agent against one slice handoff with scope checks | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:execute-slice -- --slice specs/<spec>/slices/<slice>/slice.json --dry-run` |
+| `quiver:ai:review-plan` | Reviews the technical-plan draft for production readiness before approval and spec generation | macOS, Linux, Windows | v0.11 | `npm run quiver:ai:review-plan -- --dry-run` |
+| `quiver:ai:approve` | Persists approved acceptance criteria or technical plans for the next planner phase | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:approve -- --phase acceptance --input acceptance-approved.md` |
+| `quiver:ai:prompt-slice` | Prints a minimal executor prompt for manual slice assignment without calling a provider | macOS, Linux, Windows | v0.11 | `npm run quiver:ai:prompt-slice -- --slice specs/<spec>/slices/<slice>/slice.json --dry-run` |
+| `quiver:ai:execute-slice` | Runs an executor agent against one slice handoff with scope checks and optional commit | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:execute-slice -- --slice specs/<spec>/slices/<slice>/slice.json --dry-run --commit` |
+| `quiver:ai:execute-plan` | Prints or executes dependency-safe waves of slices, with manual prompts or delegated worktrees | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:execute-plan -- --dry-run --commit --mode delegated` |
 | `quiver:ai:doctor` | Runs GitHub PR preflight checks without opening a PR | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:doctor -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work` |
-| `quiver:ai:pr` | Validates `gh`, GitFlow docs, branch/worktree state, and SSH inputs before PR work | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:pr -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work` |
+| `quiver:ai:pr` | Validates `gh`, reads `pr.md`, prints a PR plan, and creates a PR only with `--create` | macOS, Linux, Windows | v0.10 | `npm run quiver:ai:pr -- --dry-run --input specs/<spec>/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work` |
+| `quiver:spec:create` | Creates the real spec tree from the reviewed approved technical plan | macOS, Linux, Windows | v0.11 | `npm run quiver:spec:create -- --dry-run` |
+| `quiver:spec:start` | Creates or reuses the dedicated worktree for one spec | macOS, Linux, Windows | v0.10 | `npm run quiver:spec:start -- specs/<spec>` |
+| `quiver:spec:status` | Shows spec worktree, branch, `slice-00`, and pending slices | macOS, Linux, Windows | v0.10 | `npm run quiver:spec:status -- specs/<spec>` |
+| `quiver:spec:close` | Closes a merged clean spec worktree and pulls the main checkout | macOS, Linux, Windows | v0.10 | `npm run quiver:spec:close -- specs/<spec> --dry-run` |
+| `quiver:check-slice -- --local <slice.json>` | Runs local structural slice validation without remote/base checks | macOS, Linux, Windows | v0.11 | `npm run quiver:check-slice -- --local specs/<spec>/slices/<slice>/slice.json` |
 
 ## CLI Flags
 
@@ -31,30 +53,56 @@ This document is the canonical command reference for the orchestration roadmap.
 | `--legacy-scripts` | `init` | Add legacy Bash wrappers under `tools/scripts/` |
 | `--include-templates` | `init` | Export packaged templates under `.quiver/templates/` |
 | `--skip-install` | `init`, `migrate` | Skip auto-install of `create-quiver` as dev dependency (useful for CI) |
+| `--fix` | `doctor` | Apply only safe non-destructive repairs; combine with `--dry-run` first |
+| `--output <file>` | `evidence run` | Write the evidence Markdown file to an explicit path instead of `.quiver/evidence/` |
+| `--max-output <n>` | `evidence run` | Limit captured stdout and stderr characters per section |
+| `--dir <target>` | `demo create spec-viewer` | Select the demo target directory; default is `./quiver-spec-viewer` |
 | `--json` | `plan`, `graph`, `next` | Emit machine-readable JSON |
 | `--format <tree\|mermaid\|dot>` | `graph` | Output format |
 | `--all-ready` | `next` | List all ready slices instead of just the next one |
 | `--only-ready` | `plan` | Show only slices with no pending dependencies |
-| `--spec <slug>` | `plan`, `graph` | Restrict output to one spec |
-| `--provider <codex\|claude\|gemini>` | `ai onboard`, `ai plan`, `ai execute-slice` | Select the local AI CLI adapter |
-| `--role <planner\|executor>` | `ai onboard`, `ai plan`, `ai execute-slice` | Select planner or executor role; `execute-slice` requires executor |
-| `--context <full\|planning\|slice\|minimal>` | `ai onboard`, `ai plan`, `ai execute-slice` | Select a token-budgeted context pack |
+| `--include-completed` | `plan`, `graph`, `next` | Include completed slices for audit/demo history without changing default pending-only behavior |
+| `--local` | `check-slice` | Run structural validation without remote/base checks; use normal mode before PR readiness |
+| `--spec <slug>` | `plan`, `graph`, `spec create` | Restrict output to one spec or override the generated spec slug |
+| `--provider <codex\|claude\|gemini>` | `ai onboard`, `ai plan`, `ai review-plan`, `ai execute-slice`, `ai execute-plan` | Select the local AI CLI adapter |
+| `--model <label>` | `ai agent set` | Store a free-form model label in an agent profile; Quiver does not verify model availability |
+| `--label <label>` | `ai agent set` | Store a display label for the profile |
+| `--role <planner\|executor>` | `ai onboard`, `ai plan`, `ai execute-slice`, `ai execute-plan` | Select planner or executor role; execution requires executor |
+| `--context <full\|planning\|slice\|minimal>` | `ai onboard`, `ai plan`, `ai review-plan`, `ai execute-slice`, `ai execute-plan` | Select a token-budgeted context pack |
 | `--phase <acceptance\|technical-plan\|spec>` | `ai plan` | Select the gated planner phase |
-| `--input <file>` | `ai plan` | Read approved requirements, criteria, or technical plan from a file |
-| `--slice <slice.json>` | `ai execute-slice` | Select the slice handoff to execute |
+| `--input <file>` | `ai plan`, `ai review-plan`, `ai approve`, `ai pr`, `spec create` | Read approved requirements/plans or select the generated PR body |
+| `--version <n>` | `ai approve` | Approve a specific saved draft version |
+| `--slice <slice.json>` | `ai prompt-slice`, `ai execute-slice` | Select the slice handoff to print or execute |
+| `--commit` | `ai execute-slice`, `ai execute-plan` | Commit validated slice changes after provider, scope, and tests pass |
+| `--execute` | `ai execute-plan` | Execute the planned waves instead of printing commands |
+| `--mode <auto\|manual\|delegated>` | `ai execute-plan` | Choose compatible sequential execution, manual prompt output, or delegated worktree execution |
+| `--create` | `ai pr` | Create the GitHub PR after preflight and plan review |
+| `--base <branch>` | `ai pr`, `spec close` | Select PR base or cleanup base branch |
+| `--allow-dirty` | `ai execute-slice`, `ai execute-plan` | Allow pre-existing dirty files and ignore them for scope diff |
 | `--ssh-host-alias <alias>` | `ai doctor`, `ai pr` | SSH host alias from the user's Git config, for example `github-work` |
 | `--identity-file <path>` | `ai doctor`, `ai pr` | SSH key path to validate separately from the host alias |
 
 ## Notes
 
 - Add new rows here only when a command is officially shipped.
+- The `quiver` binary is an alias to the same package CLI after local installation. Keep `npx create-quiver` as the bootstrap command.
 - Keep the table concise and cross-platform.
 - Shared graph library: `src/create-quiver/lib/slice-graph.js`.
 - `quiver:graph --format mermaid` is the PR-friendly Mermaid export; `--format dot` is for Graphviz/DOT consumers.
 - `quiver:next` prints the next ready slice and can auto-start it behind a confirmation prompt.
 - `check-slice` validates `depends_on` targets and requires `parallel_safe_reason` when `parallel_safe` is `never`.
-- `quiver:ai:onboard`, `quiver:ai:plan`, and `quiver:ai:execute-slice` support `codex`, `claude`, and `gemini` through local CLIs. Use `--dry-run` first to inspect the invocation without requiring provider auth.
-- `quiver:ai:execute-slice` uses executor context only and validates changed files against `slice.json.files` after provider execution.
-- `quiver:ai:pr -- --dry-run` validates GitHub CLI, auth, Git remote, current branch/worktree, `docs/GITFLOW_PR_GUIDE.md`, SSH host alias, and identity file without creating a PR.
+- `quiver:ai:onboard`, `quiver:ai:plan`, `quiver:ai:review-plan`, and `quiver:ai:execute-slice` support `codex`, `claude`, and `gemini` through local CLIs. Use `--dry-run` first to inspect the invocation without requiring provider auth.
+- `quiver:ai:prepare-context -- --dry-run` previews docs-only context drafts. Run it before write mode and review assumptions, risks, and omitted paths.
+- `quiver:ai:agent` stores provider/model labels under `.quiver/agents/profiles.json`; credentials stay in the provider CLI or OS credential store.
+- Planner drafts are versioned under `.quiver/approvals/<phase>/drafts/`; use `quiver:ai:review-plan -- --dry-run` before approving a technical-plan draft, then `quiver:ai:approve -- --phase technical-plan --version 1` to approve the reviewed version.
+- `quiver:ai:prompt-slice -- --dry-run` prints a paste-ready manual executor prompt and does not call a provider.
+- `quiver:evidence -- run -- <command>` preserves the wrapped command exit code. Redaction is best effort; avoid commands that intentionally print secrets.
+- `demo create spec-viewer` is optional and static; it must stay outside default `init`.
+- `quiver:ai:execute-slice -- --commit` creates exactly one commit only after provider, scope, and validation commands pass.
+- `quiver:ai:execute-plan -- --dry-run --commit --mode manual` prints paste-ready executor prompt commands without provider execution.
+- `quiver:ai:execute-plan -- --dry-run --commit --mode delegated` prints safe delegated waves and falls back to sequential mode when file scope is missing or overlapping.
+- `quiver:ai:execute-plan -- --execute --commit --mode delegated` uses temporary worktrees for parallel-ready waves and integrates one validated commit per slice.
+- `quiver:ai:pr -- --dry-run` validates GitHub CLI, auth, Git remote, current branch/worktree, `docs/GITFLOW_PR_GUIDE.md`, SSH host alias, identity file, and `pr.md` without creating a PR. Add `--create` only after reviewing the plan.
+- `quiver:spec:close` refuses dirty or unmerged spec worktrees unless discard behavior is explicitly requested.
 - After `init` or `migrate`, Quiver auto-installs itself as a dev dependency. Use `--skip-install` to suppress.
 - Cross-platform authoring rules live in `docs/SUPPORT_MATRIX.md`.

package/docs/CONTEXTO.md.template

@@ -16,6 +16,7 @@
 
 - [Current goal 1]
 - [Current goal 2]
+- [TODO: confirm current onboarding context before broadening scope]
 
 ## Where The Stack Lives
 
@@ -30,3 +31,4 @@ The stack, package manager, and command surface are generated in `docs/PROJECT_M
 ## Next Step
 
 Read `AI_CONTEXT.md` first if you are an AI agent. Otherwise read `INDEX.md` to navigate the rest of the documentation.
+Use `npx create-quiver ai prepare-context --dry-run` to preview context drafts before writing docs.

package/docs/DECISIONS.md.template

@@ -4,6 +4,7 @@
 **Status:** {{ESTADO}}
 
 This file records durable project decisions so AI agents do not re-litigate choices that were already made.
+Use it for durable context-preparation choices too, especially when a missing generated doc is guidance-only rather than debt.
 
 ## Log
 

package/docs/INDEX.md.template

@@ -4,7 +4,6 @@
 
 ## Start Here
 
-- **Project Map** - `./PROJECT_MAP.md`
 - **Context** - `./CONTEXTO.md`
 - **AI Context** - `./AI_CONTEXT.md`
 - **Decision Log** - `./DECISIONS.md`
@@ -13,23 +12,28 @@
 - **Commands** - `./COMMANDS.md`
 - **Support Matrix** - `./SUPPORT_MATRIX.md`
 - **Troubleshooting** - `./TROUBLESHOOTING.md`
-- **Multi-agent workflow** - `./MULTI_AGENT_WORKFLOW.md`
 
 ## AI Configuration
 
-- **QUICK** - `./ai/QUICK.md`
-- **STANDARD** - `./ai/STANDARD.md`
-- **DEEP** - `./ai/DEEP.md`
 - **Principles** - `./ai/PRINCIPLES.md`
 - **Rules** - `./ai/RULES.yaml`
 - **Lessons** - `./ai/LESSONS.md`
 
-## Optional Docs
+## Project Map Generated After Analyze
 
-- **Status** - `./STATUS.md`
-- **Specs** - `../specs/{{PROJECT_SLUG}}/`
-- **Tools** - `./tools/`
-- **Archive** - `./archive/`
+`docs/PROJECT_MAP.md` is created by:
+
+```bash
+npx create-quiver analyze
+```
+
+Use it after analysis for detected stack, package manager, commands, and file hints.
+
+## Optional Docs and Profiles
+
+- `npx create-quiver init --full` can add optional multi-agent notes, examples, and starter spec assets.
+- Real specs and slices should be created later from approved requirements and plans with `npx create-quiver spec create`.
+- Legacy Bash wrappers are only added with `--full` or `--legacy-scripts`.
 
 ## Directory Layout
 
@@ -38,9 +42,6 @@ docs/
 ├── INDEX.md
 ├── AI_CONTEXT.md
 ├── DECISIONS.md
-├── ai/QUICK.md
-├── ai/STANDARD.md
-├── ai/DEEP.md
 ├── AI_ONBOARDING_PROMPT.md
 ├── CONTEXTO.md
 ├── STATUS.md
@@ -48,9 +49,10 @@ docs/
 ├── COMMANDS.md
 ├── SUPPORT_MATRIX.md
 ├── TROUBLESHOOTING.md
-├── MULTI_AGENT_WORKFLOW.md
-├── ai/
-├── api/
-├── tools/
-└── archive/
+├── TESTING_GUIDE_FOR_AI.md
+├── GITFLOW_PR_GUIDE.md
+└── ai/
+    ├── PRINCIPLES.md
+    ├── RULES.yaml
+    └── LESSONS.md
 ```

package/docs/STATUS.md.template

@@ -24,3 +24,4 @@ This page tracks progress, blockers, and the current slice. Stack and command de
 
 - Update this file after each completed slice.
 - Keep stack and command changes in `docs/PROJECT_MAP.md`, not here.
+- Record uncertainty with `TODO`, `Assumption`, or `Pending confirmation` instead of treating it as product debt.

package/docs/SUPPORT_MATRIX.md.template

@@ -9,7 +9,7 @@ Quiver is intentionally opinionated about the first-run environment. If your set
 
 | Area | Supported | Notes |
 |------|-----------|-------|
-| Operating systems | macOS, Linux, and Windows | Windows native support is verified only when the cross-platform CI matrix is green. |
+| Operating systems | macOS, Linux, and Windows | Primary runtime is the Node CLI and generated `quiver:*` npm scripts. |
 | Shells | Terminal, bash-compatible shells, PowerShell, and CMD | Bash is a legacy compatibility path, not a required runtime dependency. |
 | Git | Git 2.40+ | Must support worktrees and standard branch refs on every supported OS. |
 | Node.js | Node 22.x LTS | Required on every supported OS. |
@@ -40,7 +40,7 @@ Quiver is intentionally opinionated about the first-run environment. If your set
 
 ## What This Means
 
-- You can bootstrap and run Quiver on macOS, Linux, and Windows native shells once the runtime slices land and the CI matrix is green.
+- You can bootstrap and run Quiver on macOS, Linux, and Windows native shells with the Node CLI.
 - Windows native usage should target PowerShell or CMD instead of Bash.
 - Quiver should not auto-install Bash, Git Bash, MSYS2, or WSL.
 - You do not need a remote to begin work if a local base branch already exists.

package/docs/TROUBLESHOOTING.md.template

@@ -44,6 +44,56 @@ Use this guide when a first-run bootstrap or gate check fails. The recovery path
 2. Re-add the remote only if the workflow genuinely needs it.
 3. Prefer the local base branch path when validating first-run behavior.
 
+## Local Slice Validation In A New Repo
+
+### Symptom
+
+- `check-slice` asks for a remote/base branch while the repo is still local-only
+
+### Recovery
+
+1. Run `npx create-quiver check-slice --local <slice.json>` for structural validation.
+2. Before PR readiness, run normal `check-slice <slice.json>` with a local base branch, `--base <branch>`, or a configured remote.
+3. Treat `--local` as a first-use validation mode, not as a replacement for PR checks.
+
+## Context Preparation Overwrites Docs
+
+### Symptom
+
+- `ai prepare-context` wrote generated context docs and you expected only a preview
+
+### Recovery
+
+1. Use `npx create-quiver ai prepare-context --dry-run` first.
+2. Review assumptions, risks, files considered, and omitted paths.
+3. Commit or preserve any manual edits before running write mode.
+4. Write mode is intentionally limited to approved docs/context files and does not touch product code.
+
+## Evidence Contains Sensitive Output
+
+### Symptom
+
+- `evidence run` captured output that may include secrets
+
+### Recovery
+
+1. Treat redaction as best effort, not a secret scanner.
+2. Avoid running commands that intentionally print credentials.
+3. Delete or rewrite the local evidence file before sharing it if sensitive output remains.
+4. Prefer `--max-output <n>` for noisy commands.
+
+## Demo Scaffold Conflict
+
+### Symptom
+
+- `demo create spec-viewer` reports preserved files in the target directory
+
+### Recovery
+
+1. Re-run with `--dry-run` and inspect the planned preserve/create list.
+2. Use `--dir <empty-target>` when you want a clean demo.
+3. Existing files are preserved; Quiver does not overwrite them for the demo.
+
 ## Generated File Conflicts
 
 ### Symptom