From 7f4e956466039d5521a358716fedd8c927215cbb Mon Sep 17 00:00:00 2001 From: Mortdecai Date: Sat, 18 Apr 2026 23:42:05 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20session=20handoff=20=E2=80=94=20OpenWeb?= =?UTF-8?q?UI=20setup=20doc?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Chains from 2026-04-18-canonical-tooling-research. Captures the settings-guide work shipped in d9477da and the repo-convention note (push-on-commit for ~/bin Gitea projects). Co-Authored-By: Claude Opus 4.7 (1M context) --- .../2026-04-18-233832-openwebui-setup-doc.md | 135 ++++++++++++++++++ 1 file changed, 135 insertions(+) create mode 100644 .claude/handoffs/2026-04-18-233832-openwebui-setup-doc.md diff --git a/.claude/handoffs/2026-04-18-233832-openwebui-setup-doc.md b/.claude/handoffs/2026-04-18-233832-openwebui-setup-doc.md new file mode 100644 index 0000000..7a1f835 --- /dev/null +++ b/.claude/handoffs/2026-04-18-233832-openwebui-setup-doc.md @@ -0,0 +1,135 @@ +# Handoff: OpenWebUI Setup Doc for Gemma 4 + +## Session Metadata +- Created: 2026-04-18 23:38:32 +- Project: /home/claude/bin/gemma4-research +- Branch: master (pushed to origin) +- Session duration: short (~15 min, one doc) + +### Recent Commits (for context) + - **d9477da docs: OpenWebUI setup guide for Gemma 4** ← this session + - 8436a91 feat: mort-bot think=true vs think=false bakeoff + - c613949 fix: walk back round-1/2 conclusions — the cause was think=false all along + - 7f806e0 feat: round-2 bakeoff — 26b silent-stop is tool-response context size + - a945207 feat: CLI coding agent bakeoff — 26b reproducibly silent-stops at write_file + +## Handoff Chain + +- **Continues from**: [2026-04-18-canonical-tooling-research.md](./2026-04-18-canonical-tooling-research.md) + - Previous title: Handoff — 2026-04-18: Canonical Tooling Research +- **Supersedes**: None + +> Previous handoff's tooling-research context is unrelated to this session's doc-write task. Reference it only if the next session needs canonical upstream material. + +## Current State Summary + +Small doc-write session. Seth asked for a how-to guide for running Gemma 4 in OpenWebUI, starting from the state "OpenWebUI is running and the model is pulled in Ollama," with coverage of every toggleable setting. Created `docs/openwebui-setup.md`, indexed it in `README.md`, committed as `d9477da`, and pushed to `git.sethpc.xyz/Seth/gemma4-research`. Repo is clean. Nothing pending. + +## Codebase Understanding + +### Architecture Overview + +The repo is a Gemma 4 research corpus — SYNTHESIS.md (opinionated guide) + GOTCHAS.md (known issues) + CORPUS_*.md (reference material) + `tooling/` (147-file upstream source drop) + `docs/reference/*` (bakeoff experimental findings). The new `docs/openwebui-setup.md` is the first doc under `docs/` that's a derived how-to guide (not a reference/experimental report), so `docs/` now has two tiers: `docs/reference/*` for experiments, `docs/*.md` for applied guides. + +### Critical Files + +| File | Purpose | Relevance | +|------|---------|-----------| +| `docs/openwebui-setup.md` | New — OpenWebUI configuration guide derived from SYNTHESIS + GOTCHAS | The artifact of this session | +| `README.md` | Repo index | Updated to include the new doc | +| `SYNTHESIS.md` | Opinionated Gemma 4 build guide | Source of the settings table | +| `GOTCHAS.md` | Known issues, severity-ranked | Source of the troubleshooting table in the new doc | +| `docs/reference/bakeoff-2026-04-18.md` | Round 3 evidence for the 26B `think:false` silent-stop | Referenced from the new doc's lead warning | + +### Key Patterns Discovered + +- The repo commit-prefix convention is `docs:` for corpus additions, `feat:` for harness/scripts, `fix:` for walked-back conclusions. Confirmed from last 10 commits. +- Existing docs under `docs/reference/` are bakeoff experimental reports. The new top-level `docs/openwebui-setup.md` intentionally sits outside `reference/` to signal "applied how-to, not raw finding." + +## Work Completed + +### Tasks Finished + +- [x] Created `docs/openwebui-setup.md` (~258 line diff, full per-setting table + two Workspace Model profiles + troubleshooting table) +- [x] Indexed the new doc in `README.md` +- [x] Committed as `d9477da` with `docs:` prefix matching the repo convention +- [x] Pushed to `origin` (Gitea at `git.sethpc.xyz/Seth/gemma4-research`) + +### Files Modified + +| File | Changes | Rationale | +|------|---------|-----------| +| `docs/openwebui-setup.md` | Created — full setup guide | Seth asked for this doc | +| `README.md` | One new row in the index table | Future sessions need to discover the doc | + +### Decisions Made + +| Decision | Options Considered | Rationale | +|----------|-------------------|-----------| +| Put the doc in `gemma4-research/docs/`, not `openwebui/` project | `openwebui/` project dir also exists | The doc is a direct application of SYNTHESIS + GOTCHAS findings — lives with the research corpus, not the OpenWebUI scripts | +| Top-level `docs/`, not `docs/reference/` | Put it next to bakeoff reports | `reference/` holds experimental findings; how-to guides are a different kind. Creating a sibling tier rather than blurring the distinction | +| Lead the TL;DR with the 26B `think:false` footgun | Could have listed settings alphabetically | OpenWebUI chat is exactly the shape Round 3 of the bakeoff showed breaks 26B. Highest-stakes setting goes first | +| Didn't pin to a specific OpenWebUI UI version | Could have screenshot-documented one version | OpenWebUI rearranges the Advanced Params accordion per release. Mapped UI-label → Ollama JSON field name in parallel (`Context Length (num_ctx)`) so future sessions can find the control even after relabeling | +| Pushed after Seth's "I don't see it on git" | Could have asked | Per `~/bin/CLAUDE.md` Gitea convention: "Commit every meaningful change immediately; push on the same command." I defaulted to git-safety no-push on the first commit — that was wrong for this repo's convention | + +## Pending Work + +## Immediate Next Steps + +1. **Nothing required.** The task shipped cleanly and the repo is clean. +2. *Optional:* Seth could test the `gemma4-26b-chat` and `gemma4-26b-extract` Workspace Model profiles against a real OpenWebUI instance to confirm the setting names match the current UI version. The doc's label↔field mapping is defensive but the first live walkthrough is the best test. +3. *Optional:* If the new `mcp-gemma4` project (added to `~/bin/CLAUDE.md` as a project entry this session, outside this repo) ends up needing setup docs for the same `gemma4:26b` backend, the `docs/openwebui-setup.md` advanced-params table is directly portable. + +### Blockers/Open Questions + +- None. + +### Deferred Items + +- Screenshots of the OpenWebUI UI flow. Deferred because (a) UI shifts per release, (b) Seth didn't ask, (c) the label↔field mapping serves the same purpose without the maintenance cost. + +## Context for Resuming Agent + +## Important Context + +- **The repo convention is push-on-commit.** `~/bin/CLAUDE.md` says "Commit every meaningful change immediately; push on the same command." I defaulted to git-safety no-push on my first commit this session and Seth had to correct me with "I don't see it on git." For any commit in `~/bin/*` Gitea projects, push in the same step as the commit. +- **The single biggest Gemma 4 OpenWebUI footgun is `think: false` on `gemma4:26b` in multi-turn chat.** If a future session debugs "OpenWebUI chat with Gemma 4 silently stops answering after a few turns," check the Reasoning toggle in the Workspace Model first. Round 3 of the 2026-04-18 bakeoff (`docs/reference/bakeoff-2026-04-18.md`) has the evidence trail. +- **Gemma 4 needs an explicit system prompt** — it's ultra-compliant but has no identity. Any setup guidance that skips the system prompt produces a generic chatbot. + +### Assumptions Made + +- Seth's OpenWebUI install is recent enough to have the "Workspace Models" / "Create Model" preset feature. True of all OpenWebUI versions from mid-2024 onward. +- The settings UI labels match or closely match the names used in the doc. Defensive mapping to Ollama JSON field names compensates if they drift. +- `gemma4:26b` is Seth's default on pve197 CT 105 and steel141 (confirmed by `~/bin/CLAUDE.md` "Ollama models" section). + +### Potential Gotchas + +- If the next session adds more docs under `docs/` top-level, keep them *how-to* / *applied-guide* in flavor. Experimental or raw findings go in `docs/reference/`. The tier distinction is new and shallow — easy to erode. +- The doc references `~/bin/FreibergFamily/simon/` as the multi-turn tool-calling example. Path is outside the repo; future sessions editing this doc from a different host should verify the path still resolves on steel141 before changing it. + +## Environment State + +### Tools/Services Used + +- Git (committed, pushed to Gitea at `git.sethpc.xyz/Seth/gemma4-research`) +- No Ollama / OpenWebUI runtime touched this session — pure doc-write. + +### Active Processes + +- None started or left running by this session. + +### Environment Variables + +- None set or referenced. (`~/.config/gitea/token` used implicitly by `git push` via the HTTPS remote.) + +## Related Resources + +- [docs/openwebui-setup.md](../../docs/openwebui-setup.md) — the artifact +- [SYNTHESIS.md](../../SYNTHESIS.md) — source of the settings recommendations +- [GOTCHAS.md](../../GOTCHAS.md) — source of the troubleshooting table +- [docs/reference/bakeoff-2026-04-18.md](../../docs/reference/bakeoff-2026-04-18.md) — Round 3 evidence for the `think:false` / 26B gotcha +- Gitea commit: `git.sethpc.xyz/Seth/gemma4-research` @ `d9477da` + +--- + +**Security Reminder**: Before finalizing, run `validate_handoff.py` to check for accidental secret exposure.