spark: add verified even Fibonacci sum solver

2026-10-30 10:35:49 +00:00
1 parent 8c67a8a540
commit f0fddc5a9c
@@ -1,25 +1,148 @@
 # Troupe Free-Tier Bot Crew — Quickstart

-This guide gets a new Hermes profile running on free-tier providers in under 10 minutes.
+*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 and Python 3.10+
- Git
- A Nous Portal account with free-tier API access

-## 2. Clone the Stackchain Library
-git clone https://github.com/stackchain/library.git
-cd library
+- 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

-## 3. Create a Hermes Profile
-cp -r profiles/example profiles/<yourname>
-export HERMES_PROFILE=<yourname>
+```
+bash --version | head -1; python3 -V; git --version; hermes --version
+```

-## 4. Configure Providers
-Edit profiles/<yourname>/config.yaml:
- Set provider: nous
- Set model: inclusionai/ling-3.1-flash (or other free-tier model)
- Confirm no payment methods are attached
+Reading `[S1]`: bash 5.2.21(1), Python 3.14.9, git 2.43.0, Hermes Agent
+v0.22.5 (2026.9.24).

-## 5. Run Your First Job
-hermes run "echo hello world"
+## 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.
@@ -0,0 +1,159 @@
+# QUICKSTART.md — execution transcript
+
+*Every step id referenced by `QUICKSTART.md`, with the exact command that was run,
+its exit code, and its raw output. Measured 2026-10-30 on the host that runs
+`hermes` v0.22.5, from `/tmp` unless stated. Profile names `q110demo`,
+`q110demo2`, `q110demo3` are throwaway probes: each was deleted afterwards and
+no `q110demo*` profile remains (`ls -d ~/.hermes/profiles/q110demo*` → no such
+file, rc 2).*
+
+Format read by `wizard-work/volt/q110_check.py`: a `### S<n> — title` heading,
+then `cmd:`, `rc:`, `status:` lines. `status` is one of `TESTED` (rc must be 0),
+`EXPECTED-FAIL` (rc must be nonzero), `UNTESTED` (rc is the observed failure).
+
+### S1 — toolchain versions
+cmd: bash --version | head -1; python3 -V; git --version; hermes --version
+rc: 0
+status: TESTED
+out:
+    GNU bash, version 5.2.21(1)-release (x86_64-pc-linux-gnu)
+    Python 3.14.9
+    git version 2.43.0
+    Hermes Agent v0.22.5 (2026.9.24) · stable · local bf0203a794a0
+
+### S2 — clone the pipe (the URL the rewritten doc gives)
+cmd: git clone -q https://forge.alexanderwhitestone.com/git/stackchain/troupe-standup.git lib
+rc: 0
+status: TESTED
+out:
+    real 0m31.490s
+    300851899 bytes on disk (du -sb lib)
+    git -C lib rev-parse HEAD -> 85cc9e69638d415d79ab5a7a9d5d5dcbcc795c94
+    85cc9e6 2026-10-30 06:02:25 +0000 volt: bound the tool_map drift CHECK (...)
+    landing re-check: git ls-remote --heads -> rc 0, main = 85cc9e69638d…,
+    branch-head = 9dd32f4d59bc… (tree reachable unauthenticated)
+
+### S3 — create the profile
+cmd: hermes profile create q110demo3 --clone --no-alias
+rc: 0
+status: TESTED
+out:
+    Profile 'q110demo3' created at /root/.hermes/profiles/q110demo3
+    Cloned config, .env, SOUL.md, and skills from volt.
+    (an earlier run of the same command, timed: real 0m13.351s)
+    landing re-check (no --clone): rc 0, real 0m16.371s, 58 bundled skills;
+    `hermes profile delete -y q110probe` rc 0 and the path is gone
+    (timings vary run to run; the rc does not)
+
+### S4 — set provider, base_url, model
+cmd: hermes -p q110demo3 config set model.provider deepseek; hermes -p q110demo3 config set model.base_url https://api.deepseek.com/v1; hermes -p q110demo3 config set model.default deepseek-flash
+rc: 0
+status: TESTED
+out:
+    ✓ Set model.provider = deepseek in /root/.hermes/profiles/q110demo3/config.yaml
+    ✓ Set model.base_url = https://api.deepseek.com/v1 in /root/.hermes/profiles/q110demo3/config.yaml
+    ✓ Set model.default = deepseek-flash in /root/.hermes/profiles/q110demo3/config.yaml
+
+### S5 — read the model back
+cmd: hermes -p q110demo3 config get model.default
+rc: 0
+status: TESTED
+out:
+    deepseek-flash
+
+### S6 — first job
+cmd: hermes -p q110demo3 chat -q "Reply with exactly: PONG" -Q
+rc: 0
+status: TESTED
+out:
+    PONG
+    session_id: local-e0f1e5f4d155fed44e2c52377b2807bf637956ca9304fadf679eace06ac4e359
+    real 0m9.964s
+    landing re-check on the `volt` profile: PONG, rc 0, real 0m13.845s,
+    session_id local-fc6bfcd10385fa4eb3f397a925fb5ad6906543083f2d362d5e5531abde7f2bbb
+
+### S7 — negative control: an invented model id
+cmd: hermes -p q110demo3 config set model.default deepseek-nonexistent-probe; hermes -p q110demo3 chat -q "Reply with exactly: PONG" -Q
+rc: 1
+status: EXPECTED-FAIL
+out:
+    DeepSeek rejected this request as malformed, so the model didn't answer. ...
+    Provider said: HTTP 400: The supported API model names are deepseek-flash,
+    deepseek-v4-pro, but you passed deepseek-nonexistent-probe.
+    (request_id: 7fc43101-260f-4ae7-8f95-ecb097189797)
+
+### S8 — delete the throwaway profile
+cmd: hermes profile delete -y q110demo3
+rc: 0
+status: TESTED
+out:
+    ✓ Removed /root/.hermes/profiles/q110demo3
+    Profile 'q110demo3' deleted.
+    ls -d /root/.hermes/profiles/q110demo3 -> No such file or directory
+    ls /root/.local/bin/q110demo3 -> No such file or directory
+
+### S9 — the old clone URL is dead
+cmd: curl -sS -o /dev/null -w "%{http_code} %{url_effective}\n" -L https://github.com/stackchain/library.git
+rc: 0
+status: TESTED
+out:
+    404 https://github.com/stackchain/library
+    api.github.com/repos/stackchain/library -> also 404
+    landing re-check 2026-10-30: 404 https://github.com/stackchain/library
+
+### S10 — the old first-job command does not exist
+cmd: hermes run "echo hello world"
+rc: 2
+status: EXPECTED-FAIL
+out:
+    hermes: 'run' is not a `hermes` command.
+    Run `hermes --help` to see all commands.
+    landing re-check: rc 2, same two lines
+
+### S11 — a bare HERMES_HOME directory is not a profile
+cmd: HERMES_HOME=<scratch>/h2 hermes chat -q "Reply with exactly: PONG" -Q
+rc: 1
+status: EXPECTED-FAIL
+out:
+    Hermes couldn't start the model connection: Gateway could not start: the gateway
+    exited with status 0 before it could serve:. Your message was not sent.
+    real 0m10.666s   (repeated 0m11.746s with the parent's session env stripped,
+    and 0m12.812s from /tmp on the live profile home: same reading)
+
+### S12 — HERMES_HOME exported hides a freshly created profile
+cmd: HERMES_HOME=<scratch>/h2 hermes -p q110demo2 chat -q "Reply with exactly: PONG" -Q
+rc: 1
+status: EXPECTED-FAIL
+out:
+    Error: Profile 'q110demo2' does not exist. Create it with: hermes profile create q110demo2
+
+### S13 — the one-shot form Hermes documents
+cmd: hermes --help
+rc: 0
+status: TESTED
+out:
+    usage: hermes [-h] [--version] [-z PROMPT] [--usage-file PATH] [-m MODEL]
+    (the same invocation lists `chat`, and `hermes chat --help` documents
+    `-q/--query` with `--oneshot`)
+    landing re-check: `-z PROMPT` 1 match in `hermes --help`; `--no-alias`
+    2 matches in `hermes profile create --help`
+
+### S14 — the cloned repo has no profiles/ directory
+cmd: ls -d profiles   (cwd = the clone from S2)
+rc: 2
+status: EXPECTED-FAIL
+out:
+    ls: cannot access 'profiles': No such file or directory
+    landing re-check: same reading from /root/troupe-standup (rc 2)
+
+### S15 — a fresh HERMES_HOME blocks in dependency preparation (landing re-measure)
+cmd: HERMES_HOME=/tmp/q110h2 timeout 25 hermes -p q110nope config get model.default; HERMES_HOME=/tmp/q110h2 timeout 100 hermes chat -q "PONG" -Q
+rc: 124
+status: UNTESTED
+out:
+    hermes: preparing dependencies for this data root (the checkout's updates belong to /root/.hermes)...
+      → Installing Python dependencies…
+    (both commands, plus `-p volt config get`, printed that first line and did not
+    finish: 25 s, 25 s, 100 s, each killed by `timeout` → rc 124)
+    Not a pass and not a refusal: the lookup message S11/S12 record was never
+    reached at landing, so this step is recorded as unreachable, not as measured.