// SELF.UPGRADE()

## 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