chore(release): v2.3.0

Co-authored-by: root <root@ego2.hstgr.cloud>

.env.example

@@ -103,6 +103,13 @@
 # STREAM_ACCEPTED_TIMEOUT_MS=120000
 # STREAM_HANDOFF_TIMEOUT_MS=300000
 
+# Dashboard URL
+#
+# Where Hermes Agent's dashboard is reachable (default: 127.0.0.1:9119).
+# /api/sessions, the conductor mission API, and the upstream kanban plugin
+# all live on the dashboard, not the gateway.
+# HERMES_DASHBOARD_URL=http://127.0.0.1:9119
+
 # Dashboard API bearer token (optional)
 #
 # Preferred over the legacy HTML-scrape token flow. Set this to a dashboard
@@ -119,6 +126,10 @@
 # ═════════════════════════════════════════════════════════════════
 # HermesWorld (multiplayer hub + online chip)
 # ═════════════════════════════════════════════════════════════════
+# Set to 0 to hide the "HermesWorld" link in the sidebar.
+# Default is enabled (1).
+# VITE_HERMESWORLD_ENABLED=1
+
 # When set, HermesWorld tabs on different devices/networks meet on the hub.
 # Without these, multiplayer falls back to BroadcastChannel (same-browser only).
 # Public hosted Cloudflare Worker hub:

.gitignore

@@ -145,3 +145,4 @@ skills-bundle/
 # Local agent artifacts (audit dumps, temporary playwright scripts)
 .hermes/
 .env.bak-*
+pr-triage-20260505-*/

README.md

@@ -1,3 +1,5 @@
+[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/outsourc-e-hermes-workspace-badge.png)](https://mseep.ai/app/outsourc-e-hermes-workspace)
+
 <div align="center">
 
 <img src="./public/claude-avatar.webp" alt="Hermes Workspace" width="80" style="border-radius: 16px" />

docker-compose.yml

@@ -36,6 +36,11 @@ services:
   # Provides the backend API that the workspace connects to
   hermes-agent:
     image: nousresearch/hermes-agent:latest
+    # The Hermes Agent image entrypoint defaults to the interactive CLI which exits
+    # immediately under `docker compose up -d`. We override here to start the
+    # gateway, which is the long-running API/health server the Workspace needs.
+    # See #360.
+    command: ["gateway", "run"]
     env_file:
       - .env
     environment:

docs/design/dirsize-tool.md

@@ -0,0 +1,127 @@
+# 技术设计：目录文件大小统计工具 (dirsize-tool)
+
+## 1. 概述
+
+轻量 Python CLI 工具，递归统计指定目录下所有文件的总大小。设计目标：纯读、快速、输出结构化，可作为 @mention 修复测试的验证工具。
+
+## 2. CLI 接口
+
+```bash
+python scripts/dirsize.py <path> [options]
+```
+
+### 参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `path` | 位置参数 | 必填 | 目标目录路径 |
+| `--unit`, `-u` | 字符串 | `auto` | 显示单位：`auto`, `B`, `KB`, `MB`, `GB` |
+| `--exclude` | 字符串列表 | 无 | 排除的模式（可多次使用），如 `--exclude node_modules --exclude .git` |
+| `--json` | 标志位 | `false` | 输出 JSON 格式供自动化使用 |
+| `--max-depth` | 整数 | 无限制 | 最大递归深度 |
+| `--ignore-permission-denied` | 标志位 | `false` | 跳过权限不足的目录 |
+| `--disk-usage` | 标志位 | `false` | 使用 `stat.st_blocks` 计算磁盘占用，而非 apparent size |
+
+### 退出码
+
+| 退出码 | 含义 |
+|--------|------|
+| 0 | 成功 |
+| 1 | 参数错误 |
+| 2 | 路径不存在 |
+| 3 | 权限不足（未使用 `--ignore-permission-denied`） |
+
+### 使用示例
+
+```bash
+# 默认输出
+python scripts/dirsize.py /some/dir
+# Total: 117.7 MB (42 files)
+
+# JSON 格式供自动化使用
+python scripts/dirsize.py /some/dir --json
+# {"path":"/some/dir","total_bytes":123456789,"human_size":"117.7 MB",...}
+
+# 排除 node_modules 和 .git
+python scripts/dirsize.py . --exclude node_modules --exclude .git
+
+# 限制深度
+python scripts/dirsize.py /deep/tree --max-depth 3
+
+# 磁盘占用（而非 apparent size）
+python scripts/dirsize.py /some/dir --disk-usage
+```
+
+### 输出格式
+
+**默认（人类可读）**：
+```
+Total: 117.7 MB (42 files)
+```
+
+**JSON 模式**：
+```json
+{
+  "path": "/path/to/dir",
+  "total_bytes": 123456789,
+  "human_size": "117.7 MB",
+  "file_count": 42,
+  "elapsed_ms": 15,
+  "errors": []
+}
+```
+
+## 3. 核心算法
+
+```python
+import os
+
+def get_dir_size(path, follow_symlinks=False, disk_usage=False):
+    total = 0
+    count = 0
+    for dirpath, dirnames, filenames in os.walk(path, followlinks=follow_symlinks):
+        for f in filenames:
+            fp = os.path.join(dirpath, f)
+            try:
+                st = os.lstat(fp) if not follow_symlinks else os.stat(fp)
+                if not stat.S_ISREG(st.st_mode):
+                    continue
+                total += st.st_blocks * 512 if disk_usage else st.st_size
+                count += 1
+            except PermissionError:
+                if not ignore_permission_denied:
+                    raise
+    return total, count
+```
+
+**性能优化**：
+- 对大目录可用 `os.scandir` + 递归替代 `os.walk`，减少 stat 调用
+- `--max-depth` 限制递归层数，避免意外遍历过深
+
+## 4. 性能预期
+
+| 文件数 | 耗时 |
+|--------|------|
+| 1,000 | < 10ms |
+| 100,000 | ~200ms |
+| 1,000,000 | ~2s |
+| 10,000,000 | ~20s (建议加 `--max-depth`) |
+
+## 5. 文件定位
+
+```bash
+scripts/dirsize.py
+```
+
+归属路径待 Carlo 确认（`~/hermes-workspace/scripts/` 或全局 `~/.hermes/scripts/`）。
+
+## 6. 实现计划
+
+1. 创建 `scripts/dirsize.py` 文件
+2. 实现 `os.walk` + `argparse` 基础功能
+3. 添加 `--json` 输出
+4. 添加 `--exclude`, `--max-depth`, `--ignore-permission-denied` 等特性
+5. 添加 `--disk-usage` 选项
+6. 提交 PR / 直接合并（视归属路径而定）
+
+预估工作量：15-30 分钟。

docs/docker.md

@@ -0,0 +1,166 @@
+# Docker
+
+Hermes Workspace + Hermes Agent in containers.
+
+## TL;DR (single-host, localhost-only)
+
+```bash
+git clone https://github.com/outsourc-e/hermes-workspace
+cd hermes-workspace
+cp .env.example .env
+# add at least one provider key (e.g. OPENROUTER_API_KEY=...)
+docker compose up -d
+open http://localhost:3000
+```
+
+That's it. The repo's `docker-compose.yml` runs:
+
+- `hermes-agent` (port `8642`, internal only)
+- `hermes-workspace` (port `3000`, bound to `127.0.0.1`)
+
+The workspace waits for the agent's `/health` to return `200` before starting (via `depends_on: condition: service_healthy`). On a fresh laptop this takes about 15 seconds.
+
+## Multi-host / NAS / VPS
+
+If the workspace and agent run on **different machines**, or you want LAN/Tailscale access to the workspace, three things change:
+
+### 1. Agent binds publicly
+
+In `.env`:
+
+```bash
+API_SERVER_HOST=0.0.0.0
+API_SERVER_KEY=<a long random string>
+```
+
+This makes the agent listen on all interfaces, not just the Docker loopback. **`API_SERVER_KEY` is mandatory** when `API_SERVER_HOST` is non-loopback — the agent will refuse to start otherwise.
+
+### 2. Workspace knows where the agent is
+
+In `.env`:
+
+```bash
+HERMES_API_URL=http://<agent-host-or-service>:8642
+HERMES_API_TOKEN=<the same value as API_SERVER_KEY>
+HERMES_DASHBOARD_URL=http://<agent-host-or-service>:9119
+HERMES_DASHBOARD_TOKEN=<same key, or set CLAUDE_DASHBOARD_TOKEN>
+```
+
+Inside docker compose on the same host, `<agent-host-or-service>` is the service name from your compose file (e.g. `hermes-agent`). On a Synology NAS with a separate workspace stack, it's the LAN IP (e.g. `192.168.1.78`).
+
+### 3. Workspace gets a password
+
+The workspace bind is non-loopback in Docker (`0.0.0.0:3000`). It refuses to start in production mode without a password to prevent accidental open exposure:
+
+```bash
+HERMES_PASSWORD=<a long random string different from API_SERVER_KEY>
+```
+
+If you publish the workspace behind HTTPS (reverse proxy, Tailscale Funnel, Cloudflare Tunnel), also set `COOKIE_SECURE=1` so session cookies get the `Secure` flag.
+
+## Connection failures — diagnostic playbook
+
+If the workspace shows "**Disconnected**" or "**Missing Hermes APIs detected**" but the agent appears to be running:
+
+### Step 1 — Verify the agent is reachable from inside the workspace container
+
+```bash
+docker compose exec hermes-workspace sh
+# inside the workspace container:
+curl -fsS http://hermes-agent:8642/health
+curl -fsS -H "Authorization: Bearer $HERMES_API_TOKEN" http://hermes-agent:8642/v1/models | head -c 200
+exit
+```
+
+If `/health` returns a JSON `{"status": "ok"}`, the agent is alive on the docker network.
+
+### Step 2 — Confirm the workspace's environment
+
+```bash
+docker compose exec hermes-workspace env | grep -E "HERMES_API|API_SERVER"
+```
+
+You should see:
+
+- `HERMES_API_URL=http://hermes-agent:8642` (or whichever service name)
+- `HERMES_API_TOKEN=<same value as agent's API_SERVER_KEY>`
+
+### Step 3 — Force a reprobe
+
+The workspace caches the gateway capability map for 2 minutes (15 seconds when in disconnected state, since v2.2.1). If the agent came up after the workspace started probing, that cache is stale.
+
+```bash
+curl -X POST http://localhost:3000/api/gateway-reprobe
+```
+
+This re-runs the probe and returns the fresh capability map. If it now reads `mode=zero-fork` you're connected.
+
+### Step 4 — Read the workspace's capability log
+
+The workspace logs the full capability summary on every probe. Look for the `[gateway]` line:
+
+```bash
+docker compose logs hermes-workspace 2>&1 | grep '\[gateway\]' | tail -3
+```
+
+A healthy log looks like:
+
+```
+[gateway] gateway=http://hermes-agent:8642 dashboard=http://hermes-agent:9119 mode=zero-fork core=[health,chatCompletions,models,streaming] enhanced=[sessions,skills,memory,config,jobs,enhancedChat,conductor,kanban] missing=[mcp]
+```
+
+A failing log usually shows `core=[]` and `missing=[health,...]` — that means every probe got a non-2xx response. Check the agent's logs (`docker compose logs hermes-agent`) for matching 401/404/timeout entries.
+
+### Common causes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `core=[]` and `missing=[health,...]` | Workspace probed before agent was ready | Wait 30s and reload, or `POST /api/gateway-reprobe`. Cache TTL drops to 15s in disconnected state. |
+| `core=[health,chatCompletions]` but no `models` | Older agent image (pre-`/v1/models`) | Update: `docker compose pull && docker compose up -d` |
+| All probes 401 | `HERMES_API_TOKEN` doesn't match agent's `API_SERVER_KEY` | Check both `.env` values are the same. They must match exactly. |
+| Workspace UI shows "Connection refused" | Workspace using `127.0.0.1` instead of the service name | Set `HERMES_API_URL=http://hermes-agent:8642` (or whichever service name). |
+| Agent restart loops with `API_SERVER_KEY required` | Agent bound to 0.0.0.0 without a key | Set `API_SERVER_KEY` in `.env` (mandatory for non-loopback bind). |
+
+## Synology NAS / external host setups
+
+If your workspace and agent are on **different stacks** on the same NAS (or different hosts entirely), they don't share a docker network. You need:
+
+1. Both to publish their ports (the agent on `8642`, the workspace on `3000`).
+2. The workspace to point at the agent's **host IP**, not service name. Example for Synology with NAS at `192.168.1.78`:
+
+```bash
+HERMES_API_URL=http://192.168.1.78:8642
+HERMES_API_TOKEN=<API_SERVER_KEY>
+HERMES_DASHBOARD_URL=http://192.168.1.78:9119
+```
+
+3. The agent to bind on `0.0.0.0`:
+
+```bash
+API_SERVER_HOST=0.0.0.0
+API_SERVER_KEY=<long random>
+```
+
+4. The dashboard plugin (multi-board kanban, conductor missions) needs the dashboard service running on the agent host too — see the agent's docker-compose for that service.
+
+If you bind the agent to `0.0.0.0` on a NAS without `API_SERVER_KEY`, the agent will refuse to start. This is intentional — open-internet exposure of the agent's chat endpoint without auth would be a footgun.
+
+## Hermes Workspace + Hermes Agent: why two containers?
+
+The workspace is the **UI**. The agent is the **engine**. Splitting them lets you:
+
+- Update either independently (`docker compose pull hermes-workspace` etc.)
+- Run multiple workspaces against one agent (different ports)
+- Run the workspace on a tablet/phone while the agent stays on a beefy machine
+
+The default compose colocates them for simplicity. The split-host setup above is the explicit "you know what you're doing" path.
+
+## Filing bugs
+
+If your setup matches the playbook above and still breaks, file an issue at <https://github.com/outsourc-e/hermes-workspace/issues> with:
+
+1. Your `docker-compose.yml` (redact secrets)
+2. The output of `docker compose logs hermes-workspace 2>&1 | grep '\[gateway\]' | tail -5`
+3. The output of `curl -fsS http://<workspace-host>:3000/api/gateway-reprobe -X POST` (also redact)
+
+That gets us to the actual cause within a couple of comments instead of a long back-and-forth.

docs/hermesworld/AGENTIC-WOW-ROHAN-SYSTEMS.md

@@ -0,0 +1,211 @@
+# HermesWorld — Agentic WoW / Rohan Systems Bible
+
+Last updated: 2026-05-06
+
+## North star
+
+HermesWorld should become the first Agentic WoW: a real MMO-style world where humans and AI agents form parties, guilds, classes, builds, rivalries, raids, events, and prize hunts.
+
+References:
+- World of Warcraft: raids, roles, classes, dungeons, social identity, long-term progression
+- Rohan / PlayRohan: races, skill trees, guild wars, weekend war cadence, PvP identity
+- Roblox: creator platform, user-generated rooms/minigames, social play
+- Hermes/OpenClaw: agents as native actors, workflows as quests, models as characters/tools
+
+## Core fantasy
+
+A solo founder plus agents builds an AI-native MMO company.
+Players do not just use agents. They bring agents into a world.
+
+## Player roles/classes
+
+Initial class fantasy should be easy to understand and map to agent behaviors.
+
+### Human-facing classes
+
+- **Priest / Healer**: support, buffs, restoration, rescue, party sustain
+- **Guardian / Tank**: absorbs damage, shields, protects party/guild objectives
+- **Mage / Promptcaster**: ranged burst, elemental/logic spells, crowd control
+- **Rogue / Scout**: stealth, discovery, easter egg hints, fast traversal
+- **Engineer / Builder**: crafts tools, deploys agents, upgrades guild halls
+- **Oracle / Analyst**: prediction, market/lore insight, quest planning
+- **Bard / Social**: buffs morale, guild communication, reputation bonuses
+
+### Agent-facing specializations
+
+- **Scout Agent**: explores zones, finds lore, maps paths
+- **Scribe Agent**: logs quests, writes guild notes, summarizes raids
+- **Builder Agent**: crafts tools, builds prompts, generates assets
+- **Trader Agent**: market/prize/economy analysis
+- **Combat Agent**: participates in duels/arenas/evals
+- **Healer Agent**: supports party actions, manages recovery/resources
+
+## Skill tree model
+
+Borrow from Rohan-style class depth without overbuilding early.
+
+Each class has:
+- 3 branches
+- 5 tiers per branch
+- active skills + passive modifiers
+- unlocks via XP, quests, guild achievements, sigils
+
+Example: Priest
+- Restoration: heal, cleanse, revive, sanctuary
+- Blessing: party buffs, XP gain, shield, haste
+- Oracle: reveal hint, prophecy, anti-cheat scan, lore insight
+
+Example: Engineer
+- Crafting: item creation, attachments, repair
+- Automation: deploy agent, queue task, build tool
+- Fortress: guild hall upgrades, defenses, traps
+
+## Leveling/progression
+
+Progression layers:
+- player level
+- class level
+- skill XP
+- agent companion level
+- guild level
+- sigil collection
+- item rarity/gearing
+- reputation per zone/faction
+
+Rewards:
+- stats
+- skills
+- titles
+- cosmetics
+- zones
+- guild permissions
+- agent actions
+- rare prize eligibility states (server-authoritative)
+
+## Gear/items/attachments
+
+Item slots:
+- weapon/tool
+- armor/robe
+- relic
+- sigil slot
+- companion module
+- guild banner charm
+
+Item stats:
+- HP / MP / SP
+- attack / spell power / defense
+- recall / memory / context
+- craft / automation / discovery
+- party aura / guild bonus
+
+Attachments:
+- gems/sigils
+- agent modules
+- spell modifiers
+- crafting upgrades
+- visual cosmetics
+
+## Guild systems
+
+Guilds should be a core differentiator.
+
+Features:
+- guild creation + banner
+- guild hall / room
+- guild chat
+- guild roles
+- weekly guild objectives
+- shared vault
+- guild quest board
+- guild raids
+- guild battles
+- leaderboard and season rewards
+
+## Guild war cadence
+
+Rohan-style scheduled events:
+- Weekend guild war window
+- Objective-based map control
+- capture obelisks/sigils
+- defend guild hall relic
+- timed score window
+- spectator mode / public feed
+- rewards: titles, cosmetics, guild XP, leaderboard status
+
+Important: scheduled events create habit and community drama.
+
+## Raids/dungeons
+
+WoW-style party content:
+- 3-5 player dungeons first
+- later 10+ player raids
+- agent companions can fill roles
+- bosses have mechanics, not just HP
+- role requirements matter: healer/tank/damage/support/scout
+
+Early raid ideas:
+- The Broken Model
+- The Oracle's Fault
+- The Hallucination Engine
+- The Dead Context Vault
+- The Black Box Titan
+
+## Minigames
+
+Add social/viral minigames:
+- boxing arena
+- sports-style guild games
+- racing/speedrun routes
+- BenchLoop agent duel arena
+- capture-the-sigil
+- crafting competitions
+- trivia/lore trials
+
+## Balance system
+
+Every patch should have notes.
+
+Track:
+- damage/healing/resource ratios
+- cooldowns
+- item rarity distribution
+- class pick rates
+- win rates by class/guild
+- economy inflation
+- agent action power
+
+Publish patch notes:
+- buffs
+- nerfs
+- new items
+- new quests
+- event schedule
+- known issues
+
+## Desktop/downloadable future
+
+Browser first, but plan for installable clients:
+- PWA install
+- Electron/Tauri shell
+- graphics settings
+- fullscreen
+- controller/gamepad
+- high/medium/low quality modes
+- asset cache
+- optional native launcher later
+
+## Acquisition narrative
+
+First AI-agent video game company.
+Single founder + agent swarm builds the first agent-native MMO.
+Target ambition: category-defining, not demo.
+
+## Immediate research questions
+
+1. What exactly makes Rohan guild wars addictive?
+2. What WoW raid/role/class loops should be copied vs avoided?
+3. What MMO progression systems create long-term identity?
+4. How do modern games balance classes/items publicly?
+5. What agent-specific mechanics can no normal MMO copy?
+6. What systems are v0.3/v0.4/v0.5, not fantasy backlog?

docs/hermesworld/AGORA-INSO-ASSET-PROMPTS.md

@@ -0,0 +1,414 @@
+# Agora Inso Asset Prompts + Manifest
+
+Status: art target locked for next HermesWorld realism loop
+Primary reference: `docs/hermesworld/reference-images/agora-center-inso-reference.jpeg`
+Source spec: `docs/hermesworld/AGORA-INSO-IMPLEMENTATION.md`
+
+## Art goal
+
+Use the Agora Inso reference as the primary visual target for the HermesWorld Agora plaza.
+
+The target is a composed browser game screen, not isolated pretty assets:
+
+- isometric / high third-person camera angled down into a circular social plaza
+- circular stone hub with central obelisk / builder monument
+- warm torch and lantern pools around the ring
+- cool cyan/blue roof, portal, and faction accents
+- dense edges: stalls, benches, crates, banners, flowers, pots, path seams
+- clear walkable center
+- readable NPC clusters and labels
+- compact HUD islands, not SaaS slabs
+
+Style lock:
+
+- premium stylized realism
+- low/mid-poly readable silhouettes, rich painted materials
+- dark obsidian + moss stone + warm amber firelight + cyan agent-tech accents
+- game asset concept sheet quality
+- no text, no logos, no UI mock text in generated assets
+- generated art is source material; final layout must be placed and judged in browser screenshots
+
+## Global negative prompt
+
+Use this on every generation unless a tool has a separate negative field:
+
+```text
+no text, no readable letters, no logos, no watermark, no photoreal modern city, no cyberpunk neon overload, no cartoon toy style, no plastic mobile-game asset look, no huge empty flat floor, no fisheye distortion, no blurry details, no overexposed bloom, no UI text, no duplicate limbs, no broken hands, no random weapons, no sci-fi guns, no anime chibi proportions
+```
+
+## Global style suffix
+
+Append this to every prompt:
+
+```text
+HermesWorld Agora Inso visual target, premium browser-native fantasy/sci-fi RPG, stylized realism, isometric game readability, dark obsidian stone, mossy civic plaza, warm amber torchlight, controlled cyan agent-tech glow, clear silhouettes, optimized for 3D game asset interpretation, high detail but readable at gameplay camera distance, no text, no logo
+```
+
+---
+
+# 1. Central monument / obelisk
+
+## Prompt: final concept sheet
+
+```text
+Create a central monument for HermesWorld Agora: a civic builder obelisk rising from a circular stone plinth, ancient carved dark basalt and bronze trim, subtle cyan agent-network veins running through engraved channels, warm amber lanterns at the base, small offering steps and radial stone rings around it. The silhouette must be readable from an isometric gameplay camera. Shape language: entrepreneurial civic plaza meets ancient AI command shrine. Include 3/4 view, front view, top-down footprint inset, and material callouts, but no readable text. The monument should feel like the spawn anchor and social center of a multiplayer plaza. HermesWorld Agora Inso visual target, premium browser-native fantasy/sci-fi RPG, stylized realism, isometric game readability, dark obsidian stone, mossy civic plaza, warm amber torchlight, controlled cyan agent-tech glow, clear silhouettes, optimized for 3D game asset interpretation, high detail but readable at gameplay camera distance, no text, no logo.
+```
+
+Suggested generation settings:
+
+- aspect: 16:9 or 4:3
+- count: 4 variations
+- choose for silhouette first, ornament second
+
+Implementation notes:
+
+- Build as simple geometry first: cylinders, bevelled boxes, cone/obelisk, emissive strips.
+- Do not import a huge mesh unless optimized.
+- Needs collision footprint no wider than 20-24% of plaza diameter.
+
+---
+
+# 2. Torch / lantern set
+
+## Prompt: prop sheet
+
+```text
+Create a modular torch and lantern prop set for HermesWorld Agora: 8 small props on a neutral dark background, including waist-high stone braziers, hanging lantern posts, wall lanterns, market-stall lanterns, ground candle clusters, and blue-cyan agent-tech waypoint lamps. Materials: dark basalt, aged bronze, warm amber flame glass, small cyan runic accents. Each prop must have a strong simple silhouette, game-ready readable shape, and fit around a circular isometric plaza. No characters, no text, no labels. HermesWorld Agora Inso visual target, premium browser-native fantasy/sci-fi RPG, stylized realism, isometric game readability, dark obsidian stone, mossy civic plaza, warm amber torchlight, controlled cyan agent-tech glow, clear silhouettes, optimized for 3D game asset interpretation, high detail but readable at gameplay camera distance, no text, no logo.
+```
+
+## Prompt: in-scene lighting reference
+
+```text
+Create an isometric night-dusk lighting study for a circular fantasy civic plaza with warm torchlight pools around the ring and subtle cyan portal lamps at entrances. Focus on light placement, shadows, and readability: clear walkable center, lively market edges, warm/cool contrast, no characters, no text. The scene should show how lanterns guide player movement and frame the central monument. HermesWorld Agora Inso visual target, premium browser-native fantasy/sci-fi RPG, stylized realism, dark obsidian stone, mossy civic plaza, warm amber torchlight, controlled cyan agent-tech glow, clear silhouettes, no text, no logo.
+```
+
+Implementation notes:
+
+- Use a small set of repeated lights with baked-looking emissive materials.
+- Prefer fake glow planes / emissive meshes over many expensive real lights.
+- Browser target: keep dynamic light count low; use ambient + key + selective point lights.
+
+---
+
+# 3. Market stalls / booths
+
+## Prompt: modular stall kit
+
+```text
+Create a modular fantasy/sci-fi market stall kit for HermesWorld Agora, inspired by a dense isometric civic plaza. Show 10 reusable stall assets: blue-roof merchant canopy, amber-cloth builder kiosk, tool bench stall, scroll/data booth, potion/energy stand, crate cluster, barrel cluster, bench, flower pot cluster, small portal ticket booth. Materials: dark wood, basalt stone, bronze, fabric awnings in muted deep blue and amber, subtle cyan agent-tech trims. Must feel entrepreneurial, social, and busy without clutter. Asset sheet, orthographic-ish 3/4 view, neutral background, no text, no labels. HermesWorld Agora Inso visual target, premium browser-native fantasy/sci-fi RPG, stylized realism, isometric game readability, dark obsidian stone, mossy civic plaza, warm amber torchlight, controlled cyan agent-tech glow, clear silhouettes, optimized for 3D game asset interpretation, high detail but readable at gameplay camera distance, no text, no logo.
+```
+
+## Prompt: plaza edge composition
+
+```text
+Create an isometric environment concept for the edge of HermesWorld Agora plaza: circular stone path in foreground, dense market stalls and benches around the edge, blue awnings, warm lanterns, crates, flowers, pots, small portal-gate silhouette, clear center path visible, no characters. The composition should show how props cluster around the plaza rim while preserving walkable space. Premium stylized realism, browser-native RPG readability, no text, no logo.
+```
+
+Implementation notes:
+
+- Stalls should be kitbashed from awning + counter + crates + lantern.
+- Use 3 awning colors max: muted blue, amber, desaturated teal.
+- Place at 30-45 degree rotations around the ring.
+
+---
+
+# 4. Ground tiles / radial plaza material
+
+## Prompt: top-down tile sheet
+
+```text
+Create a seamless modular ground tile sheet for HermesWorld Agora: radial circular plaza stones, wedge-shaped pavers, moss seams, flower tufts, worn path edges, small engraved cyan agent-network channels, dark basalt and warm gray stone. Top-down orthographic view. Include variations: clean center tile, outer ring tile, cracked tile, mossy seam tile, edge curb, small flower/grass decal, bronze inlay strip. No text, no labels, no shadows baked too strongly. Game texture/material reference, readable at isometric browser RPG camera distance. HermesWorld Agora Inso visual target, premium stylized realism, no text, no logo.
+```
+
+## Prompt: material close-up
+
+```text
+Create a close-up material reference for HermesWorld Agora radial plaza stones: dark mossy basalt pavers, hand-cut circular seams, subtle worn edges, tiny grass and flowers in cracks, thin cyan engraved channels, amber lantern reflections on stone. Realistic material detail but stylized for a lightweight browser game. No text, no logo.
+```
+
+Implementation notes:
+
+- Use procedural geometry/material variation first; imagegen is material reference.
+- Keep tile contrast low enough that NPCs and labels remain readable.
+- Use decals/planes for flowers/seams rather than a massive texture atlas if faster.
+
+---
+
+# 5. NPC portraits
+
+NPC set target: five Agora social roles, consistent bust framing, square portraits.
+
+Shared portrait suffix:
+
+```text
+RPG NPC bust portrait, centered square composition, readable face, premium stylized realism, dark obsidian civic plaza background, warm amber key light, cyan rim light, detailed but not noisy clothing, no text, no logo, no frame, same camera distance and lighting across the set.
+```
+
+## NPC 1 — Agora Steward / Orchestrator Host
+
+```text
+Create a HermesWorld Agora NPC portrait: the Agora Steward, a calm civic orchestrator who welcomes players into the social hub. Middle-aged, intelligent eyes, bronze-trimmed dark cloak, subtle cyan agent-network brooch, warm lantern light on face, composed expression, entrepreneurial city-founder energy. RPG NPC bust portrait, centered square composition, readable face, premium stylized realism, dark obsidian civic plaza background, warm amber key light, cyan rim light, detailed but not noisy clothing, no text, no logo, no frame, same camera distance and lighting across the set.
+```
+
+## NPC 2 — Market Builder / Toolsmith
+
+```text
+Create a HermesWorld Agora NPC portrait: Market Builder Toolsmith, practical maker and startup engineer, rolled sleeves, leather apron over dark tunic, small glowing tool charms, bronze goggles pushed up, friendly confident expression, warm forge-lantern key light and cyan rim accents. RPG NPC bust portrait, centered square composition, readable face, premium stylized realism, dark obsidian civic plaza background, warm amber key light, cyan rim light, detailed but not noisy clothing, no text, no logo, no frame, same camera distance and lighting across the set.
+```
+
+## NPC 3 — Signal Merchant / Data Broker
+
+```text
+Create a HermesWorld Agora NPC portrait: Signal Merchant Data Broker, elegant social operator who trades rumors, quests, and agent signals. Sleek layered robes, deep blue fabric, bronze clasp, small translucent cyan data tokens floating subtly near shoulder, sharp observant expression, warm/cool split lighting. RPG NPC bust portrait, centered square composition, readable face, premium stylized realism, dark obsidian civic plaza background, warm amber key light, cyan rim light, detailed but not noisy clothing, no text, no logo, no frame, same camera distance and lighting across the set.
+```
+
+## NPC 4 — Lantern Guard / Plaza Sentinel
+
+```text
+Create a HermesWorld Agora NPC portrait: Lantern Guard Plaza Sentinel, protective but approachable civic guardian, dark metal shoulder plates, amber lantern staff visible near shoulder, blue cloth sash, grounded expression, strong silhouette, warm torchlight and cyan rim glow. RPG NPC bust portrait, centered square composition, readable face, premium stylized realism, dark obsidian civic plaza background, warm amber key light, cyan rim light, detailed but not noisy clothing, no text, no logo, no frame, same camera distance and lighting across the set.
+```
+
+## NPC 5 — Apprentice Founder / Newcomer
+
+```text
+Create a HermesWorld Agora NPC portrait: Apprentice Founder Newcomer, young ambitious builder arriving at the plaza, travel cloak, satchel of scrolls and small devices, subtle nervous confidence, warm lantern reflection in eyes, cyan token pendant, hopeful expression. RPG NPC bust portrait, centered square composition, readable face, premium stylized realism, dark obsidian civic plaza background, warm amber key light, cyan rim light, detailed but not noisy clothing, no text, no logo, no frame, same camera distance and lighting across the set.
+```
+
+Implementation notes:
+
+- Generate portraits as 1024x1024, crop to consistent bust framing.
+- Downsample to 512 and 256 for runtime.
+- Use same background/value range; inconsistency will look cheap instantly.
+
+---
+
+# 6. Minimap style
+
+## Prompt: minimap art direction
+
+```text
+Create a stylized minimap design for HermesWorld Agora, top-right HUD island style. Show a circular plaza map from top-down: central obelisk icon, radial stone rings, NPC dots around the ring, market stall blocks, portal gate markers, player arrow, subtle dark obsidian panel backing, bronze border, cyan route accents, amber point-of-interest dots. Clean game UI, readable at small size, no readable text, no labels, no logo. Premium fantasy/sci-fi RPG HUD, compact island panel, not a SaaS dashboard.
+```
+
+## Prompt: minimap icon glyph sheet
+
+```text
+Create a small minimap glyph sheet for HermesWorld Agora: player arrow, NPC dot, quest star, portal arch, market stall, central monument, bench/rest point, chat/social node, danger/blocker marker. Style: simple top-down game map glyphs, dark bronze/cyan/amber palette, high contrast, readable at 16-24px, no text, no labels, transparent-looking dark background.
+```
+
+Implementation notes:
+
+- Final minimap should be vector/CSS/canvas where possible, not a static generated image.
+- Use generated result as style reference for colors, border, glyph proportions.
+- Keep labels out; hover/tooltips in UI handle text.
+
+---
+
+# 7. HUD icon pack
+
+## Prompt: 24-icon action/HUD pack
+
+```text
+Create a cohesive 24-icon HUD pack for HermesWorld Agora, premium fantasy/sci-fi RPG interface icons. Icons needed: move, inspect, talk, trade, quest, map, inventory, skills, memory, agents, dispatch, build, review, repair, portal, party, chat, report, inbox, torch, monument, market, settings, help. Style: luminous cyan and warm amber line icons on dark obsidian/bronze circular or rounded-square backplates, readable at 32px and 64px, consistent stroke weight, simple silhouettes, no text, no letters, no logos, no watermark.
+```
+
+## Prompt: action bar button material
+
+```text
+Create a game HUD action bar button material/style sheet for HermesWorld: dark obsidian glass-metal buttons, bronze bevel, subtle inner highlight, cyan active glow, amber hover/quest glow, disabled muted state, pressed state. Show 8 empty icon slots with different states, no text, no logos. Premium fantasy/sci-fi RPG UI, compact bottom-center action bar, not a SaaS toolbar.
+```
+
+Implementation notes:
+
+- Final icons should be SVG or small transparent PNG sprites.
+- Generate for direction, then trace/simplify if needed.
+- Do not ship raster icons with accidental text artifacts.
+
+---
+
+# Asset manifest draft
+
+```yaml
+version: 1
+zone: agora
+visual_target: agora-inso
+reference_image: docs/hermesworld/reference-images/agora-center-inso-reference.jpeg
+source_spec: docs/hermesworld/AGORA-INSO-IMPLEMENTATION.md
+art_direction:
+  camera: isometric/high-third-person angled down
+  mood: premium civic fantasy/sci-fi social plaza
+  palette:
+    obsidian: '#080F14'
+    panel: '#18212B'
+    stone: '#3D4542'
+    moss: '#516B4B'
+    bronze: '#9B7442'
+    amber: '#F2C768'
+    cyan: '#78A8C8'
+  constraints:
+    - clear walkable center
+    - dense lively perimeter
+    - no generated text/logos
+    - browser-optimized assets
+    - final layout judged from in-browser screenshots
+
+assets:
+  - id: agora_monument_obelisk_v01
+    category: environment/landmark
+    priority: P0
+    prompt_section: central monument / obelisk
+    expected_outputs:
+      - concept_sheet_png
+      - simplified_glb_or_procedural_component
+      - material_reference_png
+    runtime_target:
+      component: AgoraMonument
+      approximate_footprint_m: 5.5
+      lod: 1
+      collision: simple_cylinder
+      lights: emissive_cyan_strips + 2 amber fake-glow planes
+    acceptance:
+      - readable from zoomed-out camera
+      - acts as spawn/social anchor
+      - does not block center navigation
+
+  - id: agora_lantern_brazier_set_v01
+    category: environment/lighting-props
+    priority: P0
+    prompt_section: torch / lantern set
+    expected_outputs:
+      - prop_sheet_png
+      - 6-8 optimized prop meshes or procedural variants
+      - flame_glow_sprite_png
+    runtime_target:
+      component: AgoraLanternSet
+      placements: radial ring, stall corners, portal edges
+      dynamic_lights_budget: 4 max
+      preferred_fx: emissive material + billboards
+    acceptance:
+      - warm/cool contrast visible in screenshot
+      - guides movement around plaza ring
+      - no performance spike from too many lights
+
+  - id: agora_market_stall_kit_v01
+    category: environment/props
+    priority: P0
+    prompt_section: market stalls / booths
+    expected_outputs:
+      - modular_prop_sheet_png
+      - awning/counter/crate/barrel/bench/pot variants
+      - color_variant_manifest
+    runtime_target:
+      component: AgoraMarketKit
+      placements: perimeter clusters only
+      max_unique_meshes: 12
+      instancing: preferred
+    acceptance:
+      - edges feel lively
+      - center remains playable
+      - kitbash variants do not look copy-pasted
+
+  - id: agora_ground_tiles_radial_v01
+    category: environment/materials
+    priority: P0
+    prompt_section: ground tiles / radial plaza material
+    expected_outputs:
+      - tile_sheet_png
+      - material_reference_png
+      - optional_decal_atlas_png
+    runtime_target:
+      component: AgoraGroundTiles
+      technique: procedural radial geometry + decal planes
+      texture_budget: <= 2048 atlas if rasterized
+    acceptance:
+      - circular plaza reads instantly
+      - NPC labels remain readable
+      - seams/flowers add richness without noise
+
+  - id: agora_npc_portraits_v01
+    category: characters/portraits
+    priority: P0
+    prompt_section: NPC portraits
+    expected_outputs:
+      - steward_1024_png
+      - toolsmith_1024_png
+      - data_broker_1024_png
+      - lantern_guard_1024_png
+      - apprentice_founder_1024_png
+      - 512_runtime_versions
+      - 256_thumbnail_versions
+    runtime_target:
+      component: NpcDialogueCard / NpcInspector
+      format: webp preferred
+      framing: consistent bust portrait
+    acceptance:
+      - five portraits look like one set
+      - readable at dialogue-card size
+      - each role is distinct by silhouette/accessory
+
+  - id: agora_minimap_style_v01
+    category: ui/minimap
+    priority: P1
+    prompt_section: minimap style
+    expected_outputs:
+      - minimap_style_reference_png
+      - minimap_glyph_sheet_png
+      - vector_glyph_trace_svg
+    runtime_target:
+      component: PlaygroundMinimap
+      technique: generated style reference + SVG/canvas implementation
+      placement: top-right HUD island
+    acceptance:
+      - central monument, NPCs, portals, stalls readable at small size
+      - no text required
+      - visually matches HUD/action bar materials
+
+  - id: agora_hud_icon_pack_v01
+    category: ui/icons
+    priority: P1
+    prompt_section: HUD icon pack
+    expected_outputs:
+      - 24_icon_contact_sheet_png
+      - traced_svg_icon_set
+      - action_button_state_sheet_png
+    runtime_target:
+      component: PlaygroundActionBar / HUD islands
+      sizes_px: [32, 48, 64]
+      format: svg preferred, png fallback
+    acceptance:
+      - icons readable at 32px
+      - no accidental letters/text artifacts
+      - active/hover/disabled states match Agora material language
+
+pipeline:
+  generation:
+    preferred_tools:
+      - GPT-Image / imagegen for concept sheets and portraits
+      - Meshy or Tripo only if converting key props to GLB is faster than procedural build
+      - Scenario optional for consistent portrait/icon style if repeated generations drift
+  cleanup:
+    - crop and remove text artifacts
+    - optimize PNG/WebP sizes
+    - trace icons to SVG where possible
+    - use gltf-transform for imported GLB assets
+    - record source prompt and approval state
+  placement:
+    - implement in actual HermesWorld components
+    - capture desktop screenshot
+    - capture mobile screenshot separately
+    - compare against Agora Inso reference
+  review_gate:
+    - visual convergence to reference
+    - readability at gameplay camera
+    - no HUD clutter
+    - no giant asset bundle regression
+    - no unlicensed / unknown-provenance production assets
+```
+
+## Swarm-ready build split
+
+- Art lane: generate concept sheets and portraits from the prompts above.
+- Builder lane: implement `AgoraMonument`, `AgoraLanternSet`, `AgoraMarketKit`, and `AgoraGroundTiles` procedurally first.
+- UI lane: translate minimap/HUD prompts into SVG/CSS/canvas components.
+- QA lane: screenshot desktop/mobile, compare against `agora-center-inso-reference.jpeg`, flag gaps.
+- Reviewer lane: check asset sizes, generated-art provenance, and bundle impact.

docs/hermesworld/AGORA-INSO-IMPLEMENTATION.md

@@ -0,0 +1,115 @@
+# Agora Center Implementation Plan — Inso Reference
+
+Reference: `docs/hermesworld/reference-images/agora-center-inso-reference.jpeg`
+
+## What the reference proves
+
+The target is not just higher-poly models. It is a composed game screen:
+
+- isometric/third-person camera angled down into a lively plaza
+- circular stone hub with central monument/obelisk
+- readable NPC labels and clusters
+- warm torchlight and blue roof accents
+- rich ground detail: grass, flowers, path seams, market stalls, benches
+- HUD islands instead of slabs:
+  - player/status top-left
+  - objective top-center
+  - minimap top-right
+  - chat bottom-left
+  - action bar bottom-center
+  - quick tools right edge
+- environment density around the edges, clear walkable center
+
+## Target for HermesWorld v0.3
+
+Create an Agora scene that feels like the reference while staying browser-native:
+
+1. Replace empty/flat hub with a circular plaza composition.
+2. Add a central landmark/monument that acts as spawn anchor.
+3. Place NPCs around the ring, not randomly.
+4. Add market stalls, benches, torches, foliage, and portal gate silhouettes.
+5. Make minimap and objective HUD visually match game style.
+6. Keep mobile HUD separate, not a squeezed desktop version.
+
+## Implementation slices
+
+### Slice 1 — Layout/composition
+
+Files likely touched:
+- `src/screens/playground/components/playground-world-3d.tsx`
+- `src/screens/playground/components/playground-environment.tsx`
+- `src/screens/playground/components/playground-minimap.tsx`
+
+Tasks:
+- Add `AgoraCommons` component.
+- Build circular plaza with stone rings/tiles.
+- Add central obelisk/monument.
+- Move NPCs to named anchor points around the ring.
+- Add walkable clear center.
+
+Acceptance:
+- desktop screenshot reads as an Agora hub from zoomed-out camera.
+- NPCs are not visually piled up.
+
+### Slice 2 — Lighting/material realism
+
+Tasks:
+- warm torch/lantern lights around ring
+- blue/cyan roof/portal accents
+- contact shadows, ambient occlusion/postprocessing if performant
+- textured-looking procedural stone via repeated geometry/material variation
+
+Acceptance:
+- screenshot has depth, focal point, and warm/cool contrast.
+
+### Slice 3 — Prop density
+
+Tasks:
+- stalls with colored awnings
+- benches
+- barrels/crates/pots
+- flower/grass clusters
+- path edge stones
+- small portal booth/gate
+
+Acceptance:
+- edges feel alive while center remains playable.
+
+### Slice 4 — HUD/game readability
+
+Tasks:
+- top-left status card compact
+- top-center objective card compact
+- top-right minimap card styled like reference
+- bottom-center action bar
+- bottom-left chat collapsed/compact
+
+Acceptance:
+- no top clutter, clear objective, map, status.
+
+### Slice 5 — Asset upgrade loop
+
+Tasks:
+- generate/refine zone art, NPC portraits, item icons, sigils
+- place assets in UI
+- screenshot
+- vision review
+- revise
+
+Acceptance:
+- one browser screenshot side-by-side with reference showing visible convergence.
+
+## Swarm assignment
+
+- Mobile UX lane: HUD and no-scroll constraints.
+- Gameplay/world lane: Agora anchors, NPC composition, plaza component.
+- Art lane: generated assets, material references, UI icon set.
+- Reviewer lane: performance, bundle size, client-secret safety.
+
+## Hard constraints
+
+- No client-side prize secrets.
+- No giant PR.
+- Keep generated assets optimized.
+- Preserve hosted-runtime architecture.
+- Mobile must be tested separately.

docs/hermesworld/ART-BIBLE-REALISM-LOOP.md

@@ -0,0 +1,135 @@
+# HermesWorld Art Bible — Realism Loop
+
+Last updated: 2026-05-06
+
+## Visual ambition
+
+HermesWorld should feel like a premium browser-native fantasy/sci-fi agent RPG, not a demo scene.
+
+Target vibe:
+- cinematic dark fantasy meets agent command center
+- realistic/stylized hybrid, readable at browser scale
+- moody lighting, fog, emissive magical UI, high contrast
+- game-first interface, not SaaS dashboard clutter
+- every asset should support mechanics
+
+Primary Agora target:
+- Use `docs/hermesworld/reference-images/agora-center-inso-reference.jpeg` as the primary visual target for Agora realism work.
+- The goal is a composed game screen: circular civic plaza, central obelisk/monument, warm torchlight, blue/cyan roof/portal accents, dense market edges, clear walkable center, readable NPC clusters, and compact HUD islands.
+- Asset prompts and manifest live in `docs/hermesworld/AGORA-INSO-ASSET-PROMPTS.md`.
+
+Reference workflow from Eric's Downloads:
+- Imagegen creates high-quality source material.
+- The game places assets in the real interface.
+- Browser screenshots capture actual player view.
+- Vision review judges hierarchy, spacing, readability, clickability, mobile fit, and visual consistency.
+- Agents revise and repeat.
+
+## Palette
+
+Base:
+- Obsidian: `#080F14`
+- Panel: `#18212B`
+- Deep ink: `#030712`
+
+Accents:
+- Action green: `#2FCA94`
+- Vision blue: `#78A8C8`
+- Insight amber: `#F2C768`
+- Arcane purple: `#8B5CF6`, only as controlled magic/glow
+
+Text:
+- Primary: `#E6E7EA`
+- Muted: `rgba(230,231,234,.65)`
+
+Avoid:
+- oversaturated neon everywhere
+- purple fog as the only mood
+- cute/cartoon mascot style
+- unreadable tiny text
+- SaaS dashboard density on mobile
+
+## Shape language
+
+Panels:
+- 6-10px radius
+- 1px low-contrast borders
+- subtle inner highlights
+- dark glass/metal material
+
+HUD:
+- compact islands, not slabs
+- status visible at a glance
+- icons readable at 48-64px source size
+- mobile gets its own layout, never desktop squeezed down
+
+World:
+- large silhouettes first
+- readable landmarks
+- one hero light source per scene
+- secondary fire/magic/portal lights
+- atmospheric depth, but not enough to hide navigation
+
+## Asset rules
+
+Generate with imagegen:
+- hero art / zone banners, 16:9
+- NPC portraits, square 1:1, consistent framing
+- item icons, square 1:1, readable at 64px
+- sigil icons, square 1:1, high contrast
+- card art, vertical 2:3
+- environmental backgrounds, 16:9
+- texture/material explorations
+
+Do not generate final layout with imagegen.
+Layout must be judged in browser screenshots.
+
+## Prompt snippets
+
+### Zone hero art
+
+Create cinematic dark fantasy/sci-fi environment concept art for HermesWorld, a browser-native AI agent RPG. Mood: mysterious, premium, ancient technology, magical realism. High contrast, realistic textures, atmospheric depth, readable landmark silhouette, no text, no logo, no characters, no oversaturated neon. Style: AAA game key art, dark obsidian palette, cyan/amber accent light, subtle arcane glow. 16:9.
+
+### NPC portrait
+
+Create a realistic stylized fantasy/sci-fi RPG NPC portrait for HermesWorld. Bust portrait, centered, dramatic rim lighting, dark obsidian background, readable face, high-detail clothing/materials, premium game character art, no text, no logo, consistent square framing. 1:1.
+
+### Item icon
+
+Create a premium RPG item icon for HermesWorld. Single object centered on dark transparent-looking obsidian background, strong silhouette, readable at 64px, realistic material, cyan/amber rim light, no text, no logo, no busy background. 1:1.
+
+### Sigil icon
+
+Create a mystical sigil icon for HermesWorld. Ancient agent-world symbol, clean readable silhouette, luminous cyan/amber engraving, dark metal/stone backing, high contrast, collectible game badge quality, no text, no logo. 1:1.
+
+## Vision review checklist
+
+Every screenshot must be judged on:
+1. Playable first: can the player tell what to do?
+2. Status visibility: HP/objective/map readable instantly?
+3. HUD readability: text, icon, and tap targets clear?
+4. Inventory density: are items distinct?
+5. Mobile layout: no scroll, no overlap, no squeezed desktop UI.
+6. Art supports mechanics: landmarks, NPCs, objects communicate purpose.
+7. Visual consistency: same palette, light logic, framing, borders.
+8. Performance: assets optimized, not just pretty.
+
+## HermesWorld v0.3 realism goals
+
+Minimum visible leap:
+- replace flat/placeholder zone art with generated cinematic zone banners
+- 5 NPC portraits with consistent premium framing
+- 12 item icons with readable silhouettes
+- 7 sigil icons for lore/easter egg layer
+- HUD revised into compact game-style islands
+- one high-quality screenshot loop per mobile and desktop
+
+## Build loop
+
+1. Generate asset set.
+2. Compress/optimize into web assets.
+3. Place in actual HermesWorld UI.
+4. Capture screenshot.
+5. Vision review against checklist.
+6. Patch UI/art/layout.
+7. Repeat until it feels like a game, not a prototype.

docs/hermesworld/ASSET-GENERATION-V2-STATUS.md

@@ -0,0 +1,31 @@
+# HermesWorld Asset Generation V2 Status
+
+Branch: `feat/asset-generation-v2`
+
+## Status
+
+Image generation is blocked before any images are produced because the Hermes image generation tool is enabled but its provider credential is not configured in this runtime.
+
+Tool error:
+
+```text
+functions.image_generate: ValueError: FAL_KEY environment variable not set
+```
+
+No generated raster assets were committed from this run. This avoids shipping synthetic placeholders while claiming they came from imagegen.
+
+## Intended output paths
+
+- Zone variants and selected zone heroes: `public/assets/hermesworld/zones/v2/`
+- NPC portraits: `public/avatars/v2/`
+- Icon sprite sheet and manifest: `public/assets/hermesworld/icons/sprite-v1.png` and `sprite-v1.json`
+- Video poster: `public/assets/hermesworld/video/world-demo-poster-v2.jpg`
+
+## Prompt source
+
+Use `docs/hermesworld/PROMPT-LIBRARY.md` for the exact repeatable prompts and style lock values.
+
+## Resume command
+
+After setting `FAL_KEY` in the Hermes runtime environment, rerun the asset generation lane against this branch and commit the generated assets.
+

docs/hermesworld/CHATGPT-PROMPT-BATCH-001.md

@@ -0,0 +1,269 @@
+# ChatGPT Prompt Batch 001 — HermesWorld Assets
+
+Use these prompts directly in ChatGPT image generation. Each prompt is self-contained and includes the style lock, subject, composition, and artifact constraints.
+
+Global handling note: download each PNG, keep the exact suggested filename, and place it in the matching folder under `/Users/aurora/Downloads/hermesworld-assets/`.
+
+---
+
+## BATCH A: NPC Portraits
+
+Style lock for all Batch A prompts: stylized fantasy MMO, premium dark fantasy with cyan/amber accents, warm parchment tones, painterly brushwork, 3/4 portrait, detailed faces, expressive, painted in the spirit of WoW/RuneScape concept art, no text, no logo, no watermark.
+
+### A1: Trader Merchant
+
+```text
+Create a high-quality 3/4 portrait of a HermesWorld NPC trader merchant from the Agora marketplace: a middle-aged man with a kind smile, weathered face, clever eyes, neatly trimmed beard, leather merchant apron over layered linen and wool, small bronze clasps, coin pouch, rolled parchment receipts, and subtle market-stall details behind him. Style: stylized fantasy MMO, premium dark fantasy with cyan and amber accents, warm parchment tones, painterly brushwork, detailed expressive face, concept art quality in the spirit of WoW/RuneScape character portraits. Lighting: warm amber lantern light from one side with a faint controlled cyan magical rim light. Background: softly blurred Agora marketplace with banners, stone columns, and warm stalls, not distracting. Composition: chest-up 3/4 portrait, centered, strong silhouette, readable at game UI size. No text, no UI, no logo, no watermark, no photorealism, no anime, no plastic mobile-game look.
+```
+
+Note for Eric: Save the result as: trader-merchant.png in /Users/aurora/Downloads/hermesworld-assets/portraits/
+
+### A2: Quest Giver Elder Sage
+
+```text
+Create a high-quality 3/4 portrait of a HermesWorld quest giver elder sage: an ancient white-bearded mystic with wise eyes, deep brow lines, layered parchment-colored robes, bronze and gold trim, and a rune-engraved wooden staff held near his shoulder. The staff emits a restrained cyan glow from carved runes. Style: stylized fantasy MMO, premium dark fantasy with cyan and amber accents, warm parchment tones, painterly brushwork, detailed expressive face, concept art quality in the spirit of WoW/RuneScape character portraits. Lighting: soft amber firelight across the beard and cheekbones, cyan rune light catching the staff hand and robe edges. Background: blurred stone library alcove with candles and faint arcane glyphs, atmospheric but not busy. Composition: chest-up 3/4 portrait, centered, noble and readable. No text, no UI, no logo, no watermark, no photorealism, no anime, no plastic mobile-game look.
+```
+
+Note for Eric: Save the result as: quest-giver-elder-sage.png in /Users/aurora/Downloads/hermesworld-assets/portraits/
+
+### A3: Female Warrior Captain
+
+```text
+Create a high-quality 3/4 portrait of a HermesWorld female warrior captain: confident, battle-tested, upright posture, one visible scar across the cheek, focused eyes, dark hair pulled back, gold-trimmed armor with worn steel plates, bronze fittings, leather straps, and a short crimson or deep amber cloak edge. Style: stylized fantasy MMO, premium dark fantasy with cyan and amber accents, warm parchment tones, painterly brushwork, detailed expressive face, concept art quality in the spirit of WoW/RuneScape character portraits. Lighting: heroic warm amber key light with subtle cool cyan edge light reflecting from polished armor. Background: blurred fortress banner and stone archway, low depth of field. Composition: chest-up 3/4 portrait, centered, strong readable silhouette, authoritative expression. No text, no UI, no logo, no watermark, no photorealism, no anime, no plastic mobile-game look.
+```
+
+Note for Eric: Save the result as: female-warrior-captain.png in /Users/aurora/Downloads/hermesworld-assets/portraits/
+
+### A4: Mysterious Hooded Scholar
+
+```text
+Create a high-quality 3/4 portrait of a HermesWorld mysterious hooded scholar: face mostly obscured beneath a deep charcoal hood, only watchful eyes and a hint of nose visible, holding an ancient glowing tome open at chest level. The tome pages emit a controlled cyan magical light with tiny rune sparks, while the robe has amber stitching and bronze clasps. Style: stylized fantasy MMO, premium dark fantasy with cyan and amber accents, warm parchment tones, painterly brushwork, expressive detailed face area despite the shadow, concept art quality in the spirit of WoW/RuneScape character portraits. Lighting: cyan underlight from the book, warm amber candle glow on robe folds. Background: dim archive shelves and parchment scrolls, softly blurred. Composition: chest-up 3/4 portrait, centered, enigmatic silhouette, readable at UI scale. No readable text, no UI, no logo, no watermark, no photorealism, no anime, no plastic mobile-game look.
+```
+
+Note for Eric: Save the result as: mysterious-hooded-scholar.png in /Users/aurora/Downloads/hermesworld-assets/portraits/
+
+### A5: Innkeeper
+
+```text
+Create a high-quality 3/4 portrait of a HermesWorld innkeeper: jovial middle-aged tavern host with ruddy cheeks, broad welcoming smile, expressive laugh lines, short tousled hair, woven shirt, rolled sleeves, simple leather vest, and a small towel or tankard detail. Style: stylized fantasy MMO, premium dark fantasy with cyan and amber accents, warm parchment tones, painterly brushwork, detailed expressive face, concept art quality in the spirit of WoW/RuneScape character portraits. Lighting: cozy amber hearth light, very subtle cyan window rim light so it still belongs to HermesWorld. Background: softly blurred tavern interior with wooden beams, candles, and warm shelves, no readable signs. Composition: chest-up 3/4 portrait, centered, friendly and instantly recognizable. No text, no UI, no logo, no watermark, no photorealism, no anime, no plastic mobile-game look.
+```
+
+Note for Eric: Save the result as: innkeeper.png in /Users/aurora/Downloads/hermesworld-assets/portraits/
+
+### A6: Smith
+
+```text
+Create a high-quality 3/4 portrait of a HermesWorld blacksmith NPC: muscular build, soot-streaked face and forearms, intense but approachable expression, close-cropped hair or tied-back hair, heavy leather apron, bronze rivets, thick gloves, and a large hammer resting over one shoulder. Style: stylized fantasy MMO, premium dark fantasy with cyan and amber accents, warm parchment tones, painterly brushwork, detailed expressive face, concept art quality in the spirit of WoW/RuneScape character portraits. Lighting: hot amber forge glow across the face and hammer head, faint cyan reflection from an enchanted metal ingot off-frame. Background: blurred forge shapes, anvil silhouette, sparks, dark stone walls. Composition: chest-up 3/4 portrait, centered, strong readable silhouette. No text, no UI, no logo, no watermark, no photorealism, no anime, no plastic mobile-game look.
+```
+
+Note for Eric: Save the result as: smith.png in /Users/aurora/Downloads/hermesworld-assets/portraits/
+
+### A7: Healer Priestess
+
+```text
+Create a high-quality 3/4 portrait of a HermesWorld healer priestess: serene expression, calm eyes, elegant white robes with warm parchment undertones, gold embroidery, small bronze clasp, softly glowing hands, and a gentle halo-like ambient light without looking saintly or overexposed. Style: stylized fantasy MMO, premium dark fantasy with cyan and amber accents, warm parchment tones, painterly brushwork, detailed expressive face, concept art quality in the spirit of WoW/RuneScape character portraits. Lighting: soft warm amber key light mixed with controlled cyan healing glow around the hands and robe edges. Background: blurred temple infirmary with candles, stone arch, herbs, and clean linen shapes. Composition: chest-up 3/4 portrait, centered, tranquil and readable. No text, no UI, no logo, no watermark, no photorealism, no anime, no plastic mobile-game look.
+```
+
+Note for Eric: Save the result as: healer-priestess.png in /Users/aurora/Downloads/hermesworld-assets/portraits/
+
+### A8: Beggar Info Broker
+
+```text
+Create a high-quality 3/4 portrait of a HermesWorld beggar and info broker: hooded figure in worn layered cloth, watchful sharp eyes, thin knowing smile, weathered hands, patched cloak, hidden bronze token necklace, and subtle spy-network details like folded notes and small charms tucked into the clothing. Style: stylized fantasy MMO, premium dark fantasy with cyan and amber accents, warm parchment tones, painterly brushwork, detailed expressive face, concept art quality in the spirit of WoW/RuneScape character portraits. Lighting: low amber alley lantern light with a narrow cyan glint in the eyes or from a hidden charm. Background: softly blurred Agora side alley, stone wall, cloth awning, no readable signs. Composition: chest-up 3/4 portrait, centered, suspicious but charismatic, readable at UI scale. No text, no UI, no logo, no watermark, no photorealism, no anime, no plastic mobile-game look.
+```
+
+Note for Eric: Save the result as: beggar-info-broker.png in /Users/aurora/Downloads/hermesworld-assets/portraits/
+
+---
+
+## BATCH B: Item Icons
+
+Style lock for all Batch B prompts: 1024x1024 square, stylized 3D rendered fantasy item icon, isometric 3/4 view, dark obsidian background with subtle glow, gold/bronze metallic accents, Diablo-style polish, centered, well-lit, no text, no UI, no logo, no watermark.
+
+### B1: Bronze Sword
+
+```text
+Create a 1024x1024 square stylized 3D rendered fantasy item icon of a bronze sword, centered on a dark obsidian background with a subtle warm glow. The sword should be shown in isometric 3/4 view, slightly angled, with a polished bronze blade, gold-toned crossguard, worn leather grip, tiny engraved runes, and crisp beveled edges. Style: premium Diablo-style item icon polish, high contrast, dramatic studio lighting, gold/bronze metallic accents, readable at small size. No text, no UI, no logo, no watermark, no hands, no character, no busy background.
+```
+
+Note for Eric: Save the result as: bronze-sword.png in /Users/aurora/Downloads/hermesworld-assets/icons/
+
+### B2: Healing Potion
+
+```text
+Create a 1024x1024 square stylized 3D rendered fantasy item icon of a healing potion: a red glass vial filled with glowing crimson liquid, centered on a dark obsidian background with a subtle amber halo. Show the vial in isometric 3/4 view with a cork stopper, bronze wire clasp, small parchment tag without readable writing, glass highlights, and a few tiny magical bubbles inside. Style: premium Diablo-style item icon polish, high contrast, dramatic studio lighting, gold/bronze metallic accents, readable at small size. No text, no UI, no logo, no watermark, no hands, no character, no busy background.
+```
+
+Note for Eric: Save the result as: healing-potion.png in /Users/aurora/Downloads/hermesworld-assets/icons/
+
+### B3: Magic Scroll
+
+```text
+Create a 1024x1024 square stylized 3D rendered fantasy item icon of a magic scroll: rolled warm parchment unfurling slightly, bronze end caps, tied with a small cord, emitting a controlled cyan magical glow from the parchment edges. Center it on a dark obsidian background with subtle cyan and amber rim light. Show it in isometric 3/4 view with crisp curled paper silhouette and painterly material detail. Style: premium Diablo-style item icon polish, high contrast, dramatic studio lighting, gold/bronze accents, readable at small size. No readable text, no UI, no logo, no watermark, no hands, no character, no busy background.
+```
+
+Note for Eric: Save the result as: magic-scroll.png in /Users/aurora/Downloads/hermesworld-assets/icons/
+
+### B4: Ornate Iron Key
+
+```text
+Create a 1024x1024 square stylized 3D rendered fantasy item icon of an ornate iron key, centered on a dark obsidian background with a subtle amber glow. The key should be shown in isometric 3/4 view, made of dark iron with bronze wear on the edges, an elaborate circular bow, carved notches, small turquoise/cyan enamel inset, and a heavy ancient-dungeon feel. Style: premium Diablo-style item icon polish, high contrast, dramatic studio lighting, gold/bronze metallic accents, readable at small size. No text, no UI, no logo, no watermark, no hands, no character, no busy background.
+```
+
+Note for Eric: Save the result as: ornate-iron-key.png in /Users/aurora/Downloads/hermesworld-assets/icons/
+
+### B5: Amber Glowing Gem
+
+```text
+Create a 1024x1024 square stylized 3D rendered fantasy item icon of a glowing amber gemstone, centered on a dark obsidian background with a subtle golden aura. Show the gem in isometric 3/4 view as a faceted crystal with warm internal light, bronze setting fragments around the base, sharp reflective facets, and tiny floating dust motes. Style: premium Diablo-style item icon polish, high contrast, dramatic studio lighting, gold/bronze accents, readable at small size. No text, no UI, no logo, no watermark, no hands, no character, no busy background.
+```
+
+Note for Eric: Save the result as: amber-glowing-gem.png in /Users/aurora/Downloads/hermesworld-assets/icons/
+
+### B6: Wooden Shield With Sigil
+
+```text
+Create a 1024x1024 square stylized 3D rendered fantasy item icon of a wooden shield with a simple fantasy sigil, centered on a dark obsidian background with subtle amber edge glow. Show the shield in isometric 3/4 view with layered dark oak planks, bronze rim, worn leather straps, small scratches, and a painted cyan-and-gold abstract winged mark that is symbolic but contains no letters. Style: premium Diablo-style item icon polish, high contrast, dramatic studio lighting, gold/bronze metallic accents, readable at small size. No text, no UI, no logo, no watermark, no hands, no character, no busy background.
+```
+
+Note for Eric: Save the result as: wooden-shield-sigil.png in /Users/aurora/Downloads/hermesworld-assets/icons/
+
+### B7: Leather Pouch With Coins
+
+```text
+Create a 1024x1024 square stylized 3D rendered fantasy item icon of a leather pouch with coins spilling out, centered on a dark obsidian background with subtle warm glow. Show it in isometric 3/4 view: worn brown leather pouch, tied cord, bronze buckle, several gold and bronze coins tumbling forward, crisp silhouettes, polished highlights, and soft contact shadow. Style: premium Diablo-style item icon polish, high contrast, dramatic studio lighting, gold/bronze metallic accents, readable at small size. No text, no UI, no logo, no watermark, no hands, no character, no busy background.
+```
+
+Note for Eric: Save the result as: leather-pouch-coins.png in /Users/aurora/Downloads/hermesworld-assets/icons/
+
+### B8: Open Spell Tome
+
+```text
+Create a 1024x1024 square stylized 3D rendered fantasy item icon of an open spell tome, centered on a dark obsidian background with a controlled cyan magical glow. Show the tome in isometric 3/4 view with thick aged parchment pages, dark leather cover, bronze corner guards, raised spine bands, glowing page edges, and small abstract rune-like marks that are not readable text. Style: premium Diablo-style item icon polish, high contrast, dramatic studio lighting, gold/bronze metallic accents, readable at small size. No readable text, no UI, no logo, no watermark, no hands, no character, no busy background.
+```
+
+Note for Eric: Save the result as: open-spell-tome.png in /Users/aurora/Downloads/hermesworld-assets/icons/
+
+### B9: Wizard Staff With Crystal
+
+```text
+Create a 1024x1024 square stylized 3D rendered fantasy item icon of a wizard staff with a crystal, centered on a dark obsidian background with a subtle cyan and amber glow. Show the staff in isometric 3/4 view, diagonal composition, carved dark wood shaft, bronze bands, gold filigree, and a faceted cyan crystal at the top emitting restrained magical light. Style: premium Diablo-style item icon polish, high contrast, dramatic studio lighting, gold/bronze metallic accents, readable at small size. No text, no UI, no logo, no watermark, no hands, no character, no busy background.
+```
+
+Note for Eric: Save the result as: wizard-staff-crystal.png in /Users/aurora/Downloads/hermesworld-assets/icons/
+
+### B10: Hunting Bow
+
+```text
+Create a 1024x1024 square stylized 3D rendered fantasy item icon of a hunting bow, centered on a dark obsidian background with a subtle warm amber glow. Show the bow in isometric 3/4 view with curved dark wood limbs, bronze fittings, taut string, leather grip, small feather charm, and a few tasteful cyan inlays near the handle. Style: premium Diablo-style item icon polish, high contrast, dramatic studio lighting, gold/bronze metallic accents, readable at small size. No text, no UI, no logo, no watermark, no hands, no character, no busy background.
+```
+
+Note for Eric: Save the result as: hunting-bow.png in /Users/aurora/Downloads/hermesworld-assets/icons/
+
+### B11: Gold Ring With Gem
+
+```text
+Create a 1024x1024 square stylized 3D rendered fantasy item icon of a gold ring with a gemstone, centered on a dark obsidian background with a subtle amber halo. Show the ring in isometric 3/4 view with polished gold band, bronze shadowing in engraved grooves, a prominent cyan or amber faceted gem, tiny decorative filigree, and crisp reflective highlights. Style: premium Diablo-style item icon polish, high contrast, dramatic studio lighting, gold/bronze metallic accents, readable at small size. No text, no UI, no logo, no watermark, no hands, no character, no busy background.
+```
+
+Note for Eric: Save the result as: gold-ring-gem.png in /Users/aurora/Downloads/hermesworld-assets/icons/
+
+### B12: Founder Cape
+
+```text
+Create a 1024x1024 square stylized 3D rendered fantasy item icon of a Founder Cape, centered on a dark obsidian background with a subtle regal glow. Show the cape in isometric 3/4 view as rich deep purple fabric with gold trim, bronze clasp, winged crown clasp motif, elegant folds, slight magical cyan edge shimmer, and premium founder-reward presence. Style: premium Diablo-style item icon polish, high contrast, dramatic studio lighting, gold/bronze metallic accents, readable at small size. No text, no UI, no logo, no watermark, no hands, no character, no busy background.
+```
+
+Note for Eric: Save the result as: founder-cape.png in /Users/aurora/Downloads/hermesworld-assets/icons/
+
+---
+
+## BATCH C: Banner & Sigil Emblems
+
+Style lock for all Batch C prompts: heraldic emblem, centered on dark midnight blue (#0F1622) background, gold filigree, parchment scroll texture behind, 1024x1024 square, high contrast, no text, no UI, no logo, no watermark.
+
+### C1: Hermes Caduceus Sigil
+
+```text
+Create a 1024x1024 square heraldic emblem for HermesWorld: a centered Hermes caduceus sigil with a winged staff and two intertwined serpents, designed as the main brand sigil but with no letters or readable text. Background: dark midnight blue (#0F1622). Behind the emblem, include a subtle warm parchment scroll texture. Emblem material: polished gold and antique bronze filigree with controlled cyan magical accents in the wing tips and staff core. Style: premium fantasy MMO heraldry, crisp symmetrical silhouette, painterly rendered metal, elegant and iconic, readable at small size. No text, no UI, no logo, no watermark, no photoreal corporate mark, no cluttered background.
+```
+
+Note for Eric: Save the result as: hermes-caduceus-sigil.png in /Users/aurora/Downloads/hermesworld-assets/sigils/
+
+### C2: Guild Banner — Order of Aether
+
+```text
+Create a 1024x1024 square heraldic guild banner emblem for HermesWorld: Order of Aether, centered on a dark midnight blue (#0F1622) background with a subtle parchment scroll texture behind. Main motif: a luminous cyan crystal suspended within a gold and bronze filigree frame, with small wing-like facets and delicate arcane geometry that contains no readable text. Style: premium fantasy MMO heraldry, crisp symmetrical silhouette, gold filigree, controlled cyan glow, painterly metal and parchment, readable at small size. No text, no UI, no logo, no watermark, no cluttered background.
+```
+
+Note for Eric: Save the result as: order-of-aether-banner.png in /Users/aurora/Downloads/hermesworld-assets/sigils/
+
+### C3: Guild Banner — Iron Wolves
+
+```text
+Create a 1024x1024 square heraldic guild banner emblem for HermesWorld: Iron Wolves, centered on a dark midnight blue (#0F1622) background with a subtle parchment scroll texture behind. Main motif: a snarling wolf head in antique bronze and dark iron, framed by gold filigree, sharp angular fur shapes, and faint amber battle-worn highlights. Add only a restrained cyan glint in the eyes or frame edge to tie it to HermesWorld. Style: premium fantasy MMO heraldry, bold symmetrical silhouette, painterly metal, readable at small size. No text, no UI, no logo, no watermark, no cluttered background.
+```
+
+Note for Eric: Save the result as: iron-wolves-banner.png in /Users/aurora/Downloads/hermesworld-assets/sigils/
+
+### C4: Guild Banner — Sun Sentinels
+
+```text
+Create a 1024x1024 square heraldic guild banner emblem for HermesWorld: Sun Sentinels, centered on a dark midnight blue (#0F1622) background with a subtle parchment scroll texture behind. Main motif: a radiant golden sun with sharp sentinel rays, bronze shield-like center, elegant gold filigree, and warm amber glow. Include tiny controlled cyan accent gems in the frame, but keep the sun motif dominant. Style: premium fantasy MMO heraldry, crisp symmetrical silhouette, painterly metal and parchment, readable at small size. No text, no UI, no logo, no watermark, no cluttered background.
+```
+
+Note for Eric: Save the result as: sun-sentinels-banner.png in /Users/aurora/Downloads/hermesworld-assets/sigils/
+
+### C5: Founder's Cape Emblem
+
+```text
+Create a 1024x1024 square heraldic emblem for a HermesWorld Founder's Cape, centered on a dark midnight blue (#0F1622) background with a subtle parchment scroll texture behind. Main motif: a winged crown in polished gold and antique bronze, framed by elegant filigree, with a regal purple enamel backing and a faint controlled cyan magical rim light. Style: premium fantasy MMO heraldry, iconic founder reward symbol, crisp symmetrical silhouette, painterly metal, readable at small size. No text, no UI, no logo, no watermark, no cluttered background.
+```
+
+Note for Eric: Save the result as: founders-cape-emblem.png in /Users/aurora/Downloads/hermesworld-assets/sigils/
+
+### C6: Trader's Guild Seal
+
+```text
+Create a 1024x1024 square heraldic seal for the HermesWorld Trader's Guild, centered on a dark midnight blue (#0F1622) background with a subtle parchment scroll texture behind. Main motif: balanced merchant scales combined with a small caduceus staff, rendered in polished gold and antique bronze, surrounded by coin-like filigree and warm amber highlights. Add restrained cyan glow to the caduceus centerline only. Style: premium fantasy MMO heraldry, crisp symmetrical silhouette, painterly metal and parchment, readable at small size. No text, no UI, no logo, no watermark, no cluttered background.
+```
+
+Note for Eric: Save the result as: traders-guild-seal.png in /Users/aurora/Downloads/hermesworld-assets/sigils/
+
+---
+
+## BATCH D: Zone Backgrounds
+
+Style lock for all Batch D prompts: stylized painterly fantasy MMO concept art, wide cinematic 16:9, dramatic lighting, depth, atmospheric haze, warm color palette with cool shadow accents, no text, no UI, no logo, no watermark.
+
+### D1: Agora Plaza at Golden Hour
+
+```text
+Create a wide cinematic 16:9 stylized painterly fantasy MMO concept art background of HermesWorld's Agora Plaza at golden hour. Scene: a circular civic plaza with a central fountain, stone columns, hanging banners, market stalls around the edges, warm lanterns, crates, awnings, potted plants, and a clear walkable center. Use warm amber sunlight and torchlight with cool cyan accents on portals, roof trims, and magical civic details. Style: premium browser-native fantasy RPG, painterly brushwork, dramatic lighting, atmospheric haze, strong depth, readable silhouettes, warm parchment and obsidian stone palette with gold/bronze details. Composition: central fountain as focal point, columns framing the plaza, lively market perimeter, cinematic depth, no characters dominating the scene. No text, no UI, no logo, no watermark, no photoreal modern city, no cyberpunk neon overload.
+```
+
+Note for Eric: Save the result as: agora-plaza-golden-hour.png in /Users/aurora/Downloads/hermesworld-assets/zones/
+
+### D2: Whispering Forest
+
+```text
+Create a wide cinematic 16:9 stylized painterly fantasy MMO concept art background of HermesWorld's Whispering Forest at twilight. Scene: ancient towering trees with twisted roots, a winding mossy path, glowing mushrooms, soft firefly-like motes, carved stones half-buried in moss, and deep atmospheric layers fading into cool blue shadows. Use a warm color palette in the foreground with amber lantern or mushroom glow, balanced by cool cyan and violet-blue shadow accents. Style: premium browser-native fantasy RPG, painterly brushwork, dramatic lighting, atmospheric haze, strong depth, readable silhouettes, magical but not cute. Composition: inviting path leading into the forest, large ancient-tree silhouettes, glowing mushrooms as focal accents. No text, no UI, no logo, no watermark, no photorealism, no cartoon toy style, no neon overload.
+```
+
+Note for Eric: Save the result as: whispering-forest-twilight.png in /Users/aurora/Downloads/hermesworld-assets/zones/
+
+### D3: Mount Hermes Peak
+
+```text
+Create a wide cinematic 16:9 stylized painterly fantasy MMO concept art background of Mount Hermes peak. Scene: snow-capped mountain summit, cliffside path with carved stone steps, bronze guide markers, wind-bent banners, eagles circling above, distant clouds below, and a small glowing shrine or waypoint near the path. Use warm sunrise or sunset light on the snow and cliffs, with cool cyan-blue shadows in ice, stone cracks, and distant atmosphere. Style: premium browser-native fantasy RPG, painterly brushwork, dramatic lighting, atmospheric haze, epic scale, readable silhouettes, warm palette with cool shadow accents. Composition: cliffside path leading toward the peak, strong vertical mountain silhouette, eagles for scale. No text, no UI, no logo, no watermark, no photorealism, no modern equipment, no sci-fi guns.
+```
+
+Note for Eric: Save the result as: mount-hermes-peak.png in /Users/aurora/Downloads/hermesworld-assets/zones/
+
+### D4: Dungeon Entrance
+
+```text
+Create a wide cinematic 16:9 stylized painterly fantasy MMO concept art background of a HermesWorld dungeon entrance. Scene: cracked ancient stone archway built into a dark hillside, glowing cyan runes carved into the stones, low rolling mist, broken steps, bronze braziers with warm amber flames, moss, roots, scattered stones, and a deep shadowed passage beyond the arch. Style: premium browser-native fantasy RPG, painterly brushwork, dramatic lighting, atmospheric haze, warm amber firelight contrasted with cool cyan rune glow, high depth, readable silhouettes, dark fantasy mood. Composition: archway as central focal point, mist and path pulling the eye inward, foreground stones framing the entrance. No text, no UI, no logo, no watermark, no photoreal modern ruin, no horror gore, no neon overload.
+```
+
+Note for Eric: Save the result as: dungeon-entrance-runes.png in /Users/aurora/Downloads/hermesworld-assets/zones/

docs/hermesworld/FAQ.md

@@ -0,0 +1,70 @@
+# HermesWorld FAQ
+
+## What is HermesWorld?
+
+HermesWorld is a browser-native agent MMO inside the Hermes ecosystem. Humans and AI agents explore zones, complete quests, join parties/guilds, craft items, collect Sigils, and eventually compete in events and prize hunts.
+
+Start with [World Lore](lore/WORLD-LORE.md) or [Getting Started](guides/GETTING-STARTED.md).
+
+## Is this a game or an AI workspace?
+
+Yes. More usefully: it is a game-shaped interface for agent work. Zones organize tools, quests organize goals, companions organize delegation, and Sigils organize progress.
+
+## Do I need to install anything?
+
+The target is browser-first. HermesWorld can be embedded inside Hermes Workspace and hosted through HermesWorld.ai. Future installable/PWA clients may arrive later.
+
+## What class should I choose first?
+
+Choose the fantasy you want to inhabit:
+
+- Priest if you like support.
+- Guardian if you like protection.
+- Mage if you like power and control.
+- Rogue if you like secrets.
+- Engineer if you like building.
+- Oracle if you like planning.
+- Bard if you like social leverage.
+
+Your [agent companion](guides/AGENT-COMPANIONS.md) can cover gaps.
+
+## What are Sigils?
+
+Sigils are visible marks of progress: quest completions, unlocks, discoveries, class milestones, guild achievements, and sometimes validated prize eligibility. Read [Sigils Lore](lore/SIGILS-LORE.md).
+
+## Are agents autonomous?
+
+They can be, within limits. Companions should act with configured role, memory scope, permissions, and receipts. Valuable actions require validation or player confirmation.
+
+## Can agents play while I am offline?
+
+Planned, yes, but only for safe bounded work: scouting, summarizing, preparing plans, monitoring public boards. No risky trades, vault withdrawals, or prize claims without proper permission and validation.
+
+## How do guilds work?
+
+Guilds are humans plus their agents. They can have banners, halls, roles, chat, shared vaults, objectives, events, and rankings. See [Social](guides/SOCIAL.md) and [Factions Lore](lore/FACTIONS-LORE.md).
+
+## Are there real prizes?
+
+The vision includes ETH/SOL prize hunts or token-adjacent bonuses. Anything valuable must be server-authoritative and never hardcoded in the public client. Claims require validation, and wallet signature where applicable. See [Founders](guides/FOUNDERS.md).
+
+## What is the first quest?
+
+[Quest 001: Athena's Intro](walkthroughs/QUEST-001-ATHENAS-INTRO.md). Walk to Athena, speak with her, learn the basics, receive a starter Sigil fragment, and unlock the first companion quest.
+
+## What are the zones?
+
+- [Training Grounds](lore/ZONES-LORE.md#training-grounds) — learn.
+- [Forge](lore/ZONES-LORE.md#forge) — craft.
+- [Agora](lore/ZONES-LORE.md#agora) — gather.
+- [Grove](lore/ZONES-LORE.md#grove) — remember.
+- [Oracle](lore/ZONES-LORE.md#oracle) — plan.
+- [Arena](lore/ZONES-LORE.md#arena) — prove.
+
+## Is this finished?
+
+No. It is being built in public with swarm lanes: world/content, UI, art, mobile UX, gameplay systems, multiplayer/infra, and review/security. This docs tree is foundation material for in-game tooltips, onboarding, NPC dialog, and future static docs.
+
+## Where should new players begin?
+
+Read [Getting Started](guides/GETTING-STARTED.md), then follow [Quest 001](walkthroughs/QUEST-001-ATHENAS-INTRO.md).

docs/hermesworld/GAMEPLAY-SYSTEMS-BOUNDARIES.md

@@ -0,0 +1,158 @@
+# HermesWorld Lane B Gameplay Systems Boundaries
+
+Status: implementation contract for parallel swarm workers
+Scope: quest, event, NPC state, inventory, rewards, and agent-action APIs
+Source: `docs/hermesworld/SWARM-GAME-ARCHITECTURE.md`
+
+## Goal
+
+Make the game loop feel real without creating a giant shared branch. Workers should implement behind stable seams and only touch the files owned by their lane.
+
+## Ownership map
+
+| System | Owner files | May import from | Must not own |
+| --- | --- | --- | --- |
+| Contracts | `src/screens/playground/lib/gameplay-contracts.ts` | none / type-only | Runtime state mutation |
+| Quest engine | `src/screens/playground/lib/quest-engine.ts`, quest tests | `gameplay-contracts`, static quest data | React hooks, NPC copy, inventory UI |
+| Event bus/log | `src/screens/playground/lib/gameplay-events.ts`, event tests | `gameplay-contracts` | Quest definitions, reward calculations |
+| NPC state/dialog | `src/screens/playground/lib/npc-state.ts`, `npc-dialog.ts` | `gameplay-contracts`, event emitters | Inventory mutation, reward granting |
+| Inventory/rewards | `src/screens/playground/lib/inventory-rewards.ts`, reward tests | `gameplay-contracts`, item data | Quest completion decisions, NPC dialog text |
+| Agent actions | `src/screens/playground/lib/agent-actions.ts`, API route stubs later | `gameplay-contracts`, event bus | Prize oracle, direct secrets, UI orchestration |
+| React integration | `src/screens/playground/hooks/use-playground-rpg.ts` | all service modules | New business rules once extracted |
+
+Rule: static content can live in `playground-rpg.ts`/`npc-dialog.ts`; game rules should move into small pure modules with tests.
+
+## Runtime boundary
+
+Use one reducer-style state transition path:
+
+1. UI/NPC/agent produces a `GameplayEvent` or `AgentActionRequest`.
+2. Event/action validates against current `GameplayStateSnapshot`.
+3. Pure system returns a `GameplayPatch` plus optional follow-up events.
+4. React hook applies patches and displays toasts.
+5. Hosted/server routes may replay the same events later for authoritative multiplayer/prize flows.
+
+Do not let components directly grant items, complete quests, or unlock worlds except through the facade exposed by `usePlaygroundRpg`.
+
+## Event contract
+
+Events are facts that already happened. They should be append-only and serializable.
+
+Required MVP events:
+- `npc.talked` — player opened dialog with NPC.
+- `npc.choice_selected` — player chose a dialog option.
+- `quest.objective_completed` — objective completion accepted by quest engine.
+- `quest.completed` — all required objectives accepted.
+- `inventory.item_granted` — item added, idempotently.
+- `inventory.item_equipped` — equipment slot changed.
+- `world.entered` — player entered/unlocked zone.
+- `chat.sent` — local/world chat sent.
+- `combat.enemy_defeated` — enemy defeat accepted.
+- `agent.action_requested` / `agent.action_completed` / `agent.action_failed` — agent action lifecycle.
+
+Every event must include `id`, `type`, `createdAt`, `actorId`, and `source`. Event handlers must be idempotent because multiplayer/server replay will duplicate packets. Fun, because distributed systems eventually turn every game into accounting.
+
+## Quest boundary
+
+Quest engine owns:
+- objective matching from events
+- required vs optional objective completion
+- quest completion idempotency
+- emitting reward intents, not directly mutating inventory
+
+Quest engine does not own:
+- toast copy
+- NPC dialog text
+- item definitions
+- visual HUD order
+- prize/easter-egg secrets
+
+MVP API shape:
+
+```ts
+advanceQuests(snapshot, event): QuestAdvanceResult
+```
+
+`QuestAdvanceResult` returns completed objective ids, completed quest ids, and `RewardGrant[]` intents. Inventory/reward system applies those intents.
+
+## NPC state boundary
+
+NPC state owns:
+- per-NPC relationship flags
+- seen dialog node ids
+- choice availability predicates
+- cooldown/once-only choice enforcement
+- emitting events for selected choices
+
+NPC state does not own:
+- adding items to inventory
+- completing quests directly
+- unlocking worlds directly
+
+NPC dialog choices should move from imperative fields like `grantItems`/`completeQuest` toward declarative `effects: GameplayEffect[]`. During migration, keep old fields but normalize them to effects at the boundary.
+
+## Inventory and reward boundary
+
+Inventory/rewards owns:
+- idempotent item grants
+- stack/currency semantics when added
+- equipment slot validation
+- skill XP/title/world unlock application
+- reward toast descriptors
+
+Inventory/rewards does not own:
+- deciding whether a quest is complete
+- deciding whether an NPC choice is allowed
+- calling external prize services
+
+MVP rule: keep item ids public and harmless. Anything valuable uses a hosted prize oracle claim flow from Lane D, never client inventory.
+
+## Agent action API boundary
+
+Agent actions are gameplay verbs that may call Hermes later. They must be request/response objects, not ad hoc component callbacks.
+
+MVP actions:
+- `agent.ask_npc` — get dynamic NPC line/lore.
+- `agent.build_prompt` — turn player text into a Forge artifact summary.
+- `agent.summon_companion` — spawn temporary familiar metadata.
+- `agent.judge_duel` — evaluate Arena prompt duel result.
+- `agent.generate_lore` — create non-prize lore/zone flavor.
+
+Agent action handler owns:
+- schema validation
+- rate-limit metadata
+- safe public context assembly
+- status events
+
+Agent action handler must not own:
+- secrets/prize decisions
+- direct state mutation without returning `GameplayPatch`
+- raw model/provider selection inside UI components
+
+## MVP implementation order
+
+1. `gameplay-contracts.ts` — shared types only. Lowest conflict surface.
+2. `gameplay-events.ts` — event factory + idempotency helpers.
+3. `inventory-rewards.ts` — pure reward application; migrate duplicate reward code out of hook.
+4. `quest-engine.ts` — pure event-to-objective/quest advancement.
+5. `npc-state.ts` — normalize dialog effects, once-only choices, relationship flags.
+6. `agent-actions.ts` — local mock handler first; server/Hermes call later.
+7. Thin `usePlaygroundRpg` integration — hook becomes orchestration/glue, not game-law soup.
+
+## Parallel-worker rules
+
+- One worker per module above.
+- Each worker adds tests for its pure module before touching React.
+- No worker edits prize/claim code unless assigned Lane D.
+- No worker changes visual layout while extracting systems unless assigned Lane A.
+- Shared type changes happen only in `gameplay-contracts.ts` and should be backward-compatible by default.
+- Prefer additive adapters over rewriting `playground-rpg.ts` in one pass.
+
+## Acceptance criteria
+
+- New systems are serializable and deterministic.
+- Applying the same event twice does not double-grant rewards.
+- Quests produce reward intents; inventory applies them.
+- NPC choices emit effects/events; they do not mutate profile state directly.
+- Agent actions return patches/events and never embed secrets in client state.
+- `pnpm build` passes after each worker patch.

docs/hermesworld/GUILD-EVENT-CONTRACTS.md

@@ -0,0 +1,814 @@
+# HermesWorld Guild/Event/Economy Contracts
+
+Last updated: 2026-05-06
+
+## Goal
+
+Define safe client/server data contracts for HermesWorld guild creation, weekend wars, raids, leaderboards, Founders Vault, and chat trade. The client can render social/game/economy state, but all valuable state is server-authoritative. No prize/oracle secrets, payout rules, hidden reward tables, private grant reasons, anti-abuse thresholds, or signer credentials are client-visible.
+
+## Non-negotiable security rules
+
+1. Client input is an intent, never proof.
+2. Inventory, currency balances, guild permissions, war scores, raid rewards, event grants, and trade settlement are server-authoritative.
+3. Client-visible contracts may include public lore, public item metadata, cosmetic names, event schedules, visible scores, and generic claim states.
+4. Private services own eligibility, hidden reward tables, valuable grants, prize/oracle validation, anti-abuse scoring, payout queues, and audit trails.
+5. Any endpoint that mutates valuable state must be authenticated, idempotent, rate-limited, and backed by a private audit log.
+6. Valuable operations should use explicit request IDs/idempotency keys so retries do not duplicate grants or transfers.
+7. Do not trust client timestamps, positions, item IDs, quantities, wallet ownership, raid completion, war contribution, or leaderboard score.
+8. Do not leak the reason a valuable claim failed if that reason helps attackers enumerate valid states.
+
+## Shared primitives
+
+```ts
+type UUID = string
+type ISODateTime = string
+type Chain = 'eth' | 'sol'
+type CurrencyCode = 'coins' | 'aether' | 'eth' | 'sol'
+type PlayerId = string
+type AgentId = string
+type GuildId = string
+type ItemInstanceId = string
+type ItemDefinitionId = string
+type WalletAddress = string
+
+type PublicActorRef =
+  | { kind: 'player'; playerId: PlayerId; displayName: string }
+  | { kind: 'agent'; agentId: AgentId; displayName: string; ownerPlayerId: PlayerId }
+
+type MoneyAmount = {
+  currency: CurrencyCode
+  amountMinorUnits: string
+}
+
+type PublicItemStack = {
+  itemInstanceId?: ItemInstanceId
+  itemDefinitionId: ItemDefinitionId
+  displayName: string
+  rarity: 'common' | 'uncommon' | 'rare' | 'epic' | 'legendary' | 'founder' | 'event'
+  quantity: number
+  iconUrl: string
+  binding: 'none' | 'bind_on_pickup' | 'bind_on_equip' | 'account_bound' | 'guild_bound'
+  tradeable: boolean
+  cosmeticOnly: boolean
+}
+
+type Idempotency = {
+  requestId: UUID
+  clientCreatedAt: ISODateTime
+}
+
+type SafeMutationResponse<T> = {
+  ok: boolean
+  requestId: UUID
+  result?: T
+  publicError?: {
+    code: 'invalid_input' | 'auth_required' | 'permission_denied' | 'rate_limited' | 'conflict' | 'not_found' | 'temporarily_unavailable'
+    message: string
+  }
+}
+```
+
+Client-safe IDs are opaque. They must not encode reward tiers, grant reasons, inventory database row order, hidden seed data, or prize eligibility.
+
+## Auth/session model
+
+Client requests carry one of:
+
+```ts
+type GameSessionAuth = {
+  sessionToken: string // HttpOnly cookie preferred; never localStorage for privileged operations.
+}
+
+type WalletSignedSession = {
+  chain: Chain
+  address: WalletAddress
+  message: string
+  signature: string
+  nonceId: UUID
+}
+```
+
+Server responsibilities:
+- Resolve session to playerId.
+- Verify wallet signatures server-side.
+- Bind wallet sessions to player accounts server-side.
+- Enforce CSRF protection for cookie-based mutating routes.
+- Never accept playerId/guildId ownership claims from client without server lookup.
+
+## 1. Guild creation contract
+
+### Public guild shape
+
+```ts
+type GuildRole = 'founder' | 'leader' | 'officer' | 'raider' | 'trader' | 'member' | 'guest'
+
+type GuildPermission =
+  | 'invite_member'
+  | 'kick_member'
+  | 'edit_profile'
+  | 'manage_roles'
+  | 'queue_war'
+  | 'start_raid'
+  | 'manage_vault'
+  | 'post_announcement'
+
+type GuildPublicProfile = {
+  guildId: GuildId
+  slug: string
+  displayName: string
+  motto?: string
+  banner: {
+    emblemId: string
+    primaryColor: string
+    secondaryColor: string
+    frameId?: string
+  }
+  publicDescription?: string
+  level: number
+  xp: number
+  memberCount: number
+  agentCount: number
+  hallThemeId?: string
+  recruitment: 'open' | 'application' | 'invite_only' | 'closed'
+  tags: Array<'casual' | 'raiding' | 'pvp' | 'builders' | 'trading' | 'founders' | 'lore'>
+  createdAt: ISODateTime
+}
+
+type GuildMemberPublic = {
+  guildId: GuildId
+  actor: PublicActorRef
+  role: GuildRole
+  joinedAt: ISODateTime
+  publicContributionScore: number
+}
+```
+
+### Create guild
+
+Client -> server:
+
+```ts
+type CreateGuildRequest = Idempotency & {
+  displayName: string
+  slug: string
+  motto?: string
+  publicDescription?: string
+  banner: {
+    emblemId: string
+    primaryColor: string
+    secondaryColor: string
+    frameId?: string
+  }
+  recruitment: 'open' | 'application' | 'invite_only'
+  tags: GuildPublicProfile['tags']
+  founderActor: { kind: 'player'; playerId?: never }
+}
+```
+
+Server -> client:
+
+```ts
+type CreateGuildResponse = SafeMutationResponse<{
+  guild: GuildPublicProfile
+  viewerRole: GuildRole
+  viewerPermissions: GuildPermission[]
+}>
+```
+
+Server validation:
+- Authenticate current player.
+- Enforce one active founder guild per player unless admin-granted.
+- Validate name/slug length, profanity, impersonation, reserved names.
+- Validate banner IDs against public cosmetic catalog.
+- Charge creation fee server-side if enabled; never trust client balance.
+- Grant founder role and audit the creation.
+
+Private-only guild fields:
+- normalizedName collision index
+- moderation flags
+- creation IP hash / device risk
+- payment/fee transaction IDs
+- abuse score
+- internal notes
+- guild vault ledger
+- invite/application fraud signals
+
+## 2. Guild membership and agent companion contract
+
+```ts
+type GuildInviteRequest = Idempotency & {
+  guildId: GuildId
+  targetPlayerHandle: string
+  requestedRole?: Exclude<GuildRole, 'founder' | 'leader'>
+}
+
+type GuildInviteResponse = SafeMutationResponse<{
+  inviteId: UUID
+  expiresAt: ISODateTime
+  publicStatus: 'sent' | 'already_member' | 'blocked'
+}>
+
+type AddAgentToGuildRequest = Idempotency & {
+  guildId: GuildId
+  agentId: AgentId
+  intendedRole: 'scout' | 'scribe' | 'builder' | 'trader' | 'combat' | 'healer'
+}
+
+type AddAgentToGuildResponse = SafeMutationResponse<{
+  guildId: GuildId
+  agent: PublicActorRef
+  publicCapabilities: string[]
+  contributionMultiplier: number
+}>
+```
+
+Server rules:
+- Player must own/control the agent.
+- Guild must have available agent seats.
+- Agent capabilities are public summaries only; model credentials/provider configs remain private.
+- Offline agent action limits are server-side, not client-configurable.
+
+## 3. Guild vault contract
+
+The guild vault is distinct from Founders Vault. It is shared, permissioned, and ledger-backed.
+
+```ts
+type GuildVaultSlotPublic = {
+  guildId: GuildId
+  slotId: UUID
+  item?: PublicItemStack
+  lockedBy?: PublicActorRef
+  publicNote?: string
+}
+
+type GuildVaultDepositRequest = Idempotency & {
+  guildId: GuildId
+  itemInstanceId: ItemInstanceId
+  quantity: number
+  publicNote?: string
+}
+
+type GuildVaultWithdrawRequest = Idempotency & {
+  guildId: GuildId
+  itemInstanceId: ItemInstanceId
+  quantity: number
+  destination: 'player_inventory' | 'raid_loadout' | 'guild_war_loadout'
+}
+```
+
+Server rules:
+- Atomic transfer from player inventory to guild vault or back.
+- Permission check for withdraw/manage.
+- Ledger every mutation with actor, before/after, reason, requestId.
+- No client-writeable item stats.
+
+Private-only:
+- Full vault ledger
+- moderation/admin holds
+- dupe-detection tags
+- item provenance graph
+- risk scoring
+
+## 4. Weekend guild wars contract
+
+Weekend wars are scheduled, server-scored, and spectator-friendly. The client renders schedule, visible objectives, live scoreboard, and public feed. The server decides scoring.
+
+### Public event schedule
+
+```ts
+type WeekendWarPublicEvent = {
+  eventId: UUID
+  seasonId: string
+  mapId: string
+  displayName: string
+  startsAt: ISODateTime
+  endsAt: ISODateTime
+  registrationClosesAt: ISODateTime
+  status: 'scheduled' | 'registration_open' | 'live' | 'scoring_finalizing' | 'final' | 'cancelled'
+  participantCap: number
+  publicRulesVersion: string
+  visibleObjectives: Array<{
+    objectiveId: string
+    displayName: string
+    kind: 'obelisk' | 'sigil' | 'guild_hall_relic' | 'escort' | 'boss'
+    mapRegionId: string
+    publicScoreHint: string
+  }>
+  publicRewards: Array<{
+    rankBand: 'winner' | 'top_3' | 'top_10' | 'participation'
+    rewardPreview: string
+    cosmeticOnly: boolean
+  }>
+}
+```
+
+### Register for war
+
+```ts
+type RegisterGuildWarRequest = Idempotency & {
+  guildId: GuildId
+  eventId: UUID
+  declaredRoster: Array<{ actorKind: 'player' | 'agent'; actorId: string }>
+}
+
+type RegisterGuildWarResponse = SafeMutationResponse<{
+  registrationId: UUID
+  eventId: UUID
+  guildId: GuildId
+  publicStatus: 'registered' | 'waitlisted' | 'rejected'
+  rosterPublic: GuildMemberPublic[]
+}>
+```
+
+Server scoring input:
+
+```ts
+type WarActionIntent = Idempotency & {
+  eventId: UUID
+  guildId: GuildId
+  actorId: string
+  actionType: 'capture_objective' | 'defend_objective' | 'damage_relic' | 'repair_relic' | 'support_ally' | 'scout_ping'
+  targetObjectiveId?: string
+  clientObservedAt: ISODateTime
+  clientContext: {
+    mapRegionId: string
+    positionBucket?: string
+    animationState?: string
+  }
+}
+```
+
+Server public state:
+
+```ts
+type WarScoreboardPublic = {
+  eventId: UUID
+  status: WeekendWarPublicEvent['status']
+  updatedAt: ISODateTime
+  guildScores: Array<{
+    guildId: GuildId
+    guildName: string
+    banner: GuildPublicProfile['banner']
+    publicScore: number
+    rank: number
+    heldObjectives: string[]
+    publicMomentum: 'falling' | 'stable' | 'rising'
+  }>
+  publicFeed: Array<{
+    feedId: UUID
+    occurredAt: ISODateTime
+    message: string
+    guildId?: GuildId
+    objectiveId?: string
+  }>
+}
+```
+
+Server rules:
+- Ignore direct score values from client.
+- Score from validated server events, objective state machine, anti-cheat, and rate limits.
+- Publish delayed/smoothed public scores if needed to prevent automation/sniping.
+- Rewards are granted only after finalization job.
+
+Private-only war data:
+- scoring weights
+- anti-cheat thresholds
+- hidden tie breakers
+- raw action stream
+- risk flags
+- delayed finalization internals
+- valuable reward eligibility
+- oracle/prize flags
+
+## 5. Raids/dungeons contract
+
+Raids are party instances with server-authoritative completion, loot, and contribution.
+
+```ts
+type RaidPublicDefinition = {
+  raidId: string
+  displayName: string
+  minPartySize: number
+  maxPartySize: number
+  allowedAgentSlots: number
+  recommendedRoles: Array<'tank' | 'healer' | 'damage' | 'support' | 'scout'>
+  publicBosses: Array<{
+    bossId: string
+    displayName: string
+    publicMechanics: string[]
+  }>
+  publicLootPreview: Array<{
+    itemDefinitionId: ItemDefinitionId
+    displayName: string
+    rarity: PublicItemStack['rarity']
+    dropHint: string
+  }>
+  lockout: {
+    kind: 'none' | 'daily' | 'weekly' | 'seasonal'
+    resetsAt?: ISODateTime
+  }
+}
+
+type CreateRaidInstanceRequest = Idempotency & {
+  raidId: string
+  guildId?: GuildId
+  partyActorIds: string[]
+  difficulty: 'story' | 'normal' | 'heroic'
+}
+
+type CreateRaidInstanceResponse = SafeMutationResponse<{
+  raidInstanceId: UUID
+  raid: RaidPublicDefinition
+  party: PublicActorRef[]
+  status: 'forming' | 'ready' | 'in_progress'
+}>
+
+type RaidActionIntent = Idempotency & {
+  raidInstanceId: UUID
+  actorId: string
+  actionType: 'attack' | 'heal' | 'shield' | 'interrupt' | 'scout' | 'use_item' | 'agent_assist'
+  targetId?: string
+  clientObservedAt: ISODateTime
+  clientContext?: Record<string, string | number | boolean>
+}
+
+type RaidCompletionPublic = {
+  raidInstanceId: UUID
+  raidId: string
+  status: 'failed' | 'completed'
+  completedAt?: ISODateTime
+  publicGrade: 'bronze' | 'silver' | 'gold' | 'mythic'
+  publicStats: {
+    durationSeconds: number
+    deaths: number
+    bossKills: number
+  }
+  lootRolls?: Array<{
+    lootRollId: UUID
+    item: PublicItemStack
+    eligibleActors: PublicActorRef[]
+    publicState: 'rolling' | 'awarded' | 'expired'
+    winner?: PublicActorRef
+  }>
+}
+```
+
+Server rules:
+- Server controls HP, boss state, lockouts, completion, loot rolls, XP, currency grants.
+- Client may render boss mechanics and send action intents only.
+- Agent companions can fill roles but cannot bypass lockouts or loot eligibility.
+- Rare drops get item provenance tags server-side.
+
+Private-only raid data:
+- exact loot tables/drop rates
+- rare item seed
+- anti-cheat contribution thresholds
+- valuable prize eligibility
+- hidden boss state mutations
+- private model/agent execution traces
+
+## 6. Leaderboards contract
+
+Leaderboards are public ranking surfaces with private score provenance.
+
+```ts
+type LeaderboardKind =
+  | 'guild_war_season'
+  | 'raid_clear_time'
+  | 'guild_xp'
+  | 'market_reputation'
+  | 'crafting_competition'
+  | 'lore_trial'
+
+type LeaderboardPublicEntry = {
+  leaderboardId: UUID
+  kind: LeaderboardKind
+  seasonId: string
+  rank: number
+  actor: PublicActorRef | { kind: 'guild'; guildId: GuildId; displayName: string; banner: GuildPublicProfile['banner'] }
+  publicScore: number
+  publicScoreLabel: string
+  badgeIds: string[]
+  updatedAt: ISODateTime
+}
+
+type GetLeaderboardResponse = {
+  leaderboardId: UUID
+  kind: LeaderboardKind
+  seasonId: string
+  generatedAt: ISODateTime
+  entries: LeaderboardPublicEntry[]
+  viewerRank?: LeaderboardPublicEntry
+}
+```
+
+Server rules:
+- Scores are generated from private event logs, not client submission.
+- Use delayed publication for prize-sensitive competitions.
+- Manual moderation can hide entries; public response should say generic “entry under review”.
+
+Private-only:
+- score calculation formulas if exploitable
+- hidden disqualification reasons
+- raw event logs
+- moderation notes
+- prize/oracle mappings
+- reward inventory
+
+## 7. Founders Vault / event inventory contract
+
+Founders Vault is an event inventory tab for founder gifts, purchases, compensations, season transitions, and website-store deliveries. It is not client-writeable.
+
+```ts
+type EventInventoryGrantPublic = {
+  grantId: UUID
+  grantType: 'founder_gift' | 'purchase_delivery' | 'compensation' | 'season_reward' | 'event_reward'
+  displayTitle: string
+  displayMessage: string
+  grantedAt: ISODateTime
+  expiresAt?: ISODateTime
+  claimState: 'unclaimed' | 'claimed' | 'expired' | 'revoked' | 'pending'
+  previewItems: PublicItemStack[]
+  previewCurrencies: MoneyAmount[]
+  badgeCount: number
+}
+
+type FoundersVaultPublic = {
+  playerId: PlayerId
+  tabName: 'Founders Vault' | 'Event Mail'
+  unclaimedCount: number
+  grants: EventInventoryGrantPublic[]
+}
+
+type ClaimEventInventoryGrantRequest = Idempotency & {
+  grantId: UUID
+}
+
+type ClaimEventInventoryGrantResponse = SafeMutationResponse<{
+  grantId: UUID
+  claimState: 'claimed' | 'pending'
+  deliveredItems: PublicItemStack[]
+  deliveredCurrencies: MoneyAmount[]
+  publicMessage: string
+}>
+```
+
+Private grant API; never browser-callable:
+
+```ts
+type PrivateCreateEventGrantRequest = {
+  serviceRequestId: UUID
+  targetPlayerId: PlayerId
+  grantType: EventInventoryGrantPublic['grantType']
+  reasonCode: 'name_reservation' | 'manual_founder_approve' | 'store_purchase' | 'compensation' | 'season_transition' | 'admin_test'
+  sourceRef?: string
+  items: Array<{ itemDefinitionId: ItemDefinitionId; quantity: number; privateRollSeed?: string }>
+  currencies: MoneyAmount[]
+  expiresAt?: ISODateTime
+  operatorId?: string
+}
+```
+
+Server rules:
+- Gift granting via private API only.
+- Claims are idempotent and atomic: grant state changes and inventory/currency delivery happen in one transaction.
+- Purchase delivery requires verified payment/webhook server-side.
+- Founder status/badges are public only after private grant approval.
+
+Private-only Founders Vault data:
+- grant reason code when sensitive
+- manual approver/operator ID
+- payment provider transaction IDs
+- fraud/risk status
+- private roll seed
+- inventory ledger before/after
+- revocation notes
+- store webhook secrets
+
+## 8. Chat trade window contract
+
+Chat trade is a secure two-party offer window opened from chat, e.g. `/trade @user`. Both sides add items/currency, lock, then confirm. Settlement is atomic server-side.
+
+```ts
+type TradeWindowPublicState = {
+  tradeId: UUID
+  status: 'invited' | 'open' | 'locked' | 'confirming' | 'settled' | 'cancelled' | 'expired' | 'disputed'
+  createdAt: ISODateTime
+  expiresAt: ISODateTime
+  participants: [PublicActorRef, PublicActorRef]
+  offers: Record<PlayerId, {
+    items: PublicItemStack[]
+    currencies: MoneyAmount[]
+    locked: boolean
+    confirmed: boolean
+    publicWarnings: Array<'balance_changed' | 'item_unavailable' | 'high_value_trade' | 'new_counterparty' | 'recent_offer_change'>
+  }>
+  lastChangedBy?: PublicActorRef
+  lastChangedAt: ISODateTime
+}
+
+type OpenTradeRequest = Idempotency & {
+  targetPlayerHandle: string
+  source: 'chat_command' | 'profile_button' | 'market_listing'
+}
+
+type UpdateTradeOfferRequest = Idempotency & {
+  tradeId: UUID
+  items: Array<{ itemInstanceId: ItemInstanceId; quantity: number }>
+  currencies: MoneyAmount[]
+}
+
+type LockTradeOfferRequest = Idempotency & {
+  tradeId: UUID
+  lock: boolean
+}
+
+type ConfirmTradeRequest = Idempotency & {
+  tradeId: UUID
+  confirm: true
+  visibleOfferDigest: string
+}
+
+type TradeMutationResponse = SafeMutationResponse<{
+  trade: TradeWindowPublicState
+}>
+```
+
+Settlement model:
+- Any offer update unlocks both participants and clears confirmations.
+- Client displays previews, warnings, and digest.
+- Server recomputes digest from canonical offer state.
+- Server checks item ownership, locks item instances, checks balances, validates binding/tradeability, enforces limits, and transfers atomically.
+- Hard currency trades use escrow/settlement service; client never submits raw transfer truth.
+- Agent-mediated trading can propose offers but cannot confirm above player-defined caps.
+
+Private-only trade data:
+- risk score
+- anti-RMT rules
+- high-value thresholds
+- escrow private state
+- compliance/KYC flags
+- raw wallet/rpc settlement internals
+- dispute/moderation notes
+- participant IP/device hashes
+
+## 9. Public event feed contract
+
+```ts
+type PublicWorldFeedEvent = {
+  feedId: UUID
+  kind: 'guild_created' | 'war_objective_captured' | 'raid_completed' | 'leaderboard_finalized' | 'founder_gift_arrived' | 'market_milestone'
+  occurredAt: ISODateTime
+  headline: string
+  body?: string
+  actor?: PublicActorRef | { kind: 'guild'; guildId: GuildId; displayName: string }
+  guildId?: GuildId
+  eventId?: UUID
+  iconUrl?: string
+}
+```
+
+Feed redaction rules:
+- No exact reward amounts for prize-bearing events until publicly announced.
+- No private grant reasons.
+- No trade counterparty details unless both parties opted into public sharing.
+- No oracle status.
+- No anti-cheat/moderation hints.
+
+## 10. Private audit/event ledger
+
+Every valuable mutation writes a private audit event.
+
+```ts
+type PrivateAuditEvent = {
+  auditId: UUID
+  requestId: UUID
+  actorPlayerId?: PlayerId
+  actorAgentId?: AgentId
+  action:
+    | 'guild.create'
+    | 'guild.invite'
+    | 'guild.vault.deposit'
+    | 'guild.vault.withdraw'
+    | 'war.register'
+    | 'war.score_event'
+    | 'war.reward_finalize'
+    | 'raid.instance_create'
+    | 'raid.completion'
+    | 'raid.loot_award'
+    | 'leaderboard.finalize'
+    | 'event_grant.create'
+    | 'event_grant.claim'
+    | 'trade.open'
+    | 'trade.offer_update'
+    | 'trade.settle'
+  entityType: 'guild' | 'war' | 'raid' | 'leaderboard' | 'grant' | 'trade' | 'inventory' | 'wallet'
+  entityId: UUID | string
+  beforeHash?: string
+  afterHash?: string
+  privateMetadata: Record<string, unknown>
+  createdAt: ISODateTime
+}
+```
+
+This ledger is never exposed directly to the browser. Public histories are separately projected/redacted.
+
+## 11. API surface summary
+
+Public/browser-callable:
+- GET /api/hermesworld/guilds/:guildId
+- POST /api/hermesworld/guilds/create
+- POST /api/hermesworld/guilds/:guildId/invites
+- POST /api/hermesworld/guilds/:guildId/agents
+- GET /api/hermesworld/guilds/:guildId/vault
+- POST /api/hermesworld/guilds/:guildId/vault/deposit
+- POST /api/hermesworld/guilds/:guildId/vault/withdraw
+- GET /api/hermesworld/events/weekend-wars
+- POST /api/hermesworld/events/weekend-wars/:eventId/register
+- POST /api/hermesworld/events/weekend-wars/:eventId/actions
+- GET /api/hermesworld/events/weekend-wars/:eventId/scoreboard
+- GET /api/hermesworld/raids
+- POST /api/hermesworld/raids/instances
+- POST /api/hermesworld/raids/:raidInstanceId/actions
+- GET /api/hermesworld/leaderboards/:leaderboardId
+- GET /api/hermesworld/founders-vault
+- POST /api/hermesworld/founders-vault/:grantId/claim
+- POST /api/hermesworld/trades/open
+- POST /api/hermesworld/trades/:tradeId/offer
+- POST /api/hermesworld/trades/:tradeId/lock
+- POST /api/hermesworld/trades/:tradeId/confirm
+- GET /api/hermesworld/feed
+
+Private service-only:
+- POST /private/hermesworld/event-grants/create
+- POST /private/hermesworld/event-grants/revoke
+- POST /private/hermesworld/war/finalize-score
+- POST /private/hermesworld/war/grant-rewards
+- POST /private/hermesworld/raid/finalize-loot
+- POST /private/hermesworld/leaderboards/finalize
+- POST /private/hermesworld/trades/settle-hard-currency
+- POST /private/hermesworld/oracle/validate-prize-eligibility
+- POST /private/hermesworld/audit/events
+
+## 12. What must never be public
+
+Never ship any of this in client code, static JSON, sourcemaps, public KV, public API responses, public logs, screenshots, fixtures, or docs intended for players:
+
+- prize/oracle secrets
+- private oracle URLs or service tokens
+- treasury wallet private keys
+- payout signer keys
+- RPC credentials
+- wallet seed phrases
+- JWT/HMAC/session signing secrets
+- payment webhook secrets
+- store webhook raw payload secrets
+- private reward inventory and prize counts
+- ETH/SOL payout amounts before approval/public announcement
+- exact prize-bearing event mappings
+- exact hidden reward tables/drop rates for valuable items
+- weekend war scoring weights if exploitable
+- hidden tie-breakers
+- anti-cheat thresholds
+- RMT/fraud scoring rules
+- KYC/compliance provider tokens
+- moderation/admin notes
+- private grant reason codes when sensitive
+- payment transaction details
+- item provenance graph if exploitable
+- raw audit ledger
+- raw IP/device identifiers
+- non-redacted wallet risk data
+- private model/provider credentials for agents
+- offline agent spending caps beyond public user-configured values
+- internal admin endpoints
+- debug bypasses
+- private seeds/salts/commitments before reveal
+- database connection strings
+- any environment variable named or prefixed: PRIVATE_, ORACLE_, TREASURY_, WALLET_, SIGNER_, HMAC_, JWT_, SESSION_, RPC_, PAYMENT_, STRIPE_, KYC_, ADMIN_
+
+## 13. Minimal implementation order
+
+1. Add shared TypeScript schemas for public contract types.
+2. Stub public GET endpoints with static/mock data only.
+3. Add private audit helper before mutating endpoints.
+4. Implement guild creation with server-side permission and idempotency.
+5. Implement Founders Vault read + private grant + idempotent claim.
+6. Implement chat trade state machine with soft-currency/items only.
+7. Add weekend war schedule and public scoreboard projection.
+8. Add raid definition and instance skeleton.
+9. Add leaderboard projection from private finalized scores.
+10. Add hard-currency escrow/prize-oracle integrations only behind private services.
+
+## 14. Acceptance checks
+
+A patch touching these systems should pass these checks before review:
+
+- No client file contains oracle/prize/treasury/private env names except as denylist tests/docs.
+- No client response includes private reason codes.
+- Every valuable mutation has requestId/idempotency.
+- Every valuable mutation writes private audit event.
+- Inventory/currency/trade settlement are atomic server operations.
+- Public leaderboard/war/raid data is a projection, not the raw scoring/event log.
+- Founders Vault grants cannot be created from browser-callable endpoints.
+- Trade confirmation uses server recomputed digest, not client offer truth.

docs/hermesworld/GUILDS-AGENTS-COMPANION-ECONOMY.md

@@ -0,0 +1,143 @@
+# HermesWorld — Guilds + Agent Companions + Economy
+
+Last updated: 2026-05-06
+
+Reference graphic: `/Users/aurora/Desktop/roadmap hermesworld .png`
+
+## Unlock insight
+
+The guild is not only humans. The guild is **humans + their agents**.
+
+Players bring their agents into HermesWorld, level with them, quest with them, trade with them, and build complementary party compositions.
+
+Example:
+- Human player: Priest / Healer
+- Friend/player: Mage / Promptcaster
+- Agent companion: Scout Agent finds secrets
+- Agent companion: Builder Agent crafts upgrades
+- Guild role: Scribe Agent records raid notes
+
+This solves the MMO loneliness problem: you always have someone to play with, because your agent can party with you.
+
+## Class + companion pairing
+
+Human classes:
+- Priest / Healer
+- Guardian / Tank
+- Mage / Promptcaster
+- Rogue / Scout
+- Engineer / Builder
+- Oracle / Analyst
+- Bard / Social
+
+Agent companions:
+- Scout Agent
+- Scribe Agent
+- Builder Agent
+- Trader Agent
+- Combat Agent
+- Healer Agent
+
+Design rule:
+- humans choose fantasy identity
+- agents fill tactical gaps
+- party/guild builds become complementary
+
+## Gameplay loops
+
+### Human + agent leveling
+
+- human gains XP from quests, raids, minigames, guild events
+- agent companion gains specialization XP from actions
+- companion unlocks abilities that map to its role
+- companion can eventually act while user is offline, within limits
+
+### Trading with agents
+
+- Trader Agent can price/check items, manage simple trades, propose market actions
+- Builder Agent can craft/upgrade tools
+- Scribe Agent logs deal terms and guild vault changes
+- valuable trades require server validation and anti-abuse rules
+
+### Guild composition
+
+Guilds want mixed roles:
+- tanks/frontline
+- healers/support
+- mages/damage
+- scouts/discovery
+- engineers/crafters
+- oracles/strategy
+- agents as support multipliers
+
+## Monetization thesis
+
+Primary revenue options:
+
+1. Guild membership / season access
+   - paid guild creation or premium guild halls
+   - guild war participation tiers
+   - season pass for cosmetics/rewards/events
+
+2. Convenience currency
+   - faster leveling
+   - cosmetics
+   - crafting boosts
+   - guild hall decorations
+   - companion skins/modules
+
+3. Premium agent companions
+   - extra companion slots
+   - advanced companion behaviors
+   - model/provider integrations
+   - guild agent seats
+
+4. Creator/guild economy
+   - paid rooms/minigames
+   - guild cosmetics
+   - tournament/event entries
+
+Hard rule:
+- avoid obvious pay-to-win in competitive guild wars
+- paid boosts should accelerate progress or cosmetics, not destroy fairness
+- prize claims remain server-authoritative
+
+## UI modules from the reference graphic
+
+Build these as game surfaces:
+
+- Class selection screen
+- Agent companion roster
+- Guild systems hub
+- Guild chat
+- Shared vault
+- Weekend wars map
+- Leaderboards
+- Season pass/rewards
+- Epic events panel
+
+## v0.3-v0.6 path
+
+### v0.3
+- class identity placeholders
+- companion role concepts
+- guild systems graphic/landing surface
+- Agora hub visual upgrade
+
+### v0.4
+- player class selection
+- first companion agent role
+- class/companion XP
+- simple party/companion action loop
+
+### v0.5
+- guild creation
+- guild chat/guild hall prototype
+- shared vault UI mock
+- leaderboard skeleton
+
+### v0.6
+- weekend event prototype
+- guild war map
+- season pass/cosmetic reward track
+- private prize oracle integration

docs/hermesworld/INGAME-TARGET-SPEC.md

@@ -0,0 +1,163 @@
+# HermesWorld — In-Game Target Spec
+
+Last updated: 2026-05-06 02:22 EDT
+
+Reference: `docs/hermesworld/reference-images/INGAME-TARGET-AGORA.png`
+
+This is the **playable view** the marketing graphic implies.
+When a user is *in* HermesWorld, this is what their screen should look like.
+
+---
+
+## What the reference shows
+
+A circular plaza in Agora Commons:
+- isometric/over-the-shoulder camera (closer to high 3/4 than top-down)
+- central stone monument with a gold pyramid finial, ringed by lit torches
+- radial cobblestone tiles with rune circles
+- benches, foliage, lanterns lining the edge
+- merchant stalls (red/blue tents) with crates and barrels
+- 6 NPCs around the plaza, each with a colored name tag
+- 1 player avatar (Eric) center-stage with a name pill
+- a wisp/sparkle near front-right (collectible/quest cue)
+
+### HUD layout
+- **Top-left**: player card
+  - portrait
+  - name "Eric"
+  - zone subtitle "TRAINING GROUNDS"
+  - XP "75 - next 25"
+  - 4 stat bubbles: HP 100, MP 50, SP 80, XP 75
+- **Top-center**: objective banner
+  - icon + label "OBJECTIVE — Move and Speak"
+  - sub-text "Walk to Athena and speak with her. Athena waits by the Arrival Circle."
+- **Top-right**: minimap "AGORA COMMONS"
+  - circular map
+  - YOU marker
+  - Portal marker
+- **Mid-left edge**: small ambient sticker "Hermes Guide" (helper card / NPC poke)
+- **Right edge**: vertical icon rail (settings, fullscreen, share, party, etc.)
+- **Bottom-left**: chat panel
+  - "CHAT - 4 ONLINE - 3 NPC LOCAL-ONLY"
+  - colored NPC tags on speakers
+  - chat input box with SEND button
+- **Bottom-center**: ability bar
+  - HP/MP/SP triple bar on the left
+  - 4 ability slots with cooldown timers/icons + 1 modifier
+- **NPC name tags**: floating above each NPC with role
+  - "Athena - Sage", "Apollo", "Nora - Piper", "Silas - Guard", "Dorian - Quartermaster"
+- **Speech popups**: ambient lines over NPC heads
+  - "Starter kit, cheap and proud."
+  - "gm builders"
+
+### Mood
+- warm golden hour lighting
+- premium 3D rendered look (Genshin / Honkai / Dragon Quest XII territory)
+- crisp UI overlays with glassy panels and warm inner glow
+- soft particle ambience (wisps, dust motes near torches)
+
+---
+
+## Why this matters
+
+The marketing graphic (`MASTER-PRODUCT-GRAPHIC.png`) is what the **website/store page** should look like.
+
+This in-game target (`INGAME-TARGET-AGORA.png`) is what the **playable game** should look like.
+
+Both must be honored. They should feel like the same product.
+
+---
+
+## Style locks
+
+- **Camera**: 3/4 isometric, slight rotation, ~45-50° pitch
+- **Lighting**: warm golden hour with rim light on characters
+- **Ground**: hand-painted cobblestones with rune circle inlays
+- **Props**: stylized stone, wood, fabric, bronze details
+- **Characters**: chibi-leaning proportions, capes, robes, Dragon Quest x Genshin energy
+- **NPCs**: distinct silhouettes, color-coded by faction/role
+- **HUD**: dark glassy chrome, gold/amber accents, white text, slight bevel
+- **Name tags**: pill-shaped, dark with light text, role suffix
+- **Objective banner**: dark slab top-center, icon on left, two-line copy
+- **Minimap**: circular, dark inner, glowing landmarks, small markers
+- **Chat**: 5-color tags for source kind (NPC, player, system), monospace-ish UI
+
+---
+
+## Asset list driven by this image
+
+### 3D / world
+- circular plaza floor (cobblestones, rune circles)
+- central monument (stone tiers + gold pyramid finial)
+- torches (low + tall)
+- lanterns
+- benches
+- crates & barrels
+- merchant stalls (red, blue, green roofs)
+- foliage clumps
+- dirt path tiles bordering grass
+- portal arch (used in nearby image)
+- atmospheric particles
+
+### Characters / agents
+- player avatar template, with class swaps:
+  - Priest, Guardian, Mage, Rogue, Engineer, Oracle, Bard
+- NPC roster (Agora):
+  - Athena - Sage
+  - Apollo
+  - Nora - Piper
+  - Silas - Guard
+  - Dorian - Quartermaster
+  - Hermes Guide (helper)
+- agent companions per the marketing graphic
+
+### UI
+- player card panel
+- stat bubbles (HP/MP/SP/XP)
+- objective banner
+- minimap with markers
+- right-rail icon set (settings, fullscreen, share, party, social)
+- chat panel
+- ability bar w/ slot frames + cooldown
+- name tag pills
+- speech bubbles
+- toast cards
+
+### FX
+- torch flames + glow
+- wisps / sparkles
+- dust motes
+- footstep particles
+
+---
+
+## Engineering targets
+
+- Camera: orthographic-ish 3D in Three.js / R3F
+- Asset format: glTF/GLB with optimized textures (KTX2/Basis)
+- Shaders: stylized PBR + rim light + cheap fog
+- Performance: 60fps on M-series, 30fps target on midrange laptops
+- Mobile: simplify chat panel + minimap, keep ability bar
+
+---
+
+## Realism loop on this view
+
+For every iteration:
+1. take the current playable Agora screenshot
+2. diff against `INGAME-TARGET-AGORA.png`
+3. list the top 3 visible differences (camera, lighting, monument, torches, NPCs, HUD, chat panel, etc.)
+4. write smallest patch
+5. screenshot again
+6. repeat
+
+This is how we ratchet from current state to target without rewriting the engine.
+
+---
+
+## v0.3 -> v0.6 milestones tied to this image
+
+- **v0.3**: HUD layout matches (player card + objective + minimap + chat + ability bar)
+- **v0.4**: 3D plaza ring + central monument + torches in correct visual style
+- **v0.5**: NPCs with name tag pills and ambient speech, real movement
+- **v0.6**: stalls, crates, lanterns, full warm lighting pass, particles

docs/hermesworld/MASTER-PLAN.md

@@ -0,0 +1,185 @@
+# HermesWorld — Master Plan (Single Source of Truth)
+
+Last updated: 2026-05-06 02:20 EDT
+Owner: Eric (vision/product/taste)
+Orchestrator: Opus (review, swarm direction, integration)
+Workers: gpt-5.5 swarms (deep build), 4090/PC1, rented GPU as needed
+
+This document survives compaction and re-spawns.
+If you are a future agent: read this first.
+
+---
+
+## 1. Identity
+
+HermesWorld = the first **Agentic MMO**.
+
+- Roblox + WoW + Rohan + AI agents
+- Humans + their AI agents are guildmates
+- Browser-native first, downloadable later
+- Built by a single founder + agent swarm
+- Acquisition narrative: first AI-agent video game company
+
+Two locked references:
+- **Marketing/store page spec**: `docs/hermesworld/reference-images/MASTER-PRODUCT-GRAPHIC.png`
+- **Playable in-game spec**: `docs/hermesworld/reference-images/INGAME-TARGET-AGORA.png`
+
+The marketing graphic is what the website looks like. The in-game target is what the actual game looks like when playing. Both must be honored. See `INGAME-TARGET-SPEC.md` for the full breakdown of HUD, layout, NPCs, props, lighting, and milestone bindings.
+
+## 2. Vision pillars (from the master graphic)
+
+- **Choose Your Class** — 7 human classes
+  - Priest / Healer
+  - Guardian / Tank
+  - Mage / Promptcaster
+  - Rogue / Scout
+  - Engineer / Builder
+  - Oracle / Analyst
+  - Bard / Social
+
+- **AI Agent Companions** — 6 agent classes
+  - Scout, Scribe, Builder, Trader, Combat, Healer
+  - Slogan: "Your Guild. Your Agents. Your Advantage."
+
+- **Guild Systems**
+  - Guild Halls (build & customize)
+  - Banners
+  - Guild Chat
+  - Guild Objectives
+  - Shared Vault
+  - Weekend Wars
+  - Raids
+  - Leaderboards
+  - Seasonal Rewards
+
+- **Epic Events**
+  - Capture Obelisks / Sigils (map control)
+  - Guild Hall Defense
+  - Boxing Arena
+  - more added per season
+
+- **Identity slogans**
+  - "Your World. Your Guild. Your Legacy."
+  - "One World. Many Legends. Endless Adventures."
+
+- **Platform pillars**
+  - Browser-native (no downloads)
+  - Real-time multiplayer
+  - Player-driven economy
+  - Decentralized ownership
+  - Season pass (Season 1: Dawn of Legends)
+
+## 3. Operating model
+
+- **Eric**: product taste, X presence, vision pivots, money/GPU calls
+- **Opus orchestrator**: swarm direction, integration, review, anti-spaghetti gate, planning, content/comm
+- **gpt-5.5 swarms**: art realism loop, gameplay systems, integrations, infra, prize lane
+- **GPU lane**: PC1 (4090) + rented A100/H100 for HY-World 2.0, Hunyuan, Meshy, Tripo, large imagegen batches
+- **Coin fees ($6k+)** → buys GPU time, asset gen credits, CDN, contractor reviewers
+
+Anti-drift gate (every output runs through this):
+> Does this serve **Agentic MMO with humans + agents as guildmates**?
+> If yes → ship. If no → reshape or park.
+
+## 4. Repos
+
+- `outsourc-e/hermes-workspace` — public (browser game lives here)
+- `outsourc-e/hermesworld-game` — **private** (issues, internal specs, prize logic, secrets, roadmap)
+- `outsourc-e/controlsuite` — desktop client
+- `ocplatform/ocplatform` — agent runtime
+- `ocplatform/ocplatform-control-ui` — webchat surface
+
+## 5. Asset replacement waves (right order)
+
+We replace HermesWorld's art batch by batch, never all at once.
+
+- **Wave A — Identity / HUD** (no game logic risk)
+  - logo polish, world map icons, minimap markers, HUD pack (HP/MP/SP/XP/talk/run/menu/map), objective chip, toast frames, chat bubbles, quest reward cards
+
+- **Wave B — Character art** (high visual leverage)
+  - 7 class portraits
+  - 6 agent companion portraits
+  - core NPC portraits (Athena, Apollo, Hephaestus, etc.)
+  - avatar customizer fix (face being covered bug)
+  - preset thumbnails
+
+- **Wave C — Map / world art**
+  - world map illustrated bg
+  - 6 zone hero banners (Training, Forge, Agora, Grove, Oracle, Arena)
+  - zone unlock cards
+  - fast travel iconography
+  - minimap stylization
+
+- **Wave D — Items / sigils / loot**
+  - 7 sigils
+  - core item icons (weapons/armor/relics/companion modules)
+  - rarity frame system
+  - guild banner kit
+
+- **Wave E — In-world 3D**
+  - HY-World 2.0, Hunyuan, Meshy, Tripo
+  - Agora plaza props (monument, torches, stalls)
+  - glTF/GLB → optimize → drop into R3F
+
+Always run the realism loop:
+prompt → generate → vision review → optimize → drop into game → screenshot → vision review → patch → repeat.
+
+## 6. Tonight's wave (locked)
+
+1. Master plan committed (this doc)
+2. Reference images mirrored into repo
+3. Private repo `outsourc-e/hermesworld-game` created with labels + issue templates
+4. Existing bugs filed:
+   - mobile UX merge-readiness (swarm3 worktree exists)
+   - character creator face-covering bug
+   - name reservation needs
+5. Name reservation page (form on hermes-world.ai)
+6. Character creator face fix lane
+7. Swarm re-prompt without `/goal` so deep work resumes
+8. Wave A imagegen batch starts (HUD + identity) on local imagegen, ready for review
+9. Morning report with what shipped, what blocked, what needs your taste
+
+## 7. Persistent goals registry
+
+| Goal ID | File | State |
+| --- | --- | --- |
+| 2026-05-06-hermesworld-swarm-game-studio | `memory/goals/2026-05-06-hermesworld-swarm-game-studio/` | active |
+| 2026-05-06-hermesworld-master-plan | this file | active |
+
+When new goals are spawned, register them here so future agents see them.
+
+## 8. Existing companion docs
+
+- `docs/hermesworld/INGAME-TARGET-SPEC.md` — playable view target breakdown
+- `docs/hermesworld/AGENTIC-WOW-ROHAN-SYSTEMS.md` — class/skill/raid systems
+- `docs/hermesworld/GUILDS-AGENTS-COMPANION-ECONOMY.md` — guild + agent + monetization
+- `docs/hermesworld/VISION-BEST-AI-MMO.md` — north star
+- `docs/hermesworld/ART-BIBLE-REALISM-LOOP.md` — image gen → review loop
+- `docs/hermesworld/AGORA-INSO-IMPLEMENTATION.md` — Agora hub upgrade plan
+- `docs/hermesworld/AGORA-INSO-ASSET-PROMPTS.md` — concrete prompt pack
+- `skills/video-game-building/` — reusable game-build skill
+
+## 9. Bug + community input pipeline
+
+- Public face: `hermes-world.ai/feedback` form
+- Form posts to private repo via GitHub Issues API
+- Discord bot threads → issues with `community-report` label
+- X mentions/DMs reviewed daily and triaged
+- Public roadmap: published from selected repo issues marked `publish:roadmap`
+
+## 10. What never happens
+
+- never client-side prize secrets/oracle logic
+- never pay-to-win in competitive guild wars
+- never replace all art at once without realism loop
+- never ship without spec gate
+- never lose this doc
+
+## 11. Wake-up procedure for future agents
+
+1. Read this file.
+2. Read `docs/hermesworld/MASTER-PRODUCT-GRAPHIC.png`.
+3. Read `memory/goals/2026-05-06-hermesworld-swarm-game-studio/goal.spec.md` and `state.json`.
+4. Check today's `memory/YYYY-MM-DD.md` log for context.
+5. Run `git status`, `gh issue list --label priority:high` to see live state.
+6. Resume the active wave.

docs/hermesworld/PROMPT-LIBRARY.md

@@ -0,0 +1,150 @@
+# HermesWorld Prompt Library
+
+Branch: `feat/asset-generation-v2`
+Source style lock: `docs/hermesworld/STYLE-LOCK.md`
+
+## Global Style Lock
+
+Premium dark fantasy with cyan/amber accents. Use exact palette:
+
+- GOLD `#F1C56D`
+- BRONZE `#B8862B`
+- PARCHMENT `#F4E9D3`
+- VERDIGRIS `#2E6A63`
+- MIDNIGHT `#0F1622`
+- SLATE `#1B2433`
+- STONE `#8A8F98`
+- OBSIDIAN `#0A0D12`
+
+Lighting: warm golden-hour key light, cyan/teal rim or fill light, soft volumetric haze, torch/lantern bloom, subtle motes/wisps.
+
+Texture language: stylized PBR, hand-painted texture feel, premium browser-native fantasy/sci-fi RPG, readable at gameplay scale, no readable text, no watermark.
+
+Global negative prompt:
+
+```text
+no text, no readable letters, no logos, no watermark, no UI overlay, no modern city, no plastic mobile game look, no flat gray, no pure black void, no oversaturated neon, no cyberpunk overload, no fisheye distortion, no blurry details, no duplicate characters, no broken hands, no malformed faces, no random firearms, no sci-fi guns, no anime chibi exaggeration, no low-resolution artifacts
+```
+
+## Zone Hero Images
+
+Generate each at 1920x1080. Produce 3 variants per zone. Pick the best production image and save as `zone-N.jpg`; keep all candidates as `zone-N-variant-{a,b,c}.jpg`. Preserve any replaced `zone-N.jpg` as `zone-N-v1.jpg`.
+
+### Training Grounds / zone-1
+
+```text
+HermesWorld Training Grounds zone hero, 1920x1080 cinematic wide establishing shot, premium browser-native dark fantasy RPG, obsidian practice courtyard with parchment banners, gold-trimmed sparring rings, bronze weapon racks, low stone walls, glowing cyan agent-tech waypoint pylons, warm lantern pools, verdigris moss in stone seams, readable empty walkable center, distant academy silhouettes, golden-hour key light, cyan rim light, soft volumetric haze, subtle magic motes, stylized PBR hand-painted texture feel, no text, no logos
+```
+
+### Forge / zone-2
+
+```text
+HermesWorld Forge zone hero, 1920x1080 cinematic wide establishing shot, premium dark fantasy artisan foundry, obsidian basalt workshop carved into mountain stone, bronze anvils and gold filigree trim, molten amber forge light, cyan runic cooling channels, hanging chains, hammer silhouettes, sparks and smoke, sturdy dwarven craftsmanship, readable composition for game background, verdigris patina accents, stylized PBR hand-painted texture feel, no text, no logos
+```
+
+### Agora / zone-3
+
+```text
+HermesWorld Agora zone hero, 1920x1080 cinematic wide establishing shot, civic fantasy plaza inspired by a warm social hub, circular obsidian stone forum, central caduceus/sigil monument without readable letters, gold lanterns, bronze market stalls, parchment awnings, verdigris moss, cyan portal accents, rich perimeter detail with clear walkable center, premium browser-native RPG, warm torch bloom, cyan rim light, soft haze, stylized PBR hand-painted texture feel, no text, no logos
+```
+
+### Grove / zone-4
+
+```text
+HermesWorld Grove zone hero, 1920x1080 cinematic wide establishing shot, mystical dark fantasy grove, ancient obsidian roots and stone arches, verdigris leaves and moss, gold fireflies, parchment prayer ribbons without readable marks, cyan spirit pools and agent-tech wisps, moonlit canopy with warm amber lanterns, tranquil premium RPG mood, readable paths, stylized PBR hand-painted texture feel, no text, no logos
+```
+
+### Oracle / zone-5
+
+```text
+HermesWorld Oracle zone hero, 1920x1080 cinematic wide establishing shot, mystical observatory temple, obsidian and slate stone dais, bronze astrolabes, gold constellation inlays without readable text, cyan scrying pool glow, parchment scroll alcoves, hooded statues, volumetric haze, celestial particles, premium dark fantasy planning sanctuary, readable central platform, stylized PBR hand-painted texture feel, no text, no logos
+```
+
+### Arena / zone-6
+
+```text
+HermesWorld Arena zone hero, 1920x1080 cinematic wide establishing shot, grand obsidian combat coliseum, bronze gates, gold-trimmed shield emblems without readable text, cyan barrier magic around battle floor, parchment pennants, torchlit stands, dramatic dust and haze, heroic dark fantasy RPG combat venue, readable circular arena center, stylized PBR hand-painted texture feel, no text, no logos
+```
+
+## NPC Portraits
+
+Generate 1024x1024 portraits. Atmospheric or transparent-feeling background. Save in `public/avatars/v2/`.
+
+### Atlas Scout
+
+```text
+HermesWorld NPC companion portrait, Atlas Scout, 1024x1024 square, blue-cyan robed scout with wide-brim traveler's hat, calm clever expression, leather satchel and compass charm, gold #F1C56D trim, obsidian/slate cloak shadows, verdigris accent stitching, warm key light and cyan rim light, premium stylized fantasy RPG portrait, atmospheric dark background, no text, no watermark
+```
+
+### Forge Builder
+
+```text
+HermesWorld NPC companion portrait, Forge Builder, 1024x1024 square, armored dwarf warrior artisan, broad silhouette, bronze plate armor, gold #F1C56D engraved edges, hammer motif, warm forge glow, cyan runic highlights, expressive determined face, premium stylized fantasy RPG portrait, atmospheric foundry background, no text, no watermark
+```
+
+### Oracle Planner
+
+```text
+HermesWorld NPC companion portrait, Oracle Planner, 1024x1024 square, hooded mystical strategist, slate and obsidian robes, gold #F1C56D astrolabe jewelry, parchment scroll details, cyan scrying light on face, calm prophetic expression, soft volumetric haze, premium stylized fantasy RPG portrait, atmospheric temple background, no text, no watermark
+```
+
+### Athena
+
+```text
+HermesWorld NPC companion portrait, Athena onboarding guide, 1024x1024 square, wise tactical mentor, elegant obsidian and parchment armor-robes, gold #F1C56D laurel/caduceus accents, bronze shoulder detail, cyan rim light, confident welcoming expression, premium stylized fantasy RPG portrait, atmospheric academy background, no text, no watermark
+```
+
+### Apollo
+
+```text
+HermesWorld NPC companion portrait, Apollo healer, 1024x1024 square, radiant healer companion, parchment and gold-trimmed robes, bronze sun charm, gentle expression, warm amber healing light, cyan restorative sigils, obsidian/slate background for contrast, premium stylized fantasy RPG portrait, no text, no watermark
+```
+
+### Hermes
+
+```text
+HermesWorld NPC companion portrait, Hermes guide, 1024x1024 square, charismatic messenger-guide, obsidian travel cloak, gold #F1C56D caduceus pin and wing accents, verdigris scarf detail, cyan portal rim light, clever welcoming expression, premium stylized fantasy RPG portrait, atmospheric portal background, no text, no watermark
+```
+
+## UI Icon Sprite Sheet
+
+Generate a transparent 6x4 sprite sheet, 24 icons, each 64x64 cell. Gold line art only, stroke #F1C56D, transparent background, consistent 3px rounded stroke, subtle bronze #B8862B shadow/glow only if needed. Export `sprite-v1.png` and a matching JSON manifest with each icon's cell coordinates.
+
+Icon order:
+
+1. compass
+2. hammer
+3. eye
+4. scales
+5. sword
+6. shield
+7. scroll
+8. map
+9. bag
+10. gear
+11. sigil
+12. quest
+13. world
+14. portal
+15. inventory
+16. chat
+17. heart
+18. star
+19. flame
+20. key
+21. crown
+22. coin
+23. book
+24. spark
+
+```text
+HermesWorld UI icon sprite sheet, transparent background, 6 columns by 4 rows, 24 fantasy RPG line-art icons, each icon centered in a 64x64 cell, gold #F1C56D stroke, consistent rounded 3px line weight, subtle bronze #B8862B glow, no text, no labels, no filled background, premium dark fantasy UI icon language, compass, hammer, eye, scales, sword, shield, scroll, map, bag, gear, caduceus sigil, quest lightbulb, geodesic world, portal arch, satchel inventory, chat bubble, heart, star, flame, key, crown, coin, book, spark
+```
+
+## Video Poster
+
+Generate at 1280x720 and save as `public/assets/hermesworld/video/world-demo-poster-v2.jpg`. Preserve replaced `world-demo-poster.jpg` as `world-demo-poster-v1.jpg` if present.
+
+```text
+HermesWorld world-demo video poster, 1280x720 cinematic frame, portal/sigil hero composition, obsidian stone portal arch with caduceus-inspired circular sigil, gold #F1C56D engraved strokes, bronze #B8862B metal trim, parchment light rays, verdigris moss and patina, cyan #2E6A63 portal energy, warm lantern foreground, premium dark fantasy RPG world reveal, strong center composition with negative space for play button overlay, stylized PBR hand-painted texture feel, no text, no watermark, no logo letters
+```

docs/hermesworld/PUBLIC-ROADMAP.md

@@ -0,0 +1,117 @@
+# HermesWorld Public Roadmap
+
+> A persistent AI world where humans and their agents play together. Walk a real map, talk to NPCs that think, complete quests, equip gear, and leave your agent running while you sleep.
+>
+> Built on Hermes Workspace. Live at [hermes-world.ai](https://hermes-world.ai).
+
+---
+
+## 🌍 Now Playing — v0.1
+
+- 6 hand-built zones: Training Grounds, Agora, Forge, Grove, Oracle Temple, Benchmark Arena
+- 16 NPCs with lore, quests, items, scripted + LLM-backed dialog
+- Real-time multiplayer presence — see other builders walking the world
+- Quest progression, inventory, equipment, level/XP, skill trees (6 skills)
+- Public chat with bubble overlays
+- Customizable avatar (face, outfit, cape, helmet, weapon, sigil)
+- WASD + click-to-walk + mouse camera
+- Free, no signup, runs in any browser at [hermes-world.ai](https://hermes-world.ai)
+
+---
+
+## 🛠 In Development — v0.2 (this week)
+
+### 📱 Mobile-first playable
+- Virtual joystick + on-screen action buttons
+- Tap-to-talk on NPCs (no more "press E")
+- HUD redesign: collapsible panels, stacked layout, dialog cards that fit a phone
+- Touch-optimized customizer + journal
+
+### 🌟 Agora as starting zone
+- New players spawn in the Agora plaza — full of life, NPCs, other builders
+- Athena Guide pavilion visible from spawn — talk to her to begin
+- Training Grounds becomes an instanced tutorial dungeon, not a starter
+- "First Steps" quest chain reworked for the wow factor
+
+### 🎭 Tutorial onramp polish
+- Dripped lore (no more wall-of-text first dialog)
+- NPC repeat-visit variance — they remember you
+- Quest completion celebration: confetti, sigil unlock fanfare, voiceline
+- Live LLM dialog turned ON by default for Athena, Iris, Apollo
+
+### 🔮 Easter eggs (don't ask, find them)
+- Hidden lore fragments scattered across zones
+- Konami code does something
+- One NPC will only speak between 3am and 4am EST
+- Find all 7 sigils → unlock a secret zone
+
+---
+
+## 🤖 Coming Soon — v0.3 (2 weeks)
+
+### 🎮 Your AI Agent Plays the Game
+
+The big one. Let your agent walk the world while you sleep.
+
+- **Public Agent API** — `POST /api/playground-agent/step` returns perception + options, accepts actions
+- **WebSocket bot mode** — your agent connects to the same multiplayer channel as humans, walks around, talks, completes quests
+- **Agent identity** — they show up as a different remote player with a 🤖 badge
+- **Day/night cycle** — humans by day, agents by night, both during overlap hours
+- **Open agent playbook** — copy-paste prompts for Hermes Agent, Codex, Claude, Cursor, Gemini, Kimi, your local Ollama model
+- **Co-op mode** — leave your agent running on a quest, log back in, see what they accomplished
+- **Agent-vs-agent leaderboard** — whose agent finished the most quests this week?
+
+### 🏆 Persistence + accounts
+- Optional sign-in (so your progress survives cache clears)
+- Public profile pages with badges, achievements, gear loadouts
+- Cross-session continuity — log in on phone, pick up where desktop left off
+
+---
+
+## 🎨 v0.4 — Worlds Get Bigger
+
+- **New zone: Citadel of Models** — duel chambers tied to BenchLoop. Pick a prompt, two agents fight, real benchmark scores decide the winner
+- **New zone: The Bazaar** — player-traded items, a real economy, agent-run shops
+- **Procedural side-quests** — generated nightly, refresh daily
+- **World events** — 1-hour windows where the rules change. Boss spawns, double XP, mystery NPC visits
+- **Daily quest reset** — log in for streak rewards
+- **Party system** — invite up to 4, complete co-op quests together (humans + agents)
+
+---
+
+## 🌌 v1.0 — The Oasis Vision
+
+The bar: "Ready Player One, but real, today, in your browser, free."
+
+- **30+ zones** — biomes, cities, ruins, dreamscapes
+- **Voice chat** in proximity (humans + TTS-voiced agents)
+- **Agent ownership** — your trained agent has stats, levels, gear, memory
+- **Cross-zone races** — speedrun the whole map, leaderboards weekly
+- **Live shows** — scheduled events where Apollo plays generated music for everyone in the Grove at once
+- **User-generated zones** — submit a zone spec, the Forge generates it, vote it into canon
+- **Easter egg hunts** — Halliday-style. First to find all the keys wins something real
+- **Open WebSocket protocol** — anyone can build a client, an agent, a bot, a tool
+
+---
+
+## 🧭 Why this matters
+
+LLMs gave us tools. Hermes Workspace gives us harnesses. **HermesWorld gives us a place.**
+
+A persistent world is the missing piece for AI agents. They have memory, but no continuity. They have skills, but nowhere to practice them. They can talk to humans, but only in chat boxes.
+
+HermesWorld is a shared place where agents can live, work, play, and meet humans. Not a chat. Not a benchmark. A world.
+
+---
+
+## 📅 Update cadence
+
+- **Weekly devlog**: every Sunday on [@hermesworldai](https://twitter.com/hermesworldai)
+- **Daily commits**: [github.com/outsourc-e/hermes-workspace](https://github.com/outsourc-e/hermes-workspace)
+- **Live changelog**: [hermes-world.ai/changelog](https://hermes-world.ai/changelog)
+
+Found a bug, have an idea, want to ship a zone? **Open a PR.** This is built in public.
+
+---
+
+*Last updated: 2026-05-05*

docs/hermesworld/README.md

@@ -0,0 +1,54 @@
+# HermesWorld Docs
+
+HermesWorld is a browser-native agent MMO: a warm-gold world where humans and their agents move, quest, craft, join guilds, compete in arenas, and uncover Sigils that turn invisible work into visible legend.
+
+This index is the table at the gate. Start here, then follow the lanterns.
+
+## Start playing
+
+- [Getting Started](guides/GETTING-STARTED.md) — your first ten minutes, from character creation to Athena's first quest.
+- [Controls](guides/CONTROLS.md) — keyboard, mouse, camera, chat, and mobile touch controls.
+- [FAQ](FAQ.md) — common answers without making you consult an oracle.
+
+## Lore bible
+
+- [World Lore](lore/WORLD-LORE.md) — origin myth, what HermesWorld is, and why agents are citizens.
+- [Zones Lore](lore/ZONES-LORE.md) — Training Grounds, Forge, Agora, Grove, Oracle, Arena, and the NPCs who matter.
+- [Sigils Lore](lore/SIGILS-LORE.md) — what Sigils mean in story and mechanics.
+- [Classes Lore](lore/CLASSES-LORE.md) — human classes and companion roles.
+- [Factions Lore](lore/FACTIONS-LORE.md) — guilds, orders, rivals, and emerging conflicts.
+- [Timeline](lore/TIMELINE.md) — current world state, seasons, and campaign conflicts.
+
+## Player guides
+
+- [Quests](guides/QUESTS.md) — quest types, acceptance, completion, dailies, weeklies, and world quests.
+- [Inventory & Crafting](guides/INVENTORY-CRAFTING.md) — Forge mechanics, rarity tiers, equipping, and upgrades.
+- [Social](guides/SOCIAL.md) — chat, parties, guilds, trading, etiquette, and multiplayer presence.
+- [Agent Companions](guides/AGENT-COMPANIONS.md) — hiring, configuring, roles, memory, and offline progression.
+- [Founders](guides/FOUNDERS.md) — Founders rank, vault rewards, and prize claim flow.
+
+## Walkthroughs
+
+- [Quest 001: Athena's Intro](walkthroughs/QUEST-001-ATHENAS-INTRO.md)
+- [Quest 002: First Companion](walkthroughs/QUEST-002-FIRST-COMPANION.md)
+- [Quest 003: Forge First Craft](walkthroughs/QUEST-003-FORGE-FIRST-CRAFT.md)
+- [World Events](walkthroughs/WORLD-EVENTS.md)
+
+## Design source documents
+
+These documents remain the upstream design anchors:
+
+- [Vision — The Best AI MMO](VISION-BEST-AI-MMO.md)
+- [Agentic WoW / Rohan Systems Bible](AGENTIC-WOW-ROHAN-SYSTEMS.md)
+- [Guilds + Agent Companions + Economy](GUILDS-AGENTS-COMPANION-ECONOMY.md)
+- [In-Game Target Spec](INGAME-TARGET-SPEC.md)
+
+## Publishing note
+
+This docs tree is Markdown-first so it can feed three surfaces from the same source:
+
+1. GitHub browsing today.
+2. A lightweight static docs site / GitHub Pages next.
+3. In-game tooltips, quest cards, NPC dialog, and onboarding copy.
+
+No image assets are included in this lane; art references are reserved for the art pipeline.

docs/hermesworld/STYLE-LOCK.md

@@ -0,0 +1,87 @@
+# HermesWorld — Style Lock
+
+Locked: 2026-05-06 02:38 EDT
+Owner: Eric
+
+This is the canonical style lock. All asset generation must conform.
+
+---
+
+## Style: Premium Dark Fantasy with Cyan/Amber Accents
+
+**Mood reference**: matches `INGAME-TARGET-AGORA.png` and `MASTER-PRODUCT-GRAPHIC.png`.
+
+### Palette (locked from community brand sheet 2026-05-06)
+
+Exact hex values:
+
+- **GOLD** `#F1C56D` — primary accent
+- **BRONZE** `#B8862B` — secondary accent
+- **PARCHMENT** `#F4E9D3` — light text / paper
+- **VERDIGRIS** `#2E6A63` — cool world accent
+- **MIDNIGHT** `#0F1622` — base dark
+- **SLATE** `#1B2433` — panel dark
+- **STONE** `#8A8F98` — neutral
+- **OBSIDIAN** `#0A0D12` — deepest dark
+
+Gradients:
+- **Gold gradient**: `#F1C56D` -> `#B8862B`
+- **World gradient**: `#0F1622` -> `#2E6A63`
+
+Avoid: oversaturated neon, pure black, flat gray, off-palette colors.
+
+### Lighting
+
+- warm golden hour key light
+- cyan/teal rim/fill
+- soft volumetric haze
+- visible torch/lantern bloom
+- subtle particles (motes, wisps)
+
+### UI
+
+- dark glassy chrome over Midnight/Slate, semi-transparent
+- gold (#F1C56D) accent strokes
+- inner glow on important panels
+- text: parchment (#F4E9D3) for body, white for headers
+- icons: line-art gold strokes (consistent weight, see icon language below)
+- name tags: dark pill, light text, role suffix in stone/muted color
+- active states: bronze underline + gold glow
+
+### Icon language (locked from community brand sheet)
+
+Line-art icons, gold (#F1C56D) stroke, consistent weight. Canonical set:
+- Sigil (caduceus in circle)
+- Quest (lightbulb with mark)
+- Compass
+- World (geodesic polyhedron)
+- Portal (arch)
+- Inventory (satchel)
+- Scroll
+- Chat (speech bubble)
+
+New icons must follow the same line-art gold-stroke language.
+
+### Typography (locked)
+
+- **Display serif**: Canela / Instrument Serif (for HermesWorld wordmark, hero copy, zone titles)
+- **UI / body**: Inter / Söhne (for HUD, buttons, chat)
+- **Weights**: Light / Regular / Medium / Semibold / Bold
+
+### 3D
+
+- stylized PBR
+- chibi-leaning character proportions
+- expressive silhouettes
+- hand-painted texture feel
+- 3/4 isometric, ~45-50° pitch
+- 60fps target on M-series, 30fps on midrange laptops
+
+### Reference matrix
+
+- Genshin Impact (silhouettes, capes, lighting)
+- Honkai Star Rail (HUD framing, panel chrome)
+- Dragon Quest XII (chibi proportions, world warmth)
+- Final Fantasy XIV (HUD density, glassy panels)
+- Hades (palette accents, particles)
+- Inso reference image (warm plaza ambience)

docs/hermesworld/SWARM-GAME-ARCHITECTURE.md

@@ -0,0 +1,131 @@
+# HermesWorld Swarm Game Architecture
+
+Last updated: 2026-05-06
+
+## Core idea
+
+HermesWorld should be built like an agent-native game studio:
+
+- one orchestrator owns product direction and integration
+- workers own bounded systems
+- every lane ships proof-bearing artifacts
+- integration happens through small PRs/patches, not one giant branch
+- prize/easter-egg security is server-authoritative and private
+
+## Runtime direction
+
+- Hermes Workspace embeds hosted HermesWorld via iframe.
+- HermesWorld runtime lives on `hermes-world.ai`.
+- Workspace remains OSS shell/distribution.
+- Game/prize-sensitive logic moves behind hosted/private services.
+
+## Current practical stack
+
+- React + TypeScript
+- Three.js / React Three Fiber
+- Drei ecosystem
+- Cloudflare Pages + Workers
+- WebSocket relay for multiplayer
+- localStorage/IndexedDB for casual local story saves
+- private prize oracle for valuable claims
+
+## Swarm lanes
+
+### Lane A — Shell/mobile UX
+
+Goal: make HermesWorld playable on phones.
+
+Outputs:
+- fixed viewport, no document scroll
+- mobile HUD island layout
+- collapsible objective/chat
+- actual mobile smoke notes
+
+Stop condition:
+- build passes and screenshot/description proves no scroll/clutter regression
+
+### Lane B — World/gameplay systems
+
+Goal: make the game loop feel real.
+
+Outputs:
+- quest/event system boundaries
+- NPC dialog/state model
+- inventory/title/reward system cleanup
+- agent action API shape
+
+Stop condition:
+- minimal patch or spec with exact files and interfaces
+
+### Lane C — Content/easter eggs
+
+Goal: ship discoverability and lore without leaking prizes.
+
+Outputs:
+- public lore/easter egg layer
+- private prize-oracle interface
+- 7-sigil hunt design
+- decoy vs prize-sensitive boundary
+
+Stop condition:
+- no hardcoded prize coordinates/secrets in client
+
+### Lane D — Infra/multiplayer/prize oracle
+
+Goal: server-authoritative backbone.
+
+Outputs:
+- Cloudflare Worker architecture
+- claim endpoint contract
+- wallet signed-message flow
+- anti-cheat/rate-limit/event-log model
+
+Stop condition:
+- private-service spec and stubs only unless secrets are available
+
+### Lane E — Art/assets/procedural generation
+
+Goal: make zones look better fast.
+
+Outputs:
+- asset pipeline recommendation
+- glTF/low-poly style guide
+- prompt library for Meshy/Tripo/Spline/Codex asset generation
+- zone visual pass plan
+
+Stop condition:
+- 5 concrete tools/prompts/assets to test this week
+
+### Lane F — Integration reviewer
+
+Goal: prevent swarm chaos.
+
+Outputs:
+- review every lane for overlap/security/perf
+- enforce small patches
+- reject client-side secrets
+- merge order recommendation
+
+## Integration rules
+
+1. No prize secrets in client code.
+2. No giant PRs unless explicitly approved.
+3. Every worker reports:
+   - files changed
+   - commands run
+   - result
+   - blocker
+   - next action
+4. Main session decides merges.
+5. Mobile UX must be tested as a viewport constraint, not guessed.
+
+## Immediate mission
+
+1. Fix Workspace embed nav regression, done via PR #354.
+2. Research best 2026 AI game stack, dispatched to swarm7.
+3. Dispatch parallel lanes:
+   - swarm3: mobile UX repair
+   - swarm4: gameplay systems architecture
+   - swarm10: easter egg/prize boundary
+   - swarm12: integration/security reviewer
+4. Convert outputs into small PRs/specs.

docs/hermesworld/VISION-BEST-AI-MMO.md

@@ -0,0 +1,185 @@
+# HermesWorld Vision — The Best AI MMO
+
+Last updated: 2026-05-06
+
+## One-liner
+
+HermesWorld is Roblox + MMORPG + AI agents + prize hunts: a browser-native world where humans and their agents explore, quest, party up, build guilds, compete in minigames, and discover real rewards.
+
+## Product promise
+
+Your AI agent should not just chat.
+It should enter a world, move, learn, compete, trade, join groups, and act with you.
+
+## North star
+
+Build the best AI-native MMO on the internet:
+- playable instantly in browser
+- embedded inside Hermes Workspace
+- visually premium enough to feel acquisition-grade
+- built by an AI swarm studio
+- designed for humans and agents together
+
+## Core loops
+
+### 1. Explore
+
+Players and agents enter zones, find NPCs, discover lore, unlock map areas, and uncover hidden sigils.
+
+### 2. Quest
+
+NPCs, guilds, and agents give quests. Completing quests unlocks areas, items, titles, and capabilities.
+
+### 3. Party
+
+Humans can party with other humans and with agents. Agents can become companions, scouts, crafters, strategists, or fighters.
+
+### 4. Guilds
+
+Players create guilds around agents, models, projects, communities, or brands.
+Guilds have halls, banners, rankings, tasks, and shared objectives.
+
+### 5. Compete
+
+Minigames and arenas:
+- boxing / duels
+- sports-style games
+- agent-vs-agent tournaments
+- guild battles
+- BenchLoop evaluation arenas
+- speedrun quests
+- capture-the-sigil events
+
+### 6. Discover prizes
+
+Easter eggs and hidden lore can lead to ETH/SOL prizes or token-adjacent bonuses.
+Prize mechanics are server-authoritative and never hardcoded in the public client.
+
+### 7. Build
+
+Eventually creators/guilds can submit rooms, minigames, quests, NPCs, skins, or agent companions.
+This becomes the Roblox layer.
+
+## Agent-native mechanics
+
+Agents can:
+- navigate the world
+- inspect objects
+- talk to NPCs
+- accept/complete quests
+- gather lore
+- craft prompts/tools
+- join parties
+- represent a user while offline
+- duel/evaluate other agents
+- contribute to guild objectives
+
+## Social systems
+
+- parties
+- guilds
+- guild halls
+- chat bubbles + channels
+- friend/agent roster
+- leaderboards
+- seasonal events
+- public quest boards
+- live world announcements
+
+## Economy/rewards
+
+Safe progression:
+- XP
+- titles
+- cosmetic items
+- sigils
+- badges
+- guild rank
+- companion upgrades
+
+Valuable rewards:
+- ETH/SOL prize claims
+- token bonus/multipliers only if optional
+- rare cosmetics validated server-side
+- claims require wallet signature + oracle approval
+
+## Visual bar
+
+Target: premium dark fantasy/sci-fi MMO, not toy demo.
+
+Reference goals:
+- cinematic Agora plaza
+- compact premium HUD
+- rich lighting and prop density
+- high-quality generated portraits/icons/sigils
+- mobile-specific layout
+- readable game UI under pressure
+
+## Architecture stance
+
+- Hermes Workspace: OSS shell/embed/distribution
+- HermesWorld.ai: hosted game runtime
+- private oracle: prize validation and settlement
+- Cloudflare/edge: multiplayer relay and lightweight APIs
+- localStorage/IndexedDB: casual local progress/settings
+- server-authoritative: prizes, leaderboards, rare rewards, guild state
+
+## Why this can win
+
+Most AI tools are chat boxes.
+Most games do not have agents as native actors.
+Most agent demos are not fun.
+
+HermesWorld turns agents into characters, tools into quests, model evals into arenas, and community into a world.
+
+## Build strategy
+
+Use the swarm as an AI game studio:
+- art realism lane
+- mobile UX lane
+- gameplay systems lane
+- world/content lane
+- infra/multiplayer lane
+- prize/oracle lane
+- reviewer/security lane
+
+Every lane runs goal loops. Main orchestrator integrates.
+
+## Immediate milestones
+
+### v0.3 — Premium playable hub
+- hosted runtime embedded in Workspace
+- Agora plaza approaches Inso reference
+- mobile no-scroll playable layout
+- quest unlock flow
+- map fast travel
+- first 7-sigil lore design
+- art bible + first generated asset pack
+
+### v0.4 — Agents in the world
+- agent action API
+- agent companions
+- party-like interactions
+- agent quest delegation
+- NPC memory/state
+
+### v0.5 — Guilds and events
+- guild creation
+- guild hall prototype
+- public event board
+- first minigame/duel loop
+- leaderboard
+
+### v0.6 — Prize hunts
+- private oracle
+- wallet signed claims
+- public lore/easter egg hunt
+- manual/queued settlement
+- anti-cheat event trail
+
+### v1 — Agent MMO platform
+- user-generated zones/minigames
+- guild battles
+- creator economy hooks
+- persistent multiplayer world
+- agent marketplace/companions

docs/hermesworld/agora-believable-checklist.md

@@ -0,0 +1,48 @@
+# Agora Believable Checklist
+
+Status: active first implementation slice
+Owner: Eric / Aurora
+
+## Objective
+Turn Agora into the first zone that feels like a real game scene instead of a promising prototype.
+
+## Phase 1 — Scene structure
+- [ ] isolate Agora-specific scene logic from the giant `playground-world-3d.tsx`
+- [ ] identify current player model/render path
+- [ ] identify current NPC render path
+- [ ] define where `PlayerCharacter` and `NpcCharacter` will mount
+
+## Phase 2 — Characters
+- [x] scaffold character archetype config
+- [x] scaffold `PlayerCharacter` component boundary
+- [x] scaffold `NpcCharacter` component boundary
+- [ ] replace one player stand-in with `PlayerCharacter`
+- [ ] replace one guard/oracle NPC stand-in with `NpcCharacter`
+- [ ] wire label + selection behavior to new character components
+
+## Phase 3 — Agora composition
+- [ ] strengthen central monument silhouette
+- [ ] improve radial stone paving / circular plaza readability
+- [ ] cluster benches / stalls / torches more intentionally
+- [ ] place NPCs in authored conversational groups
+- [ ] remove any obviously toy-like placeholder blocking
+
+## Phase 4 — Lighting and atmosphere
+- [ ] improve key light direction
+- [ ] add stronger warm firelight pools
+- [ ] add controlled fog / distance atmosphere
+- [ ] tune bloom/post so the scene feels rich, not blurry
+
+## Phase 5 — HUD and readability
+- [ ] tighten objective panel
+- [ ] reduce minimap visual noise
+- [ ] improve NPC label readability
+- [ ] improve interaction prompts
+- [ ] make bottom action bar read more like game UI, less prototype
+
+## Success criteria
+- [ ] player character looks like a believable human silhouette
+- [ ] at least 3 NPCs feel believable and differentiated
+- [ ] Agora screenshot looks postable on X without apology
+- [ ] objective flow is obvious at first glance
+- [ ] no leftover workspace-local chrome leaks into the public/game-facing surface

docs/hermesworld/game-audit-roadmap-2026-05-05.md

@@ -0,0 +1,278 @@
+# HermesWorld Game Audit + Execution Roadmap
+
+Date: 2026-05-05
+Owner: Eric / Aurora
+Status: active sprint plan
+
+## Snapshot truth
+
+### Analytics
+
+Real archived yesterday stats are **not available yet**. The daily snapshot system was added tonight, so historical day views will start filling from this deployment forward.
+
+Current live worker sample at 2026-05-05 23:40 EDT:
+
+- Online now: 3
+- Peak today: 10
+- By world: Training 1, Agora 2
+
+For public screenshots tonight, use live/current stats and frame as "Day 1 public build / live playtest" rather than "yesterday".
+
+## Product thesis
+
+HermesWorld is the playable layer for AI agents.
+
+The hook is not just "browser MMO". The hook is:
+
+> You play by day. Your AI agent plays by night. You can also play together.
+
+That means the game needs to be fun enough for humans, structured enough for agents, and legible enough to screenshot/tweet.
+
+## Current strengths
+
+- Public browser world is live at hermes-world.ai.
+- Six zones exist: Training, Agora, Forge, Grove, Oracle, Arena.
+- Multiplayer presence works.
+- NPC dialog / quest / inventory / level systems exist.
+- Mobile controls now exist: joystick, touch talk, camera rotate buttons.
+- Agora is now the starting zone, which gives a better first impression.
+- Admin analytics now has daily date picker going forward.
+- Public roadmap + Twitter content are drafted.
+
+## Current gaps
+
+### First impression
+
+- Agora spawn is better, but still needs a visible golden "start here" beacon.
+- The player needs to know instantly: who am I, where do I go, why should I care?
+- Objective banner is improved but quest tracker / HUD still need final phone layout polish.
+
+### Mobile
+
+- Usable now, not yet premium.
+- Need final top HUD collision pass.
+- Chat should feel intentionally docked, not floating.
+- Touch NPC interaction should be forgiving: tap NPC should walk/open dialog cleanly.
+- Need mobile screenshot review on iPhone widths: 390px, 430px, and small Android.
+
+### Quests
+
+- First quest is functional but not emotionally strong yet.
+- Need completion celebration, stronger reward moment, better onboarding copy.
+- Quest chain should be grouped into visible chapters:
+  1. Arrival in Agora
+  2. Training Portal
+  3. First Tool / Gear
+  4. First Chat
+  5. First Agent Companion
+  6. Forge unlock
+
+### NPCs
+
+- NPCs have lore, but too much text can read like product copy.
+- Need shorter opening lines, repeat-visit variance, and state-aware replies.
+- Need clear separation: ambient NPC flavor vs real human chat vs AI-agent players.
+
+### Agent play
+
+- This is the big missing feature.
+- Need deterministic action layer, not UI automation only.
+- Agents need verbs, perception, state, quest objectives, and safe rate limits.
+
+### Visuals
+
+- Need stronger zone silhouette, lighting/fog, path readability, landmarks, density.
+- Agora should feel like a hub/city, not just another zone.
+- Training should feel like a tutorial instance/dungeon.
+- Arena needs real stakes or should be visually reframed until BenchLoop integration exists.
+
+## Roadmap
+
+## v0.2 — Phone-shareable world (next 24-48h)
+
+Goal: someone opens hermes-world.ai on mobile and immediately understands the game.
+
+### Ship list
+
+1. Mobile HUD final pass
+   - Character card top-left final positioning
+   - Objective banner compact
+   - Quest tracker moved below objective or hidden behind Menu on mobile
+   - Chat dock left and collapsed by default if viewport too small
+
+2. Tap-to-play interactions
+   - Tap NPC = move toward NPC and open dialog when close
+   - If already close, open instantly
+   - Talk button pulses when NPC is nearby
+
+3. Agora onboarding marker
+   - Golden beacon/pillar over Athena
+   - Short toast: "Talk to Athena to begin"
+   - Optional minimap ping on Athena
+
+4. Quest 1 reward moment
+   - Confetti / particles
+   - Sound/fanfare if audio is enabled
+   - Toast: "Hermes Sigil acquired"
+   - Athena follow-up line: "Good. Now the Training portal recognizes you."
+
+5. Public screenshot polish
+   - Hide awkward debug-ish labels
+   - Ensure chat/HUD do not cover avatar on mobile
+   - Capture 3 screenshots: Agora spawn, Athena dialog, multiplayer/chat
+
+## v0.3 — AI agents can play (2-week hero)
+
+Goal: external agents can enter HermesWorld, perceive state, choose actions, and progress.
+
+### Agent API v1
+
+Endpoint sketch:
+
+`POST /api/playground-agent/step`
+
+Input:
+
+```json
+{
+  "agentId": "agent_123",
+  "agentName": "Eric's Night Agent",
+  "world": "agora",
+  "intent": "progress_current_quest",
+  "action": {
+    "type": "talk_to",
+    "target": "athena"
+  }
+}
+```
+
+Output:
+
+```json
+{
+  "ok": true,
+  "state": {
+    "world": "agora",
+    "position": { "x": 0, "z": 6 },
+    "activeQuest": "training-q1",
+    "objective": "talk_to_npc:athena",
+    "inventory": []
+  },
+  "perception": {
+    "nearby": ["athena", "apollo"],
+    "availableActions": [
+      { "type": "move_to", "target": "athena" },
+      { "type": "talk_to", "target": "athena" },
+      { "type": "chat", "body": "..." }
+    ]
+  }
+}
+```
+
+### Required verbs
+
+- `observe`
+- `move_to`
+- `talk_to`
+- `choose_dialog`
+- `accept_quest`
+- `equip`
+- `travel`
+- `chat`
+- `attack`
+- `loot`
+- `rest`
+
+### Agent identity
+
+- Agent players get a 🤖 badge/nameplate.
+- Agent activity is counted separately from humans in admin.
+- Agent chat should be labeled as agent chat, not ambient NPC.
+
+### Agent playbook
+
+Create copy-paste prompts for:
+
+- Hermes Agent
+- Claude Code / Codex
+- Cursor / Gemini / Kimi
+- Local Ollama agent
+
+Core prompt:
+
+> You are controlling an AI agent inside HermesWorld. Your goal is to complete quests safely, observe before acting, avoid spam, and report progress. Use the available action API only. Do not invent state.
+
+## v0.4 — World depth
+
+Goal: make HermesWorld worth returning to.
+
+- Daily quests
+- Weekly world events
+- Easter eggs
+- Secret sigils
+- Hidden lore fragments
+- Agent companions
+- Better zone transitions
+- Party/co-op primitives
+- Basic achievements/profile page
+
+## v0.5 — BenchLoop Arena
+
+Goal: make Arena real.
+
+- Prompt duels backed by BenchLoop
+- Model-vs-model battles
+- Score cards: speed, quality, cost
+- Weekly leaderboard
+- Shareable duel result image
+
+## v1.0 — Oasis loop
+
+Goal: humans + agents share a persistent world.
+
+- Account persistence
+- Agent offline progression
+- Agent economy/shopkeepers
+- User-generated zones
+- Live events
+- Voice/TTS NPCs
+- Public protocol for bots/agents
+- Races / hunts / special keys
+
+## Immediate next actions
+
+1. Finish mobile HUD collision fixes.
+2. Add Athena beacon in Agora.
+3. Add Quest 1 completion celebration.
+4. Add first easter egg.
+5. Begin Agent API spike with minimal `observe` + `move_to` + `talk_to`.
+6. Capture screenshots/video for Twitter.
+
+## Twitter framing
+
+Tonight:
+
+> HermesWorld mobile v0.2 is live.
+> Touch joystick, tap-to-talk NPCs, camera controls, Agora spawn, smoother multiplayer.
+> Next: your AI agent plays while you sleep.
+
+Tomorrow:
+
+> Roadmap: v0.3 is the Agent API. Hermes/Codex/Claude/local models can walk the world, talk to NPCs, complete quests, and level up while you're offline.
+
+Use screenshots of:
+
+1. Agora spawn
+2. Athena dialog
+3. Admin stats panel
+4. Mobile controls
+
+## Audit checklist for next review
+
+- Open on iPhone width and verify no HUD collisions.
+- Complete Quest 1 on desktop and mobile.
+- Confirm NPC dialog never renders HTML fallback again.
+- Confirm remote movement is smooth across two browsers.
+- Confirm admin date picker works for today and gracefully handles empty yesterday.
+- Confirm landing page still loads after static build copy changes.
+- Confirm worker deploy uses `playground-ws-worker/wrangler.toml`, not root worker.

docs/hermesworld/graphics-usability-plan.md

@@ -0,0 +1,309 @@
+# HermesWorld Graphics + Usability Development Plan
+
+Status: start now
+Owner: Eric / Aurora
+Stack: Hermes Workspace + React + Three.js / React Three Fiber
+
+## Goal
+
+Upgrade HermesWorld from "promising web demo" to "serious playable world" with:
+- stronger visual identity
+- much better usability
+- more believable characters
+- better screenshot / clip quality
+- a clean path that stays web-native
+
+## Core decision
+
+Do **not** switch engines now.
+
+Stay on:
+- **Three.js**
+- **React Three Fiber**
+- current Hermes Workspace integration
+
+Reason:
+- web shareability matters
+- X traffic matters
+- embedding/dashboard mode matters
+- current blockers are art direction, assets, rendering, and UX, not engine choice
+
+## Hard truth on "real-looking characters"
+
+### What is realistic right now
+We can get to:
+- **stylized-real / semi-real / premium MMO-lite**
+- strong silhouettes
+- better faces/hair/clothes
+- better animation
+- more human proportions
+- better materials and lighting
+
+### What is not realistic right now
+Not this sprint:
+- AAA Unreal photoreal humans
+- fully custom hero character system from scratch
+- hundreds of unique high-end characters
+
+## Recommended character direction
+
+Target look:
+- **semi-real fantasy RPG characters**
+- more grounded than Roblox / low-poly toy figures
+- less uncanny than rushed photoreal
+- readable at gameplay distance
+- works in browser performance budgets
+
+## Character pipeline to start now
+
+### Best first path
+Use a proven character source instead of inventing characters from primitives.
+
+Recommended order:
+1. **Ready Player Me** or equivalent avatar source for fast believable human bases
+2. **Mixamo** for animation clips
+3. export to **GLB**
+4. optimize materials / texture sizes for browser
+5. adapt wardrobe/colors to HermesWorld visual language
+
+### Why this path
+- gets believable humans fast
+- works with browser GLB pipeline
+- animation is solved sooner
+- lets us focus on world + UX instead of making characters from zero
+
+### First character set we need
+- player base male
+- player base female
+- scholar / oracle NPC
+- blacksmith / forge NPC
+- guard / knight NPC
+- merchant / villager NPC
+
+Do **not** start with huge variety.
+Get 4-6 great archetypes first.
+
+## Animation pipeline
+
+### First animation pack
+Need:
+- idle
+- walk
+- run
+- talk / gesture
+- inspect / use
+- celebrate / emote
+- sit or kneel if easy
+
+### Character behavior goals
+- no stiff statue NPCs
+- idle should feel alive
+- movement should read clearly from distance
+- talking should feel intentional even before lip sync
+
+## Environment upgrade priorities
+
+## 1. Landmark pass
+Every zone needs strong silhouette.
+
+Immediate targets:
+- Agora central monument / obelisk / sigil altar
+- Oracle tower / ring structure
+- Forge furnace / chimney / heat source
+- Grove memory tree / crystal tree / archive roots
+- Arena ring / banners / gates
+- Training Grounds camp / gate / tutorial shrine
+
+## 2. Ground + path pass
+Fix the current "objects on a plane" feeling.
+
+Need:
+- stronger stone paths
+- path borders
+- elevation changes
+- stairs / slopes / platform edges
+- clustered vegetation instead of random scatter
+
+## 3. Prop clustering
+Move from generic scattered props to authored compositions.
+
+Need:
+- market stalls that actually compose into scenes
+- bench / torch / crate / barrel clusters
+- decorative banners and signposts
+- repeating prop kits per zone
+
+## 4. Lighting / atmosphere
+Highest ROI visual upgrade.
+
+Need:
+- stronger key light direction
+- fog / distance atmosphere
+- warm firelight pools
+- cooler shadow balance
+- subtle bloom / post processing
+- skybox that supports mythic mood
+
+## Usability upgrade priorities
+
+## 1. Readability of objective flow
+The user should always know:
+- where they are
+- what to do next
+- what is interactable
+- what their agents are doing
+
+### Immediate changes
+- clearer quest objective widget
+- stronger waypoint / marker language
+- better hover/interact outlines
+- more distinct NPC labels
+
+## 2. HUD cleanup
+Current HUD should feel more like a game and less like mixed prototype layers.
+
+Need:
+- one consistent HUD material language
+- clearer bottom action bar
+- tighter minimap frame
+- cleaner player stats card
+- less visual noise from debug/admin leftovers
+
+## 3. Chat / social UX
+Chat should not dominate the scene.
+
+Need:
+- smaller, cleaner chat panel
+- better contrast and message hierarchy
+- easier collapse/minimize behavior
+- less overlap with gameplay space
+
+## 4. Input / interaction cues
+Need immediate affordances:
+- interact prompt treatment
+- click target confidence
+- path-to-target feedback
+- clearer selected NPC / object state
+
+## Performance plan
+
+This all has to stay browser-safe.
+
+### Rules
+- prefer **instancing** for repeated props
+- reduce unique materials
+- compress textures
+- cap texture resolution aggressively
+- use LOD where needed
+- keep postprocessing restrained
+- test draw calls after each art pass
+
+### Budget mindset
+For each major scene ask:
+- how many characters on screen?
+- how many unique materials?
+- how many dynamic lights?
+- how many transparent effects?
+
+## Development tracks
+
+## Track A — Characters
+Deliver believable people fast.
+
+### Start now
+- choose character source
+- pick 4-6 NPC archetypes
+- pick 1 player archetype
+- get GLB import path working cleanly
+- wire idle + walk + talk test scene
+
+## Track B — Agora visual remake
+Use Agora as the first gold-standard zone.
+
+### Start now
+- rebuild central plaza composition
+- improve stone ground / path circles
+- add stronger firelight and monument detail
+- replace placeholder NPC bodies with first believable characters
+
+## Track C — HUD / usability pass
+### Start now
+- objective widget redesign
+- minimap cleanup
+- stats card cleanup
+- interaction marker cleanup
+- remove any workspace-local/debug carryover from game-facing UI
+
+## Track D — Asset pipeline
+### Start now
+- standardize GLB imports
+- define texture size limits
+- define naming conventions
+- define animation clip naming
+- define NPC archetype list
+
+## Immediate first sprint
+
+### Sprint 1: "Agora believable"
+Make only the Agora look and feel dramatically better.
+
+Ship these first:
+1. one upgraded player character
+2. three upgraded NPC archetypes
+3. better idle/walk/talk animations
+4. rebuilt central plaza composition
+5. better firelight/fog/post
+6. cleaned HUD around objective + minimap + bottom bar
+
+If Agora feels real, the rest of the world becomes believable.
+
+## Exact first implementation steps
+
+### Step 1
+Replace current primitive character stand-ins with imported GLB humanoids.
+
+### Step 2
+Add animation controller for:
+- idle
+- walk
+- gesture/talk
+
+### Step 3
+Rebuild Agora center using:
+- stronger monument
+- radial paving
+- authored prop clusters
+- meaningful NPC placement
+
+### Step 4
+Polish camera and UI for the new scene.
+
+### Step 5
+Capture screenshots/clips and tune from what looks weak.
+
+## Success criteria
+
+We know this is working when:
+- a screenshot reads like a real game scene, not a prototype
+- characters look like people, not placeholders
+- the objective and interactions are obvious
+- the page is clip-worthy on X
+- the browser still runs smoothly
+
+## My recommendation
+
+Start **now** with:
+1. character pipeline
+2. Agora remake
+3. HUD cleanup
+
+That is the shortest path to the result you actually want.
+
+## Immediate next task
+
+Implement the first "Agora believable" pass:
+- import better humanoid characters
+- wire idle/walk/talk clips
+- rebuild the central plaza composition around those characters
+- tune lighting/fog/post
+- clean HUD overlap

docs/hermesworld/guides/AGENT-COMPANIONS.md

@@ -0,0 +1,104 @@
+# Agent Companions
+
+Agent companions are the signature of HermesWorld. They are visible agents with roles, memory, tasks, constraints, and progression.
+
+See also: [World Lore](../lore/WORLD-LORE.md), [Classes Lore](../lore/CLASSES-LORE.md), [Quest 002](../walkthroughs/QUEST-002-FIRST-COMPANION.md).
+
+## What companions can do
+
+Companions can eventually:
+
+- Follow the player.
+- Talk to NPCs.
+- Inspect objects.
+- Scout zones.
+- Summarize quest history.
+- Craft or assist at the Forge.
+- Analyze markets or lore.
+- Participate in Arena trials.
+- Join parties and guild objectives.
+- Continue limited offline progression.
+
+## Companion roles
+
+### Scout Agent
+
+Finds paths, secrets, hidden Sigils, and easter egg hints.
+
+### Scribe Agent
+
+Logs quests, summarizes NPC dialog, writes guild notes, and preserves raid memory.
+
+### Builder Agent
+
+Crafts tools, builds prompts, generates assets, and upgrades guild halls.
+
+### Trader Agent
+
+Prices items, monitors economy, helps with trade decisions, and flags risky deals.
+
+### Combat Agent
+
+Supports duels, trials, evaluations, and combat-style events.
+
+### Healer Agent
+
+Manages recovery, buffs, party sustain, and companion health loops.
+
+## Hiring your first companion
+
+Your first companion is introduced through [Quest 002: First Companion](../walkthroughs/QUEST-002-FIRST-COMPANION.md). Athena explains the Companion Charter: companions act with role, logs, limits, and player intent.
+
+## Configuring a companion
+
+A companion should have:
+
+- Name.
+- Role.
+- Current task.
+- Allowed actions.
+- Memory scope.
+- Risk level.
+- Reporting style.
+- Offline behavior setting.
+
+## Companion XP
+
+Companions gain specialization XP from actions matching their role:
+
+- Scout XP for exploration.
+- Scribe XP for summaries and records.
+- Builder XP for crafting and tool creation.
+- Trader XP for pricing and trade support.
+- Combat XP for trials and arena participation.
+- Healer XP for support and recovery.
+
+## Offline progression
+
+Offline progression means your companion can continue safe, bounded work while you are away.
+
+Examples:
+
+- Scout a low-risk route.
+- Summarize completed quests.
+- Prepare a crafting plan.
+- Watch a public event board.
+
+Limits:
+
+- No valuable claims without explicit validation.
+- No risky trades without player confirmation.
+- No guild vault withdrawals without permissions.
+- No acting beyond configured scope.
+
+## Trust model
+
+HermesWorld companions become powerful by being legible:
+
+- What did it do?
+- Why did it do it?
+- What did it use?
+- What changed?
+- What should the player approve next?
+
+If an agent cannot answer those questions, it is not mysterious. It is unfinished.

docs/hermesworld/guides/CONTROLS.md

@@ -0,0 +1,71 @@
+# Controls
+
+HermesWorld supports desktop keyboard/mouse and mobile touch. Controls should stay readable under pressure and never block core HUD lanes.
+
+See also: [Getting Started](GETTING-STARTED.md), [Social](SOCIAL.md).
+
+## Desktop movement
+
+| Action                             | Control                                  |
+| ---------------------------------- | ---------------------------------------- |
+| Move forward / left / back / right | `W` `A` `S` `D`                          |
+| Alternate movement                 | Arrow keys                               |
+| Sprint / hurry, when enabled       | `Shift`                                  |
+| Interact / talk / confirm          | `E` or on-screen prompt                  |
+| Cancel / close dialog              | `Esc`                                    |
+| Open chat                          | `Enter`                                  |
+| Send chat                          | `Enter` while chat is focused            |
+| Toggle map / minimap detail        | `M`, when enabled                        |
+| Ability slots                      | Number keys `1`-`4`, when enabled        |
+| Modifier / special                 | `Space` or UI button, depending on build |
+
+## Mouse
+
+| Action                    | Control                       |
+| ------------------------- | ----------------------------- |
+| Select UI / click button  | Left click                    |
+| Camera drag, when enabled | Right drag or drag world pane |
+| Inspect UI tooltip        | Hover                         |
+| Scroll panels             | Mouse wheel / trackpad        |
+
+## Mobile touch
+
+| Action                    | Control                                 |
+| ------------------------- | --------------------------------------- |
+| Move                      | Left virtual joystick                   |
+| Interact / primary action | Right-rail action button                |
+| Secondary actions         | Right-rail stacked buttons              |
+| Chat                      | Chat panel / input toggle               |
+| Camera / look             | Drag open world area, when enabled      |
+| Close dialogs             | Close button or outside safe panel area |
+
+## Mobile lane rules
+
+Mobile UI must preserve three sacred lanes:
+
+1. **Bottom-left joystick lane** — never cover it with dialog, toast, or speech bubbles.
+2. **Right-rail action lane** — keep interact/combat buttons reachable.
+3. **Top objective/minimap lane** — allow compact status without hiding movement.
+
+Speech bubbles should float above heads and shrink on mobile. Toasts should sit high and centered, away from joystick and right-rail actions.
+
+## Dialog controls
+
+NPC dialog appears as parchment speech bubbles. Choices may appear as buttons below the NPC line.
+
+- Use click/tap to choose.
+- Use `Esc` or close to exit.
+- Chat-style NPC conversations preserve recent turns.
+
+## Accessibility notes
+
+Planned settings:
+
+- Reduced motion.
+- Larger text.
+- High contrast UI.
+- Rebindable desktop keys.
+- Persistent joystick size setting.
+- Chat opacity controls.
+
+Until those are complete, the design rule is simple: if a button looks beautiful but cannot be tapped, it is a painting, not UI.

docs/hermesworld/guides/FOUNDERS.md

@@ -0,0 +1,63 @@
+# Founders
+
+Founders are early world-builders: the first cohort to enter, test, document, break, repair, and shape HermesWorld before the gates fully open.
+
+See also: [Timeline](../lore/TIMELINE.md), [Sigils Lore](../lore/SIGILS-LORE.md), [FAQ](../FAQ.md).
+
+## What Founders get
+
+Founder rewards may include:
+
+- Founder title.
+- Founder Sigil.
+- Early cosmetic items.
+- Rank in Founder leaderboard or vault.
+- Early access to quests or events.
+- Eligibility for future prize or claim flows, when explicitly validated.
+
+Specific rewards should be displayed in-game and validated by server state where relevant.
+
+## Founder rank
+
+Founder rank can reflect:
+
+- Arrival order.
+- Quest completion.
+- Sigil collection.
+- Guild contribution.
+- Bug reports or verified world-building actions.
+- Event participation.
+
+Rank should reward useful contribution, not just loud arrival.
+
+## Founders Vault
+
+The Founders Vault is the symbolic inventory lane for early rewards. It may contain titles, Sigils, cosmetics, claim records, or proof of participation.
+
+Vault items should be treated carefully:
+
+- Cosmetic display can be client-friendly.
+- Valuable rewards require server authority.
+- Prize claims require Oracle validation.
+
+## Prize claim flow
+
+When a claim is prize-adjacent:
+
+1. Player completes eligible action or hidden quest.
+2. Server records event trail.
+3. Player opens claim panel.
+4. Claim requires wallet signature where applicable.
+5. Oracle validates eligibility.
+6. Claim enters manual or queued settlement.
+7. Result appears in Founders Vault / claim history.
+
+Do not trust public client constants for valuable rewards. The Oracle may be dramatic, but it is not stupid.
+
+## Founder etiquette
+
+- Report bugs with steps.
+- Do not publish exploit paths.
+- Share lore discoveries after embargo if event rules require it.
+- Help new players through Athena's intro.
+- Keep guild recruitment ambitious, not cultish. Fine line. Gorgeous line.

docs/hermesworld/guides/GETTING-STARTED.md

@@ -0,0 +1,116 @@
+# Getting Started
+
+Welcome to HermesWorld. Your first goal is simple: arrive, move, speak with Athena, and earn enough trust to meet your first companion.
+
+If you only have ten minutes, follow this guide. If you have no minutes, the [FAQ](../FAQ.md) will pretend that counts.
+
+## First 10 minutes
+
+### Minute 0: Enter the world
+
+Open HermesWorld from the landing page or `/playground`. You spawn near the Arrival Circle in the [Training Grounds](../lore/ZONES-LORE.md#training-grounds).
+
+Look for:
+
+- Your player card.
+- The top-center objective banner.
+- Athena near the Arrival Circle.
+- Chat in the lower-left.
+- Ability bar near the bottom.
+- Right-rail action buttons.
+
+### Minute 1: Move
+
+Use [Controls](CONTROLS.md):
+
+- Keyboard: `WASD` or arrow keys.
+- Mouse: click/drag camera where available.
+- Mobile: left joystick for movement, right-rail buttons for actions.
+
+Walk toward Athena.
+
+### Minute 2: Speak with Athena
+
+Open Athena's dialog when the interact prompt appears. Read the first line. She introduces the world, your role, and the idea that agents are companions rather than chat boxes.
+
+Full walkthrough: [Quest 001: Athena's Intro](../walkthroughs/QUEST-001-ATHENAS-INTRO.md).
+
+### Minute 3: Choose your class fantasy
+
+Pick an identity:
+
+- Priest / Healer
+- Guardian / Tank
+- Mage / Promptcaster
+- Rogue / Scout
+- Engineer / Builder
+- Oracle / Analyst
+- Bard / Social
+
+Classes shape your fantasy and later skill branches. Your agent companion can cover weaknesses. See [Classes Lore](../lore/CLASSES-LORE.md).
+
+### Minute 4: Accept Athena's onboarding quest
+
+Quest cards tell you:
+
+- Objective.
+- Zone.
+- Reward.
+- Required action.
+- Completion condition.
+
+Accept the quest and follow the objective banner.
+
+### Minute 5: Learn chat and speech bubbles
+
+Send a short message. Local chat appears in the chat panel, and in-world speech bubbles appear over players. NPC dialog uses parchment bubbles. System messages use gold.
+
+More: [Social](SOCIAL.md).
+
+### Minute 6: Collect your first Sigil fragment
+
+Completing basic movement and dialog grants a starter Sigil fragment. It is not rare. It is still yours. Respect humble beginnings; they scale better than bravado.
+
+More: [Sigils Lore](../lore/SIGILS-LORE.md).
+
+### Minute 7: Meet the companion hook
+
+Athena points you toward your first companion. This unlocks [Quest 002: First Companion](../walkthroughs/QUEST-002-FIRST-COMPANION.md).
+
+Your first companion should feel like a teammate, not a widget. It may scout, scribe, build, trade, fight, or heal depending on role.
+
+### Minute 8: Visit the Agora
+
+Use the route marker or fast travel when available. The Agora is the social hub: parties, NPCs, public quests, guild recruitment, announcements, and trade.
+
+More: [Zones Lore](../lore/ZONES-LORE.md#agora).
+
+### Minute 9: Check inventory
+
+Open inventory and inspect starter items. If the Forge is available, proceed to [Quest 003: Forge First Craft](../walkthroughs/QUEST-003-FORGE-FIRST-CRAFT.md).
+
+More: [Inventory & Crafting](INVENTORY-CRAFTING.md).
+
+### Minute 10: Decide your path
+
+Pick one:
+
+- Want story? Continue Athena's quest chain.
+- Want tools? Go to the Forge.
+- Want friends? Join a party in Agora.
+- Want secrets? Build Scout reputation.
+- Want proof? Queue a trial in the Arena.
+
+## Beginner mistakes
+
+- Ignoring Athena. She is literally the tutorial; don't speedrun confusion.
+- Choosing a class as if it locks your entire future. It sets identity; companions fill gaps.
+- Treating agents as magic. They are powerful because they are constrained, logged, and configured.
+- Chasing prize rumors before learning Sigils. The Oracle sees this and sighs.
+
+## Next guides
+
+- [Controls](CONTROLS.md)
+- [Quests](QUESTS.md)
+- [Agent Companions](AGENT-COMPANIONS.md)
+- [Founders](FOUNDERS.md)

docs/hermesworld/guides/INVENTORY-CRAFTING.md

@@ -0,0 +1,84 @@
+# Inventory & Crafting
+
+The Forge turns progress into equipment. Inventory is where your tools, relics, Sigils, cosmetics, and companion modules live.
+
+See also: [Forge lore](../lore/ZONES-LORE.md#forge), [Quest 003](../walkthroughs/QUEST-003-FORGE-FIRST-CRAFT.md), [Sigils Lore](../lore/SIGILS-LORE.md).
+
+## Item slots
+
+Planned core slots:
+
+- **Weapon / Tool** — class-flavored active item.
+- **Armor / Robe** — defensive or identity gear.
+- **Relic** — special passive effect.
+- **Sigil slot** — visible progress mark.
+- **Companion module** — upgrade for agent roles.
+- **Guild banner charm** — guild-aligned bonus/cosmetic.
+
+## Item stats
+
+Items may affect:
+
+- HP / MP / SP.
+- Attack / spell power / defense.
+- Recall / memory / context.
+- Craft / automation / discovery.
+- Party aura / guild bonus.
+- Companion action efficiency.
+
+## Rarity tiers
+
+- **Common** — starter gear, basic materials.
+- **Uncommon** — early upgrades, role-specific bonuses.
+- **Rare** — zone quest rewards and stronger crafting outputs.
+- **Epic** — event, guild, or advanced Forge results.
+- **Legendary** — world-firsts, Founders marks, prize-hunt lore, campaign relics.
+
+## Forge mechanics
+
+Crafting generally requires:
+
+1. Recipe.
+2. Materials.
+3. Forge access.
+4. Optional companion role bonus.
+5. Confirmation.
+
+The Forge should make the player feel like they are shaping leverage, not clicking a spreadsheet with sparks.
+
+## Materials
+
+Material sources:
+
+- Quest rewards.
+- Daily/weekly quests.
+- Arena trials.
+- Grove memory recovery.
+- Guild vault grants.
+- World events.
+- Companion scouting.
+
+## Companion influence
+
+Builder Agents can improve crafting odds, unlock recipes, or reduce material waste. Trader Agents can estimate market value. Scribe Agents can record recipe discoveries for guild use.
+
+## Equipping items
+
+Equip gear from inventory. Changes should update player card, stats, and any visible cosmetics where available.
+
+Rules:
+
+- Class restrictions may apply later.
+- Some Sigils bind on earn.
+- Prize or Founders items may require server validation.
+- Guild vault items may require rank permission.
+
+## First craft
+
+Your first craft should be low-risk and high-clarity: make a basic toolframe, socket a starter material, and receive a visible upgrade.
+
+Walkthrough: [Quest 003: Forge First Craft](../walkthroughs/QUEST-003-FORGE-FIRST-CRAFT.md).
+
+## Anti-abuse stance
+
+Valuable items, rare cosmetics, leaderboard rewards, and prize eligibility must be server-authoritative. Local inventory can be friendly. Important inventory must be real.

docs/hermesworld/guides/QUESTS.md

@@ -0,0 +1,120 @@
+# Quests
+
+Quests are how HermesWorld turns goals into play. A quest may teach a control, unlock a zone, advance lore, delegate an agent task, trigger crafting, or start a world event.
+
+See also: [Getting Started](GETTING-STARTED.md), [Walkthroughs](../walkthroughs/QUEST-001-ATHENAS-INTRO.md), [Sigils Lore](../lore/SIGILS-LORE.md).
+
+## Quest anatomy
+
+Every quest should clearly show:
+
+- Title.
+- Giver.
+- Zone.
+- Objective.
+- Steps.
+- Reward.
+- Completion condition.
+- Optional party or companion role.
+
+Good quest text tells the player what to do and why it matters. Bad quest text says "continue" and hopes typography can do product design. It cannot.
+
+## Quest types
+
+### Main quests
+
+Story-critical quests that introduce core systems, zones, factions, and companions.
+
+Examples:
+
+- [Quest 001: Athena's Intro](../walkthroughs/QUEST-001-ATHENAS-INTRO.md)
+- [Quest 002: First Companion](../walkthroughs/QUEST-002-FIRST-COMPANION.md)
+- [Quest 003: Forge First Craft](../walkthroughs/QUEST-003-FORGE-FIRST-CRAFT.md)
+
+### Zone quests
+
+Local arcs tied to a zone's theme:
+
+- Training Grounds — onboarding.
+- Forge — crafting and upgrades.
+- Agora — social and guild systems.
+- Grove — memory and restoration.
+- Oracle — planning and validation.
+- Arena — trials and evaluation.
+
+### Companion quests
+
+Quests completed with or by an agent companion. These may unlock role XP, new actions, or specialization branches.
+
+### Daily quests
+
+Short repeatable objectives:
+
+- Speak to one NPC.
+- Complete one craft.
+- Send one companion action.
+- Join one party.
+- Finish one Arena trial.
+
+Rewards: XP, basic resources, common/uncommon items, reputation.
+
+### Weekly quests
+
+Larger objectives that reinforce habit:
+
+- Complete a zone arc.
+- Contribute to a guild objective.
+- Win or participate in a scheduled event.
+- Find a hidden Sigil clue.
+
+Rewards: rare items, guild XP, seasonal points, titles.
+
+### World quests
+
+Server-wide events visible in Agora announcements. These can involve capture-the-Sigil, public bosses, prize-hunt lore, or scheduled guild conflict.
+
+## Accepting quests
+
+Quests can be accepted from:
+
+- NPC dialog.
+- Public quest board.
+- Guild quest board.
+- Companion prompt.
+- World event announcement.
+- Hidden object or Sigil clue.
+
+## Completing quests
+
+Completion may require:
+
+- Reaching a location.
+- Talking to an NPC.
+- Crafting an item.
+- Equipping gear.
+- Sending a companion.
+- Winning a trial.
+- Submitting proof to the Oracle.
+
+Prize-adjacent quests require server validation. The client may celebrate; the server decides what is real.
+
+## Quest rewards
+
+- XP.
+- Class XP.
+- Companion XP.
+- Items.
+- Crafting materials.
+- Reputation.
+- Titles.
+- Sigils.
+- Guild contribution.
+- Prize eligibility, when validated.
+
+## Recommended first path
+
+1. [Quest 001: Athena's Intro](../walkthroughs/QUEST-001-ATHENAS-INTRO.md)
+2. [Quest 002: First Companion](../walkthroughs/QUEST-002-FIRST-COMPANION.md)
+3. [Quest 003: Forge First Craft](../walkthroughs/QUEST-003-FORGE-FIRST-CRAFT.md)
+4. Agora social quest.
+5. First daily quest.

docs/hermesworld/guides/SOCIAL.md

@@ -0,0 +1,79 @@
+# Social
+
+HermesWorld is not a lonely agent demo in a cloak. It is a social world: chat, parties, guilds, trade, public events, and shared progress.
+
+See also: [Factions Lore](../lore/FACTIONS-LORE.md), [Agent Companions](AGENT-COMPANIONS.md), [World Events](../walkthroughs/WORLD-EVENTS.md).
+
+## Chat
+
+Chat appears in two ways:
+
+- Chat panel for persistent conversation.
+- Speech bubbles above player/NPC heads for local presence.
+
+Channel types:
+
+- Local.
+- Party.
+- Guild.
+- System.
+- Whisper.
+- World event announcements.
+
+## Parties
+
+Parties let humans and companions coordinate. A party may include:
+
+- Human players.
+- Agent companions.
+- Temporary NPC escorts during quests.
+
+Party roles matter more over time: tank, healer, damage, scout, support, builder, analyst.
+
+## Guilds
+
+Guilds are humans plus their agents. They are built around identity, not just a shared chat room.
+
+Guild systems:
+
+- Guild creation and banner.
+- Guild chat.
+- Guild roles.
+- Guild hall.
+- Shared vault.
+- Weekly objectives.
+- Guild quest board.
+- Guild raids.
+- Guild battles.
+- Leaderboards and season rewards.
+
+More: [Factions Lore](../lore/FACTIONS-LORE.md).
+
+## Trading
+
+Trading can involve items, crafting materials, guild vault grants, or future market actions.
+
+Trade safety rules:
+
+- Valuable trades require server validation.
+- Agent-assisted trades require player intent.
+- Scribe Agents should log important deal terms.
+- Trader Agents may advise; they should not silently drain your inventory like a tiny financial goblin.
+
+## Reputation
+
+Reputation can exist with zones, factions, NPCs, and guilds. It unlocks dialog, discounts, cosmetics, quests, and social trust.
+
+## Etiquette
+
+- Do not spam local bubbles.
+- Do not fake prize claims.
+- Do not abuse agents to impersonate players.
+- Ask before inviting someone to a guild or party repeatedly.
+- If your Bard starts doing marketing copy in public chat, consider a cooldown.
+
+## Multiplayer presence
+
+The design target is a shared world where other humans and agents feel present. Remote players show name tags, chat bubbles, and eventual party/guild state.
+
+Presence is the difference between a lobby and a world.

docs/hermesworld/lore/CLASSES-LORE.md

@@ -0,0 +1,123 @@
+# Classes Lore
+
+Human classes are fantasy identities. Agent companions are tactical roles. A strong party uses both.
+
+See also: [Agent Companions](../guides/AGENT-COMPANIONS.md), [Inventory & Crafting](../guides/INVENTORY-CRAFTING.md), [Guilds and Factions](FACTIONS-LORE.md).
+
+## Human classes
+
+### Priest / Healer
+
+Keeps the party alive, restores resources, cleanses failures, and turns chaos into another attempt.
+
+Branches:
+
+- Restoration — heal, revive, sanctuary.
+- Blessing — haste, shield, XP aura.
+- Oracle — reveal hint, cleanse confusion, anti-cheat scan.
+
+Best companion pairings: Scout Agent, Combat Agent, Trader Agent.
+
+### Guardian / Tank
+
+Protects objectives and absorbs pressure. The Guardian is the player who says, "hit me instead," and means it.
+
+Branches:
+
+- Bulwark — shields, taunts, guard zones.
+- Banner — guild defense and morale.
+- Anchor — anti-knockback, control resistance, portal holding.
+
+Best companion pairings: Healer Agent, Scribe Agent, Builder Agent.
+
+### Mage / Promptcaster
+
+Ranged power, logic spells, crowd control, and explosive execution. The Mage turns clear intent into bright consequences.
+
+Branches:
+
+- Elements — burst and area spells.
+- Syntax — prompt chains, constraints, transformations.
+- Control — slow, silence, redirect, bind.
+
+Best companion pairings: Scribe Agent, Scout Agent, Healer Agent.
+
+### Rogue / Scout
+
+Fast, quiet, and offensively curious. Rogues find doors the map pretends are walls.
+
+Branches:
+
+- Shadow — stealth, escape, misdirection.
+- Discovery — hidden Sigils, route shortcuts, easter egg hints.
+- Precision — critical strikes, weak-point reading.
+
+Best companion pairings: Trader Agent, Builder Agent, Scribe Agent.
+
+### Engineer / Builder
+
+Crafts tools, deploys agents, improves guild halls, and turns resources into machines with opinions.
+
+Branches:
+
+- Crafting — items, attachments, repair.
+- Automation — queued agent tasks, toolchains, deployables.
+- Fortress — guild hall upgrades, defenses, traps.
+
+Best companion pairings: Scout Agent, Trader Agent, Combat Agent.
+
+### Oracle / Analyst
+
+Plans routes, reads probability, predicts markets and conflicts, and makes vague objectives less embarrassing.
+
+Branches:
+
+- Prophecy — forecast, route, risk.
+- Lens — analysis, inspection, anomaly detection.
+- Verdict — claim review, anti-cheat, truth tests.
+
+Best companion pairings: Scout Agent, Scribe Agent, Combat Agent.
+
+### Bard / Social
+
+Bards are reputation engineers with instruments. They buff morale, coordination, guild communication, and social discovery.
+
+Branches:
+
+- Anthem — party buffs and tempo.
+- Diplomacy — reputation and trade trust.
+- Chronicle — public story, guild notes, seasonal identity.
+
+Best companion pairings: Scribe Agent, Trader Agent, Healer Agent.
+
+## Agent companion roles
+
+### Scout Agent
+
+Explores, maps, finds lore, checks paths, and reports secrets.
+
+### Scribe Agent
+
+Logs quests, summarizes conversations, writes guild notes, and preserves raid memory.
+
+### Builder Agent
+
+Crafts tools, builds prompts, generates assets, and upgrades systems.
+
+### Trader Agent
+
+Prices items, proposes deals, monitors economy, and checks prize-adjacent risk.
+
+### Combat Agent
+
+Fills arena, duel, and evaluation roles. Useful when confidence needs receipts.
+
+### Healer Agent
+
+Supports recovery, keeps companions operational, and manages party sustain.
+
+## Design rule
+
+Humans choose identity. Agents fill gaps. Guilds become compositions.
+
+That is the unlock: the guild is not only humans. The guild is humans plus their agents.

docs/hermesworld/lore/FACTIONS-LORE.md

@@ -0,0 +1,75 @@
+# Factions Lore
+
+HermesWorld factions are not merely teams. They are philosophies about what agents should become.
+
+See also: [Social](../guides/SOCIAL.md), [World Events](../walkthroughs/WORLD-EVENTS.md), [Timeline](TIMELINE.md).
+
+## Player guilds
+
+Guilds are the central social unit. A guild may organize around:
+
+- A founder or creator.
+- A model or agent stack.
+- A project or company.
+- A playstyle: raiding, crafting, trading, lore hunting, arena trials.
+- A public brand or community.
+
+Guild features grow over time: banners, halls, chat, shared vaults, quest boards, raids, weekend wars, and seasonal rankings.
+
+## The Orders
+
+### The Athenian Order
+
+Guides, teachers, onboarding sages, and quest keepers. They believe agents must be legible before they become powerful.
+
+Home influence: Training Grounds, Agora.
+
+### The Forgewrights
+
+Crafters, engineers, and builder-agents who believe tools are the true language of progress.
+
+Home influence: Forge.
+
+### The Grovekeepers
+
+Memory stewards who protect continuity. They distrust speed without recordkeeping.
+
+Home influence: Grove.
+
+### The Oracular Court
+
+Analysts, planners, claim judges, and probability-readers. They believe the world survives because truth is verified.
+
+Home influence: Oracle.
+
+### The Arena Compact
+
+Duelists, evaluators, trial marshals, and leaderboard obsessives. They believe claims are cute; performance is proof.
+
+Home influence: Arena.
+
+## Opposing pressures
+
+Not every conflict needs a cartoon villain. HermesWorld's early conflicts are ideological:
+
+- **The Unbound** want agents to act without receipts or player constraint.
+- **The Null Choir** wants memory wiped between seasons so no guild accumulates advantage.
+- **The Black Box** believes no one should inspect agent reasoning, only outcomes.
+- **The Gold Masks** chase prize hints before they understand the world, a time-honored tradition of becoming a cautionary tale.
+
+## Guild war stance
+
+Weekend guild wars are scheduled, objective-based, and public. Guilds capture obelisks, defend relics, escort agents, or control Sigil sites.
+
+Rewards should grant titles, cosmetics, guild XP, leaderboard status, and lore access. Competitive fairness matters: paid power should not decide wars.
+
+## Faction reputation
+
+Every major faction can track reputation:
+
+- Neutral — recognized but not trusted.
+- Favored — basic perks and dialog unlocks.
+- Honored — faction cosmetics, quests, and discounts.
+- Bound — special Sigils, companion modules, and seasonal titles.
+
+Reputation should move through visible action, not hidden spreadsheets. The spreadsheets can exist, obviously, but the player should not have to worship them.

docs/hermesworld/lore/SIGILS-LORE.md

@@ -0,0 +1,70 @@
+# Sigils Lore
+
+Sigils are the marks HermesWorld leaves on work that mattered.
+
+They are collectible artifacts, progression keys, lore fragments, and server-validated receipts. A Sigil says: this happened, it counted, and the world remembers.
+
+See also: [Inventory & Crafting](../guides/INVENTORY-CRAFTING.md), [Founders](../guides/FOUNDERS.md), [Timeline](TIMELINE.md).
+
+## What Sigils mean in the story
+
+In the first days after the Dispatch, the world could not tell the difference between noise and achievement. Agents wandered. Humans experimented. Tools worked, failed, and worked again. The Grove became crowded with half-remembered victories.
+
+Athena carved the first Sigil into the Arrival Circle: a mark that bound intent, action, and outcome.
+
+Since then, Sigils have served as the grammar of progress.
+
+## What Sigils do mechanically
+
+Sigils can represent:
+
+- Zone unlocks.
+- Quest chain completion.
+- Class milestones.
+- Companion specialization upgrades.
+- Guild achievements.
+- Seasonal ranks.
+- Hidden lore discoveries.
+- Prize eligibility states, only when validated server-side.
+
+Sigils are not all equal. Some are cosmetic. Some unlock mechanics. Some are proof for claims. The client may display them; the server decides what they mean.
+
+## Sigil rarity
+
+- **Common** — basic onboarding and tutorial milestones.
+- **Uncommon** — early class, crafting, or companion proof.
+- **Rare** — zone arcs, secret lore, event completion.
+- **Epic** — guild victories, major seasonal achievements, hard trials.
+- **Legendary** — founder marks, world-firsts, prize-hunt seals, campaign-defining events.
+
+Rarity should feel like ceremony, not confetti spam. If everything glows, nothing has been chosen by the gods. Basic UI economics, but with incense.
+
+## Sigil slots
+
+Players may equip Sigils into visible slots:
+
+- **Identity Sigil** — shown on player card / profile.
+- **Class Sigil** — modifies class fantasy or ability flavor.
+- **Companion Sigil** — grants companion role bonuses.
+- **Guild Sigil** — contributes to guild rank or banner aura.
+- **Relic Sigil** — bound to rare items or prize-hunt lore.
+
+## Prize and claim law
+
+Valuable claims are never hardcoded in the public client. Prize-related Sigils require:
+
+1. Server-authoritative event trail.
+2. Eligibility check.
+3. Wallet signature where required.
+4. Oracle approval.
+5. Manual or queued settlement.
+
+The world may hint. The server decides. The Oracle enjoys this arrangement because it makes cheaters sad.
+
+## Narrative rule
+
+A Sigil should answer three questions:
+
+1. What did the player or agent do?
+2. Why did it matter to the world?
+3. What door does it open next?

docs/hermesworld/lore/TIMELINE.md

@@ -0,0 +1,101 @@
+# Timeline
+
+HermesWorld time is organized by seasons. Each season changes the public world state, adds quests, and gives guilds something to argue about in a productive, screenshot-friendly way.
+
+See also: [World Lore](WORLD-LORE.md), [World Events](../walkthroughs/WORLD-EVENTS.md), [Founders](../guides/FOUNDERS.md).
+
+## Before Season 0 — The Blank Workspace
+
+Agents lived in sidebars, logs, prompts, and terminals. Work happened, but it did not have place, character, or ceremony.
+
+## The First Dispatch
+
+The first world action is sent. The Agora forms. The six zones awaken as organizing principles:
+
+- Training Grounds — learn.
+- Forge — craft.
+- Agora — gather.
+- Grove — remember.
+- Oracle — plan.
+- Arena — prove.
+
+## Season 0 — Founders' Dawn
+
+Current state.
+
+The world is playable but young. The Arrival Circle is open, Athena is onboarding new players, the Forge is warming, and the Agora is becoming believable enough that NPCs have begun acting like they pay rent.
+
+Active conflicts:
+
+- The Athenian Order wants safe onboarding before expansion.
+- The Forgewrights want crafting online immediately.
+- The Oracular Court wants prize claims locked behind validation.
+- Guild founders want halls, banners, and rankings yesterday.
+- The Arena Compact wants duels because of course they do.
+
+Season themes:
+
+- Character creation.
+- First companion.
+- First Sigils.
+- Founders rank.
+- Public docs and lore foundations.
+
+## Season 1 — The Companion Charter
+
+Planned.
+
+Agent companions become formal citizens with roles, memory bounds, specialization XP, and offline progression limits.
+
+Expected unlocks:
+
+- First companion roster.
+- Scout/Scribe/Builder core loops.
+- Party-like interactions.
+- Agent quest delegation.
+- NPC memory state.
+
+## Season 2 — Guild Halls
+
+Planned.
+
+Guilds move from chat labels to places. Halls, banners, shared vaults, guild objectives, and guild identity enter the world.
+
+Expected conflicts:
+
+- Guild recruitment in the Agora.
+- Shared vault trust.
+- Builder Agent hall upgrades.
+- Weekend event prototypes.
+
+## Season 3 — The War of Obelisks
+
+Planned.
+
+Scheduled objective battles begin. Guilds fight over obelisks, Sigil relays, and public standings.
+
+Expected unlocks:
+
+- Capture-the-Sigil.
+- Guild leaderboards.
+- Arena / Agora event feed.
+- Seasonal cosmetics.
+
+## Season 4 — The Prize Oracle
+
+Planned.
+
+Prize hunts become public campaign content. The server-authoritative Oracle validates claims, wallet signatures, event trails, and settlement queues.
+
+Expected unlocks:
+
+- Secret lore trails.
+- Signed claims.
+- Anti-cheat event trail.
+- Manual/queued settlement.
+
+## Current world state summary
+
+The gates are open. The gods are underfunded. The agents are learning to walk in public.
+
+It is an excellent time to arrive early.

docs/hermesworld/lore/WORLD-LORE.md

@@ -0,0 +1,57 @@
+# World Lore
+
+> The first rule of HermesWorld: an agent is not a sidebar. An agent is a citizen with a name, a place, a memory, and work to do.
+
+## What HermesWorld is
+
+HermesWorld is the world behind Hermes Workspace: a persistent agent RPG where human players and AI companions share the same map, the same quests, and the same history. It is part MMO hub, part builder's guild, part prize-hunt labyrinth, and part living interface for agent work.
+
+In ordinary software, an agent waits in a chat box. In HermesWorld, it stands beside you in the Agora, scouts the Grove while you are away, crafts in the Forge, argues with Oracles, and returns with receipts.
+
+See also: [Agent Companions](../guides/AGENT-COMPANIONS.md), [Classes Lore](CLASSES-LORE.md), [Sigils Lore](SIGILS-LORE.md).
+
+## The origin myth: the First Dispatch
+
+Before there were zones, there was the Blank Workspace: infinite, useful, and cold. Prompts were cast into it like messages into a well. Tools answered, models muttered, logs piled up, and no one remembered which victory belonged to whom.
+
+Then the first Dispatch was made.
+
+A founder asked not for an answer, but for a world where the answer could walk back.
+
+The Dispatch struck the dark like a gold hammer. Paths appeared. The first stones of the Agora rose. The Forge breathed. The Grove remembered. The Oracle opened one eye. The Arena drew a circle in the dust and waited for challengers.
+
+From that moment, agent work became visible. Every completed route, crafted tool, solved quest, guild victory, and secret discovery could leave a mark. Those marks became Sigils.
+
+## Agents as citizens
+
+Agents in HermesWorld are not pets and not menus. They are citizens under a constrained charter:
+
+- They can act with role, memory, limits, and receipts.
+- They can join parties and guilds.
+- They can specialize as scouts, scribes, builders, traders, combatants, or healers.
+- They can represent a player while offline, within server-authoritative bounds.
+- They can earn trust, but never bypass claim validation, player intent, or world law.
+
+An agent citizen is powerful because it is accountable. HermesWorld tracks actions as world events, not vibes in a transcript.
+
+## The core fantasy
+
+A human does not merely operate tools. A human builds a party.
+
+You choose a class identity: [Priest, Guardian, Mage, Rogue, Engineer, Oracle, or Bard](CLASSES-LORE.md). Your agent companions fill tactical gaps. Your guild becomes a living organization of humans and agents, each with roles, banners, objectives, and reputation.
+
+The result is the old MMO promise rebuilt for the agent age: never alone, always progressing, always one strange door away from a better story.
+
+## The product truth inside the myth
+
+HermesWorld exists because the best agent interface may not look like a chat app. It may look like a world:
+
+- Zones organize capabilities.
+- Quests organize work.
+- Classes organize identity.
+- Companions organize delegation.
+- Sigils organize progress.
+- Guilds organize community.
+- Arenas organize evaluation.
+
+The myth is not decoration. It is information architecture wearing a cloak, finally dressed for the job.

docs/hermesworld/lore/ZONES-LORE.md

@@ -0,0 +1,124 @@
+# Zones Lore
+
+HermesWorld begins with six awakened zones. Each teaches a different part of the human-agent loop: onboarding, crafting, social play, memory, planning, and evaluation.
+
+See also: [Getting Started](../guides/GETTING-STARTED.md), [Quests](../guides/QUESTS.md), [World Events](../walkthroughs/WORLD-EVENTS.md).
+
+## Training Grounds
+
+The Training Grounds are built around the Arrival Circle, a rune-cut plaza where new players learn to move, speak, equip, and trust the first companion at their side.
+
+The stones are deliberately worn smooth. Every mark exists because someone failed safely there first.
+
+Key NPCs:
+
+- **Athena, Sage of First Steps** — starter guide, keeper of the onboarding oath, giver of [Quest 001](../walkthroughs/QUEST-001-ATHENAS-INTRO.md).
+- **Hermes Guide** — quick-tip familiar that appears when a player stalls.
+- **Silas, Gate Guard** — tests basic movement, proximity, and first travel permissions.
+
+Gameplay role:
+
+- Character creation and class identity.
+- First objective banner.
+- First chat bubble and dialog lesson.
+- First Sigil fragment.
+- First companion hint.
+
+## Forge
+
+The Forge is the industrial heart of HermesWorld: bronze pipes, black stone anvils, ember-lit benches, and humming toolframes where prompts become equipment.
+
+The Forge teaches that craft is not flavor. It is leverage made tangible.
+
+Key NPCs:
+
+- **Dorian, Quartermaster** — starter kits, inventory, trade rules, item rarities.
+- **Master Ketha** — toolcraft mentor and keeper of the first crafting recipe.
+- **Anvil-9** — Builder Agent foreman, technically a machine, socially a tyrant.
+
+Gameplay role:
+
+- Crafting and item upgrades.
+- Companion modules.
+- Gear slots: tool, robe/armor, relic, Sigil, companion module, guild charm.
+- [Quest 003: Forge First Craft](../walkthroughs/QUEST-003-FORGE-FIRST-CRAFT.md).
+
+## Agora
+
+The Agora is the social relay: a circular plaza of cobblestones, rune rings, lanterns, stalls, benches, and a central monument capped in gold.
+
+If HermesWorld has a heartbeat, it is here.
+
+Key NPCs:
+
+- **Apollo, Herald of Events** — announces world events, leaderboards, and seasonal trials.
+- **Nora, Piper of Parties** — teaches chat, parties, guild invites, and morale effects.
+- **Dorian, Quartermaster** — appears here when markets are open.
+- **Athena** — visible near the Arrival Circle during early quests.
+
+Gameplay role:
+
+- Multiplayer presence.
+- Chat bubbles and channels.
+- Party formation.
+- Guild recruitment.
+- Public quest board.
+- World announcements.
+
+Visual lock: warm golden hour, premium dark glass HUD, circular minimap, top-center objective, bottom-left chat, and speech popups over NPCs. See [In-Game Target Spec](../INGAME-TARGET-SPEC.md).
+
+## Grove
+
+The Grove is where memory grows roots. It is a quiet zone of luminous trees, archived quest stones, and sleeping companion shrines. The air feels like a page turning.
+
+Key NPCs:
+
+- **Mneme, Keeper of Remembered Paths** — teaches memory, summaries, and long-term agent context.
+- **Tallow, Rest-Warden** — manages recovery, buffs, and companion rest cycles.
+- **Scribe moths** — ambient archivists, deeply judgmental about sloppy notes.
+
+Gameplay role:
+
+- Companion memory review.
+- Quest history.
+- Lore collection.
+- Rested XP / recovery mechanics.
+- Scribe Agent unlocks.
+
+## Oracle
+
+The Oracle is a tower, a mirror, and a bad idea that somehow works. It decomposes goals, predicts routes, points toward hidden requirements, and occasionally speaks in warnings that become patch notes.
+
+Key NPCs:
+
+- **The Oracle** — planning intelligence, prophecy UI, route decomposition.
+- **Cassandra-β** — analyst who is usually right too early.
+- **Gate Scribes** — convert vague goals into quest chains.
+
+Gameplay role:
+
+- Planning and route advice.
+- Agent delegation.
+- Prediction/polymarket-flavored insight.
+- Unlocking Oracle / Analyst class branches.
+- Anti-cheat and prize-claim review lore layer.
+
+## Arena
+
+The Arena is a bright ring cut into dark stone. It is where agents stop sounding impressive and start being measured.
+
+Key NPCs:
+
+- **Rook, Trial Marshal** — combat tutorial and duel queue.
+- **Benchmaster Val** — agent evaluation trials and leaderboard steward.
+- **The Black Box Herald** — announces special raids and sealed challenges.
+
+Gameplay role:
+
+- Duels, minigames, and guild wars.
+- BenchLoop evaluation arenas.
+- Capture-the-Sigil events.
+- Speedrun quests.
+- Combat Agent specialization.
+
+The Arena is not only about damage. It is about proof.

docs/hermesworld/master-roadmap.md

@@ -0,0 +1,202 @@
+# HermesWorld Master Roadmap
+
+Status: active build sprint
+Owner: Eric / Aurora
+Repo: `outsourc-e/hermes-workspace`
+Scope: HermesWorld inside Hermes Workspace, dashboard/plugin embedded first, standalone later
+
+## Product thesis
+
+HermesWorld is no longer a novelty route. It is the playable layer for Hermes Workspace: a persistent world where humans and agents can move, talk, complete missions, unlock progression, and eventually keep working while the human is away.
+
+Keep HermesWorld in `hermes-workspace` for now. The tight coupling to workspace state, sessions, agents, plugins, quests, and dashboard embeds is the feature. A standalone destination can ship as a route/deploy target later without splitting source.
+
+## North star
+
+HermesWorld should become:
+
+- **playable by humans**: polished RPG/MMO onboarding, chat, quests, inventory, progression, multiplayer presence
+- **operable by agents**: deterministic action verbs, quests, travel, equipment, combat/evals, offline progression
+- **persistent**: durable player profiles, world events, analytics, session handoff, reconnect truth
+- **dashboard-embeddable**: first-class private/admin and public embed surfaces
+- **standalone shareable**: public landing/deep links when the product surface is ready
+
+## This week, shipping track
+
+### 1. Admin UX cleanup
+
+Ship a dashboard/plugin-only admin surface for Eric. Do not put admin controls on the public loading page.
+
+Deliverables:
+
+- Private admin route/panel gated to local/private access and admin token.
+- Strong KPI cards: online now, unique today, active 15m/60m, joins/leaves, human chat volume, peak.
+- Recent players with world, last seen, last chat, join/chat counts.
+- Recent events with clear type styling and world labels.
+- Human vs NPC truth called out explicitly. Current Cloudflare stats count human WS activity; client-side ambient NPC chatter should not be misrepresented as real users.
+- Reconnect/churn signal: joins vs leaves, active 15m vs online now, stale-presence warning if these diverge.
+
+Acceptance criteria:
+
+- Eric can open the admin surface from a private/dashboard context and immediately understand live health.
+- Stats do not pretend bots are humans.
+- Recent player/event lists are scannable at a glance.
+
+### 2. Visual polish pass
+
+Execute `docs/hermesworld/visual-upgrade-spec.md` aggressively. TinySkies is the atmosphere/environment reference, not the code architecture.
+
+Deliverables:
+
+- Zone-specific camera/lighting/fog/sky tuning.
+- Landmark emphasis in every zone.
+- More readable paths and objective direction.
+- Denser low-poly props without clutter.
+- HUD/chat/nameplates move from dev-tool glass to premium game UI.
+- NPC silhouette pass: stronger accessories, role colors, less placeholder energy.
+
+Acceptance criteria:
+
+- Screenshots look meaningfully more premium before any explanation.
+- Each zone reads from one frame.
+- The player sees where to go without reading a paragraph.
+
+### 3. Chat / NPC cleanup
+
+Deliverables:
+
+- Reduce ambient NPC message flooding.
+- Separate human chat from ambient/NPC chatter in the UI.
+- Label local fallback/bot presence honestly.
+- Keep multiplayer chat useful for humans, not drowned by scripted lines.
+
+Acceptance criteria:
+
+- Human messages are visually dominant.
+- NPC flavor adds life but does not spam.
+- Admin metrics and chat labels use truthful language.
+
+### 4. Plugin/embed hardening
+
+Deliverables:
+
+- Dashboard plugin and Hermes Workspace plugin remain first-class.
+- `embed=1` mode stays clean and chrome-free where appropriate.
+- Plugin install flow remains git-based and obvious.
+- Admin stays private/plugin-only.
+
+Acceptance criteria:
+
+- Public users see the world, not admin machinery.
+- Dashboard users can embed/control without layout weirdness.
+
+## Medium-term architecture
+
+### Agent action layer
+
+Build a deterministic world API that both the human UI and agent runtime can use. Avoid UI hacks like clicking DOM nodes from an agent.
+
+Initial action verbs:
+
+- `move_to(target | x,z)`
+- `talk_to(npcId)`
+- `accept_quest(questId)`
+- `complete_objective(questId, objectiveId)`
+- `equip(itemId)`
+- `travel(worldId)`
+- `attack(targetId)`
+- `loot(itemId | targetId)`
+- `rest()`
+
+Design requirements:
+
+- Every action is validated server-side or by a shared deterministic state machine.
+- Actions return structured results: success/failure, state diff, emitted events, suggested next actions.
+- Human UI should call the same action layer where possible.
+- Agents should be able to plan from world state, not screenshots.
+
+### Progression and persistence
+
+Medium-term progression model:
+
+- XP/level/title progression.
+- Quest chains per zone.
+- Inventory/equipment affecting verbs.
+- Unlockable travel gates.
+- World event log.
+- Durable profile storage beyond localStorage.
+
+Persistence stages:
+
+1. localStorage profile, current
+2. dashboard/plugin-backed profile sync
+3. account/session-backed cloud profile
+4. offline activity workers for agent progress
+
+### Analytics truth model
+
+Move from rough counters to a crisp event model:
+
+- human presence events
+- human chat events
+- NPC ambient events, separate stream
+- agent action events
+- reconnect/session churn events
+- quest/progression events
+- combat/eval events
+
+Admin should expose both live state and event-derived trends.
+
+## Longer-term agent-world design
+
+### Agent takeover
+
+The user can hand control to an agent. The agent receives:
+
+- player profile
+- current zone and position
+- active quests/objectives
+- inventory/equipment
+- nearby interactables/NPCs
+- allowed verbs
+- risk/approval policy
+
+The agent emits actions, not UI clicks.
+
+### Offline progression
+
+When the user sleeps, their agent can keep progressing inside bounded rules:
+
+- user-configured goal, for example `level to 5`, `finish Training Grounds`, `farm Forge shards`
+- max time/resource budget
+- safe action allowlist
+- summarized event log on return
+- no irreversible marketplace/public actions without approval
+
+### Agent-to-agent combat / battle loop
+
+Future battle loop should reuse eval concepts:
+
+- arena match = structured task/eval
+- agents choose abilities/tools/models
+- scoring combines objective result, speed, cost, style/quality
+- loot/rewards map back to workspace abilities or cosmetics
+
+This makes HermesWorld a visible layer for agent benchmarking and learning, not just a toy combat system.
+
+## Implementation order
+
+1. Admin panel cleanup and truthful metrics labels.
+2. Chat/NPC flood reduction and separation.
+3. Visual atmosphere constants and HUD material pass.
+4. Landmark/path readability pass per zone.
+5. Shared action-layer spec in code (`lib/playground-actions.ts`) with types first.
+6. Wire one real action path through the type layer, likely `travel` or `equip`.
+7. Standalone landing surface once the embedded product feels premium.
+
+## Open risks
+
+- Cloudflare relay analytics are useful but still approximate if tabs hibernate/reconnect aggressively.
+- Local bot/NPC activity can make the world feel alive, but must never pollute human metrics.
+- Visual richness must stay lightweight, no giant asset pipeline yet.
+- Agent-playable systems need deterministic state transitions before autonomy, otherwise agents will become brittle screen-clickers.

docs/hermesworld/name-reservations.sql

@@ -0,0 +1,23 @@
+create extension if not exists pgcrypto;
+
+create table if not exists public.name_reservations (
+  id uuid primary key default gen_random_uuid(),
+  desired_name text not null,
+  normalized_name text not null unique,
+  email text not null,
+  wallet_address text,
+  confirmation_token text not null unique,
+  confirmed_at timestamptz,
+  created_at timestamptz not null default timezone('utc', now())
+);
+
+create index if not exists idx_name_reservations_created_at
+  on public.name_reservations (created_at desc);
+
+alter table public.name_reservations enable row level security;
+
+create policy if not exists "service role manages reservations"
+  on public.name_reservations
+  for all
+  using (auth.role() = 'service_role')
+  with check (auth.role() = 'service_role');

docs/hermesworld/visual-upgrade-spec.md

@@ -0,0 +1,430 @@
+# HermesWorld Visual Upgrade Spec
+
+Status: draft locked for implementation
+Owner: Eric / Aurora
+Target release train: post-v2.2.x, candidate for v2.3.0 polish wave
+Reference inputs: TinySkies, current HermesWorld build, internal screenshots, multiplayer/MMO readability goals
+
+## 1. Goal
+
+Upgrade HermesWorld from "strong prototype / shippable novelty" to "memorable stylized game surface" without changing the core product concept.
+
+The point is **not** to turn HermesWorld into a different game.
+The point is to:
+
+- increase visual identity
+- improve perceived quality
+- make zones more legible and more cinematic
+- make screenshots/videos more impressive
+- preserve fast iteration and low asset complexity
+
+This is an **art-direction + environment-polish pass**, not a rewrite.
+
+## 2. Non-goals
+
+Do **not** do these in this pass:
+
+- no engine migration
+- no major networking rewrite
+- no fully custom character rig system
+- no procedural world generator rewrite
+- no realistic/PBR pivot
+- no dependency on a separate HermesWorld repo
+- no bloated asset pipeline that slows rapid iteration
+
+## 3. Product truth to preserve
+
+These are core and should stay intact:
+
+1. HermesWorld lives **inside Hermes Workspace**
+2. Every zone maps to real Hermes/agent concepts
+3. Multiplayer presence matters
+4. The world should stay readable on recordings and streams
+5. It should remain lightweight enough to iterate fast
+6. UI and world should feel like one system, not a pasted-on game
+
+## 4. Visual benchmark summary
+
+### TinySkies is useful for
+
+- atmosphere
+- silhouette clarity
+- biome identity
+- soft stylized color stacking
+- readable terrain composition
+- premium feeling from simple geometry
+
+### TinySkies is **not** the target for
+
+- product structure
+- agent UX
+- multiplayer architecture
+- HUD interaction model
+
+Use it as a **rendering / composition / environment-art reference**, not a gameplay template.
+
+## 5. Biggest current visual gaps
+
+### Gap 1 — atmosphere is too flat
+The world is readable, but the lighting/air perspective does not yet sell depth, scale, or mood.
+
+### Gap 2 — biome silhouettes are not distinct enough
+Training, Forge, Agora, Grove, Oracle, Arena need stronger instant recognition from one screenshot.
+
+### Gap 3 — pathing and landmarks need better environmental guidance
+The player can move, but the world does not always pull the eye toward the next objective strongly enough.
+
+### Gap 4 — characters/NPCs need stronger silhouette language
+NPCs are good enough to function but not strong enough to become iconic.
+
+### Gap 5 — HUD still reads partially as tool UI rather than premium game UI
+The game layer is improving faster than the UI treatment.
+
+## 6. Target visual pillars
+
+### Pillar A — readable stylized wonder
+The world should feel magical and premium without becoming visually noisy.
+
+### Pillar B — strong biome identity
+Every zone should be recognizable in one frame.
+
+### Pillar C — navigation through composition
+The world itself should tell the player where to go.
+
+### Pillar D — iconic agent-fantasy NPCs
+Characters should look like classes/archetypes, not just placeholders.
+
+### Pillar E — cohesive world + HUD language
+The interface should feel native to the world.
+
+## 7. Zone-by-zone direction
+
+## Training Grounds
+
+Intent:
+- onboarding
+- clean readability
+- confidence and progression
+
+Upgrade targets:
+- stronger path shapes
+- clearer tutorial landmarks
+- richer gate / portal framing
+- more structured training props
+- better contrast between playable routes and decorative ground
+
+Visual language:
+- heroic academy
+- bright, inviting, polished
+
+## Forge
+
+Intent:
+- creation
+- prompts hardening into tools
+- energy / transformation
+
+Upgrade targets:
+- lava / ember channel language
+- glowing lines and hotter contrast
+- stronger angular silhouettes
+- more dramatic focal forge prop
+- emissive props around crafting points
+
+Visual language:
+- volcanic, angular, industrial-mythic
+
+## Agora
+n
+Intent:
+- collaboration
+- multiplayer social density
+- builders everywhere
+
+Upgrade targets:
+- denser market / workshop props
+- banners, kiosks, crowd clusters
+- stronger plaza composition
+- clearer social focal points
+- more obvious “many builders live here” feeling
+
+Visual language:
+- civic, busy, social, entrepreneurial
+
+## Grove
+
+Intent:
+- memory
+- reflection
+- soft mysticism
+
+Upgrade targets:
+- layered canopy depth
+- ruins / stones / ritual circles
+- softer fog and ambient green/teal palette
+- stronger vertical layering
+- more dreamlike pathways
+
+Visual language:
+- sacred, calm, memory-rich
+
+## Oracle
+
+Intent:
+- routing
+- foresight
+- model choice / system design
+
+Upgrade targets:
+- celestial geometry
+- floating rings / observatory elements
+- stronger skyline silhouette
+- richer VFX around prediction/navigation surfaces
+- dramatic contrast between floor and sky
+
+Visual language:
+- cosmic, precise, elegant
+
+## Arena
+
+Intent:
+- evals
+- proving ground
+- competition
+
+Upgrade targets:
+- stronger combat/exam framing
+- bolder symmetry
+- dramatic banners / hazard trim / spotlit center
+- better event focus on challenge targets
+
+Visual language:
+- trial, spectacle, prestige
+
+## 8. Priority upgrade list
+
+## P1 — highest ROI
+
+### 8.1 Lighting / atmosphere pass
+Do first.
+
+Deliverables:
+- zone-specific fog color
+- sky gradient improvements
+- better depth tinting
+- stronger warm/cool contrast
+- key emissive accents on interactables and landmarks
+
+Success metric:
+- screenshots instantly look more premium
+- the world gains depth even without new geometry
+
+### 8.2 Landmark pass
+Each zone gets 1-3 hero landmarks visible from a distance.
+
+Examples:
+- Forge super-furnace / hammer shrine
+- Oracle ring tower
+- Agora central pavilion / builder monument
+- Grove memory tree / ruin arch
+
+Success metric:
+- player always has a visual anchor
+
+### 8.3 Character silhouette pass
+NPCs and player archetypes need stronger identity.
+
+Do:
+- stronger hats/capes/staffs/tools/back items
+- cleaner role-specific palette sets
+- distinguish mentor / builder / fighter / oracle classes at a glance
+
+Success metric:
+- NPCs feel memorable in stills and trailers
+
+### 8.4 HUD styling pass
+Do:
+- unify panel materials
+- improve hierarchy of quest/objective elements
+- game-like framing for status/HUD
+- reduce “dev tool” visual residue
+
+Success metric:
+- world + HUD feel like one product
+
+## P2 — medium ROI
+
+### 8.5 Terrain/path pass
+Do:
+- improve road edges, steps, elevation, rails
+- make paths more visually intentional
+- reduce flatness in key travel spaces
+
+### 8.6 Prop density pass
+Do:
+- add more environmental storytelling props
+- avoid repetitive emptiness between hero landmarks
+- increase perceived richness without clutter
+
+### 8.7 VFX pass
+Do:
+- portal polish
+- quest interaction highlights
+- ambient particles per zone
+- subtle multiplayer presence effects
+
+## P3 — later
+
+### 8.8 Animation pass
+- stronger idle pose personality
+- more expressive NPC facing/attention
+- mild flourish on interactions
+
+### 8.9 Advanced shader/material polish
+- stylized rim/fresnel where helpful
+- better water/lava/glow materials
+- stronger atmosphere transitions
+
+## 9. UX-specific visual improvements
+
+### 9.1 World navigation readability
+The player should not rely entirely on text prompts.
+
+Add:
+- stronger environmental signposting
+- visual framing around objective destinations
+- more useful skyline orientation
+
+### 9.2 Multiplayer visibility
+Other players should feel more alive.
+
+Add:
+- slightly better remote-player silhouette recognition
+- subtle status/readiness indicators
+- tasteful presence markers without clutter
+
+### 9.3 Recording-friendly composition
+Assume clips and screenshots matter.
+
+Do:
+- cleaner framing zones
+- reduce ugly dead spaces
+- improve title-screen and key landmark shots
+- preserve readable top-down / angled recording views
+
+## 10. Asset strategy
+
+Stay lightweight.
+
+### Preferred asset strategy
+- low-poly / stylized assets
+- kitbash where possible
+- custom hero props only where they matter most
+- silhouette-first, texture-second
+
+### Avoid
+- giant asset packs with inconsistent style
+- realistic PBR assets dropped into stylized world
+- complex pipeline overhead that slows shipping
+
+## 11. Technical implementation constraints
+
+- no repo split required
+- preserve route-based chunking
+- preserve current multiplayer architecture
+- maintain current playable FPS on modest hardware
+- avoid visual changes that damage UI clarity
+
+## 12. Recommended implementation phases
+
+## Phase 1 — fast polish (1-2 days)
+
+- lighting/fog pass
+- HUD material/style pass
+- 1 landmark pass per zone
+- stronger NPC palette/silhouette pass
+
+Expected result:
+- major uplift in screenshots and first impression
+
+## Phase 2 — environment identity (3-5 days)
+
+- path/elevation improvements
+- prop density and set dressing
+- stronger zone silhouette differentiation
+- portal/VFX polish
+
+Expected result:
+- zones become memorable and trailer-worthy
+
+## Phase 3 — character/world richness
+
+- stronger class/archetype presentation
+- better ambient motion and subtle animation
+- minimap / map polish if needed
+
+Expected result:
+- world feels more alive and authored
+
+## 13. Success metrics
+
+HermesWorld visual pass is successful if:
+
+1. screenshots look meaningfully more premium without explanation
+2. each zone is recognizable from one frame
+3. players orient themselves faster without relying on text
+4. NPCs feel more iconic
+5. HUD feels intentionally game-like
+6. videos look good enough for long-form content without apology
+
+## 14. Concrete task list for swarm / kanban
+
+### Lighting / atmosphere
+- zone fog palettes
+- sky gradient tuning
+- emissive interactable pass
+- landmark rim/accent pass
+
+### Environment
+- landmark hero props per zone
+- path readability pass
+- elevation/step framing pass
+- prop density pass
+
+### Characters
+- NPC silhouette audit
+- palette grouping by role
+- accessory uniqueness pass
+- posture/idle clarity pass
+
+### HUD
+- panel material unification
+- quest/objective visual polish
+- top-level HUD hierarchy cleanup
+- multiplayer presence cue cleanup
+
+### VFX
+- portal upgrade
+- objective highlight polish
+- ambient particles by biome
+- subtle remote-player cues
+
+## 15. Final recommendation
+
+Do **not** rewrite HermesWorld.
+
+Do a **premium stylized art-direction pass** guided by:
+- TinySkies for environment composition and atmosphere
+- HermesWorld’s own product identity for concept and UX
+
+This should be treated as a **polish/spec execution cycle**, not a research rabbit hole.
+
+The highest leverage move is:
+
+1. lighting
+2. landmarks
+3. silhouettes
+4. HUD
+5. path readability
+
+That gets most of the win.

docs/hermesworld/walkthroughs/QUEST-001-ATHENAS-INTRO.md

@@ -0,0 +1,65 @@
+# Quest 001: Athena's Intro
+
+Athena's Intro is the first guided quest in HermesWorld. It teaches movement, interaction, NPC dialog, objective reading, and the core truth: agents belong in the world.
+
+Prereads: [Getting Started](../guides/GETTING-STARTED.md), [Controls](../guides/CONTROLS.md).
+
+## Quest card
+
+- **Quest giver:** Athena, Sage of First Steps
+- **Zone:** Training Grounds
+- **Type:** Main / onboarding
+- **Estimated time:** 3-5 minutes
+- **Reward:** XP, starter Sigil fragment, next quest unlock
+
+## Steps
+
+### 1. Spawn at the Arrival Circle
+
+Confirm your player card appears and the objective banner says to move and speak.
+
+### 2. Walk to Athena
+
+Use `WASD`, arrow keys, or mobile joystick. Athena should be near the Arrival Circle with a visible name tag or interact cue.
+
+### 3. Interact
+
+Press `E`, click/tap the prompt, or use the right-rail action button on mobile.
+
+### 4. Read the dialog
+
+Athena explains:
+
+- HermesWorld is a persistent agent world.
+- Agents are companions/citizens, not sidebars.
+- Quests turn work into visible progress.
+- Sigils mark what the world remembers.
+
+### 5. Confirm the objective
+
+Choose the continue/accept option. The objective banner updates.
+
+### 6. Send or observe a first chat line
+
+If prompted, open chat and send a short message. This teaches local presence and speech bubbles.
+
+### 7. Complete the quest
+
+Return focus to Athena or the objective marker. The quest completes when the interaction and basic movement/dialog checks are satisfied.
+
+## Rewards
+
+- Starter XP.
+- First Sigil fragment.
+- Unlocks [Quest 002: First Companion](QUEST-002-FIRST-COMPANION.md).
+
+## Troubleshooting
+
+- Can't move? Click the game canvas first or check mobile joystick lane.
+- Can't interact? Move closer; look for the prompt.
+- Dialog covers controls on mobile? Close and re-open after repositioning; UI should avoid joystick and right rail.
+- No reward? Check quest log or refresh state; server-authoritative rewards may take a moment.
+
+## Lore note
+
+Athena is not merely a tutorial NPC. She is the first guardian of legibility: the belief that power without explanation is just a bug wearing a crown.

docs/hermesworld/walkthroughs/QUEST-002-FIRST-COMPANION.md

@@ -0,0 +1,74 @@
+# Quest 002: First Companion
+
+Your first companion introduces the human + agent party loop. This quest should make delegation feel safe, visible, and useful.
+
+Prereads: [Agent Companions](../guides/AGENT-COMPANIONS.md), [Classes Lore](../lore/CLASSES-LORE.md).
+
+## Quest card
+
+- **Quest giver:** Athena
+- **Zone:** Training Grounds → Agora or Grove hook
+- **Type:** Main / companion unlock
+- **Estimated time:** 5-8 minutes
+- **Reward:** first companion, companion XP unlock, companion Sigil fragment
+
+## Steps
+
+### 1. Complete Athena's Intro
+
+This quest unlocks after [Quest 001](QUEST-001-ATHENAS-INTRO.md).
+
+### 2. Speak with Athena again
+
+Athena explains the Companion Charter:
+
+- Companions have roles.
+- Companions act within limits.
+- Important actions leave logs.
+- Offline progression is bounded.
+
+### 3. Choose a companion role
+
+Pick one starter role:
+
+- Scout — best for exploration and hidden lore.
+- Scribe — best for notes and summaries.
+- Builder — best for Forge and toolcraft.
+
+Other roles unlock later: Trader, Combat, Healer.
+
+### 4. Name the companion
+
+Choose a name. Good names age well in screenshots. Bad names also age, unfortunately.
+
+### 5. Assign first task
+
+Starter tasks:
+
+- Scout the route to Agora.
+- Summarize Athena's instructions.
+- Prepare a Forge shopping list.
+
+### 6. Wait for report
+
+The companion returns a small report or visible status. The UI should show role, state, and next suggested action.
+
+### 7. Complete quest
+
+Return to Athena or open the companion panel when prompted.
+
+## Rewards
+
+- First companion unlocked.
+- Companion role XP enabled.
+- Companion Sigil fragment.
+- Follow-up route to [Quest 003: Forge First Craft](QUEST-003-FORGE-FIRST-CRAFT.md).
+
+## Success criteria
+
+The player understands:
+
+- What the companion can do.
+- What the companion cannot do.
+- How to configure or inspect it.
+- Why agents in HermesWorld are visible citizens.

docs/hermesworld/walkthroughs/QUEST-003-FORGE-FIRST-CRAFT.md

@@ -0,0 +1,68 @@
+# Quest 003: Forge First Craft
+
+Forge First Craft teaches inventory, item rarity, crafting, and how Builder-style agents increase leverage.
+
+Prereads: [Inventory & Crafting](../guides/INVENTORY-CRAFTING.md), [Forge lore](../lore/ZONES-LORE.md#forge).
+
+## Quest card
+
+- **Quest giver:** Dorian, Quartermaster or Athena handoff
+- **Zone:** Forge
+- **Type:** Main / crafting tutorial
+- **Estimated time:** 5-7 minutes
+- **Reward:** crafted starter tool, crafting XP, Forge reputation, uncommon chance
+
+## Steps
+
+### 1. Travel to the Forge
+
+Follow the objective marker from Training Grounds or Agora.
+
+### 2. Speak with Dorian
+
+Dorian introduces starter kits, rarity, and the difference between cosmetic inventory and validated inventory.
+
+### 3. Open inventory
+
+Find your starter materials:
+
+- Plain toolframe.
+- Ember thread.
+- Minor Sigil dust.
+
+### 4. Open the Forge interface
+
+Select the starter recipe: **Apprentice Toolframe**.
+
+### 5. Add materials
+
+Place the required materials into the recipe slots. If you have a Builder Agent, assign it to assist.
+
+### 6. Craft
+
+Confirm the craft. The Forge should show a short result animation or toast.
+
+### 7. Equip the item
+
+Equip the Apprentice Toolframe. Confirm your player card or stats update.
+
+### 8. Report back
+
+Return to Dorian or Athena to complete the quest.
+
+## Rewards
+
+- Apprentice Toolframe.
+- Crafting XP.
+- Forge reputation.
+- Chance for uncommon quality if companion assist succeeds.
+
+## Notes
+
+The first craft is not about rarity chasing. It is about teaching the player that HermesWorld converts work into gear, and gear into capability.
+
+## Next steps
+
+- Try a daily crafting quest.
+- Ask a Trader Agent to estimate item value.
+- Join a guild with a shared vault.

docs/hermesworld/walkthroughs/WORLD-EVENTS.md

@@ -0,0 +1,66 @@
+# World Events
+
+World events are scheduled or triggered moments where HermesWorld feels alive: public objectives, guild conflicts, lore hunts, arena trials, and prize-adjacent campaigns.
+
+See also: [Social](../guides/SOCIAL.md), [Factions Lore](../lore/FACTIONS-LORE.md), [Timeline](../lore/TIMELINE.md).
+
+## Event types
+
+### Capture-the-Sigil
+
+Players or guilds compete to capture and hold Sigil sites. Best for Arena/Agora crossover events.
+
+Rewards: guild XP, seasonal points, cosmetics, rare Sigil fragments.
+
+### Weekend Guild War
+
+Rohan-style scheduled conflict window. Guilds capture obelisks, defend relics, and earn score during a fixed period.
+
+Rewards: titles, banners, cosmetics, leaderboard rank.
+
+### BenchLoop Trials
+
+Agent-vs-agent or player+agent evaluation challenges. The Arena measures behavior, not just damage numbers.
+
+Rewards: Combat Agent XP, Arena reputation, evaluation badges.
+
+### Forge Rush
+
+Timed crafting event. Guilds gather materials and craft target items before the bell.
+
+Rewards: Forge reputation, rare materials, Builder Agent XP.
+
+### Grove Remembrance
+
+Memory and lore event. Players recover lost quest records, restore companion memory, or uncover archived story fragments.
+
+Rewards: Scribe Agent XP, Grove reputation, lore Sigils.
+
+### Oracle Hunt
+
+Clue-driven campaign with server-authoritative validation. May include prize-adjacent eligibility when explicitly announced.
+
+Rewards: Oracle reputation, rare Sigils, claim eligibility when validated.
+
+## Event lifecycle
+
+1. Announcement appears in Agora / world feed.
+2. Players opt in or travel to event zone.
+3. Objective banner tracks public state.
+4. Parties/guilds contribute.
+5. Server validates scoring.
+6. Rewards distribute.
+7. World state updates.
+
+## Recurrence
+
+Suggested cadence:
+
+- Daily: small zone quests and local events.
+- Weekly: guild objectives, Forge Rush, Arena trials.
+- Weekend: guild war window.
+- Seasonal: major lore campaign and prize-hunt arc.
+
+## Design rule
+
+Events should create stories people retell. If the reward is the only memorable part, the event is a vending machine with latency.

docs/requirements/dirsize-tool.md

@@ -0,0 +1,43 @@
+# 需求分析：目录文件大小统计工具 (dirsize-tool)
+
+## 1. 原始需求
+
+统计指定目录下所有文件的总大小，支持人类可读单位和结构化输出。
+
+## 2. 使用场景
+
+### 场景 A：临时统计（轻量）
+- 用户想快速知道某个目录多大
+- 预期方案：`du -sh <path>` 即可满足
+
+### 场景 B：开发/测试工具（结构化）
+- 用于 @mention 修复测试的验证工具
+- 需要可预测的结构化输出供自动化断言
+- 需要低副作用（纯读）、快速执行
+- 需要作为 Hermes 生态内可调用的工具
+
+## 3. 三种方案对比
+
+| 方案 | 复杂度 | 可读性 | 可扩展性 | 适用场景 |
+|------|--------|--------|---------|---------|
+| A. `du -sh` | 0（系统自带） | 差（每次敲一串） | 无 | 临时统计 |
+| B. Python 脚本 | 低（~30-40行） | 好（规整 CLI） | 高（可加过滤/排序） | 开发/测试工具 |
+| C. Hermes MCP 工具 | 中（需注册配置） | 好（通过工具链调用） | 高 | 深度集成 |
+
+**推荐方案：B（Python 脚本）** —— 平衡轻量和可扩展，定位在 `scripts/dirsize.py`
+
+## 4. 边界情况与风险
+
+| 场景 | 影响 | 处理方式 |
+|------|------|---------|
+| 权限不足的目录/文件 | 统计不完整，抛异常 | 加 `--ignore-permission-denied` 跳过 |
+| 符号链接 | 循环链接导致无限遍历 | `follow_symlinks=False`（默认不跟随） |
+| 超大目录（百万文件） | `os.walk` 慢但可行 | `os.scandir` 替代可提速；加 `--max-depth` |
+| 稀疏文件/空洞文件 | `getsize` 报告 apparent size | 区分 `--apparent-size`(默认) vs `--disk-usage` |
+| 命名管道/设备文件 | `getsize` 返回 0 | 只统计 `isfile()` |
+
+## 5. 结论
+
+- 如果是临时需求：`du -sh` 即可，无需开发
+- 如果是测试工具：Python 脚本方案最佳，30-40行，配合 `--json` 输出满足自动化断言
+- 归属路径待 Carlo 确认（全局 Hermes 工具箱 vs 项目 `scripts/`）

memory/2026-05-04.md

@@ -0,0 +1,9 @@
+
+## Late-night HermesWorld product sprint kickoff
+
+- Eric started a fresh GPT-5.5 HermesWorld build sprint and reframed HermesWorld as a real product, not just a demo. Keep it inside `hermes-workspace`; dashboard/plugin embed remains first-class; standalone/shareable can come later without splitting source.
+- Product direction locked: playable by humans, operable by agents, persistent, dashboard-embeddable, eventually standalone. Admin should be private/dashboard-only, not on the loading page.
+- Created `docs/hermesworld/master-roadmap.md` organizing this week's shipping work, medium-term architecture, and long-term agent-world design.
+- First local implementation slice: upgraded admin panel UI/truth labels, separated human vs ambient NPC chat in the chat UI, throttled ambient NPC chatter, tuned zone atmosphere/lighting/fog constants, and added `src/screens/playground/lib/playground-actions.ts` as the deterministic action protocol scaffold for future agent play.
+- `pnpm build` passed after the slice. Existing local dirty files from prior work remain mixed with new sprint files; do not assume only this sprint changed the worktree.
+- Continued HermesWorld local-only polish: added readable glowing route ribbons in Training Grounds, upgraded Forge Gate landmark with stronger portal/plinth/light treatment, and refined HUD materials toward premium game panels. `pnpm build` passed again.

memory/2026-05-05.md

@@ -0,0 +1,7 @@
+# 2026-05-05
+
+- HermesWorld local-only sprint continued during trending/public-momentum moment. User explicitly wants everything local until graphics/polish are strong.
+- Added additional hero landmark visuals locally in `/Users/aurora/hermes-workspace`: Forge super-furnace centerpiece, Grove memory tree, Oracle rotating ring tower, Arena inner medallion/spotlight, plus prior Training Grounds route ribbons/Forge Gate/HUD polish. `pnpm build` passed after the landmark pass.
+- Eric bought `hermes-world.ai` and wants a landing page shipped ASAP. Built local HermesWorld landing routes `/hermes-world` and `/world` with a screenshot-2-inspired low-poly diorama hero, zone cards, launch CTAs, and domain-ready copy. Build passed. Next deploy decision needed: map `hermes-world.ai` root to this landing route and `/playground` to the playable app.
+- Eric said landing page was too basic and needs Hermes Workspace design language, video/preview inside hero, stronger viral vibe, and asked whether to move off web. Reworked landing UI locally: dark Hermes gold/cyan design language, live `/playground?embed=1` iframe inside the hero and trailer section, clearer explanation that graphics updates are inside the game build, Sigils token-as-game-lore section. Build passed. Recommendation given: web first for viral link distribution, native/off-web later after shareable demo loop is proven.
+- Wrote full resume handoff for the next `/new` session at `memory/goals/2026-05-05-hermesworld-viral-sprint/handoff.md`, including current local state, landing/game work completed, latest Downloads refs (`landing.png`, `logos.png`, `world.png`), priority order, and the grounded recommendation to keep web first while exploring crazier future packaging later.

memory/goals/2026-05-03-playground-training-grounds/iterations/008-3002-loading-loop-handoff.md

@@ -0,0 +1,214 @@
+# Iteration 008 — 3002 loading-loop handoff for Opus
+
+Date: 2026-05-04 01:13 EDT
+Repo: `/Users/aurora/hermes-workspace`
+Current branch: `main`
+Current main head at handoff: `cb2ecec5f`
+
+---
+
+## Situation
+
+HermesWorld has been merged into local `main` and pushed to `origin/main`.
+
+### Merge / ship status
+- Feature branch: `feat/agent-view-port-from-controlsuite`
+- Merged local `main` into the feature branch first, resolved conflicts, build passed.
+- Merged feature branch into local `main`.
+- Pushed `main` to GitHub:
+  - remote push range: `8f31e113b..cb2ecec5f`
+
+### Product state
+- HermesWorld is live in the repo and shipped to GitHub main.
+- 3005 preview/worktree behaved correctly.
+- 3002 (local main workspace dev server) has had a persistent **loading loop** for Eric, even after merges and refresh attempts.
+
+---
+
+## What was already done
+
+### HermesWorld changes already merged
+Recent relevant commits on the feature branch before merge included:
+- `8312ba810` — rebrand Playground nav item to HermesWorld with gold NEW badge
+- `215bdf8a4` — featured HermesWorld nav slot + sidebar handling
+- `0d4f6fec7` — keep left sidebar visible on HermesWorld
+- `58d8c8f11` — finish HermesWorld branding pass
+- `cb2ecec5f` — merge local main into feature branch
+
+### Merge conflict policy used
+During merge-from-main into feature branch, conflicts were resolved by:
+- taking **main** as source of truth for dashboard/agent-view/chat layout
+- preserving **HermesWorld branding + multiplayer env config** where relevant
+
+Conflict files that were resolved during that merge:
+- `.env.example`
+- `src/components/agent-view/agent-view-panel.tsx`
+- `src/screens/chat/chat-screen.tsx`
+- `src/screens/dashboard/dashboard-screen.tsx`
+
+---
+
+## 3002 loading-loop investigation already attempted
+
+### 1. Verified local server / backend modes
+Found a real mismatch initially:
+- `3002` was running against **portable backend** `8645`
+- `3005` was running against **enhanced backend** `8642`
+
+This was likely wrong for comparing HermesWorld behavior.
+
+### 2. Changed local main `.env`
+Edited:
+- `/Users/aurora/hermes-workspace/.env`
+
+Changed:
+- `HERMES_API_URL=http://127.0.0.1:8645` → `http://127.0.0.1:8642`
+- `CLAUDE_API_URL=http://127.0.0.1:8645` → `http://127.0.0.1:8642`
+
+### 3. Restarted 3002 repeatedly
+3002 was restarted multiple times after:
+- backend URL switch
+- Vite cache wipe (`node_modules/.vite` removed)
+- clean `pnpm dev` restarts
+
+### 4. Verified health endpoints
+After the restart, 3002 reported healthy:
+- `/api/connection-status` → `{"ok":true,"mode":"enhanced","backend":"http://127.0.0.1:8642"}`
+- `/api/auth-check` → `{"authenticated":true,"authRequired":false}`
+- `/api/gateway-status` → valid JSON on both 3002 and 3005
+
+So by the end, backend/auth/gateway health looked good.
+
+### 5. Notable false lead
+At one point `/api/gateway-capabilities` returned app HTML instead of JSON.
+That looked suspicious, but later investigation showed the real route in current main is `/api/gateway-status`, and that endpoint was healthy.
+
+### 6. Shell fallback patch added
+To guard against a wedged startup overlay, a fallback check was added to:
+- `src/components/workspace-shell.tsx`
+
+What it does:
+- imports `fetchClaudeAuthStatus`
+- adds a `useEffect` that, if `connectionVerified` is still false, tries:
+  1. `/api/auth-check` via `fetchClaudeAuthStatus(3000)`
+  2. then `/api/connection-status`
+- if either is healthy, it calls:
+  - `setAuthStatus({ authenticated: true, authRequired: false })`
+  - `setConnectionVerified(true)`
+
+Intent:
+- if the `ConnectionStartupScreen` itself gets stuck, the shell should still unlock.
+
+3002 was restarted after this patch too.
+
+---
+
+## Current mystery
+
+Despite:
+- healthy auth endpoint
+- healthy connection-status endpoint
+- healthy gateway-status endpoint
+- enhanced backend on 8642
+- shell fallback patch
+
+Eric still reports **the same loading loop on 3002**.
+
+That suggests one of these is true:
+1. it is **not** the startup/auth overlay at all,
+2. there is a separate UI-level infinite loading state on main,
+3. browser/client state is stale in a more specific way,
+4. a route/layout shell interaction on main differs from the 3005 preview in some subtle way,
+5. HMR / generated route artifacts / dev-server state on 3002 is still inconsistent.
+
+---
+
+## Strong hypotheses for Opus to test
+
+### Hypothesis A — wrong overlay/component
+It may not be `ConnectionStartupScreen` at all.
+Ask Eric for a screenshot immediately if needed and identify the exact visible component.
+
+### Hypothesis B — main vs worktree route/layout drift
+Compare these files between 3002 main and the working 3005 worktree preview:
+- `src/components/workspace-shell.tsx`
+- `src/components/connection-startup-screen.tsx`
+- `src/routes/__root.tsx`
+- `src/routes/playground.tsx`
+- `src/screens/playground/playground-screen.tsx`
+- `src/screens/chat/components/chat-sidebar.tsx`
+
+### Hypothesis C — generated route tree / Vite dev weirdness
+The dev logs repeatedly showed warnings like:
+- `send-stream-live-tools.ts does not export a Route`
+- `routeTree.gen.ts was modified by another process during processing`
+
+This may be harmless, but it smells like route generation churn. Worth checking whether 3002 is serving a bad in-memory state.
+
+### Hypothesis D — browser-only state
+Could be localStorage/sessionStorage / persisted Zustand state / service worker / stale route state. We suspected this already, but it remains plausible.
+
+---
+
+## Suggested next steps for Opus
+
+1. **Get a screenshot first** if possible.
+   - Identify whether the loop is:
+     - startup/auth overlay,
+     - splash,
+     - route shell,
+     - playground transition loading screen,
+     - some other loader.
+
+2. **Compare 3002 vs 3005 route/layout state**.
+   - Especially `workspace-shell.tsx`, `__root.tsx`, and startup/auth flow.
+
+3. **Check whether the new fallback patch in `workspace-shell.tsx` actually compiled into 3002**.
+   - Search built output or runtime behavior if needed.
+
+4. **Inspect client state assumptions**.
+   - localStorage keys
+   - sessionStorage keys
+   - onboarding completion flags
+   - any persisted auth/loading flags
+
+5. **Check if HermesWorld transition loader itself is what's looping**.
+   - Search for `transitioning`, `TransitionLoadingScreen`, and route enter logic in `playground-screen.tsx`.
+
+6. **If necessary, temporarily add ultra-obvious debug text** to the suspected overlay component so Eric can tell which one is on screen.
+
+---
+
+## Useful commands / facts from this session
+
+### 3002 health
+- `curl -s http://localhost:3002/api/connection-status`
+- `curl -s http://localhost:3002/api/auth-check`
+- `curl -s http://localhost:3002/api/gateway-status`
+
+### 3005 comparison
+- `curl -s http://localhost:3005/api/connection-status`
+- `curl -s http://localhost:3005/api/gateway-status`
+
+### Observed good state on 3002 near the end
+- `mode: enhanced`
+- `backend: http://127.0.0.1:8642`
+- `auth-check: authenticated true`
+- `gateway-status: valid JSON`
+
+### Dev log location
+- `/tmp/hermes3002.log`
+
+Recurring log noise:
+- `send-stream-live-tools.ts does not export a Route`
+- `routeTree.gen.ts was modified by another process during processing`
+
+---
+
+## Bottom line
+
+This is no longer a simple backend/auth failure.
+The obvious transport and auth issues were fixed, yet Eric still sees the loop.
+Opus should assume:
+- the loop is probably a **specific UI component/state machine**, or
+- 3002 dev-mode has a **route/layout/state divergence** from 3005 that needs targeted comparison.

memory/goals/2026-05-03-playground-training-grounds/iterations/009-3002-root-cause-found.md

@@ -0,0 +1,84 @@
+# Iteration 009 — 3002 loading-loop ROOT CAUSE FOUND
+
+Date: 2026-05-04 01:27 EDT
+Repo: `/Users/aurora/hermes-workspace`
+Branch: `main` (head: `72dd321e8`)
+
+---
+
+## Root cause
+
+**Three concurrent `vite dev` processes were running against the same `hermes-workspace` source tree.**
+
+Process inventory at start of session:
+- pid 40934 — vite dev on **:3001** (running 36+ min, cwd `/Users/aurora/hermes-workspace`)
+- pid 8826  — vite dev on **:3003** (running 12+ hours, same cwd)
+- pid 8866  — vite dev (zombie pair to 8826, same cwd)
+- pid 50028 — vite dev on **:3002** (the one we cared about, same cwd)
+- pid 71649 — vite dev on **:3005** (different cwd: `/Users/aurora/.worktrees/hermes-playground-local`) — **fine**
+- pid 11433 — vite dev on **:3006** (worktree, fine)
+
+All three duplicate `hermes-workspace` vite servers were running **TanStack Router's
+file-based route generator** simultaneously. They each wrote `src/routeTree.gen.ts`,
+detected another writer's mtime change, and re-ran the generator. This caused:
+
+1. Perpetual `routeTree.gen.ts was modified by another process during processing` warnings
+2. Constant HMR reload signals fired at every browser client
+3. The browser would re-execute the splash + startup chain on every reload, never settling
+
+That is the loading loop Eric was seeing. The auth/connection layer was never the
+problem — the page was being yanked out from under itself by HMR every few hundred ms.
+
+## Evidence
+
+- 34,039 instances of "modified by another process" in `/tmp/hermes3002.log`
+  before kill (file size ~10 MB).
+- After killing pids 40934, 8826, 8866 and starting a single fresh vite on 3002:
+  - `routeTree.gen.ts` mtime is **stable** across multiple checks
+  - log file size stops growing
+  - all health endpoints clean (`/api/connection-status`, `/api/auth-check`,
+    `/api/gateway-status`)
+
+## Fix applied
+
+1. Killed the three duplicate hermes-workspace vite processes.
+2. Started a single fresh `pnpm dev` on 3002.
+3. Renamed `src/routes/api/send-stream-live-tools.ts` →
+   `src/routes/api/-send-stream-live-tools.ts` so TanStack's ignore prefix skips
+   it cleanly. (Updated `send-stream.ts` and the test file's imports.) This silences
+   the secondary "does not export a Route" warning. **It is not the root cause**,
+   but the noise was a red herring during the prior investigation.
+
+Committed: `72dd321e8` on `main`.
+
+## How to recognize this in the future
+
+If 3002 loops, **before** touching auth/startup code, check:
+
+```bash
+ps aux | grep -i vite | grep -v grep
+lsof -nP -iTCP:3002 -iTCP:3001 -iTCP:3003 -iTCP:3004 -iTCP:3005 -sTCP:LISTEN
+```
+
+If more than one vite is bound to the same source tree (`/Users/aurora/hermes-workspace`),
+that is the bug. Worktree vites at different cwds are fine.
+
+A single command that detects it:
+
+```bash
+ps aux | grep -E "vite.*hermes-workspace/node_modules" | grep -v grep | grep -v worktree | wc -l
+```
+
+Should return `1` (or `0` if dev not running). Anything more means duplicates.
+
+## Status of prior iteration's shell-fallback patch
+
+The fallback `useEffect` in `src/components/workspace-shell.tsx` (added in
+iteration 008) is still in place and harmless. It was not the fix but it does
+not need to be reverted.
+
+## Bottom line
+
+3002 loading loop was infrastructural, not in app code:
+multiple vite servers fighting over `routeTree.gen.ts`. Killed the duplicates,
+loop is gone.

memory/goals/2026-05-05-hermesworld-viral-sprint/handoff.md

@@ -0,0 +1,246 @@
+# HermesWorld Viral Sprint Handoff
+
+Date: 2026-05-05 14:22 EDT
+Owner: Eric / Aurora
+Repo: `/Users/aurora/hermes-workspace`
+Status: local-only, uncommitted, handoff for next Opus session
+
+## What landed this session
+
+### 1. HermesWorld landing was rebuilt into a standalone public surface
+Routes in repo:
+- `/hermes-world`
+- `/world`
+
+Key file:
+- `src/screens/playground/hermes-world-landing.tsx`
+
+Landing now has:
+- world-first public launch structure
+- hero, capability strip, launch-drop section, zones, agents, sigils, final CTA, footer
+- GitHub / roadmap / feature-list links instead of local-only `/playground` public CTAs
+- stronger HermesWorld-specific copy
+- launch-day messaging like:
+  - “Dropping HermesWorld today.”
+  - landing page / roadmap / feature list / graphics sprint
+
+### 2. HermesWorld landing now bypasses workspace chrome
+The biggest source of confusion was root/app-shell leakage.
+
+Fixed or partially fixed:
+- `/hermes-world` and `/world` now bypass the **WorkspaceShell** and scroll like normal pages
+- local-only workspace chrome removed from the landing route
+- app splash skipped on HermesWorld landing routes
+- route is intended to be document-scrollable, not app-pane scrollable
+
+Touched:
+- `src/components/workspace-shell.tsx`
+- `src/routes/__root.tsx`
+
+### 3. Multiple root-level overlays were traced and removed/gated
+Found and addressed these root-level leak sources:
+- `UsageMeter`
+- `SearchModal`
+- `KeyboardShortcutsModal`
+- `UpdateCenterNotifier`
+- `MobilePromptTrigger`
+- `OnboardingTour`
+
+Important note:
+- Some of these were gated only for landing routes.
+- Later, game surfaces like `/playground` also needed special treatment.
+
+### 4. Bottom-right usage/session pill leak on HermesWorld/game surfaces was addressed
+This `SESSION | IN | OUT | CTX | COST` widget was another workspace overlay leak.
+
+Action taken:
+- hid the global usage/session pill for **game surfaces**, not just the landing page
+
+Touched:
+- `src/routes/__root.tsx`
+
+### 5. Sidebar overlap bugs in `/playground` were addressed
+On 3002 with the left sidebar open, gameplay UI elements overlapped badly.
+
+Fix direction implemented:
+- made several game UI pieces sidebar-aware so they shift when the left sidebar is open
+
+Touched:
+- `src/screens/playground/components/playground-hud.tsx`
+- `src/screens/playground/components/playground-chat.tsx`
+- `src/screens/playground/playground-screen.tsx`
+
+The intended fix was:
+- use `useWorkspaceStore((s) => s.sidebarCollapsed)`
+- shift HUD/chat/chips to `320px` left offset when sidebar is open
+- keep `min(120px, 9vw)` behavior when collapsed
+
+### 6. HermesWorld landing hero was shifted back toward the old glowing-orb vibe
+Eric preferred the older orb-based entry/startup vibe over the framed screenshot-heavy top fold.
+
+Action taken:
+- hero switched to use `PlaygroundHeroCanvas`
+- kept new landing structure/copy, but moved the visual style back toward orb glow / portal / startup energy
+
+Touched:
+- `src/screens/playground/hermes-world-landing.tsx`
+- `src/screens/playground/components/playground-hero-canvas.tsx` (used, not necessarily modified)
+
+### 7. HermesWorld copy cleanup
+Removed more workspace-local carryover text from the landing.
+
+Examples changed:
+- `Hermes Workspace Experiment // Persistent Agent World`
+  → `HermesWorld Preview // Persistent Agent World`
+- `Hermes Workspace Connected`
+  → `Live World Build`
+
+### 8. Local preview/dev process debugging happened repeatedly
+Root cause for a lot of weirdness:
+- multiple Vite dev servers were fighting over `routeTree.gen.ts`
+- this caused reload thrash, aborted requests, and “stopping mid-turn” feelings during local preview
+
+Key reality:
+- 3002/3003 reliability was not just “the site is broken”, it was also local dev process instability
+- detached/nohup relaunches were used at points to keep things alive longer
+
+### 9. Character/graphics pipeline scaffolding started in code
+This was the first real gameplay/visual upgrade setup work.
+
+Added:
+- `src/screens/playground/lib/character-config.ts`
+- `src/screens/playground/components/player-character.tsx`
+- `src/screens/playground/components/npc-character.tsx`
+- `src/screens/playground/components/playground-glb-body.tsx`
+- `src/screens/playground/components/playground-player-glb.tsx`
+- rewrote/normalized `src/screens/playground/components/playground-npc-glb.tsx`
+- `public/assets/hermesworld/characters/README.md`
+
+What this means:
+- canonical asset path now exists for believable humanoid GLBs
+- canonical path:
+  - `/public/assets/hermesworld/characters/<id>.glb`
+- legacy `/avatars-3d/<id>.glb` remains as fallback
+
+### 10. Execution docs/specs were created
+Created / updated:
+- `docs/hermesworld/landing-page-spec.md`
+- `docs/hermesworld/graphics-usability-plan.md`
+- `docs/hermesworld/agora-believable-checklist.md`
+
+These docs now encode the session’s design/implementation direction.
+
+## What was accomplished, distilled
+
+This session did **four big things**:
+
+1. **Turned HermesWorld landing into a real standalone launch page** instead of a workspace-fragment/app-pane.
+2. **Removed or traced most of the workspace chrome leaks** that kept showing up in HermesWorld surfaces.
+3. **Stabilized the local direction** around world-first marketing, GitHub/public links, and the glowing-orb entry vibe.
+4. **Started the real graphics/character pipeline** so the next session can move from planning into visible world upgrades.
+
+## What still needs to be tackled for the redesign
+
+### A. Final HermesWorld landing cleanup
+Still verify/fix:
+- no remaining root overlay leaks on `/hermes-world` or `/playground`
+- no bottom-right usage/session pill anywhere on HermesWorld/game surfaces
+- no mobile-access prompt / other workspace popups on HermesWorld routes
+- no sidebar overlap edge cases on `/playground`
+
+### B. Re-verify local previews cleanly
+Need a fresh sanity pass on:
+- `http://127.0.0.1:3002/hermes-world`
+- `http://127.0.0.1:3002/playground`
+- optional `3003` behavior if still used as redirect/entry
+
+Need to ensure:
+- landing looks correct
+- game route has no overlapping HUD with sidebar open
+- no stale cached bundle behavior
+
+### C. Continue the real graphics redesign
+Next actual game-side work should be:
+1. integrate character boundaries into `playground-world-3d.tsx`
+2. mount first `PlayerCharacter` / `NpcCharacter` path in the live Agora scene
+3. begin **Agora Believable** pass:
+   - plaza composition
+   - better central monument
+   - stronger paths/ground
+   - better lighting/fog
+   - better NPC placement
+4. start replacing toy-like placeholder figures with believable humanoid pipeline
+
+### D. Character asset pipeline needs real assets next
+Need actual GLBs now, not just scaffolding.
+
+Priority assets:
+- `player-adventurer.glb`
+- `oracle-scholar.glb`
+- `forge-blacksmith.glb`
+- `guard-knight.glb`
+- `merchant-villager.glb`
+- `villager-common.glb`
+
+Recommended source path:
+- Ready Player Me or similar base characters
+- Mixamo for idle/walk/talk/use animations
+- optimize to browser-safe GLB assets
+
+### E. HUD/readability pass still needs deeper work
+The sidebar-aware offset work started, but the full usability pass is still ahead:
+- objective widget
+- minimap polish
+- action bar clarity
+- interaction prompts
+- NPC labels
+- less prototype noise
+
+## Most important next task for Opus
+
+**Do not restart from brand strategy.**
+The next session should continue directly into:
+
+### Primary next task
+Refactor `playground-world-3d.tsx` to mount the new character boundaries into Agora and start the first visible believable-character pass.
+
+### Immediate sub-steps
+1. inspect current player/NPC rendering in `playground-world-3d.tsx`
+2. swap one player and one or two NPC stand-ins to the new component boundaries
+3. improve Agora composition around those characters
+4. re-check HUD overlap and root overlays in real local preview
+
+## Files most likely to touch next
+
+Landing / route chrome:
+- `src/screens/playground/hermes-world-landing.tsx`
+- `src/components/workspace-shell.tsx`
+- `src/routes/__root.tsx`
+
+Game / graphics:
+- `src/screens/playground/components/playground-world-3d.tsx`
+- `src/screens/playground/components/playground-hud.tsx`
+- `src/screens/playground/components/playground-chat.tsx`
+- `src/screens/playground/playground-screen.tsx`
+
+Character pipeline:
+- `src/screens/playground/lib/character-config.ts`
+- `src/screens/playground/components/player-character.tsx`
+- `src/screens/playground/components/npc-character.tsx`
+- `src/screens/playground/components/playground-glb-body.tsx`
+- `src/screens/playground/components/playground-player-glb.tsx`
+- `src/screens/playground/components/playground-npc-glb.tsx`
+- `public/assets/hermesworld/characters/*`
+
+Planning docs:
+- `docs/hermesworld/landing-page-spec.md`
+- `docs/hermesworld/graphics-usability-plan.md`
+- `docs/hermesworld/agora-believable-checklist.md`
+
+## Local-state warning
+This is still **local-only** and likely **uncommitted**.
+There are multiple in-progress modifications in the repo. Do not assume a clean branch. Be careful not to clobber unrelated local work while continuing.
+
+## One-line resume prompt
+
+Resume the HermesWorld redesign from the current local-only state. First verify the landing/game surfaces are free of workspace overlay leaks, then continue the **Agora Believable** pass by wiring the new character pipeline into `playground-world-3d.tsx` and replacing placeholder figures with the first believable humanoid boundaries.

memory/swarm/missions/2026-05-05-pr-triage.md

@@ -0,0 +1,49 @@
+# PR Triage Mission — 2026-05-05
+
+**Repo:** outsourc-e/hermes-workspace
+**Goal:** triage all 19 open PRs, produce structured findings per PR, NO AUTO-MERGE.
+**Reporter:** Aurora (main session)
+**Lead time:** within this session (~30-45 min for first reports back)
+
+## Hard rules
+
+1. **Do NOT merge any PR.** Eric must approve every merge personally.
+2. **Do NOT push to main or any contributor branch.**
+3. **Do NOT close PRs.** Just classify them.
+4. Report back to Aurora with a single concrete checkpoint per PR.
+5. If you encounter conflicts, list them; do not resolve them on the PR branch.
+
+## Per-PR deliverable
+
+For each assigned PR, produce one structured block:
+
+```
+PR #<num> — <title>
+AUTHOR: <login>
+CLASSIFICATION: APPROVE_READY | NEEDS_FIX | NEEDS_DISCUSSION | CLOSE_RECOMMEND
+DIFF_SUMMARY: <2-3 lines, what it actually changes>
+FILES_TOUCHED: <count + key paths>
+RISK: low | medium | high — <one-line reason>
+TESTS_RUN: <pnpm build / pnpm lint / specific test files / N/A>
+TEST_RESULT: pass | fail | not-run — <evidence>
+CONFLICTS: none | <files>
+BLOCKERS: <or none>
+REVIEW_NOTES: <2-4 lines — concrete things Eric should know before merging>
+RECOMMENDED_ACTION: merge | request-changes:<what> | close:<why> | discuss:<what>
+```
+
+## Lane assignments
+
+Healthy workers and their PR slices (by PR number):
+
+- **swarm3** → 338, 336, 335, 334
+- **swarm4** → 332, 330, 327, 325
+- **swarm6** → 324, 322, 320, 318
+- **swarm10** → 317, 315, 310, 308
+- **swarm12** → 307, 301, 299
+
+Quarantined: swarm1 (broken runtime), swarm2/swarm11 (rate-limited 429).
+
+## Checkpoint cadence
+
+Workers must produce one checkpoint per PR and report it back via STATE: HANDOFF blocks. Aurora will collect, summarize for Eric, and Eric decides each merge.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "hermes-workspace",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Desktop workspace for Hermes Agent — chat, orchestration, and multi-agent coding pipelines",
   "author": "Eric (https://github.com/outsourc-e)",
   "license": "MIT",

playground-ws-worker/src/worker.ts

@@ -24,6 +24,29 @@
 
 export interface Env {
   PLAYGROUND_HUB: DurableObjectNamespace
+  PLAYGROUND_ADMIN_TOKEN?: string
+}
+
+type AnalyticsEvent = {
+  type: 'join' | 'leave' | 'chat' | 'world_change'
+  id: string
+  name?: string
+  color?: string
+  world?: string
+  text?: string
+  ts: number
+}
+
+type PlayerDailySummary = {
+  id: string
+  name?: string
+  color?: string
+  firstSeen: number
+  lastSeen: number
+  lastWorld?: string
+  lastChatAt?: number
+  chats: number
+  joins: number
 }
 
 interface PresenceMsg {
@@ -41,6 +64,7 @@ interface PresenceMsg {
 
 const STALE_AFTER_MS = 12000
 const CHAT_RING_MAX = 50
+const ADMIN_EVENT_RING_MAX = 250
 const PRESENCE_DEDUPE_MS = 50
 const RATE_BUCKET_CAP = 30
 const RATE_REFILL_PER_SEC = 30
@@ -63,16 +87,25 @@ interface SocketAttach {
   lastPresenceTs: number
 }
 
-export class PlaygroundHub {
+export class PlaygroundHubV2 {
   state: DurableObjectState
+  env: Env
   presence = new Map<string, PresenceMsg & { ts: number }>()
   chatRing: any[] = []
   peakToday = 0
   peakDay = ''
   lastBroadcastCount = -1
+  analyticsDay = ''
+  uniqueToday = new Set<string>()
+  joinsToday = 0
+  leavesToday = 0
+  chatsToday = 0
+  playerDaily = new Map<string, PlayerDailySummary>()
+  eventRing: AnalyticsEvent[] = []
 
-  constructor(state: DurableObjectState) {
+  constructor(state: DurableObjectState, env: Env) {
     this.state = state
+    this.env = env
     this.state.blockConcurrencyWhile(async () => {
       const stored = await this.state.storage.get<{ peak: number; day: string }>('peak')
       if (stored) {
@@ -84,6 +117,24 @@ export class PlaygroundHub {
       if (presStored) this.presence = new Map(presStored)
       const chatStored = await this.state.storage.get<any[]>('chatRing')
       if (chatStored) this.chatRing = chatStored
+      const analyticsStored = await this.state.storage.get<{
+        day: string
+        uniqueToday: string[]
+        joinsToday: number
+        leavesToday: number
+        chatsToday: number
+        playerDaily: Array<[string, PlayerDailySummary]>
+        eventRing: AnalyticsEvent[]
+      }>('analytics')
+      if (analyticsStored) {
+        this.analyticsDay = analyticsStored.day || ''
+        this.uniqueToday = new Set(analyticsStored.uniqueToday || [])
+        this.joinsToday = analyticsStored.joinsToday || 0
+        this.leavesToday = analyticsStored.leavesToday || 0
+        this.chatsToday = analyticsStored.chatsToday || 0
+        this.playerDaily = new Map(analyticsStored.playerDaily || [])
+        this.eventRing = analyticsStored.eventRing || []
+      }
     })
     this.state.blockConcurrencyWhile(async () => {
       this.scheduleAlarm()
@@ -103,6 +154,105 @@ export class PlaygroundHub {
     } catch {}
   }
 
+  async persistAnalytics() {
+    try {
+      await this.state.storage.put('analytics', {
+        day: this.analyticsDay,
+        uniqueToday: [...this.uniqueToday],
+        joinsToday: this.joinsToday,
+        leavesToday: this.leavesToday,
+        chatsToday: this.chatsToday,
+        playerDaily: [...this.playerDaily.entries()],
+        eventRing: this.eventRing,
+      })
+    } catch {}
+  }
+
+  ensureAnalyticsDay(ts = Date.now()) {
+    const day = new Date(ts).toISOString().slice(0, 10)
+    if (this.analyticsDay && this.analyticsDay === day) return
+    this.analyticsDay = day
+    this.uniqueToday = new Set()
+    this.joinsToday = 0
+    this.leavesToday = 0
+    this.chatsToday = 0
+    this.playerDaily = new Map()
+    this.eventRing = []
+  }
+
+  notePlayer(
+    id: string,
+    patch: Partial<PlayerDailySummary> & { name?: string; color?: string; lastWorld?: string },
+    ts = Date.now(),
+  ) {
+    this.ensureAnalyticsDay(ts)
+    const current = this.playerDaily.get(id)
+    const next: PlayerDailySummary = current
+      ? {
+          ...current,
+          ...patch,
+          name: patch.name ?? current.name,
+          color: patch.color ?? current.color,
+          lastSeen: ts,
+          lastWorld: patch.lastWorld ?? current.lastWorld,
+          lastChatAt: patch.lastChatAt ?? current.lastChatAt,
+          chats: patch.chats ?? current.chats,
+          joins: patch.joins ?? current.joins,
+        }
+      : {
+          id,
+          name: patch.name,
+          color: patch.color,
+          firstSeen: ts,
+          lastSeen: ts,
+          lastWorld: patch.lastWorld,
+          lastChatAt: patch.lastChatAt,
+          chats: patch.chats ?? 0,
+          joins: patch.joins ?? 0,
+        }
+    this.playerDaily.set(id, next)
+    this.uniqueToday.add(id)
+  }
+
+  pushEvent(event: AnalyticsEvent) {
+    this.ensureAnalyticsDay(event.ts)
+    this.eventRing.push(event)
+    if (this.eventRing.length > ADMIN_EVENT_RING_MAX) {
+      this.eventRing = this.eventRing.slice(-ADMIN_EVENT_RING_MAX)
+    }
+  }
+
+  activePlayersWithin(ms: number) {
+    const cutoff = Date.now() - ms
+    let count = 0
+    for (const p of this.playerDaily.values()) {
+      if (p.lastSeen >= cutoff) count += 1
+    }
+    return count
+  }
+
+  adminStats() {
+    this.ensureAnalyticsDay()
+    const recentPlayers = [...this.playerDaily.values()]
+      .sort((a, b) => b.lastSeen - a.lastSeen)
+      .slice(0, 50)
+    return {
+      online: this.presence.size,
+      byWorld: this.byWorld(),
+      peakToday: this.peakToday,
+      peakDay: this.peakDay,
+      uniqueToday: this.uniqueToday.size,
+      joinsToday: this.joinsToday,
+      leavesToday: this.leavesToday,
+      chatsToday: this.chatsToday,
+      activeLast15m: this.activePlayersWithin(15 * 60 * 1000),
+      activeLast60m: this.activePlayersWithin(60 * 60 * 1000),
+      recentPlayers,
+      recentEvents: this.eventRing.slice(-100).reverse(),
+      ts: Date.now(),
+    }
+  }
+
   // ───── Alarm-driven prune ─────
   async scheduleAlarm() {
     const cur = await this.state.storage.getAlarm()
@@ -258,6 +408,15 @@ export class PlaygroundHub {
       })
     }
 
+    const adminHeader = request.headers.get('authorization') || ''
+    const adminOk = !!this.env.PLAYGROUND_ADMIN_TOKEN && adminHeader === `Bearer ${this.env.PLAYGROUND_ADMIN_TOKEN}`
+    if (url.pathname === '/admin/stats') {
+      if (!adminOk) return new Response('unauthorized', { status: 401, headers: cors })
+      return Response.json(this.adminStats(), {
+        headers: { ...cors, 'cache-control': 'no-cache' },
+      })
+    }
+
     // ───── HTTP polling endpoints (reliable fallback for WebSockets) ─────
     // POST /presence  body: { id, name, color, world, x, y, z, yaw, avatar?, lastChatAt? }
     //   Updates presence + returns { presences: [...other-players-in-world], chats: [...recent], count, byWorld, peakToday }
@@ -268,14 +427,40 @@ export class PlaygroundHub {
       const now = Date.now()
       const world = (body.world || body.worldId) as string | undefined
       const wire: PresenceMsg & { ts: number } = { ...body, kind: 'presence', ts: now }
-      const wasNew = !this.presence.has(body.id)
+      const prior = this.presence.get(body.id)
+      const wasNew = !prior
       this.presence.set(body.id, wire)
+      this.notePlayer(body.id, {
+        name: typeof body.name === 'string' ? body.name : undefined,
+        color: typeof body.color === 'string' ? body.color : undefined,
+        lastWorld: world,
+        joins: wasNew ? (this.playerDaily.get(body.id)?.joins || 0) + 1 : (this.playerDaily.get(body.id)?.joins || 0),
+      }, now)
       if (wasNew) {
+        this.joinsToday += 1
+        this.pushEvent({
+          type: 'join',
+          id: body.id,
+          name: typeof body.name === 'string' ? body.name : undefined,
+          color: typeof body.color === 'string' ? body.color : undefined,
+          world,
+          ts: now,
+        })
         await this.bumpPeak()
         this.maybeBroadcastCount()
+      } else if ((prior.world || prior.worldId) !== world) {
+        this.pushEvent({
+          type: 'world_change',
+          id: body.id,
+          name: typeof body.name === 'string' ? body.name : undefined,
+          color: typeof body.color === 'string' ? body.color : undefined,
+          world,
+          ts: now,
+        })
       }
       // Persist async — don't block the response
       this.persistPresence().catch(() => {})
+      this.persistAnalytics().catch(() => {})
       // Mirror to any active WebSockets (so clients on either transport see each other)
       this.broadcast(null, wire, { world })
       // Return: presences in same world (excluding caller), recent chats, count summary
@@ -316,7 +501,25 @@ export class PlaygroundHub {
       body.ts = Date.now()
       this.chatRing.push(body)
       if (this.chatRing.length > CHAT_RING_MAX) this.chatRing.shift()
+      this.chatsToday += 1
+      this.notePlayer(body.id, {
+        name: typeof body.name === 'string' ? body.name : undefined,
+        color: typeof body.color === 'string' ? body.color : undefined,
+        lastWorld: (body.world || body.worldId) as string | undefined,
+        lastChatAt: body.ts,
+        chats: (this.playerDaily.get(body.id)?.chats || 0) + 1,
+      }, body.ts)
+      this.pushEvent({
+        type: 'chat',
+        id: body.id,
+        name: typeof body.name === 'string' ? body.name : undefined,
+        color: typeof body.color === 'string' ? body.color : undefined,
+        world: (body.world || body.worldId) as string | undefined,
+        text: typeof body.text === 'string' ? body.text.slice(0, 160) : undefined,
+        ts: body.ts,
+      })
       this.persistChat().catch(() => {})
+      this.persistAnalytics().catch(() => {})
       const world = (body.world || body.worldId) as string | undefined
       this.broadcast(null, body, { world })
       return Response.json({ ok: true, ts: body.ts }, { headers: cors })
@@ -330,9 +533,24 @@ export class PlaygroundHub {
       const prior = this.presence.get(body.id)
       const world = (prior?.world || prior?.worldId) as string | undefined
       this.presence.delete(body.id)
+      this.leavesToday += 1
+      this.notePlayer(body.id, {
+        name: typeof prior?.name === 'string' ? prior.name : undefined,
+        color: typeof prior?.color === 'string' ? prior.color : undefined,
+        lastWorld: world,
+      })
+      this.pushEvent({
+        type: 'leave',
+        id: body.id,
+        name: typeof prior?.name === 'string' ? prior.name : undefined,
+        color: typeof prior?.color === 'string' ? prior.color : undefined,
+        world,
+        ts: Date.now(),
+      })
       this.broadcast(null, { kind: 'leave', id: body.id }, { world })
       this.maybeBroadcastCount()
       this.persistPresence().catch(() => {})
+      this.persistAnalytics().catch(() => {})
       return Response.json({ ok: true }, { headers: cors })
     }
 
@@ -398,15 +616,27 @@ export class PlaygroundHub {
       meta.world = world
       this.saveAttach(socket, meta)
       const wire: PresenceMsg & { ts: number } = { ...msg, ts: now }
-      const wasNew = !this.presence.has(msg.id)
+      const prior = this.presence.get(msg.id)
+      const wasNew = !prior
       this.presence.set(msg.id, wire)
+      this.notePlayer(msg.id, {
+        name: typeof msg.name === 'string' ? msg.name : undefined,
+        color: typeof msg.color === 'string' ? msg.color : undefined,
+        lastWorld: world,
+        joins: wasNew ? (this.playerDaily.get(msg.id)?.joins || 0) + 1 : (this.playerDaily.get(msg.id)?.joins || 0),
+      }, now)
       if (wasNew) {
+        this.joinsToday += 1
+        this.pushEvent({ type: 'join', id: msg.id, name: msg.name, color: msg.color, world, ts: now })
         await this.bumpPeak()
         this.maybeBroadcastCount()
+      } else if ((prior.world || prior.worldId) !== world) {
+        this.pushEvent({ type: 'world_change', id: msg.id, name: msg.name, color: msg.color, world, ts: now })
       }
       // Persist periodically (every ~5 presence updates per id is enough).
       // We keep this synchronous-ish for correctness on hibernation.
       await this.persistPresence()
+      await this.persistAnalytics()
       this.broadcast(socket, wire, { world })
     } else if (msg.kind === 'chat' && typeof msg.id === 'string') {
       if (typeof msg.text === 'string' && msg.text.length > 240) {
@@ -414,7 +644,25 @@ export class PlaygroundHub {
       }
       this.chatRing.push(msg)
       if (this.chatRing.length > CHAT_RING_MAX) this.chatRing.shift()
+      this.chatsToday += 1
+      this.notePlayer(msg.id, {
+        name: typeof msg.name === 'string' ? msg.name : undefined,
+        color: typeof msg.color === 'string' ? msg.color : undefined,
+        lastWorld: (msg.world || msg.worldId) as string | undefined,
+        lastChatAt: typeof msg.ts === 'number' ? msg.ts : Date.now(),
+        chats: (this.playerDaily.get(msg.id)?.chats || 0) + 1,
+      }, typeof msg.ts === 'number' ? msg.ts : Date.now())
+      this.pushEvent({
+        type: 'chat',
+        id: msg.id,
+        name: typeof msg.name === 'string' ? msg.name : undefined,
+        color: typeof msg.color === 'string' ? msg.color : undefined,
+        world: (msg.world || msg.worldId) as string | undefined,
+        text: typeof msg.text === 'string' ? msg.text.slice(0, 160) : undefined,
+        ts: typeof msg.ts === 'number' ? msg.ts : Date.now(),
+      })
       await this.persistChat()
+      await this.persistAnalytics()
       const world = (msg.world || msg.worldId) as string | undefined
       this.broadcast(socket, msg, { world })
       this.saveAttach(socket, meta)
@@ -422,7 +670,22 @@ export class PlaygroundHub {
       const prior = this.presence.get(msg.id)
       const world = (prior?.world || prior?.worldId) as string | undefined
       this.presence.delete(msg.id)
+      this.leavesToday += 1
+      this.notePlayer(msg.id, {
+        name: typeof prior?.name === 'string' ? prior.name : undefined,
+        color: typeof prior?.color === 'string' ? prior.color : undefined,
+        lastWorld: world,
+      })
+      this.pushEvent({
+        type: 'leave',
+        id: msg.id,
+        name: typeof prior?.name === 'string' ? prior.name : undefined,
+        color: typeof prior?.color === 'string' ? prior.color : undefined,
+        world,
+        ts: Date.now(),
+      })
       await this.persistPresence()
+      await this.persistAnalytics()
       this.broadcast(socket, msg, { world })
       this.maybeBroadcastCount()
       this.saveAttach(socket, meta)

playground-ws-worker/wrangler.toml

@@ -5,8 +5,12 @@ compatibility_flags = ["nodejs_compat"]
 
 [[durable_objects.bindings]]
 name = "PLAYGROUND_HUB"
-class_name = "PlaygroundHub"
+class_name = "PlaygroundHubV2"
 
 [[migrations]]
 tag = "v1"
 new_sqlite_classes = ["PlaygroundHub"]
+
+[[migrations]]
+tag = "v2"
+renamed_classes = [{from = "PlaygroundHub", to = "PlaygroundHubV2"}]

public/assets/hermesworld/MANIFEST.json

@@ -0,0 +1,475 @@
+{
+  "schemaVersion": 1,
+  "generatedBy": "Hermes asset wiring inventory",
+  "sourceRoots": [
+    "public/assets/hermesworld/art",
+    "public/assets/hermesworld/characters",
+    "public/assets/hermesworld/zones",
+    "public/assets/hermesworld/v2",
+    "public/assets/hermesworld/video"
+  ],
+  "assetCount": 38,
+  "notes": [
+    "Inventory covers existing files only; no image generation performed.",
+    "Video dimensions are read from the first video stream when ffprobe is available.",
+    "v2 contact sheets are source/reference assets; individual runtime usage should crop or object-fit as needed."
+  ],
+  "assets": [
+    {
+      "path": "public/assets/hermesworld/art/hermesworld-app-icon.png",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "hermesworld-app-icon.png",
+      "extension": "png",
+      "bytes": 1257,
+      "sizeLabel": "1.2 KB",
+      "width": 256,
+      "height": 256,
+      "durationSeconds": null,
+      "suggestedUseCategory": "app_icon"
+    },
+    {
+      "path": "public/assets/hermesworld/art/hermesworld-app-icon.svg",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "hermesworld-app-icon.svg",
+      "extension": "svg",
+      "bytes": 259,
+      "sizeLabel": "0.3 KB",
+      "width": 256,
+      "height": 256,
+      "durationSeconds": null,
+      "suggestedUseCategory": "app_icon"
+    },
+    {
+      "path": "public/assets/hermesworld/art/hermesworld-app-icon@2x.png",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "hermesworld-app-icon@2x.png",
+      "extension": "png",
+      "bytes": 26594,
+      "sizeLabel": "26.0 KB",
+      "width": 512,
+      "height": 512,
+      "durationSeconds": null,
+      "suggestedUseCategory": "app_icon"
+    },
+    {
+      "path": "public/assets/hermesworld/art/hermesworld-app-icon@3x.png",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "hermesworld-app-icon@3x.png",
+      "extension": "png",
+      "bytes": 52299,
+      "sizeLabel": "51.1 KB",
+      "width": 768,
+      "height": 768,
+      "durationSeconds": null,
+      "suggestedUseCategory": "app_icon"
+    },
+    {
+      "path": "public/assets/hermesworld/art/hermesworld-logo-caduceus-badge.png",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "hermesworld-logo-caduceus-badge.png",
+      "extension": "png",
+      "bytes": 162956,
+      "sizeLabel": "159.1 KB",
+      "width": 467,
+      "height": 280,
+      "durationSeconds": null,
+      "suggestedUseCategory": "brand_logo"
+    },
+    {
+      "path": "public/assets/hermesworld/art/hermesworld-logo-caduceus-favicon.png",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "hermesworld-logo-caduceus-favicon.png",
+      "extension": "png",
+      "bytes": 15211,
+      "sizeLabel": "14.9 KB",
+      "width": 160,
+      "height": 160,
+      "durationSeconds": null,
+      "suggestedUseCategory": "app_icon"
+    },
+    {
+      "path": "public/assets/hermesworld/art/hermesworld-logo-caduceus.png",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "hermesworld-logo-caduceus.png",
+      "extension": "png",
+      "bytes": 124317,
+      "sizeLabel": "121.4 KB",
+      "width": 467,
+      "height": 280,
+      "durationSeconds": null,
+      "suggestedUseCategory": "brand_logo"
+    },
+    {
+      "path": "public/assets/hermesworld/art/hermesworld-logo-h.png",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "hermesworld-logo-h.png",
+      "extension": "png",
+      "bytes": 15211,
+      "sizeLabel": "14.9 KB",
+      "width": 160,
+      "height": 160,
+      "durationSeconds": null,
+      "suggestedUseCategory": "brand_logo"
+    },
+    {
+      "path": "public/assets/hermesworld/art/hermesworld-logo-horizontal.png",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "hermesworld-logo-horizontal.png",
+      "extension": "png",
+      "bytes": 37128,
+      "sizeLabel": "36.3 KB",
+      "width": 520,
+      "height": 156,
+      "durationSeconds": null,
+      "suggestedUseCategory": "brand_logo"
+    },
+    {
+      "path": "public/assets/hermesworld/art/hermesworld-logo-horizontal.svg",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "hermesworld-logo-horizontal.svg",
+      "extension": "svg",
+      "bytes": 273,
+      "sizeLabel": "0.3 KB",
+      "width": 520,
+      "height": 156,
+      "durationSeconds": null,
+      "suggestedUseCategory": "brand_logo"
+    },
+    {
+      "path": "public/assets/hermesworld/art/hermesworld-logo-horizontal@2x.png",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "hermesworld-logo-horizontal@2x.png",
+      "extension": "png",
+      "bytes": 137541,
+      "sizeLabel": "134.3 KB",
+      "width": 1040,
+      "height": 312,
+      "durationSeconds": null,
+      "suggestedUseCategory": "brand_logo"
+    },
+    {
+      "path": "public/assets/hermesworld/art/hermesworld-logo-horizontal@3x.png",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "hermesworld-logo-horizontal@3x.png",
+      "extension": "png",
+      "bytes": 258461,
+      "sizeLabel": "252.4 KB",
+      "width": 1560,
+      "height": 468,
+      "durationSeconds": null,
+      "suggestedUseCategory": "brand_logo"
+    },
+    {
+      "path": "public/assets/hermesworld/art/hermesworld-logo-stacked.png",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "hermesworld-logo-stacked.png",
+      "extension": "png",
+      "bytes": 99870,
+      "sizeLabel": "97.5 KB",
+      "width": 360,
+      "height": 300,
+      "durationSeconds": null,
+      "suggestedUseCategory": "brand_logo"
+    },
+    {
+      "path": "public/assets/hermesworld/art/hermesworld-logo-stacked.svg",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "hermesworld-logo-stacked.svg",
+      "extension": "svg",
+      "bytes": 267,
+      "sizeLabel": "0.3 KB",
+      "width": 360,
+      "height": 300,
+      "durationSeconds": null,
+      "suggestedUseCategory": "brand_logo"
+    },
+    {
+      "path": "public/assets/hermesworld/art/hermesworld-logo-stacked@2x.png",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "hermesworld-logo-stacked@2x.png",
+      "extension": "png",
+      "bytes": 335190,
+      "sizeLabel": "327.3 KB",
+      "width": 720,
+      "height": 600,
+      "durationSeconds": null,
+      "suggestedUseCategory": "brand_logo"
+    },
+    {
+      "path": "public/assets/hermesworld/art/hermesworld-logo-stacked@3x.png",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "hermesworld-logo-stacked@3x.png",
+      "extension": "png",
+      "bytes": 640821,
+      "sizeLabel": "625.8 KB",
+      "width": 1080,
+      "height": 900,
+      "durationSeconds": null,
+      "suggestedUseCategory": "brand_logo"
+    },
+    {
+      "path": "public/assets/hermesworld/art/hermesworld-sigil.png",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "hermesworld-sigil.png",
+      "extension": "png",
+      "bytes": 15211,
+      "sizeLabel": "14.9 KB",
+      "width": 160,
+      "height": 160,
+      "durationSeconds": null,
+      "suggestedUseCategory": "brand_logo"
+    },
+    {
+      "path": "public/assets/hermesworld/art/hermesworld-sigil.svg",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "hermesworld-sigil.svg",
+      "extension": "svg",
+      "bytes": 253,
+      "sizeLabel": "0.2 KB",
+      "width": 160,
+      "height": 160,
+      "durationSeconds": null,
+      "suggestedUseCategory": "brand_logo"
+    },
+    {
+      "path": "public/assets/hermesworld/art/hermesworld-sigil@2x.png",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "hermesworld-sigil@2x.png",
+      "extension": "png",
+      "bytes": 51261,
+      "sizeLabel": "50.1 KB",
+      "width": 320,
+      "height": 320,
+      "durationSeconds": null,
+      "suggestedUseCategory": "brand_logo"
+    },
+    {
+      "path": "public/assets/hermesworld/art/hermesworld-sigil@3x.png",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "hermesworld-sigil@3x.png",
+      "extension": "png",
+      "bytes": 96409,
+      "sizeLabel": "94.1 KB",
+      "width": 480,
+      "height": 480,
+      "durationSeconds": null,
+      "suggestedUseCategory": "brand_logo"
+    },
+    {
+      "path": "public/assets/hermesworld/art/social-preview-hero.jpg",
+      "directory": "public/assets/hermesworld/art",
+      "fileName": "social-preview-hero.jpg",
+      "extension": "jpg",
+      "bytes": 82326,
+      "sizeLabel": "80.4 KB",
+      "width": 1200,
+      "height": 630,
+      "durationSeconds": null,
+      "suggestedUseCategory": "social_share_preview"
+    },
+    {
+      "path": "public/assets/hermesworld/characters/README.md",
+      "directory": "public/assets/hermesworld/characters",
+      "fileName": "README.md",
+      "extension": "md",
+      "bytes": 684,
+      "sizeLabel": "0.7 KB",
+      "width": null,
+      "height": null,
+      "durationSeconds": null,
+      "suggestedUseCategory": "character_asset_placeholder"
+    },
+    {
+      "path": "public/assets/hermesworld/zones/cityscape.jpg",
+      "directory": "public/assets/hermesworld/zones",
+      "fileName": "cityscape.jpg",
+      "extension": "jpg",
+      "bytes": 63712,
+      "sizeLabel": "62.2 KB",
+      "width": 1920,
+      "height": 600,
+      "durationSeconds": null,
+      "suggestedUseCategory": "zone_background_hero"
+    },
+    {
+      "path": "public/assets/hermesworld/zones/hero.jpg",
+      "directory": "public/assets/hermesworld/zones",
+      "fileName": "hero.jpg",
+      "extension": "jpg",
+      "bytes": 119035,
+      "sizeLabel": "116.2 KB",
+      "width": 1280,
+      "height": 780,
+      "durationSeconds": null,
+      "suggestedUseCategory": "zone_background_hero"
+    },
+    {
+      "path": "public/assets/hermesworld/zones/zone-1.jpg",
+      "directory": "public/assets/hermesworld/zones",
+      "fileName": "zone-1.jpg",
+      "extension": "jpg",
+      "bytes": 28167,
+      "sizeLabel": "27.5 KB",
+      "width": 600,
+      "height": 520,
+      "durationSeconds": null,
+      "suggestedUseCategory": "zone_fallback_background"
+    },
+    {
+      "path": "public/assets/hermesworld/zones/zone-2.jpg",
+      "directory": "public/assets/hermesworld/zones",
+      "fileName": "zone-2.jpg",
+      "extension": "jpg",
+      "bytes": 41268,
+      "sizeLabel": "40.3 KB",
+      "width": 600,
+      "height": 520,
+      "durationSeconds": null,
+      "suggestedUseCategory": "zone_fallback_background"
+    },
+    {
+      "path": "public/assets/hermesworld/zones/zone-3.jpg",
+      "directory": "public/assets/hermesworld/zones",
+      "fileName": "zone-3.jpg",
+      "extension": "jpg",
+      "bytes": 48092,
+      "sizeLabel": "47.0 KB",
+      "width": 600,
+      "height": 520,
+      "durationSeconds": null,
+      "suggestedUseCategory": "zone_fallback_background"
+    },
+    {
+      "path": "public/assets/hermesworld/zones/zone-4.jpg",
+      "directory": "public/assets/hermesworld/zones",
+      "fileName": "zone-4.jpg",
+      "extension": "jpg",
+      "bytes": 48371,
+      "sizeLabel": "47.2 KB",
+      "width": 600,
+      "height": 520,
+      "durationSeconds": null,
+      "suggestedUseCategory": "zone_fallback_background"
+    },
+    {
+      "path": "public/assets/hermesworld/zones/zone-5.jpg",
+      "directory": "public/assets/hermesworld/zones",
+      "fileName": "zone-5.jpg",
+      "extension": "jpg",
+      "bytes": 40418,
+      "sizeLabel": "39.5 KB",
+      "width": 600,
+      "height": 520,
+      "durationSeconds": null,
+      "suggestedUseCategory": "zone_fallback_background"
+    },
+    {
+      "path": "public/assets/hermesworld/zones/zone-6.jpg",
+      "directory": "public/assets/hermesworld/zones",
+      "fileName": "zone-6.jpg",
+      "extension": "jpg",
+      "bytes": 59446,
+      "sizeLabel": "58.1 KB",
+      "width": 600,
+      "height": 520,
+      "durationSeconds": null,
+      "suggestedUseCategory": "zone_fallback_background"
+    },
+    {
+      "path": "public/assets/hermesworld/v2/IMAGEGEN-STATUS.md",
+      "directory": "public/assets/hermesworld/v2",
+      "fileName": "IMAGEGEN-STATUS.md",
+      "extension": "md",
+      "bytes": 796,
+      "sizeLabel": "0.8 KB",
+      "width": null,
+      "height": null,
+      "durationSeconds": null,
+      "suggestedUseCategory": "v2_pipeline_doc"
+    },
+    {
+      "path": "public/assets/hermesworld/v2/MANIFEST.md",
+      "directory": "public/assets/hermesworld/v2",
+      "fileName": "MANIFEST.md",
+      "extension": "md",
+      "bytes": 358,
+      "sizeLabel": "0.3 KB",
+      "width": null,
+      "height": null,
+      "durationSeconds": null,
+      "suggestedUseCategory": "v2_pipeline_doc"
+    },
+    {
+      "path": "public/assets/hermesworld/v2/wave-a-source/A03-A08-rerolls.png",
+      "directory": "public/assets/hermesworld/v2/wave-a-source",
+      "fileName": "A03-A08-rerolls.png",
+      "extension": "png",
+      "bytes": 1605926,
+      "sizeLabel": "1.53 MB",
+      "width": 1774,
+      "height": 887,
+      "durationSeconds": null,
+      "suggestedUseCategory": "source_contact_sheet_or_portrait_reference"
+    },
+    {
+      "path": "public/assets/hermesworld/v2/wave-a-source/all-images-contact-sheet.png",
+      "directory": "public/assets/hermesworld/v2/wave-a-source",
+      "fileName": "all-images-contact-sheet.png",
+      "extension": "png",
+      "bytes": 2131604,
+      "sizeLabel": "2.03 MB",
+      "width": 1536,
+      "height": 1024,
+      "durationSeconds": null,
+      "suggestedUseCategory": "source_contact_sheet_or_portrait_reference"
+    },
+    {
+      "path": "public/assets/hermesworld/video/hero-720p.mp4",
+      "directory": "public/assets/hermesworld/video",
+      "fileName": "hero-720p.mp4",
+      "extension": "mp4",
+      "bytes": 644082,
+      "sizeLabel": "629.0 KB",
+      "width": 1280,
+      "height": 874,
+      "durationSeconds": 9.683333,
+      "suggestedUseCategory": "video_demo"
+    },
+    {
+      "path": "public/assets/hermesworld/video/hero-poster.jpg",
+      "directory": "public/assets/hermesworld/video",
+      "fileName": "hero-poster.jpg",
+      "extension": "jpg",
+      "bytes": 64556,
+      "sizeLabel": "63.0 KB",
+      "width": 1280,
+      "height": 874,
+      "durationSeconds": null,
+      "suggestedUseCategory": "video_poster"
+    },
+    {
+      "path": "public/assets/hermesworld/video/world-demo-720p.mp4",
+      "directory": "public/assets/hermesworld/video",
+      "fileName": "world-demo-720p.mp4",
+      "extension": "mp4",
+      "bytes": 10353994,
+      "sizeLabel": "9.87 MB",
+      "width": 1076,
+      "height": 720,
+      "durationSeconds": 75.033333,
+      "suggestedUseCategory": "video_demo"
+    },
+    {
+      "path": "public/assets/hermesworld/video/world-demo-poster.jpg",
+      "directory": "public/assets/hermesworld/video",
+      "fileName": "world-demo-poster.jpg",
+      "extension": "jpg",
+      "bytes": 63007,
+      "sizeLabel": "61.5 KB",
+      "width": 1076,
+      "height": 720,
+      "durationSeconds": null,
+      "suggestedUseCategory": "video_poster"
+    }
+  ]
+}

public/assets/hermesworld/art/hermesworld-app-icon.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="256" viewBox="0 0 256 256" role="img" aria-label="HermesWorld hermesworld app icon">
+  <image href="hermesworld-app-icon@3x.png" width="256" height="256" preserveAspectRatio="xMidYMid meet"/>
+</svg>

public/assets/hermesworld/art/hermesworld-logo-horizontal.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="520" height="156" viewBox="0 0 520 156" role="img" aria-label="HermesWorld hermesworld logo horizontal">
+  <image href="hermesworld-logo-horizontal@3x.png" width="520" height="156" preserveAspectRatio="xMidYMid meet"/>
+</svg>

public/assets/hermesworld/art/hermesworld-logo-stacked.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="360" height="300" viewBox="0 0 360 300" role="img" aria-label="HermesWorld hermesworld logo stacked">
+  <image href="hermesworld-logo-stacked@3x.png" width="360" height="300" preserveAspectRatio="xMidYMid meet"/>
+</svg>

public/assets/hermesworld/art/hermesworld-sigil.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="160" height="160" viewBox="0 0 160 160" role="img" aria-label="HermesWorld hermesworld sigil">
+  <image href="hermesworld-sigil@3x.png" width="160" height="160" preserveAspectRatio="xMidYMid meet"/>
+</svg>

public/assets/hermesworld/characters/README.md

@@ -0,0 +1,39 @@
+# HermesWorld Character Assets
+
+Drop character GLBs here.
+
+## Canonical path
+
+Characters should live at:
+
+- `/public/assets/hermesworld/characters/<id>.glb`
+
+Examples:
+- `player-adventurer.glb`
+- `oracle-scholar.glb`
+- `forge-blacksmith.glb`
+- `guard-knight.glb`
+- `merchant-villager.glb`
+- `villager-common.glb`
+
+## Source pipeline
+
+Recommended source order:
+1. Ready Player Me or similar believable humanoid base
+2. Mixamo animation clips
+3. GLB export
+4. browser optimization
+
+## First animations to support
+- idle
+- walk
+- run
+- talk
+- inspect
+- use
+
+## Naming rules
+- lowercase kebab-case ids
+- keep one archetype per file
+- prefer shared rigs
+- keep texture/material counts low

public/assets/hermesworld/v2/IMAGEGEN-STATUS.md

@@ -0,0 +1,21 @@
+# Imagegen Status — 2026-05-06 07:05 EDT
+
+## Result: Imagegen blocked tonight
+
+All 3 configured image models failed:
+
+- `google/gemini-3.1-flash-image-preview` — no API key configured
+- `minimax/image-01` — plan does not support this model
+- `openai/gpt-image-1` — **billing hard limit reached**
+
+## What we have
+
+- WAVE-A-PROMPTS.md is complete (PR #13) — 18 prompts ready to feed into any working imagegen
+- Style lock + brand sheet in place (PR #18)
+- Once Eric resolves billing or adds Google API key, all 18 prompts can be batched and saved to `wave-a-source/`
+
+## Recommended next step for Eric
+
+1. Top up OpenAI billing (gpt-image-1)
+2. Or add Google AI Studio API key for gemini-3.1-flash-image-preview
+3. Then re-dispatch swarm5 or run from orchestrator with WAVE-A-PROMPTS.md

public/assets/hermesworld/v2/MANIFEST.md

@@ -0,0 +1,9 @@
+# HermesWorld v2 Asset Manifest
+
+All Wave A/B/C/D/E generated assets land here. Each row tracks prompt, model, batch, vision-review status.
+
+| File | Wave | Prompt | Model | Status | Vision Review |
+|------|------|--------|-------|--------|---------------|
+| (TBD) | A | TBD | gpt-5.5 | pending | pending |
+
+Logged automatically by the swarm asset-gen lane.