the-living-world/AGENTS.md

AGENTS.md

Guidance for AI coding agents (Cursor, Claude Code, Copilot, Codex, and similar) working in this repository.

EchoVault (required)

This project uses the EchoVault MCP server (user-echovault) as persistent memory across sessions. Use it aggressively. Skipping it means the next agent starts from zero.

When to call what

Tool	When
memory_context	Session start and after a major topic change. Loads recent decisions for this project.
memory_search	Before work on a familiar/unclear topic, and whenever the user’s request may relate to prior decisions or bugs.
memory_save	Before ending any session where you made decisions, fixed bugs, discovered non-obvious patterns, or changed architecture/infra. Not optional.

Prefer project: "the-living-world" when the tool accepts a project filter.

What to save

Save when you:

• Chose an approach (X over Y) or fixed a non-obvious bug
• Learned something about this codebase that is not obvious from reading the code
• Set up tooling/config the next agent will need
• Were corrected or given a durable requirement by the user

Do not save: typos, pure formatting, facts already clear from the code, or duplicates of existing memories.

How to write a good memory

• title — short (≤60 chars)

• what — 1–2 sentences the next agent needs

• why / impact — reasoning and what changed

• category — one of: decision, bug, pattern, learning, context

• tags / related_files — so search can find it

• details — write for an agent with zero context. Prefer:

  Context
  Options considered
  Decision
  Tradeoffs
  Follow-up
  

Session checklist

1. Call memory_context (and memory_search if the task is specific).
2. Do the work.
3. Call memory_save for every meaningful decision or fix before you stop.

Project snapshot

The Living World is a web game whose map is a real place: the API imports OpenStreetMap via Overpass into an Arch ECS world and serves chunked geometry; a PixiJS client renders it.

Area	Path / stack
API	src/TheLivingWorld.Api — .NET 10, minimal APIs
Core / ECS	src/TheLivingWorld.Core — Arch, geo, export
OSM import	src/TheLivingWorld.Osm — Overpass + import pipeline
Web client	src/TheLivingWorld.Web — TypeScript, Vite, PixiJS 8
Aspire host	src/TheLivingWorld.AppHost
Tests	tests/TheLivingWorld.Tests (xUnit), Vitest under the web project

Worlds are stored as files under data/ (not committed). Cap: WorldStorage:MaxConcurrentWorlds. Ready worlds run a live game clock on the server (5 game minutes per real second at x1; default start 12 April 2012 06:00) plus weather: a Köppen-lite climate preset per world, with drifting pressure systems as ECS entities on top of a deterministic seasonal/diurnal baseline. UI: main menu (list + create, with a climate picker) → map screen with pause, speed, clock and weather, and a renderer that washes the map for time of day, cloud, fog and lying snow and drops rain or snow through it. One weather reading covers a whole world; the overlay has an on/off button in the game bar.

New ECS components must be added to the probe entity in SimulationComponents — Arch assigns component type ids on first use without a lock, and two threads racing there hand out the same id.

StoredWorldDto is what state.json holds; WorldSummaryDto is what clients get. Cross only via ToSummary() — the wire type deliberately has no field for the simulation's bookkeeping.

Keep wire DTOs in sync: TheLivingWorld.Core.Contracts and src/TheLivingWorld.Web/src/api/types.ts.

Working conventions

• Prefer small, focused diffs. Do not rewrite unrelated code or add docs the user did not ask for.
• Match existing naming, comments, and file layout.
• Backend tests: dotnet test tests/TheLivingWorld.Tests/TheLivingWorld.Tests.csproj
• Frontend checks: npm --prefix src/TheLivingWorld.Web test and npm --prefix src/TheLivingWorld.Web run typecheck
• Full stack: run.cmd or dotnet run --project src/TheLivingWorld.AppHost
• Do not commit unless the user asks. Do not invent secrets or commit data/.

Details of the import pipeline, API surface, and renderer live in README.md — read that before large map/API changes.