docs: add Day 3 treasure panel implementation plan

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.gitignore

@@ -209,6 +209,9 @@ tempCodeRunnerFile.py
 # PyPI configuration file
 .pypirc
 
+# Superpowers brainstorming
+.superpowers/
+
 # Marimo
 marimo/_static/
 marimo/_lsp/

docs/superpowers/plans/2026-06-10-day3-treasure-panel.md

@@ -0,0 +1,392 @@
+# Day 3 — Treasure Panel Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Show the memories Hollow extracts from the visitor in a "Treasure" side panel, and confirm Hollow uses them in later turns.
+
+**Architecture:** The backend is already complete — `TurnUpdate.new_memories`, the extraction prompt, `apply_update`'s dedupe, and `build_system_prompt`'s treasure injection all exist and are tested. This day is **presentation only**. We add a pure `render_treasure(treasure) -> str` function in a new `render.py` module (no Gradio import → unit-testable in isolation, the same separation pattern Day 2 used when it moved logic into `memory.py`), then wire a `gr.HTML` panel into a two-column layout in `app.py`. All visitor-derived memory text is HTML-escaped before injection.
+
+**Tech Stack:** Python 3.11, Gradio 6.x (`gr.Blocks`, `gr.Row`, `gr.Column`, `gr.HTML`, `.then()` chaining), `html` stdlib, pytest via uv.
+
+---
+
+## File map
+
+| File | Action | Responsibility |
+|------|--------|----------------|
+| `render.py` | **Create** | `render_treasure` — pure HTML string from a memory list, with escaping |
+| `tests/test_render.py` | **Create** | Unit tests for `render_treasure` (placeholder, items, escaping) |
+| `app.py` | **Modify** | Two-column layout; `gr.HTML` treasure panel; wire into both `chat()` returns |
+
+**No changes** to `engine.py`, `memory.py`, `character.py`, `schemas.py` — the memory pipeline is done.
+
+---
+
+## Design notes (read before starting)
+
+- **Empty state = Hollow's voice.** When `treasure` is empty, the panel shows `...nothing yet. but i'm listening.` — chosen so the panel reads as Hollow paying attention, not as empty UI.
+- **Escaping is mandatory.** Memories originate from the visitor's typed text (the LLM extracts them). Raw injection into `gr.HTML` would break on `<`, `>`, `&` and allow HTML injection. Every memory passes through `html.escape()`.
+- **The 7th output.** `chat()` currently returns 6 values from **two** `return` statements (the empty-message early return and the normal return). Both must be extended with the treasure HTML or Gradio raises an output-count mismatch.
+- **`_start_turn` is NOT touched for treasure.** It does not receive `state`, and a memory shared this turn is only extracted inside `chat()` — there is nothing new to show during the loading placeholder. Treasure updates live only in `chat()`.
+- **Inline styles are the Day-3 base.** The dark styling here is intentionally minimal (matches the approved mockup). Day 5 replaces it with global CSS in `styles.css`. Keep all styling inside `render.py` so Day 5 has one place to change.
+
+---
+
+## Task 1: Create `tests/test_render.py` with failing tests for `render_treasure`
+
+**Files:**
+- Create: `tests/test_render.py`
+
+- [ ] **Step 1: Write the failing tests**
+
+Create `tests/test_render.py`:
+
+```python
+from render import render_treasure
+
+
+class TestRenderTreasure:
+    def test_empty_shows_placeholder(self):
+        out = render_treasure([])
+        assert "nothing yet. but i'm listening." in out
+
+    def test_empty_has_no_memory_item(self):
+        # The memory-item style marker must not appear when there are no memories
+        out = render_treasure([])
+        assert "border-left:2px solid #5a3a7a" not in out
+
+    def test_single_memory_appears(self):
+        out = render_treasure(["has a dog named Nala"])
+        assert "has a dog named Nala" in out
+
+    def test_multiple_memories_all_appear(self):
+        out = render_treasure(["has a dog named Nala", "grew up near the sea"])
+        assert "has a dog named Nala" in out
+        assert "grew up near the sea" in out
+
+    def test_html_tags_are_escaped(self):
+        out = render_treasure(["<script>alert('x')</script>"])
+        assert "<script>" not in out
+        assert "&lt;script&gt;" in out
+
+    def test_ampersand_is_escaped(self):
+        out = render_treasure(["mom & dad"])
+        assert "mom &amp; dad" in out
+
+    def test_header_present_in_both_states(self):
+        assert "Treasure" in render_treasure([])
+        assert "Treasure" in render_treasure(["x"])
+```
+
+- [ ] **Step 2: Run tests to confirm they fail with ImportError**
+
+```
+.venv\Scripts\pytest tests/test_render.py -v
+```
+
+Expected: FAIL with `ModuleNotFoundError: No module named 'render'`. The tests must fail before we implement.
+
+---
+
+## Task 2: Create `render.py` to make the tests pass
+
+**Files:**
+- Create: `render.py`
+
+- [ ] **Step 1: Create `render.py`**
+
+```python
+import html
+
+_PLACEHOLDER = "...nothing yet. but i'm listening."
+
+_PANEL = (
+    "background:#0c0a12;border:1px solid #2a1f3d;border-radius:4px;"
+    "padding:10px;min-height:460px;"
+)
+_HEADER = (
+    "font-size:10px;letter-spacing:2px;text-transform:uppercase;color:#5a4570;"
+    "padding-bottom:6px;border-bottom:1px solid #1e1628;margin-bottom:8px;"
+)
+_ITEM = (
+    "background:#110d1a;border:1px solid #2a1f3d;border-left:2px solid #5a3a7a;"
+    "border-radius:0 3px 3px 0;padding:5px 8px;margin-bottom:6px;"
+    "font-size:11px;color:#9a80b8;line-height:1.4;"
+)
+_EMPTY = "font-size:11px;color:#4a3f56;font-style:italic;"
+
+
+def render_treasure(treasure: list[str]) -> str:
+    header = f'<div style="{_HEADER}">✦ Treasure</div>'
+    if not treasure:
+        body = f'<div style="{_EMPTY}">{_PLACEHOLDER}</div>'
+    else:
+        body = "".join(
+            f'<div style="{_ITEM}">{html.escape(m)}</div>' for m in treasure
+        )
+    return f'<div style="{_PANEL}">{header}{body}</div>'
+```
+
+Note: `_PLACEHOLDER` is a trusted constant (no visitor data), so it is not escaped — its apostrophe is valid in HTML text content. Only the visitor-derived `m` values are passed through `html.escape()`. `✦` is the ✦ star glyph, kept as an escape so the file stays ASCII-safe.
+
+- [ ] **Step 2: Run the tests**
+
+```
+.venv\Scripts\pytest tests/test_render.py -v
+```
+
+Expected: all 7 tests PASS.
+
+- [ ] **Step 3: Run the full suite to confirm nothing else broke**
+
+```
+.venv\Scripts\pytest tests/ -v
+```
+
+Expected: all 23 tests PASS (16 from `test_memory.py` + 7 new).
+
+- [ ] **Step 4: Commit**
+
+```
+git add render.py tests/test_render.py
+git commit -m "feat: add render.py with render_treasure, tests passing"
+```
+
+---
+
+## Task 3: Wire the treasure panel into `app.py`
+
+**Files:**
+- Modify: `app.py`
+
+- [ ] **Step 1: Replace the full contents of `app.py`**
+
+```python
+import gradio as gr
+
+from character import build_system_prompt, OPENING_LINE
+from engine import run_turn
+from memory import apply_update, get_tier
+from render import render_treasure
+
+
+def _init_state():
+    return {
+        "affinity": 15,
+        "treasure": [],
+        "claimed": [],
+        "history": [],
+        "turn": 0,
+    }
+
+
+def _start_turn(user_msg: str, history: list):
+    if not user_msg.strip():
+        return gr.update(), gr.update(interactive=False), history
+    new_history = history + [
+        {"role": "user", "content": user_msg},
+        {"role": "assistant", "content": "..."},
+    ]
+    return gr.update(interactive=False), gr.update(interactive=False), new_history
+
+
+def chat(user_msg: str, state: dict, history: list):
+    if not user_msg.strip():
+        tier = get_tier(state["affinity"])
+        return (
+            gr.update(interactive=True),
+            gr.update(interactive=True),
+            history,
+            state,
+            state["affinity"],
+            f"*{tier}*",
+            render_treasure(state["treasure"]),
+        )
+
+    system = build_system_prompt(state["affinity"], state["treasure"])
+    chat_messages = [{"role": "system", "content": system}] + state["history"] + [
+        {"role": "user", "content": user_msg}
+    ]
+
+    reply, raw_json = run_turn(chat_messages, user_msg)
+    state = apply_update(state, raw_json)
+
+    state["history"].append({"role": "user", "content": user_msg})
+    state["history"].append({"role": "assistant", "content": reply})
+    state["turn"] += 1
+
+    new_history = history[:-1] + [{"role": "assistant", "content": reply}]
+
+    tier = get_tier(state["affinity"])
+    return (
+        gr.update(value="", interactive=True),
+        gr.update(interactive=True),
+        new_history,
+        state,
+        state["affinity"],
+        f"*{tier}*",
+        render_treasure(state["treasure"]),
+    )
+
+
+with gr.Blocks(title="Hollow") as demo:
+    state = gr.State(_init_state)
+
+    gr.Markdown("## Hollow\n*something is here, at the edge of the wood*")
+
+    with gr.Row():
+        with gr.Column(scale=2):
+            chatbot = gr.Chatbot(
+                value=[{"role": "assistant", "content": OPENING_LINE}],
+                label="",
+                height=500,
+            )
+
+            with gr.Row():
+                affinity_slider = gr.Slider(
+                    minimum=0, maximum=100, value=15,
+                    interactive=False, label="Bond", scale=4,
+                )
+                tier_label = gr.Markdown("*Hollow*", scale=1)
+
+            with gr.Row():
+                msg_input = gr.Textbox(
+                    placeholder="say something...",
+                    show_label=False,
+                    scale=9,
+                    autofocus=True,
+                )
+                send_btn = gr.Button("→", scale=1)
+
+        with gr.Column(scale=1):
+            treasure_panel = gr.HTML(value=render_treasure([]))
+
+    send_btn.click(
+        fn=_start_turn,
+        inputs=[msg_input, chatbot],
+        outputs=[msg_input, send_btn, chatbot],
+    ).then(
+        fn=chat,
+        inputs=[msg_input, state, chatbot],
+        outputs=[msg_input, send_btn, chatbot, state, affinity_slider, tier_label, treasure_panel],
+    )
+
+    msg_input.submit(
+        fn=_start_turn,
+        inputs=[msg_input, chatbot],
+        outputs=[msg_input, send_btn, chatbot],
+    ).then(
+        fn=chat,
+        inputs=[msg_input, state, chatbot],
+        outputs=[msg_input, send_btn, chatbot, state, affinity_slider, tier_label, treasure_panel],
+    )
+
+if __name__ == "__main__":
+    demo.launch()
+```
+
+Key changes from the Day-2 version:
+- `from render import render_treasure` added.
+- Chat + meters + input wrapped in `gr.Column(scale=2)`; a new `gr.Column(scale=1)` holds `treasure_panel = gr.HTML(value=render_treasure([]))` so the placeholder shows on load.
+- Both `chat()` returns now append `render_treasure(state["treasure"])` as a 7th value.
+- Both `.then(...)` chat events add `treasure_panel` as the 7th output. `_start_turn` outputs are unchanged.
+
+- [ ] **Step 2: Confirm the app imports without error**
+
+```
+.venv\Scripts\python -c "import app; print('app imports OK')"
+```
+
+Expected: `app imports OK` with no traceback. (This catches output-count or syntax mistakes before launching.)
+
+- [ ] **Step 3: Run the full test suite**
+
+```
+.venv\Scripts\pytest tests/ -v
+```
+
+Expected: all 23 tests PASS.
+
+- [ ] **Step 4: Commit**
+
+```
+git add app.py
+git commit -m "feat: treasure panel in app.py two-column layout"
+```
+
+---
+
+## Task 4: Manual behavioral verification (the Day-3 checkpoint)
+
+This checkpoint is **behavioral**, not visual — it must be run against the live local model (Ollama), not just confirmed by a rendered panel.
+
+**Files:** none (verification only).
+
+- [ ] **Step 1: Make sure Ollama is serving `qwen3:8b`**
+
+```
+ollama list
+```
+
+Expected: `qwen3:8b` appears in the list. If Ollama is not running, start it first.
+
+- [ ] **Step 2: Launch the app**
+
+```
+.venv\Scripts\python app.py
+```
+
+Open `http://127.0.0.1:7860`.
+
+- [ ] **Step 3: Verify the empty state**
+
+On load, the right column shows the Treasure panel with the header `✦ Treasure` and the placeholder `...nothing yet. but i'm listening.`
+
+- [ ] **Step 4: Verify a memory appears (turn 1)**
+
+Type: `I have a dog named Nala.` and press Enter.
+After Hollow replies, a memory item (e.g. `has a dog named Nala`) appears in the Treasure panel.
+
+> Note: extraction is the LLM's job. The exact wording may vary; what matters is that a Nala-related memory shows up. If nothing appears, the issue is extraction (Day 2), not this panel — check the engine/extraction output, do not patch the panel.
+
+- [ ] **Step 5: Verify Hollow recalls it (turn 2 — the real checkpoint)**
+
+Type: `Do you remember my pet?` and press Enter.
+Hollow's reply should reference Nala/the dog. This proves the treasure was injected into the next turn's system prompt via `build_system_prompt`.
+
+> Timing by design: the memory shared in turn 1 is injected starting in turn 2 — the prompt that generates a reply cannot contain a memory that same reply hasn't been extracted from yet. See `app.py` `chat()`: `build_system_prompt(...)` runs before `apply_update(...)`.
+
+- [ ] **Step 6: Verify escaping (defensive)**
+
+Type: `My password is <secret>.` and press Enter.
+If a memory is extracted from it, the Treasure panel renders the angle brackets as literal text — the panel does not break and no tag is interpreted.
+
+**Checkpoint Day 3 done:** a memory the visitor shares appears in the Treasure panel, and Hollow references it on a later turn. ✅
+
+---
+
+## Task 5: Deploy to HF Space
+
+**Files:** none (deploy only).
+
+- [ ] **Step 1: Push to the Space**
+
+```
+git push space main
+```
+
+- [ ] **Step 2: Verify on the live Space**
+
+Open `https://huggingface.co/spaces/Pabloler21/hollow` once the Space rebuilds. Confirm:
+- The Treasure panel is visible in the right column with the placeholder on load.
+- After sharing a memory, it appears in the panel.
+- On a later turn, Hollow references the shared memory.
+
+---
+
+## Self-review notes
+
+- **Spec coverage:** Day-3 plan items — extend `TurnUpdate` (already done Day 2), extraction of personal facts (already done Day 2), dedupe + treasure injection (already done Day 2), and the side panel listing memories (Tasks 1–3). The behavioral checkpoint is Task 4. All covered.
+- **Escaping:** handled in `render.py` (Task 2) and tested (Task 1, `test_html_tags_are_escaped`, `test_ampersand_is_escaped`).
+- **Output count:** both `chat()` returns and both `.then()` events extended together (Task 3) — no mismatch.
+- **Type consistency:** `render_treasure(treasure: list[str]) -> str` defined in Task 2, imported and called identically in `app.py` (Task 3) and tests (Task 1).