Imported from pragmaticW92/The.Walled.City (AGENTS.md). Install upstream with npx skills add pragmaticW92/The.Walled.City. Copyright stays with the author.

The Walled City — Operating Manual

How work gets done here. These rules bind every change, every session, every feature. Quadrillion-dollar AAA standard — no prototypes, no patches, no technical debt.

Core architecture rules (non-negotiable)

1. Server authority. The Node/TypeScript backend owns absolute reality. Clients only render what the server dictates — never client-side math or simulated state. If the backend doesn't know a value, the surface says "not on file" — never a 0, never a placeholder.
2. Owner mutation only. Only the owner mutates world state, through /api/nf-power/* behind stealth auth — unauthorized requests get 404, not 401. Public/player routes never expose or mutate owner data.
3. Persistence is mandatory. All world state survives restarts, written atomically to var/*.json through the shared BookStore (createBookStore, validated restore, shutdown flush via saveAllBooks()). If it doesn't survive restart, it isn't done.
4. TS ↔ Python parity. Every simulation kernel has an exact mirrored counterpart in obsidian_logic/, changed on both sides with tests.
5. No fakes, no shortcuts. NPCs never spawn items — to build or craft they must physically possess the goods in their holdings.move ledger. NPC behavior emerges from individual minds (needs, roles, history, resources, skills, surroundings), never scripted behavior. If a subsystem breaks or hits 0% utilization, fix the root cause — never write a workaround.
6. Unknown stays unknown. Reading a record must never create it. Missing data renders as missing.

Execution protocol

1. Ingest context first. Before writing code, read docs/MASTER_PLAN.md and docs/ENDPOINT_INVENTORY.md (plus the relevant system doc) — no duplicating existing routes, no drifting off-scope.
2. Atomic scope. Execute exactly one phase or feature at a time, on its own branch, as its own PR against main. Do not build multiple phases in one pass; do not touch files outside the assigned feature's scope.
3. Additive expansions. New capability extends the system; existing behavior is preserved. Backwards-compatible routes, save formats, and DTOs.
4. The verification gauntlet — all must pass with zero suppressed errors before a PR:
   • npx tsc --noEmit (backend) and client tsc -p .
   • vitest run — the relevant suites pass
   • pytest + ruff check when Python changes
   • route inventory regen (routes:check) when routes change
   • boot the real server and observe the feature live
5. Docs stay honest. docs/WORK_LOG.md, docs/MASTER_PLAN.md, and system docs reflect what actually shipped — corrected in the same PR, not later.

Failure behavior

• A failing test or type error means the logic is wrong — read the output, find the root cause, fix the underlying logic.
• NEVER rewrite a test to force a pass, use @ts-ignore/type: ignore to silence a real error, suppress warnings, or hide a failure.
• Issues found inside a diff's blast radius get fixed — no "pre-existing" excuses.

Housekeeping

• Worktrees under wc-worktrees/ are real git worktree checkouts tracking real branches — no detached copies. Stale copies drift and lie to the IDE.
• World saves (var/walled_city.json, var/*.json) are irreplaceable — back them up outside the repo before any destructive operation.