docs: add needs overhaul design (food, thirst, productivity visibility)

Berry bushes as gatherable food, thirst need consuming water items,
productivity bar on status tab, desperate forage goal, remove magic
food POIs.

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

docs/plans/2026-03-10-needs-food-thirst-design.md

@@ -0,0 +1,118 @@
+# Needs Overhaul: Food, Thirst & Productivity Visibility
+
+**Date**: 2026-03-10
+**Status**: Approved
+
+## Overview
+
+Three related changes to the NPC needs system:
+1. Berry bushes as a gatherable food resource (replacing magic food POIs)
+2. Thirst as a new need consuming water items
+3. Productivity bar visible on the Status tab
+
+## Berry Bushes & Food Resource
+
+**Terrain feature:**
+- 3-5 clusters of 2-4 berry bushes placed during map generation (like stone/tree clusters)
+- Each bush is an obstacle tile with `resourceType: 'berries'` gather point
+- Placeholder visual (colored circle) until proper sprite is added
+
+**Depletion & regrowth:**
+- Each bush has `berryCount` starting at max capacity (5)
+- Gathering depletes 1 berry per gather action
+- When depleted (0), gathering fails — NPC moves to next bush
+- Regrowth: +1 berry every 200 ticks until back at max
+- Bush state persists across save/load
+
+**New seed item:** `berries` (category: `resource`)
+
+**Cleanup:** Remove food POI generation and food POI pathfinding entirely.
+
+## Thirst Need
+
+**Mechanics (mirrors hunger):**
+- Range: 0-100
+- Decay: 0.05/tick (same as hunger)
+- Constitution modifier: `1 - (CON - 10) * 0.03`
+- Half rate during sleep
+- Threshold: 30 — triggers `drink` goal
+- Stat penalties when low (same pattern as hunger in statModifierSystem)
+
+**Drinking:**
+- Consume 1 `water` item → gain +20 thirst
+- Check own inventory first, then pathfind to nearest stockpile with water
+- If no water anywhere, trigger desperate `forage` goal targeting water tiles
+
+**Wire protocol:** Add `thirst` to `Needs` interface in shared types.
+
+## Hunger Rework
+
+**Replace magic food POI recharge with item consumption:**
+- Consume 1 `berries` item → gain +20 hunger
+- Check own inventory first, then pathfind to nearest stockpile with berries
+- If no berries anywhere, trigger desperate `forage` goal targeting berry bushes
+
+**Remove:** Food POI pathfinding, free hunger recharge, `food` POI type.
+
+## Desperate Forage Goal
+
+When an NPC is hungry/thirsty but has no items and stockpiles are empty:
+- New goal: `forage` — survival-priority gathering
+- Pathfind to nearest berry bush (if hungry) or water tile (if thirsty)
+- Gather then immediately consume
+- Ignores productivity threshold — this is survival
+- If both hungry and thirsty, prioritize whichever is lower
+
+**Updated priority order:**
+1. Sleep (energy < threshold or nighttime)
+2. Eat (hunger < 30, has berries available)
+3. Drink (thirst < 30, has water available)
+4. Forage (hunger < 30 OR thirst < 30, no items available)
+5. Dropoff (at carry capacity)
+6. Gather (productivity < 40)
+7. Wander (default)
+
+## Status Tab UI
+
+**Four bars on the NPC info panel Status tab:**
+1. Hunger
+2. Thirst
+3. Energy
+4. Productivity
+
+All use same color scheme: green (>60), yellow (30-60), red (<30).
+
+## Configuration
+
+New tuning values (externalized for future admin UI):
+
+| Key | Value | Description |
+|-----|-------|-------------|
+| `berryBushMaxCount` | 5 | Berries per bush at full capacity |
+| `berryRegrowthTicks` | 200 | Ticks per berry regrown |
+| `berryBushClusters` | [3, 5] | Min/max clusters on map |
+| `berryBushClusterSize` | [2, 4] | Min/max bushes per cluster |
+| `thirstDecayPerTick` | 0.05 | Thirst decay rate |
+| `thirstThreshold` | 30 | Thirst crisis threshold |
+| `drinkRecovery` | 20 | Thirst gained per water consumed |
+| `eatRecovery` | 20 | Hunger gained per berry consumed |
+
+## Systems Touched
+
+- `shared/src/types.ts` — add `thirst` to Needs, add `drink`/`forage` goal types
+- `shared/src/constants.ts` — thirst defaults
+- `server/src/map/mapGenerator.ts` — berry bush clusters, remove food POIs
+- `server/src/systems/needsDecaySystem.ts` — thirst decay
+- `server/src/systems/npcBrainSystem.ts` — drink/forage goals, consumption logic
+- `server/src/systems/statModifierSystem.ts` — thirst stat penalties
+- `server/src/systems/gatheringSystem.ts` — berry depletion, regrowth tick
+- `server/src/industry/itemRegistry.ts` — berries seed item
+- `server/src/config/` — new tuning values
+- `server/src/persistence/` — berry bush state save/load
+- `client/src/ui/NpcInfoPanel.ts` — thirst + productivity bars
+
+## Out of Scope
+
+- Farming, fishing, hunting systems
+- Invention-to-action bridge (inventions unlocking new behavior types)
+- Berry bush sprite (placeholder for now)