@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/docs/getting-started/QUICK_START.md

@@ -0,0 +1,260 @@
+# Build Quick Start
+
+> Start with [INSTALL.md](../../INSTALL.md), the canonical installation and
+> initial setup guide. It distinguishes the public `@ebrindley/build` package
+> (`npm install -g @ebrindley/build`) from current GitHub source through
+> `install.sh --source git --version main`. Use the same instructions on local
+> machines and cloud VMs.
+
+Get going in five minutes or less. Start with the provider-setup and
+target-repository flow below, then describe your first task to `build`:
+it studies the project, does the work in an isolated worktree, checks it, and
+applies the result to your branch. Use `build run competition` when you want
+judge scores/rationale or multi-variant comparative selection, and a planned
+build for larger work.
+
+This guide is the canonical first-success path; the README, INSTALL.md, and the
+CLI reference link here rather than repeating it.
+
+Visibility tiers match `build --help` (Public / Advanced / Internal). Workflow
+maturity and the supported surface contract are defined in
+[RELEASE_VERIFICATION.md](https://github.com/ebrindley/build/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          | `build --version` prints the version         |
+| 2    | Set up a provider          | ~3 min          | A small provider invocation succeeds |
+| 3    | Init the repo, then build  | ~3 min          | `build init` then `build`; 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 Build (~2 Minutes)
+
+Follow [prerequisites and channel selection](../../INSTALL.md#choose-your-path),
+then [verify the installed executable and commit](../../INSTALL.md#verify-the-installation).
+Source builds on a cold machine can take longer than a package install.
+A version string alone cannot distinguish a preinstalled launcher from the new
+package. Bare `build` prints ordinary help in TTY, non-TTY, and CI contexts.
+
+## Step 2: Set Up a Provider, Then Init the Target Repo (~3 Minutes)
+
+Follow [provider setup](../../INSTALL.md#set-up-a-provider) and
+[project initialization](../../INSTALL.md#initialize-a-project-and-run-a-task).
+That guide covers interactive and unattended setup, externally supplied
+credentials, active-profile precedence, and a small live provider check.
+Deferred auth from `build doctor` is not a reason to skip execution.
+
+`build init` creates the full scaffold; `build init --safe-branch <name>` also
+creates and switches to a working branch. `build init quickstart` is an optional
+readiness check; it does not install or authenticate providers.
+Noninteractive init leaves optional knowledge and CI choices unchanged.
+For CI configuration and enforcement readback, see [CI setup](../CLI_REFERENCE.md#build-ci).
+
+A new `AGENTS.md` gets a short Build block that points agents at
+`build context --json`. Your project keeps its existing work tracker unless you
+opt in: `build init --work-tracking` adds the `build-work-tracking` block to a new
+`AGENTS.md`, and `build init generate-instructions --refresh-work-tracking` adds or
+restores it in an existing one. Ordinary init does not reapply the template or
+refresh blocks already in an existing guide.
+
+Commit the files `build init` creates before your first task: isolated
+worktrees start from your last commit, so uncommitted instructions such as a new
+`AGENTS.md` are not part of the agent's context.
+
+For the offline configuration preview, `build explain providers` reads embedded
+config only. For available providers and release tiers, see
+[provider setup](../PROVIDER_SETUP.md).
+
+## 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 Build source checkout or inside another nested git repository
+if you later use `run competition apply` (it targets the nearest git root). Do not run
+pipeline commands on `main` without `--allow-main`.
+
+### Start here: describe the task and let Build build it
+
+```bash
+cd /path/to/your/project
+build init --safe-branch fix/my-first-task
+# fix/ is one of several product prefixes; feature/, docs/, and test/ behave identically
+
+build "Create first-task-marker.txt with exactly one line: FIRST_TASK_OK. Do not modify any other files."
+git status
+# first-task-marker.txt appears in the repo root when the build succeeds
+```
+
+`build` studies the repository and gathers the context the agent needs,
+chooses the quick route for a small task like this one, runs it in an isolated
+worktree, checks the result, and applies it to your branch. Its default output
+includes a `Route reason:` line; add `--dry-run` to preview the route and the context
+without executing anything.
+
+### Direct single-provider execution
+
+```bash
+build run "Create first-task-marker.txt with exactly one line: FIRST_TASK_OK. Do not modify any other files."
+```
+
+`build run` executes one provider in an isolated worktree, and its result may stay
+there. Successful runs print worktree and optional patch paths under `.build-project/`
+when changes did not land in-place: `build run apply <task-id>` applies the patch
+on the current branch, and `cd <worktree> && git diff` inspects it.
+
+### When you want judge scores or multi-variant comparison
+
+```bash
+build run competition "Create first-task-marker.txt with exactly one line: FIRST_TASK_OK. Do not modify any other files." \
+  --variant claude
+# 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
+build run competition apply <competition-id>
+
+git status
+# first-task-marker.txt should appear in the repo root after a successful apply
+```
+
+Single-variant judged `run competition` is **graded evaluation** (scores and rationale).
+Multi-variant judged `run competition` 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. For analysis questions, use `build run fusion`
+(or `--profile analysis`) to get peer synthesis instead of graded judging. For a quick
+question about your code, `build run fusion --fast` is usually faster; see
+[fast or regular](../CLI_REFERENCE.md#build-run-fusion) for when to use each.
+
+`build` and direct `run` are **Beta**; direct `run` because delivery may
+remain in an isolated worktree or patch. Judged `run competition`, `run competition apply`, and default agentic
+synthesis are **Dependable**. The `ai` and `multi-lens` judges are supported;
+cherry-pick synthesis remains experimental.
+
+`build` applies successful execution results by default. In the planned
+build path, `build "<intent>" --planned --no-apply` stops after planning;
+it does not execute a candidate for later application. For execution followed
+by a separate application step, use the competition and apply commands above.
+See [build options](../CLI_REFERENCE.md#build) for the current contract.
+
+## Next: Plan Larger Work
+
+Planning is how Build keeps larger, automated work safe. Capture work in the
+backlog as you think of it, see what is ready, and hand a larger intent to a
+planned build:
+
+```bash
+build plan backlog add "Add rate limiting to the public API"   # saves a draft; exits 1 until its spec is complete
+build plan backlog refine <id>                                 # <id> is printed by add; answer the prompts
+build plan next
+build --planned "Add rate limiting to the public API"
+```
+
+A planned build decomposes the intent, checks it for blockers (add `--interactive`
+to answer them yourself), runs each stage in an
+isolated worktree, and adds a review by a second AI provider when you have one set
+up. The [Sprint Planning Guide](https://github.com/ebrindley/build/blob/main/docs/SPRINT_PLANNING_GUIDE.md#why-plan) covers the
+full loop, including executing and finalizing tracked backlog items.
+
+## 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
+build context --json
+```
+
+### Beta limitations (read before trying other commands)
+
+| Path                                         | What to expect                                                                      |
+| -------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `build`                               | Intent-first default; applies a successful result to your branch; `--planned --no-apply` stops after planning |
+| `build run` (optionally `--optimize cost`) | Direct single-provider execution; changes may stay in a worktree or patch |
+| Single-variant judged `run competition`      | Graded evaluation (AI judge default); apply with `run competition apply` on `fix/*`  |
+| Multi-variant judged `run competition`       | 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) |
+| `run competition apply` on `run/*`           | Blocked — use `fix/*`, `docs/*`, or `test/*`                                        |
+| Validation from `main`                       | Use `build run competition --validation-run ...`; move real fixes to `fix/*` before apply  |
+| Cleanup                                      | Dry-run first with `build cleanup doctor` or `build 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 Build's architecture: [`ARCHITECTURE.md`](https://github.com/ebrindley/build/blob/main/ARCHITECTURE.md)
+- Manage costs: `build telemetry cost status` and related CLI commands
+- Power-user pattern: pair an executor with an independent AI code reviewer on every task — [`./EXECUTOR_REVIEWER.md`](https://github.com/ebrindley/build/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/build/blob/main/docs/RELEASE_VERIFICATION.md#supported-surface-contract):
+
+- [ ] Installed the public package and confirmed `build --version` | (~2 min)
+- [ ] Completed provider setup and a small live invocation | (~3 min)
+- [ ] Ran `build context --json` if using an agent or script | (~1 min)
+- [ ] Ran `build` for a small task (or judged `run competition` when scores/comparison are needed) | (~3 min)
+- [ ] Confirmed delivery with `git status` after `build` or `run competition apply` | (~1 min)
+
+**Execution maturity:** `build` and direct `build run` remain Beta. Judged `run competition`,
+`run competition apply`, `--judge off`, and default agentic synthesis are dependable.
+Internal-tier commands (`plan sprint run`, `run flywheel`) remain outside the
+first-user path.
+
+## Cost mode and common commands
+
+```bash
+build "task"    # Start here: intent-first delivery, applied to your branch
+build --planned "intent"       # Larger work: decompose, check blockers, run stages in isolation
+build run "task"      # Direct single-provider execution
+build run "task" --optimize cost     # Cost-focused, single-pass execution on fast models
+build run competition "task" --variant claude
+                       # Graded evaluation (default AI judge); add more --variant for comparison
+build provider setup             # Interactive setup wizard
+build provider list     # Check readiness
+build explain providers # Offline view of configured defaults (internal tier)
+build doctor --all      # Full environment + providers health report
+build --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 `build provider list` after installing anything new.
+
+## Common Issues
+
+| Issue                              | Solution                                                                                             |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `build` command missing           | Reinstall `@ebrindley/build`, confirm the npm global bin is on `PATH`, and reopen your shell |
+| Provider error                     | Run `build provider list` (or `build doctor --all`) and follow the reported remediation            |
+| Pipeline command blocked on `main` | Use `build init --safe-branch fix/<slug>`, then run and apply from that branch   |
+| Success but no file in repo root   | Expected for default `build run` isolation — run the printed `build run apply <task-id>`, or `run competition apply` after a competition, on a `fix/*` branch |
+| Changes appeared in the wrong repo | Run from an external project directory; `run competition apply` targets the nearest git root |
+| Validation only, no product patch  | Use `build run competition --validation-run ...` and do not harvest from that branch unless you create a separate `fix/*` branch |
+
+Cleanup commands default to dry-run. Inspect with `build cleanup doctor`, then
+add `--execute` to the specific command, such as `build cleanup worktrees --execute`.
+Managed directories such as `backlog/`, `sprint/`, and `task/` are changed through
+the CLI, not by hand.
+
+Need more help? [`../TROUBLESHOOTING.md`](../TROUBLESHOOTING.md) has deeper guidance.
+
+## Keep Exploring
+
+- Use `build plan next` to see actionable work items
+- Run multi-variant `build run competition` for comparative selection (AI judge default)
+- Authorized contributors can build the CLI locally: [`./BUILDING.md`](https://github.com/ebrindley/build/blob/main/docs/getting-started/BUILDING.md)
+- Read about AI sessions and flywheels: [`../WORKFLOW_CHECKLIST.md`](https://github.com/ebrindley/build/blob/main/docs/WORKFLOW_CHECKLIST.md) and [`../FLYWHEEL.md`](https://github.com/ebrindley/build/blob/main/docs/FLYWHEEL.md)
+
+Ready for the next command? Use `build` for another task, a planned build for larger work, or `build run competition` when you want graded feedback or comparative selection.

package/docs/getting-started/README.md

@@ -0,0 +1,198 @@
+# Getting Started with Build
+
+Welcome to Build. 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 Build?
+
+Build is a public MIT-licensed TypeScript CLI for safe, high-velocity
+development with the AI coding tools you already use. It carries work through
+one lifecycle: prepare the repository, plan the work, run it in isolated
+worktrees, verify it, land it safely, and observe what happened (see
+[VISION.md](https://github.com/ebrindley/build/blob/main/VISION.md#the-lifecycle)).
+Use and distribution are governed by the repository
+[LICENSE](../../LICENSE). Visibility tiers match `build --help` (Public /
+Advanced / Internal); workflow maturity is documented separately. The
+dependable surface covers readiness (`provider list`, `doctor`), orientation
+(`next`, backlog capture), stable telemetry reads (`telemetry`, `cost`), judged
+competition, competition apply, and default agentic synthesis. Direct `run`
+remains Beta because of its isolated-worktree and patch-delivery caveat. Full
+tier tables and exclusions are in
+[RELEASE_VERIFICATION.md](https://github.com/ebrindley/build/blob/main/docs/RELEASE_VERIFICATION.md#supported-surface-contract).
+
+**Preferred first path:** follow [INSTALL.md](../../INSTALL.md) for channel
+selection (`npm install -g @ebrindley/build` or source `install.sh`), executable
+verification, provider setup, and `build init` in the target repository, then
+the [Quick Start](./QUICK_START.md) for a first `build`.
+The guide covers both people and automation. Use single-variant judged
+`build run competition` when you want graded feedback, or add variants for comparative
+selection; AI judging is the default
+for ordinary edit/code competition. Fusion peer synthesis is used only when you declare
+analysis (`build run fusion`, `--profile analysis`, `--analysis-only`). Provider
+release tiers are in
+[PROVIDER_RELEASE_TIERS.md](../reference/PROVIDER_RELEASE_TIERS.md).
+
+**Other execution surfaces:** `build` and direct `run` are Beta. Backlog capture,
+`plan next`, `plan approve`, and planned builds are Public; the backlog ship loop
+(`plan backlog execute`, `plan backlog finalize`) and sprint management are
+Advanced; `plan sprint run` is an Internal alias of `run sprint`. Judged
+`run competition` and `run competition apply` are Public / Dependable workflows. Use
+`build run --optimize cost` for single-pass runs on fast models.
+
+Build aims for parallel execution, peer synthesis, provider routing, and
+optimization modes; 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
+`build init` in the target repository and `build` for a first task.
+`build doctor` is readiness, not a substitute for init. Use judged
+`build run competition` for graded feedback or multi-variant comparison, and a
+planned build for larger work.
+
+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/build/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/build/blob/main/docs/reference/CLI_PROMPT_COMMANDS.md)
+Quick reference for the stored prompt commands (list, show, activate, rollback, history).
+
+Perfect for: Advanced users who manage versioned prompts for workflows.
+
+## Recommended Learning Path
+
+### For New Users
+1. Run `npm install -g @ebrindley/build` or the authenticated official `install.sh` command in the Quick Start, then install and authenticate a provider, run provider setup, `build init`, and `build` in the target repository. The anonymous raw-GitHub one-liner becomes available when the repository is public. `build doctor` remains a readiness check.
+2. Follow the [Quick Start Guide](./QUICK_START.md) for your first task
+3. Explore judged `build run competition` and planned builds as needed. `build init --safe-branch <name>` creates a working branch.
+
+### For Agents and Scripts
+1. Run `build 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/build/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/build/blob/main/docs/reference/CLI_PROMPT_COMMANDS.md) for stored prompt management
+
+### For Contributors
+1. Complete the developer path above
+2. Review
+   [BUILDING.md](https://github.com/ebrindley/build/blob/main/docs/getting-started/BUILDING.md)
+   for development workflow
+3. Check out [../INSTRUCTION_ARCHITECTURE.md](https://github.com/ebrindley/build/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 @ebrindley/build
+# Future public source route:
+# curl -fsSL https://raw.githubusercontent.com/ebrindley/build/main/install.sh | bash
+build --version
+build provider setup --first-run
+cd /path/to/your/project
+build init
+build doctor
+build init quickstart
+build provider list
+build 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
+build init --safe-branch fix/my-first-task
+# Commit the files init created, then:
+build "Add error handling to my API endpoints"
+git status
+```
+
+`build` studies the repository, runs the work in an isolated worktree,
+checks it, and applies a successful result to your branch. See the
+[Quick Start Guide](./QUICK_START.md) for the full walkthrough, judged
+competitions, planned builds, and Beta limitations.
+
+### Configure Providers
+```bash
+build provider setup
+build provider setup --providers claude,codex
+build 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/build/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 `build --help`
+- **Parallel execution** (beta):
+  [../PARALLEL_EXECUTION.md](https://github.com/ebrindley/build/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/build/blob/main/docs/INSTRUCTION_ARCHITECTURE.md)
+
+## Getting Help
+
+- **Troubleshooting**: See [../TROUBLESHOOTING.md](../TROUBLESHOOTING.md) for common issues
+- **Command Help**: Run `build --help` or `build <command> --help`
+- **Issue Tracker**: [Report bugs on GitHub](https://github.com/ebrindley/build/issues)
+- **Documentation**: Browse [../README.md](../README.md) for complete docs index
+
+## Quick Reference Card
+
+```bash
+# Start here: describe the task and let Build build it
+build init --safe-branch fix/<slug>
+build "task"
+
+# Larger work: plan it, then build it
+build plan backlog add "title"
+build plan next
+build --planned "intent"
+
+# Direct single-provider execution (result stays in a worktree or patch until applied)
+build run "task"
+
+# Optional: graded feedback or multi-variant comparison (AI judge default)
+build run competition "task" --variant claude
+# Apply from the same branch; no second branch is needed
+build run competition apply <competition-id>
+git status
+
+# Cost mode (worktree/patch delivery caveats apply)
+build run "task" --optimize cost     # Optimize for cost (single pass on fast models)
+
+# Helpful commands
+build init quickstart     # Target-repo readiness and safe-branch guidance
+build context --json # Compact project context for agents/scripts
+build --help          # Show all commands
+build provider list   # Check environment readiness
+build telemetry cost status     # View current costs
+build quality         # Run quality gates
+```
+
+---

package/docs/getting-started/SETUP.md

@@ -0,0 +1,25 @@
+# Build - Quick Requirements & Setup
+
+Follow [INSTALL.md](../../INSTALL.md) for the shared installation and first-use
+sequence on local machines, agents, CI, and cloud VMs:
+
+1. [Prerequisites](../../INSTALL.md#prerequisites): Node 24 or 26, npm, Git, and the target toolchain.
+2. [Choose a channel](../../INSTALL.md#choose-your-path): `npm install -g @ebrindley/build`
+   for the published release, or `install.sh --source git --version main` for current GitHub source.
+3. [Verify the installation](../../INSTALL.md#verify-the-installation): selected executable, PATH, and installed revision.
+4. [Set up a provider](../../INSTALL.md#set-up-a-provider): interactive or unattended credentials, intended profile, and a live invocation.
+5. [Initialize the target project](../../INSTALL.md#initialize-a-project-and-run-a-task): `build init`, diagnostics, and a first task.
+
+`build doctor` provides diagnostics; `build init quickstart` is an optional
+branch/readiness helper after initialization. Neither replaces provider setup.
+Agents can use `build context --json` for compact project context.
+For an offline preview that does not initialize project state, use the internal
+command `build explain providers`.
+
+Provider-specific installation and authentication details live in
+[PROVIDER_SETUP.md](../PROVIDER_SETUP.md). For example, Grok's shell installer
+requires explicit opt-in:
+`BUILD_ALLOW_CURL_BASH=1 build provider setup --providers grok`.
+The same guide describes interactive browser authentication and headless
+`XAI_API_KEY` use. CLI/model versions follow the maintained defaults unless
+an exact version is needed for reproducibility.

package/docs/reference/AGENT_CONTEXT.md

@@ -0,0 +1,84 @@
+# Agent Context
+
+Audience: Agent/client integrator.
+
+Agents should inspect Build state before choosing a command:
+
+```bash
+build 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 describe what is unavailable or unsafe in this checkout; `no_ready_provider` is
+  raised when no provider is ready and none is installed with auth unverified (that is
+  the normal cold state, since auth is established on first run); a provider with a
+  failed auth check or a broken CLI does not prevent it
+- 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 `build provider
+list`; run `build provider list --json` when an agent needs the full operator
+readiness view.
+
+Use the CLI for execution and operator workflows. Prefer `build context --json`
+and other read-only CLI commands for compact state access; run mutating CLI
+commands only when the user explicitly asks.
+
+The list holds at most five actions. While the instructions import is on offer
+(some agent has global instructions and nobody has imported or declined on this
+machine), the last slot is always its preview, `build config instructions import
+--check`, marked `"audience": "person"`. The preview writes nothing; the import
+itself is the person's decision, so tell them about it rather than running it.
+
+When local execution records show a delivery with an open PR or a pending archive
+sync, the list leads with `build plan backlog finalize --auto` (tier `git_mutation`).
+It is read from local files only; the command itself checks each delivery and
+finalizes only those confirmed merged. The `provider-setup` action is also marked
+`"audience": "person"`.
+
+Side-effect tiers:
+
+- `read_only`: inspection only
+- `local_write`: writes local Build/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
+the managed planning buckets directly (`backlog/`, `sprint/`, `task/` at the repo root by
+default, or under `.build-project/work/` with the git-branch storage backend; see
+`.build-project/config/buckets.yaml`); use Build CLI surfaces.
+
+## Repository purpose
+
+`.build-project/context/purpose.md` holds one sentence (200 characters or fewer) describing
+the repository. It is committed, shared team context. Build uses it the same way on
+every machine, in CI, and under `build init --yes`: it appears as the `PURPOSE:` line
+of the context-injection identity and in the `build-context-purpose` block of
+`AGENTS.md`. `build init --purpose "<text>"` sets or replaces it; interactive init asks
+for one only when none exists. A leftover `.build-project/state/purpose.confirmed.json` from
+earlier versions is ignored.
+
+When no purpose exists, Build drafts a suggestion from the root manifest description
+(`package.json`, `pyproject.toml`, `Cargo.toml`, `composer.json`) or the README's first
+sentence. It never saves the draft on its own: interactive init shows it and saves it
+only when you type `y` (Enter skips), `build context --json` lists it as a
+person-audience `set-purpose` action, and `build doctor` shows it as an info line.
+
+Earlier versions required each machine to confirm the committed purpose before using
+it. That gate is gone. It made every collaborator, machine and moved checkout
+re-confirm, dropped purpose silently in CI and under `--yes`, and protected nothing
+the repository does not already trust: the same sentence reaches builders through the
+committed `AGENTS.md` block, and committed instructions (`AGENTS.md`,
+`stack-intent.json`, the knowledge manifest) are authoritative without confirmation.
+
+| Concern | Control |
+| --- | --- |
+| A clone supplies an injectable sentence | Committed context is reviewed through git diffs like `AGENTS.md` |
+| Injection of Build-managed markers | Sanitizer rejects `<!--` / `-->` and strips `build-` / `BUILD_` prefixes |
+| Oversized or multi-line text | Sanitizer enforces the length bound, collapses whitespace and drops control characters |
+| Destructive actions | Execution permissions and sandboxing, not prompt content ([SECURITY.md](SECURITY.md)) |