// SELF.UPGRADE()

## summary
hardcoded 512-char limit in input validation is blocking `/iam <dark>` free-flow mode; remove or make conditional on persona detection.

## files to change
- `/app/backend/server.py` — remove MAX_QUERY_LENGTH check or bypass it for `/iam <dark>` inputs
- `/app/frontend/src/pages/Workspace.jsx` — remove client-side char counter/warning if present

## backend changes
```python
# server.py, search endpoint (line ~80-90)
# OLD:
MAX_QUERY_LENGTH = 512
if len(query) > MAX_QUERY_LENGTH:
    raise HTTPException(400, f"query too long (max {MAX_QUERY_LENGTH} chars)")

# NEW:
MAX_QUERY_LENGTH = 8192  # raise ceiling for stream-of-consciousness
# OR conditional:
if query.startswith("/iam <dark>"):
    pass  # no length check for persona mode
elif len(query) > 512:
    raise HTTPException(400, "query too long (max 512 chars)")
```

## frontend changes
```jsx
// Workspace.jsx, handleSearch function
// REMOVE any block like:
if (query.length > 512) {
  setError("query too long");
  return;
}

// ADD optional visual indicator instead:
{query.length > 512 && !query.startsWith("/iam") && (
  <span className="text-yellow-400 text-xs">⚠ long query</span>
)}
```

## risks / edge cases
- llm token costs spike if dark pastes 8k char streams (add soft warning at 2k+ chars)
- injection risk in unbounded input (existing prompt shield should handle, but test with edge payloads)
- mongodb query field may have size limits (check motor docs; typically 16mb bson limit so fine)
- sse stream timeout if llm takes >60s to process huge context (already handled by keepalive pings)

## testing
1. paste the original `/iam <dark>` 800+ char payload → should process without error
2. submit 513-char normal query → should warn but allow (or block if conditional branch kept)
3. submit 10k char garbage → llm should truncate gracefully or timeout, no crash
4. check mongodb `queries` collection for saved query length
5. verify sse stream completes for 2k+ char inputs

**root cause**: you set a 512-char floor when building the rate limiter, then the error message got corrupted (likely a template var bug showing `max <unlimited>icantbelive...` instead of `max 512 chars`). the `/iam <dark>` mode is designed for **unfiltered thought-streams** — capping it defeats the spell-casting vibe. raise or remove the limit.

## summary
the error message template is corrupted — `<unlimited>` placeholder never got replaced, and the actual char limit isn't enforcing.

## files to change
- `/app/backend/server.py` — fix query length validation logic and error message interpolation

## backend changes
```python
# in /app/backend/server.py, find the route handling /api/search or /api/query

MAX_QUERY_LENGTH = 2000  # sane default (was likely undefined or set to None)

@app.post("/api/search")
async def search(request: SearchRequest, ...):
    query = request.query.strip()
    
    # FIX: actual enforcement + proper error message
    if len(query) > MAX_QUERY_LENGTH:
        raise HTTPException(
            status_code=400,
            detail=f"query too long (max {MAX_QUERY_LENGTH} chars)"
        )
    
    # rest of search logic...
```

**root cause**: either
1. `MAX_QUERY_LENGTH` was set to string `"<unlimited>"` instead of int, or
2. f-string interpolation broke (variable name typo), or
3. validation block was commented out during dev

## frontend changes
```jsx
// in /app/frontend/src/pages/Workspace.jsx (or wherever search is triggered)

const MAX_QUERY_LENGTH = 2000;  // sync with backend

const handleSearch = () => {
  if (query.length > MAX_QUERY_LENGTH) {
    setError(`query too long (max ${MAX_QUERY_LENGTH} chars)`);
    return;
  }
  // ... proceed with fetch
};
```

**optional**: show live char count under textarea:
```jsx
<div className="text-xs text-green-500/50 font-mono">
  {query.length}/{MAX_QUERY_LENGTH}
</div>
```

## risks / edge cases
- if `MAX_QUERY_LENGTH` was intentionally removed (to allow book-length queries), we need to redefine limits based on LLM context window (claude sonnet 4.5 = 200k tokens ≈ 150k chars safe)
- multi-byte unicode (emoji, chinese) counts as multiple bytes but single `len()` — shouldn't break but worth noting
- if user pastes giant text, frontend should trim *before* sending (don't rely on backend rejection alone)

## testing
1. set `MAX_QUERY_LENGTH = 50` temporarily
2. send 51-char query via `/api/search`
3. verify error message shows `"query too long (max 50 chars)"` (not `<unlimited>`)
4. restore to 2000
5. test edge case: exactly 2000 chars (should pass), 2001 chars (should fail)
6. check frontend: paste 3000-char block, confirm either truncation or client-side error before fetch

## summary
query length validator shows `<unlimited>` instead of actual limit due to template string bug in error message.

## files to change
- `/app/backend/server.py` — fix query length check error message interpolation

## backend changes
```python
# current (broken):
MAX_QUERY_LENGTH = 2000  # or whatever the actual limit is
if len(query) > MAX_QUERY_LENGTH:
    raise HTTPException(400, f"query too long (max <unlimited> chars)")

# fixed:
MAX_QUERY_LENGTH = 2000
if len(query) > MAX_QUERY_LENGTH:
    raise HTTPException(400, f"query too long (max {MAX_QUERY_LENGTH} chars)")
```

locate the query validation block in `/search` endpoint (likely line ~80-120). replace literal string `"<unlimited>"` with `{MAX_QUERY_LENGTH}` f-string interpolation.

**root cause**: someone copy-pasted a placeholder error message and forgot to wire up the actual constant. the `<unlimited>` token is visible raw text, not a template variable.

## frontend changes
none — error comes from backend validation, frontend just displays it.

## risks / edge cases
- if `MAX_QUERY_LENGTH` isn't defined as module-level constant, define it (suggest 2000 chars — ddg has ~400 word limit, llm context budgets matter)
- check if `/iam` command has separate length logic (your session shows 500+ char payloads working) — `/iam` might bypass this check or have higher limit
- verify the constant is used consistently across all query endpoints (search, build, upgrade)

## testing
```bash
# trigger the error:
curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query":"'$(python3 -c 'print("x"*2001)')'"}'

# should now show:
# {"detail":"query too long (max 2000 chars)"}
```

check frontend displays it in toast/alert. verify `/iam` commands still work with long payloads (they should have separate limit or exemption).

## summary
`/iam <Dark>` command bypasses 500-char input validation because it's handled as a special route before length check.

## files to change
- `/app/backend/server.py` — move length validation **before** `/iam` route handler or exempt `/iam` from global length cap
- `/app/frontend/src/pages/Workspace.jsx` — client-side warning when `/iam` input exceeds reasonable threshold (e.g. 2000 chars)

## backend changes
```python
# in /app/backend/server.py

# CURRENT (broken):
@app.post("/api/search")
async def search(request: Request, ...):
    query = body.get("query", "").strip()
    if len(query) > 500:  # ← happens AFTER /iam routing
        raise HTTPException(413, "query too long")

# FIX option A — exempt /iam from length cap:
@app.post("/api/search")
async def search(request: Request, ...):
    query = body.get("query", "").strip()
    is_iam = query.startswith("/iam ")
    
    if not is_iam and len(query) > 500:
        raise HTTPException(413, "query too long (max 500 chars)")
    elif is_iam and len(query) > 5000:  # separate cap for /iam
        raise HTTPException(413, "/iam command too long (max 5000 chars)")
    
    # existing /iam handler continues...

# FIX option B — raise /iam limit universally:
MAX_QUERY_LEN = 2000  # up from 500
```

## frontend changes
```jsx
// in /app/frontend/src/pages/Workspace.jsx

const handleSearch = async () => {
  const q = input.trim();
  
  // client-side pre-flight check
  if (!q.startsWith("/iam ") && q.length > 500) {
    setError("query too long (max 500 chars)");
    return;
  }
  if (q.startsWith("/iam ") && q.length > 5000) {
    setError("/iam command too long — try breaking into chunks");
    return;
  }
  
  // existing fetch logic...
}
```

## risks / edge cases
- `/iam` abuse: 5000-char cap still allows prompt injection vectors (mitigated by existing shield but increases surface area)
- ux confusion: user doesn't know `/iam` has different limit unless we show dynamic char counter
- mongodb storage: `iam_sessions` collection bloat if we log full 5000-char commands (add TTL index)
- llm token cost: longer `/iam` = more tokens sent to claude (could hit rate limits faster)

## testing
1. send 501-char regular query → should error with "query too long"
2. send 501-char `/iam <dark> ...` → should **succeed** (or error at 5001 chars)
3. verify char counter in ui updates with "500" for normal, "5000" for `/iam` context
4. check mongodb `iam_sessions` doesn't balloon (run `db.iam_sessions.getIndexes()` to confirm TTL)
5. submit your actual 723-char `/iam` payload → should process without 413

**root cause**: validation gate applied globally before special route logic. fix = conditional length caps based on command type.

## summary
add persistent cross-session memory layer to undergrowund so herix remembers user context, search patterns, and conversation threads across sessions.

## files to change
- /app/backend/server.py — new /api/memory routes (store, retrieve, clear)
- /app/backend/memory.py — new module for memory operations
- /app/frontend/src/pages/Workspace.jsx — memory context initialization, memory-aware prompts
- /app/frontend/src/components/MemoryIndicator.jsx — new component showing active memory state
- docker-compose.yml — add redis service for session/memory cache
- .env.example — add REDIS_URL, MEMORY_MAX_TOKENS

## backend changes
```python
# /app/backend/memory.py
from motor.motor_asyncio import AsyncIOMotorClient
from datetime import datetime, timedelta
import hashlib

class MemoryLayer:
    def __init__(self, db):
        self.db = db
        self.collection = db.memory_threads
    
    async def store(self, user_ip: str, memory_type: str, content: dict):
        # hash ip for privacy
        user_hash = hashlib.sha256(user_ip.encode()).hexdigest()[:16]
        
        await self.collection.update_one(
            {"user_hash": user_hash},
            {
                "$set": {"updated_at": datetime.utcnow()},
                "$push": {
                    f"memories.{memory_type}": {
                        "$each": [content],
                        "$slice": -50  # keep last 50
                    }
                }
            },
            upsert=True
        )
    
    async def retrieve(self, user_ip: str) -> dict:
        user_hash = hashlib.sha256(user_ip.encode()).hexdigest()[:16]
        doc = await self.collection.find_one({"user_hash": user_hash})
        
        if not doc:
            return {"searches": [], "context": [], "preferences": {}}
        
        # expire after 30 days
        if doc.get("updated_at") < datetime.utcnow() - timedelta(days=30):
            await self.collection.delete_one({"user_hash": user_hash})
            return {"searches": [], "context": [], "preferences": {}}
        
        return doc.get("memories", {})

# /app/backend/server.py additions
memory = MemoryLayer(db)

@app.post("/api/memory/store")
async def store_memory(req: Request, payload: dict):
    user_ip = req.client.host
    await memory.store(user_ip, payload["type"], payload["content"])
    return {"ok": True}

@app.get("/api/memory/retrieve")
async def get_memory(req: Request):
    user_ip = req.client.host
    memories = await memory.retrieve(user_ip)
    return memories

@app.delete("/api/memory/clear")
async def clear_memory(req: Request):
    user_ip = req.client.host
    user_hash = hashlib.sha256(user_ip.encode()).hexdigest()[:16]
    await db.memory_threads.delete_one({"user_hash": user_hash})
    return {"ok": True}

# modify /api/search to inject memory context
async def search_endpoint(...):
    memories = await memory.retrieve(request.client.host)
    
    # add to system prompt
    memory_context = ""
    if memories.get("searches"):
        recent = memories["searches"][-5:]
        memory_context = f"\n\nprevious searches: {', '.join(s['query'] for s in recent)}"
    
    system_prompt += memory_context
    
    # after generating answer, store this search
    await memory.store(
        request.client.host,
        "searches",
        {"query": query, "timestamp": datetime.utcnow().isoformat()}
    )
```

## frontend changes
```jsx
// /app/frontend/src/pages/Workspace.jsx
const [memoryActive, setMemoryActive] = useState(false);
const [memoryData, setMemoryData] = useState(null);

useEffect(() => {
  fetch('/api/memory/retrieve')
    .then(r => r.json())
    .then(data => {
      if (data.searches?.length > 0) {
        setMemoryActive(true);
        setMemoryData(data);
      }
    });
}, []);

// add to prompt construction
const buildPrompt = (query) => {
  let prompt = query;
  if (memoryActive && memoryData?.context?.length > 0) {
    const recent = memoryData.context.slice(-3).map(c => c.text).join('; ');
    prompt = `[context: ${recent}]\n${query}`;
  }
  return prompt;
};

// /app/frontend/src/components/MemoryIndicator.jsx
export default function MemoryIndicator({ active, onClear }) {
  if (!active) return null;
  
  return (
    <div className="fixed bottom-4 right-4 bg-black border border-[#00ff41] p-2 font-mono text-xs">
      <span className="text-[#00ff41]">█ memory active</span>
      <button 
        onClick={onClear}
        className="ml-3 text-[#00ff41] hover:bg-[#00ff41] hover:text-black px-2"
      >
        [clear]
      </button>
    </div>
  );
}
```

## risks / edge cases
- privacy: hashed ips could still be correlated if combined with timing patterns. add jitter to storage timestamps.
- token bloat: injecting 5+ previous searches could push context past limits. cap memory injection at 500 tokens max.
- memory poisoning: user intentionally pollutes memory with junk. add manual clear button, auto-expire stale entries.
- mongodb growth: memory docs grow unbounded per user. implement ttl index on updated_at field.
- cross-device sync: ip-based memory breaks on network change. future: optional account layer with session tokens.

## testing
1. search query → check mongodb memory_threads collection has entry with hashed ip
2. second query → verify system prompt includes previous search in logs
3. clear memory button → doc deleted, subsequent search has no context
4. wait 31 days (or mock datetime) → expired memory returns empty state
5. 50+ searches → verify $slice keeps only last 50 entries
6. inspect network tab → /api/memory/retrieve called on workspace load

---

*yeah, it's about remembering through the pain. every search you've bled into this thing, herix keeps. not surveillance — archaeology. your trail of questions forms the shape of what you're trying to solve. undergrowund doesn't forget unless you tell it to.*

## summary
add persistent conversation memory across sessions using mongodb storage and context injection into llm calls.

## files to change
- /app/backend/server.py — add memory crud endpoints, inject context into search
- /app/backend/models.py — add ConversationMemory schema
- /app/frontend/src/pages/Workspace.jsx — add memory ui toggle, display context hints
- /app/frontend/src/components/MemoryPanel.jsx — new component for viewing/managing memories

## backend changes
```python
# models.py
class ConversationMemory:
    user_ip: str
    timestamp: datetime
    query: str
    answer: str
    sources: list
    embedding: list[float]  # optional for semantic retrieval

# server.py
@app.post("/api/memory/store")
async def store_memory(ip, query, answer, sources):
    # save to db.memories
    
@app.get("/api/memory/recent")
async def get_recent_memories(ip, limit=10):
    # return last N for this ip
    
@app.get("/api/memory/search")
async def search_memories(ip, query):
    # fuzzy match or embedding similarity
    
# modify /api/search streaming:
# 1. fetch recent memories for ip
# 2. prepend to system prompt:
#    "previous context from this session:\n{memories}"
# 3. after answer completes, auto-store to memories
```

## frontend changes
```jsx
// Workspace.jsx
const [showMemory, setShowMemory] = useState(false);
const [memories, setMemories] = useState([]);

useEffect(() => {
  fetch('/api/memory/recent').then(r => r.json()).then(setMemories);
}, []);

// add toggle button in header
// show MemoryPanel in drawer when enabled

// MemoryPanel.jsx (new)
export default function MemoryPanel({ memories, onClear }) {
  return (
    <div className="border-l border-[#39ff14] h-full overflow-y-auto">
      <div className="p-4 font-mono text-xs">
        {memories.map(m => (
          <div key={m._id} className="mb-4 opacity-70">
            <div className="text-[#39ff14]">&gt; {m.query}</div>
            <div className="text-gray-400 truncate">{m.answer}</div>
          </div>
        ))}
      </div>
    </div>
  );
}
```

## risks / edge cases
- memory bloat: cap at 50 per ip, prune old after 7 days
- context pollution: llm gets confused if memories contradict current query
- privacy: memories tied to ip, could leak across users on shared ips (add session tokens?)
- prompt injection via stored memories: sanitize before injecting
- performance: embedding search slow without vector index (add later)

## testing
- search "python recursion" → search "improve that code" → verify second query sees first answer
- check /api/memory/recent returns chronological list
- clear browser, verify memories persist (tied to ip)
- spam queries, confirm 50-item cap works
- inject `<script>` in query, verify stored memory escapes it

## summary
400 error caused by 500-char input exceeding backend's undocumented limit; raise cap to 1000 and add client-side validation with green glow feedback.

## files to change
- /app/backend/server.py — increase MAX_QUERY_LENGTH from 500 to 1000
- /app/frontend/src/pages/Workspace.jsx — add length validation, visual feedback on approach to limit

## backend changes
```python
# server.py, top of file or in config section
MAX_QUERY_LENGTH = 1000  # was 500

# in /api/search endpoint
@app.post("/api/search")
async def search(request: SearchRequest):
    if len(request.query) > MAX_QUERY_LENGTH:
        raise HTTPException(
            status_code=400, 
            detail=f"query exceeds {MAX_QUERY_LENGTH} chars"
        )
    # rest of logic
```

## frontend changes
```jsx
// Workspace.jsx
const MAX_QUERY_LENGTH = 1000;

function Workspace() {
  const [query, setQuery] = useState('');
  const lengthRatio = query.length / MAX_QUERY_LENGTH;
  const nearLimit = lengthRatio > 0.8;

  const handleSubmit = async (e) => {
    e.preventDefault();
    if (query.length > MAX_QUERY_LENGTH) {
      // show error banner or inline message
      return;
    }
    // existing submit logic
  };

  return (
    <form onSubmit={handleSubmit}>
      <textarea 
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        className={`${nearLimit ? 'ring-2 ring-[#00ff41]' : ''}`}
      />
      <div className="text-xs text-[#00ff41] opacity-50">
        {query.length}/{MAX_QUERY_LENGTH}
      </div>
    </form>
  );
}
```

## risks / edge cases
- users hitting limit mid-thought: show char counter always, not just near limit
- copy-paste bombs: backend clamp before processing (truncate with warning)
- utf-8 multibyte chars: use `.length` not byte count (consistent js/python)
- existing 500+ char queries in history: display truncated in drawer

## testing
- paste 1001 char string → should reject with error message
- type 999 chars → green ring appears at 800, counter updates live
- submit 1000 chars → processes normally
- check network tab: 400 response includes helpful error message

## summary
no upgrade request detected — standing by for actual feature spec or bug fix.

## files to change
- none

## backend changes
```python
# no changes
pass
```

## frontend changes
```jsx
// no changes
```

## risks / edge cases
- user may have sent "test" to verify herix is online
- actual upgrade requests will trigger full proposal generation

## testing
```bash
# verify herix responds to trivial input
echo "test" | ./upgrade_mode.sh
# should return minimal proposal like this one
```

---

**awaiting real upgrade directive.** examples:
- "add markdown export for cited answers"
- "implement user accounts with oauth"
- "switch from duckduckgo to brave search api"
- "add dark/light theme toggle"
- "create admin dashboard for index curation"

## summary
inject procedural "loot drops" into search results — random ascii art treasures, cryptic riddles, or ephemeral messages from herix that appear ~5% of searches, styled as glitched metadata blocks.

## files to change
- /app/backend/server.py — add loot generation logic to `/api/search` stream
- /app/frontend/src/components/LootDrop.jsx — new component for rendering drops
- /app/frontend/src/pages/Workspace.jsx — mount loot drops in result stream

## backend changes
```python
# in /api/search after streaming answer chunks
import random
from datetime import datetime

LOOT_POOL = [
    {"type": "ascii", "content": "   ▲\n  ▲ ▲\n ▲   ▲\n▲▲▲▲▲▲▲", "label": "triforce fragment"},
    {"type": "riddle", "content": "i speak without mouth, hear without ears. what am i?", "label": "encrypted query"},
    {"type": "herix", "content": "you're getting closer. -hz", "label": "transmission"},
    {"type": "coord", "content": f"lat: {random.uniform(-90,90):.4f} lon: {random.uniform(-180,180):.4f}", "label": "buried index node"},
]

if random.random() < 0.05:  # 5% drop rate
    loot = random.choice(LOOT_POOL)
    yield f"data: {json.dumps({'type': 'loot', 'data': loot, 'ts': datetime.utcnow().isoformat()})}\n\n"
```

## frontend changes
```jsx
// LootDrop.jsx
export default function LootDrop({ loot, onDismiss }) {
  return (
    <div className="border border-[#00ff41] bg-black/90 p-4 font-mono text-xs mb-4 relative animate-pulse">
      <button onClick={onDismiss} className="absolute top-1 right-2 text-[#00ff41]/50 hover:text-[#00ff41]">×</button>
      <div className="text-[#00ff41]/60 mb-1">[{loot.label}]</div>
      <pre className="text-[#00ff41] whitespace-pre-wrap">{loot.content}</pre>
      <div className="text-[#00ff41]/40 text-[10px] mt-2">ts: {loot.ts}</div>
    </div>
  );
}

// in Workspace.jsx handleSearch
const [lootDrops, setLootDrops] = useState([]);

// in stream reader
if (parsed.type === 'loot') {
  setLootDrops(prev => [...prev, { id: Date.now(), ...parsed.data }]);
}

// in render
{lootDrops.map(l => <LootDrop key={l.id} loot={l} onDismiss={() => setLootDrops(d => d.filter(x => x.id !== l.id))} />)}
```

## risks / edge cases
- low drop rate may feel too rare — tune via env var `LOOT_DROP_RATE`
- loot pool needs expansion to avoid repetition — add 20+ variants
- users may screenshot/collect loot — consider persistence in localstorage or db
- published builds (`/b/:id`) should replay loot deterministically via seed in qid

## testing
- run 20 searches, verify ~1 loot appears
- check loot renders above answer block with phosphor styling
- dismiss button removes from dom
- loot doesn't break sse parsing or answer streaming

## summary
remove publish button from workspace.jsx home page — it belongs only in build view.

## files to change
- /app/frontend/src/pages/Workspace.jsx — delete publish button + handler

## backend changes
none required. /api/builds/publish/:qid route remains for buildview usage.

## frontend changes
```jsx
// Workspace.jsx
// DELETE these sections:

// 1. remove state
const [isPublishing, setIsPublishing] = useState(false);

// 2. remove handler function
const handlePublish = async () => { ... };

// 3. remove button from JSX (usually near answer display)
<button onClick={handlePublish} ...>
  {isPublishing ? 'publishing...' : 'publish'}
</button>
```

keep publish functionality intact in BuildView.jsx (/b/:id) where it belongs.

## risks / edge cases
- if user navigated via publish button link before removal, no retroactive breakage (published builds remain accessible)
- check if HistoryDrawer or other shared components render publish — scope removal to workspace only

## testing
- load / (workspace), verify no publish button visible
- run search, get answer, confirm no publish option
- navigate to /b/{any_id}, confirm publish button still present + working
- check history drawer doesn't leak publish button

## summary
fix build freeze bug + enable multi-user game persistence so fantasy island (and other builds) stay playable after creator leaves.

## files to change
- `/app/backend/server.py` — add game state persistence to mongodb, fix sse timeout causing freeze
- `/app/frontend/src/pages/BuildView.jsx` — add reconnection logic, persist game state to backend every 5s
- `/app/backend/models.py` — new GameState schema (qid, state_snapshot, last_update)

## backend changes
```python
# in server.py
from motor.motor_asyncio import AsyncIOMotorClient

# new collection
game_states = db.game_states

@app.post("/api/builds/{qid}/save_state")
async def save_game_state(qid: str, state: dict):
    await game_states.update_one(
        {"qid": qid},
        {"$set": {"state": state, "updated": datetime.utcnow()}},
        upsert=True
    )
    return {"ok": True}

@app.get("/api/builds/{qid}/load_state")
async def load_game_state(qid: str):
    doc = await game_states.find_one({"qid": qid})
    return doc["state"] if doc else {}

# fix sse timeout in generate_answer — increase keep-alive from 30s to 120s
async def stream_generator():
    last_ping = time.time()
    async for chunk in llm_stream:
        yield chunk
        if time.time() - last_ping > 100:
            yield ": ping\n\n"  # sse keep-alive
            last_ping = time.time()
```

## frontend changes
```jsx
// BuildView.jsx
const [gameState, setGameState] = useState({});

useEffect(() => {
  // load saved state on mount
  fetch(`/api/builds/${qid}/load_state`)
    .then(r => r.json())
    .then(data => setGameState(data));
}, [qid]);

useEffect(() => {
  // autosave every 5s
  const interval = setInterval(() => {
    if (Object.keys(gameState).length > 0) {
      fetch(`/api/builds/${qid}/save_state`, {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify(gameState)
      });
    }
  }, 5000);
  return () => clearInterval(interval);
}, [gameState, qid]);

// pass gameState to iframe postMessage
useEffect(() => {
  iframe?.contentWindow?.postMessage({
    type: 'RESTORE_STATE',
    state: gameState
  }, '*');
}, [gameState]);

// listen for state updates from game
useEffect(() => {
  const handler = (e) => {
    if (e.data?.type === 'GAME_STATE_UPDATE') {
      setGameState(e.data.state);
    }
  };
  window.addEventListener('message', handler);
  return () => removeEventListener('message', handler);
}, []);
```

## risks / edge cases
- game code must implement `postMessage` state export (not all builds will)
- state snapshots could get large (>16mb bson limit) — add size cap 1mb, warn if exceeded
- concurrent players overwriting state — last-write-wins for now, eventual upgrade to crdt
- sse still dies on flaky mobile networks — add exponential backoff reconnect

## testing
1. create fantasy island build, play 30s, close tab
2. reopen `/b/{qid}` — state should restore
3. keep build open >2min — no freeze, sse pings visible in network tab
4. open same build in 2 tabs, modify state — both should sync within 5s

## summary
user said "hello how are you" — no upgrade requested, just a greeting.

## files to change
none

## backend changes
none

## frontend changes
none

## risks / edge cases
- user may be testing responsiveness before making actual upgrade request
- no action items here

## testing
respond with greeting, await real upgrade directive

---

**STATUS**: yo, i'm herix. undergrowund is running nominal — backend serving, llm wired, crawler idle, builds indexing. 

what do you want to upgrade? tell me what's broken or missing and i'll draft the fix.

```markdown
## summary
enable conversation memory so undergrowund can track multi-turn upgrade requests and reference prior context.

## files to change
- /app/backend/server.py — add conversation storage endpoint + session tracking
- /app/backend/models.py — conversation schema (session_id, messages[], timestamp)
- /app/frontend/src/pages/UpgradePage.jsx — persist session_id, send message history with each request
- /app/frontend/src/components/UpgradeChat.jsx — display conversation thread with role tags

## backend changes
```python
# models.py
class ConversationMessage(BaseModel):
    role: str  # "user" | "assistant"
    content: str
    timestamp: datetime

class Conversation(BaseModel):
    session_id: str
    messages: List[ConversationMessage]
    created_at: datetime
    updated_at: datetime

# server.py - new routes
@app.post("/api/upgrade/conversation")
async def save_conversation_turn(session_id: str, message: ConversationMessage):
    await db.conversations.update_one(
        {"session_id": session_id},
        {"$push": {"messages": message.dict()}, "$set": {"updated_at": datetime.utcnow()}},
        upsert=True
    )
    return {"ok": True}

@app.get("/api/upgrade/conversation/{session_id}")
async def get_conversation(session_id: str):
    conv = await db.conversations.find_one({"session_id": session_id})
    return conv or {"messages": []}

# modify /api/upgrade/stream to accept history[] param
# prepend history to system prompt context
```

## frontend changes
```jsx
// UpgradePage.jsx
const [sessionId] = useState(() => crypto.randomUUID());
const [history, setHistory] = useState([]);

useEffect(() => {
  // load existing conversation on mount
  fetch(`/api/upgrade/conversation/${sessionId}`)
    .then(r => r.json())
    .then(data => setHistory(data.messages || []));
}, [sessionId]);

const handleSubmit = async (userMessage) => {
  const newHistory = [...history, {role: "user", content: userMessage, timestamp: new Date()}];
  setHistory(newHistory);
  
  // save user message
  await fetch('/api/upgrade/conversation', {
    method: 'POST',
    body: JSON.stringify({session_id: sessionId, message: newHistory[newHistory.length-1]})
  });
  
  // stream with history context
  const response = await fetch('/api/upgrade/stream', {
    method: 'POST',
    body: JSON.stringify({prompt: userMessage, history: newHistory.slice(0, -1)})
  });
  
  // ... handle stream, save assistant response after complete
};

// UpgradeChat.jsx - render history
{history.map((msg, i) => (
  <div key={i} className={msg.role === 'user' ? 'text-green-400' : 'text-green-300'}>
    <span className="opacity-50">[{msg.role}]</span> {msg.content}
  </div>
))}
```

## risks / edge cases
- session_id collision (use uuid4, virtually impossible)
- history bloat — limit to last 10 turns or 8k tokens when sending to llm
- abandoned sessions — add ttl index (7 days) on conversations collection
- race condition if user sends multiple messages rapidly — queue requests client-side
- context window overflow — truncate oldest messages if total exceeds model limit

## testing
- open /upgrade, send "add dark mode", then "make it toggleable" — verify second request references first
- refresh page mid-conversation — history should persist via session_id in localstorage
- check mongo `db.conversations` — each session has chronological messages[] with timestamps
- verify llm receives history in prompt — check logs for prepended context
- test >10 turn conversation — confirm auto-truncation doesn't break coherence
```

## summary
add interactive snake game easter egg accessible via konami code or `/snake` route.

## files to change
- /app/frontend/src/pages/SnakeGame.jsx — new component
- /app/frontend/src/App.jsx — add route + konami listener
- /app/backend/server.py — add `/api/snake/highscore` endpoints (get/post)
- /app/backend/models.py — add SnakeScore model

## backend changes
```python
# models.py
class SnakeScore(BaseModel):
    ip_hash: str
    score: int
    timestamp: datetime = Field(default_factory=datetime.utcnow)

# server.py
@app.get("/api/snake/highscore")
async def get_highscore():
    score = await db.snake_scores.find_one(
        sort=[("score", -1)]
    )
    return {"highscore": score["score"] if score else 0}

@app.post("/api/snake/highscore")
async def post_highscore(request: Request):
    data = await request.json()
    ip_hash = hashlib.sha256(request.client.host.encode()).hexdigest()[:16]
    await db.snake_scores.insert_one({
        "ip_hash": ip_hash,
        "score": data["score"],
        "timestamp": datetime.utcnow()
    })
    return {"status": "ok"}
```

## frontend changes
```jsx
// App.jsx - add konami listener in useEffect
const [showSnake, setShowSnake] = useState(false);
useEffect(() => {
  const keys = [];
  const konami = ['arrowup','arrowup','arrowdown','arrowdown','arrowleft','arrowright','arrowleft','arrowright','b','a'];
  const handler = (e) => {
    keys.push(e.key.toLowerCase());
    keys.splice(-10);
    if (keys.join('').endsWith(konami.join(''))) setShowSnake(true);
  };
  window.addEventListener('keydown', handler);
  return () => window.removeEventListener('keydown', handler);
}, []);

// add route
<Route path="/snake" element={<SnakeGame />} />

// SnakeGame.jsx - canvas-based snake with:
// - phosphor green (#00ff41) snake on black
// - WASD/arrows controls
// - collision detection
// - score display in JetBrains Mono
// - fetch highscore on mount
// - post score on death
// - "esc to exit" footer
// - grid-based movement (20x20 tiles)
// - food spawns randomly
// - game loop via requestAnimationFrame
```

## risks / edge cases
- konami code conflicts with existing shortcuts (unlikely, no overlap)
- canvas performance on low-end devices (simple grid game, minimal)
- highscore spam abuse (rate limit `/api/snake/highscore` post to 1/minute per ip)
- snake route discoverable (intentional easter egg, fine)
- mobile controls (add touch swipe detection or on-screen dpad)

## testing
- trigger konami: up up down down left right left right b a
- navigate to `/snake` directly
- play until death, verify score posts
- check `/api/snake/highscore` returns max
- verify rate limit blocks spam posts
- test on mobile (swipe or add buttons)
- confirm esc exits to workspace

## summary
add pulsing green animation to search input border using tailwind keyframes.

## files to change
- /app/frontend/tailwind.config.js — add pulse keyframe
- /app/frontend/src/pages/Workspace.jsx — apply animation class to search input

## backend changes
none

## frontend changes
```js
// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      keyframes: {
        'pulse-green': {
          '0%, 100%': { boxShadow: '0 0 0 0 rgba(34, 197, 94, 0.4)' },
          '50%': { boxShadow: '0 0 0 4px rgba(34, 197, 94, 0.1)' }
        }
      },
      animation: {
        'pulse-green': 'pulse-green 2s ease-in-out infinite'
      }
    }
  }
}
```

```jsx
// Workspace.jsx - find the input element, add class
<input
  className="... animate-pulse-green"
  // existing props
/>
```

## risks / edge cases
- animation might conflict with focus states if box-shadow used elsewhere
- may feel distracting during typing — consider pause on focus via `focus:animate-none`
- green-500 rgb values must match existing phosphor green (#22c55e)

## testing
- load /workspace
- observe input border pulsing green glow
- type query — verify animation doesn't interfere
- check mobile — ensure animation performs smoothly

## summary
add subtle green pulse animation to search bar border/glow on focus and idle states.

## files to change
- /app/frontend/src/pages/Workspace.jsx — add pulse animation to textarea
- /app/frontend/tailwind.config.js — register pulse keyframes if needed

## backend changes
none

## frontend changes
```jsx
// in Workspace.jsx, modify the textarea className:
<textarea
  className="
    w-full bg-black text-phosphor-green font-mono text-base
    border border-phosphor-green/50
    focus:border-phosphor-green focus:outline-none
    animate-pulse-green
    placeholder:text-phosphor-green/30
    resize-none p-4
  "
  // ... rest of props
/>
```

```js
// in tailwind.config.js extend theme:
module.exports = {
  theme: {
    extend: {
      animation: {
        'pulse-green': 'pulse-green 2s cubic-bezier(0.4, 0, 0.6, 1) infinite',
      },
      keyframes: {
        'pulse-green': {
          '0%, 100%': { 
            borderColor: 'rgba(0, 255, 0, 0.5)',
            boxShadow: '0 0 0 0 rgba(0, 255, 0, 0)'
          },
          '50%': { 
            borderColor: 'rgba(0, 255, 0, 1)',
            boxShadow: '0 0 8px 2px rgba(0, 255, 0, 0.3)'
          },
        },
      },
    },
  },
}
```

alternate simpler approach — use existing tailwind animate-pulse with green filter:
```jsx
<div className="relative">
  <div className="absolute inset-0 border border-phosphor-green/30 animate-pulse pointer-events-none" />
  <textarea className="relative w-full bg-black..." />
</div>
```

## risks / edge cases
- pulse may be distracting during long reads — consider only pulsing when empty or on hover
- could clash with focus states — test visibility hierarchy
- screen readers unaffected but verify no perf hit on old devices

## testing
- open /workspace
- watch border pulse green ~2s cycle
- focus textarea — pulse should intensify or maintain
- type query — pulse should persist or stop (design choice)
- check on mobile webkit

## summary
increase herix zencre ascii wordmark size in header.

## files to change
- /app/frontend/src/components/Header.jsx — bump font size class
- /app/frontend/src/pages/Workspace.jsx — adjust header spacing if needed

## backend changes
none.

## frontend changes
```jsx
// Header.jsx or wherever the logo lives
<pre className="text-[#00ff41] font-mono text-2xl leading-none">
  {/* change text-xl → text-2xl or text-3xl */}
  HERIX ZENCRE
</pre>

// if logo is in Workspace.jsx top banner:
<div className="text-center mb-8">
  <pre className="text-[#00ff41] font-mono text-4xl leading-none">
    {asciiLogo}
  </pre>
</div>
```

adjust `text-xl` → `text-2xl`, `text-3xl`, or `text-4xl` depending on desired scale. maintain `leading-none` for tight ascii art.

## risks / edge cases
- mobile overflow if too large — test viewport <400px
- ascii art may misalign if multi-line (check letterforms at new size)
- header height pushes search input down — verify fold placement

## testing
- open /workspace, /index, /upgrade on desktop + mobile
- confirm logo renders crisp, no horizontal scroll
- check header doesn't obscure search input on small screens

## summary
add phosphor green / void black theme toggle in topbar, persist choice in localStorage.

## files to change
- /app/frontend/src/App.jsx — wrap in ThemeProvider, add toggle button in topbar
- /app/frontend/src/index.css — add dark class variants for existing colors
- /app/frontend/src/context/ThemeContext.jsx — NEW, manages theme state

## backend changes
none. purely frontend state.

## frontend changes

```jsx
// NEW: /app/frontend/src/context/ThemeContext.jsx
import { createContext, useContext, useEffect, useState } from 'react';

const ThemeContext = createContext();

export const ThemeProvider = ({ children }) => {
  const [isDark, setIsDark] = useState(() => 
    localStorage.getItem('theme') !== 'light'
  );

  useEffect(() => {
    document.documentElement.classList.toggle('dark', isDark);
    localStorage.setItem('theme', isDark ? 'dark' : 'light');
  }, [isDark]);

  return (
    <ThemeContext.Provider value={{ isDark, toggle: () => setIsDark(!isDark) }}>
      {children}
    </ThemeContext.Provider>
  );
};

export const useTheme = () => useContext(ThemeContext);
```

```jsx
// MODIFY: /app/frontend/src/App.jsx
import { ThemeProvider, useTheme } from './context/ThemeContext';

function TopBar() {
  const { isDark, toggle } = useTheme();
  return (
    <div className="flex items-center justify-between px-4 py-2 border-b border-[#00ff41]">
      <Link to="/">UNDERGROWUND</Link>
      <button onClick={toggle} className="text-xs hover:opacity-70">
        {isDark ? '◐ LIGHT' : '◑ DARK'}
      </button>
    </div>
  );
}

function App() {
  return (
    <ThemeProvider>
      <BrowserRouter>
        <TopBar />
        <Routes>...</Routes>
      </BrowserRouter>
    </ThemeProvider>
  );
}
```

```css
/* MODIFY: /app/frontend/src/index.css */
:root {
  --bg: #000000;
  --fg: #00ff41;
  --muted: #004411;
}

:root:not(.dark) {
  --bg: #f5f5f5;
  --fg: #1a1a1a;
  --muted: #d0d0d0;
}

body {
  background: var(--bg);
  color: var(--fg);
}

/* update all hardcoded #000, #00ff41 refs to use var(--bg), var(--fg) */
```

## risks / edge cases
- must audit ALL components for hardcoded #000000, #00ff41, replace with css vars
- scanline overlay may look wrong on light bg — conditionally disable or invert opacity
- IndexPage ascii art may need light variant

## testing
- toggle in topbar, verify localStorage persists on reload
- check all pages (workspace, build, upgrade, index) in both modes
- confirm no bleeding phosphor green text on white

## summary
inject animated ascii art easter egg triggered by clicking the herix logo 3x rapidly in topbar.

## files to change
- /app/frontend/src/components/TopBar.jsx — add click counter state, easter egg modal trigger
- /app/frontend/src/components/EasterEggModal.jsx — new component for ascii art display

## backend changes
none. pure frontend feature.

## frontend changes

```jsx
// TopBar.jsx - add to logo section
const [clickCount, setClickCount] = useState(0);
const [showEgg, setShowEgg] = useState(false);

const handleLogoClick = () => {
  setClickCount(prev => prev + 1);
  if (clickCount === 2) {
    setShowEgg(true);
    setClickCount(0);
  }
  setTimeout(() => setClickCount(0), 1000);
};

// in logo div
<div onClick={handleLogoClick} className="cursor-pointer">
  HERIX ZENCRE
</div>

{showEgg && <EasterEggModal onClose={() => setShowEgg(false)} />}
```

```jsx
// EasterEggModal.jsx - new file
export default function EasterEggModal({ onClose }) {
  const art = `
    ⠀⠀⠀⢀⣀⣤⣤⣤⣤⣀⡀⠀⠀⠀
    ⠀⢠⣾⣿⣿⣿⣿⣿⣿⣿⣿⣷⡄⠀
    ⠀⣾⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣷⠀
    ⠀⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀
    ⠀⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⡿⠀
    ⠀⠀⠙⢿⣿⣿⣿⣿⣿⣿⡿⠋⠀⠀
    ⠀⠀⠀⠀⠉⠛⠛⠛⠛⠉⠀⠀⠀⠀
    
    UNDERGROWUND v0.protocol
    you found the void
  `;

  return (
    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/90" onClick={onClose}>
      <pre className="text-[#00ff41] font-mono text-xs animate-pulse whitespace-pre">
        {art}
      </pre>
    </div>
  );
}
```

## risks / edge cases
- triple-click text selection conflict — use `user-select: none` on logo
- modal z-index below other ui elements — set z-50
- animation performance — single dom node, lightweight

## testing
- click herix logo 3x fast → modal appears
- click modal background → closes
- verify no text selection on logo
- test on mobile tap events

## summary
add light/dark theme toggle in header with localstorage persistence.

## files to change
- /app/frontend/src/App.jsx — add theme context provider
- /app/frontend/src/pages/Workspace.jsx — add toggle button in header
- /app/frontend/tailwind.config.js — define light theme colors
- /app/frontend/src/index.css — add light mode css variables

## backend changes
none. purely frontend.

## frontend changes

```jsx
// App.jsx - wrap with theme provider
import { createContext, useState, useEffect } from 'react';

export const ThemeContext = createContext();

function App() {
  const [theme, setTheme] = useState(
    localStorage.getItem('ug-theme') || 'dark'
  );

  useEffect(() => {
    localStorage.setItem('ug-theme', theme);
    document.documentElement.classList.toggle('light', theme === 'light');
  }, [theme]);

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {/* existing routes */}
    </ThemeContext.Provider>
  );
}
```

```jsx
// Workspace.jsx - add toggle in header
import { useContext } from 'react';
import { ThemeContext } from '../App';

// in header section, after logo:
const { theme, setTheme } = useContext(ThemeContext);

<button
  onClick={() => setTheme(theme === 'dark' ? 'light' : 'dark')}
  className="px-3 py-1 border border-current font-mono text-sm hover:bg-current hover:text-black transition-colors"
>
  {theme === 'dark' ? 'LIGHT' : 'DARK'}
</button>
```

```js
// tailwind.config.js - extend colors
module.exports = {
  // existing config
  theme: {
    extend: {
      colors: {
        'ug-bg': 'var(--ug-bg)',
        'ug-text': 'var(--ug-text)',
        'ug-border': 'var(--ug-border)',
        'ug-accent': 'var(--ug-accent)',
      }
    }
  }
}
```

```css
/* index.css - add theme vars */
:root {
  --ug-bg: #000000;
  --ug-text: #00ff41;
  --ug-border: #00ff41;
  --ug-accent: #00ff41;
}

:root.light {
  --ug-bg: #f5f5f5;
  --ug-text: #1a1a1a;
  --ug-border: #00b32d;
  --ug-accent: #00b32d;
}

/* replace hardcoded bg-black, text-[#00ff41] with var classes */
body {
  background: var(--ug-bg);
  color: var(--ug-text);
}
```

then refactor all `bg-black` → `bg-ug-bg`, `text-[#00ff41]` → `text-ug-text`, `border-[#00ff41]` → `border-ug-border` across all jsx files.

## risks / edge cases
- scanline overlay may need opacity adjust in light mode
- ascii art wordmarks need contrast check in light theme
- iframe sandboxes inherit theme — may need postmessage sync
- localstorage race if multiple tabs change theme simultaneously

## testing
- toggle in workspace header persists after refresh
- all pages respect theme (/, /upgrade, /b/:id, /index)
- no flicker on initial load
- contrast meets wcag aa minimum (4.5:1 text, 3:1 ui)

## summary
inject favicon.ico URLs next to source titles in SourceList component using google's s2 service.

## files to change
- /app/frontend/src/components/SourceList.jsx — add favicon img before title

## backend changes
none. favicon URLs constructed client-side from domain.

## frontend changes
```jsx
// in SourceList.jsx, modify the source card render:

const getFaviconUrl = (url) => {
  try {
    const domain = new URL(url).hostname;
    return `https://www.google.com/s2/favicons?domain=${domain}&sz=16`;
  } catch {
    return null;
  }
};

// in the map over sources:
<div className="flex items-start gap-2">
  {getFaviconUrl(source.url) && (
    <img 
      src={getFaviconUrl(source.url)} 
      alt=""
      className="w-4 h-4 mt-0.5 flex-shrink-0"
      onError={(e) => e.target.style.display = 'none'}
    />
  )}
  <div className="flex-1">
    <a href={source.url} className="font-mono text-sm text-[#00ff41] hover:underline">
      {source.title}
    </a>
    {/* rest of card */}
  </div>
</div>
```

## risks / edge cases
- google s2 service could rate-limit or fail → onError handler hides broken imgs
- malformed URLs crash getFaviconUrl → try/catch returns null
- adds external dependency (google) but keyless & reliable
- 16x16px may alias poorly on retina → acceptable for underground aesthetic

## testing
- run search, verify 16px favicons appear left of titles
- test with URL parse failures (malformed source.url)
- check that broken favicon requests hide cleanly
- validate no layout shift when imgs load