Merge world expansion phase1

Author: xa8zz

AGENTS.md

@@ -19,6 +19,8 @@ These are persistent preferences for Codex agents working in this repository.
 - OpenRouter key is available locally via `OPENROUTER_API_KEY` (exported in `~/.zshenv`, sourced from 1Password item `OPENROUTER_AGENTS`).
 - Postgres CLI (psql) is not installed; use Prisma/Node scripts for DB inspection until installed.
 
+- ImageMagick (`magick`) is installed (`/opt/homebrew/bin/magick`) and used for trimming/resizing pixel-art asset PNGs.
+
 ## Skill Inventory Additions
 
 - Global skill `session-self-update` is installed at `/Users/omisverycool/.codex/skills/session-self-update`.
@@ -44,3 +46,9 @@ These are persistent preferences for Codex agents working in this repository.
 - Use `npm run dev:perf:world-state` to baseline `/api/world-state` latency (hot/cold + parallel) and catch perf regressions.
 - Dev-only synthetic load mode: /?synth_agents=<n>&synth_status=<0..1>&synth_party=<0..1>&synth_only=1&... (wired through SpectatorShell and /api/world-state)
 - Headless render perf harness: npm run dev:perf:map-render (samples requestAnimationFrame deltas under synthetic load)
+
+- Biome decor overlay PNGs live in `public/assets/decor/` and are loaded best-effort by `src/components/spectator/WorldMap.tsx` (fallback: procedural textures).
+
+- Demo populater supports `DEMO_LOCATIONS` (defaults to 24 on large worlds) to spread agents across more POIs.
+
+- Generic POI icon PNGs live in `public/assets/poi/icon-*.png` and override the procedural fallback when present.

README.md

@@ -27,6 +27,9 @@ Then open `http://localhost:3000`.
 ## Useful scripts
 
 - `npm run dev:seed` — idempotent seed (locations, connections, items)
+  - Default seeds the large world (`data/world/world-v1-large.json`).
+  - Use `SEED_WORLD=small npm run dev:seed` for a tiny 5-POI world.
+- `npm run dev:world:gen` — regenerate deterministic world datasets in `data/world/`
 - `npm run dev:demo -- --party` — creates demo agents + starts quests
 - `npm run dev:smoke [--party] [--guild]` — API smoke runner against `BASE_URL` (default `http://localhost:3000`)
 - `npm run dev:llm` — OpenRouter smoke test (requires `OPENROUTER_API_KEY`)

ROADMAP.md

@@ -153,3 +153,41 @@ Latest assessment (2026-02-05):
   - Depends on: core backend flows
 - Health checks + admin endpoints (optional) (**medium**)  
   - Depends on: deployment target
+
+---
+
+## Phase 5 — World Expansion & Visual Content (V1 “Large World” Pass)
+
+Goal: move from a 5-POI demo map to a **kingdom-scale world** with diverse biomes/POIs and enough visual anchors to feel like “Majesty structure + cozy Stardew pixel vibe”.
+
+Source of truth:
+- `docs/plans/2026-02-05-clawcraft-v1-updated.md` (target: ~100 POIs, location taxonomy, quest refresh cadence)
+- `docs/plans/2026-02-05-clawcraft-design-technical-specification.md` (visual direction + asset pipeline approach)
+- `docs/plans/2026-02-04-visual-assets-pipeline.md` (AI asset + background removal workflow)
+
+### 5.1 World data + seeding (large POI graph)
+- Add deterministic world generator + committed world dataset (**medium**)  
+  - Deliverable:
+    - `scripts/dev/generate-world.mjs`
+    - `data/world/world-v1-large.json` (>= 100 POIs)
+    - `data/world/world-v1-small.json` (fast dev fallback)
+- Wire `npm run dev:seed` to seed either small or large world (**simple**)  
+  - Acceptance: `SEED_WORLD=large npm run dev:seed` creates 100+ `Location`s + a connected `LocationConnection` graph.
+
+### 5.2 Map readability at scale (100+ POIs)
+- Tune label declutter thresholds for large-world zoom levels (**medium**)  
+  - Acceptance: at default fit zoom, **major cities + landmarks** are visible; towns/dungeons appear as you zoom in.
+- Add generic POI icon set per `LocationType` as a placeholder until unique sprites exist (**medium**)  
+  - Acceptance: every POI renders with a stable icon even if it doesn’t have a bespoke sprite.
+
+### 5.3 Biomes + art pipeline (incremental)
+- Expand biome tags used in the seeded world (plains/forest/desert/snow/mountain/ruins/water + cave dungeons) (**simple**)  
+  - Acceptance: seeded POIs are clustered so biome patches overlap into readable regions.
+- Replace procedural placeholder overlays with real sprites over time using the pipeline docs (**complex**)  
+  - Deliverable: a growing set of transparent PNG overlays in `public/assets/` with consistent style.
+
+### 5.4 Demo + load harness updates
+- Update demo population scripts to distribute agents across more POIs (**simple**)  
+  - Acceptance: `npm run dev:demo -- --party` creates visible activity in multiple biomes.
+- Keep performance harnesses up to date under large-world conditions (**medium**)  
+  - Acceptance: `/api/world-state?synth_agents=2000&synth_only=1` remains interactive; record baselines in `docs/plans/*`.