fix

docs/local-llm-tuning.md

@@ -14,12 +14,21 @@ Defaults for OpenAI-compatible local servers such as Green Chat Gemma 12B (`over
 
 Restart **both** `api` and `worker` after changing `OPENAI_*`. Worker logs should say `OpenAI enabled base=… model=…`, not `heuristic completer`.
 
+## Product enhance model choice
+
+Admin AI role for **product enhance** should prefer a **fast non-reasoning chat model** that emits `message.content` (JSON) under budget.
+
+Reasoning / “code-fast” style models often spend the entire `max_tokens` budget in `reasoning_content`, then return `finish_reason=length` with empty or truncated JSON. Descrybe retries once at `MaxTokensEnhanceRetry` and may synthesize formula HTML as salvage — that is **not** live LLM formula compliance.
+
+If enhance logs show `finish_reason=length` with empty/truncated content even after the retry, switch Admin enhance to a non-reasoning model.
+
 ## Hardening defaults (code)
 
 | Constant | Value | Where |
 |----------|------:|-------|
 | `DefaultStructuredTemp` | `0.2` (capped ≤0.3) | `processing/llm_json.go`, `openai.go` |
-| `MaxTokensEnhance` | `350` | product title/description |
+| `MaxTokensEnhance` | `16384` | product title/description (reasoning + formula HTML JSON) |
+| `MaxTokensEnhanceRetry` | `32768` | one-shot bump on `finish_reason=length` empty/truncated JSON |
 | `MaxTokensSEO` | `180` | meta title/description |
 | `MaxTokensCampaign` | `650` | email JSON |
 | `MaxProductDescRunes` | `400` | user context |
@@ -27,6 +36,8 @@ Restart **both** `api` and `worker` after changing `OPENAI_*`. Worker logs shoul
 | `MaxBrandInjectRunes` | `500` | brand kit block |
 | `MaxCampaignProducts` | `8` | campaign product list |
 
+OpenAI-compatible chat completions here use a single `max_tokens` completion budget (no separate reasoning vs content split on typical gateways). Length-cap handling lives in `OpenAIClient.doComplete` / `CompleteWithOptions`.
+
 ## Prompt style
 
 - Short system prompts with **bullet rules** + explicit JSON schema
@@ -43,6 +54,8 @@ Restart **both** `api` and `worker` after changing `OPENAI_*`. Worker logs shoul
 3. On parse fail → **one retry** with `INVALID. Reply with ONLY one JSON object…`
 4. Call sites fall back to originals/templates instead of storing garbage prose as titles
 
+`OpenAIClient` additionally treats `finish_reason=length` with empty or unparseable JSON as failure (not success) and retries once at `MaxTokensEnhanceRetry`.
+
 ## Ops tips
 
 - Prefer LAN TCP reachability checks (`Test-NetConnection host -Port 8767`) over ICMP