# 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.