docs: merge tooling findings into SYNTHESIS/GOTCHAS/CORPUS_* and add handoff

Patches the top-level corpus docs with the 13 findings flagged during the
2026-04-18 canonical tooling research pass. tooling/README.md now marks each
finding [merged: <file>] or [flagged] for provenance.

- CORPUS_ollama_variants.md: annotate gemma4:26b as MoE (25.2B total / 3.8B
  active, 8-of-128 experts + 1 shared). Note Q4_K_M inference is standard
  (the "MoE quality degrades at 4-bit" caveat is training-only). Add note
  that audio on E-series is NOT available via Ollama — llama.cpp mmproj
  or vLLM only.
- CORPUS_capabilities.md: native system role, configurable thinking mode,
  first trained tool use (vs Gemma 1/2/3 proof-of-concept), native object
  detection with bbox output in 1000x1000 coords, pointer to EmbeddingGemma
  for retrieval (Gemma 4 has no embedding mode).
- CORPUS_tool_calling_format.md: add Chat Template Context section
  documenting the <|turn>/<turn|> asymmetric brackets (new in Gemma 4,
  replaced <start_of_turn>/<end_of_turn>) plus <|think>, <|channel>,
  <|image>, <|audio> tokens. Add HF transformers Alternative section
  showing processor.parse_response with response_schema.
- GOTCHAS.md: add MEDIUM gotcha for abandoned google/gemma_pytorch (no
  Gemma 4 support since 2025-05-30). Expand fine-tuning section with FA2/FA4
  head_dim=512 break, fused LoRA kernel issues, 26B A4B training-quant
  guidance, new tool-call tokens as learned embeddings.
- SYNTHESIS.md: add banner pointing to tooling/ for canonical upstream
  material. Add embeddinggemma row to Model Selection table.

Also:
- Add .gitignore excluding .backup/ (local scratch per global CLAUDE.md
  convention, not needed in tracked history) and __pycache__/.
- Add .claude/handoffs/2026-04-18-canonical-tooling-research.md so future
  sessions can pick up cold — facts verified, open threads, what changed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

GOTCHAS.md

@@ -168,6 +168,21 @@ Gemma 4 can generate `<unused>` or `<unused24>` tokens in an infinite loop on Vu
 
 **Source:** [ggml-org/llama.cpp#21516](https://github.com/ggml-org/llama.cpp/issues/21516)
 
+## MEDIUM: `google/gemma_pytorch` Abandoned for Gemma 4
+
+**Severity: MEDIUM — wastes time on a dead-end path**
+
+The `google/gemma_pytorch` repo (last push 2025-05-30) has zero Gemma 4 support —
+its variants validator only accepts Gemma 1/2/3 IDs. Anyone pointing at it as "the
+official PyTorch reference" for Gemma 4 is wrong.
+
+**Use instead:**
+- **Inference:** `huggingface/transformers` (`AutoModelForMultimodalLM`, v5.5.4+)
+- **Reference impl:** `google-deepmind/gemma` (JAX/Flax)
+- **Serving:** Ollama / vLLM / llama.cpp
+
+See `tooling/google-official/gemma-pytorch/README.md` for the original repo state.
+
 ## LOW: Fine-Tuning Ecosystem Issues
 
 **Severity: LOW — only relevant if fine-tuning**
@@ -177,6 +192,20 @@ Day-one issues for fine-tuners:
 - PEFT couldn't handle Gemma4ClippableLinear (new vision encoder layer type)
 - New `mm_token_type_ids` field required during training even for text-only data
 - E2B/E4B show training loss of 13-15, which is normal for multimodal models (not a bug)
+- **Flash Attention 2/4 incompatible:** Gemma 4's global-attention head_dim is 512;
+  FA2 max is 256, FA4 max is 128. Training backends fall back to SDP or Flex Attention
+  (Axolotl hard-codes `sdp_attention: true` for Gemma 4). Does not affect inference
+  runtimes that already use SDP (Ollama, vLLM).
+- **Fused LoRA kernels broken** (shared-KV layers). Axolotl disables
+  `lora_mlp_kernel` / `qkv_kernel` / `o_kernel` for Gemma 4; Unsloth routes around it.
+- **26B A4B MoE wants ≥8-bit LoRA**, not 4-bit QLoRA — MoE expert quality degrades
+  at 4-bit during training. Axolotl's ScatterMoE + expert-LoRA config is the only
+  validated 4-bit MoE path. (This caveat is **training-only**; Q4_K_M inference is fine.)
+- **New tool-call / channel tokens are learned embeddings** — if fine-tuning, set
+  `modules_to_save=["lm_head","embed_tokens"]` + `ensure_weight_tying=True` in
+  `LoraConfig`, or the adapter trains against frozen random vectors for them.
+
+See `tooling/fine-tuning/recipe-recommendation.md` for the full training path.
 
 ## LOW: Vision Validator Overrejects