Skip to content

Commit bf7816c

Browse files
itsminclaude
andcommitted
Refresh the kit for Oct 2026: dead tags, watchlist, install docs, Level 5 timeout
- Fix tags that no longer exist upstream: qwen3-coder-next:80b (never existed, now :q4_K_M), glm-5:cloud and kimi-k2.5:cloud (retired, now glm-5.3:cloud and kimi-k3:cloud) across all nine templates. - Add newer models (Qwen 3.5/3.6, Devstral Small 2) as watching rows. Verified picks are unchanged until a model passes the tool-calling test. - test.sh Level 5: portable timeout around opencode run, which can hang before it starts (anomalyco/opencode#38723). - etude: offer opencode updates only within the installed major version. - Rewrite install-macos.md around install.sh and the variant step; rewrite install-windows.md (marked unverified, variant step, correct template name, LAN no-auth warning). Refresh models.md, hardware-tiers.md, usage.md, README. - Installer closing message: open a new terminal, start with etude. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 8043a60 commit bf7816c

21 files changed

Lines changed: 353 additions & 260 deletions

‎CLAUDE.md‎

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Project: **etude** — an install kit and docs for running a Claude Code-like coding agent on open-weight models. Three tiers: local, LAN peer, Ollama Cloud.
44

5-
**Status**: Harness verified end-to-end on the M3 Air (install + Level 5 smoke + agentic tool calling). Repo **public** on GitHub. `status.sh` audit tool shipped. **`etude` front-door command shipped (Session #06)** — health + drift check + glass-box opencode/ollama/etude updates, then hands off to opencode; its live TUI handoff is not yet interactively verified. opencode upgraded 1.4.7 → 1.15.13. Mac-air-24gb is the only fully-verified tier. Next up — close out `etude` end-to-end (verify the live TUI handoff interactively, add a `test.sh` Level 5 timeout, investigate the opencode 1.15 headless-`run` hang), then the RTX 5080 PC / Windows install (gpu-16gb). Other tiers use the same variant pattern but remain untested.
5+
**Status**: Harness verified end-to-end on the M3 Air (install + Level 5 smoke + agentic tool calling). Repo **public** on GitHub. `status.sh` audit tool shipped. **`etude` front-door command shipped (Session #06)**; its live TUI handoff is not yet interactively verified. **Session #07 (2026-10-13) refreshed the public kit**: dead tags fixed, a watchlist of newer models added (Qwen 3.5/3.6, Devstral Small 2), install guides rewritten to match the harness, `test.sh` Level 5 timeout added, opencode-major guard in `etude`. Versions current at refresh: Ollama 0.40.3, opencode 1.19.0. The author's Mac currently has **no local models pulled** (disk space), so nothing was re-run end to end on 0.40. Mac-air-24gb is the only fully-verified tier (April 2026). Next up: verify the live TUI handoff, then promote watchlist models by testing them on real hardware.
66

77
---
88

@@ -75,32 +75,35 @@ Added in session #04:
7575

7676
Still unverified:
7777
- **`etude` live TUI handoff (Session #06).** `etude`'s health checks + `--dry-run` are verified on the M3 Air; the actual `exec opencode` into the interactive TUI has NOT been watched. Run `etude` interactively and confirm it drops into a working session.
78-
- **opencode 1.15.13 headless `opencode run` (Session #06).** Intermittent: passed twice in agent `test.sh` runs, hung 12.5h once. `test.sh` Level 5 has no timeout (macOS lacks `timeout`), so a hang blocks indefinitely. Investigate root cause (config-schema migration from 1.4? stdin/TTY wait? model-load contention?) and add a portable timeout to Level 5.
78+
- **~~opencode headless `opencode run` hang~~ — explained in Session #07.** It's upstream: anomalyco/opencode#38723 reports `opencode run` intermittently hanging before it creates a session (44% success over a day, reproduced on 1.17 and 1.18, no fix as of 2026-10-13). `test.sh` Level 5 now runs it in the background with a portable deadline (default 300s, `ETUDE_L5_TIMEOUT`), stdin closed, and a plain-language failure. Verified against stub `opencode` programs (hang, success, nonzero exit, wrong answer); not yet run against a real model on Ollama 0.40.
79+
- **Session #07 refresh, unexercised parts.** Everything below was checked by dry run, tag lookup on ollama.com, or stub tests only: the install path on Ollama 0.40.3 / opencode 1.19.0; the rewritten `docs/install-macos.md` (describes the harness, so lower risk); the rewritten `docs/install-windows.md` (PowerShell Modelfile variant recipe and config path are unverified); the `glm-5.3:cloud` / `kimi-k3:cloud` template entries (tags exist; cloud path never tested).
7980
- **Fresh `brew install --cask ollama` branch of Phase 4.** Session #03 couldn't exercise it — Ollama.app was already on the M3 Air (downloaded directly, not via cask). First machine without Ollama.app is the target. *(De-prioritized — the M1 Air session was dropped; see Parking lot.)*
8081
- **Daemon auto-start after a fresh cask install.** Currently `open -a Ollama` with `sleep 2` retry, untested against a cold machine.
81-
- **All tiers other than mac-air-24gb.** `mac-light`, `mac-pro-32gb`, `mac-heavy-64gb`, `mac-max`, and every `gpu-*` tier are registry entries + config templates + (now) variant recipes without a real run. The variant pattern is model-agnostic, so the risk is memory/fit (e.g. `qwen3-coder-next:80b-128k` on mac-max), not tool-calling reliability.
82+
- **All tiers other than mac-air-24gb.** `mac-light`, `mac-pro-32gb`, `mac-heavy-64gb`, `mac-max`, and every `gpu-*` tier are registry entries + config templates + (now) variant recipes without a real run. The variant pattern is model-agnostic, so the risk is memory/fit (e.g. `qwen3-coder-next:q4_K_M-128k` on mac-max), not tool-calling reliability.
8283
- **`install-windows.md`** — entire Windows path, entirely unverified.
8384
- **LAN-serve flow** (Air → desktop Ollama, or vice versa). LAN templates now reference variant tags too; the peer machine would need to have run `install.sh` (or manually `ollama create` the variant) for cross-machine calls to resolve.
8485
- **Ollama Cloud auth / `:cloud` model pull** — see open threads.
85-
- **`install-macos.md` prose** — deferred from session #03, needs a full rewrite to match the harness (currently documents the old brew-formula path and has no mention of the variant tag pattern).
86+
- **`install-macos.md` prose** — rewritten in #07 to match the harness. The manual path in it hasn't been walked on a fresh Mac.
8687

8788
---
8889

8990
## Work queue
9091

9192
### P1 (active)
9293

93-
**Close out `etude` end-to-end (Session #06 follow-ups).** We shipped the front door with an unverified launch path and a real hang finding — verify what we shipped before building more. Doable on the M3 Air. Three parts: (a) run `etude` interactively and confirm the `exec opencode` handoff drops into a working TUI session; (b) add a portable timeout to `test.sh` Level 5 so a hung `opencode run` fails fast instead of blocking (macOS has no `timeout` — use a bash background+sleep+kill pattern); (c) investigate the opencode 1.15 headless-`run` intermittent hang (config-schema migration from 1.4? stdin/TTY wait? model-load contention?).
94+
**Verify the `etude` live TUI handoff.** Run `etude` interactively and confirm the `exec opencode` handoff drops into a working session. Needs a model pulled (`qwen3:8b` is 5.2GB). *Parts (b) Level 5 timeout and (c) the hang investigation were closed in Session #07: the hang is upstream (anomalyco/opencode#38723).*
95+
96+
**Promote watchlist models.** `tiers.tsv` now carries `watching` rows for `qwen3.5:4b`, `qwen3.5:9b`, `qwen3.6:27b-coding`, `qwen3.6:35b-a3b-coding`, `devstral-small-2:24b`. Each needs the README→SUMMARY tool-calling test through opencode on real hardware before flipping to `good` and taking over a daily slot. `qwen3.5:9b` is the obvious first candidate (Ollama's own opencode example; would replace `qwen3:8b` across small tiers).
9497

9598
### P2 (next up)
9699

97-
- **Bucket A — capture the research in `docs/models.md`.** Add the Ollama VRAM-tiering citation (the num_ctx default is now codified: `<24GiB → 4k`, all etude tiers in that bucket; Ollama recommends ≥64k for agents) and a short "how we vet model picks" note pointing at BFCL V4 (state-based agentic eval). Quick, machine-independent, banks the research before it goes stale. Bump `Last reviewed`.
100+
- **Bucket A — partially done in #07.** The Ollama VRAM-tiering citation and the ≥64k recommendation are in `docs/models.md` and `docs/hardware-tiers.md`. Still open: a "how we vet model picks" note pointing at BFCL V4 (re-verify before citing).
98101
- **RTX 5080 PC / Windows install** (gpu-16gb tier). Hardware-gated — needs the PC. Exercises the `gpu-16gb` templates (`qwen3-coder:30b-32k` daily, `qwen3:8b-32k` speed), the unverified `install-windows.md` prose, and the `etude` launcher on a non-Mac surface (the macOS-specific bits — `open -a Ollama`, `brew --cask` — need Windows branches). **Fold in Bucket B:** evaluate Devstral Small 2 24B (`devstral-small-2:24b`, 15GB Q4, purpose-built for agentic coding) head-to-head against the current picks via the README→SUMMARY tool-calling test.
99-
- **Rewrite `docs/install-macos.md`** — 133 lines of outdated brew-formula speculation, no variant-tag mention. Best after a second tier is verified.
102+
- ~~**Rewrite `docs/install-macos.md`**~~ — done in #07, rewritten around `install.sh` with the variant step in the manual path.
100103
- **Build `install.sh --refresh` mode** — detect sidecar, diff vs current TSV, rebuild variants at the current `context` column, rewrite config. (When this lands, `etude` should call it directly instead of printing "re-run ./install.sh" after an etude-self update that changed tiers.tsv.)
101104
- Flesh out `docs/usage.md` further — *partially done in #06 (added the `etude` section + `Last reviewed` bump);* still want day-to-day patterns, mode switching, real examples, and the `-<N>k` suffix explainer.
102105
- Capture LAN-serve latency numbers (Air → desktop). LAN peers need install.sh or a manual `ollama create` for variant tags to resolve.
103-
- Rewrite `install-windows.md` alongside the PC session.
106+
- Verify `install-windows.md` on the PC (rewritten in #07 but never run).
104107
- Watch the Gemma 4 E4B tool-calling bug; flip `reliability` `watching → good` in `tiers.tsv` once fixed upstream, then verify it survives the variant pattern.
105108

106109
### Upcoming sessions
@@ -138,6 +141,15 @@ Conditional: if next session is on the PC, #3 jumps ahead of #1/#2 (it's the har
138141

139142
### Complete (recent)
140143

144+
### Session #07 — Public kit refresh (2026-10-13)
145+
- **Research** (primary sources): Ollama latest 0.40.3, default context still 4k under 24GiB, Ollama's opencode guide uses the same `@ai-sdk/openai-compatible` → `/v1` path etude does. opencode latest 1.19.0 (auto-update removed; OpenCode 2 behind `--major`). Every tag checked against ollama.com tag pages.
146+
- **Fixed dead references:** `qwen3-coder-next:80b` (never existed → `:q4_K_M`, 52GB), `glm-5:cloud` and `kimi-k2.5:cloud` (retired → `glm-5.3:cloud`, `kimi-k3:cloud`) across all 9 templates; drifted sizes.
147+
- **Watchlist:** newer models added as `watching` rows (shown by detect-tier, never offered by install). Verified picks unchanged; nothing could be re-tested (author's Mac has no models, disk space).
148+
- **`test.sh` Level 5 timeout** (portable background+deadline, `ETUDE_L5_TIMEOUT`), verified with stub opencode. The 12.5h hang is upstream (anomalyco/opencode#38723).
149+
- **`etude`** offers opencode updates only within the installed major (guards against OpenCode 2 nagging); 5 new tests pass. **Installer** closing message now says to open a new terminal and start with `etude`.
150+
- **Docs:** `install-macos.md` and `install-windows.md` rewritten (Windows marked unverified, variant step added, wrong template filename fixed, LAN no-auth warning); `models.md`, `hardware-tiers.md`, `usage.md`, README refreshed.
151+
- **Known:** `test-etude.sh`'s dry-run integration check fails on this Mac only because no model is installed.
152+
141153
### Session #06 — Stack re-eval + `etude` front door (2026-06-03/04)
142154
- **Stack re-evaluated** (deep-research pass): keep Ollama + opencode + Qwen3-Coder-30B; the num_ctx variant pattern is *vindicated* by Ollama's own VRAM-tiering docs (all etude tiers fall in the 4k bucket; Ollama recommends ≥64k for agents). Devstral Small 2 24B is the one new candidate to evaluate; BFCL V4 noted as a vetting method. opencode under heavy active maintenance (v1.15.x) — no harness switch.
143155
- **`etude` front-door command shipped** — brainstorm → spec → 13-task TDD plan → built subagent-driven w/ layered review → merged to main + pushed (17 commits). Health check + throttled offline-safe drift check (opencode/ollama/etude) + glass-box updates + `exec opencode` handoff. Sourceable; on PATH via install.sh symlink; test.sh Level 6 + `test-etude.sh`. Spec/plan in `docs/superpowers/`.

‎README.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -126,6 +126,8 @@ Add `--check-updates` to also verify your base tags still exist in the ollama re
126126

127127
Six levels: binaries → daemon → models → inference → full stack → etude front door. If it passed during install and fails now, something changed on your machine.
128128

129+
Level 5 gives opencode 5 minutes to answer, then stops it. opencode's headless mode sometimes hangs before it starts ([opencode issue 38723](https://github.com/anomalyco/opencode/issues/38723)), so a Level 5 timeout usually means "run it again," not "your install is broken." On a slow machine loading a big model, allow more time with `ETUDE_L5_TIMEOUT=600 ./scripts/test.sh`.
130+
129131
### What to expect
130132

131133
These models are good, not great. They handle:
@@ -165,11 +167,13 @@ You don't switch providers to switch tiers. Same provider block, different model
165167

166168
## Current picks
167169

168-
See [docs/models.md](docs/models.md). The file is timestamped. When it's more than a few weeks stale, something in it is probably wrong — update it.
170+
See [docs/models.md](docs/models.md). It lists the verified picks the installer offers, plus a watchlist of newer models (Qwen 3.5 and 3.6, Devstral Small 2) that haven't been through etude's tool-calling test yet. The file is timestamped. When it's more than a few weeks stale, something in it is probably wrong — update it.
169171

170172
## Status
171173

172-
The install script, tier registry, smoke test, the `etude` front-door command, and agentic tool calling all work end-to-end on verified hardware. One Mac tier is fully verified — other tiers have config templates and registry entries but haven't been tested on real machines yet. `etude`'s live launch handoff and the Windows and LAN-serve paths are documented but not yet interactively verified.
174+
*Last refreshed: 2026-10-13. Versions current then: Ollama 0.40, opencode 1.19.*
175+
176+
The install script, tier registry, smoke test, the `etude` front-door command, and agentic tool calling all work end-to-end on verified hardware. One Mac tier is fully verified (M3 Air 24GB, April 2026) — other tiers have config templates and registry entries but haven't been tested on real machines yet. `etude`'s live launch handoff and the Windows and LAN-serve paths are documented but not yet interactively verified.
173177

174178
If you hit a bug, it's probably a real bug. File an issue.
175179

‎config/opencode/gpu-16gb.json‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,13 +18,13 @@
1818
"tools": true,
1919
"limit": { "context": 32768, "output": 8192 }
2020
},
21-
"glm-5:cloud": {
22-
"name": "GLM-5 (Ollama Cloud)",
21+
"glm-5.3:cloud": {
22+
"name": "GLM-5.3 (Ollama Cloud)",
2323
"tools": true,
2424
"limit": { "context": 131072, "output": 8192 }
2525
},
26-
"kimi-k2.5:cloud": {
27-
"name": "Kimi K2.5 (Ollama Cloud)",
26+
"kimi-k3:cloud": {
27+
"name": "Kimi K3 (Ollama Cloud)",
2828
"tools": true,
2929
"limit": { "context": 131072, "output": 8192 }
3030
}

‎config/opencode/gpu-24gb.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@
1313
"tools": true,
1414
"limit": { "context": 65536, "output": 8192 }
1515
},
16-
"glm-5:cloud": {
17-
"name": "GLM-5 (Ollama Cloud)",
16+
"glm-5.3:cloud": {
17+
"name": "GLM-5.3 (Ollama Cloud)",
1818
"tools": true,
1919
"limit": { "context": 131072, "output": 8192 }
2020
}

‎config/opencode/gpu-heavy.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@
1313
"tools": true,
1414
"limit": { "context": 65536, "output": 8192 }
1515
},
16-
"glm-5:cloud": {
17-
"name": "GLM-5 (Ollama Cloud)",
16+
"glm-5.3:cloud": {
17+
"name": "GLM-5.3 (Ollama Cloud)",
1818
"tools": true,
1919
"limit": { "context": 131072, "output": 8192 }
2020
}

‎config/opencode/gpu-light.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,8 @@
1313
"tools": true,
1414
"limit": { "context": 32768, "output": 8192 }
1515
},
16-
"glm-5:cloud": {
17-
"name": "GLM-5 (Ollama Cloud)",
16+
"glm-5.3:cloud": {
17+
"name": "GLM-5.3 (Ollama Cloud)",
1818
"tools": true,
1919
"limit": { "context": 131072, "output": 8192 }
2020
}

‎config/opencode/mac-air-24gb.json‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,13 +18,13 @@
1818
"tools": true,
1919
"limit": { "context": 32768, "output": 8192 }
2020
},
21-
"glm-5:cloud": {
22-
"name": "GLM-5 (Ollama Cloud)",
21+
"glm-5.3:cloud": {
22+
"name": "GLM-5.3 (Ollama Cloud)",
2323
"tools": true,
2424
"limit": { "context": 131072, "output": 8192 }
2525
},
26-
"kimi-k2.5:cloud": {
27-
"name": "Kimi K2.5 (Ollama Cloud)",
26+
"kimi-k3:cloud": {
27+
"name": "Kimi K3 (Ollama Cloud)",
2828
"tools": true,
2929
"limit": { "context": 131072, "output": 8192 }
3030
}

‎config/opencode/mac-heavy-64gb.json‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -13,13 +13,13 @@
1313
"tools": true,
1414
"limit": { "context": 65536, "output": 8192 }
1515
},
16-
"qwen3-coder-next:80b-64k": {
17-
"name": "Qwen3-Coder-Next 80B MoE (heavy — unverified)",
16+
"qwen3-coder-next:q4_K_M-64k": {
17+
"name": "Qwen3-Coder-Next (heavy — unverified)",
1818
"tools": true,
1919
"limit": { "context": 65536, "output": 8192 }
2020
},
21-
"glm-5:cloud": {
22-
"name": "GLM-5 (Ollama Cloud)",
21+
"glm-5.3:cloud": {
22+
"name": "GLM-5.3 (Ollama Cloud)",
2323
"tools": true,
2424
"limit": { "context": 131072, "output": 8192 }
2525
}

‎config/opencode/mac-light.json‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,13 +18,13 @@
1818
"tools": true,
1919
"limit": { "context": 16384, "output": 4096 }
2020
},
21-
"glm-5:cloud": {
22-
"name": "GLM-5 (Ollama Cloud)",
21+
"glm-5.3:cloud": {
22+
"name": "GLM-5.3 (Ollama Cloud)",
2323
"tools": true,
2424
"limit": { "context": 131072, "output": 8192 }
2525
},
26-
"kimi-k2.5:cloud": {
27-
"name": "Kimi K2.5 (Ollama Cloud)",
26+
"kimi-k3:cloud": {
27+
"name": "Kimi K3 (Ollama Cloud)",
2828
"tools": true,
2929
"limit": { "context": 131072, "output": 8192 }
3030
}

‎config/opencode/mac-max.json‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,18 +8,18 @@
88
"baseURL": "http://localhost:11434/v1"
99
},
1010
"models": {
11-
"qwen3-coder-next:80b-128k": {
12-
"name": "Qwen3-Coder-Next 80B MoE (unverified)",
11+
"qwen3-coder-next:q4_K_M-128k": {
12+
"name": "Qwen3-Coder-Next (unverified)",
1313
"tools": true,
1414
"limit": { "context": 131072, "output": 8192 }
1515
},
16-
"glm-5:cloud": {
17-
"name": "GLM-5 (Ollama Cloud)",
16+
"glm-5.3:cloud": {
17+
"name": "GLM-5.3 (Ollama Cloud)",
1818
"tools": true,
1919
"limit": { "context": 131072, "output": 8192 }
2020
},
21-
"kimi-k2.5:cloud": {
22-
"name": "Kimi K2.5 (Ollama Cloud)",
21+
"kimi-k3:cloud": {
22+
"name": "Kimi K3 (Ollama Cloud)",
2323
"tools": true,
2424
"limit": { "context": 131072, "output": 8192 }
2525
}

0 commit comments

Comments
 (0)