Goal

Make binary installs (curl/Homebrew) the official primary path and the archon setup CLI dead-simple end-to-end. The recommended primary use of Archon is CLI + the archon Claude skill — a coding provider configured, no chat adapter required. Today's setup wizard makes adapter prompts feel mandatory and handles ~40% of what a new user needs; the rest is documented across multiple guides users miss, leading to opaque first-run errors (missing Claude binary, missing gh auth, unsigned Telegram bots open to the world, etc.).

What we're shipping in 0.3.11

Setup wizard scope

The recommended path through this wizard is: AI provider → skip GitHub → skip Slack → skip Telegram → copy skill → run doctor. A user who just wants Archon as CLI + skill should be done in under a minute with no irrelevant prompts.

archon doctor (new top-level command)

End-to-end verification with green/red checklist. Re-runnable for troubleshooting after setup.

Checks:

• Claude binary resolves and spawns
• gh auth status if GitHub adapter configured (skipped otherwise — don't tell users without GitHub they're broken)
• DB reachable
• Workspace dir writable
• Optional adapter token pings (Slack auth.test, Telegram getMe) — best-effort, skip on no network
• Bundled defaults load without errors

Skill embedded in the binary

Same machinery as bundled workflows + commands (packages/workflows/src/defaults/bundled-defaults.generated.ts pattern). Source mode keeps copy-from-disk so contributors editing the skill see live changes; binary mode writes from embedded bytes.

This unblocks binary-only users who today have to clone the Archon repo just to get the skill copied into their target repo.

Docs reframe (lands after the code, documents reality)

Three files:

• README.md — split "For users" (curl/brew/docker) vs "For contributors" (clone + bun run dev).
• getting-started/overview.md — flip Step 1 to binary install; source clone becomes a footnote in a "Contributing" section.
• getting-started/installation.md — already mostly correct (curl is line-1); just re-link from README and add archon doctor reference.

Document archon doctor everywhere setup is referenced. Document the "CLI + skill, no adapter" path as the primary recommended setup.

Out of 0.3.11 scope

• PostgreSQL setup — moved to standalone doc. SQLite is the only documented option for the wizard.
• GitHub App support — separate roadmap issue. Likely partially resolves rfc(auth): rethink per-codebase GitHub PAT injection — env vars are the wrong primitive #1467 (per-codebase PAT primitive), bug(isolation/git): worktree sync fails 403 on org repos — per-codebase GH_TOKEN never reaches git fetch subprocess #1469 (worktree sync 403 on org repos), and Bash nodes don't inherit gh keyring auth — fresh-private-repo first runs fail silently #1476 (bash nodes inherit gh keyring auth).
• NPX-distributed skill — long-term direction (similar to how other Agent skills are distributed publicly), not 0.3.11. Today's embed-in-binary is the right interim.
• Per-platform webhook automation (auto-creating GitHub webhooks via API) — feature, not polish.

Background: gaps in today's archon setup

Audit findings:

1. Doesn't verify Claude Code is installed before saving CLAUDE_BIN_PATH — defers error to first workflow run.
2. Doesn't check gh auth status — workflows shelling out to gh fail with opaque 401s.
3. Telegram bot wide open to internet by default — no allowlist prompt; anyone can DM.
4. No verification step — setup ends with no "did this actually work?" answer.
5. No update path documented — users don't know how to upgrade later.
6. Skill copy depends on running setup from a source clone — binary-only users can't get the skill.
7. GitHub webhook secret generated but URL to paste it into never shown.
8. Adapter prompts feel mandatory — even though Archon works fine as CLI + skill alone.
9. Database step asks Postgres vs SQLite but doesn't run Postgres migrations — Postgres users get table-doesn't-exist errors.
10. Discord/Telegram intent + allowlist guidance missing.

Items 1-8 are addressed in this issue. Items 9-10 are out of scope (Postgres deferred to docs; Discord deferred to community).

Implementation order

1. Embed the skill in the binary — unblocks the skill-copy step for binary users. Build script change + new bundled-defaults entry. (~2h)
2. Setup wizard rewrite — add validation, make every adapter skippable with clear "Archon works without this" messaging, add Telegram allowlist, add doctor invocation, add update-path footer. Remove database prompt and Discord step. (~3h)
3. archon doctor command — new CLI subcommand, shared verification helpers. (~2h)
4. Docs reframe — README + overview + installation. Documents what was actually built. (~1.5h)

Goal: one PR for steps 1-3 (code = source of truth), separate PR for step 4 (docs follow code).

Success criteria

• A new user can: run curl install → run archon setup → run archon doctor → run their first workflow, with no other steps needed.
• The recommended "CLI + skill only" path takes under a minute through the wizard, with no irrelevant adapter prompts forced on the user.
• Telegram users cannot accidentally expose their bot to the public.
• archon doctor is the canonical "is my setup OK?" command, runnable at any time.
• The README and overview no longer lead users to bun run dev as the primary path.

Tracking

• Companion roadmap issue: GitHub App support (to be filed)
• Companion doc: PostgreSQL standalone setup guide (to be filed)