Make init non-interactive and move first-run configuration into the supervising session

[atqamz]

Problem

hand init --setup mixes two responsibilities: bootstrapping a fleet home and interactively configuring external agent harnesses. The resulting prompts do not explain valid values and can request settings the selected harness cannot use.

Observed with Codex selected:

$ ./hand init --setup
found harnesses: claude codex opencode
found tools: treehouse herdr no-mistakes gh
select default worker harness:
1) claude
2) codex
3) opencode
2
default worker model: sol
worker effort: auto

sol and auto are guesses typed by the user, not suggested defaults. More importantly, the harness contract says Codex supports neither a model nor an effort launch flag, so both saved values are unusable and can only produce warnings at dispatch.

Harness availability, model identifiers, and effort capabilities can vary independently of a hand release. Initialization should not pretend to own or synchronously enumerate those catalogs. A supervising agent already has a normal conversation channel in which it can explain missing configuration, ask the operator, and act on the answer.

The documentation compounds the confusion:

• README Quick start leads with cloning the development repository and running make build.
• README mentions nix build, but not the already-supported direct nix profile install github:atqamz/secondhand or one-shot Nix execution.
• SPECS.md documents those Nix forms and go install github.com/atqamz/secondhand@latest, but README does not.
• SPECS.md advertises https://secondhand.dev/install.sh, although that installer is not present.
• Initialization completion help says a Claude Code session is ready regardless of what the operator intends to use.

The latest release already contains checksummed Linux amd64/arm64 and macOS amd64/arm64 archives, so an install-first path can use existing artifacts.

Proposed outcome

Make the first-run journey install -> initialize -> start a supervising session -> configure the fleet through conversation -> add a project. Keep source builds in contributor documentation.

Initialization only bootstraps

• hand init [directory] creates or refreshes the fleet-home layout, generated instructions, database, and supported session integration. It asks no questions.
• Do not select a worker harness, model, or effort during initialization, and do not create placeholder values that look configured.
• Prerequisite discovery must not turn initialization into a wizard. Diagnostics can be reported non-interactively or deferred to the first session.
• Retire --setup: remove it if compatibility permits, or keep it temporarily as a deprecated no-op alias with a clear migration message. Do not preserve a second interactive initialization path.
• The bootstrap remains deterministic and usable from scripts and terminals without stdin.

First supervising session configures the fleet

• At every supervising session start, hand reports configuration state in the injected session document.
• If no default worker harness is configured, the generated AGENTS.md instructions tell the supervisor to ask the operator which detected harness to use and persist the answer. This is the first configuration question.
• After the harness is selected, the supervisor asks only for missing defaults that the selected worker harness can carry. Codex, Grok, and Pi need neither model nor effort; OpenCode can need model only; Claude can need both.
• The session hook itself stays non-interactive and never waits on stdin. Questions happen in normal agent/operator conversation after the session opens.
• Persist answers through a hand command that owns validation and atomic writes rather than instructing the agent to edit config files ad hoc.
• Harness identifiers and stable effort vocabularies may be validated by hand. Harness-native model identifiers should remain open strings so hand does not bake in a fast-staling model catalog.
• After each persisted answer, the supervisor rechecks configuration and continues until no required applicable value is missing.
• Once configured, questions disappear from later sessions. If the operator declines to configure a required value, the next session surfaces it again without preventing unrelated read-only fleet inspection.
• A setting unsupported by the selected worker harness is not applicable, not missing.
• Changing the worker harness re-evaluates applicability. Values belonging to another harness must not silently become defaults for the new one; configuration should be keyed by harness or explicitly cleared/migrated.
• Task-level brief and spawn/promote overrides continue to win over fleet defaults.
• Cover empty homes, capability matrices, persistence, repeat sessions, declined configuration, and harness changes with tests.

Documentation

• Rewrite Quick start around installing hand, creating a standalone fleet home with non-interactive hand init, starting a supervising session, completing conversational setup, and adding the first project.
• List release binaries, direct Nix profile/one-shot usage, and go install as actual install options.
• Move clone + build instructions under Contributing/development.
• Remove the nonexistent secondhand.dev/install.sh claim from SPECS.md unless that installer is implemented as part of the change.
• Explain prerequisite tools separately from installing hand. The first session should explain missing prerequisites in context.
• Use harness-neutral completion help and only claim a session integration that was actually installed.

Distribution follow-ups

Do not make this issue depend on every package ecosystem. The current release assets support a small checksummed installer next. A maintained Homebrew tap is a reasonable follow-up because Homebrew officially supports third-party taps and the releases already contain both macOS architectures. Linux distro repositories require separate metadata, ownership, and release automation per ecosystem and should be proposed individually. An npm wrapper is not recommended yet: hand is a native Go CLI with no Node runtime integration, so npm would add another downloader/wrapper and supply-chain surface without improving the binary itself.

Acceptance criteria

• hand init succeeds without reading stdin and asks no configuration questions.
• No worker harness, model, or effort is guessed or written during initialization.
• The first supervising session asks for the worker harness through normal conversation when it is missing.
• After harness selection, only applicable missing settings are requested and persisted through hand.
• Session-start output distinguishes configured, missing-applicable, and unsupported settings.
• Selecting Codex never asks for or writes model/effort values that Codex cannot use.
• Configured questions do not repeat in later sessions, while declined missing values remain visible.
• Switching harnesses cannot silently reuse incompatible defaults.
• --setup is removed or explicitly deprecated as a non-interactive compatibility path.
• A new user can follow README from no checkout to an initialized and configured fleet home.
• Every documented command exists and is exercised or checked in CI where practical.
• Source-build instructions are clearly identified as contributor/development setup.
• README, SPECS.md, hand init --help, generated AGENTS.md, session-start output, and actual behavior agree.