A first run's questions are one state machine in the harness, asked over the protocol, so both clients ask the same things and a run done in one is done in the other¶
Decision 705 · accepted · 2026-09-27 · issue #76
Superseded in part
In part by 817.
Issue #76's second slice: a person with a fresh machine and one API
key reaches a first working session in the desktop app without opening the docs,
and the terminal client does not ask again. Troupe.Setup is the flow — where
(this machine or a plane), provider (Anthropic, OpenAI, a gateway or a LiteLLM
proxy by URL; or opencode's providers and a config.yaml that works, detected and
offered), key (pasted, or kept as {env:VAR}), models, workspace with the
approval model in two sentences, finish — and Troupe.Gateway.Setup holds one
in progress behind setup.get and setup.answer, the daemon's only, like
config.*. The choices that could have gone another way:
- The key is checked with a real request before anything is written: the provider's
model listing, which every provider authenticates and which also fills the models step.
A refused key keeps the step; a provider that answers but will not list (a gateway with
no listing) is unknown and the person goes on and types a model id, since a working
gateway is not a wrong key. Everything is written as late as the answer is complete —
the settings at models, auto_approve at workspace — through
Troupe.Config.ModelSettings and Troupe.Config.write_key/3, into the user's
config.yaml and never a repository's .troupe/.
- No keychain. The daemon has no keychain module — the plane's refresh tokens
are the plane's — so the key goes into config.yaml, readable by the user alone
on Unix, and the flow says so (key_storage) rather than pretending. A keychain
is a later slice.
- Completion is a record in the state directory (<state>/setup.json, beside
identity.json), not a config key: the settings file is what was set up, and
the record is that somebody finished, including a person who chose a plane and
wrote no settings. needed is the absence of all three (the record, a
config.yaml, a model that can be asked), which is what the desktop app asks
before showing the questions and the terminal client asks before its own
(setup.get; a daemon without the method still gets the old questions).
- finish starts the first session on the daemon, as session.create would
under the caller, with a prompt suited to the directory — a repository is asked
to explain itself — so the flow ends on a session and not on a settings screen.
- troupe doctor is Troupe.Doctor in the harness, printed by both programs:
config, provider, key (the same live check), key storage, daemon, both binaries
on the PATH, and every plane the caller knows of, one line each, FAIL making
the exit status 1. It is not a session command, so it is not in
Troupe.Commands.
Governs: apps/troupe_core/lib/troupe/setup.ex, apps/troupe_gateway/lib/troupe/gateway/setup.ex