docs: Update documentation

CLAUDE.md

@@ -117,6 +117,12 @@ engine._view ─▶ ViewState ─▶ frontend/index.html  (backdrop + sprite + d
 6. **Context window is finite** ("Thousand Token Wood"). Feed summary + present sheets + last k turns —
    never the whole log. `memory.py` enforces it.
 7. **Spaces filesystem is ephemeral.** `.md` memory is per-session unless you wire HF persistent storage.
+8. **Qwen3 think-mode on ZeroGPU.** Qwen3-14B via `transformers` sometimes puts the entire JSON answer
+   inside its `<think>` block and emits nothing after `</think>`. `TransformersLLM.complete_json` handles
+   this by calling `apply_chat_template(..., enable_thinking=False)` to suppress thinking for structured
+   output, and falls back to searching inside the think block if no JSON appears after it. Do NOT use
+   `_quiet_stderr()` around transformers loads — it swallows loading errors that are essential for
+   ZeroGPU debugging.
 
 ## Definition of done (MVP)
 

docs/ARCHITECTURE.md

@@ -153,7 +153,7 @@ class GameState(BaseModel):
 {
   "speaker": "lantern_moth",          // which present character speaks (or "narrator")
   "dialogue": "string",               // their line, in voice
-  "emotion": "neutral|joy|fear|anger|sad|surprise|tender",  // → sprite mood
+  "emotion": "string",                // free-form mood word (e.g. "curious", "tender") → sprite mood
   "directives": {
     "scene_change": null,             // or { "place": "...", "description": "...", "mood": "..." }
     "new_character": null,            // or a partial Character (id,name,one_line,appearance,voice,traits,goals)
@@ -166,7 +166,7 @@ class GameState(BaseModel):
 }
 ```
 
-`emotion` is required and constrained to an enum (cheap mood→sprite mapping). Every nested object is optional/nullable so simple turns stay tiny. **All of this is grammar-enforced** — `complete_json` cannot return anything that doesn’t parse.
+`emotion` is a free-form string (the LLM picks whatever fits the moment). Every nested object is optional/nullable so simple turns stay tiny. `complete_json` enforces structure on the llama.cpp path via GBNF; on the `transformers` path it uses prompt-based JSON extraction with 3-attempt retry.
 
 ### 4.3 `.md` as a derived view (not the truth)
 

docs/PROMPTS.md

@@ -107,8 +107,7 @@ out = llm.create_chat_completion(
   "properties": {
     "speaker": { "type": "string" },
     "dialogue": { "type": "string" },
-    "emotion": { "type": "string",
-      "enum": ["neutral","joy","fear","anger","sad","surprise","tender"] },
+    "emotion": { "type": "string" },
     "directives": {
       "type": "object",
       "additionalProperties": false,
@@ -199,7 +198,7 @@ ending      ::= "{" ws
                 "\"kind\"" ws ":" ws ("\"warm\"" | "\"bittersweet\"" | "\"strange\"") ws "," ws
                 "\"text\"" ws ":" ws string ws "}"
 
-emotion     ::= "\"neutral\"" | "\"joy\"" | "\"fear\"" | "\"anger\"" | "\"sad\"" | "\"surprise\"" | "\"tender\""
+emotion     ::= string
 
 flagobj     ::= "{" ws ( flagpair ( ws "," ws flagpair )* ws )? "}"
 flagpair    ::= string ws ":" ws string
@@ -244,4 +243,4 @@ For **mood swaps** with FLUX.2 Klein, condition on the cached base sprite instea
 | Memory compaction | 0.3 | 0.9 | want faithful, terse summary |
 | Image-prompt | — | — | composed in code, no sampling |
 
-Add a light `repeat_penalty` (~1.05–1.1) to fight the “AI slop” repetition small models drift into. Keep `max_tokens` tight (≈512) for the director call — it should be short.
+Add a light `repeat_penalty` (~1.05–1.1) to fight the “AI slop” repetition small models drift into. Use `max_tokens≈1024` for the director call — actions like `scout` (which must fill a full `new_character` object) need the extra budget.