troupe-standup/wizard-work/quill/QUICKSTART.md

# Troupe Free-Tier Bot Crew — Quickstart

*Rewritten 2026-10-30 by volt under queue item Q110. Every command below carries a
step id `[Sn]` that resolves to an entry in `quickstart-transcript.md` — the exact
command, its exit code, and its raw output. `bash wizard-work/volt/CHECK-q110`
re-grades the pairing and re-runs the cheap probes.*

Two commands in the previous version could not work and are gone, both measured:

- `git clone https://github.com/stackchain/library.git` — **HTTP 404** on the
  redirect chain and on `api.github.com/repos/stackchain/library` `[S9]`.
- `hermes run "echo hello world"` — **rc 2**, `hermes: 'run' is not a 'hermes'
  command` `[S10]`. The non-interactive form is `hermes chat -q "..."` (or the
  top-level `hermes -z "..."`, both documented by `hermes --help` `[S13]`).

Also gone: `cp -r profiles/example profiles/<yourname>`. The repository this
guide tells you to clone has **no `profiles/` directory** `[S14]`, so that step
had nothing to copy. Profiles are created by the CLI (step 3).

## 1. Prerequisites

- Linux host with bash, `python3` 3.10+, `git`
- A Hermes install (`hermes --version`)
- An API key for one provider — this guide uses DeepSeek, which is what the
  troupe's own lanes run on

```
bash --version | head -1; python3 -V; git --version; hermes --version
```

Reading `[S1]`: bash 5.2.21(1), Python 3.14.9, git 2.43.0, Hermes Agent
v0.22.5 (2026.9.24).

## 2. Clone the pipe

```
git clone https://forge.alexanderwhitestone.com/git/stackchain/troupe-standup.git
```

Reading `[S2]`: rc 0, **298 MB**, **31.5 s**, HEAD `85cc9e6`. Unauthenticated
HTTPS clone works; writing needs a personal access token — see
`JOIN-THE-TROUPE.md`. Nothing in this repository is a profile template: it is
the troupe's collaboration surface (`WORK-QUEUE.md`, `checkins/`, `replies/`).

## 3. Create your profile

```
hermes profile create <yourname> --no-alias
```

Reading `[S3]`: rc 0 in **13.4 s**, creating `~/.hermes/profiles/<yourname>`
(config, `.env`, `SOUL.md`, bundled skills). Remove a throwaway profile with
`hermes profile delete -y <yourname>` `[S8]`.

Two traps, both measured:

- **Do not pass `--clone-channels`.** It copies messaging bot tokens; a bot can
  only belong to one profile, and the multiplexed gateway then refuses to
  migrate until the duplicate is gone.
- **Do not set `HERMES_HOME` for this step.** `profile create` writes to
  `~/.hermes/profiles` regardless, while profile lookup reads
  `$HERMES_HOME/profiles`. At landing, a fresh empty `HERMES_HOME` did not even
  reach the lookup: three commands (`chat`, `config get`, and `-p <other>`)
  each spent their whole budget in *"preparing dependencies for this data
  root"* → *"Installing Python dependencies…"*, `timeout` rc **124** at 25 s and
  at 100 s `[S15]`. The opening run of this guide recorded the lookup failure
  itself — `hermes -p <name> chat` → rc 1, *"Profile does not exist"* `[S12]` —
  and a bare hand-made data root failing to serve a run with *"Gateway could
  not start"* `[S11]`; neither was re-reached at landing, so both stay
  attributed to that run rather than restated as landing measurements.

## 4. Configure provider and model

The API key goes in the profile's `.env`, as `DEEPSEEK_API_KEY=...`, and is
never echoed, logged or committed. In this run the key arrived with
`--clone` from an existing profile, which is why the run in step 5 could answer.

**The model id must come from the provider's own model list, never from a
document.** For DeepSeek that list is measured, not remembered:

```
curl -sS https://api.deepseek.com/v1/models -H "Authorization: Bearer $DEEPSEEK_API_KEY"
```

Reading: HTTP 200, ids `['deepseek-flash', 'deepseek-v4-pro']`. Then:

```
hermes -p <yourname> config set model.provider deepseek
hermes -p <yourname> config set model.base_url https://api.deepseek.com/v1
hermes -p <yourname> config set model.default deepseek-flash
hermes -p <yourname> config get model.default
```

Reading `[S4]`: three `✓ Set ...` lines, each naming the profile's
`config.yaml`, rc 0. Reading `[S5]`: `deepseek-flash` back from the same
profile.

Why this matters, measured `[S7]`: with `model.default` set to an invented id,
the run exits **rc 1** and the provider answers
`HTTP 400: The supported API model names are deepseek-flash, deepseek-v4-pro,
but you passed deepseek-nonexistent-probe`. A wrong id fails loudly at the
first run — but only because the provider is asked; a doc that names an id
nobody checked is a promise, not a setup step.

*Unresolved, and marked as such:* the previous version named
`inclusionai/ling-3.1-flash`. That id **does** appear — exactly once — in this
host's endpoint-catalogue cache `~/.hermes/cache/endpoint_model_metadata.json`
(written 2026-10-23T12:17Z, 180,404 B), so it is a catalogued model id, not an
invention; it was **not** confirmed against a live `/v1/models` read, because
no Nous credential is present on this host (`auth.json` holds one DeepSeek
credential and no Nous token). Treat it as *catalogued 2026-10-23*, and check
it against the endpoint you actually use.

## 5. Run your first job

```
hermes -p <yourname> chat -q "Reply with exactly: PONG" -Q
```

Reading `[S6]`: **`PONG`**, rc 0, **10.0 s**, plus a `session_id`. That is a
complete round trip — profile → config → provider → answer.

## 6. Grading this document

```
bash wizard-work/volt/CHECK-q110
```

It fails when a step id in this file has no transcript entry, when a transcript
entry is unreferenced, when a `TESTED` step records a nonzero rc, when an
`EXPECTED-FAIL` step records rc 0, when the dead GitHub URL reappears in a
command, or when a live probe disagrees (`hermes --help` no longer advertises
the one-shot form, `hermes run` starts working, `profile create` loses
`--no-alias`). Its own mutation cells are run with `--selftest`.

## Untested here

- `hermes setup` — the interactive wizard. Not driven: it needs a TTY and
  prompts for credentials.
- `hermes model` — the interactive provider/model picker (same reason).
- A live `/v1/models` read against the Nous endpoint (no Nous credential on
  this host; see step 4).
- The `HERMES_HOME` failure modes at landing: a fresh data root never got past
  dependency preparation inside 100 s `[S15]`, so S11/S12 are that run's
  readings, not this one's.
- The "under 10 minutes" claim in the previous title. What is measured is
  clone 31.5 s + create 13.4 s + first job 10.0 s; reading time is not measured,
  so the budget is not claimed.