@poetic-ai/poetic 1.42.0

package/docs/getting-started/QUICK_START.md

@@ -0,0 +1,294 @@
+# Poetic Quick Start
+
+> Install the public `@poetic-ai/poetic` package from npm or with the official
+> `install.sh`. For automation, pin the release tag and matching package version
+> and use `--strict`. Then run
+> `poetic provider setup --first-run`, then enter the target git repository and
+> run `poetic init` then `poetic run`. Use `poetic doctor` to check readiness;
+> it is not a substitute for init. Use `poetic init quickstart` as an
+> optional readiness/branch helper after init.
+
+Get going in five minutes or less. Start with the provider-setup and
+target-repository flow below. Prefer `poetic run` for
+straightforward single-provider execution; use `poetic compete` when you want
+judge scores/rationale or multi-variant comparative selection.
+
+Support tiers match `poetic --help` (Beta / Advanced / Internal). The supported
+surface contract is defined in
+[RELEASE_VERIFICATION.md](https://github.com/ebrindley/Poetic/blob/main/docs/RELEASE_VERIFICATION.md#supported-surface-contract).
+
+## 5-Minute Flow (Zero to Working in Under 10 Minutes)
+
+| Step | Focus                      | Target Duration | Checkpoint                                    |
+| ---- | -------------------------- | --------------- | --------------------------------------------- |
+| 1    | Install the public package | ~2 min          | `poetic --version` prints the version         |
+| 2    | Set up a provider          | ~3 min          | `poetic provider list` shows a ready provider |
+| 3    | Init the repo, then run    | ~3 min          | `poetic init` then `poetic run`; doctor is readiness, not a substitute for init |
+
+> Total target time: 2 + 3 + 3 = 8 minutes, leaving a working buffer before hitting 10.
+
+## Step 1: Install Poetic (~2 Minutes)
+
+Supported public installs:
+
+```bash
+npm install -g @poetic-ai/poetic@1.42.0
+poetic --version
+```
+
+The repository is currently private. Authenticated users can run the exact
+installer through GitHub CLI:
+
+```bash
+gh api -H 'Accept: application/vnd.github.raw+json' \
+  'repos/ebrindley/Poetic/contents/install.sh?ref=v1.42.0' \
+  | bash -s -- --version 1.42.0 --strict
+```
+
+When the repository becomes public, the floating one-liner will work without
+authentication:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ebrindley/Poetic/main/install.sh | bash
+```
+
+If that prints `1.42.0` or later, you are ready for the next step.
+In an interactive terminal, bare `poetic` opens the local dashboard; in CI or
+non-interactive shells it prints lightweight help.
+
+### Conversational TUI
+
+Run `poetic` in the target repository to open the operator workspace. Its stable
+vocabulary is:
+
+- **Work** — planned tasks, backlog items, and configuration.
+- **Details** — the selected or running item's status, activity, and evidence.
+- **Conversation** — provider-neutral chat and reviewed action proposals.
+
+At 140 columns the three areas appear together. Around 100 columns the workspace
+uses two columns, and at 80 columns it stacks the same information so the prompt
+and controls remain usable. When a Work or Details object is attached to the
+conversation, the `Context:` bar names that selected object above the transcript;
+use the displayed `Esc clear` action to detach it. Use `/context attach` to pin
+the currently selected Work object without making it follow later navigation.
+
+Conversation uses the provider selected by resolved configuration or the current
+TUI session. Enter plain text to chat, or use `/chat-cli <provider>` to choose a
+different ready provider without changing the conversation UI. A same-provider
+turn can use that provider's native continuation when supported and when Poetic
+has valid continuation metadata. Changing providers cannot move a native provider
+session, so Poetic asks how the new provider should join:
+
+1. **Continue with context** (recommended and selected by default) — bounded
+   recent finalized messages plus the selected object, objective, decisions,
+   blockers, and artifact references that are available.
+2. **Recent messages** — bounded finalized messages only.
+3. **Summary** — the available summary and structured context, without replaying
+   message history.
+4. **Fresh** — no conversation history; selected-object inclusion is explicit.
+5. **Something else...** — choose exactly which visible messages and Poetic-owned
+   fields to carry before confirming.
+
+The dialog shows what the selected choice includes and omits before confirmation.
+Handoffs can carry finalized user/assistant messages and Poetic object references,
+objectives, summaries, decisions, blockers, and artifacts when available. They do
+not transfer provider-private reasoning, credentials, live streaming state, tool
+state, or a provider-native session to another provider.
+
+Suggested commands use one two-step preview flow: `Enter` first reviews the next
+proposal; the preview then shows its action, route, sandbox posture, cost label,
+warnings, and errors. `Enter` again runs an eligible preview, while `Esc` returns
+to editing. In the proposal list, `s` skips the current suggestion and `Esc`
+cancels the remaining suggestions.
+
+Useful keys are shown in the footer and `?` help: `j`/`k` moves selection,
+`1`/`2`/`3` chooses the numbered workspace panel, `[`/`]` cycles panels, `Tab`
+moves focus, `/` opens command entry, and `Ctrl+T` toggles chat metadata. Quit
+cleanly with `q` from navigation or `/quit` from command entry; wait for the
+process to exit before closing the terminal.
+
+## Step 2: Set Up a Provider, Then Init the Target Repo (~3 Minutes)
+
+Set up providers from any directory, then switch to the target repository:
+
+```bash
+poetic provider setup --first-run
+cd /path/to/your/project
+poetic init
+poetic doctor
+# Optional branch helper after init:
+poetic init quickstart "my first task" --branch
+```
+
+`poetic init` is the full project scaffold (optional `--purpose`). `poetic doctor`
+reports readiness; it is not a substitute for init. `poetic init quickstart` is an
+optional readiness and branch helper. It
+does not install or authenticate providers. Poetic works once at least one provider CLI
+is installed and authenticated. The primary validated path uses
+Claude or Codex. Grok, Cursor, and OpenCode are supported validated
+alternatives; Antigravity is supported validated. Gemini is experimental: Google retired its CLI
+for free, AI Pro, and Ultra tiers on 2026-06-18, so prefer Antigravity.
+
+`poetic provider list` reports readiness. For an offline view of the configured
+defaults that never touches your environment, the internal `poetic explain
+providers` reads embedded config only (not advertised in `poetic --help`):
+
+```bash
+poetic explain providers
+```
+
+For explicit setup, run `poetic provider setup --providers claude,codex`, then
+authenticate with `claude auth login` and/or `codex login`.
+
+Verify readiness:
+
+```bash
+poetic provider list
+# or:
+poetic doctor --provider claude
+```
+
+## Step 3: First Success — Run a Task (~3 Minutes)
+
+Use a disposable project repo or a feature branch in your own repo. Do not run
+this inside the Poetic source checkout or inside another nested git repository
+if you later use `compete apply` (it targets the nearest git root). Do not run
+pipeline commands on `main` without `--allow-main`.
+
+### Preferred: straightforward single-provider execution
+
+```bash
+cd /path/to/your/project
+poetic init quickstart "my first task" --branch --branch-name fix/my-first-task
+# fix/ is one of several product prefixes; feature/, docs/, and test/ behave identically
+
+poetic run "Create a file named first-task-marker.txt in the repository root with exactly this single line: FIRST_TASK_OK"
+# Note worktree and/or patch paths in the output when delivery stays isolated
+```
+
+`poetic run` uses an isolated worktree by default. Repo-root delivery is not
+guaranteed: successful runs print worktree and optional patch paths under
+`.poetic/` when changes did not land in-place. Use those paths to inspect or
+recover (`git apply --3way <patch>` or `cd <worktree> && git diff`).
+
+### When you want judge scores or multi-variant comparison
+
+```bash
+poetic compete "Create a file named first-task-marker.txt in the repository root with exactly this single line: FIRST_TASK_OK" \
+  --variant claude:conservative
+# AI judging is the default — no need to pass --judge ai
+# Note the competition ID and apply guidance in the output
+
+# Stay on the fix/my-first-task branch created above — no second branch is needed
+poetic compete apply <competition-id>
+
+git status
+# first-task-marker.txt should appear in the repo root after a successful apply
+```
+
+Single-variant judged `compete` is **graded evaluation** (scores and rationale).
+Multi-variant judged `compete` is **comparative selection**. Apply harvested
+results on a `fix/*`, `docs/*`, or `test/*` branch — `run/*` and `validation/*`
+are evidence branches, not apply targets.
+
+The example above is an edit task. Analysis-classified tasks auto-use Fusion
+peer synthesis; pass `--judge ai` explicitly when you want graded judge
+feedback instead of Fusion.
+
+Direct `run` and judged `compete` are **Beta**. Do not treat either as an
+A-grade claim until post-apply verification, judgeWinner/deliveryArtifact
+identity, and the end-to-end judged apply path are validated.
+
+## For Agents and Scripts
+
+Agents and non-interactive integrations should use the compact JSON context
+surface instead of reading the full documentation set or running the
+interactive quickstart flow:
+
+```bash
+poetic context --json
+```
+
+### Beta limitations (read before trying other commands)
+
+| Path                                         | What to expect                                                                      |
+| -------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `poetic run` / `poetic fast` / `poetic best` | Preferred default for single-provider work; changes may stay in a worktree or patch |
+| Single-variant judged `compete`              | Graded evaluation (AI judge default); apply with `compete apply` on `fix/*`          |
+| Multi-variant judged `compete`               | Comparative selection with default AI judging                                       |
+| `--judge off`, single variant                | Ungraded execution through competition infrastructure                               |
+| `--judge off`, multiple variants             | Manual comparison; no automatic winner — apply a chosen variant explicitly          |
+| `plan approve --to-sprint --no-apply`        | Still runs Flywheel; skips merge only (use `build "<intent>" --planned --no-apply` for plan-only) |
+| `compete apply` on `run/*`                   | Blocked — use `fix/*`, `docs/*`, or `test/*`                                        |
+| Validation from `main`                       | Use `poetic compete --validation-run ...`; move real fixes to `fix/*` before apply  |
+| Cleanup                                      | Dry-run first with `poetic cleanup doctor` or `poetic cleanup worktrees`            |
+
+## Where to Go Next
+
+Once your first task completes:
+
+- Explore command reference: [`../CLI_REFERENCE.md`](../CLI_REFERENCE.md) for every flag and subcommand
+- Follow the setup notes: [`./SETUP.md`](./SETUP.md) if you need more providers
+- Understand Poetic's architecture: [`ARCHITECTURE.md`](https://github.com/ebrindley/Poetic/blob/main/ARCHITECTURE.md)
+- Manage costs: `poetic cost status` and related CLI commands
+- Power-user pattern: pair a fast executor with an independent AI code reviewer on every task — [`./EXECUTOR_REVIEWER.md`](https://github.com/ebrindley/Poetic/blob/main/docs/getting-started/EXECUTOR_REVIEWER.md)
+
+## Validation Checklist (Can you stay under 10 minutes?)
+
+These checks are the public-release success criteria from the
+[supported surface contract](https://github.com/ebrindley/Poetic/blob/main/docs/RELEASE_VERIFICATION.md#supported-surface-contract):
+
+- [ ] Installed the public package and confirmed `poetic --version` | (~2 min)
+- [ ] Ran provider setup and saw `poetic provider list` report at least one provider ready | (~3 min)
+- [ ] Ran `poetic context --json` if using an agent or script | (~1 min)
+- [ ] Ran `poetic run` for a small task (or judged `compete` when scores/comparison are needed) | (~3 min)
+- [ ] Inspected delivery: worktree/patch output for `run`, or `git status` after `compete apply` | (~1 min)
+
+**Beta execution paths:** `poetic run`, judged `compete`, and `--judge off`
+modes are supported Beta surfaces — not an A-grade claim. Internal-tier
+commands (`plan approve`, `sprint run`, `swarm`) remain outside the first-user path.
+
+## Outcome and optimization aliases
+
+```bash
+poetic run "task"      # Preferred: straightforward single-provider execution
+poetic fast "task"     # Speed-focused, parallel execution
+poetic best "task"     # Quality-focused, strategy competition
+poetic cheap "task"    # Cost-focused, single-pass execution
+poetic compete "task" --variant claude:conservative
+                       # Graded evaluation (default AI judge); add more --variant for comparison
+poetic provider setup             # Interactive setup wizard
+poetic provider list     # Check readiness
+poetic explain providers # Offline view of configured defaults (internal tier)
+poetic doctor --all      # Full environment + providers health report
+poetic --help            # Global help and subcommand hints
+```
+
+## Provider Setup (Optional)
+
+Install and authenticate whichever provider(s) you want to use. See
+`./SETUP.md` and `../PROVIDER_SETUP.md` for provider-specific notes.
+
+Run `poetic provider list` after installing anything new.
+
+## Common Issues
+
+| Issue                              | Solution                                                                                             |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `poetic` command missing           | Reinstall `@poetic-ai/poetic`, confirm the npm global bin is on `PATH`, and reopen your shell |
+| Provider error                     | Run `poetic provider list` (or `poetic doctor --all`) and follow the reported remediation            |
+| Pipeline command blocked on `main` | Use `poetic init quickstart "task" --branch --branch-name fix/<slug>`, then run and apply from that branch   |
+| Success but no file in repo root   | Expected for default `poetic run` isolation — inspect printed worktree/patch paths, or use `compete apply` on a `fix/*` branch after compete |
+| Changes appeared in the wrong repo | Run from an external project directory; `compete apply` targets the nearest git root |
+| Validation only, no product patch  | Use `poetic compete --validation-run ...` and do not harvest from that branch unless you create a separate `fix/*` branch |
+
+Need more help? [`../TROUBLESHOOTING.md`](../TROUBLESHOOTING.md) has deeper guidance.
+
+## Keep Exploring
+
+- Use `poetic next` to see actionable work items
+- Run multi-variant `poetic compete` for comparative selection (AI judge default)
+- Authorized contributors can build the CLI locally: [`./BUILDING.md`](https://github.com/ebrindley/Poetic/blob/main/docs/getting-started/BUILDING.md)
+- Read about AI sessions and flywheels: [`../WORKFLOW_CHECKLIST.md`](https://github.com/ebrindley/Poetic/blob/main/docs/WORKFLOW_CHECKLIST.md) and [`../FLYWHEEL.md`](https://github.com/ebrindley/Poetic/blob/main/docs/FLYWHEEL.md)
+
+Ready for the next command? Prefer `poetic run` for another straightforward task, or `poetic compete` when you want graded feedback or comparative selection.

package/docs/getting-started/README.md

@@ -0,0 +1,188 @@
+# Getting Started with Poetic
+
+Welcome to Poetic. This guide helps users install the public npm package, set
+up a provider, and run a first task from the target project. Agents and scripts
+have a separate compact context path.
+
+## What is Poetic?
+
+Poetic is a public MIT-licensed TypeScript CLI for orchestrating local AI coding
+providers. Use and distribution are governed by the repository
+[LICENSE](../../LICENSE). Support tiers match
+`poetic --help` (Beta / Advanced / Internal).
+The narrow dependable surface covers readiness (`provider list`, `doctor`),
+orientation (`next`, backlog capture), and stable telemetry reads (`telemetry`,
+`cost`). Execution paths remain Beta. Full tier tables and exclusions are in
+[RELEASE_VERIFICATION.md](https://github.com/ebrindley/Poetic/blob/main/docs/RELEASE_VERIFICATION.md#supported-surface-contract).
+
+**Preferred first path:** install with npm or the official `install.sh`. Pin the
+release tag and matching package version with `--strict` for automation. Then run
+`poetic provider setup --first-run`, then in the target repository run
+`poetic init` then `poetic run`. Use `poetic doctor` to check readiness; it is
+not a substitute for init. Use `poetic init quickstart` as an optional
+branch helper after init. Inspect the printed worktree or patch path when delivery
+stays isolated. Use single-variant judged `poetic compete` when you want graded
+feedback, or add variants for comparative selection; AI judging is the default
+for ordinary edit/code competition. Analysis-classified tasks auto-use Fusion;
+pass `--judge ai` explicitly for graded judge feedback instead. Provider release tiers are in
+[PROVIDER_RELEASE_TIERS.md](../reference/PROVIDER_RELEASE_TIERS.md).
+
+**Beta or advanced execution:** `run`, judged
+`compete`, sprint/backlog operator flows, and internal-tier orchestration
+(`plan approve`, `sprint run`, `swarm`) are available with the documented
+delivery and validation caveats. Hidden `fast` / `best` / `cheap` aliases
+rewrite onto `poetic run --optimize`.
+
+Poetic aims for parallel execution, strategy synthesis, provider routing, and
+outcome-focused commands; those capabilities are uneven across tiers today.
+
+## Quick Navigation
+
+### 1. [Quick Start Guide](./QUICK_START.md)
+**Start here.** Install the public npm package, set up a provider, then run
+`poetic init` in the target repository and `poetic run` for a first task.
+`poetic doctor` is readiness, not a substitute for init. Use judged
+`poetic compete` for graded feedback or multi-variant comparison.
+
+Perfect for: Proving the 5-minute flow and reaching a visible first success.
+
+### 2. [Setup Instructions](./SETUP.md)
+Minimum requirements and automated setup scripts to get your environment ready.
+
+Perfect for: Understanding prerequisites and running automated environment detection.
+
+### 3. Contributor Source Build
+The source checkout includes
+[BUILDING.md](https://github.com/ebrindley/Poetic/blob/main/docs/getting-started/BUILDING.md)
+for local linking and development.
+
+Perfect for: Contributors and developers working on unreleased source.
+
+### 4. [Prompt Commands Quick Reference](https://github.com/ebrindley/Poetic/blob/main/docs/reference/CLI_PROMPT_COMMANDS.md)
+Quick reference for the prompt management CLI commands (list, status, optimize, etc.).
+
+Perfect for: Advanced users who want to manage and optimize their prompts.
+
+## Recommended Learning Path
+
+### For New Users
+1. Run `npm install -g @poetic-ai/poetic@1.42.0` or the authenticated official `install.sh` command in the Quick Start, then run `poetic provider setup --first-run`, `poetic init`, and `poetic run` in the target repository. The anonymous raw-GitHub one-liner becomes available when the repository is public. `poetic doctor` remains a readiness check.
+2. Follow the [Quick Start Guide](./QUICK_START.md) for your first task
+3. Explore judged `poetic compete` as needed. `poetic init quickstart` remains an optional branch helper.
+
+### For Agents and Scripts
+1. Run `poetic context --json` to read compact project context
+2. Skip the interactive `quickstart` flow unless a human is driving setup
+3. Use side-effect tiers in the JSON to choose read-only, local-write, git, or provider-call actions
+
+### For Developers
+1. Follow [Setup Instructions](./SETUP.md) to install dependencies
+2. Use
+   [BUILDING.md](https://github.com/ebrindley/Poetic/blob/main/docs/getting-started/BUILDING.md)
+   when working on unreleased code
+3. Read the [Quick Start Guide](./QUICK_START.md) to understand usage patterns
+4. Explore the [Prompt Commands](https://github.com/ebrindley/Poetic/blob/main/docs/reference/CLI_PROMPT_COMMANDS.md) for advanced optimization
+
+### For Contributors
+1. Complete the developer path above
+2. Review
+   [BUILDING.md](https://github.com/ebrindley/Poetic/blob/main/docs/getting-started/BUILDING.md)
+   for development workflow
+3. Check out [../INSTRUCTION_ARCHITECTURE.md](https://github.com/ebrindley/Poetic/blob/main/docs/INSTRUCTION_ARCHITECTURE.md) for instruction-system design
+4. See [../../CONTRIBUTING.md](../../CONTRIBUTING.md) for contribution guidelines
+
+## Common First Tasks
+
+### Install and Verify
+```bash
+npm install -g @poetic-ai/poetic@1.42.0
+# Future public source route:
+# curl -fsSL https://raw.githubusercontent.com/ebrindley/Poetic/main/install.sh | bash
+poetic --version
+poetic provider setup --first-run
+cd /path/to/your/project
+poetic init
+poetic doctor
+poetic init quickstart
+poetic provider list
+poetic context --json
+```
+
+See [Setup Instructions](./SETUP.md) for detailed steps.
+
+### Your First Command
+```bash
+# fix/ is one of several product prefixes; feature/, docs/, and test/ behave identically
+poetic init quickstart "my first task" --branch --branch-name fix/my-first-task
+poetic run "Add error handling to my API endpoints"
+
+# Optional: graded feedback (AI judge default)
+poetic compete "Add error handling to my API endpoints" --variant claude:conservative
+# Stay on the branch created above — no second branch is needed
+poetic compete apply <competition-id>
+git status
+```
+
+`poetic run` may leave changes in an isolated worktree or patch artifact.
+`compete apply` is needed only after a competition whose result you want to
+harvest. See [Quick Start Guide](./QUICK_START.md) for the full walkthrough and
+Beta limitations.
+
+### Configure Providers
+```bash
+poetic provider setup
+poetic provider setup --providers claude,codex
+poetic provider list
+```
+
+See [Setup Instructions](./SETUP.md) for provider-specific authentication.
+
+## Next Steps
+
+Once your first task completes:
+
+- **Support contract**:
+  [RELEASE_VERIFICATION.md](https://github.com/ebrindley/Poetic/blob/main/docs/RELEASE_VERIFICATION.md#supported-surface-contract) - dependable vs beta vs experimental surfaces
+- **Command reference**:
+  [../CLI_REFERENCE.md](../CLI_REFERENCE.md#support-tiers-and-release-contract) - tier labels aligned with `poetic --help`
+- **Parallel execution** (beta):
+  [../PARALLEL_EXECUTION.md](https://github.com/ebrindley/Poetic/blob/main/docs/PARALLEL_EXECUTION.md) - may use worktrees instead of repo-root delivery
+- **Cost tracking** (dependable reads): [../CLI_REFERENCE.md#cost-management](../CLI_REFERENCE.md)
+- **Provider setup** (per-provider validation): [../PROVIDER_SETUP.md](../PROVIDER_SETUP.md)
+- **Instruction architecture**: [../INSTRUCTION_ARCHITECTURE.md](https://github.com/ebrindley/Poetic/blob/main/docs/INSTRUCTION_ARCHITECTURE.md)
+
+## Getting Help
+
+- **Troubleshooting**: See [../TROUBLESHOOTING.md](../TROUBLESHOOTING.md) for common issues
+- **Command Help**: Run `poetic --help` or `poetic <command> --help`
+- **Issue Tracker**: [Report bugs on GitHub](https://github.com/ebrindley/Poetic/issues)
+- **Documentation**: Browse [../README.md](../README.md) for complete docs index
+
+## Quick Reference Card
+
+```bash
+# Preferred default: straightforward single-provider execution
+poetic init quickstart "task" --branch --branch-name fix/<slug>
+poetic run "task"
+
+# Optional: graded feedback or multi-variant comparison (AI judge default)
+poetic compete "task" --variant claude:conservative
+# Apply from the same branch; no second branch is needed
+poetic compete apply <competition-id>
+git status
+
+# Outcome commands (worktree/patch delivery caveats apply)
+poetic fast "task"     # Optimize for speed (parallel execution)
+poetic best "task"     # Optimize for quality (strategy synthesis)
+poetic cheap "task"    # Optimize for cost (efficient routing)
+
+# Helpful commands
+poetic init quickstart     # Target-repo readiness and safe-branch guidance
+poetic context --json # Compact project context for agents/scripts
+poetic --help          # Show all commands
+poetic provider list   # Check environment readiness
+poetic cost status     # View current costs
+poetic quality         # Run quality gates
+```
+
+---

package/docs/getting-started/SETUP.md

@@ -0,0 +1,52 @@
+# Poetic - Quick Requirements & Setup
+
+This document lists the minimum requirements and quick setup steps to get Poetic working locally.
+
+Minimum requirements
+- Node.js 24.x
+- npm >= 9
+- git
+
+Install Poetic
+- Run `npm install -g @poetic-ai/poetic@1.42.0` or the authenticated official `install.sh` command in [QUICK_START.md](./QUICK_START.md); afterward run `poetic provider setup --first-run`. The anonymous raw-GitHub one-liner becomes available when the repository is public.
+- For agents and scripts: run `poetic context --json` after installation to read compact project context.
+- For unreleased code or contributor validation: clone the public repository, run `npm install`, then `./scripts/build-poetic.sh`.
+
+Authentication Options:
+- Provider authentication is provider-specific (CLI login or API keys). Poetic guides you, but does not magically authenticate providers for you.
+
+Quick automated setup
+1. Preview providers without creating project state. `poetic explain` is an
+   internal-tier command (absent from `poetic --help`) kept read-only for exactly
+   this case -- it reads embedded config and never initializes a project:
+
+```bash
+poetic explain providers
+```
+
+2. Run provider setup before entering the target repository:
+
+```bash
+poetic provider setup --first-run
+```
+
+3. Or install specific providers non-interactively (examples):
+
+```bash
+poetic provider setup --providers grok
+```
+
+4. Verify the environment:
+
+```bash
+poetic provider list
+# or:
+poetic doctor --all
+```
+
+Notes
+- `poetic provider setup` can install some provider CLIs (safe installs by default) and prints actionable auth instructions.
+- For `curl | bash` installers, Poetic requires explicit opt-in: `POETIC_ALLOW_CURL_BASH=1`.
+- Claude and Codex are the primary validated providers. Grok, Cursor, and OpenCode are supported validated alternatives; Antigravity is supported validated. Gemini is experimental because Google retired its CLI for free, AI Pro, and Ultra tiers on 2026-06-18.
+- For non-interactive environments, prefer explicit flags: `poetic provider setup --providers <ids> --non-interactive`.
+- After provider setup, run `poetic init` then `poetic run` in the target repository. `poetic doctor` reports readiness; it is not a substitute for init. `poetic init quickstart` is an optional readiness and branch helper. It does not install or authenticate providers.

package/docs/reference/AGENT_CONTEXT.md

@@ -0,0 +1,38 @@
+# Agent Context
+
+Audience: Agent/client integrator.
+
+Agents should inspect Poetic state before choosing a command:
+
+```bash
+poetic context --json
+```
+
+The context output is read-only and compact. It reports:
+
+- project initialization state
+- git branch role, dirty state, and apply eligibility
+- passive provider readiness labels plus internal status codes
+- limits that block execution or mutation
+- recommended next actions with side-effect tiers
+
+Provider readiness in this snapshot uses passive setup checks and intentionally
+skips execute-tier sandbox probes. It can be less complete than `poetic provider
+list`; run `poetic provider list --json` when an agent needs the full operator
+readiness view.
+
+Use the CLI for execution and operator workflows. Prefer `poetic context --json`
+and other read-only CLI commands for compact state access; run mutating CLI
+commands only when the user explicitly asks.
+
+Side-effect tiers:
+
+- `read_only`: inspection only
+- `local_write`: writes local Poetic/project state
+- `provider_call`: may call an AI/provider-backed service
+- `git_mutation`: changes git state
+- `destructive_cleanup`: removes branches, worktrees, or runtime artifacts
+
+Prefer JSON output for automation. Do not read or edit managed planning files in
+`.poetic/backlog/`, `.poetic/sprint/`, or `.poetic/task/` directly; use Poetic
+CLI surfaces.

package/docs/reference/PROVIDER_RELEASE_TIERS.md

@@ -0,0 +1,34 @@
+# Provider Release Tiers
+
+This table is the public-release provider confidence contract. Command tiers
+(`Beta`, `Advanced`, `Internal`) describe CLI surface area; provider release
+tiers describe which local AI providers are expected to carry first-user
+workflows.
+
+`release_status` in `.poetic/config/providers.yaml` is the source of truth.
+`poetic doctor --matrix` renders the same status next to CLI/auth/runtime
+health, so local readiness can be checked before a run.
+
+## Tier Criteria
+
+| Release status | Criteria |
+| --- | --- |
+| Primary validated | Release-blocking provider path for first-user workflows; validated for the public-release path and expected to carry normal usage. |
+| Supported validated | Validated provider path for supported workflows; ready to use when its local CLI and auth are configured. |
+| Supported beta | Supported provider path with beta caveats; requires local readiness checks and a small runtime smoke before relying on it. |
+| Experimental | Available for exploration but excluded from the validated supported-surface claim. |
+
+## Provider Matrix
+
+| Provider ID | Provider | Release status | Runtime tier | Public-release role |
+| --- | --- | --- | --- | --- |
+| claude | Claude | Primary validated | Supported | Primary workhorse for coding, review, and judge/synthesis workflows. |
+| codex | Codex | Primary validated | Supported | Primary workhorse for coding and CLI-first release workflows. |
+| grok | Grok | Supported validated | Supported | Validated supported path for Grok CLI users with local auth configured. |
+| cursor | Cursor | Supported validated | Supported | Validated supported path for Cursor CLI users with local auth configured. |
+| opencode | OpenCode | Supported validated | Supported | Validated supported path for OpenCode users with upstream auth configured. |
+| gemini | Gemini | Experimental | Experimental | Sunsetting. Google retired Gemini CLI for free, AI Pro, and Ultra tiers on 2026-06-18; usable only with enterprise Code Assist or paid API keys. Opt-in via provider id or `--include-experimental`. Prefer `antigravity`. |
+| copilot | GitHub Copilot | Experimental | Experimental | Available, but outside the validated public-release matrix. |
+| kiro | Kiro | Experimental | Experimental | Experimental headless provider. |
+| antigravity | Antigravity | Supported validated | Supported | Successor to the sunsetting `gemini` provider; validated 2026-07-25 against authenticated `agy` 1.1.7. Passive auth readiness reports `unknown` (no non-interactive `agy` probe); auth errors surface at execution time. |
+| pi | Pi | Supported validated | Supported | Validated supported path for Pi CLI users with a configured backend. Pi is a backend-agnostic host, so cost and capability depend on the operator-configured backend; ratings are deliberately conservative. Validated 2026-07-26 against `pi` 0.82.1 with a cloud Anthropic backend, exercised through `poetic run` and `poetic compete` with incremental streaming. Passive auth readiness reports `unknown` (a local endpoint may need no credential); auth errors surface at execution time and are classified for retry. The local OpenAI-compatible (self-hosted) backend is not yet validated. |