Verify first-run onboarding from a clean environment: install, configure, doctor and a first run (LAUNCH-A)

Start with AGENTS.md, docs/usage.md, docs/configuration.md, tests/AGENTS.md and the security-boundaries page from #257. Review README.md, docs/README.md, doctor.py, config.py, the existing CI install job from #256, and tests before defining the guide and smoke procedure. Done means the guide, tested starter configurations, clean-room steps and automated install smoke meet the listed acceptance criteria; a maintainer must perform the credentialed real run and post its friction log.

Artifact: implementation-ready issue (LAUNCH-A of the Public Alpha EPIC #255). This issue body is the authoritative copy; the working copy was drafted in the maintainer's local session scratchpad and is not kept elsewhere. Baseline: main at 711ff09, read on 2026-10-21 (UTC). Planning created this issue only: no code, branch or PR.

Parent: #255 · Priority: P0 · Gates: 1 (Fresh installation), 2 (First successful run) · Blocked by: #256, #257 [native] · Blocks: #261, #262 [native]

Summary

A developer who has never seen AutoForge can install it, configure it, diagnose their environment and run a first workflow on a repository of their own, using only the public documentation. This issue writes that path, fixes the first-run obstacles it finds, and proves it with a clean-room procedure.

Verified current state (711ff09)

• Install only works inside the AutoForge clone. README "Installation" is uv sync (editable) and uv run autoforge --help (README.md:207-213); the Quick start says to run uv run autoforge … "from a checkout of the repository the issues belong to" (README.md:219-240). No document explains how to run AutoForge against another repository; no doc mentions uv tool, pipx or --project. (#256 fixes packaging and chooses the install channel.)
• doctor fails on a fresh repository. Its "default branch requires checks" row (doctor.py:141) fails unless an active ruleset or classic branch protection requires a status check on the default branch, naming those in safety.required_checks (default ["ci"], the aggregate check of AutoForge's own CI); an empty list does not make the row pass. The same key feeds the merge gate's required-check and check-definition verification (safety.verify_check_definition). doctor is Quick start step 1.
• Defaults need two vendors. analyze_execute/fix run Claude Code with model fable; every review round, replan_reexecute and update_epic run OpenCode with openai/gpt-5.6-* (config.py:868-904). There is no starter configuration and no init for REMOTE mode (local init creates a LOCAL feature file only). autoforge.yaml is gitignored; autoforge.example.yaml is long and has stale lines (:111-112, :228).
• run requires --epic and --issue (autoforge run --help), and no document says what the EPIC or the issue must contain, or that both must be in the checkout's own repository (cross-repository runs are refused).
• What exists: doctor (with remedies for many rows), run --dry-run ("no subprocess, no gh call, no state file"), status, resume, a detailed docs/usage.md and docs/configuration.md, and LOCAL mode (docs/local-mode.md) which needs no GitHub at all.

Scope

1. A getting-started guide (for example docs/getting-started.md), written for a stranger, in order:
   1. prerequisites by name and minimum version, linking #256's compatibility matrix (OS, Python, uv or the chosen installer, git, gh and its authentication with the scopes from #257, Claude Code and OpenCode logins or keys, and who pays for model calls);
   2. installing AutoForge with the channel #256 chose, so that autoforge runs from any directory;
   3. preparing a throwaway repository you control (not a public repository where strangers can comment on the issue or PR the agent reads; see #257's security page): what the EPIC and the issue are for, what they should contain, a copy-paste example of each, the branch-protection / required-check expectation, and the .gitignore or .git/info/exclude entries for .autoforge/ and autoforge.yaml so runtime state, logs and a local configuration are never committed;
   4. a minimal working configuration (item 2);
   5. autoforge doctor, with what each failing row means for a first run, and how to record the CLI versions it reports (Gates 1–3 record them);
   6. run --dry-run, then a real run, then status, then what READY_FOR_MERGE and BLOCKED look like and what to do next (a human merges);
   7. the commonest first-run failures with their exact messages and fixes (item 4).
2. Starter configuration(s) under an examples/ directory (or equivalent), each commented and loaded by a test so it cannot rot: (a) the default two-provider routing made explicit; (b) evaluate and, if it works, add a single-provider starter (for example Claude Code for every phase), stating plainly that its review is then not cross-vendor. Do not change default_config().
3. The first-run doctor experience. Decide, with the maintainer, how a fresh repository passes or knowingly skips the "default branch requires checks" row (for example: the guide shows how to add a ruleset requiring a check; or the starter configuration sets safety.required_checks to the check the user's own CI produces; or the row explains that it matters only to the merge gate). Whatever is chosen must not weaken the merge gate: READY_FOR_MERGE and MERGE keep their checks.
4. Common failure messages. This issue owns setup and first-run diagnostics: everything up to a run that exists (install, configuration, doctor, credentials, the first run --dry-run and the start of the first run). Everything once a run exists (a state directory, a phase, a stop) is #260's; link it rather than repeating it. Collect the messages a first run actually hits (missing CLI, unauthenticated gh or agent CLI, unknown model, missing required check, cross-repository URL, dirty checkout, lock held, permission request per #258 if merged) and make sure each is in the guide with its fix. If a message is itself misleading, fix it in this issue when the change is small; otherwise file it as a sub-issue of #255.
5. The clean-room procedure (docs/ page or a section of the guide), reusable by Gates 1 and 2 at the release candidate: the environment to start from (fresh VM, container or user account; no prior AutoForge, uv cache, config or state), the exact steps, what to capture (redacted), and the friction log format.
6. An automated install smoke that runs the install-and-diagnose half of the procedure in a clean container or fresh virtual environment, offline and without credentials: install by the documented method, autoforge --version, autoforge doctor (asserting the rows that need no credential), run --dry-run on a fixture. Extend the install job #256 adds to CI rather than adding a second one; if it does not fit the ci aggregate's constraints, provide it as a make target documented in docs/development.md.
7. If the EPIC decides to promote LOCAL mode as a first-run path (condition C7), the guide includes it and the clean-room run covers it.

Acceptance criteria

• The getting-started guide exists and is linked from README.md and docs/README.md. Every offline command in it (install, --version, --help, doctor rows that need no credential, run --dry-run on a fixture) was executed on the branch by the implementer, transcript in the PR, redacted; every credentialed command (authenticated doctor, a real run) was executed by the maintainer, with the result recorded on this issue.
• Every starter configuration is loaded and validated by a test.
• On a fresh repository that follows the guide, doctor either passes or reports only rows the guide explicitly tells the user to expect, with no change to the merge gate's checks.
• The clean-room procedure is documented, and one clean-room run following only the published docs on the PR head has been performed, through install, doctor, run --dry-run and a first real run on a throwaway repository to READY_FOR_MERGE (or BLOCKED with the guide explaining why), with the OS, Python and CLI versions recorded. Its friction log is posted on this issue; every friction point is fixed or documented.
• The automated install smoke passes.
• make check passes.

Out of scope

• Packaging and the install channel itself (#256); the README redesign (#262); the full troubleshooting guide (#260); the public demo (#261).
• Changing provider defaults, adding an interactive init wizard, or Windows support.

Executor and maintainer actions

Agent-implementable: the guide, starter configurations, the procedure, the automated smoke, small message fixes. Maintainer action: the first real run of the clean-room procedure needs real agent logins and model spend; the maintainer (or a volunteer) performs it and posts the friction log. Gate 2 at the release candidate additionally requires someone other than the maintainer.

Notes for the implementer

Read AGENTS.md, docs/usage.md, docs/configuration.md, tests/AGENTS.md and #257's security-boundaries page first. Tests never call a real agent or GitHub; the clean-room real run is the maintainer's. Do not commit autoforge.yaml (it is gitignored and maintainer-local).