create-quiver 0.9.1 → 0.12.0

package/README_FOR_AI.md

@@ -1,32 +1,43 @@
-# AI Guide for Quiver Docs Template
+# AI Guide for Quiver
 
-Use this guide when initializing a new project from the template or when explaining the workflow to another agent.
+Use this guide when initializing a new project with Quiver or when explaining the workflow to another agent.
 
 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 --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, and `quiver:next` for the next ready slice. Use `quiver:graph --format mermaid` for PR-ready Markdown or `quiver:graph --format dot` for Graphviz source.
+If the project was never initialized by Quiver, do not use `migrate` as bootstrap; run `npx create-quiver init --name "Project Name"` first.
+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`.
+The raw analyzer output is internal machinery at `.quiver/scans/PROJECT_SCAN.json`; read it only when the visible map is not enough.
 The universal router for generated projects is `AGENTS.md`; read it before `docs/AI_CONTEXT.md` and `docs/AI_ONBOARDING_PROMPT.md`.
 Generated projects also get `docs/DECISIONS.md`; use it for durable choices that should not be re-litigated.
 If a generated project has been analyzed, the exact agent handoff prompt is `docs/AI_ONBOARDING_PROMPT.md`.
 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
 
 Use the smallest context that still answers the current task.
 
-- **Onboarding:** start from `README.md`, `AGENTS.md` when present, `docs/PROJECT_MAP.md`, `docs/PROJECT_SCAN.json`, `docs/AI_CONTEXT.md`, and `docs/AI_ONBOARDING_PROMPT.md` before opening source files.
+- **Onboarding:** start from `README.md`, `AGENTS.md` when present, `docs/PROJECT_MAP.md`, `.quiver/scans/PROJECT_SCAN.json` when it exists, `docs/AI_CONTEXT.md`, and `docs/AI_ONBOARDING_PROMPT.md` before opening source files.
 - **Onboarding router:** start from `README.md` and `AGENTS.md` first, then the onboarding files above.
 - **Implementation:** start from `docs/ai/ACTIVE_SLICE.md` when it exists; otherwise start from `specs/<project-slug>/slices/<slice-id>/slice.json`, then read only the declared files, nearby tests, and directly related source.
 - **Handoff:** start from `specs/<project-slug>/HANDOFF.md` when the work was explicitly transferred through a handoff artifact.
@@ -38,90 +49,116 @@ Prefer maps, metadata, diffs, and summaries over full file reads when they are e
 
 ## Core Rules
 
-- Never customize `docs-template/` for a specific project.
-- Always use `init-docs.sh` instead of copying files by hand.
-- Treat `docs-template/` as generic and `docs/` as generated project-specific output.
+- Do not treat `docs-template/` as part of the default project contract. It is legacy or exported only when explicitly requested.
+- Use `npx create-quiver init` or `npx create-quiver --name "Project Name"` instead of copying templates by hand.
+- Treat `.quiver/` as Quiver internal machinery and `docs/` as the visible project-specific contract.
 - Not every project needs every optional file.
 - The AI context pack lives in `docs/AI_CONTEXT.md`; `docs/CONTEXTO.md` is the broader project overview; `docs/PROJECT_MAP.md` owns stack and command facts.
-- The onboarding prompt lives in `docs/AI_ONBOARDING_PROMPT.md` and should reference the analyzer outputs.
+- The onboarding prompt lives in `docs/AI_ONBOARDING_PROMPT.md` and should reference `docs/PROJECT_MAP.md`; raw scan details live in `.quiver/scans/PROJECT_SCAN.json`.
 - `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
 
-1. Copy the template folder into the target project as `docs-template/`.
-2. Run:
+1. From the target project root, run the default AI-first initializer:
 
 ```bash
-./docs-template/scripts/init-docs.sh "Project Name"
+npx create-quiver init --name "Project Name"
+npx create-quiver flow
 ```
 
-3. Tell the user to edit:
+The compatibility alias is still valid:
+
+```bash
+npx create-quiver --name "Project Name"
+```
+
+2. Analyze and validate the project contract:
+
+```bash
+npx create-quiver analyze
+npx create-quiver doctor
+```
+
+3. Tell the user to review or complete:
   - `docs/AI_CONTEXT.md`
   - `docs/AI_ONBOARDING_PROMPT.md`
   - `docs/CONTEXTO.md`
   - `docs/STATUS.md`
-  - `docs/SUPPORT_MATRIX.md`
-  - `docs/TROUBLESHOOTING.md`
-  - `specs/{{PROJECT_SLUG}}/SPEC.md`
+  - `docs/PROJECT_MAP.md`
+
+## What Init Creates
 
-## What the Script Creates
+Default init creates the visible AI-first contract and Quiver internal state:
 
+- `AGENTS.md`
 - `docs/`
 - `docs/ai/`
 - `docs/AI_CONTEXT.md`
 - `docs/AI_ONBOARDING_PROMPT.md`
-- `specs/{{PROJECT_SLUG}}/`
-- `tools/scripts/`
-- `docs/SEARCH.md`
-- a merged or copied `package.json` with the required npm scripts
-- the default OSS baseline when those files are missing:
-- `LICENSE`
-- `CONTRIBUTING.md`
-- `CODE_OF_CONDUCT.md`
-- `SECURITY.md`
-- `CHANGELOG.md`
-- `ROADMAP.md`
 - `docs/SUPPORT_MATRIX.md`
 - `docs/TROUBLESHOOTING.md`
-- `.github/pull_request_template.md`
-- `.github/ISSUE_TEMPLATE/bug_report.md`
-- `.github/ISSUE_TEMPLATE/feature_request.md`
-- `.github/workflows/ci.yml`
+- `.gitignore`
+- `.quiver/config.json`
+- `.quiver/state.json`
+- `.quiver/.gitignore`
+- a merged or copied `package.json` with `quiver:*` scripts
+
+Default init does not create `docs-template/`, `tools/scripts/`, or a placeholder spec.
+
+Optional compatibility profiles:
+
+- `--minimal` creates only the essential onboarding contract.
+- `--full` preserves the broad legacy-compatible layout, including placeholder spec assets and OSS/community files.
+- `--legacy-scripts` adds Bash wrappers under `tools/scripts/`.
+- `--include-templates` exports packaged templates under `.quiver/templates/`, not root `docs-template/`.
 
-`init-docs.sh` preserves any existing target files and reports skipped copies instead of overwriting them.
+Init preserves existing target files and reports skipped copies instead of overwriting them.
 
 ## Required Follow-Up
 
 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 scan artifacts are 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 --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. Create the first slice in `specs/{{PROJECT_SLUG}}/slices/[slice-id]/`
-12. Add `ticket` and `git.*`
-13. Run `npx create-quiver plan` or `npm run quiver:plan`
-14. Run `npx create-quiver next` or `npm run quiver:next`
-14. Run `npx create-quiver start-slice [--allow-draft] <slice.json>` or `npm run quiver:start-slice -- [--allow-draft] <slice.json>`
-15. Make one commit per slice
-16. Open one PR per spec
-17. 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
 
@@ -130,7 +167,7 @@ Bootstrap note: `start-slice` should resolve paths canonically, prefer a local `
 - `docs/GITFLOW_PR_GUIDE.md` if the team wants a stricter branch workflow
 - `docs/SUPPORT_MATRIX.md` and `docs/TROUBLESHOOTING.md` for first-run support
 - `docs/ai/LESSONS.md` after each slice
-- `docs/AI_ONBOARDING_PROMPT.md` after analysis
+- `.quiver/templates/` only when the team explicitly exports packaged templates
 
 ## Good Defaults
 

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_SCAN.json`
-   - `docs/PROJECT_MAP.md`
-   - `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.
 
@@ -66,13 +59,36 @@ Actúa como asistente de onboarding de IA para este proyecto. Tu objetivo es com
 
 Usa el menor contexto que todavía permita resolver la tarea:
 
-- **Onboarding:** usa mapas y metadatos primero. Lee `docs/PROJECT_SCAN.json` y `docs/PROJECT_MAP.md` antes de abrir archivos fuente. Después usa `docs/AI_CONTEXT.md`, `docs/CONTEXTO.md` y `docs/WORKFLOW.md` para completar vacíos.
+- **Onboarding:** usa mapas y metadatos primero. Lee `docs/PROJECT_MAP.md` antes de abrir archivos fuente. Si necesitás el scan crudo, usá `.quiver/scans/PROJECT_SCAN.json`. Después usa `docs/AI_CONTEXT.md`, `docs/CONTEXTO.md` y `docs/WORKFLOW.md` para completar vacíos.
+- **Planner:** usa contexto amplio solo para onboarding y planificación. El planner genera criterios de aceptación, plan técnico, specs, slices, handoffs y cuerpo de PR con aprobación humana entre fases.
+- **Executor:** usa contexto mínimo del slice. El executor parte de `slice.json` y `EXECUTION_BRIEF.md`, puede modificar código solo cuando el usuario lo autoriza y debe mantenerse dentro de `slice.json.files`.
 - **Implementación:** no implementes durante onboarding salvo autorización explícita. Si el usuario autoriza implementación, empieza por `specs/{{PROJECT_SLUG}}/slices/<slice-id>/slice.json`, archivos declarados, pruebas cercanas y código directamente relacionado.
 - **Review:** empieza por `git diff` y el alcance del slice antes de abrir archivos completos.
 - **Debug:** empieza por el comando, exit code, primer error relevante, stacktrace y código más cercano al cambio.
 
 Prefiere resúmenes, deltas y metadatos antes que lecturas completas cuando sean suficientes.
 
+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: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
 
 1. Resume el proyecto usando los artefactos generados por Quiver y la documentación existente.
@@ -83,10 +99,11 @@ Prefiere resúmenes, deltas y metadatos antes que lecturas completas cuando sean
 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
 
-- Cita `docs/PROJECT_SCAN.json` y `docs/PROJECT_MAP.md` cuando hagas afirmaciones sobre stack, comandos o estructura.
+- Cita `docs/PROJECT_MAP.md` cuando hagas afirmaciones sobre stack, comandos o estructura. Si usás datos del scan crudo, cita `.quiver/scans/PROJECT_SCAN.json`.
 - Indica rutas omitidas o señales faltantes.
 - Mantén la respuesta enfocada en documentación y contexto de onboarding salvo que el usuario haya autorizado cambios de código de producto.
 - No cambies reglas del workflow de Quiver salvo que el usuario lo pida explícitamente.

package/docs/COMMANDS.md.template

@@ -9,28 +9,100 @@ This document is the canonical command reference for the orchestration roadmap.
 
 | Command | Purpose | OS | Since | Example |
 |---------|---------|----|-------|---------|
+| `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: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`, 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
 
 | Flag | Applies to | Purpose |
 |------|------------|---------|
+| `--minimal` | `init` | Create only the essential onboarding contract |
+| `--full` | `init` | Create the broad legacy-compatible layout explicitly |
+| `--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 |
+| `--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`, `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`, `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/GITFLOW_PR_GUIDE.md.template

@@ -11,11 +11,22 @@ This guide explains how to open and review spec PRs without breaking the canonic
 
 - One slice = one commit
 - One spec = one PR
+- One spec should be worked from one dedicated worktree/branch.
 - Slice numbers reset per spec. `slice-01` is the first slice in each spec.
 - Do not commit directly to `develop`
 - Open and merge the documentation PR before the first slice starts execution
 - Do not open the spec PR before the documentation PR is merged
 
+## AI PR Preflight
+
+Before asking an AI agent to prepare PR work, validate the local setup:
+
+```bash
+npm run quiver:ai:pr -- --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+```
+
+Use the SSH host alias from your Git remote separately from the key path. Quiver validates `gh`, `gh auth status`, the remote, branch/worktree state, this guide, and the identity file. It does not install `gh`, edit SSH config, or create a PR in dry-run mode.
+
 ## Review Guidance
 
 - Start with `git diff` and the slice scope before opening full files.

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
 ```