gemma4-research/.claude/handoffs/2026-04-18-233832-openwebui-setup-doc.md

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
  • 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

• Created docs/openwebui-setup.md (~258 line diff, full per-setting table + two Workspace Model profiles + troubleshooting table)
• Indexed the new doc in README.md
• Committed as d9477da with docs: prefix matching the repo convention
• 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 — the artifact
• SYNTHESIS.md — source of the settings recommendations
• GOTCHAS.md — source of the troubleshooting table
• 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.